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.

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

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

Доступность: 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].
%Z	Имя часового пояса (без символов, если часовой пояс отсутствует).
%%	Буквальный символ '%'.

Примечания:

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(). Если строку строка невозможно разобрать по формату или в ней есть избыточные данные после разбора, генерируется исключение ValueError. По умолчанию используются значения, заполняющие отсутствующие данные, когда более точные значения нельзя вывести, (1900, 1, 1, 0, 0, 0, 0, 1, -1). И строка, и формат должны быть строками.

Например:

>>> 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_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

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

Примечания

1

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