Lines Matching +full:path +full:- +full:key
1 :mod:`zoneinfo` --- IANA time zone support
14 --------------
20 first-party `tzdata`_ package available on PyPI.
29 First-party package maintained by the CPython core developers to supply
32 .. include:: ../includes/wasm-notavail.rst
35 ------------------
47 2020-10-31 12:00:00-07:00
58 2020-11-01 12:00:00-08:00
71 2020-11-01 01:00:00-07:00
74 2020-11-01 01:00:00-08:00
83 >>> # Before the PDT -> PST transition
85 2020-11-01 01:00:00-07:00
87 >>> # After the PDT -> PST transition
89 2020-11-01 01:00:00-08:00
92 ------------
96 first-party PyPI package `tzdata`_, if available. Some systems, including
98 projects targeting cross-platform compatibility that require time zone data, it
108 When ``ZoneInfo(key)`` is called, the constructor first searches the
109 directories specified in :data:`TZPATH` for a file matching ``key``, and on
117 3. At :ref:`runtime <zoneinfo_data_runtime_config>`, the search path can be
122 Compile-time configuration
126 time zone database (except on Windows, where there are no "well-known"
129 time zone data is deployed may change the default time zone path by specifying
130 the compile-time option ``TZPATH`` (or, more likely, the :option:`configure
131 flag --with-tzpath <--with-tzpath>`), which should be a string delimited by
134 On all platforms, the configured value is available as the ``TZPATH`` key in
145 path.
149 This is an :data:`os.pathsep`-separated string containing the time zone
150 search path to use. It must consist of only absolute rather than relative
152 but otherwise the behavior when a relative path is specified is
153 implementation-defined; CPython will raise :exc:`InvalidTZPathWarning`, but
165 The TZ search path can also be configured at runtime using the
168 specific time zone path (or require disabling access to the system time zones).
172 ----------------------
174 .. class:: ZoneInfo(key)
177 zone specified by the string ``key``. Calls to the primary constructor will
180 ``key``, the following assertion will always be true:
182 .. code-block:: python
184 a = ZoneInfo(key)
185 b = ZoneInfo(key)
188 ``key`` must be in the form of a relative, normalized POSIX path, with no
189 up-level references. The constructor will raise :exc:`ValueError` if a
190 non-conforming key is passed.
192 If no file matching ``key`` is found, the constructor will raise
198 .. classmethod:: ZoneInfo.from_file(fobj, /, key=None)
200 Constructs a ``ZoneInfo`` object from a file-like object returning bytes
204 The ``key`` parameter sets the name of the zone for the purposes of
209 .. classmethod:: ZoneInfo.no_cache(key)
233 the primary constructor for each key will return a new instance.
235 If an iterable of key names is passed to the ``only_keys`` parameter, only
244 ``ZoneInfo`` in surprising ways; this modifies process-wide global state
245 and thus may have wide-ranging effects. Only use it if you know that you
250 .. attribute:: ZoneInfo.key
252 This is a read-only :term:`attribute` that returns the value of ``key``
253 passed to the constructor, which should be a lookup key in the IANA time
257 For zones constructed from file without specifying a ``key`` parameter,
264 relevant zones and not necessarily user-facing elements. Projects like
266 more user-friendly strings from these keys.
272 :class:`ZoneInfo` object defaults to using the :attr:`ZoneInfo.key` attribute (see
281 '2020-04-01T03:15:00+12:00 [Pacific/Kwajalein]'
283 For objects constructed from a file without specifying a ``key`` parameter,
285 implementation-defined and not necessarily stable between versions, but it is
286 guaranteed not to be a valid ``ZoneInfo`` key.
294 serialized by key, and ``ZoneInfo`` objects constructed from files (even those
295 with a value for ``key`` specified) cannot be pickled.
299 1. ``ZoneInfo(key)``: When constructed with the primary constructor, a
300 ``ZoneInfo`` object is serialized by key, and when deserialized, the
307 .. code-block:: pycon
314 2. ``ZoneInfo.no_cache(key)``: When constructed from the cache-bypassing
315 constructor, the ``ZoneInfo`` object is also serialized by key, but when
321 .. code-block:: pycon
328 3. ``ZoneInfo.from_file(fobj, /, key=None)``: When constructed from a file, the
332 key or storing the contents of the file object and serializing that.
335 key be available on both the serializing and deserializing side, similar to the
342 ---------
347 anywhere on the time zone path. This is recalculated on every call to the
357 determine if a file on the time zone path is a valid time zone is to
362 These values are not designed to be exposed to end-users; for user
364 Unicode Common Locale Data Repository) to get more user-friendly
365 strings. See also the cautionary note on :attr:`ZoneInfo.key`.
369 Sets or resets the time zone search path (:data:`TZPATH`) for the module.
378 :exc:`ValueError` will be raised if something other than an absolute path
382 -------
386 A read-only sequence representing the time zone search path -- when
387 constructing a ``ZoneInfo`` from a key, the key is joined to each entry in
396 assigning a long-lived variable to ``zoneinfo.TZPATH``.
398 For more information on configuring the time zone search path, see
402 -----------------------
407 specified key could not be found on the system. This is a subclass of
413 be filtered out, such as a relative path.