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 см. в Константы идентификаторов таймеров.

Доступность: 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.

Доступность: 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 при применении DST к заданному времени.

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

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

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

Изменено в версии 3.5: Функция теперь всегда доступна и всегда глобальна.

time.monotonic_ns() → int

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

Новая в версии 3.7.

time.perf_counter() → float

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

Новая в версии 3.3.

time.perf_counter_ns() → int

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

Новая в версии 3.7.

time.process_time() → float

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

Новая в версии 3.3.

time.process_time_ns() → int

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

Новая в версии 3.7.

time.sleep(secs)

Приостанавливает выполнение вызывающей нити на заданное количество секунд. Аргумент может быть числом с плавающей точкой для более точного управления временем ожидания. Фактическое время приостановки может быть меньше запрошенного, так как любой пойманный сигнал завершит sleep() после выполнения обработчика этого сигнала. Кроме того, время приостановки может быть больше запрошенного на произвольную величину из-за планирования других активностей в системе.

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

time.strftime(format[, t])

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

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

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

Директива	Значение	Примечания
%a	Сокращённое имя дня недели в локали.
%A	Полное имя дня недели в локали.
%b	Сокращённое имя месяца в локали.
%B	Полное имя месяца в локали.
%c	Представление даты и времени в локали.
%d	День месяца в виде десятичной цифры [01,31].
%H	Час (24-часовой формат) в виде десятичной цифры [00,23].
%I	Час (12-часовой формат) в виде десятичной цифры [01,12].
%j	Номер дня в году в виде десятичной цифры [001,366].
%m	Номер месяца в виде десятичной цифры [01,12].
%M	Минута в виде десятичной цифры [00,59].
%p	Локальный эквивалент AM или PM.	(1)
%S	Секунда в виде десятичной цифры [00,61].	(2)
%U	Номер недели в году (воскресенье — первый день недели) в виде десятичной цифры [00,53]. Все дни в новом году до первого воскресенья считаются неделей 0.	(3)
%w	Номер дня недели в виде десятичной цифры [0(воскресенье),6].
%W	Номер недели в году (понедельник — первый день недели) в виде десятичной цифры [00,53]. Все дни в новом году до первого понедельника считаются неделей 0.	(3)
%x	Представление даты в локали.
%X	Представление времени в локали.
%y	Год без века в виде десятичной цифры [00,99].
%Y	Год с веком в виде десятичной цифры.
%z	Смещение часового пояса, указывающее на положительное или отрицательное различие во времени от UTC/GMT в формате +HHMM или -HHMM, где H обозначает десятичные цифры часа, а M — десятичные цифры минуты [-23:59, +23:59]. 1
%Z	Имя часового пояса (без символов, если часовой пояс отсутствует). Устарело. 1
%%	Буквальное '%'.

Примечания:

1. При использовании с функцией strptime(), директива %p влияет только на поле часа вывода, если используется директива %I для анализа часа.
2. Диапазон реально 0 до 61; значение 60 допустимо в метках времени, представляющих лип-секунды, а значение 61 поддерживается по историческим причинам.
3. При использовании с функцией 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; см. ниже
N/A	tm_zone	аббревиатура названия часового пояса
N/A	tm_gmtoff	смещение к востоку от UTC в секундах

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

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

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

time.time() → float

Возвращает время в секундах с момента эпохи в виде числа с плавающей запятой. Конкретная дата эпохи и обработка високосных секунд зависят от платформы. В Windows и на большинстве Unix-систем эпоха — 1 января 1970 года, 00:00:00 (UTC), а високосные секунды не учитываются при подсчете времени в секундах с момента эпохи. Это обычно называется временем Unix. Чтобы узнать, какова эпоха на данной платформе, обратитесь к gmtime(0).

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

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

time.thread_time() → float

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

Доступность: Windows, Linux, Unix-системы, поддерживающие CLOCK_THREAD_CPUTIME_ID.

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

time.thread_time_ns() → int

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

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

time.time_ns() → int

Аналогично 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-й день. День ноль — воскресенье.

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

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

time.daylight

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

time.timezone

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

time.tzname

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

Примечания

1(1,2,3)

Использование %Z устарело, но %z escape, расширяющийся до предпочтительного смещения часа/минуты, не поддерживается всеми библиотеками ANSI C. Кроме того, строгое прочтение исходного стандарта RFC 822 1982 года требует двухзначного года (%y вместо %Y), но практика перешла к четырёхзначным годам задолго до 2000 года. После этого RFC 822 устарел, и четырёхзначный год был сначала рекомендован RFC 1123, а затем стал обязательным в RFC 2822.