time --- دسترسی به زمان و تبدیل‌ها

---

این ماژول توابع مختلفی مرتبط با زمان را فراهم می‌کند. برای قابلیت‌های مرتبط، ماژول‌های datetime و calendar را نیز ببینید.

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

توضیحی درباره‌ی برخی اصطلاحات و قراردادها به‌جاست.

• epoch نقطه‌ای است که زمان از آن آغاز می‌شود، یعنی مقدار بازگشتی time.gmtime(0). این زمان در همه‌ی پلتفرم‌ها ۱ ژانویه‌ی ۱۹۷۰، ۰۰:۰۰:۰۰ (UTC) است.

• اصطلاح ثانیه‌های سپری‌شده از مبدأ زمانی <seconds since the epoch> به تعداد کل ثانیه‌های سپری‌شده از مبدأ زمانی اشاره دارد، معمولاً به استثنای leap seconds. ثانیه‌های کبیسه در تمام پلتفرم‌های سازگار با POSIX از این مجموع حذف می‌شوند.

• توابع این ماژول ممکن است تاریخ‌ها و زمان‌های پیش از epoch یا آینده‌ی بسیار دور را مدیریت نکنند. نقطه‌ی قطع در آینده توسط کتابخانه‌ی C تعیین می‌شود؛ برای سیستم‌های ۳۲‌بیتی، معمولاً در سال ۲۰۳۸ است.

• تابع strptime() می‌تواند سال‌های دو رقمی را در صورت دریافت کد قالب %y تجزیه کند. هنگامی که سال‌های دو رقمی تجزیه می‌شوند، آن‌ها مطابق استانداردهای POSIX و ISO C تبدیل می‌شوند: مقادیر ۶۹--۹۹ به ۱۹۶۹--۱۹۹۹ نگاشت داده می‌شوند، و مقادیر ۰--۶۸ به ۲۰۰۰--۲۰۶۸ نگاشت داده می‌شوند.

• UTC همان Coordinated Universal Time است و جایگزین Greenwich Mean Time یا GMT به‌عنوان مبنای زمان‌بندی بین‌المللی شده است. سرواژه UTC اشتباه نیست، بلکه از یک طرح‌واره نام‌گذاری پیشین و مستقل از زبان برای استانداردهای زمان مانند UT0، UT1 و UT2 پیروی می‌کند.

• DST زمان تابستانی (Daylight Saving Time) است، تنظیمی در منطقه زمانی به میزان (معمولاً) یک ساعت در بخشی از سال. قواعد DST جادویی هستند (توسط قانون محلی تعیین می‌شوند) و می‌توانند از سالی به سال دیگر تغییر کنند. کتابخانه C جدولی شامل قواعد محلی دارد (که اغلب برای انعطاف‌پذیری از یک سامانه فایل‌بندی‌ای خوانده می‌شود) و تنها منبع خرد واقعی در این زمینه است.

• دقت توابع مختلف زمان واقعی ممکن است کمتر از میزانی باشد که واحدهای بیان‌کننده‌ی مقدار یا آرگومان آن‌ها پیشنهاد می‌دهند. برای مثال، در بیشتر سیستم‌های Unix، ساعت تنها ۵۰ یا ۱۰۰ بار در ثانیه «تیک» می‌خورد.

• از سوی دیگر، دقت time() و sleep() بهتر از معادل‌های آن‌ها در یونیکس است: زمان‌ها به‌صورت اعداد ممیز شناور بیان می‌شوند، time() دقیق‌ترین زمان در دسترس را برمی‌گرداند (در صورت در دسترس بودن، از gettimeofday() یونیکس استفاده می‌شود) و sleep() زمانی با بخش کسری غیرصفر را می‌پذیرد (برای پیاده‌سازی این امکان، در صورت در دسترس بودن، از select() یونیکس استفاده می‌شود).

• مقدار زمان که توسط gmtime()، localtime() و strptime() بازگردانده می‌شود و توسط asctime()، mktime() و strftime() پذیرفته می‌شود، دنباله‌ای از ۹ عدد صحیح است. مقادیر بازگشتی gmtime()، localtime() و strptime() همچنین نام ویژگی‌هایی را برای فیلدهای جداگانه ارائه می‌دهند.

  برای شرح این اشیاء، struct_time را ببینید.

  تغییر یافته در نسخه‌ی 3.3: نوع struct_time گسترش یافت تا ویژگی‌های tm_gmtoff و tm_zone را در صورتی که پلتفرم از اعضای متناظر struct tm پشتیبانی کند، فراهم کند.

  تغییر یافته در نسخه‌ی 3.6: ویژگی‌های tm_gmtoff و tm_zone از کلاس struct_time اکنون در همه‌ی سکوها در دسترس هستند.

• برای تبدیل بین بازنمایی‌های زمان از توابع زیر استفاده کنید:

  از	به	استفاده
  ثانیه‌های سپری‌شده از مبدأ زمان	struct_time در UTC	gmtime()
  ثانیه‌های سپری‌شده از مبدأ زمان	struct_time در زمان محلی	localtime()
  struct_time در UTC	ثانیه‌های سپری‌شده از مبدأ زمان	calendar.timegm()
  struct_time در زمان محلی	ثانیه‌های سپری‌شده از مبدأ زمان	mktime()

توابع

time.asctime([time_tuple])

Convert a tuple or struct_time representing a time as returned by gmtime() or localtime() to a string of the following form: 'Sun Jun 20 23:21:05 1993'. The day field is two characters long and is space padded if the day is a single digit, for example: 'Wed Jun  9 04:26:40 1993'.

If time_tuple is not provided, the current time as returned by localtime() is used. Locale information is not used by asctime().

توجه

برخلاف تابع C با همین نام، asctime() یک نویسه خط جدید پایانی اضافه نمی‌کند.

time.pthread_getcpuclockid(thread_id, /)

clk_id ساعت زمان پردازنده‌ی مختص به نخ برای thread_id مشخص‌شده را برمی‌گرداند.

برای به دست آوردن یک مقدار مناسب برای thread_id، از threading.get_ident() یا ویژگی ident اشیای threading.Thread استفاده کنید.

هشدار

ارسال یک thread_id نامعتبر یا منقضی‌شده ممکن است منجر به رفتار تعریف‌نشده شود، مانند خطای قطعه‌بندی (segmentation fault).

دسترس‌پذیری: Unix

برای اطلاعات بیشتر، صفحه man مربوط به pthread_getcpuclockid(3) را ببینید.

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

time.clock_getres(clk_id, /)

دقت (precision) ساعت مشخص‌شده با clk_id را برمی‌گرداند. برای فهرستی از مقادیر پذیرفته‌شده برای clk_id به ثابت‌های شناسه‌ی ساعت مراجعه کنید.

دسترس‌پذیری: Unix.

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

time.clock_gettime(clk_id, /) → float

زمان ساعت مشخص‌شده با clk_id را برمی‌گرداند. برای فهرستی از مقادیر پذیرفته‌شده برای clk_id به ثابت‌های شناسه‌ی ساعت مراجعه کنید.

برای جلوگیری از کاهش دقت ناشی از نوع float، از clock_gettime_ns() استفاده کنید.

دسترس‌پذیری: Unix.

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

time.clock_gettime_ns(clk_id, /) → int

مشابه clock_gettime() است، اما زمان را به‌صورت نانوثانیه برمی‌گرداند.

دسترس‌پذیری: Unix.

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

time.clock_settime(clk_id, time: float, /)

زمان ساعت مشخص‌شده با clk_id را تنظیم کنید. در حال حاضر، CLOCK_REALTIME تنها مقدار پذیرفته‌شده برای clk_id است.

برای اجتناب از کاهش دقت ناشی از نوع float، از clock_settime_ns() استفاده کنید.

دسترس‌پذیری: Unix, not Android, not iOS.

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

time.clock_settime_ns(clk_id, time: int, /)

مشابه clock_settime() است، اما زمان را با نانوثانیه تنظیم می‌کند.

دسترس‌پذیری: Unix, not Android, not iOS.

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

time.ctime(seconds=None, /)

Convert a time expressed in seconds since the epoch to a string of a form: 'Sun Jun 20 23:21:05 1993' representing local time. The day field is two characters long and is space padded if the day is a single digit, for example: 'Wed Jun  9 04:26:40 1993'.

If seconds is not provided or None, the current time as returned by time() is used. ctime(seconds) is equivalent to asctime(localtime(seconds)). Locale information is not used by ctime().

time.get_clock_info(name, /)

اطلاعات مربوط به ساعت مشخص‌شده را به‌عنوان یک شیء فضای نام دریافت کنید. نام‌های ساعت پشتیبانی‌شده و توابع متناظر برای خواندن مقدار آن‌ها عبارتند از:

• 'monotonic': time.monotonic()

• 'perf_counter': time.perf_counter()

• 'process_time': time.process_time()

• 'thread_time': time.thread_time()

• 'time': time.time()

نتیجه دارای ویژگی‌های زیر است:

• adjustable: اگر بتوان ساعت را به‌گونه‌ای تنظیم کرد که در زمان به جلو یا عقب بپرد، True و در غیر این صورت False است. به تنظیم‌های تدریجی نرخ NTP اشاره نمی‌کند.

• implementation: نام تابع C زیربنایی که برای گرفتن مقدار ساعت استفاده می‌شود. برای مقادیر ممکن، به ثابت‌های شناسه‌ی ساعت مراجعه کنید.

• monotonic: True اگر ساعت نتواند به عقب برود، در غیر این صورت False

• resolution: دقت ساعت بر حسب ثانیه (float)

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

time.gmtime(seconds=None, /)

Convert a time expressed in seconds since the epoch to a struct_time in UTC in which the dst flag is always zero. If seconds is not provided or None, the current time as returned by time() is used. Fractions of a second are ignored. See above for a description of the struct_time object. See calendar.timegm() for the inverse of this function.

time.localtime(seconds=None, /)

Like gmtime() but converts to local time. If seconds is not provided or None, the current time as returned by time() is used. The dst flag is set to 1 when DST applies to the given time.

localtime() ممکن است در صورتی که برچسب زمانی خارج از محدوده مقادیر پشتیبانی‌شده توسط توابع C سکو یعنی localtime() یا gmtime() باشد، OverflowError را پرتاب کند، و در صورت شکست localtime() یا gmtime() نیز OSError را پرتاب کند. معمولاً این محدوده به سال‌های بین ۱۹۷۰ تا ۲۰۳۸ محدود است.

time.mktime(time_tuple, /)

این تابع معکوس localtime() است. آرگومان آن یک struct_time یا ۹-تایی کامل است (زیرا به پرچم dst نیاز است؛ اگر ناشناخته است، از -1 به‌عنوان پرچم dst استفاده کنید) که زمان را به‌وقت محلی بیان می‌کند، نه UTC. این تابع یک عدد اعشاری برمی‌گرداند تا با time() سازگار باشد. اگر مقدار ورودی نتواند به‌عنوان یک زمان معتبر بازنمایی شود، یکی از OverflowError یا ValueError پرتاب خواهد شد (که بستگی دارد به اینکه مقدار نامعتبر توسط پایتون تشخیص داده شود یا توسط کتابخانه‌های C زیرین). زودترین تاریخی که می‌تواند برای آن یک زمان تولید کند، به پلتفرم وابسته است.

time.monotonic() → float

مقدار (بر حسب ثانیه‌های کسری) یک ساعت یکنواخت (monotonic clock) را برمی‌گرداند، یعنی ساعتی که نمی‌تواند به عقب برگردد. این ساعت تحت تأثیر به‌روزرسانی‌های ساعت سیستم قرار نمی‌گیرد. نقطه مرجع مقدار برگردانده‌شده تعریف‌نشده است، بنابراین تنها اختلاف میان نتایج دو فراخوانی معتبر است.

ساعت:

• در ویندوز، QueryPerformanceCounter() و QueryPerformanceFrequency() را فراخوانی کنید.

• در macOS، mach_absolute_time() و mach_timebase_info() را فراخوانی کنید.

• در HP-UX، gethrtime() را فراخوانی کنید.

• در صورت در دسترس بودن، clock_gettime(CLOCK_HIGHRES) را فراخوانی می‌کند.

• در غیر این صورت، clock_gettime(CLOCK_MONOTONIC) را فراخوانی کنید.

برای جلوگیری از کاهش دقت ناشی از نوع float، از monotonic_ns() استفاده کنید.

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

تغییر یافته در نسخه‌ی 3.5: این تابع اکنون همیشه در دسترس است و ساعت اکنون برای همه فرایندها یکسان است.

تغییر یافته در نسخه‌ی 3.10: در macOS، اکنون ساعت برای همه‌ی فرایندها یکسان است.

time.monotonic_ns() → int

مشابه monotonic()، اما زمان را به‌صورت نانوثانیه برمی‌گرداند.

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

time.perf_counter() → float

مقدار (بر حسب ثانیه‌های کسری) یک شمارنده کارایی (performance counter) را برمی‌گرداند، یعنی ساعتی با بالاترین تفکیک‌پذیری در دسترس برای اندازه‌گیری یک مدت‌زمان کوتاه. این شامل زمان سپری‌شده در حالت توقف نیز می‌شود. این ساعت برای همه فرآیندها یکسان است. نقطه مرجع مقدار برگردانده‌شده تعریف‌نشده است، بنابراین تنها تفاوت بین نتایج دو فراخوانی معتبر است.

در CPython، از همان ساعت time.monotonic() استفاده می‌کند و یک ساعت یکنواخت است، یعنی ساعتی که نمی‌تواند به عقب بازگردد.

برای جلوگیری از کاهش دقت ناشی از نوع float، از perf_counter_ns() استفاده کنید.

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

تغییر یافته در نسخه‌ی 3.10: در ویندوز، ساعت اکنون برای همه فرایندها یکسان است.

تغییر یافته در نسخه‌ی 3.13: از همان ساعتی استفاده می‌کند که time.monotonic() از آن استفاده می‌کند.

time.perf_counter_ns() → int

مشابه perf_counter()، اما زمان را به‌صورت نانوثانیه بازمی‌گرداند.

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

time.process_time() → float

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

برای جلوگیری از کاهش دقت ناشی از نوع float، از process_time_ns() استفاده کنید.

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

time.process_time_ns() → int

مشابه process_time() اما زمان را به‌صورت نانوثانیه برمی‌گرداند.

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

time.sleep(seconds, /)

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

اگر sleep بر اثر یک سیگنال دچار وقفه شود و هندلر سیگنال استثنایی پرتاب نکند، sleep با مهلت زمانی بازمحاسبه‌شده دوباره آغاز می‌شود.

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

پیاده‌سازی ویندوز

On Windows, if seconds is zero, the thread relinquishes the remainder of its time slice to any other thread that is ready to run. If there are no other threads ready to run, the function returns immediately, and the thread continues execution. On Windows 10 and newer the implementation uses a high-resolution timer which provides resolution of 100 nanoseconds. If seconds is zero, Sleep(0) is used.

پیاده‌سازی یونیکس

• اگر clock_nanosleep() در دسترس است، از آن استفاده کنید (دقت: ۱ نانوثانیه)؛

• یا در صورت در دسترس بودن از nanosleep() استفاده کنید (دقت: ۱ نانوثانیه)؛

• یا از select() استفاده کنید (دقت: ۱ میکروثانیه).

توجه

برای شبیه‌سازی یک «عملیات بی‌اثر» (no-op)، به جای time.sleep(0) از pass استفاده کنید.

برای رها کردن داوطلبانه‌ی CPU، یک سیاست زمان‌بندی بلادرنگ مشخص کنید و در عوض از os.sched_yield() استفاده کنید.

Raises an auditing event time.sleep with argument seconds.

تغییر یافته در نسخه‌ی 3.5: The function now sleeps at least seconds even if the sleep is interrupted by a signal, except if the signal handler raises an exception (see PEP 475 for the rationale).

تغییر یافته در نسخه‌ی 3.11: در یونیکس، اکنون در صورت در دسترس بودن، از توابع clock_nanosleep() و nanosleep() استفاده می‌شود. در ویندوز، اکنون از یک زمان‌سنج انتظارپذیر (waitable timer) استفاده می‌شود.

تغییر یافته در نسخه‌ی 3.13: یک رویداد حسابرسی را پرتاب می‌کند.

time.strftime(format[, time_tuple])

Convert a tuple or struct_time representing a time as returned by gmtime() or localtime() to a string as specified by the format argument. If time_tuple is not provided, the current time as returned by localtime() is used. format must be a string. ValueError is raised if any field in time_tuple is outside of the allowed range.

۰ یک آرگومان مجاز برای هر جایگاهی از تاپل زمانی است؛ اگر در حالت عادی غیرمجاز باشد، مقدار به‌اجبار به مقداری درست تغییر می‌یابد.

می‌توان دایرکتیوهای زیر را در رشته‌ی format گنجاند. آن‌ها بدون مشخصه‌ی اختیاری عرض فیلد و دقت نمایش داده شده‌اند و در نتیجه‌ی strftime() با نویسه‌های مشخص‌شده جایگزین می‌شوند:

دایرکتیو	معنی	یادداشت‌ها
%a	نام کوتاه‌شده‌ی روز هفته بر اساس locale.
%A	نام کامل روز هفته بر اساس locale.
%b	نام کوتاه‌شده‌ی ماه در locale .
%B	نام کامل ماهِ تنظیمات locale .
%c	نمایش مناسب تاریخ و زمان متناسب با تنظیمات locale .
%d	روز ماه به‌صورت عدد دهدهی [01,31].
%f	میکروثانیه به‌صورت عدد اعشاری [000000,999999].	(1)
%H	ساعت (بر اساس ساعت ۲۴ساعته) به‌صورت عدد ده‌دهی [00,23].
%I	ساعت (ساعت ۱۲ ساعته) به‌صورت عدد دهدهی [01,12].
%j	روز سال به‌صورت عدد دهدهی [001,366].
%m	ماه به‌صورت عدد دهدهی [01,12].
%M	دقیقه به‌صورت عدد دهدهی [00,59].
%p	معادل locale برای AM یا PM.	(2)
%S	ثانیه به‌صورت عدد دهدهی [00,61].	(3)
%U	شماره‌ی هفته‌ی سال (یکشنبه به‌عنوان اولین روز هفته) به‌صورت عدد اعشاری [۰۰،۵۳]. همه‌ی روزهای سال جدید پیش از اولین یکشنبه، در هفته‌ی ۰ محسوب می‌شوند.	(4)
%u	روز هفته (دوشنبه ۱ است؛ یکشنبه ۷ است) به‌صورت عدد دهدهی [۱، ۷].
%w	روز هفته به‌صورت عدد ده‌دهی [0(یکشنبه),6].
%W	شماره‌ی هفته‌ی سال (دوشنبه به‌عنوان اولین روز هفته) به‌صورت عدد دهدهی [00,53]. همه‌ی روزهای سال جدید پیش از اولین دوشنبه، در هفته‌ی ۰ در نظر گرفته می‌شوند.	(4)
%x	نمایش تاریخ مناسب با تنظیمات locale .
%X	نمایش زمان مناسب برای تنظیمات locale .
%y	سال بدون قرن به‌صورت عدد دهدهی [00,99].
%Y	سال همراه با قرن به‌صورت عدد دهدهی.
%z	آفست منطقه زمانی که نشان‌دهنده‌ی اختلاف زمانی مثبت یا منفی نسبت به UTC/GMT به‌شکل +HHMM یا -HHMM است، که در آن H نشان‌دهنده‌ی ارقام دهدهی ساعت و M نشان‌دهنده‌ی ارقام دهدهی دقیقه است [-23:59, +23:59]. [1]
%Z	نام منطقه‌ی زمانی (اگر منطقه‌ی زمانی وجود نداشته باشد، بدون نویسه). منسوخ. [1]
%G	سال ISO 8601 (مشابه %Y، اما از قواعد سال گاه‌شماریی ISO 8601 پیروی می‌کند). سال با هفته‌ای آغاز می‌شود که شامل اولین پنجشنبه‌ی سال گاه‌شماریی است.
%V	شماره هفته ISO 8601 (به‌صورت عدد دهدهی [01,53]). نخستین هفته سال، هفته‌ای است که نخستین پنجشنبه سال در آن قرار دارد. هفته‌ها از دوشنبه آغاز می‌شوند.
%%	یک نویسه‌ی لفظی '%'.

یادداشت‌ها:

1. دایرکتیو قالب %f فقط در strptime() کاربرد دارد، نه در strftime(). با این حال، datetime.datetime.strptime() و datetime.datetime.strftime() را نیز ببینید که در آن‌ها دایرکتیو قالب %f برای میکروثانیه‌ها کاربرد دارد.

2. هنگامی که همراه با تابع strptime() استفاده شود، دایرکتیو %p تنها در صورتی بر فیلد ساعت خروجی اثر می‌گذارد که از دایرکتیو %I برای تجزیه ساعت استفاده شود.

3. بازه واقعاً از 0 تا 61 است؛ مقدار 60 در مهرهای زمانی که نمایانگر leap seconds هستند معتبر است و مقدار 61 به دلایل تاریخی پشتیبانی می‌شود.

4. هنگامی که همراه با تابع strptime() استفاده شوند، %U و %W فقط زمانی در محاسبات استفاده می‌شوند که روز هفته و سال تعیین شده باشند.

در اینجا مثالی آورده شده است، قالبی برای تاریخ‌ها که با قالب تعیین‌شده در استاندارد ایمیل اینترنتی RFC 5322 سازگار است. [1]

>>> from time import gmtime, strftime
>>> strftime("%a, %d %b %Y %H:%M:%S +0000", gmtime())
'Thu, 28 Jun 2001 14:17:15 +0000'

ممکن است دایرکتیوهای اضافی در برخی پلتفرم‌های خاص پشتیبانی شوند، اما تنها موارد فهرست‌شده در اینجا دارای معنای استانداردشده توسط ANSI C هستند. برای مشاهده مجموعه کامل کدهای قالب‌بندی پشتیبانی‌شده در پلتفرم شما، به مستندات strftime(3) مراجعه کنید.

در برخی سکوها، می‌توان بلافاصله پس از '%' ابتدایی یک دایرکتیو، مشخصه‌ی اختیاری عرض فیلد و دقت را با ترتیب زیر آورد؛ این مورد نیز غیرقابل حمل است. عرض فیلد معمولاً ۲ است، به‌جز %j که ۳ است.

time.strptime(string[, format])

رشته‌ای را که نشان‌دهنده‌ی یک زمان است، بر اساس یک قالب تجزیه می‌کند. مقدار بازگشتی یک struct_time است، مانند مقداری که توسط gmtime() یا localtime() بازگردانده می‌شود.

پارامتر format از همان دایرکتیوهایی استفاده می‌کند که در strftime() به کار می‌روند؛ مقدار پیش‌فرض آن "%a %b %d %H:%M:%S %Y" است که با قالب‌بندی برگردانده‌شده توسط ctime() مطابقت دارد. اگر string نتواند طبق format تجزیه شود، یا اگر پس از تجزیه داده اضافی داشته باشد، ValueError پرتاب می‌شود. مقادیر پیش‌فرضی که برای پر کردن هرگونه داده مفقود استفاده می‌شوند، در صورتی که نتوان مقادیر دقیق‌تری را استنتاج کرد، (1900, 1, 1, 0, 0, 0, 0, 1, -1) هستند. هر دو string و format باید رشته باشند.

برای مثال:

>>> import time
>>> time.strptime("30 Nov 00", "%d %b %y")
time.struct_time(tm_year=2000, tm_mon=11, tm_mday=30, tm_hour=0, tm_min=0,
                 tm_sec=0, tm_wday=3, tm_yday=335, tm_isdst=-1)

پشتیبانی از دایرکتیو %Z بر پایه‌ی مقادیر موجود در tzname و این‌که daylight درست باشد، است. به همین دلیل، این پشتیبانی وابسته به پلتفرم است، به‌جز برای شناسایی UTC و GMT که همیشه شناخته‌شده هستند (و به‌عنوان مناطق زمانی بدون ساعت تابستانی در نظر گرفته می‌شوند).

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

class time.struct_time

نوع دنباله‌ی مقادیر زمانی که توسط gmtime()، localtime() و strptime() برگردانده می‌شود. این، شیءای با رابط named tuple است: می‌توان به مقادیر از طریق اندیس و نام ویژگی دسترسی داشت. مقادیر زیر موجود هستند:

اندیس	ویژگی	مقادیر
0	tm_year	(برای مثال، ۱۹۹۳)
1	tm_mon	بازه [1, 12]
۲	tm_mday	بازه [۱، ۳۱]
3	tm_hour	بازه [۰، ۲۳]
4	tm_min	بازه [۰، ۵۹]
5	tm_sec	بازه [۰، ۶۱]؛ یادداشت (۲) در strftime() را ببینید
۶	tm_wday	بازه [۰، ۶]؛ دوشنبه ۰ است
7	tm_yday	بازه [1, 366]
8	tm_isdst	۰، ۱ یا -۱؛ در زیر ببینید
ناموجود	tm_zone	مخفف نام منطقه زمانی
ناموجود	tm_gmtoff	آفست شرقی از UTC به ثانیه

توجه داشته باشید که برخلاف ساختار C، مقدار ماه در بازه‌ی [۱، ۱۲] است، نه [۰، ۱۱].

در فراخوانی‌های mktime()، هرگاه ساعت تابستانی برقرار باشد، می‌توان tm_isdst را روی ۱ تنظیم کرد و هرگاه برقرار نباشد، روی ۰. مقدار -۱ نشان می‌دهد که این موضوع نامشخص است و معمولاً منجر به درج وضعیت صحیح می‌شود.

هنگامی که تاپلی با طول نادرست یا دارای عناصری از نوع اشتباه به تابعی که انتظار یک struct_time را دارد پاس داده شود، یک TypeError پرتاب می‌شود.

time.time() → float

زمان سپری‌شده از مبدأ زمانی (epoch) را بر حسب ثانیه به‌صورت یک عدد اعشاری برمی‌گرداند. نحوه‌ی مدیریت ثانیه‌های کبیسه به پلتفرم بستگی دارد. در ویندوز و بیشتر سیستم‌های یونیکسی، ثانیه‌های کبیسه در شمار ثانیه‌های سپری‌شده از مبدأ زمانی (epoch) لحاظ نمی‌شوند. این معمولاً به‌عنوان زمان یونیکس شناخته می‌شود.

توجه داشته باشید که با وجود اینکه زمان همیشه به‌صورت یک عدد ممیز شناور برگردانده می‌شود، همه‌ی سیستم‌ها زمان را با دقتی بهتر از ۱ ثانیه ارائه نمی‌کنند. در حالی که این تابع به‌طور معمول مقادیر غیرکاهشی برمی‌گرداند، اگر ساعت سیستم بین دو فراخوانی به عقب تنظیم شده باشد، ممکن است مقداری کمتر از مقدار برگردانده‌شده در یک فراخوانی قبلی برگرداند.

عدد برگردانده‌شده توسط time() می‌تواند به یک قالب زمان رایج‌تر (یعنی سال، ماه، روز، ساعت و غیره...) در UTC با ارسال آن به تابع gmtime()، یا در زمان محلی با ارسال آن به تابع localtime() تبدیل شود. در هر دو حالت یک شیء struct_time برگردانده می‌شود که کامپوننت‌های تاریخ گاه‌شماریی به‌عنوان ویژگی‌های آن قابل دسترسی هستند.

ساعت:

• در ویندوز، GetSystemTimePreciseAsFileTime() را فراخوانی کنید.

• در صورت موجود بودن، clock_gettime(CLOCK_REALTIME) را فراخوانی کنید.

• در غیر این صورت، gettimeofday() را فراخوانی کنید.

برای جلوگیری از کاهش دقت ناشی از نوع float، از time_ns() استفاده کنید.

تغییر یافته در نسخه‌ی 3.13: در ویندوز، GetSystemTimePreciseAsFileTime() را به‌جای GetSystemTimeAsFileTime() فراخوانی می‌کند.

time.time_ns() → int

مشابه time() است، اما زمان را به‌صورت عدد صحیحی از نانوثانیه‌ها از epoch برمی‌گرداند.

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

time.thread_time() → float

مقدار مجموع زمان CPU سیستم و کاربر برای نخ فعلی را (بر حسب ثانیه‌های کسری) برمی‌گرداند. این مقدار شامل زمان سپری‌شده در طول توقف نمی‌شود. این مقدار طبق تعریف مختص نخ است. نقطه مرجع مقدار برگردانده‌شده تعریف‌نشده است، بنابراین تنها تفاوت میان نتایج دو فراخوانی در یک نخ معتبر است.

برای جلوگیری از کاهش دقت ناشی از نوع float، از thread_time_ns() استفاده کنید.

دسترس‌پذیری: Linux, Unix, Windows.

سیستم‌های یونیکسی که از CLOCK_THREAD_CPUTIME_ID پشتیبانی می‌کنند.

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

time.thread_time_ns() → int

مشابه thread_time() است، اما زمان را به‌صورت نانوثانیه بازمی‌گرداند.

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

time.tzset()

قواعد تبدیل زمان مورد استفاده توسط روتین‌های کتابخانه را بازنشانی می‌کند. متغیر محیطی TZ نحوه انجام این کار را مشخص می‌کند. همچنین متغیرهای tzname (از متغیر محیطی TZ)، timezone (ثانیه‌های غیر DST در غرب UTC)، altzone (ثانیه‌های DST در غرب UTC) و daylight (به ۰ اگر این منطقه زمانی هیچ قاعده‌ای برای ساعت تابستانی نداشته باشد، یا به مقداری غیرصفر اگر زمانی در گذشته، حال یا آینده وجود داشته باشد که ساعت تابستانی اعمال شود) را نیز تنظیم خواهد کرد.

دسترس‌پذیری: Unix.

توجه

اگرچه در بسیاری از موارد، تغییر متغیر محیطی TZ ممکن است بدون فراخوانی tzset() بر خروجی توابعی مانند localtime() تأثیر بگذارد، نباید به این رفتار اتکا کرد.

متغیر محیطی TZ نباید شامل هیچ‌گونه فضای خالی باشد.

قالب استاندارد متغیر محیطی TZ به این صورت است (فضای سفید برای خوانایی اضافه شده است):

std offset [dst [offset [,start[/time], end[/time]]]]

که در آن کامپوننت‌ها عبارتند از:

std و dst

۳ یا چند نویسه‌ی الفبایی‌عددی که مخفف‌های منطقه‌ی زمانی را مشخص می‌کنند. این مقادیر به time.tzname منتقل می‌شوند

offset

آفست به شکل ± hh[:mm[:ss]] است. این، مقداری است که به زمان محلی افزوده می‌شود تا UTC به دست آید. اگر پیش از آن یک '-' بیاید، منطقه‌ی زمانی در شرق نصف‌النهار مبدأ است؛ در غیر این صورت، در غرب آن است. اگر پس از dst آفستی نیاید، فرض می‌شود ساعت تابستانی یک ساعت جلوتر از زمان استاندارد است.

start[/time], end[/time]

مشخص می‌کند که چه زمانی باید به ساعت تابستانی (DST) تغییر کرد و از آن بازگشت. قالب تاریخ‌های شروع و پایان یکی از موارد زیر است:

Jn

روز ژولینی n (۱ <= n <= ۳۶۵). روزهای کبیسه شمارش نمی‌شوند، بنابراین در همه سال‌ها، ۲۸ فوریه روز ۵۹ و ۱ مارس روز ۶۰ است.

n

روز ژولینی مبتنی بر صفر (۰ <= n <= ۳۶۵). روزهای کبیسه شمرده می‌شوند، و می‌توان به ۲۹ فوریه اشاره کرد.

Mm.n.d

d امین روز (۰ <= d <= ۶) از هفته‌ی n از ماه m از سال (۱ <= n <= ۵، ۱ <= m <= ۱۲، که هفته‌ی ۵ به معنای «آخرین روز d در ماه m» است؛ این روز ممکن است در هفته‌ی چهارم یا پنجم رخ دهد). هفته‌ی ۱ نخستین هفته‌ای است که d امین روز در آن رخ می‌دهد. روز صفر، یکشنبه است.

time همان قالب offset را دارد، با این تفاوت که علامت پیش‌رو ('-' یا '+') مجاز نیست. مقدار پیش‌فرض، اگر time داده نشود، 02:00:00 است.

>>> os.environ['TZ'] = 'EST+05EDT,M4.1.0,M10.5.0'
>>> time.tzset()
>>> time.strftime('%X %x %Z')
'02:07:36 05/08/03 EDT'
>>> os.environ['TZ'] = 'AEST-10AEDT-11,M10.5.0,M3.5.0'
>>> time.tzset()
>>> time.strftime('%X %x %Z')
'16:08:12 05/08/03 AEST'

در بسیاری از سیستم‌های یونیکسی (شامل *BSD، Linux، Solaris و Darwin)، استفاده از پایگاه داده‌ی zoneinfo سیستم (tzfile(5)) برای مشخص کردن قوانین منطقه زمانی راحت‌تر است. برای این کار، متغیر محیطی TZ را روی مسیر پرونده داده‌ی منطقه زمانی مورد نیاز، نسبت به ریشه‌ی پایگاه داده‌ی منطقه زمانی 'zoneinfo' سیستم، که معمولاً در /usr/share/zoneinfo قرار دارد، تنظیم کنید. برای مثال، 'US/Eastern'، 'Australia/Melbourne'، 'Egypt' یا 'Europe/Amsterdam'.

>>> os.environ['TZ'] = 'US/Eastern'
>>> time.tzset()
>>> time.tzname
('EST', 'EDT')
>>> os.environ['TZ'] = 'Egypt'
>>> time.tzset()
>>> time.tzname
('EET', 'EEST')

ثابت‌های شناسه‌ی ساعت

این ثابت‌ها به‌عنوان پارامترهایی برای clock_getres() و clock_gettime() استفاده می‌شوند.

time.CLOCK_BOOTTIME

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

این به برنامه‌ها امکان می‌دهد یک ساعت یکنواخت آگاه از تعلیق دریافت کنند، بدون اینکه مجبور باشند با پیچیدگی‌های CLOCK_REALTIME سروکار داشته باشند، که ممکن است در صورت تغییر زمان با استفاده از settimeofday() یا موارد مشابه، ناپیوستگی‌هایی داشته باشد.

دسترس‌پذیری: Linux >= 2.6.39.

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

time.CLOCK_HIGHRES

سیستم‌عامل Solaris دارای یک زمان‌سنج CLOCK_HIGHRES است که تلاش می‌کند از یک منبع سخت‌افزاری بهینه استفاده کند و ممکن است دقتی نزدیک به نانوثانیه ارائه دهد. CLOCK_HIGHRES ساعت غیرقابل‌تنظیم و با دقت بالا است.

دسترس‌پذیری: Solaris.

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

time.CLOCK_MONOTONIC

ساعتی که نمی‌توان آن را تنظیم کرد و زمان یکنواخت را از یک نقطه‌ی آغاز نامشخص نشان می‌دهد.

دسترس‌پذیری: Unix.

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

time.CLOCK_MONOTONIC_RAW

مشابه CLOCK_MONOTONIC، اما دسترسی به زمان خام مبتنی بر سخت‌افزار را فراهم می‌کند که مشمول تنظیم‌های NTP نمی‌شود.

دسترس‌پذیری: Linux >= 2.6.28, macOS >= 10.12.

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

time.CLOCK_MONOTONIC_RAW_APPROX

مشابه CLOCK_MONOTONIC_RAW، اما مقداری را می‌خواند که سیستم آن را هنگام تعویض زمینه در نهانگاه ذخیره کرده است و بنابراین دقت کمتری دارد.

دسترس‌پذیری: macOS >= 10.12.

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

time.CLOCK_PROCESS_CPUTIME_ID

زمان‌سنج با دقت بالا به‌ازای هر فرایند از CPU.

دسترس‌پذیری: Unix.

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

time.CLOCK_PROF

زمان‌سنج با دقت بالا به‌ازای هر فرایند از CPU.

دسترس‌پذیری: FreeBSD, NetBSD >= 7, OpenBSD.

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

time.CLOCK_TAI

زمان اتمی بین‌المللی

سیستم باید یک جدول به‌روز از ثانیه‌های کبیسه داشته باشد تا این مورد پاسخ صحیح بدهد. نرم‌افزار PTP یا NTP می‌تواند جدول ثانیه‌های کبیسه را نگه‌داری کند.

دسترس‌پذیری: Linux.

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

time.CLOCK_THREAD_CPUTIME_ID

ساعت زمان CPU مختص به نخ.

دسترس‌پذیری: Unix.

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

time.CLOCK_UPTIME

زمانی که مقدار مطلق آن، مدت زمانی است که سیستم در حال اجرا بوده و تعلیق نشده است و اندازه‌گیری دقیق زمان کارکرد (uptime) را هم به‌صورت مطلق و هم به‌صورت بازه‌ای فراهم می‌کند.

دسترس‌پذیری: FreeBSD, OpenBSD >= 5.5.

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

time.CLOCK_UPTIME_RAW

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

دسترس‌پذیری: macOS >= 10.12.

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

time.CLOCK_UPTIME_RAW_APPROX

مانند CLOCK_UPTIME_RAW، اما مقدار در تعویض‌های زمینه توسط سیستم در نهانگاه ذخیره می‌شود و بنابراین دقت کمتری دارد.

دسترس‌پذیری: macOS >= 10.12.

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

ثابت زیر تنها پارامتری است که می‌توان به clock_settime() ارسال کرد.

time.CLOCK_REALTIME

ساعت بلادرنگ. تنظیم این ساعت نیازمند دسترسی‌های مناسب است. این ساعت برای تمام فرآیندها یکسان است.

دسترس‌پذیری: Unix.

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

ثابت‌های منطقه زمانی

time.altzone

اختلاف منطقه زمانی محلی DST، بر حسب ثانیه در غرب UTC، در صورتی که تعریف شده باشد. اگر منطقه زمانی محلی DST در شرق UTC باشد (مانند اروپای غربی، از جمله بریتانیا)، این مقدار منفی است. تنها در صورتی از این استفاده کنید که daylight ناصفر باشد. یادداشت زیر را ببینید.

time.daylight

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

time.timezone

آفست منطقه زمانی محلی (غیر DST)، بر حسب ثانیه در غرب UTC (در بیشتر اروپای غربی منفی، در ایالات متحده مثبت، در بریتانیا صفر). یادداشت زیر را ببینید.

time.tzname

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

توجه

برای ثابت‌های منطقه زمانی بالا (altzone، daylight، timezone و tzname)، مقدار آن‌ها بر اساس قواعد منطقه زمانی حاکم در زمان بارگذاری ماژول یا آخرین باری که tzset() فراخوانی شده است تعیین می‌شود و ممکن است برای زمان‌های گذشته نادرست باشد. توصیه می‌شود برای دریافت اطلاعات منطقه زمانی از نتایج tm_gmtoff و tm_zone حاصل از localtime() استفاده کنید.

همچنین ملاحظه نمائید

ماژول datetime

رابط شیءگراتر برای تاریخ‌ها و زمان‌ها.

ماژول locale

خدمات بین‌المللی‌سازی. تنظیمات locale بر تفسیر بسیاری از مشخص‌کننده‌های قالب در strftime() و strptime() تأثیر می‌گذارد.

ماژول calendar

توابع عمومی مرتبط با گاه‌شماری. timegm() معکوس gmtime() از این ماژول است.

پانویس‌ها

[1] (1,2,3)

استفاده از %Z اکنون منسوخ شده است، اما دنباله‌ی خنثی‌سازی %z که به آفست ساعت/دقیقه‌ی ترجیحی گسترش می‌یابد، در همه‌ی کتابخانه‌های ANSI C پشتیبانی نمی‌شود. همچنین، خوانش دقیق از استاندارد اصلی سال ۱۹۸۲ یعنی RFC 822، سال دورقمی (%y به جای %Y) را می‌طلبد، اما رویه بسیار پیش از سال ۲۰۰۰ به سال‌های ۴‌رقمی تغییر یافت. پس از آن، RFC 822 منسوخ شد و سال ۴‌رقمی ابتدا توسط RFC 1123 توصیه شد و سپس توسط RFC 2822 الزامی شد، و RFC 5322 نیز این الزام را ادامه داده است.