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

---

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

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

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

• Эпоха (epoch) – это точка начала отсчёта времени, которая зависит от платформы. Для 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 – это летнее время (Daylight Saving Time), корректировка часового пояса (обычно) на один час в определённый период года. Правила 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.

  Изменено в версии 3.6: Атрибуты struct_time tm_gmtoff и tm_zone теперь доступны на всех платформах.

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

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

16.3.1. Функции

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

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

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

time.clock_gettime(clk_id)¶

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

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

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

time.clock_settime(clk_id, time)¶

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

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

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

time.ctime([secs])¶

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

time.get_clock_info(имя)¶

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

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

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 является допустимым аргументом для любой позиции в кортеже времени; если обычно это недопустимо, значение принудительно приводится к корректному.

Следующие директивы можно встраивать в строку формата. Они показаны без необязательных спецификаций ширины поля и точности и заменяются на указанные символы в 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(строка[, формат])¶

Разбирает строку, представляющую время, в соответствии с форматом. Возвращаемое значение – 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")   
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() не зависит от платформы и поэтому не обязательно поддерживает все доступные директивы, которые не задокументированы как поддерживаемые.

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

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

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

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

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-й день. День 0 – воскресенье.

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')

16.3.2. Константы идентификаторов часов

Эти константы используются в качестве параметров для clock_getres() и clock_gettime().

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_THREAD_CPUTIME_ID¶

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

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

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

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

time.CLOCK_REALTIME¶

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

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

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

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

time.altzone¶

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

time.daylight¶

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

time.timezone¶

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

time.tzname¶

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

Примечание

Для указанных выше констант часовых поясов (altzone, daylight, timezone и tzname) значение определяется правилами часовых поясов, действующими на момент загрузки модуля или последнего вызова tzset(), и может быть некорректным для моментов в прошлом. Рекомендуется использовать результаты tm_gmtoff и tm_zone из localtime() для получения информации о часовом поясе.

Смотрите также

Модуль datetime

Более объектно-ориентированный интерфейс для дат и времени.

Модуль locale

Сервисы интернационализации. Настройка локали влияет на интерпретацию многих спецификаторов формата в strftime() и strptime().

Модуль calendar

Общие функции, связанные с календарём. timegm() – это обратная функция для gmtime() из этого модуля.

Сноски

1

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