15.3. time – Доступ ко времени и преобразования¶time – Time access and conversions

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

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

Необходимо пояснить некоторую терминологию и соглашения.

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

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

• Проблема 2000 года (Y2K): Python зависит от системной библиотеки C, у которой обычно нет проблем с 2000 годом, поскольку все даты и время внутренне представлены в секундах с начала эпохи. Функции, принимающие struct_time (см. ниже), как правило, требуют четырёхзначный год. Для обратной совместимости двузначные годы поддерживаются, если переменная модуля accept2dyear – ненулевое целое; эта переменная инициализируется значением 1, если только переменная окружения PYTHONY2K не установлена в непустую строку – в этом случае она инициализируется значением 0. Таким образом, можно установить PYTHONY2K в непустую строку в окружении, чтобы требовать четырёхзначный год для всех вводимых годов. Когда двузначные годы принимаются, они преобразуются по стандарту 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¶

Логическое значение, указывающее, принимаются ли двузначные значения года. По умолчанию истинно, но будет установлено в ложь, если переменная окружения 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() возвращает зависимую от локали байтовую строку; результат можно преобразовать в unicode с помощью 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")   
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 (не-летнее время, секунды к западу от UTC), altzone (летнее время, секунды к западу от UTC) и daylight (в 0, если часовой пояс не имеет правил перехода на летнее время, или в ненулевое значение, если существует время – прошлое, настоящее или будущее – когда применяется летнее время).

Новое в версии 2.3.

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

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

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