zoneinfo — Υποστήριξη ζωνών ώρας IANA

Added in version 3.9.

Πηγαίος κώδικας: Lib/zoneinfo

The zoneinfo module provides a concrete time zone implementation to support the IANA time zone database as originally specified in PEP 615. By default, 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.

Δείτε επίσης

Module: datetime

Παρέχει τους τύπους time και datetime με τους οποίους έχει σχεδιαστεί να χρησιμοποιείται η κλάση ZoneInfo.

Πακέτο tzdata

Το πακέτο πρώτου μέρους που διατηρείται από τους βασικούς προγραμματιστές της CPython για την παροχή δεδομένων ζώνης ώρας μέσω του PyPI.

Διαθεσιμότητα: not WASI.

Αυτό το module δεν λειτουργεί ή δεν είναι διαθέσιμο στο WebAssembly. Δείτε το WebAssembly platforms για περισσότερες πληροφορίες.

Χρήση του ZoneInfo

Το ZoneInfo είναι μια συγκεκριμένη υλοποίηση της αφηρημένης βασικής κλάσης datetime.tzinfo, και προορίζεται να συνδεθεί με το tzinfo, είτε μέσω του κατασκευαστή, της μεθόδου datetime.replace ή της datetime.astimezone:

>>> from zoneinfo import ZoneInfo
>>> import datetime as dt

>>> when = dt.datetime(2020, 10, 31, 12, tzinfo=ZoneInfo("America/Los_Angeles"))
>>> print(when)
2020-10-31 12:00:00-07:00

>>> when.tzname()
'PDT'

Οι ημερομηνίες και ώρες που κατασκευάζονται με αυτόν τον τρόπο είναι συμβατές με αριθμητικές πράξεις ημερομηνίας και ώρας και χειρίζονται τις μεταβάσεις θερινής ώρας χωρίς περαιτέρω παρέμβαση:

>>> when_add = when + dt.timedelta(days=1)

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

>>> when_add.tzname()
'PST'

Αυτές οι ζώνες ώρας υποστηρίζουν επίσης το χαρακτηριστικό fold που εισήχθη στο PEP 495. Κατά τις μεταβάσεις μετατόπισης που προκαλούν αμφίσημες ώρες (όπως μια μετάβαση από τη θερινή ώρα στη χειμερινή ώρα), η μετατόπιση από πριν τη μετάβαση χρησιμοποιείται όταν fold=0, και η μετατόπιση μετά τη μετάβαση χρησιμοποιείται όταν fold=1, για παράδειγμα:

>>> when = dt.datetime(2020, 11, 1, 1, tzinfo=ZoneInfo("America/Los_Angeles"))
>>> print(when)
2020-11-01 01:00:00-07:00

>>> print(when.replace(fold=1))
2020-11-01 01:00:00-08:00

Κατά τη μετατροπή από άλλη ζώνη ώρας, το fold θα οριστεί στην σωστή τιμή:

>>> LOS_ANGELES = ZoneInfo("America/Los_Angeles")
>>> when_utc = dt.datetime(2020, 11, 1, 8, tzinfo=dt.timezone.utc)

>>> # Before the PDT -> PST transition
>>> print(when_utc.astimezone(LOS_ANGELES))
2020-11-01 01:00:00-07:00

>>> # After the PDT -> PST transition
>>> print((when_utc + dt.timedelta(hours=1)).astimezone(LOS_ANGELES))
2020-11-01 01:00:00-08:00

Πηγές δεδομένων

Το module zoneinfo δεν παρέχει άμεσα δεδομένα ζώνης ώρας, και αντ” αυτού αντλεί πληροφορίες ζώνης ώρας από τη βάση δεδομένων ζώνης ώρας του συστήματος ή από το πακέτο πρώτου μέρους του PyPI tzdata, αν είναι διαθέσιμο. Ορισμένα συστήματα, συμπεριλαμβανομένων ενδεικτικά των συστημάτων Windows, δεν διαθέτουν βάση δεδομένων IANA, και έτσι για έργα που στοχεύουν στη διαλειτουργικότητα μεταξύ πλατφορμών και απαιτούν δεδομένα ζώνης ώρας, συνιστάται να δηλωθεί μια εξάρτηση στο tzdata. Εάν δεν είναι διαθέσιμα ούτε τα δεδομένα συστήματος ούτε το tzdata, όλες οι κλήσεις στο ZoneInfo θα κάνουν raise το ZoneInfoNotFoundError.

Διαμόρφωση των πηγών δεδομένων

Όταν καλείται το ZoneInfo(key), ο κατασκευαστής αναζητά πρώτα στους καταλόγους που καθορίζονται στο TZPATH για ένα αρχείο που ταιριάζει με το key, και σε περίπτωση αποτυχίας αναζητά μια αντιστοιχία στο πακέτο tzdata. Αυτή η συμπεριφορά μπορεί να διαμορφωθεί με τρεις τρόπους:

  1. Όταν η προεπιλεγμένη TZPATH δεν καθορίζεται διαφορετικά, μπορεί να διαμορφωθεί κατά το compile time.

  2. Το TZPATH μπορεί να διαμορφωθεί χρησιμοποιώντας μια μεταβλητή περιβάλλοντος.

  3. Κατά το runtime, η διαδρομή αναζήτησης μπορεί να χειριστεί χρησιμοποιώντας τη συνάρτηση reset_tzpath().

Διαμόρφωση κατά το compile-time

Η προεπιλεγμένη TZPATH περιλαμβάνει αρκετές κοινές τοποθεσίες ανάπτυξης για τη βάση δεδομένων ζώνης ώρας (εκτός από τα Windows, όπου δεν υπάρχουν «γνωστές» τοποθεσίες για δεδομένα ζώνης ώρας). Σε συστήματα POSIX, οι διανομείς κατεβάσματος και αυτοί που γράφουν Python από πηγαίο κώδικα που γνωρίζουν πού είναι αναπτυγμένα τα δεδομένα ζώνης ώρας του συστήματός τους μπορούν να αλλάξουν την προεπιλεγμένη διαδρομή ζώνης ώρας καθορίζοντας την επιλογή κατά το compile-time TZPATH (ή, πιο πιθανώς, το configure flag --with-tzpath), το οποίο πρέπει να είναι μια συμβολοσειρά διαχωρισμένη από os.pathsep.

Σε όλες τις πλατφόρμες, η διαμορφωμένη τιμή είναι διαθέσιμη ως το κλειδί TZPATH στη sysconfig.get_config_var().

Διαμόρφωση περιβάλλοντος

Κατά την αρχικοποίηση του TZPATH (είτε κατά το χρόνο εισαγωγής είτε όποτε καλείται η reset_tzpath() χωρίς ορίσματα), το module zoneinfo θα χρησιμοποιήσει τη μεταβλητή περιβάλλοντος PYTHONTZPATH, αν υπάρχει, για να ορίσει τη διαδρομή αναζήτησης.

PYTHONTZPATH

Αυτή είναι μια συμβολοσειρά διαχωρισμένη από το os.pathsep που περιέχει τη διαδρομή αναζήτησης ζώνης ώρας προς χρήση. Πρέπει να αποτελείται μόνο από απόλυτες και όχι σχετικές διαδρομές. Σχετικά στοιχεία που καθορίζονται στο PYTHONTZPATH δεν θα χρησιμοποιηθούν, αλλά διαφορετικά η συμπεριφορά όταν καθορίζεται μια σχετική διαδρομή είναι ορισμένη από την υλοποίηση· η CPython θα κάνει raise την InvalidTZPathWarning, αλλά άλλες υλοποιήσεις είναι ελεύθερες να αγνοήσουν σιωπηλά το λανθασμένο στοιχείο ή να κάνουν raise μια εξαίρεση.

Για να ρυθμίσετε το σύστημα να αγνοεί τα δεδομένα συστήματος και να χρησιμοποιεί αντ” αυτού το πακέτο tzdata, ορίστε PYTHONTZPATH="".

Διαμόρφωση κατά το runtime

Η διαδρομή αναζήτησης TZ μπορεί επίσης να διαμορφωθεί κατά το runtime χρησιμοποιώντας τη συνάρτηση reset_tzpath(). Αυτή δεν είναι γενικά μια συνιστώμενη λειτουργία, αν και είναι λογικό να τη χρησιμοποιήσετε σε συναρτήσεις δοκιμών που απαιτούν τη χρήση μιας συγκεκριμένης διαδρομής ζώνης ώρας (ή απαιτούν την απενεργοποίηση της πρόσβασης στις ζώνες ώρας συστήματος).

Η κλάση ZoneInfo

class zoneinfo.ZoneInfo(key)

Μια συγκεκριμένη υποκλάση της datetime.tzinfo που αντιπροσωπεύει μια ζώνη ώρας IANA που καθορίζεται από τη συμβολοσειρά key. Οι κλήσεις στον κύριο κατασκευαστή θα επιστρέφουν πάντα αντικείμενα που συγκρίνονται ταυτόσημα· με άλλα λόγια, εκτός από την ακύρωση της προσωρινής μνήμης μέσω της ZoneInfo.clear_cache(), για όλες τις τιμές του key, η ακόλουθη δήλωση θα είναι πάντα αληθής:

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

Το key πρέπει να έχει τη μορφή σχετικής, κανονικοποιημένης διαδρομής POSIX, χωρίς αναφορές σε ανώτερα επίπεδα. Ο κατασκευαστής θα κάνει raise το ValueError αν περαστεί μη συμμορφούμενο κλειδί.

Αν δεν βρεθεί αρχείο που να ταιριάζει με το key, ο κατασκευαστής θα κάνει raise το ZoneInfoNotFoundError.

Τη κλάση ZoneInfo έχει δύο εναλλακτικούς κατασκευαστές:

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

Κατασκευάζει ένα αντικείμενο ZoneInfo από ένα αντικείμενο παρόμοιο με αρχείο που επιστρέφει bytes (π.χ. ένα αρχείο ανοιγμένο σε δυαδική λειτουργία ή ένα αντικείμενο io.BytesIO). Σε αντίθεση με τον κύριο κατασκευαστή, αυτό πάντα κατασκευάζει ένα νέο αντικείμενο.

Η παράμετρος key ορίζει το όνομα της ζώνης για τους σκοπούς των __str__() και __repr__().

Τα αντικείμενα που δημιουργούνται μέσω αυτού του κατασκευαστή δεν μπορούν να σειριοποιηθούν (δείτε pickling).

ValueError is raised if the data read from file_obj is not a valid TZif file.

classmethod ZoneInfo.no_cache(key)

Ένας εναλλακτικός κατασκευαστής που παρακάμπτει την προσωρινή μνήμη του κατασκευαστή. Είναι πανομοιότυπος με τον κύριο κατασκευαστή, αλλά επιστρέφει ένα νέο αντικείμενο σε κάθε κλήση. Αυτό είναι πιο πιθανό να είναι χρήσιμο για σκοπούς δοκιμών ή επίδειξης, αλλά μπορεί επίσης να χρησιμοποιηθεί για τη δημιουργία ενός συστήματος με διαφορετική στρατηγική ακύρωσης της προσωρινής μνήμης.

Τα αντικείμενα που δημιουργούνται μέσω αυτού του κατασκευαστή θα παρακάμπτουν επίσης την προσωρινή μνήμη μιας διαδικασίας αποσειριοποίησης όταν αποσειριοποιούνται.

Προσοχή

Η χρήση αυτού του κατασκευαστή μπορεί να αλλάξει τα νοήματα των ημερομηνιών και ωρών σας με εκπληκτικούς τρόπους, χρησιμοποιήστε τον μόνο αν γνωρίζετε ότι το χρειάζεστε.

Οι ακόλουθες μέθοδοι κλάσης είναι επίσης διαθέσιμες:

classmethod ZoneInfo.clear_cache(*, only_keys=None)

Μια μέθοδος για την ακύρωση της προσωρινής μνήμης στην κλάση ZoneInfo. Αν δεν περαστούν τα ορίσματα, όλες οι προσωρινές μνήμες ακυρώνονται και η επόμενη κλήση στον κύριο κατασκευαστή για κάθε κλειδί θα επιστρέψει ένα νέο στιγμιότυπο.

Αν περαστεί μια iterable συλλογή ονομάτων κλειδιών στην παράμετρο only_keys, μόνο τα καθορισμένα κλειδιά θα αφαιρεθούν από την προσωρινή μνήμη. Τα κλειδιά που περάστηκαν στο only_keys αλλά δεν βρέθηκαν στην προσωρινή μνήμη αγνοούνται.

Προειδοποίηση

Η κλήση αυτής της συνάρτησης μπορεί να αλλάξει τα νοήματα των ημερομηνιών και ωρών που χρησιμοποιούν το ZoneInfo με εκπληκτικούς τρόπους· αυτό τροποποιεί την κατάσταση του module και έτσι μπορεί να έχει ευρείες επιπτώσεις. Χρησιμοποιήστε το μόνο αν γνωρίζετε ότι το χρειάζεστε.

Η κλάση έχει ένα χαρακτηριστικό:

ZoneInfo.key

Αυτό είναι ένα attribute μόνο για ανάγνωση που επιστρέφει την τιμή του key που περάστηκε στον κατασκευαστή, το οποίο θα πρέπει να είναι ένα κλειδί αναζήτησης στη βάση δεδομένων ζώνης ώρας IANA (π.χ. America/New_York, Europe/Paris ή Asia/Tokyo).

Για ζώνες που κατασκευάζονται από αρχείο χωρίς να καθοριστεί μια παράμετρος key, θα οριστεί σε None.

Σημείωση

Αν και είναι μια κάπως κοινή πρακτική να τις εκθέτουν στους τελικούς χρήστες, αυτές οι τιμές έχουν σχεδιαστεί για να είναι πρωτεύοντα κλειδιά για την αναπαράσταση των σχετικών ζωνών και όχι απαραίτητα στοιχεία που απευθύνονται στον χρήστη. Έργα όπως το CLDR (το Unicode Common Locale Data Repository) μπορούν να χρησιμοποιηθούν για να λάβουν πιο φιλικές προς τον χρήστη συμβολοσειρές από αυτά τα κλειδιά.

Αναπαραστάσεις συμβολοσειρών

Η αναπαράσταση συμβολοσειράς που επιστρέφεται κατά την κλήση της str σε ένα αντικείμενο ZoneInfo προεπιλέγεται να χρησιμοποιεί το χαρακτηριστικό ZoneInfo.key (δείτε τη σημείωση σχετικά με τη χρήση στην τεκμηρίωση χαρακτηριστικών):

>>> zone = ZoneInfo("Pacific/Kwajalein")
>>> str(zone)
'Pacific/Kwajalein'

>>> when = dt.datetime(2020, 4, 1, 3, 15, tzinfo=zone)
>>> f"{when.isoformat()} [{when.tzinfo}]"
'2020-04-01T03:15:00+12:00 [Pacific/Kwajalein]'

Για αντικείμενα που κατασκευάζονται από ένα αρχείο χωρίς να καθοριστεί μια παράμετρος key, το str επιστρέφει στην κλήση της repr(). Το repr του ZoneInfo είναι ορισμένο από την υλοποίηση και δεν είναι απαραίτητα σταθερό μεταξύ των εκδόσεων, αλλά εγγυάται ότι δεν θα είναι ένα έγκυρο κλειδί ZoneInfo.

Σειριοποίηση με pickle

Αντί να σειριοποιούν όλα τα δεδομένα μετάβασης, τα αντικείμενα ZoneInfo σειριοποιούνται κατά κλειδί, και τα αντικείμενα ZoneInfo που κατασκευάζονται από αρχεία (ακόμα και αυτά με μια καθορισμένη τιμή για το key) δεν μπορούν να σειριοποιηθούν με pickle.

Η συμπεριφορά ενός αρχείου ZoneInfo εξαρτάται από τον τρόπο με τον οποίο κατασκευάστηκε:

  1. ZoneInfo(key): Όταν κατασκευάζεται με τον κύριο κατασκευαστή, ένα αντικείμενο ZoneInfo σειριοποιείται κατά κλειδί, και όταν αποσειριοποιείται, η διαδικασία αποσειριοποίησης χρησιμοποιεί τον κύριο κατασκευαστή και έτσι αναμένεται ότι αυτά είναι το ίδιο αντικείμενο με άλλες αναφορές στην ίδια ζώνη ώρας. Για παράδειγμα, αν το europe_berlin_pkl είναι μια συμβολοσειρά που περιέχει ένα pickle κατασκευασμένο από ZoneInfo("Europe/Berlin"), θα περίμενε κανείς την ακόλουθη συμπεριφορά:

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

  2. ZoneInfo.no_cache(key): Όταν κατασκευάζεται από τον κατασκευαστή που παρακάμπτει την προσωρινή μνήμη, το αντικείμενο ZoneInfo σειριοποιείται επίσης κατά κλειδί, αλλά όταν αποσειριοποιείται, η διαδικασία αποσειριοποίησης χρησιμοποιεί τον κατασκευαστή που παρακάμπτει την προσωρινή μνήμη. Αν το europe_berlin_pkl_nc είναι μια συμβολοσειρά που περιέχει ένα pickle κατασκευασμένο από το ZoneInfo.no_cache("Europe/Berlin"), θα περίμενε κανείς την ακόλουθη συμπεριφορά:

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

  3. ZoneInfo.from_file(file_obj, /, key=None): Όταν κατασκευάζεται από ένα αρχείο, το αντικείμενο ZoneInfo κάνει raise μια εξαίρεση κατά τη σειριοποίηση με pickle. Αν ένας τελικός χρήστης θέλει να σειριοποιήσει με pickle ένα ZoneInfo που κατασκευάζεται από ένα αρχείο, συνιστάται να χρησιμοποιήσει έναν τύπο περιτύλιξης ή μια προσαρμοσμένη συνάρτηση σειριοποίησης: είτε σειριοποιώντας κατά κλειδί, είτε αποθηκεύοντας τα περιεχόμενα του αντικειμένου του αρχείου και σειριοποιώντας αυτά.

Αυτή η μέθοδος σειριοποίησης απαιτεί τα δεδομένα ζώνης ώρας για το απαιτούμενο κλειδί να είναι διαθέσιμα τόσο στην πλευρά σειριοποίησης όσο και στην πλευρά αποσειριοποίησης, παρόμοια με τον τρόπο που αναμένεται να υπάρχουν αναφορές σε κλάσεις και συναρτήσεις, και στα περιβάλλοντα σειριοποίησης και αποσειριοποίησης. Σημαίνει επίσης ότι δεν δίνονται εγγυήσεις σχετικά με τη συνέπεια των αποτελεσμάτων κατά την αποσειριοποίηση ενός ZoneInfo που έχει σειριοποιηθεί με pickle σε ένα περιβάλλον με διαφορετική έκδοση των δεδομένων ζώνης ώρας.

Συναρτήσεις

zoneinfo.available_timezones()

Λάβετε υπόψη σας ένα σύνολο που περιέχει όλα τα έγκυρα κλειδιά για τις ζώνες ώρας IANA που είναι διαθέσιμες οπουδήποτε στη διαδρομή ζώνης ώρας. Αυτό επαναϋπολογίζεται σε κάθε κλήση της συνάρτησης.

Αυτή η συνάρτηση περιλαμβάνει μόνο κανονικά ονόματα ζώνης και δεν περιλαμβάνει «ειδικές» ζώνες όπως αυτές κάτω από τους καταλόγους posix/ και right/, ή τη ζώνη posixrules.

Προσοχή

Αυτή η συνάρτηση μπορεί να ανοίξει μεγάλο αριθμό αρχείων, καθώς ο καλύτερος τρόπος για να προσδιοριστεί, αν ένα αρχείο στη διαδρομή ζώνης ώρας είναι μια έγκυρη ζώνη ώρας, είναι να διαβαστεί η «μαγική συμβολοσειρά» στην αρχή.

Σημείωση

Αυτές οι τιμές δεν έχουν σχεδιαστεί για να εκτίθενται στους τελικούς χρήστες· για στοιχεία που απευθύνονται στον χρήστη, οι εφαρμογές θα πρέπει να χρησιμοποιούν κάτι σαν το CLDR (το Unicode Common Locale Data Repository) για να λάβουν πιο φιλικές προς τον χρήστη συμβολοσειρές. Δείτε επίσης τη σημείωση προσοχής στο ZoneInfo.key.

zoneinfo.reset_tzpath(to=None)

Ορίζει ή επαναφέρει τη διαδρομή αναζήτησης ζώνης ώρας (TZPATH) για το module. Όταν καλείται χωρίς ορίσματα, το TZPATH ορίζεται στην προεπιλεγμένη τιμή.

Η κλήση του reset_tzpath δεν θα ακυρώσει την προσωρινή μνήμη της ZoneInfo, και έτσι οι κλήσεις στον κύριο κατασκευαστή ZoneInfo θα χρησιμοποιούν τη νέα TZPATH μόνο σε περίπτωση απώλειας στην προσωρινή μνήμη.

Η παράμετρος to πρέπει να είναι μια sequence από συμβολοσειρές ή os.PathLike και όχι μια συμβολοσειρά, όπου όλα πρέπει να είναι απόλυτες διαδρομές. Θα γίνει raise το ValueError αν περαστεί κάτι άλλο εκτός από μια απόλυτη διαδρομή.

Καθολικές μεταβλητές

zoneinfo.TZPATH

Μια ακολουθία μόνο για ανάγνωση που αντιπροσωπεύει τη διαδρομή αναζήτησης ζώνης ώρας – κατά την κατασκευή ενός ZoneInfo από ένα κλειδί, το κλειδί συνδέεται με κάθε καταχώριση στο TZPATH, και χρησιμοποιείται το πρώτο αρχείο που βρέθηκε.

Το TZPATH μπορεί να περιέχει μόνο απόλυτες διαδρομές, ποτέ σχετικές διαδρομές, ανεξάρτητα από το πώς διαμορφώνεται.

Το αντικείμενο στο οποίο δείχνει το zoneinfo.TZPATH μπορεί να αλλάξει σε απόκριση σε μια κλήση στη reset_tzpath(), οπότε συνιστάται να χρησιμοποιείτε το zoneinfo.TZPATH αντί να εισάγετε το TZPATH από το zoneinfo ή να αναθέτετε μια μακροχρόνια μεταβλητή στο zoneinfo.TZPATH.

Για περισσότερες πληροφορίες σχετικά με τη διαμόρφωση της διαδρομής αναζήτησης ζώνης ώρας, δείτε Διαμόρφωση των πηγών δεδομένων.

Εξαιρέσεις και προειδοποιήσεις

exception zoneinfo.ZoneInfoNotFoundError

Γίνεται raise όταν η κατασκευή ενός αντικειμένου ZoneInfo αποτυγχάνει επειδή το καθορισμένο κλειδί δεν βρέθηκε στο σύστημα. Αυτή είναι μια υποκλάση της KeyError.

exception zoneinfo.InvalidTZPathWarning

Γίνεται raise όταν η PYTHONTZPATH περιέχει ένα μη έγκυρο στοιχείο που θα φιλτραριστεί, όπως μια σχετική διαδρομή.