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

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

  Изменено в версии 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(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 при применении DST к заданному времени.

time.mktime(t)

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

time.monotonic()

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

В версиях Windows, более ранних, чем Vista, monotonic() обнаруживает переполнение целочисленного значения (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(), в строку, согласно аргументу формат. Если 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 — десятичные цифры часов, а М — десятичные цифры минут [-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().

Параметр формат использует те же директивы, что и функция strftime(); по умолчанию он равен "%a %b %d %H:%M:%S %Y", что соответствует формату, возвращаемому функцией ctime(). Если строка не может быть разобрана согласно формату или в ней есть избыточные данные после разбора, генерируется исключение 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; см. ниже
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 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')

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

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

time.timezone

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

time.tzname

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

Примечания

1

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