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.

Для получения подходящего значения 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, когда 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.11: В Unix, функции clock_nanosleep() и nanosleep() теперь используются, если доступны. В Windows теперь используется ожидающий таймер.

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

time.strftime(format[, t])

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

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

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

Директива	Значение	Примечания
%a	Сокращённое имя дня недели в формате локали.
%A	Полное имя дня недели в формате локали.
%b	Сокращённое имя месяца в формате локали.
%B	Полное имя месяца в формате локали.
%c	Соответствующее представленuе даты и времени в формате локали.
%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().

Параметр формат использует те же директивы, что и strftime(); он по умолчанию равен "%a %b %d %H:%M:%S %Y", что соответствует формату, возвращаемому ctime(). Если строку string нельзя разобрать в соответствии с форматом, или если после разбора есть избыточные данные, генерируется ValueError. Значения по умолчанию, используемые для заполнения отсутствующих данных, когда более точные значения нельзя вывести, — (1900, 1, 1, 0, 0, 0, 0, 1, -1). И string, и формат должны быть строками.

Например:

>>> 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; см. ниже
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 (секунды по Гринвичу без учета летнего времени), altzone (секунды по Гринвичу с учетом летнего времени) и 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

Часы 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

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

Примечания

1(1,2,3)

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