time — Доступ к времени и преобразования

Функции

time.asctime([t])

Преобразует кортеж или struct_time, представляющий время, в формате, возвращаемом функцией gmtime() или localtime(), в строку следующего вида: 'Sun Jun 20 23:21:05 1993'. Поле дня состоит из двух символов; если день представлен одной цифрой, перед ней ставится пробел, например: 'Wed Jun  9 04:26:40 1993'.

Если t не задан, используется текущее время в формате, возвращаемом функцией localtime(). Функция asctime() не использует сведения о локали.

Примечание

В отличие от одноимённой функции C, asctime() не добавляет завершающий символ новой строки.

time.pthread_getcpuclockid(thread_id)

Возвращает clk_id часов процессорного времени, относящихся к указанному потоку thread_id.

Чтобы получить подходящее значение для thread_id, используйте threading.get_ident() или атрибут ident объектов threading.Thread.

Предупреждение

Передача недействительного или уже несуществующего thread_id может привести к неопределённому поведению, например к ошибке сегментации.

Доступность: Unix

Дополнительные сведения см. на справочной странице pthread_getcpuclockid(3).

Добавлено в версии 3.7.

time.clock_getres(clk_id)

Возвращает разрешение (точность) указанных часов clk_id. Список допустимых значений clk_id см. в разделе Константы идентификаторов часов.

Доступность: Unix.

Добавлено в версии 3.3.

time.clock_gettime(clk_id) → float

Возвращает время указанных часов clk_id. Список допустимых значений clk_id см. в разделе Константы идентификаторов часов.

Используйте clock_gettime_ns(), чтобы избежать потери точности, вызванной типом float.

Доступность: Unix.

Добавлено в версии 3.3.

time.clock_gettime_ns(clk_id) → int

Аналогична clock_gettime(), но возвращает время в наносекундах.

Доступность: Unix.

Добавлено в версии 3.7.

time.clock_settime(clk_id, time: float)

Устанавливает время указанных часов clk_id. В настоящее время для clk_id допускается только значение CLOCK_REALTIME.

Используйте clock_settime_ns(), чтобы избежать потери точности, вызванной типом float.

Доступность: Unix.

Добавлено в версии 3.3.

time.clock_settime_ns(clk_id, time: int)

Аналогична clock_settime(), но устанавливает время в наносекундах.

Доступность: Unix.

Добавлено в версии 3.7.

time.ctime([secs])

Преобразует время, выраженное в секундах с начала эпохи, в строку вида: 'Sun Jun 20 23:21:05 1993', представляющую местное время. Поле дня состоит из двух символов; если день представлен одной цифрой, перед ней ставится пробел, например: 'Wed Jun  9 04:26:40 1993'.

Если secs не задан или равен None, используется текущее время в формате, возвращаемом функцией time(). ctime(secs) эквивалентно asctime(localtime(secs)). Функция 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, если часы можно изменять автоматически (например, службой NTP) или вручную системным администратором, и False в противном случае
• implementation: имя базовой функции C, используемой для получения значения часов. Возможные значения см. в разделе Константы идентификаторов часов.
• monotonic: True, если часы не могут идти назад, и False в противном случае
• resolution: разрешение часов в секундах (тип float)

Добавлено в версии 3.3.

time.gmtime([secs])

Преобразует время, выраженное в секундах с начала эпохи, в объект struct_time в UTC, в котором флаг dst всегда равен нулю. Если secs не задан или равен None, используется текущее время в формате, возвращаемом функцией time(). Доли секунды игнорируются. Описание объекта struct_time см. выше. Обратной для этой функции является calendar.timegm().

time.localtime([secs])

Подобна gmtime(), но преобразует время в местное. Если secs не задан или равен None, используется текущее время в формате, возвращаемом функцией time(). Если для указанного времени действует летнее время, флаг dst устанавливается в 1.

localtime() может вызвать исключение OverflowError, если временная метка выходит за диапазон значений, поддерживаемый функциями C-платформы localtime() или gmtime(), и OSError при ошибке localtime() или gmtime(). Часто допустимый диапазон ограничен годами с 1970 по 2038.

time.mktime(t)

Это обратная функция для localtime(). Её аргументом является struct_time или полный кортеж из 9 элементов (так как необходим флаг dst; если его значение неизвестно, используйте -1), задающий время в местной временной зоне, а не в UTC. Функция возвращает число с плавающей точкой для совместимости с time(). Если входное значение нельзя представить как допустимое время, возникает исключение OverflowError или ValueError (в зависимости от того, перехватывается ли недопустимое значение Python или нижележащими библиотеками C). Самая ранняя дата, для которой функция может сформировать время, зависит от платформы.

time.monotonic() → float

Возвращает значение (в долях секунды) монотонных часов, то есть часов, которые не могут идти назад. На эти часы не влияют изменения системных часов. Точка отсчёта возвращаемого значения не определена, поэтому допустимо использовать только разность результатов двух вызовов.

Используйте monotonic_ns(), чтобы избежать потери точности, вызванной типом float.

Добавлено в версии 3.3.

Изменено в версии 3.5: Теперь функция всегда доступна и всегда работает в масштабе всей системы.

Изменено в версии 3.10: В macOS функция теперь работает в масштабе всей системы.

time.monotonic_ns() → int

Аналогична monotonic(), но возвращает время в наносекундах.

Добавлено в версии 3.7.

time.perf_counter() → float

Возвращает значение (в долях секунды) счётчика производительности, то есть часов с максимально доступным разрешением для измерения коротких интервалов времени. Счётчик учитывает время, прошедшее во время сна, и работает в масштабе всей системы. Точка отсчёта возвращаемого значения не определена, поэтому допустимо использовать только разность результатов двух вызовов.

Используйте perf_counter_ns(), чтобы избежать потери точности, вызванной типом float.

Добавлено в версии 3.3.

Изменено в версии 3.10: В Windows функция теперь работает в масштабе всей системы.

time.perf_counter_ns() → int

Аналогична perf_counter(), но возвращает время в наносекундах.

Добавлено в версии 3.7.

time.process_time() → float

Возвращает значение (в долях секунды), равное сумме системного и пользовательского процессорного времени текущего процесса. Время, прошедшее во время сна, не учитывается. По определению функция работает в масштабе всего процесса. Точка отсчёта возвращаемого значения не определена, поэтому допустимо использовать только разность результатов двух вызовов.

Используйте process_time_ns(), чтобы избежать потери точности, вызванной типом float.

Добавлено в версии 3.3.

time.process_time_ns() → int

Аналогична process_time(), но возвращает время в наносекундах.

Добавлено в версии 3.7.

time.sleep(secs)

Приостанавливает выполнение вызывающего потока на заданное количество секунд. Аргумент может быть числом с плавающей точкой, чтобы указать более точную длительность ожидания.

Если ожидание прерывается сигналом и обработчик сигнала не вызывает исключение, ожидание начинается заново с пересчитанным тайм-аутом.

Приостановка может длиться произвольно дольше запрошенного времени из-за планирования других процессов в системе.

Реализация в Windows

В Windows, если secs равно нулю, поток уступает оставшуюся часть своего временного интервала любому другому готовому к выполнению потоку. Если других готовых потоков нет, функция немедленно возвращает управление, и поток продолжает выполнение. В Windows 8.1 и новее используется таймер высокого разрешения с разрешением 100 наносекунд. Если secs равно нулю, используется Sleep(0).

Реализация в Unix

• Если доступна, используется clock_nanosleep() (разрешение: 1 наносекунда);
• Или, если доступна, используется nanosleep() (разрешение: 1 наносекунда);
• Или используется select() (разрешение: 1 микросекунда).

Примечание

Чтобы имитировать «пустую операцию», используйте pass вместо time.sleep(0).

Чтобы добровольно уступить процессор, укажите реальную политику планирования и используйте os.sched_yield().

Изменено в версии 3.5: Теперь функция ожидает не менее secs, даже если ожидание прерывается сигналом, за исключением случаев, когда обработчик сигнала вызывает исключение (обоснование см. в PEP 475).

Изменено в версии 3.11: В Unix теперь используются функции clock_nanosleep() и nanosleep(), если они доступны. В Windows теперь используется таймер ожидания.

time.strftime(format[, t])

Преобразует кортеж или struct_time, представляющий время, в формате, возвращаемом функцией gmtime() или localtime(), в строку согласно аргументу format. Если t не задан, используется текущее время в формате, возвращаемом функцией localtime(). format должен быть строкой. Если какое-либо поле в t выходит за допустимый диапазон, возникает исключение ValueError.

0 является допустимым аргументом для любой позиции в кортеже времени; если обычно он недопустим, значение принудительно заменяется корректным.

В строку format можно включать следующие директивы. Они приведены без необязательного указания ширины поля и точности; в результате strftime() они заменяются указанными символами:

Директива	Значение	Примечания
%a	Сокращённое название дня недели согласно локали.
%A	Полное название дня недели согласно локали.
%b	Сокращённое название месяца согласно локали.
%B	Полное название месяца согласно локали.
%c	Представление даты и времени согласно локали.
%d	День месяца в виде десятичного числа [01,31].
%f	Микросекунды в виде десятичного числа [000000,999999].	(1)
%H	Час (24-часовой формат) в виде десятичного числа [00,23].
%I	Час (12-часовой формат) в виде десятичного числа [01,12].
%j	День года в виде десятичного числа [001,366].
%m	Месяц в виде десятичного числа [01,12].
%M	Минута в виде десятичного числа [00,59].
%p	Обозначение AM или PM согласно локали.	(2)
%S	Секунда в виде десятичного числа [00,61].	(3)
%U	Номер недели года (воскресенье считается первым днём недели) в виде десятичного числа [00,53]. Все дни нового года до первого воскресенья считаются днями недели 0.	(4)
%u	День недели (понедельник — 1; воскресенье — 7) в виде десятичного числа [1, 7].
%w	День недели в виде десятичного числа [0 (воскресенье), 6].
%W	Номер недели года (понедельник считается первым днём недели) в виде десятичного числа [00,53]. Все дни нового года до первого понедельника считаются днями недели 0.	(4)
%x	Представление даты согласно локали.
%X	Представление времени согласно локали.
%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 допустимо в метках времени, соответствующих високосным секундам, а значение 61 поддерживается по историческим причинам.
4. При использовании с функцией strptime() значения %U и %W используются в вычислениях только в том случае, если указаны день недели и год.

Ниже приведён пример формата даты, совместимого с форматом, заданным стандартом интернет-почты RFC 2822. [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).

На некоторых платформах за начальным '%' директивы могут сразу следовать необязательные указания ширины поля и точности в указанном порядке; это также непереносимо. Ширина поля обычно равна 2, за исключением %j, для которого она равна 3.

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(). Это объект с интерфейсом именованного кортежа: значения доступны по индексу и имени атрибута. В объекте присутствуют следующие значения:

Индекс	Атрибут	Значения
0	tm_year	(например, 1993)
1	tm_mon	диапазон [1, 12]
2	tm_mday	диапазон [1, 31]
3	tm_hour	диапазон [0, 23]
4	tm_min	диапазон [0, 59]
5	tm_sec	диапазон [0, 61]; см. примечание (2) в описании strftime()
6	tm_wday	диапазон [0, 6]; понедельник — 0
7	tm_yday	диапазон [1, 366]
8	tm_isdst	0, 1 или -1; см. ниже
Н/Д	tm_zone	аббревиатура названия часового пояса
Н/Д	tm_gmtoff	смещение к востоку от UTC в секундах

Обратите внимание: в отличие от структуры C, значение месяца находится в диапазоне [1, 12], а не [0, 11].

При вызове mktime() атрибуту tm_isdst можно присвоить значение 1, если действует летнее время, и 0, если оно не действует. Значение -1 означает, что это неизвестно; обычно в этом случае будет подставлено правильное значение.

Если функции, ожидающей объект struct_time, передать кортеж неверной длины или содержащий элементы неправильного типа, возникает исключение TypeError.

time.time() → float

Возвращает время в секундах с момента начала эпохи в виде числа с плавающей запятой. Обработка високосных секунд зависит от платформы. В Windows и большинстве систем Unix високосные секунды не учитываются при подсчёте времени в секундах с момента начала эпохи. Это обычно называют временем Unix.

Обратите внимание: хотя время всегда возвращается в виде числа с плавающей запятой, не все системы обеспечивают точность времени лучше одной секунды. Обычно эта функция возвращает неубывающие значения, однако может вернуть значение меньше предыдущего, если между вызовами системные часы были переведены назад.

Число, возвращённое функцией time(), можно преобразовать в более привычный формат времени (например, год, месяц, день, час и т. д.) в UTC, передав его функции gmtime(), или в местное время, передав его функции localtime(). В обоих случаях возвращается объект struct_time, атрибуты которого позволяют получить компоненты календарной даты.

Используйте time_ns(), чтобы избежать потери точности, связанной с типом float.

time.time_ns() → int

Аналогична time(), но возвращает время в виде целого числа наносекунд с момента начала эпохи.

Добавлена в версии 3.7.

time.thread_time() → float

Возвращает значение (в долях секунды), равное сумме системного и пользовательского процессорного времени текущего потока. Время, проведённое в ожидании, не учитывается. По определению, значение относится к конкретному потоку. Точка отсчёта возвращаемого значения не определена, поэтому имеет смысл только разность результатов двух вызовов в одном и том же потоке.

Используйте thread_time_ns(), чтобы избежать потери точности, связанной с типом float.

Доступность: Linux, Unix, Windows.

Системы Unix с поддержкой CLOCK_THREAD_CPUTIME_ID.

Добавлена в версии 3.7.

time.thread_time_ns() → int

Аналогична thread_time(), но возвращает время в наносекундах.

Добавлена в версии 3.7.

time.tzset()

Сбрасывает правила преобразования времени, используемые библиотечными функциями. Переменная окружения TZ определяет, как это выполняется. Также будут заданы переменные tzname (из переменной окружения TZ), timezone (число секунд к западу от UTC без учёта летнего времени), altzone (число секунд к западу от UTC с учётом летнего времени) и daylight (0, если для этого часового пояса не предусмотрены правила летнего времени, или ненулевое значение, если существует время — в прошлом, настоящем или будущем, — когда действует летнее время).

Доступность: Unix.

Примечание

Хотя во многих случаях изменение переменной окружения TZ может повлиять на результат таких функций, как localtime(), даже без вызова tzset(), полагаться на такое поведение не следует.

Переменная окружения TZ не должна содержать пробельных символов.

Стандартный формат переменной окружения TZ имеет следующий вид (пробелы добавлены для наглядности):

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

Компоненты:

std and dst

Три или более буквенно-цифровых символа, задающих аббревиатуры часовых поясов. Они будут записаны в time.tzname.

offset

Смещение имеет вид: ± hh[:mm[:ss]]. Оно обозначает значение, которое нужно прибавить к местному времени, чтобы получить UTC. Если перед смещением стоит знак «-», часовой пояс находится к востоку от нулевого меридиана; в противном случае — к западу. Если после dst смещение не указано, предполагается, что летнее время опережает стандартное на один час.

start[/time], end[/time]

Указывает, когда переходить на летнее время и обратно. Даты начала и окончания задаются одним из следующих способов:

Jn

Юлианский день n (1 <= n <= 365). Високосные дни не учитываются, поэтому во всех годах 28 февраля — это день 59, а 1 марта — день 60.

n

Юлианский день с нумерацией от нуля (0 <= n <= 365). Високосные дни учитываются, поэтому можно указать 29 февраля.

Mm.n.d

d-й день (0 <= d <= 6) недели n месяца m года (1 <= n <= 5, 1 <= m <= 12; неделя 5 означает «последний день d месяца m», который может приходиться на четвёртую или пятую неделю). Неделя 1 — первая неделя, в которой встречается день d. День 0 — воскресенье.

time имеет тот же формат, что и offset, за исключением того, что начальный знак («-» или «+») не допускается. Если время не указано, по умолчанию используется 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'

Во многих системах Unix (включая *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_PROCESS_CPUTIME_ID

Таймер процессорного времени высокого разрешения для отдельного процесса.

Доступность: Unix.

Добавлена в версии 3.3.

time.CLOCK_PROF

Таймер процессорного времени высокого разрешения для отдельного процесса.

Доступность: FreeBSD, NetBSD >= 7, OpenBSD.

Добавлена в версии 3.7.

time.CLOCK_TAI

Международное атомное время

Для получения правильного результата в системе должна быть актуальная таблица високосных секунд. Программное обеспечение PTP или NTP может поддерживать такую таблицу.

Доступность: Linux.

Добавлена в версии 3.9.

time.CLOCK_THREAD_CPUTIME_ID

Часы процессорного времени, относящиеся к отдельному потоку.

Доступность: Unix.

Добавлена в версии 3.3.

time.CLOCK_UPTIME

Часы, абсолютное значение которых соответствует времени работы системы без учёта периодов приостановки; обеспечивают точное измерение времени непрерывной работы как в абсолютных величинах, так и за интервал.

Доступность: FreeBSD, OpenBSD >= 5.5.

Добавлена в версии 3.7.

time.CLOCK_UPTIME_RAW

Часы, которые монотонно увеличиваются, отсчитывая время с произвольного момента; на них не влияют корректировки частоты или времени, и они не увеличиваются, пока система находится в спящем режиме.

Доступность: macOS >= 10.12.

Добавлена в версии 3.8.

Следующая константа — единственный параметр, который можно передать функции clock_settime().

time.CLOCK_REALTIME

Системные часы реального времени. Для установки этих часов требуются соответствующие права.

Доступность: Unix.

Добавлена в версии 3.3.

Константы часовых поясов

time.altzone

Смещение местного часового пояса с летним временем в секундах к западу от UTC, если такой пояс определён. Значение отрицательно, если местный часовой пояс с летним временем находится к востоку от UTC (как в Западной Европе, включая Великобританию). Используйте эту константу, только если daylight не равно нулю. См. примечание ниже.

time.daylight

Ненулевое значение, если определён часовой пояс с летним временем. См. примечание ниже.

time.timezone

Смещение местного часового пояса (без летнего времени) в секундах к западу от UTC (отрицательное значение в большей части Западной Европы, положительное — в США, нулевое — в Великобритании). См. примечание ниже.

time.tzname

Кортеж из двух строк: первая — название местного часового пояса без летнего времени, вторая — название местного часового пояса с летним временем. Если часовой пояс с летним временем не определён, вторую строку использовать не следует. См. примечание ниже.

Сноски