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. В настоящее время допустимо только значение CLOCK_REALTIME для clk_id.

Используйте 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 в качестве флага dst), который задаёт время в местном часовом поясе, а не в 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, если secs равен нулю, поток уступает оставшуюся часть своего кванта времени любому другому готовому к выполнению потоку. Если других готовых к выполнению потоков нет, функция немедленно возвращает управление, и поток продолжает выполнение. В Windows 8.1 и новее реализация использует таймер высокого разрешения с разрешением 100 наносекунд. Если secs равен нулю, используется Sleep(0).

Реализация для Unix:

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

Изменено в версии 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)
%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]
%%	Литерал '%'.

Примечания:

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_day	диапазон [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

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

Сноски