zoneinfo — IANA 시간대 지원¶
버전 3.9에 추가.
Source code: Lib/zoneinfo
zoneinfo 모듈은 원래 PEP 615에서 지정된 대로 IANA 시간대 데이터베이스를 지원하기 위한 구상 시간대 구현을 제공합니다. 기본적으로, zoneinfo는 가능하면 시스템의 시간대 데이터를 사용합니다; 사용 가능한 시스템 시간대 데이터가 없으면, 라이브러리는 PyPI에 있는 자사(first-party) tzdata 패키지를 사용하는 것으로 대체합니다.
더 보기
ZoneInfo 사용하기¶
ZoneInfo는 datetime.tzinfo 추상 베이스 클래스의 구상 구현이며, 생성자, datetime.replace 메서드 또는 datetime.astimezone을 통해 tzinfo에 연결하려는 것입니다:
>>> from zoneinfo import ZoneInfo
>>> from datetime import datetime, timedelta
>>> dt = datetime(2020, 10, 31, 12, tzinfo=ZoneInfo("America/Los_Angeles"))
>>> print(dt)
2020-10-31 12:00:00-07:00
>>> dt.tzname()
'PDT'
이 방식으로 구성된 datetime들은 datetime 산술과 호환되며 추가 개입 없이 일광 절약 시간제 전환을 처리합니다:
>>> dt_add = dt + timedelta(days=1)
>>> print(dt_add)
2020-11-01 12:00:00-08:00
>>> dt_add.tzname()
'PST'
이 시간대는 PEP 495에 도입된 fold 어트리뷰트도 지원합니다. 모호한 시간을 유발하는 오프셋 전환(가령 일광 절약 시간에서 표준 시간으로의 전환) 중, 전환 전의 오프셋이 fold=0일 때 사용되며, 전환 후의 오프셋은 fold=1일 때 사용됩니다, 예를 들어:
>>> dt = datetime(2020, 11, 1, 1, tzinfo=ZoneInfo("America/Los_Angeles"))
>>> print(dt)
2020-11-01 01:00:00-07:00
>>> print(dt.replace(fold=1))
2020-11-01 01:00:00-08:00
다른 시간대에서 변환할 때, fold는 올바른 값으로 설정됩니다:
>>> from datetime import timezone
>>> LOS_ANGELES = ZoneInfo("America/Los_Angeles")
>>> dt_utc = datetime(2020, 11, 1, 8, tzinfo=timezone.utc)
>>> # Before the PDT -> PST transition
>>> print(dt_utc.astimezone(LOS_ANGELES))
2020-11-01 01:00:00-07:00
>>> # After the PDT -> PST transition
>>> print((dt_utc + timedelta(hours=1)).astimezone(LOS_ANGELES))
2020-11-01 01:00:00-08:00
데이터 소스¶
zoneinfo 모듈은 시간대 데이터를 직접 제공하지 않고, 시스템 시간대 데이터베이스나 자사(first-party) PyPI 패키지 tzdata(있다면)에서 시간대 정보를 가져옵니다. 특히 윈도우 시스템을 포함한 일부 시스템에는 사용 가능한 IANA 데이터베이스가 없어서, 시간대 데이터가 필요한 플랫폼 간 호환성을 목표로 하는 프로젝트는 tzdata에 대한 종속성을 선언하는 것이 좋습니다. 시스템 데이터나 tzdata를 모두 사용할 수 없으면, ZoneInfo에 대한 모든 호출은 ZoneInfoNotFoundError를 발생시킵니다.
데이터 소스 구성¶
ZoneInfo(key)가 호출될 때, 생성자는 먼저 TZPATH에 지정된 디렉터리에서 key와 일치하는 파일을 검색하고, 실패하면 tzdata 패키지에서 일치하는 것을 찾습니다. 이 동작은 세 가지 방법으로 구성할 수 있습니다:
실행 시간에는,
reset_tzpath()함수를 사용하여 검색 경로를 조작할 수 있습니다.
컴파일 시간 구성¶
The default TZPATH includes several common deployment locations for the
time zone database (except on Windows, where there are no “well-known”
locations for time zone data). On POSIX systems, downstream distributors and
those building Python from source who know where their system
time zone data is deployed may change the default time zone path by specifying
the compile-time option TZPATH (or, more likely, the configure
flag --with-tzpath), which should be a string delimited by
os.pathsep.
모든 플랫폼에서, 구성된 값은 sysconfig.get_config_var()에서 TZPATH 키로 사용 가능합니다.
환경 구성¶
TZPATH를 초기화할 때 (임포트 시점이나 인자 없이 reset_tzpath()가 호출될 때마다) zoneinfo 모듈은 환경 변수 PYTHONTZPATH(있다면)를 사용하여 검색 경로를 설정합니다.
-
PYTHONTZPATH¶ 사용할 시간대 검색 경로를 포함하는
os.pathsep으로 구분된 문자열입니다. 상대 경로가 아닌 절대 경로로만 구성되어야 합니다.PYTHONTZPATH에 지정된 상대 컴포넌트는 사용되지 않지만, 그 밖의 상대 경로가 지정된 경우의 동작은 구현이 정의합니다; CPython은InvalidTZPathWarning을 발생시키지만, 다른 구현에서는 잘못된 구성 요소를 조용히 무시하거나 예외를 발생시킬 수 있습니다.
시스템이 시스템 데이터를 무시하고 tzdata 패키지를 대신 사용하도록 설정하려면, PYTHONTZPATH=""를 설정하십시오.
실행 시간 구성¶
reset_tzpath() 함수를 사용하여 실행 시간에 TZ 검색 경로를 구성할 수도 있습니다. 일반적으로 권장되는 작업은 아닙니다만, 특정 시간대 경로를 사용해야 하는 (또는 시스템 시간대에 대한 액세스를 비활성화해야 하는) 테스트 함수에 사용하는 것은 합리적입니다.
ZoneInfo 클래스¶
-
class
zoneinfo.ZoneInfo(key)¶ 문자열
key로 지정된 IANA 시간대를 나타내는 구상datetime.tzinfo서브 클래스. 기본 생성자에 대한 호출은 항상 동일하다고 비교되는 객체를 반환합니다; 다르게 말하면,ZoneInfo.clear_cache()를 통한 캐시 무효화를 방지한다면, 다음 어서션이 항상 참입니다:a = ZoneInfo(key) b = ZoneInfo(key) assert a is b
key는 상위 수준 참조가 없는 상대적인 정규화된 POSIX 경로의 형식이어야 합니다. 적합하지 않은 key가 전달되면 생성자가ValueError를 발생시킵니다.key와 일치하는 파일이 없으면, 생성자는ZoneInfoNotFoundError를 발생시킵니다.
ZoneInfo 클래스에는 두 개의 대체 생성자가 있습니다:
-
classmethod
ZoneInfo.from_file(fobj, /, key=None)¶ 바이트열을 반환하는 파일류 객체(예를 들어 바이너리 모드로 열린 파일이나
io.BytesIO객체)에서ZoneInfo객체를 생성합니다. 기본 생성자와 달리, 항상 새로운 객체를 생성합니다.key매개 변수는__str__()과__repr__()를 위해 시간대 이름을 설정합니다.이 생성자를 통해 만들어진 객체는 피클 할 수 없습니다 (피클 직렬화를 참조하십시오).
-
classmethod
ZoneInfo.no_cache(key)¶ 생성자의 캐시를 우회하는 대체 생성자. 기본 생성자와 동일하지만, 호출마다 새 객체를 반환합니다. 이것은 테스트나 데모 목적으로 유용 할 수 있지만, 다른 캐시 무효화 전략을 갖는 시스템을 만드는 데 사용될 수도 있습니다.
이 생성자를 통해 만들어진 객체는 역 피클 될 때 역 직렬화 프로세스의 캐시도 우회합니다.
조심
이 생성자를 사용하면 예기치 못한 방식으로 날짜 시간의 의미가 변경될 수 있기 때문에, 필요한 경우에만 사용하십시오.
다음과 같은 클래스 메서드도 사용할 수 있습니다:
-
classmethod
ZoneInfo.clear_cache(*, only_keys=None)¶ ZoneInfo클래스에서 캐시를 무효로 하는 메서드. 인자가 전달되지 않으면, 모든 캐시가 무효가 되고 각 키의 기본 생성자에 대한 다음 호출은 새 인스턴스를 반환합니다.키 이름의 이터러블이
only_keys매개 변수에 전달되면, 지정된 키만 캐시에서 제거됩니다.only_keys에 전달되었지만, 캐시에서 찾을 수 없는 키는 무시됩니다.경고
이 함수를 호출하면 예기치 못한 방식으로
ZoneInfo를 사용하는 날짜 시간의 의미를 변경할 수 있습니다; 이는 프로세스 전체의 전역 상태를 수정하므로 광범위한 영향을 미칠 수 있습니다. 필요한 경우에만 사용하십시오.
이 클래스에는 하나의 어트리뷰트가 있습니다:
-
ZoneInfo.key¶ 이것은 읽기 전용 어트리뷰트이며 생성자에 전달된
key의 값을 반환하는데, IANA 시간대 데이터베이스의 조회 키이어야 합니다 (예를 들어America/New_York,Europe/Paris또는Asia/Tokyo).key매개 변수를 지정하지 않고 파일에서 생성된 시간대의 경우,None으로 설정됩니다.참고
이들을 최종 사용자에게 노출하는 것이 다소 일반적인 관행이지만, 이 값들은 관련 시간대를 나타내는 기본 키로 설계되었을 뿐, 사용자 대면 요소일 필요는 없습니다. CLDR (the Unicode Common Locale Data Repository)과 같은 프로젝트를 사용하면 이러한 키에서 더 사용자 친화적인 문자열을 얻을 수 있습니다.
문자열 표현¶
ZoneInfo 객체에 대해 str을 호출할 때 반환되는 문자열 표현은 기본적으로 ZoneInfo.key 어트리뷰트를 사용합니다 (어트리뷰트 설명서의 사용법에 관한 참고를 보십시오):
>>> zone = ZoneInfo("Pacific/Kwajalein")
>>> str(zone)
'Pacific/Kwajalein'
>>> dt = datetime(2020, 4, 1, 3, 15, tzinfo=zone)
>>> f"{dt.isoformat()} [{dt.tzinfo}]"
'2020-04-01T03:15:00+12:00 [Pacific/Kwajalein]'
key 매개 변수를 지정하지 않고 파일에서 생성된 객체의 경우, str은 repr() 호출로 대체됩니다. ZoneInfo의 repr은 구현 정의이며 버전 간에 반드시 안정적일 필요는 없지만, 유효한 ZoneInfo 키가 될 수는 없음이 보장됩니다.
피클 직렬화¶
모든 전환 데이터를 직렬화하는 대신, ZoneInfo 객체는 키로 직렬화되며 파일에서 생성된 ZoneInfo 객체는 (지정된 key 값을 가진 객체조차) 피클 할 수 없습니다.
ZoneInfo 파일의 동작은 파일 생성 방식에 따라 다릅니다:
ZoneInfo(key): 기본 생성자로 생성될 때,ZoneInfo객체는 키로 직렬화되며, 역 직렬화할 때, 역 직렬화 프로세스는 기본 생성자를 사용해서 같은 시간대에 대한 다른 참조와 같은 객체가 될 것으로 예상됩니다. 예를 들어,europe_berlin_pkl이ZoneInfo("Europe/Berlin")에서 생성된 피클을 포함하는 문자열이면, 다음과 같은 동작이 예상됩니다:>>> a = ZoneInfo("Europe/Berlin") >>> b = pickle.loads(europe_berlin_pkl) >>> a is b True
ZoneInfo.no_cache(key): 캐시 우회 생성자에서 생성될 때, 이ZoneInfo객체도 키로 직렬화되지만, 역 직렬화할 때, 역 직렬화 프로세스는 캐시 우회 생성자를 사용합니다.europe_berlin_pkl_nc가ZoneInfo.no_cache("Europe/Berlin")에서 생성된 피클을 포함하는 문자열이면, 다음과 같은 동작이 예상됩니다:>>> a = ZoneInfo("Europe/Berlin") >>> b = pickle.loads(europe_berlin_pkl_nc) >>> a is b False
ZoneInfo.from_file(fobj, /, key=None): 파일에서 생성될 때,ZoneInfo객체는 피클 하려고 하면 예외를 발생시킵니다. 최종 사용자가 파일에서 생성된ZoneInfo를 피클 하길 원하면, 래퍼 형이나 사용자 정의 직렬화 함수를 사용하는 것이 좋습니다: 키로 직렬화하거나 파일 객체의 내용을 저장하고 직렬화합니다.
이 직렬화 방법에서는 직렬화와 역 직렬화 환경 모두에서 클래스와 함수에 대한 참조가 존재해야 하는 방식과 유사하게, 직렬화와 역 직렬화 측 모두에서 필요한 키의 시간대 데이터를 사용할 수 있어야 합니다. 또한 다른 버전의 시간대 데이터가 있는 환경에서 피클링 된 ZoneInfo를 역 피클링 할 때 결과의 일관성에 대해 보장되지 않습니다.
함수¶
-
zoneinfo.available_timezones()¶ 시간대 경로의 어느 곳에서건 사용 가능한 IANA 시간대에 유효한 모든 키가 포함된 집합을 가져옵니다. 이것은 함수를 호출할 때마다 다시 계산됩니다.
이 함수는 규범적(canonical) 시간대 이름 만 포함하고
posix/와right/디렉터리에 있는 것이나posixrules시간대와 같은 “특수” 시간대는 포함하지 않습니다.조심
시간대 경로에 있는 파일이 유효한 시간대인지 확인하는 가장 좋은 방법은 시작 부분에 나오는 “매직 문자열”을 읽는 것이라서, 이 함수는 많은 파일을 열 수 있습니다.
참고
이 값은 최종 사용자에게 노출되도록 설계되지 않았습니다; 사용자 대면 요소의 경우, 응용 프로그램은 CLDR (the Unicode Common Locale Data Repository)과 같은 것을 사용하여 더 사용자 친화적인 문자열을 가져와야 합니다.
ZoneInfo.key에 있는 주의 사항도 참조하십시오.
-
zoneinfo.reset_tzpath(to=None)¶ 모듈의 시간대 검색 경로(
TZPATH)를 설정하거나 재설정합니다. 인자 없이 호출하면,TZPATH가 기본값으로 설정됩니다.reset_tzpath를 호출해도ZoneInfo캐시가 무효가 되지 않아서, 기본ZoneInfo생성자에 대한 호출은 캐시 누락의 경우에만 새TZPATH를 사용합니다.to매개 변수는 문자열이나os.PathLike의 시퀀스이어야 하며 문자열이 아닙니다. 모두 절대 경로여야 합니다. 절대 경로 이외의 것이 전달되면ValueError가 발생합니다.
전역¶
-
zoneinfo.TZPATH¶ 시간대 검색 경로를 나타내는 읽기 전용 시퀀스 – 키에서
ZoneInfo를 생성할 때, 키는TZPATH의 각 항목에 결합하며, 발견된 첫 번째 파일이 사용됩니다.TZPATH는 구성 방법과 관계없이 절대 경로만 포함할 수 있고, 상대 경로는 절대 포함하지 않습니다.zoneinfo.TZPATH가 가리키는 객체는reset_tzpath()에 대한 호출에 따라 변경될 수 있어서,zoneinfo에서TZPATH를 임포트 하거나 수명이 긴 변수에zoneinfo.TZPATH를 대입하는 대신zoneinfo.TZPATH를 사용하는 것이 좋습니다.시간대 검색 경로 구성에 대한 자세한 정보는 데이터 소스 구성을 참조하십시오.
예외와 경고¶
-
exception
zoneinfo.ZoneInfoNotFoundError¶ 지정된 키를 시스템에서 찾을 수 없어서
ZoneInfo객체 생성에 실패할 때 발생합니다. 이것은KeyError의 서브 클래스입니다.
-
exception
zoneinfo.InvalidTZPathWarning¶ PYTHONTZPATH에 상대 경로와 같이 필터링 될 유효하지 않은 구성 요소가 포함되어있을 때 발생합니다.