مدیریت مناطق زمانی با zoneinfo در پایتون

مدیریت زمان در برنامه‌نویسی بدون در نظر گرفتن مناطق زمانی (Time Zones) ناقص است. تا قبل از پایتون ۳.۹، برنامه‌نویسان مجبور بودند از کتابخانه‌های خارجی مانند pytz استفاده کنند. اما با معرفی ماژول استاندارد zoneinfo، پایتون اکنون به صورت بومی از پایگاه داده IANA Time Zone پشتیبانی می‌کند.

در این مقاله، از مفاهیم اولیه تا پیچیده‌ترین نکات فنی کار با zoneinfo را بررسی می‌کنیم.

سطح مقدماتی (Beginner Level)

در این بخش، یاد می‌گیریم چگونه ساعت‌های "ناآگاه" (Naive) را به ساعت‌های "آگاه" (Aware) تبدیل کنیم و چگونه زمان را بین کشورهای مختلف تبدیل کنیم.

۱. مفهوم Time Zone Aware vs Naive

در پایتون، اشیاء datetime به دو دسته تقسیم می‌شوند:

1. Naive (ناآگاه): زمانی که هیچ اطلاعاتی از منطقه زمانی ندارد (مثلاً ساعت ۱۰ صبح، اما ۱۰ صبح کجا؟).
2. Aware (آگاه): زمانی که دقیقاً می‌داند متعلق به کدام منطقه جغرافیایی است (مثلاً ساعت ۱۰ صبح به وقت تهران).

برای استفاده از zoneinfo، باید آن را از کتابخانه استاندارد ایمپورت کنید (پایتون ۳.۹+).

مثال اول: ایجاد یک زمان آگاه (Aware)

در این مثال، یک زمان مشخص را با منطقه زمانی «آسیا/تهران» می‌سازیم.

مثال دوم: دریافت زمان جاری در یک منطقه خاص

چگونه بفهمیم همین الان در نیویورک ساعت چند است؟

۲. تبدیل مناطق زمانی (Converting Time Zones)

یکی از رایج‌ترین کارها، تبدیل زمان از یک منطقه به منطقه دیگر است (مثلاً سرور در لندن است و کاربر در توکیو). برای این کار از متد astimezone() استفاده می‌کنیم.

مثال اول: تبدیل UTC به زمان محلی

بسیاری از دیتابیس‌ها زمان را به صورت UTC ذخیره می‌کنند. ما باید آن را برای نمایش به کاربر تبدیل کنیم.

مثال دوم: تبدیل مستقیم بین دو شهر

تبدیل زمان از لس‌آنجلس به سیدنی.

سطح پیشرفته (Professional Level)

در این بخش به مباحث عمیق‌تر مانند مدیریت تغییر ساعت تابستانی (DST)، رفع ابهام در زمان‌های تکراری (Fold)، کشینگ و بهترین روش‌های معماری نرم‌افزار می‌پردازیم.

۱. مدیریت ابهام زمانی (Ambiguous Times & The fold Attribute)

زمانی که ساعت‌ها در پایان تابستان یک ساعت به عقب کشیده می‌شوند (DST ending)، یک بازه زمانی خاص (مثلاً ۱:۰۰ تا ۲:۰۰ بامداد) دو بار تکرار می‌شود. پایتون با استفاده از ویژگی fold این ابهام را حل می‌کند:

• fold=0: اولین وقوع زمان (قبل از عقب کشیدن ساعت).
• fold=1: دومین وقوع زمان (بعد از عقب کشیدن ساعت).

نکته: از آنجا که ایران قانون تغییر ساعت را لغو کرده است، برای درک این مثال از منطقه زمانی America/New_York استفاده می‌کنیم که همچنان تغییر ساعت دارد.

مثال اول: تشخیص زمان مبهم (Ambiguous Time)

در این مثال می‌بینیم که zoneinfo چگونه به صورت پیش‌فرض با این موضوع برخورد می‌کند.

مثال دوم: ساختار منطقی (Snippet)

زمانی که کاربر یک زمان مبهم را وارد می‌کند، شما باید تصمیم بگیرید کدام fold را انتخاب کنید. معمولاً fold=0 پیش‌فرض است.

# Static Snippet: Logic for handling user input ambiguity
def resolve_ambiguity(dt_input, zone_name):
    tz = ZoneInfo(zone_name)
    # اگر زمان مبهم باشد، ممکن است نیاز به پرسش از کاربر باشد
    # اما به طور پیش‌فرض پایتون اولین وقوع را در نظر می‌گیرد
    aware_dt = dt_input.replace(tzinfo=tz)
    return aware_dt

۲. دسترسی به لیست مناطق زمانی (Available Timezones)

ماژول zoneinfo متدی برای لیست کردن تمام مناطق زمانی موجود در سیستم (IANA database) دارد. این برای ساختن منوی انتخاب (Dropdown) در رابط کاربری بسیار مفید است.

مثال: دریافت تمام مناطق زمانی معتبر

۳. عملکرد و کشینگ (Caching & Performance)

کلاس ZoneInfo به گونه‌ای طراحی شده است که اشیاء را کش (Cache) می‌کند. این یعنی اگر چندین بار ZoneInfo("Asia/Tehran") را فراخوانی کنید، پایتون شیء جدیدی نمی‌سازد، بلکه همان نمونه قبلی را برمی‌گرداند. این کار باعث افزایش سرعت و کاهش مصرف حافظه می‌شود.

مثال اول: بررسی کشینگ با عملگر is

مثال دوم: پاک کردن کش (Snippet)

در برنامه‌هایی که طولانی‌مدت اجرا می‌شوند (Long-running)، اگر دیتابیس IANA سیستم عامل آپدیت شود، ممکن است نیاز داشته باشید کش را خالی کنید تا قوانین جدید اعمال شوند.

# Static Code: Clearing the cache
from zoneinfo import ZoneInfo

# متد clear_cache کش داخلی را پاک می‌کند
ZoneInfo.clear_cache()

۴. بهترین روش ذخیره‌سازی (Best Practices)

یک قانون طلایی در مهندسی نرم‌افزار برای کار با زمان وجود دارد:

"همیشه به صورت UTC ذخیره کنید، همیشه به صورت Local نمایش دهید."

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

مثال کاربردی: معماری صحیح ذخیره و نمایش

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