16.3. time – Время: доступ и преобразования¶time – Time access and conversions

---

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

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

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

• Эпоха – это точка отсчёта времени, зависит от платформы. В Unix эпоха – 1 января 1970 года, 00:00:00 (UTC). Чтобы узнать эпоху для конкретной платформы, обратитесь к time.gmtime(0).

• Термин секунды с начала эпохи обозначает общее количество прошедших секунд с момента эпохи, обычно без учёта високосных секунд. Високосные секунды не включаются в эту сумму на всех платформах, соответствующих POSIX.

• Функции этого модуля могут не поддерживать даты и время до эпохи или далёкого будущего. Граница в будущем определяется библиотекой C; для 32-битных систем она обычно приходится на 2038 год.

• Проблемы 2000 года (Y2K): Python полагается на библиотеку C платформы, в которой обычно нет проблем 2000 года, поскольку все даты и время внутренне представлены в виде секунд от эпохи. Функция strptime() может разбирать двузначные годы при указании кода формата %y. При разборе двузначных лет они преобразуются в соответствии со стандартами POSIX и ISO C: значения 69–99 отображаются на 1969–1999, а значения 0–68 – на 2000–2068.

• 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.

  Изменено в версии 3.3: Тип struct_time расширен, чтобы предоставлять атрибуты tm_gmtoff и tm_zone, если платформа поддерживает соответствующие члены struct tm.

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

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

Модуль определяет следующие функции и элементы данных:

time.altzone¶

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

time.asctime([t])¶

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

Примечание

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

time.clock()¶

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

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

Устарело с версии 3.3: Поведение этой функции зависит от платформы: используйте perf_counter() или process_time() взамен, в зависимости от требований, чтобы получить четко определенное поведение.

time.clock_getres(clk_id)¶

Возвращает разрешение (точность) указанных часов clk_id.

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

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

time.clock_gettime(clk_id)¶

Возвращает время указанных часов clk_id.

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

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

time.clock_settime(clk_id, time)¶

Устанавливает время указанных часов clk_id.

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

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

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 или новее.

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

time.CLOCK_PROCESS_CPUTIME_ID¶

Высокоточный таймер для каждого процесса, предоставляемый ЦП.

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

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

time.CLOCK_REALTIME¶

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

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

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

time.CLOCK_THREAD_CPUTIME_ID¶

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

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

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

time.ctime([secs])¶

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

time.daylight¶

Не равно нулю, если часовой пояс с переходом на летнее время (DST) определён.

time.get_clock_info(name)¶

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

• 'clock': time.clock()
• 'monotonic': time.monotonic()
• 'perf_counter': time.perf_counter()
• 'process_time': time.process_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, когда для указанного времени действует летнее время.

time.mktime(t)¶

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

time.monotonic()¶

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

В версиях Windows старше Vista функция monotonic() обнаруживает переполнение целого GetTickCount() (32 бита, сброс через 49,7 дней). Каждый раз при обнаружении переполнения она увеличивает внутреннюю эпоху (опорное время) на 2³². Эпоха хранится в состоянии процесса, поэтому значение monotonic() может различаться в двух процессах Python, работающих более 49 дней. В более новых версиях Windows и в других операционных системах monotonic() является общесистемным.

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

Изменено в версии 3.5: Функция теперь доступна всегда.

time.perf_counter()¶

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

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

time.process_time()¶

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

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

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

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

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

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

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

Изменено в версии 3.3: tm_gmtoff и tm_zone атрибуты доступны на платформах с библиотекой C, поддерживающей соответствующие поля в struct tm.

time.time()¶

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

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

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

time.timezone¶

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

time.tzname¶

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

time.tzset()¶

Сбрасывает правила преобразования времени, используемые библиотечными подпрограммами. Переменная окружения TZ указывает, как это делается.

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