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.

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

  Из	В	Используйте
  секунды с эпохи	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

Не равно нулю, если определено летнее время.

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

Значение 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; см. ниже
N/A	tm_zone	сокращение имени часового пояса
N/A	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

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

time.tzname

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

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

Примечания