xref: /third_party/python/Doc/library/zoneinfo.rst

:mod:`zoneinfo` --- IANA time zone support
==========================================

.. module:: zoneinfo
    :synopsis: IANA time zone support

.. versionadded:: 3.9

.. moduleauthor:: Paul Ganssle <paul@ganssle.io>
.. sectionauthor:: Paul Ganssle <paul@ganssle.io>

--------------

The :mod:`zoneinfo` module provides a concrete time zone implementation to
support the IANA time zone database as originally specified in :pep:`615`. By
default, :mod:`zoneinfo` uses the system's time zone data if available; if no
system time zone data is available, the library will fall back to using the
first-party `tzdata`_ package available on PyPI.

.. seealso::

    Module: :mod:`datetime`
        Provides the :class:`~datetime.time` and :class:`~datetime.datetime`
        types with which the :class:`ZoneInfo` class is designed to be used.

    Package `tzdata`_
        First-party package maintained by the CPython core developers to supply
        time zone data via PyPI.


Using ``ZoneInfo``
------------------

:class:`ZoneInfo` is a concrete implementation of the :class:`datetime.tzinfo`
abstract base class, and is intended to be attached to ``tzinfo``, either via
the constructor, the :meth:`datetime.replace <datetime.datetime.replace>`
method or :meth:`datetime.astimezone <datetime.datetime.astimezone>`::

    >>> 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'

Datetimes constructed in this way are compatible with datetime arithmetic and
handle daylight saving time transitions with no further intervention::

    >>> dt_add = dt + timedelta(days=1)

    >>> print(dt_add)
    2020-11-01 12:00:00-08:00

    >>> dt_add.tzname()
    'PST'

These time zones also support the :attr:`~datetime.datetime.fold` attribute
introduced in :pep:`495`.  During offset transitions which induce ambiguous
times (such as a daylight saving time to standard time transition), the offset
from *before* the transition is used when ``fold=0``, and the offset *after*
the transition is used when ``fold=1``, for example::

    >>> 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

When converting from another time zone, the fold will be set to the correct
value::

    >>> 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

Data sources
------------

The ``zoneinfo`` module does not directly provide time zone data, and instead
pulls time zone information from the system time zone database or the
first-party PyPI package `tzdata`_, if available. Some systems, including
notably Windows systems, do not have an IANA database available, and so for
projects targeting cross-platform compatibility that require time zone data, it
is recommended to declare a dependency on tzdata. If neither system data nor
tzdata are available, all calls to :class:`ZoneInfo` will raise
:exc:`ZoneInfoNotFoundError`.

.. _zoneinfo_data_configuration:

Configuring the data sources
****************************

When ``ZoneInfo(key)`` is called, the constructor first searches the
directories specified in :data:`TZPATH` for a file matching ``key``, and on
failure looks for a match in the tzdata package. This behavior can be
configured in three ways:

1. The default :data:`TZPATH` when not otherwise specified can be configured at
   :ref:`compile time <zoneinfo_data_compile_time_config>`.
2. :data:`TZPATH` can be configured using :ref:`an environment variable
   <zoneinfo_data_environment_var>`.
3. At :ref:`runtime <zoneinfo_data_runtime_config>`, the search path can be
   manipulated using the :func:`reset_tzpath` function.

.. _zoneinfo_data_compile_time_config:

Compile-time configuration
^^^^^^^^^^^^^^^^^^^^^^^^^^

The default :data:`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 :option:`configure
flag --with-tzpath <--with-tzpath>`), which should be a string delimited by
:data:`os.pathsep`.

On all platforms, the configured value is available as the ``TZPATH`` key in
:func:`sysconfig.get_config_var`.

.. _zoneinfo_data_environment_var:

Environment configuration
^^^^^^^^^^^^^^^^^^^^^^^^^

When initializing :data:`TZPATH` (either at import time or whenever
:func:`reset_tzpath` is called with no arguments), the ``zoneinfo`` module will
use the environment variable ``PYTHONTZPATH``, if it exists, to set the search
path.

.. envvar:: PYTHONTZPATH

    This is an :data:`os.pathsep`-separated string containing the time zone
    search path to use. It must consist of only absolute rather than relative
    paths. Relative components specified in ``PYTHONTZPATH`` will not be used,
    but otherwise the behavior when a relative path is specified is
    implementation-defined; CPython will raise :exc:`InvalidTZPathWarning`, but
    other implementations are free to silently ignore the erroneous component
    or raise an exception.

To set the system to ignore the system data and use the tzdata package
instead, set ``PYTHONTZPATH=""``.

.. _zoneinfo_data_runtime_config:

Runtime configuration
^^^^^^^^^^^^^^^^^^^^^

The TZ search path can also be configured at runtime using the
:func:`reset_tzpath` function. This is generally not an advisable operation,
though it is reasonable to use it in test functions that require the use of a
specific time zone path (or require disabling access to the system time zones).


The ``ZoneInfo`` class
----------------------

.. class:: ZoneInfo(key)

    A concrete :class:`datetime.tzinfo` subclass that represents an IANA time
    zone specified by the string ``key``. Calls to the primary constructor will
    always return objects that compare identically; put another way, barring
    cache invalidation via :meth:`ZoneInfo.clear_cache`, for all values of
    ``key``, the following assertion will always be true:

    .. code-block:: python

        a = ZoneInfo(key)
        b = ZoneInfo(key)
        assert a is b

    ``key`` must be in the form of a relative, normalized POSIX path, with no
    up-level references. The constructor will raise :exc:`ValueError` if a
    non-conforming key is passed.

    If no file matching ``key`` is found, the constructor will raise
    :exc:`ZoneInfoNotFoundError`.


The ``ZoneInfo`` class has two alternate constructors:

.. classmethod:: ZoneInfo.from_file(fobj, /, key=None)

    Constructs a ``ZoneInfo`` object from a file-like object returning bytes
    (e.g. a file opened in binary mode or an :class:`io.BytesIO` object).
    Unlike the primary constructor, this always constructs a new object.

    The ``key`` parameter sets the name of the zone for the purposes of
    :py:meth:`~object.__str__` and :py:meth:`~object.__repr__`.

    Objects created via this constructor cannot be pickled (see `pickling`_).

.. classmethod:: ZoneInfo.no_cache(key)

    An alternate constructor that bypasses the constructor's cache. It is
    identical to the primary constructor, but returns a new object on each
    call. This is most likely to be useful for testing or demonstration
    purposes, but it can also be used to create a system with a different cache
    invalidation strategy.

    Objects created via this constructor will also bypass the cache of a
    deserializing process when unpickled.

    .. TODO: Add "See `cache_behavior`_" reference when that section is ready.

    .. caution::

        Using this constructor may change the semantics of your datetimes in
        surprising ways, only use it if you know that you need to.

The following class methods are also available:

.. classmethod:: ZoneInfo.clear_cache(*, only_keys=None)

    A method for invalidating the cache on the ``ZoneInfo`` class. If no
    arguments are passed, all caches are invalidated and the next call to
    the primary constructor for each key will return a new instance.

    If an iterable of key names is passed to the ``only_keys`` parameter, only
    the specified keys will be removed from the cache. Keys passed to
    ``only_keys`` but not found in the cache are ignored.

    .. TODO: Add "See `cache_behavior`_" reference when that section is ready.

    .. warning::

        Invoking this function may change the semantics of datetimes using
        ``ZoneInfo`` in surprising ways; this modifies process-wide global state
        and thus may have wide-ranging effects. Only use it if you know that you
        need to.

The class has one attribute:

.. attribute:: ZoneInfo.key

    This is a read-only :term:`attribute` that returns the value of ``key``
    passed to the constructor, which should be a lookup key in the IANA time
    zone database (e.g. ``America/New_York``, ``Europe/Paris`` or
    ``Asia/Tokyo``).

    For zones constructed from file without specifying a ``key`` parameter,
    this will be set to ``None``.

    .. note::

        Although it is a somewhat common practice to expose these to end users,
        these values are designed to be primary keys for representing the
        relevant zones and not necessarily user-facing elements.  Projects like
        CLDR (the Unicode Common Locale Data Repository) can be used to get
        more user-friendly strings from these keys.

String representations
**********************

The string representation returned when calling :py:class:`str` on a
:class:`ZoneInfo` object defaults to using the :attr:`ZoneInfo.key` attribute (see
the note on usage in the attribute documentation)::

    >>> 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]'

For objects constructed from a file without specifying a ``key`` parameter,
``str`` falls back to calling :func:`repr`. ``ZoneInfo``'s ``repr`` is
implementation-defined and not necessarily stable between versions, but it is
guaranteed not to be a valid ``ZoneInfo`` key.

.. _pickling:

Pickle serialization
********************

Rather than serializing all transition data, ``ZoneInfo`` objects are
serialized by key, and ``ZoneInfo`` objects constructed from files (even those
with a value for ``key`` specified) cannot be pickled.

The behavior of a ``ZoneInfo`` file depends on how it was constructed:

1. ``ZoneInfo(key)``: When constructed with the primary constructor, a
   ``ZoneInfo`` object is serialized by key, and when deserialized, the
   deserializing process uses the primary and thus it is expected that these
   are expected to be the same object as other references to the same time
   zone.  For example, if ``europe_berlin_pkl`` is a string containing a pickle
   constructed from ``ZoneInfo("Europe/Berlin")``, one would expect the
   following behavior:

   .. code-block:: pycon

       >>> a = ZoneInfo("Europe/Berlin")
       >>> b = pickle.loads(europe_berlin_pkl)
       >>> a is b
       True

2. ``ZoneInfo.no_cache(key)``: When constructed from the cache-bypassing
   constructor, the ``ZoneInfo`` object is also serialized by key, but when
   deserialized, the deserializing process uses the cache bypassing
   constructor. If ``europe_berlin_pkl_nc`` is a string containing a pickle
   constructed from ``ZoneInfo.no_cache("Europe/Berlin")``, one would expect
   the following behavior:

   .. code-block:: pycon

       >>> a = ZoneInfo("Europe/Berlin")
       >>> b = pickle.loads(europe_berlin_pkl_nc)
       >>> a is b
       False

3. ``ZoneInfo.from_file(fobj, /, key=None)``: When constructed from a file, the
   ``ZoneInfo`` object raises an exception on pickling. If an end user wants to
   pickle a ``ZoneInfo`` constructed from a file, it is recommended that they
   use a wrapper type or a custom serialization function: either serializing by
   key or storing the contents of the file object and serializing that.

This method of serialization requires that the time zone data for the required
key be available on both the serializing and deserializing side, similar to the
way that references to classes and functions are expected to exist in both the
serializing and deserializing environments. It also means that no guarantees
are made about the consistency of results when unpickling a ``ZoneInfo``
pickled in an environment with a different version of the time zone data.

Functions
---------

.. function:: available_timezones()

    Get a set containing all the valid keys for IANA time zones available
    anywhere on the time zone path. This is recalculated on every call to the
    function.

    This function only includes canonical zone names and does not include
    "special" zones such as those under the ``posix/`` and ``right/``
    directories, or the ``posixrules`` zone.

    .. caution::

        This function may open a large number of files, as the best way to
        determine if a file on the time zone path is a valid time zone is to
        read the "magic string" at the beginning.

    .. note::

        These values are not designed to be exposed to end-users; for user
        facing elements, applications should use something like CLDR (the
        Unicode Common Locale Data Repository) to get more user-friendly
        strings. See also the cautionary note on :attr:`ZoneInfo.key`.

.. function:: reset_tzpath(to=None)

    Sets or resets the time zone search path (:data:`TZPATH`) for the module.
    When called with no arguments, :data:`TZPATH` is set to the default value.

    Calling ``reset_tzpath`` will not invalidate the :class:`ZoneInfo` cache,
    and so calls to the primary ``ZoneInfo`` constructor will only use the new
    ``TZPATH`` in the case of a cache miss.

    The ``to`` parameter must be a :term:`sequence` of strings or
    :class:`os.PathLike` and not a string, all of which must be absolute paths.
    :exc:`ValueError` will be raised if something other than an absolute path
    is passed.

Globals
-------

.. data:: TZPATH

    A read-only sequence representing the time zone search path -- when
    constructing a ``ZoneInfo`` from a key, the key is joined to each entry in
    the ``TZPATH``, and the first file found is used.

    ``TZPATH`` may contain only absolute paths, never relative paths,
    regardless of how it is configured.

    The object that ``zoneinfo.TZPATH`` points to may change in response to a
    call to :func:`reset_tzpath`, so it is recommended to use
    ``zoneinfo.TZPATH`` rather than importing ``TZPATH`` from ``zoneinfo`` or
    assigning a long-lived variable to ``zoneinfo.TZPATH``.

    For more information on configuring the time zone search path, see
    :ref:`zoneinfo_data_configuration`.

Exceptions and warnings
-----------------------

.. exception:: ZoneInfoNotFoundError

    Raised when construction of a :class:`ZoneInfo` object fails because the
    specified key could not be found on the system. This is a subclass of
    :exc:`KeyError`.

.. exception:: InvalidTZPathWarning

    Raised when :envvar:`PYTHONTZPATH` contains an invalid component that will
    be filtered out, such as a relative path.

.. Links and references:

.. _tzdata: https://pypi.org/project/tzdata/