توابع¶

time.asctime([time_tuple])¶

یک تاپل یا struct_time را که زمان بازگردانده‌شده توسط gmtime() یا localtime() را نشان می‌دهد، به رشته‌ای به فرم زیر تبدیل کنید: 'Sun Jun 20 23:21:05 1993'. فیلد روز دو نویسه طول دارد و اگر روز تک‌رقمی باشد با فاصله پر می‌شود، برای مثال: 'Wed Jun  9 04:26:40 1993'.

اگر پارامتر time_tuple ارائه نشود، از زمان فعلی بازگردانده‌شده توسط localtime() استفاده می‌شود. اطلاعات locale توسط 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, /)¶

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

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

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

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

تغییر یافته در نسخه‌ی 3.15: هر عدد حقیقی را به عنوان time می‌پذیرد، نه فقط عدد صحیح یا عدد اعشاری.

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

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

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

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

time.ctime(seconds=None, /)¶

زمانی را که بر حسب ثانیه از epoch گذشته است، به رشته‌ای به فرم 'Sun Jun 20 23:21:05 1993' که نشان‌دهنده‌ی زمان محلی است، تبدیل کنید. فیلد روز دو نویسه طول دارد و اگر روز تک‌رقمی باشد با فاصله پر می‌شود، برای مثال: 'Wed Jun  9 04:26:40 1993'.

اگر seconds ارائه نشود یا None باشد، از زمان فعلی بازگردانده‌شده توسط time() استفاده می‌شود. عبارت ctime(seconds) معادل asctime(localtime(seconds)) است. اطلاعات locale توسط ctime() استفاده نمی‌شود.

تغییر یافته در نسخه‌ی 3.15: هر عدد حقیقی را می‌پذیرد، نه فقط عدد صحیح یا عدد اعشاری.

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, /)¶

زمانی را که بر حسب ثانیه از epoch گذشته است، به یک شیء struct_time در زمان UTC تبدیل می‌کند که در آن پرچم dst همیشه صفر است. اگر seconds ارائه نشود یا None باشد، از زمان فعلی بازگردانده‌شده توسط time() استفاده می‌شود. کسرهای ثانیه نادیده گرفته می‌شوند. برای توضیحات درباره‌ی شیء struct_time به بالا مراجعه کنید. برای معکوس این تابع، calendar.timegm() را ببینید.

تغییر یافته در نسخه‌ی 3.15: هر عدد حقیقی را می‌پذیرد، نه فقط عدد صحیح یا عدد اعشاری.

time.localtime(seconds=None, /)¶

مانند gmtime() است اما به زمان محلی تبدیل می‌کند. اگر seconds فراهم نشده باشد یا None باشد، زمان فعلی که توسط time() برگردانده شده است استفاده می‌شود. پرچم dst روی 1 تنظیم می‌شود هنگامی که زمان صرفه‌جویی در نور روز (DST) برای زمان داده‌شده اعمال می‌شود.

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

تغییر یافته در نسخه‌ی 3.15: هر عدد حقیقی را می‌پذیرد، نه فقط عدد صحیح یا عدد اعشاری.

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 با مهلت زمانی بازمحاسبه‌شده دوباره آغاز می‌شود.

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

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

در ویندوز، اگر seconds برابر با صفر باشد، نخ باقی‌مانده‌ی اسلایس زمانی خود را به هر نخ دیگری که آماده‌ی اجرا است واگذار می‌کند. اگر هیچ نخ دیگری آماده‌ی اجرا نباشد، تابع بلافاصله برمی‌گردد و نخ به اجرای خود ادامه می‌دهد. در ویندوز ۱۰ و نسخه‌های جدیدتر، پیاده‌سازی از یک high-resolution timer استفاده می‌کند که وضوح ۱۰۰ نانوثانیه را فراهم می‌کند. اگر seconds صفر باشد، از Sleep(0) استفاده می‌شود.

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

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

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

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

نکته

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

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

یک رویداد حسابرسی time.sleep با آرگومان seconds ایجاد می‌کند.

تغییر یافته در نسخه‌ی 3.5: این تابع اکنون حداقل به مدت seconds متوقف می‌شود، حتی اگر توقف توسط یک سیگنال متوقف شود، مگر اینکه هندلر سیگنال یک استثنا ایجاد کند (برای دلیل آن به PEP 475 مراجعه کنید).

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

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

تغییر یافته در نسخه‌ی 3.15: هر عدد حقیقی را می‌پذیرد، نه فقط عدد صحیح یا عدد اعشاری.

time.strftime(format[, time_tuple])¶

یک تاپل یا struct_time که زمان بازگردانده‌شده توسط gmtime() یا localtime() را نشان می‌دهد، به رشته‌ای تبدیل کنید که توسط آرگومان format مشخص شده است. اگر time_tuple فراهم نشده باشد، زمان فعلی بازگردانده‌شده توسط localtime() استفاده می‌شود. format باید یک رشته باشد. اگر هر فیلدی در time_tuple خارج از محدوده‌ی مجاز باشد، ValueError ایجاد می‌شود.

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

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

دایرکتیو	معنی	یادداشت‌ها
%a	نام کوتاه‌شده‌ی روز هفته بر اساس locale.
%A	نام کامل روز هفته بر اساس locale.
%b	نام کوتاه‌شده‌ی ماه در locale .
%B	نام کامل ماهِ تنظیمات locale .
%c	نمایش مناسب تاریخ و زمان متناسب با تنظیمات locale .
%d	روز ماه به‌صورت عدد دهدهی [01,31].
%f	میکروثانیه به‌صورت عدد اعشاری	(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() استفاده کنید.

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¶

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

پانویس‌ها