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 системного таймера CPU для указанного потока с идентификатором thread_id.

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

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

Передача некорректного или устаревшего 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 когда 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

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

Используйте 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 должен быть строкой. ValueError генерируется, если какой-либо элемент в t выходит за допустимый диапазон.

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_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-систем лишние секунды не учитываются при подсчете времени в секундах с момента эпохи. Это обычно называется временем Unix.

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

Число, возвращаемое функцией 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-й день. День ноль — воскресенье.

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

Высокоточный таймер для каждого процесса из 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

Время, абсолютное значение которого — время работы системы без приостановок, обеспечивая точное измерение времени работы, как абсолютное, так и интервальное.

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

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

Примечания