zoneinfo — IANA 시간대 지원

zoneinfo — IANA 시간대 지원

zoneinfo 모듈은 원래 PEP 615에 지정된 IANA 시간대 데이터베이스를 지원하는 구체적인 시간대 구현을 제공해요. 기본적으로 zoneinfo는 시스템의 시간대 데이터를 사용할 수 있으면 그것을 사용하고, 시스템 시간대 데이터가 없으면 PyPI에서 사용할 수 있는 짝(tzdata) 패키지로 대체해요. 버전 3.9에서 추가되었어요.

출처: Python documentation

본문

ZoneInfo 클래스는 datetime 모듈이 제공하는 time과 datetime 타입과 함께 사용하도록 설계되었어요. tzdata는 CPython 코어 개발자들이 유지 관리하는 PyPI 시간대 데이터 공급 패키지예요. 가용성: WASI 아님.

ZoneInfo 사용 (Using ZoneInfo)

ZoneInfo는 datetime.tzinfo 추상 기본 클래스의 구체적인 구현이며, 생성자, datetime.replace 메서드 또는 datetime.astimezone을 통해 tzinfo에 연결하도록 의도되었어요:

>>> from zoneinfo import ZoneInfo
>>> import datetime as dt
>>> when = dt.datetime(2020, 10, 31, 12, tzinfo=ZoneInfo("America/Los_Angeles"))
>>> print(when)
2020-10-31 12:00:00-07:00
>>> when.tzname()
'PDT'

이렇게 만든 datetime은 datetime 산술과 호환되며, 일광 절약 시간 전환을 추가 개입 없이 처리해요. 이러한 시간대는 PEP 495에 도입된 fold 속성도 지원해요. 모호한 시간을 유도하는 오프셋 전환(일광 절약 시간에서 표준 시간으로의 전환 같은) 동안 fold=0일 때는 전환 전의 오프셋이, fold=1일 때는 전환 후의 오프셋이 사용돼요. 다른 시간대에서 변환할 때는 fold가 올바른 값으로 설정돼요.

데이터 소스 (Data sources)

zoneinfo 모듈은 시간대 데이터를 직접 제공하지 않고, 시스템 시간대 데이터베이스나 짝 패키지 tzdata(가능하면)에서 시간대 정보를 가져와요. Windows 시스템을 포함한 일부 시스템에는 IANA 데이터베이스가 없으므로, 크로스 플랫폼 호환성을 목표로 하고 시간대 데이터가 필요한 프로젝트는 tzdata에 종속성을 선언하는 것이 권장돼요. 시스템 데이터도 tzdata도 없으면 모든 ZoneInfo 호출이 ZoneInfoNotFoundError를 발생시켜요.

데이터 소스 구성 (Configuring the data sources)

ZoneInfo(key)가 호출되면 생성자는 먼저 TZPATH에 지정된 디렉터리에서 key와 일치하는 파일을 검색하고, 실패하면 tzdata 패키지에서 일치 항목을 찾아요. 이 동작은 세 가지 방식으로 구성할 수 있어요:

  • 컴파일 시: 기본 TZPATH 구성(--with-tzpath 구성 플래그)
  • 환경 변수: PYTHONTZPATH 환경 변수로 검색 경로 설정. os.pathsep으로 구분된 문자열이어야 하며 절대 경로만 포함해야 해요. PYTHONTZPATH=""로 설정하면 시스템 데이터를 무시하고 tzdata 패키지를 사용해요.
  • 런타임: reset_tzpath() 함수로 검색 경로 조작

기본 TZPATH에는 시간대 데이터베이스의 여러 일반적인 배포 위치가 포함돼요(Windows 제외). 구성된 값은 모든 플랫폼에서 sysconfig.get_config_var()의 TZPATH 키로 사용할 수 있어요.

ZoneInfo 클래스

classzoneinfo.ZoneInfo(key)

문자열 key로 지정된 IANA 시간대를 나타내는 구체적인 datetime.tzinfo 하위 클래스예요. 기본 생성자 호출은 항상 동일하게 비교되는 객체를 반환해요. key는 위쪽 참조가 없는 상대적이고 정규화된 POSIX 경로 형태여야 해요. 비준수 키가 전달되면 생성자가 ValueError를, key와 일치하는 파일이 없으면 ZoneInfoNotFoundError를 발생시켜요.

대체 생성자:

  • classmethod ZoneInfo.from_file(file_obj, /, key=None) — bytes를 반환하는 파일류 객체에서 ZoneInfo 객체를 구성해요. 기본 생성자와 달리 항상 새 객체를 만들어요. 이 생성자로 만든 객체는 피클(pickle)할 수 없어요. file_obj에서 읽은 데이터가 유효한 TZif 파일이 아니면 ValueError가 발생해요.
  • classmethod ZoneInfo.no_cache(key) — 생성자의 캐시를 우회하는 대체 생성자. 호출마다 새 객체를 반환해요. 이 생성자로 만든 객체는 역피클 시 디시리얼라이징 프로세스의 캐시도 우회해요.

클래스 메서드:

  • classmethod ZoneInfo.clear_cache(*, only_keys=None) — ZoneInfo 클래스의 캐시를 무효화하는 메서드. 인자가 없으면 모든 캐시가 무효화되고, only_keys에 키 이름의 iterable이 전달되면 지정된 키만 캐시에서 제거돼요.

class 속성:

  • ZoneInfo.key — 생성자에 전달된 key의 값을 반환하는 읽기 전용 속성. IANA 시간대 데이터베이스의 조회 키(예: America/New_York, Europe/Paris, Asia/Tokyo)여야 해요.

문자열 표현: ZoneInfo 객체에 str을 호출하면 기본적으로 ZoneInfo.key 속성을 사용해요. 파일에서 만든 객체는 키가 지정되지 않았으면 str이 repr()으로 대체돼요.

피클 직렬화: 모든 전환 데이터를 직렬화하는 대신 ZoneInfo 객체는 키로 직렬화돼요. ZoneInfo(key)로 만든 객체는 키로 직렬화되고, 역직렬화 시 기본 생성자를 사용해 같은 시간대의 다른 참조와 같은 객체가 될 것으로 기대돼요. ZoneInfo.no_cache(key)로 만든 객체도 키로 직렬화되지만 역직렬화 시 캐시 우회 생성자를 사용해요. ZoneInfo.from_file()로 만든 객체는 피클 시 예외를 발생시켜요.

함수 (Functions)

  • zoneinfo.available_timezones() — 시간대 경로 어디에서나 사용할 수 있는 IANA 시간대의 모든 유효 키를 담은 set을 가져와요. 호출마다 다시 계산돼요. 정규 시간대 이름만 포함하며 posix/와 right/ 디렉터리 아래의 "특수" 시간대나 posixrules 시간대는 포함하지 않아요. 이 함수는 많은 수의 파일을 열 수 있어요.
  • zoneinfo.reset_tzpath(to=None) — 모듈의 시간대 검색 경로(TZPATH)를 설정하거나 재설정해요. 인자 없이 호출하면 TZPATH가 기본값으로 설정돼요. to 매개변수는 문자열 시퀀스 또는 os.PathLike여야 하며, 모두 절대 경로여야 해요.

전역 (Globals)

  • zoneinfo.TZPATH — 시간대 검색 경로를 나타내는 읽기 전용 시퀀스. 키에서 ZoneInfo를 구성할 때 키는 TZPATH의 각 항목에 결합되고, 처음으로 발견된 파일이 사용돼요. TZPATH는 절대 경로만 포함할 수 있어요. reset_tzpath() 호출에 따라 변경될 수 있으므로 zoneinfo.TZPATH를 사용하는 것이 권장돼요.

예외와 경고 (Exceptions and warnings)

  • exceptionzoneinfo.ZoneInfoNotFoundError — 지정된 키를 시스템에서 찾을 수 없어 ZoneInfo 객체 구축이 실패할 때 발생. KeyError의 하위 클래스예요.
  • exceptionzoneinfo.InvalidTZPathWarning — PYTHONTZPATH가 상대 경로처럼 필터링될 잘못된 구성 요소를 포함할 때 발생.

더 알아보기 (Learn more)