`time.md`

446 строк · 32.3 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/3.0/library/time.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# `time` – Доступ ко времени и преобразования89Этот модуль предоставляет различные функции для работы со временем. За дополнительными возможностями обращайтесь также к модулям [`datetime`](https://python-all.ru/3.0/library/datetime.html#module-datetime) и [`calendar`](https://python-all.ru/3.0/library/calendar.html#module-calendar).1011Хотя этот модуль доступен всегда, не все функции доступны на всех платформах. Большинство функций, определённых в этом модуле, вызывают одноимённые функции из библиотеки C платформы. Иногда может быть полезно обратиться к документации платформы, так как семантика этих функций различается в разных системах.1213Необходимо пояснить некоторую терминологию и соглашения.1415>1617- *Эпоха* – это точка отсчёта времени. 1 января этого года в 0 часов «время с начала эпохи» равно нулю. Для Unix эпоха – 1970 год. Чтобы узнать, что такое эпоха, посмотрите на `gmtime(0)`.18- Функции этого модуля не обрабатывают даты и время до начала эпохи или далеко в будущем. Точка отсечения в будущем определяется библиотекой C; для Unix она обычно приходится на 2038 год.19- **Проблемы 2000 года (Y2K)**: Python зависит от библиотеки C платформы, в которой обычно нет проблем 2000 года, так как все даты и время представлены внутренне как секунды с начала эпохи. Функции, принимающие [`struct_time`](https://python-all.ru/3.0/library/time.html#time.struct_time) (см. ниже), обычно требуют четырёхзначный год. Для обратной совместимости двузначные годы поддерживаются, если переменная модуля `accept2dyear` – ненулевое целое; эта переменная инициализируется значением `1`, если переменная окружения [**PYTHONY2K**](https://python-all.ru/3.0/using/cmdline.html#envvar-PYTHONY2K) не установлена в непустую строку; в этом случае она инициализируется значением `0`. Таким образом, можно установить [**PYTHONY2K**](https://python-all.ru/3.0/using/cmdline.html#envvar-PYTHONY2K) в непустую строку в окружении, чтобы требовать четырёхзначные годы для всего ввода года. Если двузначные годы принимаются, они преобразуются согласно стандарту POSIX или X/Open: значения 69–99 отображаются на 1969–1999, а значения 0–68 – на 2000–2068. Значения 100–1899 всегда недопустимы. Обратите внимание, что это нововведение начиная с Python 1.5.2(a2); более ранние версии вплоть до Python 1.5.1 и 1.5.2a1 добавляли 1900 к значениям года ниже 1900.20- UTC – это Всемирное координированное время (ранее известно как среднее время по Гринвичу, или GMT). Аббревиатура UTC – не ошибка, а компромисс между английским и французским языками.21- DST – это летнее время, корректировка часового пояса (обычно на один час) в течение части года. Правила DST магические (определяются местным законодательством) и могут меняться от года к году. Библиотека C содержит таблицу с местными правилами (часто она считывается из системного файла для гибкости) и является единственным источником Истинной Мудрости в этом отношении.22- Точность различных функций реального времени может быть ниже, чем предполагают единицы, в которых выражается их значение или аргумент. Например, на большинстве Unix-систем тактовая частота составляет всего 50 или 100 тиков в секунду.23- С другой стороны, точность [`time()`](https://python-all.ru/3.0/library/time.html#time.time) и [`sleep()`](https://python-all.ru/3.0/library/time.html#time.sleep) выше, чем у их Unix-аналогов: значения времени представлены числами с плавающей запятой, [`time()`](https://python-all.ru/3.0/library/time.html#time.time) возвращает максимально точное доступное время (используя Unix `gettimeofday`, где это возможно), а [`sleep()`](https://python-all.ru/3.0/library/time.html#time.sleep) принимает время с ненулевой дробной частью (для реализации используется Unix `select`, где это возможно).24- Значение времени, возвращаемое функциями [`gmtime()`](https://python-all.ru/3.0/library/time.html#time.gmtime), [`localtime()`](https://python-all.ru/3.0/library/time.html#time.localtime) и [`strptime()`](https://python-all.ru/3.0/library/time.html#time.strptime) и принимаемое функциями [`asctime()`](https://python-all.ru/3.0/library/time.html#time.asctime), [`mktime()`](https://python-all.ru/3.0/library/time.html#time.mktime) и [`strftime()`](https://python-all.ru/3.0/library/time.html#time.strftime), представляет собой последовательность из 9 целых чисел. Возвращаемые значения [`gmtime()`](https://python-all.ru/3.0/library/time.html#time.gmtime), [`localtime()`](https://python-all.ru/3.0/library/time.html#time.localtime) и [`strptime()`](https://python-all.ru/3.0/library/time.html#time.strptime) также предоставляют имена атрибутов для отдельных полей.2526  | Индекс | Атрибут | Значения |27  | --- | --- | --- |28  | 0 | `tm_year` | (например, 1993) |29  | 1 | `tm_mon` | диапазон \[1,12\] |30  | 2 | `tm_mday` | диапазон \[1,31\] |31  | 3 | `tm_hour` | диапазон \[0,23\] |32  | 4 | `tm_min` | диапазон \[0,59\] |33  | 5 | `tm_sec` | диапазон \[0,61\]; см. **(1)** в описании [`strftime()`](https://python-all.ru/3.0/library/time.html#time.strftime) |34  | 6 | `tm_wday` | диапазон \[0,6\], понедельник – 0 |35  | 7 | `tm_yday` | диапазон \[1,366\] |36  | 8 | `tm_isdst` | 0, 1 или -1; см. ниже |3738  Обратите внимание, что в отличие от структуры C, значение месяца находится в диапазоне 1–12, а не 0–11. Значение года обрабатывается, как описано в разделе «Проблема 2000 года (Y2K)» выше. Аргумент `-1` в качестве флага перехода на летнее время, передаваемый в [`mktime()`](https://python-all.ru/3.0/library/time.html#time.mktime), обычно приводит к правильному заполнению состояния летнего времени.3940  Когда функции, ожидающей [`struct_time`](https://python-all.ru/3.0/library/time.html#time.struct_time), передается кортеж неправильной длины или с элементами неверного типа, возникает [`TypeError`](https://python-all.ru/3.0/library/exceptions.html#exceptions.TypeError).4142Модуль определяет следующие функции и элементы данных:4344#### `[time.accept2dyear]time.accept2dyear`4546Логическое значение, указывающее, будут ли приниматься двузначные значения года. По умолчанию оно истинно, но устанавливается в ложное, если переменная окружения4748[**PYTHONY2K**](https://python-all.ru/3.0/using/cmdline.html#envvar-PYTHONY2K)4950была установлена в непустую строку. Это значение также может быть изменено во время выполнения.5152#### `[time.altzone]time.altzone`5354Смещение местного часового пояса с учётом летнего времени, в секундах к западу от UTC, если оно определено. Отрицательное, если местный часовой пояс с летним временем находится к востоку от UTC (как в Западной Европе, включая Великобританию). Используйте это только если5556`daylight`5758не равен нулю.5960#### `[time.asctime]time.asctime([t])`6162Преобразует кортеж или [`struct_time`](https://python-all.ru/3.0/library/time.html#time.struct_time), представляющий время, как возвращённый функцией [`gmtime()`](https://python-all.ru/3.0/library/time.html#time.gmtime) или [`localtime()`](https://python-all.ru/3.0/library/time.html#time.localtime), в 24-символьную строку следующего вида: `'Sun Jun 20 23:21:05 1993'`. Если *t* не указан, используется текущее время, возвращаемое функцией [`localtime()`](https://python-all.ru/3.0/library/time.html#time.localtime). Локаль не используется функцией [`asctime()`](https://python-all.ru/3.0/library/time.html#time.asctime).6364> **Примечание**65>66> В отличие от одноименной функции в C, в конце строки нет символа новой строки.6768#### `[time.clock]time.clock()`6970В Unix возвращает текущее процессорное время в виде числа с плавающей запятой, выраженного в секундах. Точность и, по сути, само определение понятия «процессорное время» зависит от одноимённой функции C, но в любом случае эту функцию следует использовать для бенчмаркинга Python или замера времени алгоритмов.7172В Windows эта функция возвращает количество секунд реального времени, прошедших с момента первого вызова этой функции, в виде числа с плавающей запятой, на основе функции Win32 `QueryPerformanceCounter`. Разрешение обычно лучше одной микросекунды.7374#### `[time.ctime]time.ctime([secs])`7576Convert a time expressed in seconds since the epoch to a string representing local time. If7778*secs*7980is not provided or8182[`None`](https://python-all.ru/3.0/library/constants.html#None)8384, the current time as returned by8586[`time()`](https://python-all.ru/3.0/library/time.html#time.time)8788is used.8990`ctime(secs)`9192is equivalent to9394`asctime(localtime(secs))`9596. Locale information is not used by9798[`ctime()`](https://python-all.ru/3.0/library/time.html#time.ctime)99100.101102#### `[time.daylight]time.daylight`103104Не равно нулю, если часовой пояс с переходом на летнее время (DST) определён.105106#### `[time.gmtime]time.gmtime([secs])`107108Convert a time expressed in seconds since the epoch to a109110[`struct_time`](https://python-all.ru/3.0/library/time.html#time.struct_time)111112in UTC in which the dst flag is always zero. If113114*secs*115116is not provided or117118[`None`](https://python-all.ru/3.0/library/constants.html#None)119120, the current time as returned by121122[`time()`](https://python-all.ru/3.0/library/time.html#time.time)123124is used. Fractions of a second are ignored. See above for a description of the125126[`struct_time`](https://python-all.ru/3.0/library/time.html#time.struct_time)127128object. See129130[`calendar.timegm()`](https://python-all.ru/3.0/library/calendar.html#calendar.timegm)131132for the inverse of this function.133134#### `[time.localtime]time.localtime([secs])`135136Like137138[`gmtime()`](https://python-all.ru/3.0/library/time.html#time.gmtime)139140but converts to local time. If141142*secs*143144is not provided or145146[`None`](https://python-all.ru/3.0/library/constants.html#None)147148, the current time as returned by149150[`time()`](https://python-all.ru/3.0/library/time.html#time.time)151152is used. The dst flag is set to153154`1`155156when DST applies to the given time.157158#### `[time.mktime]time.mktime(t)`159160This is the inverse function of161162[`localtime()`](https://python-all.ru/3.0/library/time.html#time.localtime)163164. Its argument is the165166[`struct_time`](https://python-all.ru/3.0/library/time.html#time.struct_time)167168or full 9-tuple (since the dst flag is needed; use169170`-1`171172as the dst flag if it is unknown) which expresses the time in173174*local*175176time, not UTC. It returns a floating point number, for compatibility with177178[`time()`](https://python-all.ru/3.0/library/time.html#time.time)179180. If the input value cannot be represented as a valid time, either181182[`OverflowError`](https://python-all.ru/3.0/library/exceptions.html#exceptions.OverflowError)183184or185186[`ValueError`](https://python-all.ru/3.0/library/exceptions.html#exceptions.ValueError)187188will 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.189190#### `[time.sleep]time.sleep(secs)`191192Приостанавливает выполнение на указанное количество секунд. Аргумент может быть числом с плавающей запятой для более точного указания времени ожидания. Фактическое время приостановки может быть меньше запрошенного, так как любой перехваченный сигнал завершит выполнение193194[`sleep()`](https://python-all.ru/3.0/library/time.html#time.sleep)195196после выполнения подпрограммы обработки этого сигнала. Кроме того, время приостановки может быть больше запрошенного на произвольную величину из-за планирования других активностей в системе.197198#### `[time.strftime]time.strftime(format[, t])`199200Convert a tuple or [`struct_time`](https://python-all.ru/3.0/library/time.html#time.struct_time) representing a time as returned by [`gmtime()`](https://python-all.ru/3.0/library/time.html#time.gmtime) or [`localtime()`](https://python-all.ru/3.0/library/time.html#time.localtime) to a string as specified by the *format* argument. If *t* is not provided, the current time as returned by [`localtime()`](https://python-all.ru/3.0/library/time.html#time.localtime) is used. *format* must be a string. [`ValueError`](https://python-all.ru/3.0/library/exceptions.html#exceptions.ValueError) is raised if any field in *t* is outside of the allowed range.2012020 является допустимым аргументом для любой позиции в кортеже времени; если обычно это недопустимо, значение принудительно приводится к корректному.203204The 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()`](https://python-all.ru/3.0/library/time.html#time.strftime) result:205206| Директива | Значение | Примечания |207| --- | --- | --- |208| `%a` | Сокращённое название дня недели в соответствии с локалью. |  |209| `%A` | Полное название дня недели в соответствии с локалью. |  |210| `%b` | Сокращённое название месяца в соответствии с локалью. |  |211| `%B` | Полное название месяца в соответствии с локалью. |  |212| `%c` | Представление даты и времени, соответствующее локали. |  |213| `%d` | День месяца в виде десятичного числа \[01,31\]. |  |214| `%H` | Час (24-часовой формат) в виде десятичного числа \[00,23\]. |  |215| `%I` | Час (12-часовой формат) в виде десятичного числа \[01,12\]. |  |216| `%j` | День года в виде десятичного числа \[001,366\]. |  |217| `%m` | Месяц в виде десятичного числа \[01,12\]. |  |218| `%M` | Минута в виде десятичного числа \[00,59\]. |  |219| `%p` | Эквивалент AM или PM в соответствии с локалью. | (1) |220| `%S` | Секунда в виде десятичного числа \[00,61\]. | (2) |221| `%U` | Номер недели года (воскресенье – первый день недели) в виде десятичного числа \[00,53\]. Все дни нового года, предшествующие первому воскресенью, считаются неделей 0. | (3) |222| `%w` | День недели в виде десятичного числа \[0(воскресенье),6\]. |  |223| `%W` | Номер недели года (понедельник – первый день недели) в виде десятичного числа \[00,53\]. Все дни нового года, предшествующие первому понедельнику, считаются неделей 0. | (3) |224| `%x` | Представление даты, соответствующее локали. |  |225| `%X` | Представление времени, соответствующее локали. |  |226| `%y` | Год без века в виде десятичного числа \[00,99\]. |  |227| `%Y` | Год с веком в виде десятичного числа. |  |228| `%Z` | Название часового пояса (ни одного символа, если часовой пояс не задан). |  |229| `%%` | Литеральный символ `'%'`. |  |230231Примечания:2322331. При использовании с функцией [`strptime()`](https://python-all.ru/3.0/library/time.html#time.strptime) директива `%p` влияет только на поле часа на выходе, если директива `%I` используется для разбора часа.2342. Диапазон на самом деле составляет от `0` до `61`; это учитывает високосные секунды и (очень редкие) двойные високосные секунды.2353. При использовании с функцией [`strptime()`](https://python-all.ru/3.0/library/time.html#time.strptime), `%U` и `%W` используются в вычислениях только если указаны день недели и год.236237Вот пример формата дат, совместимого с указанным в [**RFC 2822**](https://python-all.ru/3.0/library/time.html) стандарте интернет-почты. [\[1\]](https://python-all.ru/3.0/library/time.html#id2)238239```python240>>> from time import gmtime, strftime241>>> strftime("%a, %d %b %Y %H:%M:%S +0000", gmtime())242'Thu, 28 Jun 2001 14:17:15 +0000'243```244245На некоторых платформах могут поддерживаться дополнительные директивы, но только перечисленные здесь имеют смысл, стандартизированный ANSI C.246247На некоторых платформах сразу после начального `'%'` директивы может следовать (в указанном порядке) необязательная спецификация ширины поля и точности; это также непереносимо. Ширина поля обычно равна 2, за исключением `%j`, где она равна 3.248249#### `[time.strptime]time.strptime(string[, format])`250251Разбирает строку, представляющую время, в соответствии с форматом. Возвращаемое значение – [`struct_time`](https://python-all.ru/3.0/library/time.html#time.struct_time), как возвращается [`gmtime()`](https://python-all.ru/3.0/library/time.html#time.gmtime) или [`localtime()`](https://python-all.ru/3.0/library/time.html#time.localtime).252253Параметр *format* использует те же директивы, что и [`strftime()`](https://python-all.ru/3.0/library/time.html#time.strftime); по умолчанию используется `"%a %b %d %H:%M:%S %Y"`, что соответствует форматированию, возвращаемому [`ctime()`](https://python-all.ru/3.0/library/time.html#time.ctime). Если *string* не удаётся разобрать в соответствии с *format* или в ней есть лишние данные после разбора, возбуждается [`ValueError`](https://python-all.ru/3.0/library/exceptions.html#exceptions.ValueError). Значения по умолчанию, используемые для заполнения отсутствующих данных, когда более точные значения не могут быть выведены: `(1900, 1, 1, 0, 0, 0, 0, 1, -1)`.254255Например:256257```python258>>> import time259>>> time.strptime("30 Nov 00", "%d %b %y")   # doctest: +NORMALIZE_WHITESPACE260time.struct_time(tm_year=2000, tm_mon=11, tm_mday=30, tm_hour=0, tm_min=0,261                 tm_sec=0, tm_wday=3, tm_yday=335, tm_isdst=-1)262```263264Поддержка директивы `%Z` основана на значениях, хранящихся в `tzname` и на том, истинно ли `daylight`. Из-за этого она зависит от платформы, за исключением распознавания UTC и GMT, которые всегда известны (и считаются часовыми поясами без перехода на летнее время).265266Поддерживаются только директивы, указанные в документации. Поскольку `strftime()` реализуется для каждой платформы отдельно, он иногда может предоставлять больше директив, чем перечислено. Но `strptime()` не зависит от платформы и поэтому не обязательно поддерживает все доступные директивы, которые не задокументированы как поддерживаемые.267268#### `[time.struct_time]time.struct_time`269270Тип последовательности значений времени, возвращаемой271272[`gmtime()`](https://python-all.ru/3.0/library/time.html#time.gmtime)273274,275276[`localtime()`](https://python-all.ru/3.0/library/time.html#time.localtime)277278и279280[`strptime()`](https://python-all.ru/3.0/library/time.html#time.strptime)281282.283284#### `[time.time]time.time()`285286Возвращает время в виде числа с плавающей точкой, выраженного в секундах с начала эпохи в UTC. Обратите внимание, что хотя время всегда возвращается как число с плавающей точкой, не все системы обеспечивают точность времени лучше 1 секунды. Хотя эта функция обычно возвращает неубывающие значения, она может вернуть значение меньше предыдущего, если системные часы были переведены назад между двумя вызовами.287288#### `[time.timezone]time.timezone`289290Смещение местного часового пояса (без DST) в секундах к западу от UTC (отрицательное в большей части Западной Европы, положительное в США, нулевое в Великобритании).291292#### `[time.tzname]time.tzname`293294Кортеж из двух строк: первая – название местного часового пояса без DST, вторая – название местного часового пояса с DST. Если часовой пояс с DST не определён, вторая строка не должна использоваться.295296#### `[time.tzset]time.tzset()`297298Сбрасывает правила преобразования времени, используемые библиотечными процедурами. Переменная окружения **TZ** определяет, как это делается.299300Доступность: Unix.301302> **Примечание**303>304> Хотя во многих случаях изменение переменной окружения **TZ** может влиять на вывод таких функций, как [`localtime()`](https://python-all.ru/3.0/library/time.html#time.localtime), без вызова [`tzset()`](https://python-all.ru/3.0/library/time.html#time.tzset), на это поведение не стоит полагаться.305>306> Переменная окружения **TZ** не должна содержать пробельных символов.307308Стандартный формат переменной окружения **TZ** выглядит так (пробелы добавлены для наглядности):309310```python311std offset [dst [offset [,start[/time], end[/time]]]]312```313314Где компоненты имеют следующее значение:315316**`std` and `dst`**317318Три или более буквенно-цифровых символа, обозначающие аббревиатуры часовых поясов. Они будут переданы в time.tzname.319320**`offset`**321322The offset has the form:323324`± hh[:mm[:ss]]`325326. 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.327328**`start[/time], end[/time]`**329330Указывает, когда переходить на летнее время и обратно. Формат дат начала и окончания – один из следующих:331332**`Jn`**333334Юлианский день335336*n*337338(1 \<=339340*n*341342\<= 365). Високосные дни не учитываются, поэтому во все годы 28 февраля – день 59, а 1 марта – день 60.343344**`n`**345346Юлианский день с нулевым отсчетом (0 \<=347348*n*349350\<= 365). Високосные дни учитываются, и можно указать 29 февраля.351352**`Mm.n.d`**353354*d*355356-й день (0 \<=357358*d*359360\<= 6) или неделя361362*n*363364месяца365366*m*367368года (1 \<=369370*n*371372\<= 5, 1 \<=373374*m*375376\<= 12, где неделя 5 означает «последний377378*d*379380-й день в месяце381382*m*383384», который может приходиться на четвертую или пятую неделю). Неделя 1 – это первая неделя, в которой встречается385386*d*387388-й день. День ноль – воскресенье.389390`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.391392```python393>>> os.environ['TZ'] = 'EST+05EDT,M4.1.0,M10.5.0'394>>> time.tzset()395>>> time.strftime('%X %x %Z')396'02:07:36 05/08/03 EDT'397>>> os.environ['TZ'] = 'AEST-10AEDT-11,M10.5.0,M3.5.0'398>>> time.tzset()399>>> time.strftime('%X %x %Z')400'16:08:12 05/08/03 AEST'401```402403На многих Unix-системах (включая \*BSD, Linux, Solaris и Darwin) удобнее использовать системную базу данных zoneinfo (*tzfile(5)*) для указания правил часовых поясов. Для этого установите переменную окружения **TZ** в путь к требуемому файлу данных часового пояса относительно корня базы данных часовых поясов zoneinfo системы, обычно находящейся в `/usr/share/zoneinfo`. Например, `'US/Eastern'`, `'Australia/Melbourne'`, `'Egypt'` или `'Europe/Amsterdam'`.404405```python406>>> os.environ['TZ'] = 'US/Eastern'407>>> time.tzset()408>>> time.tzname409('EST', 'EDT')410>>> os.environ['TZ'] = 'Egypt'411>>> time.tzset()412>>> time.tzname413('EET', 'EEST')414```415416> **См. также**417>418> **Модуль [`datetime`](https://python-all.ru/3.0/library/datetime.html#module-datetime)**419>420> Более объектно-ориентированный интерфейс для работы с датами и временем.421>422> **Модуль [`locale`](https://python-all.ru/3.0/library/locale.html#module-locale)**423>424> Службы интернационализации. Настройки локали могут влиять на возвращаемые значения некоторых функций модуля425>426> `time`427>428> .429>430> **Модуль [`calendar`](https://python-all.ru/3.0/library/calendar.html#module-calendar)**431>432> Общие календарные функции.433>434> `timegm()`435>436> является обратной по отношению к437>438> [`gmtime()`](https://python-all.ru/3.0/library/time.html#time.gmtime)439>440> из этого модуля.441442Сноски443444| [\[1\]](https://python-all.ru/3.0/library/time.html#id1) | Использование `%Z` теперь устарело, но экранирование `%z`, которое преобразуется в предпочтительное смещение в часах и минутах, поддерживается не всеми библиотеками ANSI C. Кроме того, строгое прочтение оригинального стандарта [**RFC 822**](https://python-all.ru/3.0/library/time.html) 1982 года требует двузначного года (%y, а не %Y), но на практике перешли на четырёхзначные годы задолго до 2000 года. Четырёхзначный год стал обязательным в [**RFC 2822**](https://python-all.ru/3.0/library/time.html), который заменил [**RFC 822**](https://python-all.ru/3.0/library/time.html). |445| --- | --- |446