Overview¶

tzdata is a data-only package, organized in such a way that its resources are accessible via importlib.resources (or, in older versions of Python, its backport importlib_resources). Although importlib.resources or equivalent is recommended, it is also possible to access the data via pkgutil.get_data() as well.

It is primarily intended to be used by standard library’s zoneinfo module, but it is also available as a source for time zone data for other time zone libraries. It is generally recommended that any time zone libraries should attempt to use the system data before using the tzdata package, but some systems (notably Windows) do not deploy zoneinfo binaries of this type, and so tzdata is necessary.

Contents¶

The tzdata package provides the output of zic compilation (the equivalent of something like /usr/share/zoneinfo) under the tzdata.zoneinfo package unaltered. This includes the tzdata.zi file, which is a compact text representation of the un-compiled time zone database.

The package organization looks something like this:

src/tzdata
├── __init__.py
├── zoneinfo
│   ├── __init__.py
│   ├── Africa
│   │   ├── __init__.py
│   │   ├── Abidjan
│   │   ├── Accra
│   │   ├── …
│   │   └── Windhoek
│   ├── America
│   │   ├── __init__.py
│   │   ├── Adak
│   │   ├── Anchorage
│   │   ├── …
│   │   └── Yellowknife
│   ├── …
│   ├── tzdata.zi
│   ├── …
│   ├── zone.tab
│   └── Zulu
└── zones

21 directories, 623 files

In addition to the zoneinfo files, it also provides a small amount of extra metadata about the time zones. The tzdata.zones file is a newline-delimited file listing all the IANA keys for time zone files present in the tzdata.zoneinfo package. The version of the IANA data is provided as a Python variable as tzdata.IANA_VERSION.

Examples¶

End users should generally not need to use this package directly and should use a Python library like dateutil.tz or zoneinfo, like so:

# Python 3.9+
from datetime import datetime
from zoneinfo import ZoneInfo

dt = datetime.now(ZoneInfo("America/New_York"))

For those writing time zone libraries, the recommended mechanism for access is to open the relevant zoneinfo binaries with importlib.resources.open_binary(), like so:

from importlib import resources

# America/New_York
with resources.open_binary("tzdata.zoneinfo.America", "New_York") as f:
    assert f.read(4) == b"TZif"

Note that the way this is organized, each folder in tzdata.zoneinfo is a package with resources below it. An example function for converting IANA keys to package names:

def iana_key_to_resource(key):
    package_loc, resource = key.rsplit("/", 1)
    package = "tzdata.zoneinfo." + package_loc.replace("/", ".")

    return package, resource

assert iana_key_to_resource("America/New_York") == \
       ("tzdata.zoneinfo.America", "New_York")
assert iana_key_to_resource("America/Indiana/Indianapolis") == \
       ("tzdata.zoneinfo.America.Indiana", "Indianapolis")