zoneinfo — IANA:s stöd för tidszoner

Tillagd i version 3.9.

Källkod: Lib/zoneinfo

Modulen zoneinfo tillhandahåller en konkret implementering av tidszoner för att stödja IANA:s tidszonsdatabas som ursprungligen specificerades i PEP 615. Som standard använder zoneinfo systemets tidszonsdata om de finns tillgängliga; om inga systemets tidszonsdata finns tillgängliga kommer biblioteket att falla tillbaka till att använda förstapartspaketet tzdata som finns tillgängligt på PyPI.

Se även

Modul: datetime

Tillhandahåller typerna time och datetime med vilka klassen ZoneInfo är avsedd att användas.

Paket tzdata

Förstapartspaket som underhålls av CPython-kärnutvecklarna för att tillhandahålla tidszonsdata via PyPI.

Tillgänglighet: not WASI.

Den här modulen fungerar inte eller är inte tillgänglig på WebAssembly. Se WebAssembly-plattformar för mer information.

Använda ZoneInfo

ZoneInfo är en konkret implementation av den abstrakta basklassen datetime.tzinfo, och är avsedd att kopplas till tzinfo, antingen via konstruktorn, metoden datetime.replace eller 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'

Datatider som konstrueras på detta sätt är kompatibla med datatidsaritmetik och hanterar övergångar till sommartid utan ytterligare åtgärder:

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

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

>>> dt_add.tzname()
'PST'

Dessa tidszoner har också stöd för attributet fold som introducerades i PEP 495. Vid offsetövergångar som ger upphov till tvetydiga tider (t.ex. en övergång från sommartid till normaltid) används offset från före övergången när fold=0, och offset efter övergången används när fold=1, t.ex:

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

När du konverterar från en annan tidszon kommer vikningen att ställas in på rätt värde:

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

Datakällor

Modulen zoneinfo tillhandahåller inte tidszonsdata direkt, utan hämtar istället tidszonsinformation från systemets tidszonsdatabas eller PyPI-paketet tzdata, om det finns tillgängligt. Vissa system, inklusive särskilt Windows-system, har inte en IANA-databas tillgänglig, så för projekt som riktar sig mot kompatibilitet mellan plattformar som kräver tidszonsdata rekommenderas det att deklarera ett beroende av tzdata. Om varken systemdata eller tzdata finns tillgängliga, kommer alla anrop till ZoneInfo att ge upphov till ZoneInfoNotFoundError.

Konfigurera datakällorna

När ZoneInfo(key) anropas söker konstruktören först i de kataloger som anges i TZPATH efter en fil som matchar key, och om den inte gör det letar den efter en matchning i tzdata-paketet. Detta beteende kan konfigureras på tre sätt:

  1. Standardvärdet TZPATH kan, om inget annat anges, konfigureras vid kompileringstid.

  2. TZPATH kan konfigureras med en miljövariabel.

  3. Vid runtime kan sökvägen manipuleras med hjälp av funktionen reset_tzpath().

Konfiguration under kompileringstiden

Standard TZPATH innehåller flera vanliga distributionsplatser för tidszonsdatabasen (utom på Windows, där det inte finns några ”välkända” platser för tidszonsdata). På POSIX-system kan nedströmsdistributörer och de som bygger Python från källan och som vet var deras systems tidszonsdata distribueras ändra standardtidszonssökvägen genom att ange kompileringstidsalternativet TZPATH (eller, mer troligt, configure flag --with-tzpath), som bör vara en sträng avgränsad av os.pathsep.

På alla plattformar är det konfigurerade värdet tillgängligt som nyckeln TZPATH i sysconfig.get_config_var().

Konfiguration av miljö

Vid initiering av TZPATH (antingen vid import eller när reset_tzpath() anropas utan argument) kommer modulen zoneinfo att använda miljövariabeln PYTHONTZPATH, om den finns, för att ange sökvägen.

PYTHONTZPATH

Detta är en os.pathsep-separerad sträng som innehåller sökvägen för tidszonssökning som ska användas. Den måste bestå av absoluta sökvägar snarare än relativa sökvägar. Relativa komponenter som anges i PYTHONTZPATH kommer inte att användas, men annars är beteendet när en relativ sökväg anges implementationsdefinierat; CPython kommer att höja InvalidTZPathWarning, men andra implementationer är fria att tyst ignorera den felaktiga komponenten eller höja ett undantag.

Om du vill att systemet ska ignorera systemdata och använda tzdata-paketet i stället anger du PYTHONTZPATH="".

Konfiguration för körtid

TZ-sökvägen kan också konfigureras vid körning med hjälp av funktionen reset_tzpath(). Detta är i allmänhet inte en tillrådlig åtgärd, men det är rimligt att använda den i testfunktioner som kräver användning av en specifik sökväg för tidszoner (eller kräver att åtkomst till systemets tidszoner inaktiveras).

Klassen ZoneInfo (zoninformation)

class zoneinfo.ZoneInfo(key)

En konkret datetime.tzinfo-underklass som representerar en IANA-tidszon som specificeras av strängen key. Anrop till den primära konstruktören kommer alltid att returnera objekt som jämför identiskt; uttryckt på ett annat sätt, om inte cachen ogiltigförklaras via ZoneInfo.clear_cache(), för alla värden av key, kommer följande påstående alltid att vara sant:

a = ZoneInfo(nyckel)
b = ZoneInfo(nyckel)
assert a är b

key måste vara i form av en relativ, normaliserad POSIX-sökväg, utan referenser på högre nivå. Konstruktören kommer att ge ValueError om en nyckel som inte överensstämmer skickas.

Om ingen fil som matchar key hittas, kommer konstruktören att ge upphov till ZoneInfoNotFoundError.

Klassen ZoneInfo har två alternativa konstruktörer:

classmethod ZoneInfo.from_file(file_obj, /, key=None)

Konstruerar ett ZoneInfo-objekt från ett filliknande objekt som returnerar bytes (t.ex. en fil som öppnas i binärt läge eller ett io.BytesIO-objekt). Till skillnad från den primära konstruktören konstruerar denna alltid ett nytt objekt.

Parametern key anger namnet på zonen för ändamålen __str__() och __repr__().

Objekt som skapas med denna konstruktor kan inte picklas (se pickling).

classmethod ZoneInfo.no_cache(key)

En alternativ konstruktör som förbigår konstruktörens cache. Den är identisk med den primära konstruktören, men returnerar ett nytt objekt vid varje anrop. Detta är troligen mest användbart för test- eller demonstrationsändamål, men det kan också användas för att skapa ett system med en annan strategi för inaktivering av cachen.

Objekt som skapas via denna konstruktör kommer också att gå förbi cacheminnet i en deserialiseringsprocess när de plockas upp.

Försiktighet

Om du använder den här konstruktören kan semantiken i dina datatider ändras på överraskande sätt, använd den bara om du vet att du behöver det.

Följande klassmetoder är också tillgängliga:

classmethod ZoneInfo.clear_cache(*, only_keys=None)

En metod för att inaktivera cachen för klassen ZoneInfo. Om inga argument anges kommer alla cacher att ogiltigförklaras och nästa anrop till den primära konstruktören för varje nyckel kommer att returnera en ny instans.

Om en iterabel med nyckelnamn skickas till parametern only_keys kommer endast de angivna nycklarna att tas bort från cacheminnet. Nycklar som skickas till only_keys men som inte finns i cachen ignoreras.

Varning

Om denna funktion anropas kan semantiken för datatider som använder ZoneInfo ändras på överraskande sätt; detta ändrar modulens tillstånd och kan därför få omfattande effekter. Använd den bara om du vet att du behöver det.

Klassen har ett attribut:

ZoneInfo.key

Detta är en skrivskyddad attribut som returnerar värdet på key som skickas till konstruktören, vilket bör vara en uppslagsnyckel i IANA:s tidszonsdatabas (t.ex. America/New_York, Europe/Paris eller Asia/Tokyo).

För zoner som konstrueras från en fil utan att ange en key parameter, kommer detta att sättas till None.

Anteckning

Även om det är ganska vanligt att exponera dessa för slutanvändare, är dessa värden utformade för att vara primära nycklar för att representera de relevanta zonerna och inte nödvändigtvis användarvänliga element. Projekt som CLDR (Unicode Common Locale Data Repository) kan användas för att få mer användarvänliga strängar från dessa nycklar.

Representation av strängar

Den strängrepresentation som returneras vid anrop av str på ett ZoneInfo-objekt använder som standard attributet ZoneInfo.key (se anmärkningen om användning i attributdokumentationen):

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

För objekt som konstrueras från en fil utan att ange en key parameter, faller str tillbaka till att anropa repr(). ZoneInfo s repr är implementationsdefinierad och inte nödvändigtvis stabil mellan versioner, men det är garanterat att det inte är en giltig ZoneInfo nyckel.

Pickle-serialisering

I stället för att serialisera alla övergångsdata serialiseras ZoneInfo-objekt efter nyckel, och ZoneInfo-objekt som konstrueras från filer (även de som har ett värde för key angivet) kan inte picklas.

Hur en ZoneInfo-fil fungerar beror på hur den konstruerades:

  1. ZoneInfo(nyckel): När ett ZoneInfo-objekt konstrueras med den primära konstruktören serialiseras det med nyckel, och när det deserialiseras använder deserialiseringsprocessen den primära och därmed förväntas det att dessa förväntas vara samma objekt som andra referenser till samma tidszon. Om till exempel europe_berlin_pkl är en sträng som innehåller en pickle konstruerad från ZoneInfo("Europe/Berlin"), kan man förvänta sig följande beteende:

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

  2. ZoneInfo.no_cache(key): När ZoneInfo-objektet konstrueras från den cache-förbikopplande konstruktören serialiseras det också med nyckel, men när det deserialiseras använder deserialiseringsprocessen den cache-förbikopplande konstruktören. Om europe_berlin_pkl_nc är en sträng som innehåller en pickle konstruerad från ZoneInfo.no_cache("Europe/Berlin"), kan man förvänta sig följande beteende:

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

  3. ZoneInfo.from_file(file_obj, /, key=None): När objektet ZoneInfo konstrueras från en fil uppstår ett undantag vid betning. Om en slutanvändare vill plocka ett ZoneInfo som konstruerats från en fil rekommenderas att de använder en omslagstyp eller en anpassad serialiseringsfunktion: antingen serialisering med nyckel eller lagring av innehållet i filobjektet och serialisering av det.

Denna serialiseringsmetod kräver att tidszonsdata för den nyckel som krävs finns tillgänglig både på den serialiserande och den deserialiserande sidan, på samma sätt som referenser till klasser och funktioner förväntas finnas i både den serialiserande och den deserialiserande miljön. Det innebär också att det inte finns några garantier för att resultaten är konsekventa när en ZoneInfo som är inlagd i en miljö med en annan version av tidszonsdata plockas ut.

Funktioner

zoneinfo.available_timezones()

Hämta en uppsättning som innehåller alla giltiga nycklar för IANA-tidszoner som finns tillgängliga var som helst på tidszonsvägen. Detta räknas om vid varje anrop till funktionen.

Denna funktion inkluderar endast kanoniska zonnamn och inte ”speciella” zoner som de under katalogerna posix/ och right/, eller zonen posixrules.

Försiktighet

Denna funktion kan öppna ett stort antal filer, eftersom det bästa sättet att avgöra om en fil på tidszonssökvägen har en giltig tidszon är att läsa den ”magiska strängen” i början.

Anteckning

Dessa värden är inte avsedda att exponeras för slutanvändare; för element som vänder sig till användare bör program använda något som CLDR (Unicode Common Locale Data Repository) för att få mer användarvänliga strängar. Se även försiktighetsanmärkningen om ZoneInfo.key.

zoneinfo.reset_tzpath(to=None)

Ställer in eller återställer sökvägen för tidszonssökning (TZPATH) för modulen. När den anropas utan argument sätts TZPATH till standardvärdet.

Att anropa reset_tzpath ogiltigförklarar inte ZoneInfo-cachen, och därför kommer anrop till den primära ZoneInfo-konstruktorn endast att använda den nya TZPATH om cachen missas.

Parametern to måste vara en sequence av strängar eller os.PathLike och inte en sträng, som alla måste vara absoluta sökvägar. ValueError kommer att tas upp om något annat än en absolut sökväg skickas.

Globaler

zoneinfo.TZPATH

En skrivskyddad sekvens som representerar sökvägen för tidszoner - när en ZoneInfo konstrueras från en nyckel, kopplas nyckeln till varje post i TZPATH och den första filen som hittas används.

TZPATH kan bara innehålla absoluta sökvägar, aldrig relativa sökvägar, oavsett hur den är konfigurerad.

Objektet som zoneinfo.TZPATH pekar på kan ändras som svar på ett anrop till reset_tzpath(), så det rekommenderas att använda zoneinfo.TZPATH i stället för att importera TZPATH från zoneinfo eller tilldela en långlivad variabel till zoneinfo.TZPATH.

Mer information om hur du konfigurerar sökvägen för tidszoner finns i Konfigurera datakällorna.

Undantag och varningar

exception zoneinfo.ZoneInfoNotFoundError

Uppstår när konstruktionen av ett ZoneInfo-objekt misslyckas eftersom den angivna nyckeln inte kunde hittas i systemet. Detta är en subklass av KeyError.

exception zoneinfo.InvalidTZPathWarning

Utlöses när PYTHONTZPATH innehåller en ogiltig komponent som kommer att filtreras bort, t.ex. en relativ sökväg.