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().

Примечание

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

time.pthread_getcpuclockid(thread_id)¶

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

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

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

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

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

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

time.clock_getres(clk_id)¶

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

Availability: Unix.

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

time.clock_gettime(clk_id) → float¶

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

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

Availability: Unix.

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

time.clock_gettime_ns(clk_id) → int¶

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

Availability: Unix.

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

time.clock_settime(clk_id, time: float)¶

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

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

Availability: Unix.

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

time.clock_settime_ns(clk_id, time: int)¶

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

Availability: 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()

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

• регулируемый: True если часы могут быть изменены автоматически (например, демоном NTP) или вручную системным администратором, False иначе

• реализация: Имя базовой функции языка Си, используемой для получения значения часов. Возможные значения см. в Константы идентификатора тактового генератора.

• монотонный: True если часы не могут идти назад, False в противном случае

• разрешение: Разрешение часов в секундах (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: Теперь функция спит не менее * секунд*, даже если сон прерывается сигналом, за исключением случаев, когда обработчик сигнала вызывает исключение (см. обоснование в PEP 475).

time.strftime(format[, t])¶

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

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

В строку формат могут быть встроены следующие директивы. Они показаны без необязательного указания ширины поля и точности, и заменяются указанными символами в результате 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 действительно для временных меток, представляющих leap seconds, а значение 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). И 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(). Это объект с интерфейсом named tuple: доступ к значениям возможен по индексу и по имени атрибута. Присутствуют следующие значения:

Индекс	Атрибут	Значения
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; см. ниже
Н/Д	tm_zone	аббревиатура названия часового пояса
Н/Д	tm_gmtoff	смещение к востоку от UTC в секундах

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

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

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

time.time() → float¶

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

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

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

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

time.time_ns() → int¶

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

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

time.thread_time() → float¶

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

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

Availability: Windows, Linux, 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, если в этом часовом поясе нет правил перехода на летнее время, или в ненулевое значение, если есть время, прошлое, настоящее или будущее, когда применяется переход на летнее время).

Availability: Unix.

Примечание

Хотя во многих случаях изменение переменной окружения TZ может повлиять на вывод функций типа localtime() без вызова tzset(), на такое поведение не следует полагаться.

Переменная окружения TZ не должна содержать пробелов.

Стандартный формат переменной среды TZ следующий (пробелы добавлены для ясности):

std offset [dst [offset [,start[/time], end[/time]]]]

Где находятся компоненты:

std и dst.

Три или более буквенно-цифровых символа, дающих сокращение часового пояса. Они будут перенесены в time.tzname

offset

Смещение имеет вид: ± hh[:mm[:ss]]. Это указывает величину, к которой добавляется местное время для получения UTC. Если смещению предшествует знак „-“, то часовой пояс находится к востоку от главного меридиана, в противном случае - к западу. Если за dst не следует смещение, летнее время принимается на один час раньше стандартного.

start[/time], end[/time]

Указывает время перехода на DST и обратно. Формат начальной и конечной дат - один из следующих:

Jn

Юлианский день n (1 <= n <= 365). Високосные дни не учитываются, поэтому во все годы 28 февраля - это 59-й день, а 1 марта - 60-й день.

n

Нулевой юлианский день (0 <= n <= 365). Високосные дни учитываются, и можно ссылаться на 29 февраля.

Mm.n.d

День d’th (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() или подобным образом.

Availability: Linux 2.6.39 или более поздней версии.

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

time.CLOCK_HIGHRES¶

В ОС Solaris есть таймер CLOCK_HIGHRES, который пытается использовать оптимальный аппаратный источник и может давать разрешение, близкое к наносекундному. CLOCK_HIGHRES - это нерегулируемые часы с высоким разрешением.

Availability: Solaris.

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

time.CLOCK_MONOTONIC¶

Часы, которые не могут быть установлены и представляют собой монотонное время с некоторой неопределенной начальной точки.

Availability: Unix.

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

time.CLOCK_MONOTONIC_RAW¶

Аналогично CLOCK_MONOTONIC, но предоставляет доступ к необработанному аппаратному времени, которое не подвержено корректировкам NTP.

Availability: Linux 2.6.28 и новее, macOS 10.12 и новее.

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

time.CLOCK_PROCESS_CPUTIME_ID¶

Таймер высокого разрешения для каждого процесса от центрального процессора.

Availability: Unix.

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

time.CLOCK_PROF¶

Таймер высокого разрешения для каждого процесса от центрального процессора.

Availability: FreeBSD, NetBSD 7 или более поздняя версия, OpenBSD.

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

time.CLOCK_TAI¶

International Atomic Time

Для правильного ответа система должна иметь актуальную таблицу високосных секунд. Программное обеспечение PTP или NTP может поддерживать таблицу високосных секунд.

Availability: Linux.

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

time.CLOCK_THREAD_CPUTIME_ID¶

Часы процессорного времени, специфичные для конкретного потока.

Availability: Unix.

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

time.CLOCK_UPTIME¶

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

Availability: FreeBSD, OpenBSD 5.5 или более поздней версии.

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

time.CLOCK_UPTIME_RAW¶

Часы, которые монотонно увеличиваются, отслеживая время с произвольного момента, не подвержены влиянию частотных или временных корректировок и не увеличиваются, пока система находится в спящем режиме.

Availability: macOS 10.12 и новее.

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

Следующая константа является единственным параметром, который может быть отправлен в clock_settime().

time.CLOCK_REALTIME¶

Общесистемные часы реального времени. Установка этих часов требует соответствующих привилегий.

Availability: Unix.

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

Константы часовых поясов¶

time.altzone¶

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

time.daylight¶

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

time.timezone¶

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

time.tzname¶

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

Сноски

1(1,2,3)

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