`zoneinfo` --- hỗ trợ múi giờ IANA¶

Added in version 3.9.

Mô-đun zoneinfo cung cấp triển khai múi giờ cụ thể để hỗ trợ cơ sở dữ liệu múi giờ IANA như được chỉ định ban đầu trong PEP 615. Theo mặc định, zoneinfo sử dụng dữ liệu múi giờ của hệ thống nếu có; nếu không có dữ liệu múi giờ của hệ thống, thư viện sẽ quay lại sử dụng gói tzdata của bên thứ nhất có sẵn trên PyPI.

Xem thêm

Mô-đun: datetime: Cung cấp các loại time và datetime mà lớp ZoneInfo được thiết kế để sử dụng.
Gói tzdata: Gói của bên thứ nhất được duy trì bởi các nhà phát triển cốt lõi của CPython để cung cấp dữ liệu múi giờ qua PyPI.

sẵn có: not WASI.

Mô-đun này không hoạt động hoặc không có trên WebAssembly. Xem Nền tảng WebAssugging để biết thêm thông tin.

Sử dụng `ZoneInfo`¶

ZoneInfo là một triển khai cụ thể của lớp cơ sở trừu tượng datetime.tzinfo và được dự định gắn vào tzinfo, thông qua hàm tạo, phương thức datetime.replace hoặc datetime.astimezone:

>>> từ nhập Zoneinfo ZoneInfo
>>> nhập ngày giờ dưới dạng dt

>>> khi = dt.datetime(2020, 10, 31, 12, tzinfo=ZoneInfo("America/Los_Angeles"))
>>> in (khi nào)
2020-10-31 12:00:00-07:00

>>> khi.tzname()
'PDT'

Ngày giờ được xây dựng theo cách này tương thích với số học ngày giờ và xử lý các chuyển đổi thời gian tiết kiệm ánh sáng ban ngày mà không cần can thiệp thêm:

>>> when_add = khi + dt.timedelta(ngày=1)

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

>>> When_add.tzname()
'PST'

Các múi giờ này cũng hỗ trợ thuộc tính fold được giới thiệu trong PEP 495. Trong quá trình chuyển đổi độ lệch tạo ra thời gian không rõ ràng (chẳng hạn như chuyển đổi thời gian tiết kiệm ánh sáng ban ngày sang chuyển đổi thời gian tiêu chuẩn), độ lệch từ before chuyển đổi được sử dụng khi fold=0 và độ lệch after chuyển tiếp được sử dụng khi fold=1, ví dụ:

>>> khi = dt.datetime(2020, 11, 1, 1, tzinfo=ZoneInfo("America/Los_Angeles"))
>>> in (khi nào)
2020-11-01 01:00:00-07:00

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

Khi chuyển đổi từ múi giờ khác, đường gấp sẽ được đặt thành giá trị đúng:

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

>>> # Before chuyển đổi PDT -> PST
>>> print(when_utc.astimezone(LOS_ANGELES))
2020-11-01 01:00:00-07:00

>>> # After chuyển đổi PDT -> PST
>>> print((when_utc + dt.timedelta(hours=1)).astimezone(LOS_ANGELES))
2020-11-01 01:00:00-08:00

Nguồn dữ liệu¶

Mô-đun zoneinfo không trực tiếp cung cấp dữ liệu múi giờ mà thay vào đó lấy thông tin múi giờ từ cơ sở dữ liệu múi giờ của hệ thống hoặc gói PyPI tzdata của bên thứ nhất, nếu có. Một số hệ thống, đặc biệt là hệ thống Windows, không có sẵn cơ sở dữ liệu IANA và do đó, đối với các dự án nhắm mục tiêu tương thích đa nền tảng yêu cầu dữ liệu múi giờ, bạn nên khai báo sự phụ thuộc vào tzdata. Nếu cả dữ liệu hệ thống và tzdata đều không có sẵn thì tất cả lệnh gọi tới ZoneInfo sẽ đưa ra ZoneInfoNotFoundError.

Định cấu hình nguồn dữ liệu¶

Khi ZoneInfo(key) được gọi, trước tiên, hàm tạo sẽ tìm kiếm trong các thư mục được chỉ định trong TZPATH để tìm tệp khớp với key và nếu thất bại sẽ tìm kiếm tệp khớp trong gói tzdata. Hành vi này có thể được cấu hình theo ba cách:

TZPATH mặc định khi không được chỉ định khác có thể được định cấu hình tại compile time.
TZPATH có thể được cấu hình bằng an environment variable.
Tại runtime, đường dẫn tìm kiếm có thể được thao tác bằng chức năng reset_tzpath().

Cấu hình thời gian biên dịch¶

Zz000zz mặc định bao gồm một số vị trí triển khai phổ biến cho cơ sở dữ liệu múi giờ (ngoại trừ trên Windows, nơi không có vị trí "nổi tiếng" cho dữ liệu múi giờ). Trên hệ thống POSIX, các nhà phân phối hạ nguồn và những người xây dựng Python từ nguồn biết dữ liệu múi giờ hệ thống của họ được triển khai ở đâu có thể thay đổi đường dẫn múi giờ mặc định bằng cách chỉ định tùy chọn thời gian biên dịch TZPATH (hoặc nhiều khả năng hơn là configure flag --with-tzpath), phải là một chuỗi được phân cách bằng os.pathsep.

Trên tất cả các nền tảng, giá trị được định cấu hình có sẵn dưới dạng khóa TZPATH trong sysconfig.get_config_var().

Cấu hình môi trường¶

Khi khởi tạo TZPATH (tại thời điểm nhập hoặc bất cứ khi nào reset_tzpath() được gọi mà không có đối số), mô-đun zoneinfo sẽ sử dụng biến môi trường PYTHONTZPATH, nếu nó tồn tại, để đặt đường dẫn tìm kiếm.

PYTHONTZPATH¶: Đây là một chuỗi được phân tách bằng os.pathsep chứa đường dẫn tìm kiếm múi giờ sẽ sử dụng. Nó phải chỉ bao gồm các đường dẫn tuyệt đối chứ không phải tương đối. Các thành phần tương đối được chỉ định trong PYTHONTZPATH sẽ không được sử dụng, nhưng mặt khác, hành vi khi đường dẫn tương đối được chỉ định sẽ được xác định theo cách triển khai; CPython sẽ đưa ra InvalidTZPathWarning, nhưng các cách triển khai khác có thể âm thầm bỏ qua thành phần bị lỗi hoặc đưa ra một ngoại lệ.

Để đặt hệ thống bỏ qua dữ liệu hệ thống và thay vào đó sử dụng gói tzdata, hãy đặt PYTHONTZPATH="".

Cấu hình thời gian chạy¶

Đường dẫn tìm kiếm TZ cũng có thể được cấu hình trong thời gian chạy bằng chức năng reset_tzpath(). Nói chung, đây không phải là một thao tác được khuyến khích, mặc dù sẽ hợp lý khi sử dụng nó trong các chức năng kiểm tra yêu cầu sử dụng đường dẫn múi giờ cụ thể (hoặc yêu cầu vô hiệu hóa quyền truy cập vào múi giờ của hệ thống).

Lớp `ZoneInfo`¶

class zoneinfo.ZoneInfo(key)¶

Một lớp con datetime.tzinfo cụ thể đại diện cho múi giờ IANA được chỉ định bởi chuỗi key. Các cuộc gọi đến hàm tạo chính sẽ luôn trả về các đối tượng so sánh giống hệt nhau; nói cách khác, chặn việc vô hiệu hóa bộ đệm thông qua ZoneInfo.clear_cache(), đối với tất cả các giá trị của key, xác nhận sau sẽ luôn đúng:

a = ZoneInfo(key)
b = ZoneInfo(key)
khẳng định a là b

key phải ở dạng đường dẫn POSIX tương đối, được chuẩn hóa, không có tham chiếu cấp cao hơn. Hàm tạo sẽ tăng ValueError nếu khóa không tuân thủ được truyền.

Nếu không tìm thấy tệp nào khớp với key, hàm tạo sẽ tăng ZoneInfoNotFoundError.

Lớp ZoneInfo có hai hàm tạo thay thế:

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

Xây dựng đối tượng ZoneInfo từ đối tượng giống tệp trả về byte (ví dụ: tệp được mở ở chế độ nhị phân hoặc đối tượng io.BytesIO). Không giống như hàm tạo chính, hàm này luôn tạo một đối tượng mới.

Tham số key đặt tên của vùng cho mục đích của __str__() và __repr__().

Các đối tượng được tạo thông qua hàm tạo này không thể được chọn (xem pickling).

ValueError được nâng lên nếu dữ liệu đọc từ file_obj không phải là tệp TZif hợp lệ.

classmethod ZoneInfo.no_cache(key)¶

Một hàm tạo thay thế bỏ qua bộ đệm của hàm tạo. Nó giống với hàm tạo chính nhưng trả về một đối tượng mới trong mỗi lệnh gọi. Điều này rất có thể hữu ích cho mục đích thử nghiệm hoặc trình diễn, nhưng nó cũng có thể được sử dụng để tạo một hệ thống có chiến lược vô hiệu hóa bộ đệm khác.

Các đối tượng được tạo thông qua hàm tạo này cũng sẽ bỏ qua bộ đệm của quá trình giải tuần tự hóa khi được giải nén.

Cảnh báo

Việc sử dụng hàm tạo này có thể thay đổi ngữ nghĩa của thời gian dữ liệu của bạn theo những cách đáng ngạc nhiên, chỉ sử dụng nó nếu bạn biết rằng mình cần phải làm vậy.

Các phương thức lớp sau đây cũng có sẵn:

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

Một phương pháp vô hiệu hóa bộ đệm trên lớp ZoneInfo. Nếu không có đối số nào được chuyển, tất cả bộ đệm sẽ bị vô hiệu và lệnh gọi tiếp theo tới hàm tạo chính cho mỗi khóa sẽ trả về một phiên bản mới.

Nếu một lần lặp các tên khóa được chuyển đến tham số only_keys, chỉ các khóa được chỉ định sẽ bị xóa khỏi bộ đệm. Các khóa được chuyển tới only_keys nhưng không tìm thấy trong bộ đệm sẽ bị bỏ qua.

Cảnh báo

Việc gọi hàm này có thể thay đổi ngữ nghĩa của datetimes bằng cách sử dụng ZoneInfo theo những cách đáng ngạc nhiên; điều này sửa đổi trạng thái mô-đun và do đó có thể có tác dụng trên phạm vi rộng. Chỉ sử dụng nó nếu bạn biết rằng bạn cần.

Lớp có một thuộc tính:

ZoneInfo.key¶

Đây là attribute chỉ đọc, trả về giá trị của key được truyền cho hàm tạo. Giá trị này phải là khóa tra cứu trong cơ sở dữ liệu múi giờ IANA (ví dụ: America/New_York, Europe/Paris hoặc Asia/Tokyo).

Đối với các vùng được tạo từ tệp mà không chỉ định tham số key, tham số này sẽ được đặt thành None.

Ghi chú

Mặc dù việc hiển thị những giá trị này cho người dùng cuối là một thông lệ khá phổ biến, nhưng các giá trị này được thiết kế làm khóa chính để thể hiện các vùng có liên quan và không nhất thiết là các phần tử hướng tới người dùng. Các dự án như CLDR (Kho lưu trữ dữ liệu ngôn ngữ chung Unicode) có thể được sử dụng để nhận các chuỗi thân thiện hơn với người dùng từ các khóa này.

Biểu diễn chuỗi¶

Biểu diễn chuỗi được trả về khi gọi str trên đối tượng ZoneInfo mặc định sử dụng thuộc tính ZoneInfo.key (xem ghi chú về cách sử dụng trong tài liệu thuộc tính):

>>> vùng = ZoneInfo("Pacific/Kwajalein")
>>> str(vùng)
'Thái Bình Dương/Kwajalein'

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

Đối với các đối tượng được tạo từ một tệp mà không chỉ định tham số key, str sẽ quay lại gọi repr(). Zz004zz của ZoneInfo được xác định theo triển khai và không nhất thiết phải ổn định giữa các phiên bản, nhưng nó được đảm bảo không phải là khóa ZoneInfo hợp lệ.

Tuần tự hóa dưa chua¶

Thay vì tuần tự hóa tất cả dữ liệu chuyển tiếp, các đối tượng ZoneInfo được tuần tự hóa theo khóa và các đối tượng ZoneInfo được xây dựng từ các tệp (ngay cả những đối tượng có giá trị cho key được chỉ định) không thể được chọn.

Hoạt động của tệp ZoneInfo phụ thuộc vào cách nó được tạo:

ZoneInfo(key): Khi được xây dựng bằng hàm tạo chính, một đối tượng ZoneInfo được tuần tự hóa theo khóa và khi được giải tuần tự hóa, quá trình giải tuần tự hóa sẽ sử dụng đối tượng chính và do đó dự kiến rằng đây là cùng một đối tượng với các tham chiếu khác trong cùng một múi giờ. Ví dụ: nếu europe_berlin_pkl là một chuỗi chứa một phần tử được xây dựng từ ZoneInfo("Europe/Berlin"), thì người ta sẽ mong đợi hành vi sau:
```
>>> a = ZoneInfo("Châu Âu/Berlin")
>>> b = dưa chua.loads(europe_berlin_pkl)
>>> a là b
đúng
```
ZoneInfo.no_cache(key): Khi được xây dựng từ hàm tạo bỏ qua bộ đệm, đối tượng ZoneInfo cũng được tuần tự hóa theo khóa, nhưng khi được giải tuần tự hóa, quá trình giải tuần tự hóa sẽ sử dụng hàm tạo bỏ qua bộ đệm. Nếu europe_berlin_pkl_nc là một chuỗi chứa một phần tử dưa được xây dựng từ ZoneInfo.no_cache("Europe/Berlin"), thì người ta sẽ mong đợi hành vi sau:
```
>>> a = ZoneInfo("Châu Âu/Berlin")
>>> b = dưa chua.loads(europe_berlin_pkl_nc)
>>> a là b
sai
```
ZoneInfo.from_file(file_obj, /, key=None): Khi được xây dựng từ một tệp, đối tượng ZoneInfo sẽ đưa ra một ngoại lệ đối với việc tẩy. Nếu người dùng cuối muốn chọn một ZoneInfo được tạo từ một tệp, họ nên sử dụng loại trình bao bọc hoặc chức năng tuần tự hóa tùy chỉnh: tuần tự hóa theo khóa hoặc lưu trữ nội dung của đối tượng tệp và tuần tự hóa nội dung đó.

Phương pháp tuần tự hóa này yêu cầu dữ liệu múi giờ cho khóa được yêu cầu phải có sẵn ở cả phía tuần tự hóa và giải tuần tự hóa, tương tự như cách mà các tham chiếu đến các lớp và hàm dự kiến sẽ tồn tại trong cả môi trường tuần tự hóa và giải tuần tự hóa. Điều đó cũng có nghĩa là không có đảm bảo nào được đưa ra về tính nhất quán của kết quả khi giải nén ZoneInfo được chọn trong môi trường có phiên bản dữ liệu múi giờ khác.

Chức năng¶

zoneinfo.available_timezones()¶

Nhận một bộ chứa tất cả các khóa hợp lệ cho múi giờ IANA có sẵn ở bất kỳ đâu trên đường dẫn múi giờ. Điều này được tính toán lại trên mỗi lần gọi hàm.

Chức năng này chỉ bao gồm tên vùng chuẩn và không bao gồm các vùng "đặc biệt" chẳng hạn như các vùng trong thư mục posix/ và right/ hoặc vùng posixrules.

Cảnh báo

Hàm này có thể mở một số lượng lớn tệp, vì cách tốt nhất để xác định xem tệp trên đường dẫn múi giờ có phải là múi giờ hợp lệ hay không là đọc "chuỗi ma thuật" ở đầu.

Ghi chú

Những giá trị này không được thiết kế để hiển thị cho người dùng cuối; đối với các thành phần hướng tới người dùng, các ứng dụng nên sử dụng thứ gì đó như CLDR (Kho lưu trữ dữ liệu ngôn ngữ chung Unicode) để có được các chuỗi thân thiện với người dùng hơn. Xem thêm ghi chú cảnh báo trên ZoneInfo.key.

zoneinfo.reset_tzpath(to=None)¶

Đặt hoặc đặt lại đường dẫn tìm kiếm múi giờ (TZPATH) cho mô-đun. Khi được gọi không có đối số, TZPATH được đặt thành giá trị mặc định.

Việc gọi reset_tzpath sẽ không làm mất hiệu lực bộ đệm ZoneInfo và do đó các lệnh gọi tới hàm tạo ZoneInfo chính sẽ chỉ sử dụng TZPATH mới trong trường hợp thiếu bộ đệm.

Tham số to phải là sequence của chuỗi hoặc os.PathLike chứ không phải chuỗi, tất cả đều phải là đường dẫn tuyệt đối. ValueError sẽ được nâng lên nếu có thứ gì đó không phải là đường dẫn tuyệt đối được thông qua.

Quả cầu¶

zoneinfo.TZPATH¶

Một chuỗi chỉ đọc biểu thị đường dẫn tìm kiếm múi giờ -- khi tạo ZoneInfo từ một khóa, khóa đó sẽ được nối với mỗi mục trong TZPATH và tệp đầu tiên tìm thấy sẽ được sử dụng.

TZPATH chỉ có thể chứa đường dẫn tuyệt đối, không bao giờ chứa đường dẫn tương đối, bất kể nó được định cấu hình như thế nào.

Đối tượng mà zoneinfo.TZPATH trỏ tới có thể thay đổi để phản hồi lệnh gọi tới reset_tzpath(), vì vậy, bạn nên sử dụng zoneinfo.TZPATH thay vì nhập TZPATH từ zoneinfo hoặc gán một biến tồn tại lâu dài cho zoneinfo.TZPATH.

Để biết thêm thông tin về cách định cấu hình đường dẫn tìm kiếm múi giờ, hãy xem Định cấu hình nguồn dữ liệu.

Ngoại lệ và cảnh báo¶

exception zoneinfo.ZoneInfoNotFoundError¶: Xảy ra khi việc xây dựng đối tượng ZoneInfo không thành công do không thể tìm thấy khóa được chỉ định trên hệ thống. Đây là một lớp con của KeyError.

exception zoneinfo.InvalidTZPathWarning¶: Xảy ra khi PYTHONTZPATH chứa thành phần không hợp lệ sẽ bị lọc ra, chẳng hạn như đường dẫn tương đối.

`zoneinfo` --- hỗ trợ múi giờ IANA¶

Sử dụng `ZoneInfo`¶

Nguồn dữ liệu¶

Định cấu hình nguồn dữ liệu¶

Cấu hình thời gian biên dịch¶

Cấu hình môi trường¶

Cấu hình thời gian chạy¶

Lớp `ZoneInfo`¶

Biểu diễn chuỗi¶

Tuần tự hóa dưa chua¶

Chức năng¶

Quả cầu¶

Ngoại lệ và cảnh báo¶

Table of Contents

Chủ đề trước

Chủ đề tiếp

Trang này

zoneinfo --- hỗ trợ múi giờ IANA¶

Sử dụng ZoneInfo¶

Nguồn dữ liệu¶

Định cấu hình nguồn dữ liệu¶

Cấu hình thời gian biên dịch¶

Cấu hình môi trường¶

Cấu hình thời gian chạy¶

Lớp ZoneInfo¶

Biểu diễn chuỗi¶

Tuần tự hóa dưa chua¶

Chức năng¶

Quả cầu¶

Ngoại lệ và cảnh báo¶

`zoneinfo` --- hỗ trợ múi giờ IANA¶

Sử dụng `ZoneInfo`¶

Lớp `ZoneInfo`¶