استفاده از 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'

اشیای datetime ساخته‌شده به این روش، با محاسبات datetime سازگار هستند و تغییرهای ساعت تابستانی را بدون هیچ‌گونه مداخله‌ی بیشتر مدیریت می‌کنند:

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

منابع داده¶

ماژول zoneinfo داده‌های منطقه زمانی را مستقیماً ارائه نمی‌دهد و در عوض، در صورت دسترسی‌پذیری، اطلاعات منطقه زمانی را از پایگاه داده‌ی منطقه زمانی سیستم یا بسته‌ی شخص اول PyPI یعنی tzdata دریافت می‌کند. برخی سیستم‌ها، از جمله به‌ویژه سیستم‌های ویندوزی، پایگاه داده‌ی IANA را در دسترس ندارند، بنابراین برای پروژه‌هایی که سازگاری بین‌سکویی را هدف قرار می‌دهند و به داده‌های منطقه زمانی نیاز دارند، توصیه می‌شود وابستگی به tzdata را اعلام کنید. اگر هیچ‌کدام از داده‌های سیستمی و tzdata در دسترس نباشند، همه فراخوانی‌های ZoneInfo استثنای ZoneInfoNotFoundError را پرتاب می‌کنند.

کلاس 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 نسبی و نرمال‌شده، بدون هیچ ارجاعی به سطح بالاتر باشد. سازنده در صورت ارسال یک کلید نامنطبق، ValueError را پرتاب می‌کند.

اگر هیچ پرونده‌ای مطابق key یافت نشود، سازنده استثنا ZoneInfoNotFoundError را پرتاب خواهد کرد.

کلاس ZoneInfo دو سازنده جایگزین دارد:

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

یک شیء ZoneInfo را از یک شیء شبه‌پرونده که بایت برمی‌گرداند می‌سازد (مثلاً پرونده‌ای که در حالت دودویی باز شده است یا یک شیء io.BytesIO). برخلاف سازنده‌ی اصلی، این همیشه یک شیء جدید می‌سازد.

پارامتر key نام منطقه را برای اهداف __str__() و __repr__() تنظیم می‌کند.

اشیای ایجادشده از طریق این سازنده را نمی‌توان پیکل کرد (به pickling مراجعه کنید).

اگر داده‌ی خوانده‌شده از file_obj یک پرونده TZif معتبر نباشد، استثنای ValueError پرتاب می‌شود.

classmethod ZoneInfo.no_cache(key)¶

سازنده جایگزینی که نهانگاه سازنده را دور می‌زند. این سازنده با سازنده اصلی یکسان است، اما در هر فراخوانی یک شیء جدید برمی‌گرداند. این به احتمال زیاد برای آزمون یا اهداف نمایشی مفید است، اما می‌توان از آن برای ایجاد سیستمی با راهبرد متفاوت برای ابطال نهانگاه نیز استفاده کرد.

اشیایی که از طریق این سازنده ایجاد می‌شوند، هنگام بازگردانی از pickle نیز نهانگاه یک فرایند سریال‌زدایی را دور می‌زنند.

احتیاط

استفاده از این سازنده ممکن است معنای datetimeهای شما را به‌شکل‌های غافلگیرکننده‌ای تغییر دهد؛ فقط در صورتی از آن استفاده کنید که می‌دانید به آن نیاز دارید.

متدهای کلاس زیر نیز در دسترس هستند:

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

متدی برای نامعتبر کردن نهانگاه در کلاس ZoneInfo. اگر هیچ آرگومانی ارسال نشود، همه نهانگاه‌ها نامعتبر می‌شوند و فراخوانی بعدی سازنده اصلی برای هر کلید، یک نمونه جدید را برمی‌گرداند.

اگر یک پیمایش‌پذیر از نام‌های کلید به پارامتر only_keys ارسال شود، فقط کلیدهای مشخص‌شده از نهانگاه حذف می‌شوند. کلیدهایی که به only_keys ارسال شده‌اند اما در نهانگاه یافت نمی‌شوند، نادیده گرفته می‌شوند.

هشدار

فراخوانی این تابع ممکن است معناشناسی datetimeهایی که از ZoneInfo استفاده می‌کنند را به‌شکل‌های غیرمنتظره‌ای تغییر دهد؛ این کار وضعیت ماژول را تغییر می‌دهد و بنابراین ممکن است اثرات گسترده‌ای داشته باشد. تنها در صورتی از آن استفاده کنید که می‌دانید به آن نیاز دارید.

این کلاس یک ویژگی دارد:

ZoneInfo.key¶

این یک ویژگی فقط‌خواندنی است که مقدار key داده‌شده به سازنده را برمی‌گرداند؛ این مقدار باید یک کلید جستجو در پایگاه داده‌ی مناطق زمانی IANA باشد (مثلاً America/New_York، Europe/Paris یا Asia/Tokyo).

برای منطقه‌هایی که از پرونده بدون مشخص کردن پارامتر key ساخته شده‌اند، این مقدار روی None تنظیم خواهد شد.

نکته

اگرچه تا حدی رایج است که این موارد به کاربران نهایی نمایش داده شوند، این مقادیر به‌عنوان کلیدهای اصلی برای بازنمایی مناطق مربوطه طراحی شده‌اند و لزوماً عناصر قابل‌نمایش برای کاربر نیستند. می‌توان از پروژه‌هایی مانند CLDR (Unicode Common Locale Data Repository) برای دریافت رشته‌های کاربرپسندتر از این کلیدها استفاده کرد.

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

توابع¶

zoneinfo.available_timezones()¶

مجموعه‌ای شامل تمام کلیدهای معتبر برای مناطق زمانی IANA موجود در هر نقطه از مسیر مناطق زمانی دریافت کنید. این مجموعه در هر فراخوانی تابع دوباره محاسبه می‌شود.

این تابع فقط شامل نام‌های مناطق کانونیکال است و شامل مناطق «خاص» مانند مناطق موجود در پوشه‌های posix/ و right/، یا مناطق posixrules و localtime نمی‌شود.

احتیاط

این تابع ممکن است تعداد زیادی پرونده را باز کند، زیرا بهترین راه برای تشخیص اینکه آیا یک پرونده در مسیر منطقه زمانی، یک منطقه زمانی معتبر است، خواندن «رشته جادویی» (magic string) در ابتدای آن است.

نکته

این مقادیر برای ارائه به کاربران نهایی طراحی نشده‌اند؛ برای عناصر رو به کاربر، برنامه‌ها باید برای دریافت رشته‌های کاربرپسندتر از چیزی مانند CLDR (مخزن مشترک داده‌های locale یونیکد) استفاده کنند. همچنین یادداشت هشداردهنده درباره‌ی ZoneInfo.key را ببینید.

zoneinfo.reset_tzpath(to=None)¶

مسیر جستجوی منطقه‌ی زمانی (TZPATH) را برای ماژول تنظیم یا بازنشانی می‌کند. وقتی بدون آرگومان فراخوانی شود، TZPATH به مقدار پیش‌فرض تنظیم می‌شود.

فراخوانی reset_tzpath نهانگاه ZoneInfo را بی‌اعتبار نمی‌کند، بنابراین فراخوانی‌های سازنده اصلی ZoneInfo تنها در صورتی از TZPATH جدید استفاده خواهند کرد که مورد درخواستی در نهانگاه یافت نشود.

پارامتر to باید یک دنباله از رشته‌ها یا os.PathLike باشد، نه یک رشته، و همه‌ی آن‌ها باید مسیرهای مطلق باشند. اگر چیزی غیر از مسیر مطلق ارسال شود، ValueError پرتاب خواهد شد.

سراسری‌ها¶

zoneinfo.TZPATH¶

یک دنباله فقط خواندنی که نشان‌دهنده‌ی مسیر جستجوی منطقه زمانی است -- هنگام ساخت یک ZoneInfo از یک کلید، کلید به هر ورودی در TZPATH پیوست می‌شود، و اولین پرونده یافت‌شده استفاده می‌شود.

TZPATH می‌تواند فقط شامل مسیرهای مطلق باشد و هرگز شامل مسیرهای نسبی نمی‌شود، صرف‌نظر از این‌که چگونه پیکربندی شده باشد.

شیءای که zoneinfo.TZPATH به آن اشاره می‌کند ممکن است در پاسخ به فراخوانی reset_tzpath() تغییر کند، بنابراین توصیه می‌شود به‌جای ایمپورت کردن TZPATH از zoneinfo یا انتساب یک متغیر با طول عمر زیاد به zoneinfo.TZPATH، از zoneinfo.TZPATH استفاده کنید.

برای اطلاعات بیشتر درباره‌ی پیکربندی مسیر جستجوی منطقه زمانی، پیکربندی منابع داده را ببینید.

استثناها و هشدارها¶

exception zoneinfo.ZoneInfoNotFoundError¶

زمانی پرتاب می‌شود که ساخت یک شیء ZoneInfo شکست بخورد، زیرا کلید مشخص‌شده در سیستم یافت نشد. این یک زیرکلاس از KeyError است.

exception zoneinfo.InvalidTZPathWarning¶

هنگامی که PYTHONTZPATH شامل یک کامپوننت نامعتبر باشد که حذف خواهد شد، مانند یک مسیر نسبی، پرتاب می‌شود.