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

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

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

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

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

• Функции этого модуля могут не поддерживать даты и время до эпохи или далёкого будущего. Граница в будущем определяется библиотекой 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¶

Смещение местного часового пояса с учётом летнего времени, в секундах к западу от UTC, если оно определено. Отрицательное, если местный часовой пояс с летним временем находится к востоку от 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, но в любом случае эту функцию следует использовать для бенчмаркинга Python или замера времени алгоритмов.

В 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])¶

Convert a time expressed in seconds since the epoch to a string representing local time. If secs is not provided or None, the current time as returned by time() is used. ctime(secs) is equivalent to asctime(localtime(secs)). Locale information is not used by 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: The resolution of the clock in seconds (float)

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

time.gmtime([secs])¶

Convert a time expressed in seconds since the epoch to a struct_time in UTC in which the dst flag is always zero. If secs is not provided or None, the current time as returned by time() is used. Fractions of a second are ignored. See above for a description of the struct_time object. See calendar.timegm() for the inverse of this function.

time.localtime([secs])¶

Like gmtime() but converts to local time. If secs is not provided or None, the current time as returned by time() is used. The dst flag is set to 1 when DST applies to the given time.

time.mktime(t)¶

This is the inverse function of localtime(). Its argument is the struct_time or full 9-tuple (since the dst flag is needed; use -1 as the dst flag if it is unknown) which expresses the time in local time, not UTC. It returns a floating point number, for compatibility with time(). If the input value cannot be represented as a valid time, either OverflowError or ValueError will be raised (which depends on whether the invalid value is caught by Python or the underlying C libraries). The earliest date for which it can generate a time is platform-dependent.

time.monotonic()¶

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

On Windows versions older than Vista, monotonic() detects GetTickCount() integer overflow (32 bits, roll-over after 49.7 days). It increases an internal epoch (reference time) by 2³² each time that an overflow is detected. The epoch is stored in the process-local state and so the value of monotonic() may be different in two Python processes running for more than 49 days. On more recent versions of Windows and on other operating systems, monotonic() is system-wide.

Доступность: Windows, Mac OS X, Linux, FreeBSD, OpenBSD, Solaris.

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

time.perf_counter()¶

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

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

time.process_time()¶

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

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

time.sleep(secs)¶

Приостанавливает выполнение на указанное количество секунд. Аргумент может быть числом с плавающей запятой для более точного указания времени ожидания. Фактическое время приостановки может быть меньше запрошенного, так как любой перехваченный сигнал завершит выполнение sleep() после выполнения подпрограммы обработки этого сигнала. Кроме того, время приостановки может быть больше запрошенного на произвольную величину из-за планирования других активностей в системе.

time.strftime(format[, t])¶

Convert a tuple or struct_time representing a time as returned by gmtime() or localtime() to a string as specified by the format argument. If t is not provided, the current time as returned by localtime() is used. format must be a string. ValueError is raised if any field in t is outside of the allowed range.

0 является допустимым аргументом для любой позиции в кортеже времени; если обычно это недопустимо, значение принудительно приводится к корректному.

The following directives can be embedded in the format string. They are shown without the optional field width and precision specification, and are replaced by the indicated characters in the strftime() result:

Директива	Значение	Примечания
%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")   
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	range [0, 61]; see (2) in strftime() description
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]. Аргумент -1 в качестве флага летнего времени, передаваемый в mktime(), обычно приводит к корректному заполнению состояния летнего времени.

When a tuple with an incorrect length is passed to a function expecting a struct_time, or having elements of the wrong type, a TypeError is raised.

Changed in version 3.3: tm_gmtoff and tm_zone attributes are available on platforms with C library supporting the corresponding fields in struct tm.

time.time()¶

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

time.timezone¶

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

time.tzname¶

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

time.tzset()¶

Resets the time conversion rules used by the library routines. The environment variable TZ specifies how this is done.

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

Примечание

Although in many cases, changing the TZ environment variable may affect the output of functions like localtime() without calling tzset(), this behavior should not be relied on.

The TZ environment variable should contain no whitespace.

The standard format of the TZ environment variable is (whitespace added for clarity):

std offset [dst [offset [,start[/time], end[/time]]]]

Где компоненты имеют следующее значение:

std and dst

Три или более буквенно-цифровых символа, обозначающие аббревиатуры часовых поясов. Они будут переданы в time.tzname.

offset

The offset has the form: ± hh[:mm[:ss]]. This indicates the value added the local time to arrive at UTC. If preceded by a ‘-‘, the timezone is east of the Prime Meridian; otherwise, it is west. If no offset follows dst, summer time is assumed to be one hour ahead of standard time.

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 has the same format as offset except that no leading sign (‘-‘ or ‘+’) is allowed. The default, if time is not given, is 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 теперь считается устаревшим, но управляющая последовательность %z, которая раскрывается в предпочтительное смещение в часах/минутах, поддерживается не всеми библиотеками ANSI C. Кроме того, строгое прочтение оригинального стандарта RFC 822 1982 года требует двузначного года (%y, а не %Y), но на практике перешли на четырёхзначные годы задолго до 2000 года. После этого RFC 822 устарел, и четырёхзначный год был сначала рекомендован RFC 1123, а затем закреплён в RFC 2822.