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

Этот модуль предоставляет различные функции, связанные со временем. Для функций, относящихся к датам и времени, см. также модули datetime и calendar.

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

Следует пояснить некоторые термины и соглашения.

• Эпоха — точка отсчёта времени. 1 января данного года в 0 часов «время с момента эпохи» равно нулю. Для Unix эпоха — 1970 год. Чтобы узнать, какая эпоха используется, обратитесь к gmtime(0).

• Функции в этом модуле не обрабатывают даты и время до эпохи или слишком отдалённого будущего. Точка отсечения в будущем определяется библиотекой C; для Unix, как правило, это 2038 год.

• Проблемы с годом 2000 (Y2K): Python зависит от платформенной библиотеки C, которая, как правило, не имеет проблем с годом 2000, так как все даты и время внутренне представлены в виде секунд с момента эпохи. Функции, принимающие struct_time (см. ниже), обычно требуют 4-значного года. Для обратной совместимости 2-значные годы поддерживаются, если модульная переменная accept2dyear имеет ненулевое значение; эта переменная инициализируется значением 1, если переменная окружения PYTHONY2K не пустая строка, в противном случае она инициализируется значением 0. Таким образом, вы можете установить PYTHONY2K в переменной окружения на ненулевое значение, чтобы потребовать 4-значные годы для всех входных данных года. Когда принимаются 2-значные годы, они преобразуются в соответствии со стандартами POSIX или X/Open: значения от 69 до 99 сопоставляются со значениями 1969-1999, а значения от 0 до 68 - со значениями 2000-2068. Значения от 100 до 1899 всегда недопустимы.

• UTC — это Координированное универсальное время (ранее известное как всемирное стандартное время, или GMT). Аббревиатура UTC не является ошибкой, а является компромиссом между английским и французским языками.

• DST — это летнее время, корректировка часового пояса (обычно) на один час в течение части года. Правила DST — это магия (определяются местным законодательством) и могут меняться из года в год. Библиотека C содержит таблицу с местными правилами (часто она считывается из системного файла для гибкости) и является единственным источником истинных знаний в этом вопросе.
• Точность различных функций реального времени может быть меньше, чем предполагается по единицам измерения их значения или аргумента. Например, на большинстве систем Unix часы «тикают» только 50 или 100 раз в секунду.
• С другой стороны, точность time() и sleep() лучше, чем у их эквивалентов Unix: время выражается как числа с плавающей точкой, time() возвращает самое точное доступное время (используя Unix gettimeofday(), если доступно), а sleep() примет время с ненулевой дробной частью (для реализации этого используется Unix select(), если доступно).

• Значение времени, возвращаемое gmtime(), localtime() и strptime(), и принимаемое asctime(), mktime() и strftime(), можно рассматривать как последовательность из 9 целых чисел. Значения, возвращаемые gmtime(), localtime() и strptime(), также предлагают имена атрибутов для отдельных полей.

  См. struct_time для описания этих объектов.

  Изменено в версии 2.2: Значение времени было изменено из кортежа в struct_time с добавлением имён атрибутов для полей.

• Для преобразования между представлениями времени используйте следующие функции:

  Из	В	Используйте
  секунды с момента эпохи	struct_time в UTC	gmtime()
  секунды с момента эпохи	struct_time в местном времени	localtime()
  struct_time в UTC	секунды с момента эпохи	calendar.timegm()
  struct_time в местном времени	секунды с момента эпохи	mktime()

В модуле определены следующие функции и данные:

time.accept2dyear

Булево значение, указывающее, будут ли приниматься двухзначные значения года. По умолчанию это True, но будет установлено в False, если переменная окружения PYTHONY2K задана ненулевой строкой. Она также может быть изменена во время выполнения.

time.altzone

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

time.asctime([t])

Преобразует кортеж или struct_time, представляющий время, как возвращается gmtime() или localtime(), в строку длиной 24 символа следующего формата: 'Sun Jun 20 23:21:05 1993'. Если t не указан, используется текущее время, возвращаемое localtime(). Информация о локали не используется функцией asctime().

Примечание

В отличие от одноимённой функции C, нет заключительного символа новой строки.

Изменено в версии 2.1: Допускается опускание параметра t.

time.clock()

В Unix возвращает текущее процессорное время в виде числа с плавающей точкой, выраженного в секундах. Точность и, фактически, само определение значения «процессорного времени» зависит от одноимённой функции C, но в любом случае это функция, которую следует использовать для бенчмаркинга Python или измерения времени выполнения алгоритмов.

В Windows эта функция возвращает прошедшие секунды реального времени с момента первого вызова этой функции в виде числа с плавающей точкой, основанные на функции Win32 QueryPerformanceCounter(). Разрешение обычно лучше, чем одна микросекунда.

time.ctime([secs])

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

Изменено в версии 2.1: Допускается опускание параметра secs.

Изменено в версии 2.4: Если secs равно None, используется текущее время.

time.daylight

Не равно нулю, если определен часовой пояс DST.

time.gmtime([secs])

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

Изменено в версии 2.1: Разрешено опустить secs.

Изменено в версии 2.4: Если secs равен None, используется текущее время.

time.localtime([secs])

Аналогично gmtime(), но преобразует в местное время. Если secs не указан или равен None, используется текущее время, возвращаемое time(). Флаг dst устанавливается в 1 при применении летнего времени к заданному времени.

Изменено в версии 2.1: Разрешено опустить secs.

Изменено в версии 2.4: Если secs равен None, используется текущее время.

time.mktime(t)

Это обратная функция localtime(). Ее аргумент — struct_time или полная 9-кортеж (поскольку необходим флаг dst; используйте -1 в качестве флага dst, если он неизвестен), который выражает время в местном времени, а не UTC. Возвращает число с плавающей точкой для совместимости с time(). Если входное значение не может быть представлено как допустимое время, будет поднято исключение OverflowError или ValueError (в зависимости от того, поймано ли недопустимое значение Python или базовыми C-библиотеками). Самая ранняя дата, для которой он может сгенерировать время, зависит от платформы.

time.sleep(secs)

Приостановить выполнение текущей нити на указанное количество секунд. Аргумент может быть числом с плавающей точкой для указания более точного времени сна. Фактическое время приостановки может быть меньше запрошенного, потому что любой пойманный сигнал завершит sleep() после выполнения процедуры обработки этого сигнала. Кроме того, время приостановки может быть больше запрошенного на произвольную величину из-за планирования другой активности в системе.

time.strftime(format[, t])

Преобразовать кортеж или struct_time, представляющий время, как возвращается gmtime() или localtime(), в строку, как указано в аргументе format. Если t не указан, используется текущее время, возвращаемое localtime(). format должен быть строкой. ValueError возникает, если какое-либо поле в t выходит за пределы допустимого диапазона. strftime() возвращает зависящую от локали строку байтов; результат можно преобразовать в юникод, выполнив strftime(<myformat>).decode(locale.getlocale()[1]).

Изменено в версии 2.1: Разрешено опустить t.

Изменено в версии 2.4: ValueError возбуждается, если поле в t находится вне диапазона.

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

Примечания:

1. При использовании с функцией strptime(), директива %p влияет только на поле часа вывода, если директива %I используется для анализа часа.
2. Диапазон действительно от 0 до 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).

Например:

>>> import time
>>> time.strptime("30 Nov 00", "%d %b %y")   # doctest: +NORMALIZE_WHITESPACE
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; см. ниже

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

Обратите внимание, что в отличие от C-структуры, значение месяца имеет диапазон [1, 12], а не [0, 11]. Значение года будет обрабатываться в соответствии с описанием в разделе Проблемы с годом 2000 (Y2K).

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

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

time.time()

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

time.timezone

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

time.tzname

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

time.tzset()

Переустановка правил преобразования времени, используемых библиотечными процедурами. Переменная окружения TZ определяет, как это делается. Она также устанавливает переменные tzname (из переменной окружения TZ), timezone (секунды без DST к западу от UTC), altzone (секунды с DST к западу от UTC) и daylight (в 0, если в этом часовом поясе нет правил летнего времени, или в ненулевое значение, если существует время, в прошлом, настоящем или будущем, когда действует летнее время).

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

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

Примечания

1

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