آموزش

آموزش datetime پایتون

اینجا یاد می‌گیری چطور یک شیء datetime ایجاد کنی.

تاریخ انتشار:

15 شهریور 1405

پایتون

2 دقیقه

کاربرهای فینکا در چه شرکت‌هایی مشغول به کار هستند؟

کار کردن با تاریخ و زمان اولش ساده به نظر می‌رسه، اما وقتی پای فرمت‌ها، منطقه زمانی (Timezone) ، تغییر ساعت یا timestamp سیستم‌های مختلف بیاد وسط، قضیه فرق می‌کنه. اونجاست که دیگه نمی‌تونی زمان رو فقط به شکل یه رشته یا عدد صحیح ساده ذخیره کنی. ماژول datetime پایتون دقیقا برای همین ساخته شده تا کمکت کنه این متغیرها رو راحت و بدون دردسر مدیریت کنی.

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

کلاس‌های اصلی ماژول datetime در پایتون

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

کلاس date

وقتی فقط با یه تاریخ تقویمی کار داری و نمی‌خوای درگیر ساعت یا منطقه زمانی بشی، کلاس date دقیقاً همون چیزیه که به دردت می‌خوره. این کلاس سال، ماه و روز رو با همون ویژگی‌های آشنا نشون می‌ده.

ویژگی‌هاش اینا هستن:

year
month
day

و اینم متدهاش:

today()
fromisoformat()
replace()
isoformat()
weekday()
isoweekday()

این کد یه تاریخ تقویمی ساده برات می‌سازه. اگه یه تاریخ نامعتبر (مثلاً ۳۰ فوریه) بهش بدی، پایتون خطای ValueError بهت می‌ده.

کلاس time

بعضی وقت‌ها فقط زمان یا همون ساعت برامون مهمه؛ مثلا آلارمی که باید ساعت ۲:۳۰ بعدازظهر زنگ بخوره. در اینجور مواقع، کلاس time خیلی به کار میاد، چون ساعت، دقیقه، ثانیه و حتی (هرچند در این مثال مهم نیست) میکروثانیه یا اطلاعات منطقه زمانی رو ذخیره می‌کنه.

ویژگی‌هاش اینا هستن: hour، minute، second، microsecond، tzinfo

و متدهاش: replace() و isoformat()

14:30:15

این کد یه زمان (ساعت) می‌سازه که هیچ تاریخی بهش وصل نیست. اگه مقادیر نامعتبر (مثلاً hour=27) وارد کنی، بهت خطا می‌ده.

کلاس datetime

در دنیای واقعی، بیشتر وقت‌ها با ترکیبی از تاریخ و زمان سر و کار داریم و اینجاست که کلاس datetime وارد بازی می‌شه. این کلاس همه‌کاره‌ترین بخش این ماژوله و احتمالاً برای لاگ گرفتن، پردازش و هماهنگ‌سازی رویدادها بیشترین استفاده رو ازش می‌کنی.

ویژگی‌هاش (علاوه بر همه موارد بالا) شامل اینه: tzinfo

و متدهاش شامل این موارد می‌شن: now()، utcnow()، fromisoformat()، strptime()، strftime()، astimezone() این کلاس از محاسبات با timedelta هم پشتیبانی می‌کنه که جلوتر بیشتر درباره‌اش توضیح می‌دیم.

2025-03-01 14:30:00

این کد یه timestamp کامل همراه با تاریخ و ساعت برات می‌سازه.

کلاس timedelta

هر وقت خواستی زمان سپری‌شده رو اندازه بگیری یا یه timestamp رو ببری جلو یا عقب، timedelta بهترین انتخابه. این کلاس در واقع یه بازه زمانی رو نشون می‌ده، نه یه لحظه خاص رو.

ویژگی‌هاش اینا هستن: days، seconds، microseconds. از این کلاس معمولاً برای اعمال اختلاف زمانی، محاسبه فاصله زمانی و کارهای مربوط به زمان‌بندی استفاده می‌شه.

7 days, 3:00:00

این کد یه بازه زمانی ثابت رو نشون می‌ده. وقتی این مقدار رو به یه شیء datetime اضافه یا ازش کم کنی، تازه متوجه می‌شی چقدر کاربردیه.

کلاس tzinfo

کلاس tzinfo رابط کاربری پایتون برای کار با مناطق زمانیه. معمولاً خودت مستقیم اینا رو نمی‌سازی، ولی سیستم datetime هر وقت بخواد منطقه زمانی رو تنظیم یا تبدیل کنه، از همین کلاس استفاده می‌کنه.

کلاس timezone

کلاس timezone در واقع یه پیاده‌سازی داخلی از tzinfo برای اختلاف‌های زمانی ثابت نسبت به UTC (مثل UTC یا UTC+1) هست و برای کارهای ساده‌ای که تغییرات فصلی ساعت در اونا مهم نیست، خیلی به درد می‌خوره.

ساخت و دسترسی به اشیاء datetime در پایتون

حالا که با کلاس‌ها آشنا شدی، قدم بعدی اینه که یاد بگیری چطور ازشون نمونه بسازی. بسته به اینکه داده‌هات از کجا میان، پایتون چند تا راه جلو پات می‌ذاره: وارد کردن دستی، گرفتن زمان سیستم، استفاده از timestamp یا خوندن از روی متن.

استفاده از سازنده‌های کلاس

سازنده‌ها بهت این امکان رو می‌دن که کنترل کاملی روی مقادیری که می‌سازی داشته باشی. معمولاً این روش برای ساخت اشیاء تاریخ، زمان یا datetime، شفاف‌ترین و امن‌ترین راه (با کمترین احتمال خطا) به حساب میاد.

2025-03-01

این کد مستقیماً یه تاریخ تقویمی می‌سازه. اگه مقادیر نامعتبر بهش بدی، همون لحظه خطا می‌ده و این کار کمک می‌کنه اشتباهت رو زودتر متوجه بشی.

14:30:15

این کد فقط زمان (ساعت) رو مشخص می‌کنه. در مواقعی که به تاریخ نیازی نداری، می‌تونی ازش استفاده کنی.

2025-03-01 14:30:00

این کد یه timestamp کامل برات می‌سازه. اگه آرگومان tzinfo رو هم بهش پاس بدی، شیء تو نسبت به منطقه زمانی هم آگاه می‌شه (timezone-aware).

ساخت از روی timestamp

timestamp یونیکس (Unix Timestamps) در واقع تعداد ثانیه‌هایی رو نشون می‌ده که از ۱ ژانویه ۱۹۷۰ (به وقت UTC) گذشته و معمولاً در لاگ‌ها، APIها و سیستم‌عامل‌ها زیاد دیده می‌شه. پایتون خیلی راحت اون رو به اشیاء datetime تبدیل می‌کنه تا برای ما آدما قابل خوندن باشه.

datetime.datetime(2023, 11, 15, 1, 43, 20)
DeprecationWarning: datetime.datetime.utcfromtimestamp() is deprecated and scheduled for removal in a future version. Use timezone-aware objects to represent datetimes in UTC: datetime.datetime.fromtimestamp(timestamp, datetime.UTC).
datetime.datetime(2023, 11, 14, 22, 13, 20)

اولی timestamp رو به وقت محلی نشون می‌ده، در حالی که دومی اون رو بر اساس زمان UTC تفسیر می‌کنه.

متدهای کلاس برای گرفتن زمان حال

وقتی تاریخ یا زمان همین لحظه رو می‌خوای، پایتون یه سری ابزار ساده در اختیارت می‌ذاره. این متدها برای لاگ گرفتن، ردیابی رویدادها و پایپ‌لاین‌های آنی (real-time) خیلی ضروری هستن.

این کدها بسته به نیازت، زمان فعلی سیستم رو به وقت محلی یا UTC بهت برمی‌گردونن.

datetime.datetime(2023, 11, 15, 1, 43, 20)
DeprecationWarning: datetime.datetime.utcfromtimestamp() is deprecated and scheduled for removal in a future version. Use timezone-aware objects to represent datetimes in UTC: datetime.datetime.fromtimestamp(timestamp, datetime.UTC).
datetime.datetime(2023, 11, 14, 22, 13, 20)

این متدها timestamp یونیکس رو به اشیاء datetime تبدیل می‌کنن. موقع استخراج داده‌ها از APIها یا دیتابیس، خیلی ازشون استفاده می‌شه.

استخراج از روی رشته‌های متنی

در دنیای واقعی، اکثر دیتاست‌ها timestamp رو به‌صورت متنی ذخیره می‌کنن. پایتون ابزارهای خیلی خوبی داره که می‌تونن این متن‌ها رو به مقادیر ساختاریافته و استاندارد تبدیل کنن.

2025-03-01 14:30:00

متد strptime() یه رشته متنی رو می‌گیره و با استفاده از یه الگوی فرمت مشخص، اون رو به تاریخ تبدیل می‌کنه. اگه رشته کاملاً با الگو همخونی نداشته باشه، پایتون خطای ValueError می‌ده.

ValueError: time data 'not-a-date' does not match format '%Y-%m-%d'

اجرای این کد به خطا می‌خوره، چون متن ورودی با الگویی که براش تعریف کردیم مطابقت نداره.

datetime.datetime(2025, 3, 1, 14, 30)

رشته‌های دارای فرمت ISO 8601 خیلی راحت تبدیل می‌شن چون ساختارشون استاندارد و مشخصه. معمولاً این آسون‌ترین راه برای خوندن timestamp از APIها یا سیستم‌های داده مدرن به حساب میاد.

انجام محاسبات روی تاریخ‌ها

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

استفاده از timedelta برای محاسبات زمانی

کلاس timedelta برای نشون دادن دوره‌های زمانی ثابت مثل «۵ ساعت» یا «۲ هفته» عالیه. این مدل مقادیر برای زمان‌بندی، لاگ گرفتن یا حتی ساختن یه شمارش معکوس ساده خیلی کاربردی هستن.

2025-03-06 14:30:00

در این مثال، timestamp پنج روز به جلو برده می‌شه.

19800.0

اینجا، وقتی دو تا مقدار datetime رو از هم کم می‌کنی، یه شیء timedelta به دست میاد که می‌تونی اون رو به ثانیه، دقیقه یا روز تبدیل کنی.

محاسبات زمانی ثابت و محاسبات تقویمی

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

اینجاست که dateutil.relativedelta به دادمون می‌رسه و محاسبات «تقویمی» رو برامون مدیریت می‌کنه:

2025-02-28

این کد سناریوی غیرممکنِ «۳۱ فوریه» رو خیلی هوشمندانه مدیریت می‌کنه و تاریخ رو به شکل درستی تغییر می‌ده.

فرمت‌بندی و استخراج تاریخ‌ها

بحث فرمت‌بندی datetime همه‌جا مطرح می‌شه: APIها انتظار فرمت‌های خاصی رو دارن، کاربرها دوست دارن متن‌ها خوانا باشن و لاگ‌ها هم به timestamp یکدست نیاز دارن. پایتون هم از فرمت‌بندی‌های دلخواه و هم از استانداردهای رایج پشتیبانی می‌کنه.

فرمت‌بندی متون با strftime

متد strftime() بهت اجازه می‌ده با استفاده از کدهای از پیش‌تعریف‌شده، اشیاء datetime رو به رشته‌های متنی با فرمت دلخواه تبدیل کنی.

Saturday, March 01, 2025 at 14:30

این کد یه متن خوانا و مرتب شامل اسم روز هفته و اسم کامل ماه رو چاپ می‌کنه.

'2025-03-01T14:30:00'

این کد یه خروجی متنی شبیه به فرمت ISO تولید می‌کنه که برای ذخیره کردن در دیتابیس یا ارسال به APIها، فرمت خیلی مناسبیه.

استخراج تاریخ از متن با strptime

2025-03-01 14:30:00

این کد یه متن رو می‌گیره و به یه شیء datetime تبدیلش می‌کنه. اگه رشته و الگو کوچیک‌ترین مغایرتی با هم داشته باشن، برنامه خطا می‌ده.

کار با فرمت‌های ISO 8601 و RFC 3339

استاندارد ISO 8601 تمام ابهاماتی رو که در خیلی از فرمت‌های محلی تاریخ وجود داره، از بین می‌بره. پایتون هم به‌صورت پیش‌فرض از این فرمت پشتیبانی می‌کنه:

2025-03-01T14:30:00

این امن‌ترین و بهترین فرمت برای جابه‌جایی داده بین سیستم‌ها، APIها یا دیتابیس‌های مختلف به حساب میاد.

مدیریت مناطق زمانی

کار با مناطق زمانی معمولاً یکی از دردسرسازترین بخش‌های برنامه‌نویسیه. پایتون با جدا کردن اشیاء datetime ساده (Naive) از اشیاء آگاه به منطقه زمانی (Aware) و ارائه ابزارهای عالی برای مدیریتشون، خیلی بهمون کمک می‌کنه.

اشیاء datetime ساده و آگاه

یه datetime ساده، هیچ اطلاعاتی از منطقه زمانی در خودش نداره:

None

ولی یه datetime آگاه، اختلاف منطقه زمانی رو در خودش ذخیره می‌کنه:

2025-03-01 14:30:00+01:00

قاطی کردن مقادیر ساده و آگاه در محاسبات یا مقایسه‌ها، معمولاً باعث خطا می‌شه و بهتره از این کار پرهیز کنی.

استفاده از ماژول zoneinfo

ماژول zoneinfo در پایتون بهت اجازه می‌ده مستقیماً به مناطق زمانی استاندارد IANA دسترسی داشته باشی:

2025-03-01 14:30:00+01:00

تبدیل منطقه زمانی به همین سادگیه:

datetime.datetime(2025, 3, 1, 8, 30, tzinfo=zoneinfo.ZoneInfo(key='America/New_York'))

این کد دقیقاً همون لحظه رو در یه منطقه زمانی دیگه بهت نشون می‌ده.

تبدیل مناطق زمانی به همدیگه

با استفاده از متد astimezone() می‌تونی هر timestamp آگاهی رو به یه منطقه زمانی دیگه تبدیل کنی:

2025-03-01 08:30:00-05:00

یه روش استاندارد و خیلی رایج اینه که همیشه timestamp رو به شکل UTC ذخیره کنی و فقط وقتی خواستی به کاربر نشونش بدی، اون رو تبدیل کنی.

مقایسه و فیلتر کردن تاریخ‌ها

مقایسه کردن تاریخ‌ها در هر پروژه‌ای پیش میاد. از مرتب کردن لاگ‌ها و فیلتر کردن رویدادها گرفته تا اینکه بخوایم بفهمیم یه اتفاقی قبل از یه زمان خاص افتاده یا بعدش.

True

مقایسه‌هایی که روی تاریخ‌های آگاه به منطقه زمانی انجام می‌شن، اختلاف ساعت‌ها رو هم در نظر می‌گیرن:

True

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

[datetime.datetime(2025, 3, 1, 10, 0), datetime.datetime(2025, 3, 1, 8, 0)]

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

کاربردهای پیشرفته‌تر

ماژول datetime در خیلی از پروژه‌ها، فراتر از یه استخراج و محاسبه ساده کاربرد داره. اینجا چند تا از الگوهای رایج رو می‌بینی که احتمالاً زیاد باهاشون برخورد می‌کنی.

timestamp یونیکس

این timestamp در برنامه‌نویسی سیستم‌ها و APIها به شدت پرکاربرده.

2023-11-15 01:43:20

میلی‌ثانیه‌ها و میکروثانیه‌ها نیاز به تغییر مقیاس دارن تا درست محاسبه بشن:

زمان‌بندی و تایمرها

کتابخونه‌هایی مثل schedule برای اینکه بفهمن چه زمانی باید یه تسک رو اجرا کنن، به مقادیر datetime نیاز دارن. چه بخوای یه تابع هر چند ثانیه یه بار اجرا بشه، چه بخوای یه رویداد رو فقط یه بار برای آخر روز تنظیم کنی، این datetime هست که پایه و اساس کار رو برات فراهم می‌کنه.

الگوهای تحلیل داده

معمولاً ویژگی‌های مختلف datetime رو برای گروه‌بندی و تحلیل‌های زمانی استخراج می‌کنن:

2025
datetime.IsoCalendarDate(year=2025, week=9, weekday=6)

در کتابخونه pandas، نمونه‌برداری مجدد داده‌ها (Resampling) بر اساس بازه‌های زمانی کار به شدت رایجیه:

                     value
timestamp
2025-03-02     22
2025-03-09     15

نتیجه‌گیری

اگه می‌خوای درباره datetime بیشتر یاد بگیری، پیشنهاد می‌کنیم این ویدیو از دوره ما در فینکا رو ببینی: کار با تاریخ و زمان در پایتون و انواع داده برای علم داده در پایتون.

همچنین اگه برای تبدیل رشته‌ها به راهنمایی بیشتری نیاز داری، می‌تونی آموزش ما رو با عنوان تبدیل رشته‌ها به تاریخ به عنوان اشیاء datetime ببینی.