شیءهای DateTime¶

اشیاء مختلف تاریخ و زمان توسط ماژول datetime فراهم می‌شوند. پیش از استفاده از هر یک از این توابع، پرونده‌ی سرآیند datetime.h باید در کد منبع شما گنجانده شود (توجه داشته باشید که این پرونده توسط Python.h گنجانده نمی‌شود) و ماکروی PyDateTime_IMPORT باید فراخوانی شود، که معمولاً به عنوان بخشی از تابع مقداردهی اولیه ماژول انجام می‌شود. این ماکرو یک اشاره‌گر به یک ساختار C را در یک متغیر ایستا، PyDateTimeAPI، قرار می‌دهد که توسط ماکروهای زیر استفاده می‌شود.

PyDateTime_IMPORT¶

ایمپورت کردن C API مربوط به datetime.

در صورت موفقیت، اشاره‌گر PyDateTimeAPI را پر می‌کند. در صورت شکست، PyDateTimeAPI را برابر NULL قرار می‌دهد و یک استثنا تنظیم می‌کند. فراخوان‌کننده باید از طریق PyErr_Occurred() بررسی کند که آیا خطایی رخ داده است:

PyDateTime_IMPORT;
if (PyErr_Occurred()) { /* cleanup */ }

هشدار

این با زیرمفسر‌ها سازگار نیست.

تغییر یافته در نسخه‌ی 3.15: این ماکرو اکنون نخ‌ایمن (thread-safe) است.

type PyDateTime_CAPI¶

ساختار شامل فیلدهای C API مربوط به datetime.

فیلد‌های این ساختار خصوصی هستند و ممکن است تغییر کنند.

از این مستقیماً استفاده نکنید؛ به‌جای آن، API‌های PyDateTime_* را ترجیح دهید.

PyDateTime_CAPI *PyDateTimeAPI¶

شیء تخصیص‌یافته به‌صورت پویا که C API مربوط به datetime را در بر می‌گیرد.

این متغیر تنها پس از موفقیت PyDateTime_IMPORT در دسترس است.

تغییر یافته در نسخه‌ی 3.15: به این متغیر نباید به‌طور مستقیم دسترسی پیدا کرد؛ زیرا دسترسی مستقیم نخ‌ایمن نیست. به‌جای آن از PyDateTime_IMPORT() استفاده کنید.

type PyDateTime_Date¶

این زیرنوع از PyObject یک شیء تاریخ پایتون را نمایندگی می‌کند.

type PyDateTime_DateTime¶

این زیرنوع از PyObject نمایانگر یک شیء datetime پایتون است.

type PyDateTime_Time¶

این زیرنوع از PyObject نمایانگر یک شیء زمان پایتون است.

type PyDateTime_Delta¶

این زیرنوع از PyObject تفاوت میان دو مقدار datetime را نشان می‌دهد.

PyTypeObject PyDateTime_DateType¶

این نمونه از PyTypeObject نوع تاریخ پایتون را نمایندگی می‌کند؛ این همان شیء datetime.date در لایه‌ی پایتون است.

PyTypeObject PyDateTime_DateTimeType¶

این نمونه از PyTypeObject نمایانگر نوع datetime پایتون است؛ این همان شیء datetime.datetime در لایه‌ی پایتون است.

PyTypeObject PyDateTime_TimeType¶

این نمونه از PyTypeObject، نوع time پایتون را نشان می‌دهد؛ این همان شیء datetime.time در لایه پایتون است.

PyTypeObject PyDateTime_DeltaType¶

این نمونه از PyTypeObject نوع پایتونی برای اختلاف بین دو مقدار datetime را نشان می‌دهد؛ این همان شیء datetime.timedelta در لایه پایتون است.

PyTypeObject PyDateTime_TZInfoType¶

این نمونه از PyTypeObject نوع اطلاعات منطقه زمانی پایتون را نمایندگی می‌کند؛ این همان شیء datetime.tzinfo در لایه پایتون است.

ماکرو برای دسترسی به تک‌نمونه‌ی UTC:

PyObject *PyDateTime_TimeZone_UTC¶

تک‌نمونه‌ی منطقه‌ی زمانی UTC را برمی‌گرداند؛ این همان شیء datetime.timezone.utc است.

اضافه شده در نسخه‌ی 3.7.

ماکروهای بررسی نوع:

int PyDate_Check(PyObject *ob)¶

اگر ob از نوع PyDateTime_DateType یا زیرنوعی از PyDateTime_DateType باشد، مقدار true را برمی‌گرداند. ob نباید NULL باشد. این تابع همیشه با موفقیت اجرا می‌شود.

int PyDate_CheckExact(PyObject *ob)¶

اگر ob از نوع PyDateTime_DateType باشد، مقدار true را برمی‌گرداند. ob نباید NULL باشد. این تابع همیشه با موفقیت اجرا می‌شود.

int PyDateTime_Check(PyObject *ob)¶

اگر ob از نوع PyDateTime_DateTimeType یا زیرنوعی از PyDateTime_DateTimeType باشد، true را برمی‌گرداند. ob نباید NULL باشد. این تابع همیشه موفق می‌شود.

int PyDateTime_CheckExact(PyObject *ob)¶

اگر ob از نوع PyDateTime_DateTimeType باشد، مقدار true را برمی‌گرداند. ob نباید NULL باشد. این تابع همیشه با موفقیت اجرا می‌شود.

int PyTime_Check(PyObject *ob)¶

اگر ob از نوع PyDateTime_TimeType یا زیرنوعی از PyDateTime_TimeType باشد، مقدار true را برمی‌گرداند. ob نباید NULL باشد. این تابع همیشه با موفقیت اجرا می‌شود.

int PyTime_CheckExact(PyObject *ob)¶

اگر ob از نوع PyDateTime_TimeType باشد، مقدار true را برمی‌گرداند. ob نباید NULL باشد. این تابع همیشه با موفقیت اجرا می‌شود.

int PyDelta_Check(PyObject *ob)¶

اگر ob از نوع PyDateTime_DeltaType یا زیرنوعی از PyDateTime_DeltaType باشد، مقدار true را برمی‌گرداند. ob نباید NULL باشد. این تابع همیشه با موفقیت انجام می‌شود.

int PyDelta_CheckExact(PyObject *ob)¶

اگر ob از نوع PyDateTime_DeltaType باشد، true را برمی‌گرداند. ob نباید NULL باشد. این تابع همیشه با موفقیت اجرا می‌شود.

int PyTZInfo_Check(PyObject *ob)¶

اگر ob از نوع PyDateTime_TZInfoType یا زیرنوعی از PyDateTime_TZInfoType باشد، مقدار true را برمی‌گرداند. ob نباید NULL باشد. این تابع همیشه با موفقیت اجرا می‌شود.

int PyTZInfo_CheckExact(PyObject *ob)¶

در صورتی که ob از نوع PyDateTime_TZInfoType باشد، مقدار true را برمی‌گرداند. ob نباید NULL باشد. این تابع همیشه موفق می‌شود.

ماکروهای ساخت اشیاء:

PyObject *PyDate_FromDate(int year, int month, int day)¶

مقدار بازگشتی: مرجع جدید.

یک شیء datetime.date با سال، ماه و روز مشخص‌شده برمی‌گرداند.

PyObject *PyDateTime_FromDateAndTime(int year, int month, int day, int hour, int minute, int second, int usecond)¶

مقدار بازگشتی: مرجع جدید.

یک شیء datetime.datetime با سال، ماه، روز، ساعت، دقیقه، ثانیه و میکروثانیه‌ی مشخص‌شده برمی‌گرداند.

PyObject *PyDateTime_FromDateAndTimeAndFold(int year, int month, int day, int hour, int minute, int second, int usecond, int fold)¶

مقدار بازگشتی: مرجع جدید.

یک شیء datetime.datetime با سال، ماه، روز، ساعت، دقیقه، ثانیه، میکروثانیه و fold مشخص‌شده برمی‌گرداند.

اضافه شده در نسخه‌ی 3.6.

PyObject *PyTime_FromTime(int hour, int minute, int second, int usecond)¶

مقدار بازگشتی: مرجع جدید.

یک شیء datetime.time با ساعت، دقیقه، ثانیه و میکروثانیه‌ی مشخص‌شده برمی‌گرداند.

PyObject *PyTime_FromTimeAndFold(int hour, int minute, int second, int usecond, int fold)¶

مقدار بازگشتی: مرجع جدید.

یک شیء datetime.time با ساعت، دقیقه، ثانیه، میکروثانیه و fold مشخص‌شده برمی‌گرداند.

اضافه شده در نسخه‌ی 3.6.

PyObject *PyDelta_FromDSU(int days, int seconds, int useconds)¶

مقدار بازگشتی: مرجع جدید.

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

PyObject *PyTimeZone_FromOffset(PyObject *offset)¶

مقدار بازگشتی: مرجع جدید.

یک شیء datetime.timezone با آفست ثابتِ بی‌نامی که توسط آرگومان offset نمایش داده می‌شود، برمی‌گرداند.

اضافه شده در نسخه‌ی 3.7.

PyObject *PyTimeZone_FromOffsetAndName(PyObject *offset, PyObject *name)¶

مقدار بازگشتی: مرجع جدید.

یک شیء datetime.timezone با آفست ثابتی که توسط آرگومان offset مشخص شده و با tzname برابر name برمی‌گرداند.

اضافه شده در نسخه‌ی 3.7.

ماکروهایی برای استخراج فیلدها از اشیاء تاریخ. آرگومان باید نمونه‌ای از PyDateTime_Date باشد، از جمله زیرکلاس‌ها (مانند PyDateTime_DateTime). آرگومان نباید NULL باشد و نوع آن بررسی نمی‌شود:

int PyDateTime_GET_YEAR(PyDateTime_Date *o)¶

سال را به صورت یک عدد صحیح مثبت برمی‌گرداند.

int PyDateTime_GET_MONTH(PyDateTime_Date *o)¶

ماه را به‌صورت یک عدد صحیح از ۱ تا ۱۲ برمی‌گرداند.

int PyDateTime_GET_DAY(PyDateTime_Date *o)¶

روز را به‌صورت یک عدد صحیح از ۱ تا ۳۱ برمی‌گرداند.

ماکروهایی برای استخراج فیلدها از اشیاء datetime. آرگومان باید نمونه‌ای از PyDateTime_DateTime باشد، شامل زیرکلاس‌ها. آرگومان نباید NULL باشد و نوع آن بررسی نمی‌شود:

int PyDateTime_DATE_GET_HOUR(PyDateTime_DateTime *o)¶

ساعت را به‌صورت یک عدد صحیح از ۰ تا ۲۳ برمی‌گرداند.

int PyDateTime_DATE_GET_MINUTE(PyDateTime_DateTime *o)¶

دقیقه را به‌صورت یک عدد صحیح از ۰ تا ۵۹ برمی‌گرداند.

int PyDateTime_DATE_GET_SECOND(PyDateTime_DateTime *o)¶

ثانیه را به‌صورت یک عدد صحیح از ۰ تا ۵۹ برمی‌گرداند.

int PyDateTime_DATE_GET_MICROSECOND(PyDateTime_DateTime *o)¶

میکروثانیه را به صورت یک عدد صحیح از ۰ تا ۹۹۹۹۹۹ برمی‌گرداند.

int PyDateTime_DATE_GET_FOLD(PyDateTime_DateTime *o)¶

مقدار تاخوردگی (fold) را به‌صورت یک عدد صحیح از ۰ تا ۱ برمی‌گرداند.

اضافه شده در نسخه‌ی 3.6.

PyObject *PyDateTime_DATE_GET_TZINFO(PyDateTime_DateTime *o)¶

بازگرداندن tzinfo (که ممکن است None باشد).

اضافه شده در نسخه‌ی 3.10.

ماکروهایی برای استخراج فیلدها از اشیاء زمان. آرگومان باید نمونه‌ای از PyDateTime_Time باشد، شامل زیرکلاس‌ها. آرگومان نباید NULL باشد و نوع آن بررسی نمی‌شود:

int PyDateTime_TIME_GET_HOUR(PyDateTime_Time *o)¶

ساعت را به‌صورت یک عدد صحیح از ۰ تا ۲۳ برمی‌گرداند.

int PyDateTime_TIME_GET_MINUTE(PyDateTime_Time *o)¶

دقیقه را به‌صورت یک عدد صحیح از ۰ تا ۵۹ برمی‌گرداند.

int PyDateTime_TIME_GET_SECOND(PyDateTime_Time *o)¶

ثانیه را به‌صورت یک عدد صحیح از ۰ تا ۵۹ برمی‌گرداند.

int PyDateTime_TIME_GET_MICROSECOND(PyDateTime_Time *o)¶

میکروثانیه را به صورت یک عدد صحیح از ۰ تا ۹۹۹۹۹۹ برمی‌گرداند.

int PyDateTime_TIME_GET_FOLD(PyDateTime_Time *o)¶

مقدار تاخوردگی (fold) را به‌صورت یک عدد صحیح از ۰ تا ۱ برمی‌گرداند.

اضافه شده در نسخه‌ی 3.6.

PyObject *PyDateTime_TIME_GET_TZINFO(PyDateTime_Time *o)¶

بازگرداندن tzinfo (که ممکن است None باشد).

اضافه شده در نسخه‌ی 3.10.

ماکروهایی برای استخراج فیلدها از اشیاء دلتای زمانی. آرگومان باید نمونه‌ای از PyDateTime_Delta باشد، از جمله زیرکلاس‌ها. آرگومان نباید NULL باشد و نوع آن بررسی نمی‌شود:

int PyDateTime_DELTA_GET_DAYS(PyDateTime_Delta *o)¶

تعداد روز‌ها را به صورت یک عدد صحیح از -999999999 تا 999999999 برمی‌گرداند.

اضافه شده در نسخه‌ی 3.3.

int PyDateTime_DELTA_GET_SECONDS(PyDateTime_Delta *o)¶

تعداد ثانیه‌ها را به‌صورت یک عدد صحیح از ۰ تا ۸۶۳۹۹ برمی‌گرداند.

اضافه شده در نسخه‌ی 3.3.

int PyDateTime_DELTA_GET_MICROSECONDS(PyDateTime_Delta *o)¶

تعداد میکروثانیه‌ها را به صورت یک عدد صحیح از ۰ تا ۹۹۹۹۹۹ برمی‌گرداند.

اضافه شده در نسخه‌ی 3.3.

ماکروهایی برای سهولت کار ماژول‌هایی که DB API را پیاده‌سازی می‌کنند:

PyObject *PyDateTime_FromTimestamp(PyObject *args)¶

مقدار بازگشتی: مرجع جدید.

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

PyObject *PyDate_FromTimestamp(PyObject *args)¶

مقدار بازگشتی: مرجع جدید.

با گرفتن یک تاپل آرگومان مناسب برای پاس دادن به datetime.date.fromtimestamp()، یک شیء جدید datetime.date ایجاد کرده و بازمی‌گرداند.

داده‌های داخلی¶

نمادهای زیر توسط C API ارائه‌شده‌اند، اما باید فقط داخلی در نظر گرفته شوند.

PyDateTime_CAPSULE_NAME¶

نام کپسول datetime که باید به PyCapsule_Import() پاس داده شود.

صرفاً برای استفاده‌ی داخلی. به‌جای آن از PyDateTime_IMPORT استفاده کنید.