UsingZoneInfo¶

ZoneInfo is a concrete implementation of thedatetime.tzinfoabstract base class, and is intended to be attached totzinfo, either viathe constructor, thedatetime.replacemethod ordatetime.astimezone:

>>>fromzoneinfoimportZoneInfo>>>fromdatetimeimportdatetime,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 andhandle 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 thefold attributeintroduced inPEP 495. During offset transitions which induce ambiguoustimes (such as a daylight saving time to standard time transition), the offsetfrombefore the transition is used whenfold=0, and the offsetafterthe transition is used whenfold=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 correctvalue:

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

Thezoneinfo module does not directly provide time zone data, and insteadpulls time zone information from the system time zone database or thefirst-party PyPI packagetzdata, if available. Some systems, includingnotably Windows systems, do not have an IANA database available, and so forprojects targeting cross-platform compatibility that require time zone data, itis recommended to declare a dependency on tzdata. If neither system data nortzdata are available, all calls toZoneInfo will raiseZoneInfoNotFoundError.

TheZoneInfo class¶

classzoneinfo.ZoneInfo(key)¶

A concretedatetime.tzinfo subclass that represents an IANA timezone specified by the stringkey. Calls to the primary constructor willalways return objects that compare identically; put another way, barringcache invalidation viaZoneInfo.clear_cache(), for all values ofkey, the following assertion will always be true:

a=ZoneInfo(key)b=ZoneInfo(key)assertaisb

key must be in the form of a relative, normalized POSIX path, with noup-level references. The constructor will raiseValueError if anon-conforming key is passed.

If no file matchingkey is found, the constructor will raiseZoneInfoNotFoundError.

TheZoneInfo class has two alternate constructors:

classmethodZoneInfo.from_file(fobj,/,key=None)¶

Constructs aZoneInfo object from a file-like object returning bytes(e.g. a file opened in binary mode or anio.BytesIO object).Unlike the primary constructor, this always constructs a new object.

Thekey parameter sets the name of the zone for the purposes of__str__() and__repr__().

Objects created via this constructor cannot be pickled (seepickling).

classmethodZoneInfo.no_cache(key)¶

An alternate constructor that bypasses the constructor's cache. It isidentical to the primary constructor, but returns a new object on eachcall. This is most likely to be useful for testing or demonstrationpurposes, but it can also be used to create a system with a different cacheinvalidation strategy.

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

警示

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

The following class methods are also available:

classmethodZoneInfo.clear_cache(*,only_keys=None)¶

A method for invalidating the cache on theZoneInfo class. If noarguments are passed, all caches are invalidated and the next call tothe primary constructor for each key will return a new instance.

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

警告

Invoking this function may change the semantics of datetimes usingZoneInfo in surprising ways; this modifies module stateand thus may have wide-ranging effects. Only use it if you know that youneed to.

The class has one attribute:

ZoneInfo.key¶

This is a read-onlyattribute that returns the value ofkeypassed to the constructor, which should be a lookup key in the IANA timezone database (e.g.America/New_York,Europe/Paris orAsia/Tokyo).

For zones constructed from file without specifying akey parameter,this will be set toNone.

備註

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

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

函式¶

zoneinfo.available_timezones()¶

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

This function only includes canonical zone names and does not include"special" zones such as those under theposix/ andright/directories, or theposixrules zone.

警示

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

備註

These values are not designed to be exposed to end-users; for userfacing elements, applications should use something like CLDR (theUnicode Common Locale Data Repository) to get more user-friendlystrings. See also the cautionary note onZoneInfo.key.

zoneinfo.reset_tzpath(to=None)¶

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

Callingreset_tzpath will not invalidate theZoneInfo cache,and so calls to the primaryZoneInfo constructor will only use the newTZPATH in the case of a cache miss.

Theto parameter must be asequence of strings oros.PathLike and not a string, all of which must be absolute paths.ValueError will be raised if something other than an absolute pathis passed.

Globals¶

zoneinfo.TZPATH¶

A read-only sequence representing the time zone search path -- whenconstructing aZoneInfo from a key, the key is joined to each entry intheTZPATH, and the first file found is used.

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

The object thatzoneinfo.TZPATH points to may change in response to acall toreset_tzpath(), so it is recommended to usezoneinfo.TZPATH rather than importingTZPATH fromzoneinfo orassigning a long-lived variable tozoneinfo.TZPATH.

For more information on configuring the time zone search path, seeConfiguring the data sources.

Exceptions and warnings¶

exceptionzoneinfo.ZoneInfoNotFoundError¶

Raised when construction of aZoneInfo object fails because thespecified key could not be found on the system. This is a subclass ofKeyError.

exceptionzoneinfo.InvalidTZPathWarning¶

Raised whenPYTHONTZPATH contains an invalid component that willbe filtered out, such as a relative path.