کتابخانه datetime در پایتون — راهنمای کامل و کاربردی

کتابخانه datetime یکی از مهم‌ترین ابزارها برای کار با تاریخ و زمان در پایتون است. این ماژول انواع داده‌ای استاندارد (مانند date، time، datetime، timedelta و tzinfo) را در اختیار می‌گذارد و به شما امکان محاسبات، قالب‌بندی، تبدیل timezone و پارس‌کردن رشته‌های تاریخ را می‌دهد. در این مقاله به مفاهیم پایه، نکات پیشرفته، مثال‌های عملی و اشتباهات رایج پرداخته شده است.

کلاس‌های اصلی و نقش آن‌ها

ایجاد و قالب‌بندی تاریخ/زمان

from datetime import datetime, date, time

d = date(2025, 10, 31)
t = time(14, 30, 15)
dt = datetime(2025, 10, 31, 14, 30, 15)

print(dt.isoformat())         # 2025-10-31T14:30:15
print(dt.strftime("%Y/%m/%d %H:%M"))  # 2025/10/31 14:30

کد بالا ابتدا نمونه‌هایی از date، time و datetime می‌سازد. متد isoformat() خروجی استاندارد ISO می‌دهد، و strftime برای قالب‌بندی دلخواه استفاده می‌شود. الگوهای رایج شامل %Y برای سال، %m برای ماه و %H برای ساعت هستند.

محاسبات زمانی با timedelta

from datetime import datetime, timedelta

now = datetime.now()
delta = timedelta(days=7, hours=3, minutes=30)
future = now + delta
past = now - timedelta(days=30)

print("حال:", now)
print("بعد از 7 روز و 3.5 ساعت:", future)
print("30 روز قبل:", past)

از timedelta برای جمع و تفریق تاریخ/زمان استفاده می‌شود. نتیجه عملیاتی مثل جمع یک timedelta با یک datetime، یک datetime جدید است. این روش برای محاسبه زمان انقضا، برنامه‌ریزی و گزارش‌گیری کاربردی است.

مفاهیم مهم: naive vs aware

• Naive: شیء datetime بدون اطلاعات منطقه زمانی (tzinfo=None). مثال: خروجی datetime.now() به صورت پیش‌فرض naive است.
• Aware: شیء datetime که شامل اطلاعات منطقه زمانی است (مثل UTC یا Europe/Tehran).

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

کار با مناطق زمانی (zoneinfo)

from datetime import datetime
from zoneinfo import ZoneInfo

utc = datetime.now(ZoneInfo("UTC"))
tehran = utc.astimezone(ZoneInfo("Asia/Tehran"))

print("UTC:", utc)
print("Tehran:", tehran)

در پایتون 3.9 به بعد، ماژول zoneinfo جایگزین پیشنهادی برای pytz است. کد بالا یک زمان UTC می‌سازد و سپس با astimezone آن را به منطقهٔ زمانی تهران تبدیل می‌کند. این روش به‌درستی تغییرات ساعت تابستانی (DST) را مدیریت می‌کند.

مثال پیشرفته: پارس دینامیک با strptime و dateutil

from datetime import datetime
from dateutil import parser

s1 = "2025-10-31 14:30:15"
t1 = datetime.strptime(s1, "%Y-%m-%d %H:%M:%S")

s2 = "Oct 31, 2025 2:30 PM"
t2 = parser.parse(s2)

print(t1)
print(t2)

strptime برای پارس‌کردن رشته‌های با فرمت مشخص مفید است. برای ورودی‌های آزاد یا فرمت‌های متنوع، کتابخانهٔ python-dateutil بسیار قدرتمند و منعطف است. توجه داشته باشید که dateutil.parser باید با احتیاط استفاده شود زیرا ممکن است در زبان‌ها یا قالب‌های مبهم دچار خطا شود.

تبدیل به/از timestamp و نکات دقت

from datetime import datetime, timezone

dt = datetime(2025, 10, 31, 14, 30, tzinfo=timezone.utc)
ts = dt.timestamp()  # seconds since epoch (float)
dt2 = datetime.fromtimestamp(ts, timezone.utc)

print(ts)
print(dt2)

تابع timestamp() تعداد ثانیه‌ها از epoch را برمی‌گرداند. برای جلوگیری از اشتباهات، بهتر است datetime شما آگاه به timezone (مثلاً UTC) باشد قبل از تبدیل به timestamp تا از اختلاف‌های منطقه‌ای جلوگیری شود.

نکات حرفه‌ای و اشتباهات رایج

• از استفاده هم‌زمان از datetime نا‌آگاه و آگاه خودداری کنید؛ یا همه را آگاه نگه دارید یا همه را نا‌آگاه، بسته به نیاز برنامه.
• برای برنامه‌های توزیع‌شده یا لاگ‌ها همیشه UTC را ذخیره کنید و برای نمایش محلی به منطقهٔ مناسب تبدیل کنید.
• برای مناطق زمانی از zoneinfo (Python 3.9+) استفاده کنید؛ اگر از نسخه‌های قدیمی‌تر استفاده می‌کنید، pytz راهکار معمول است اما باید localize را به‌درستی بکار ببرید.
• در عملیات حساس به دقت (مثلاً محاسبه اختلاف زمانی مالی)، از نوع دادهٔ مناسب و توجه به leap seconds و محدودیت‌های سیستم عامل آگاه باشید.

نمونه استفاده عملی: زمان‌بندی پیام‌ها با دقت منطقه‌ای

from datetime import datetime, timedelta
from zoneinfo import ZoneInfo

def schedule_in_local(dt_local, minutes_delay):
    # dt_local is timezone-aware
    utc = dt_local.astimezone(ZoneInfo("UTC"))
    run_at = utc + timedelta(minutes=minutes_delay)
    return run_at

local_dt = datetime(2025,10,31,9,0, tzinfo=ZoneInfo("Asia/Tehran"))
print(schedule_in_local(local_dt, 90))  # زمان اجرای پیام به UTC

در این الگو ابتدا زمان محلی آگاه به timezone را به UTC تبدیل می‌کنیم و سپس با timedelta زمان اجرای نهایی را محاسبه می‌کنیم. این روش برای سیستم‌هایی که وظایف زمان‌بندی‌شده را در UTC نگه می‌دارند مفید است.

خلاصه و منابع بیشتر

• برای برنامه‌های کوچک، توابع پایهٔ datetime کافی‌اند.
• برای مسائل پیچیده‌تر مانند پارس‌کردن هوشمند و مدیریت دقیق timezone از dateutil و zoneinfo استفاده کنید.
• همیشه قوانین منطقه‌ای و DST را در نظر بگیرید و داده‌ها را به صورت UTC ذخیره کنید.

با ترکیب این ابزارها و اصول می‌توانید برنامه‌هایی قابل‌اعتماد برای تاریخ و زمان بنویسید که مسائل مربوط به مناطق زمانی، قالب‌بندی و محاسبات را به‌درستی مدیریت کنند.

لطفاً از کمبود ها و مشکلات این محتوا برای ما بنویسید

ارسال