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

Функции

time.asctime([t])

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

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

Примечание

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

time.pthread_getcpuclockid(thread_id)

Возвращает clk_id таймера процессорного времени для указанного потока thread_id.

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

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

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

Доступность: Unix (см. страницу руководства для pthread_getcpuclockid(3) для дополнительной информации).

Введено в версии 3.7.

time.clock_getres(clk_id)

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

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

Введено в версии 3.3.

time.clock_gettime(clk_id) → float

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

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

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

Введено в версии 3.3.

time.clock_gettime_ns(clk_id) → int

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

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

Введено в версии 3.7.

time.clock_settime(clk_id, time: float)

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

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

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

Введено в версии 3.3.

time.clock_settime_ns(clk_id, time: int)

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

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

Введено в версии 3.7.

time.ctime([secs])

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

Если secs не указано или равно None, используется текущее время, возвращаемое time(). ctime(secs) эквивалентно asctime(localtime(secs)). Информация о локали не используется функцией ctime().

time.get_clock_info(name)

Получает информацию об указанном таймере в виде объекта пространства имен. Поддерживаемые имена таймеров и соответствующие функции для считывания их значений:

• 'monotonic': time.monotonic()
• 'perf_counter': time.perf_counter()
• 'process_time': time.process_time()
• 'thread_time': time.thread_time()
• 'time': time.time()

Результат имеет следующие атрибуты:

• adjustable: True если таймер может быть изменён автоматически (например, демоном NTP) или вручную системным администратором, False иначе
• implementation: Название базовой C-функции, используемой для получения значения таймера. Возможные значения см. в разделе Константы идентификаторов таймеров.
• monotonic: True если таймер не может идти назад, False иначе
• resolution: Разрешение таймера в секундах (float)

Введено в версии 3.3.

time.gmtime([secs])

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

time.localtime([secs])

Аналогично gmtime(), но преобразует в местное время. Если secs не указано или равно None, используется текущее время, возвращаемое time(). Флаг dst устанавливается в 1 при применении 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)

Приостанавливает выполнение вызывающей потока на заданное количество секунд. Аргумент может быть числом с плавающей точкой, чтобы указать более точное время ожидания. Фактическое время приостановки может быть меньше запрошенного, потому что любой пойманный сигнал завершит выполнение 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]. Все дни в новом году, предшествующие первому воскресенью, считаются нулевой неделей.	(3)
%w	День недели как десятичное число [0(воскресенье),6].
%W	Номер недели в году (понедельник — первый день недели) как десятичное число [00,53]. Все дни в новом году, предшествующие первому понедельнику, считаются нулевой неделей.	(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_ns(), чтобы избежать потери точности, вызванной типом float.

time.time_ns() → int

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

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

time.thread_time() → float

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

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

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

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

time.thread_time_ns() → int

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

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

time.tzset()

Перезадает правила преобразования времени, используемые библиотечными процедурами. Переменная среды TZ определяет, как это делается. Она также устанавливает переменные tzname (из переменной среды TZ), timezone (секунды до DST к западу от UTC), altzone (секунды DST к западу от 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.