`datetime` — Основные типы даты и времени¶

Модуль datetime предоставляет классы для работы с датами и временем.

Хотя арифметика даты и времени поддерживается, основное внимание в реализации уделяется эффективному извлечению атрибутов для форматирования и манипулирования выводом.

Совет

Перейдите к the format codes.

См.также

Модуль calendar: Общие функции, связанные с календарем.
Модуль time: Доступ к времени и его преобразование.
Модуль zoneinfo: Конкретные часовые пояса, представляющие базу данных часовых поясов IANA.
Пакет dateutil: Сторонняя библиотека с расширенной поддержкой часовых поясов и парсинга.
Пакет DateType: Сторонняя библиотека, которая вводит отдельные статические типы, чтобы, например, позволить static type checkers различать наивные и осознанные даты.

Осознанные и наивные объекты¶

Объекты даты и времени могут быть классифицированы как «осведомленные» или «наивные» в зависимости от того, включают ли они информацию о часовом поясе или нет.

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

Объект naive не содержит достаточно информации, чтобы однозначно определить свое местоположение относительно других объектов даты/времени. Представляет ли наивный объект всемирное координированное время (UTC), местное время или время в каком-то другом часовом поясе, зависит исключительно от программы, точно так же как от программы зависит, представляет ли конкретное число метры, мили или массу. Наивные объекты просты для понимания и работы с ними, но за счет игнорирования некоторых аспектов реальности.

Для приложений, которым требуются объекты с информацией, объекты datetime и time имеют необязательный атрибут информации о часовом поясе, tzinfo, который может быть установлен на экземпляр подкласса абстрактного класса tzinfo. Эти объекты tzinfo получают информацию о смещении от времени UTC, названии часового пояса и о том, действует ли переход на летнее время.

Модуль datetime предоставляет только один конкретный класс tzinfo, класс timezone. Класс timezone может представлять простые часовые пояса с фиксированным смещением от UTC, такие как сам UTC или североамериканские часовые пояса EST и EDT. Поддержка часовых поясов на более глубоких уровнях детализации зависит от приложения. Правила корректировки времени во всем мире скорее политические, чем рациональные, часто меняются, и не существует стандарта, подходящего для всех приложений, кроме UTC.

Константы¶

Модуль datetime экспортирует следующие константы:

datetime.MINYEAR¶: Наименьший номер года, допустимый в объекте date или datetime. MINYEAR - это 1.

datetime.MAXYEAR¶: Наибольший номер года, допустимый в объекте date или datetime. MAXYEAR - 9999.

datetime.UTC¶: Псевдоним для синглтона часового пояса UTC datetime.timezone.utc.

Added in version 3.11.

Доступные типы¶

class datetime.date: Идеализированная наивная дата, предполагающая, что текущий григорианский календарь всегда был и всегда будет в силе. Атрибуты: year, month и day.

class datetime.time: Идеализированное время, не зависящее от конкретного дня, предполагающее, что в каждом дне ровно 24*60*60 секунд. (Здесь нет понятия «високосные секунды».) Атрибуты: hour, minute, second, microsecond и tzinfo.

class datetime.datetime: Комбинация даты и времени. Атрибуты: year, month, day, hour, minute, second, microsecond и tzinfo.

class datetime.timedelta: Длительность, выражающая разницу между двумя экземплярами datetime или date с микросекундным разрешением.

class datetime.tzinfo: Абстрактный базовый класс для объектов информации о часовом поясе. Они используются классами datetime и time для предоставления настраиваемого представления о корректировке времени (например, для учета часового пояса и/или перехода на летнее время).

class datetime.timezone: Класс, реализующий абстрактный базовый класс tzinfo в виде фиксированного смещения от UTC.

Added in version 3.2.

Объекты этих типов неизменяемы.

Отношения подклассов:

object
    timedelta
    tzinfo
        timezone
    time
    date
        datetime

Общие свойства¶

Типы date, datetime, time и timezone имеют эти общие черты:

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

Определение осведомленности или наивности объекта¶

Объекты типа date всегда наивны.

Объект типа time или datetime может быть осведомленным или наивным.

Объект datetime d является осведомленным, если выполняются оба следующих условия:

d.tzinfo не None
d.tzinfo.utcoffset(d) не возвращается None

В противном случае d наивен.

Объект time t является осведомленным, если выполняются оба следующих условия:

t.tzinfo не None
t.tzinfo.utcoffset(None) не возвращает None.

В противном случае t наивен.

Различие между «знающими» и «наивными» не применимо к объектам timedelta.

`timedelta` Объекты¶

Объект timedelta представляет собой длительность, разницу между двумя экземплярами datetime или date.

class datetime.timedelta(days=0, seconds=0, microseconds=0, milliseconds=0, minutes=0, hours=0, weeks=0)¶

Все аргументы необязательны и по умолчанию равны 0. Аргументы могут быть целыми или плавающими числами и могут быть положительными или отрицательными.

Внутри хранятся только дни, секунды и микросекунды. Аргументы преобразуются в эти единицы:

Миллисекунда преобразуется в 1000 микросекунд.
Минута преобразуется в 60 секунд.
Час преобразуется в 3600 секунд.
Неделя преобразуется в 7 дней.

а дни, секунды и микросекунды затем нормализуются так, чтобы представление было уникальным, с

0 <= microseconds < 1000000
0 <= seconds < 3600*24 (количество секунд в одном дне)
-999999999 <= days <= 999999999

В следующем примере показано, как любые аргументы, кроме days, seconds и microseconds, «объединяются» и нормализуются в эти три результирующих атрибута:

>>> from datetime import timedelta
>>> delta = timedelta(
...     days=50,
...     seconds=27,
...     microseconds=10,
...     milliseconds=29000,
...     minutes=5,
...     hours=8,
...     weeks=2
... )
>>> # Only days, seconds, and microseconds remain
>>> delta
datetime.timedelta(days=64, seconds=29156, microseconds=10)

Если какой-либо аргумент является float и в нем присутствуют дробные микросекунды, то дробные микросекунды, оставшиеся от всех аргументов, объединяются, и их сумма округляется до ближайшей микросекунды с использованием тайбрейка «круглый-половинный-четный». Если ни один из аргументов не является плавающей величиной, процессы преобразования и нормализации являются точными (информация не теряется).

Если нормализованное значение дней выходит за пределы указанного диапазона, устанавливается значение OverflowError.

Обратите внимание, что нормализация отрицательных значений может поначалу удивить. Например:

>>> from datetime import timedelta
>>> d = timedelta(microseconds=-1)
>>> (d.days, d.seconds, d.microseconds)
(-1, 86399, 999999)

Атрибуты класса:

timedelta.min¶: Самый негативный объект timedelta, timedelta(-999999999).

timedelta.max¶: Самый положительный объект timedelta, timedelta(days=999999999, hours=23, minutes=59, seconds=59, microseconds=999999).

timedelta.resolution¶: Наименьшая возможная разница между неравными timedelta объектами, timedelta(microseconds=1).

Обратите внимание, что из-за нормализации timedelta.max больше, чем -timedelta.min. -timedelta.max не может быть представлен как объект timedelta.

Атрибуты экземпляра (только для чтения):

Атрибут	Значение
`days`	Между -999999999 и 999999999 включительно
`seconds`	От 0 до 86399 включительно
`microseconds`	От 0 до 999999 включительно

Поддерживаемые операции:

Операция	Результат
`t1 = t2 + t3`	Сумма `t2` и `t3`. После этого `t1 - t2 == t3` и `t1 - t3 == t2` истинны. (1)
`t1 = t2 - t3`	Разность `t2` и `t3`. После этого `t1 == t2 - t3` и `t2 == t1 + t3` истинны. (1)(6)
`t1 = t2 * i or t1 = i * t2`	Дельта умножается на целое число. После этого `t1 // i == t2` будет истинным, если `i != 0`.
	В общем случае `t1 * i == t1 * (i-1) + t1` истинно. (1)
`t1 = t2 * f or t1 = f * t2`	Дельта, умноженная на плавающее значение. Результат округляется до ближайшего кратного значения timedelta.resolution с помощью функции round-half-to-even.
`f = t2 / t3`	Деление (3) общей продолжительности `t2` на единицу интервала `t3`. Возвращает объект `float`.
`t1 = t2 / f or t1 = t2 / i`	Дельта, деленная на float или int. Результат округляется до ближайшего кратного timedelta.resolution с помощью функции round-half-to-even.
`t1 = t2 // i` или `t1 = t2 // t3`	Вычисляется пол, а остаток (если он есть) отбрасывается. Во втором случае возвращается целое число. (3)
`t1 = t2 % t3`	Остаток вычисляется как объект `timedelta`. (3)
`q, r = divmod(t1, t2)`	Вычисляет коэффициент и остаток: `q = t1 // t2` (3) и `r = t1 % t2`. q - целое число, r - объект `timedelta`.
`+t1`	Возвращает объект `timedelta` с тем же значением. (2)
`-t1`	Эквивалентно `timedelta(-t1.days, -t1.seconds, -t1.microseconds)` и `t1 -1`. (1)(4)
`abs(t)`	Эквивалентно `+t`, когда `t.days >= 0`, и `-t`, когда `t.days < 0`. (2)
`str(t)`	Возвращает строку в виде `[D day[s], ][H]H:MM:SS[.UUUUUU]`, где D - отрицательное значение для отрицательных `t`. (5)
`repr(t)`	Возвращает строковое представление объекта `timedelta` в виде вызова конструктора с каноническими значениями атрибутов.

Примечания:

Это точно, но может переполниться.
Это точное значение, которое не может переполниться.
Деление на ноль возводит в степень ZeroDivisionError.
-timedelta.max не может быть представлен как объект timedelta.
Строковые представления объектов timedelta нормализуются аналогично их внутреннему представлению. Это приводит к несколько необычным результатам для отрицательных таймдельта. Например:
```
>>> timedelta(hours=-5)
datetime.timedelta(days=-1, seconds=68400)
>>> print(_)
-1 day, 19:00:00
```
Выражение t2 - t3 всегда будет равно выражению t2 + (-t3), за исключением случая, когда t3 равно timedelta.max; в этом случае первое выражение даст результат, а второе переполнится.

Помимо перечисленных выше операций, объекты timedelta поддерживают определенные операции сложения и вычитания с объектами date и datetime (см. ниже).

Изменено в версии 3.2: Теперь поддерживается деление нацело и истинное деление объекта timedelta на другой объект timedelta, а также операции с остатком и функция divmod(). Истинное деление и умножение объекта timedelta на объект float теперь поддерживаются.

Объекты timedelta поддерживают сравнение равенства и порядка.

В булевых контекстах объект timedelta считается истинным тогда и только тогда, когда он не равен timedelta(0).

Методы экземпляра:

timedelta.total_seconds()¶

Возвращает общее количество секунд, содержащихся в длительности. Эквивалентно td / timedelta(seconds=1). Для единиц измерения интервалов, отличных от секунд, используйте форму деления напрямую (например, td / timedelta(microseconds=1)).

Обратите внимание, что для очень больших временных интервалов (более 270 лет на большинстве платформ) этот метод будет терять микросекундную точность.

Added in version 3.2.

Примеры использования: `timedelta`¶

Дополнительный пример нормализации:

>>> # Components of another_year add up to exactly 365 days
>>> from datetime import timedelta
>>> year = timedelta(days=365)
>>> another_year = timedelta(weeks=40, days=84, hours=23,
...                          minutes=50, seconds=600)
>>> year == another_year
True
>>> year.total_seconds()
31536000.0

Примеры арифметики timedelta:

>>> from datetime import timedelta
>>> year = timedelta(days=365)
>>> ten_years = 10 * year
>>> ten_years
datetime.timedelta(days=3650)
>>> ten_years.days // 365
10
>>> nine_years = ten_years - year
>>> nine_years
datetime.timedelta(days=3285)
>>> three_years = nine_years // 3
>>> three_years, three_years.days // 365
(datetime.timedelta(days=1095), 3)

`date` Объекты¶

Объект date представляет дату (год, месяц и день) в идеализированном календаре - текущем григорианском календаре, неограниченно растянутом в обе стороны.

Январь 1 года 1 называется днем номер 1, январь 2 года 1 называется днем номер 2, и так далее. [2]

class datetime.date(year, month, day)¶

Все аргументы являются обязательными. Аргументы должны быть целыми числами в следующих диапазонах:

MINYEAR <= year <= MAXYEAR
1 <= month <= 12
1 <= day <= number of days in the given month and year

Если задан аргумент, выходящий за пределы этих диапазонов, то будет задан ValueError.

Другие конструкторы, все методы класса:

classmethod date.today()¶

Возвращает текущую местную дату.

Это эквивалентно date.fromtimestamp(time.time()).

classmethod date.fromtimestamp(timestamp)¶

Возвращает локальную дату, соответствующую временной метке POSIX, такую, как возвращает time.time().

Это может вызвать ошибку OverflowError, если временная метка находится вне диапазона значений, поддерживаемых функцией localtime() платформы C, и OSError при неудаче localtime(). Обычно это ограничено годами от 1970 до 2038. Обратите внимание, что в не-POSIX системах, которые включают високосные секунды в свое понятие временной метки, високосные секунды игнорируются fromtimestamp().

Изменено в версии 3.3: Вызывайте OverflowError вместо ValueError, если временная метка находится вне диапазона значений, поддерживаемых функцией localtime() платформы C. Вызывает OSError вместо ValueError при ошибке localtime().

classmethod date.fromordinal(ordinal)¶

Возвращает дату, соответствующую пролептическому григорианскому ординалу, где 1 января года 1 имеет ординал 1.

ValueError поднимается, если только 1 <= ordinal <= date.max.toordinal(). Для любой даты d, date.fromordinal(d.toordinal()) == d.

classmethod date.fromisoformat(date_string)¶

Возвращает date, соответствующий дате_строки, заданной в любом допустимом формате ISO 8601, за следующими исключениями:

Даты с уменьшенной точностью в настоящее время не поддерживаются (YYYY-MM, YYYY).
Расширенные представления даты в настоящее время не поддерживаются (±YYYYYY-MM-DD).
Порядковые даты в настоящее время не поддерживаются (YYYY-OOO).

Примеры:

>>> from datetime import date
>>> date.fromisoformat('2019-12-04')
datetime.date(2019, 12, 4)
>>> date.fromisoformat('20191204')
datetime.date(2019, 12, 4)
>>> date.fromisoformat('2021-W01-1')
datetime.date(2021, 1, 4)

Added in version 3.7.

Изменено в версии 3.11: Ранее этот метод поддерживал только формат YYYY-MM-DD.

classmethod date.fromisocalendar(year, week, day)¶: Возвращает date, соответствующий календарной дате ISO, заданной годом, неделей и днем. Это обратная функция date.isocalendar().

Added in version 3.8.

Атрибуты класса:

date.min¶: Самая ранняя представляемая дата, date(MINYEAR, 1, 1).

date.max¶: Самая поздняя представляемая дата, date(MAXYEAR, 12, 31).

date.resolution¶: Наименьшая возможная разница между неравными объектами даты, timedelta(days=1).

Атрибуты экземпляра (только для чтения):

date.year¶: От MINYEAR до MAXYEAR включительно.

date.month¶: От 1 до 12 включительно.

date.day¶: От 1 до количества дней в данном месяце данного года.

Поддерживаемые операции:

Операция	Результат
`date2 = date1 + timedelta`	`date2` наступит через `timedelta.days` дней после `date1`. (1)
`date2 = date1 - timedelta`	Вычисляет `date2` такие, что `date2 + timedelta == date1`. (2)
`timedelta = date1 - date2`	(3)
`date1 == date2` `date1 != date2`	Сравнение равенств. (4)
`date1 < date2` `date1 > date2` `date1 <= date2` `date1 >= date2`	Сравнение заказов. (5)

Примечания:

date2 сдвигается вперед во времени, если timedelta.days > 0, или назад, если timedelta.days < 0. После этого date2 - date1 == timedelta.days. timedelta.seconds и timedelta.microseconds игнорируются. Значение OverflowError повышается, если date2.year будет меньше MINYEAR или больше MAXYEAR.
timedelta.seconds и timedelta.microseconds игнорируются.
Это точное значение, которое не может переполниться. timedelta.seconds и timedelta.microseconds равны 0, а date2 + timedelta == date1 - после.
Объекты date равны, если они представляют одну и ту же дату.

Объекты date, не являющиеся также экземплярами datetime, никогда не равны объектам datetime, даже если они представляют одну и ту же дату.
дата1 считается меньше даты2, если дата1 предшествует дате2 по времени. Другими словами, date1 < date2 тогда и только тогда, когда date1.toordinal() < date2.toordinal().

При сравнении порядка между объектом date, который не является также экземпляром datetime, и объектом datetime возникает ошибка TypeError.

Изменено в версии 3.13: Сравнение объекта datetime с экземпляром подкласса date, который не является подклассом datetime, больше не преобразует последний в date, игнорируя часть времени и часовой пояс. Поведение по умолчанию можно изменить, переопределив специальные методы сравнения в подклассах.

В булевых контекстах все объекты date считаются истинными.

Методы экземпляра:

date.replace(year=self.year, month=self.month, day=self.day)¶

Возвращает дату с тем же значением, за исключением тех параметров, которые получили новые значения в зависимости от того, какие ключевые слова-аргументы были указаны.

Пример:

>>> from datetime import date
>>> d = date(2002, 12, 31)
>>> d.replace(day=26)
datetime.date(2002, 12, 26)

Объекты date также поддерживаются родовой функцией copy.replace().

date.timetuple()¶

Возвращает time.struct_time, подобный тому, что возвращает time.localtime().

Часы, минуты и секунды равны 0, а флаг DST равен -1.

d.timetuple() эквивалентно:

time.struct_time((d.year, d.month, d.day, 0, 0, 0, d.weekday(), yday, -1))

где yday = d.toordinal() - date(d.year, 1, 1).toordinal() + 1 - номер дня в текущем году, начиная с 1 для 1 января.

date.toordinal()¶: Возвращает пролептический григорианский ординал даты, где 1 января года 1 имеет ординал 1. Для любого объекта date d, date.fromordinal(d.toordinal()) == d.

date.weekday()¶: Возвращает день недели в виде целого числа, где понедельник равен 0, а воскресенье - 6. Например, date(2002, 12, 4).weekday() == 2 - среда. См. также isoweekday().

date.isoweekday()¶: Возвращает день недели в виде целого числа, где понедельник равен 1, а воскресенье - 7. Например, date(2002, 12, 4).isoweekday() == 3 - среда. См. также weekday(), isocalendar().

date.isocalendar()¶

Возвращает объект named tuple с тремя компонентами: year, week и weekday.

Календарь ISO - это широко используемый вариант григорианского календаря. [3]

Год ISO состоит из 52 или 53 полных недель, а неделя начинается в понедельник и заканчивается в воскресенье. Первая неделя года ISO - это первая (григорианская) календарная неделя года, содержащая четверг. Она называется неделей номер 1, и год ISO этого четверга совпадает с григорианским годом.

Например, 2004 год начинается в четверг, поэтому первая неделя 2004 года ISO начинается в понедельник, 29 декабря 2003 года, и заканчивается в воскресенье, 4 января 2004 года:

>>> from datetime import date
>>> date(2003, 12, 29).isocalendar()
datetime.IsoCalendarDate(year=2004, week=1, weekday=1)
>>> date(2004, 1, 4).isocalendar()
datetime.IsoCalendarDate(year=2004, week=1, weekday=7)

Изменено в версии 3.9: Результат изменился с кортежа на named tuple.

date.isoformat()¶

Возвращает строку, представляющую дату в формате ISO 8601, YYYY-MM-DD:

>>> from datetime import date
>>> date(2002, 12, 4).isoformat()
'2002-12-04'

date.__str__()¶: Для даты d, str(d) эквивалентен d.isoformat().

date.ctime()¶

Возвращает строку, представляющую дату:

>>> from datetime import date
>>> date(2002, 12, 4).ctime()
'Wed Dec  4 00:00:00 2002'

d.ctime() эквивалентно:

time.ctime(time.mktime(d.timetuple()))

на платформах, где родная функция C ctime() (которую вызывает time.ctime(), но которую не вызывает date.ctime()) соответствует стандарту C.

date.strftime(format)¶: Возвращает строку, представляющую дату, управляемую явной строкой формата. Коды формата, относящиеся к часам, минутам или секундам, будут иметь значения 0. См. также strftime() и strptime() Поведение и date.isoformat().

date.__format__(format)¶: Аналогично date.strftime(). Это позволяет задать строку формата для объекта date в formatted string literals и при использовании str.format(). См. также strftime() и strptime() Поведение и date.isoformat().

Примеры использования: `date`¶

Пример подсчета дней до события:

>>> import time
>>> from datetime import date
>>> today = date.today()
>>> today
datetime.date(2007, 12, 5)
>>> today == date.fromtimestamp(time.time())
True
>>> my_birthday = date(today.year, 6, 24)
>>> if my_birthday < today:
...     my_birthday = my_birthday.replace(year=today.year + 1)
...
>>> my_birthday
datetime.date(2008, 6, 24)
>>> time_to_birthday = abs(my_birthday - today)
>>> time_to_birthday.days
202

Другие примеры работы с date:

>>> from datetime import date
>>> d = date.fromordinal(730920) # 730920th day after 1. 1. 0001
>>> d
datetime.date(2002, 3, 11)

>>> # Methods related to formatting string output
>>> d.isoformat()
'2002-03-11'
>>> d.strftime("%d/%m/%y")
'11/03/02'
>>> d.strftime("%A %d. %B %Y")
'Monday 11. March 2002'
>>> d.ctime()
'Mon Mar 11 00:00:00 2002'
>>> 'The {1} is {0:%d}, the {2} is {0:%B}.'.format(d, "day", "month")
'The day is 11, the month is March.'

>>> # Methods for to extracting 'components' under different calendars
>>> t = d.timetuple()
>>> for i in t:     
...     print(i)
2002                # year
3                   # month
11                  # day
0
0
0
0                   # weekday (0 = Monday)
70                  # 70th day in the year
-1
>>> ic = d.isocalendar()
>>> for i in ic:    
...     print(i)
2002                # ISO year
11                  # ISO week number
1                   # ISO day number ( 1 = Monday )

>>> # A date object is immutable; all operations produce a new object
>>> d.replace(year=2005)
datetime.date(2005, 3, 11)

`datetime` Объекты¶

Объект datetime - это единый объект, содержащий всю информацию из объекта date и объекта time.

Как и объект date, datetime предполагает, что текущий григорианский календарь распространяется в обе стороны; как и объект time, datetime предполагает, что в каждых сутках ровно 3600*24 секунды.

Конструктор:

class datetime.datetime(year, month, day, hour=0, minute=0, second=0, microsecond=0, tzinfo=None, *, fold=0)¶

Аргументы год, месяц и день являются обязательными. tzinfo может быть None или экземпляром подкласса tzinfo. Остальные аргументы должны быть целыми числами в следующих диапазонах:

MINYEAR <= year <= MAXYEAR,
1 <= month <= 12,
1 <= day <= number of days in the given month and year,
0 <= hour < 24,
0 <= minute < 60,
0 <= second < 60,
0 <= microsecond < 1000000,
fold in [0, 1].

Если задан аргумент, выходящий за пределы этих диапазонов, то будет задан ValueError.

Изменено в версии 3.6: Добавлен параметр fold.

Другие конструкторы, все методы класса:

classmethod datetime.today()¶

Возвращает текущее локальное время даты, с tzinfo None.

Эквивалент:

datetime.fromtimestamp(time.time())

См. также now(), fromtimestamp().

Этот метод функционально эквивалентен now(), но без параметра tz.

classmethod datetime.now(tz=None)¶

Возвращает текущую местную дату и время.

Если необязательный аргумент tz равен None или не указан, то это аналогично today(), но, если возможно, обеспечивает большую точность, чем можно получить при использовании временной метки time.time() (например, это возможно на платформах, предоставляющих функцию C gettimeofday()).

Если tz не является None, он должен быть экземпляром подкласса tzinfo, и текущие дата и время преобразуются в часовой пояс tz.

Эта функция предпочтительнее, чем today() и utcnow().

classmethod datetime.utcnow()¶

Возвращает текущую дату и время по Гринвичу, с tzinfo None.

Это похоже на now(), но возвращает текущую дату и время UTC в виде наивного объекта datetime. Более точное текущее время по Гринвичу можно получить, вызвав datetime.now(timezone.utc). См. также now().

Предупреждение

Поскольку наивные объекты datetime рассматриваются многими методами datetime как локальное время, для представления времени в UTC предпочтительнее использовать aware datetimes. Поэтому рекомендуемый способ создания объекта, представляющего текущее время в UTC, - это вызов datetime.now(timezone.utc).

Не рекомендуется, начиная с версии 3.12: Вместо datetime.now() используйте UTC.

classmethod datetime.fromtimestamp(timestamp, tz=None)¶

Возвращает локальную дату и время, соответствующие временной метке POSIX, такой, как возвращает time.time(). Если необязательный аргумент tz равен None или не указан, временная метка преобразуется в локальную дату и время платформы, а возвращаемый объект datetime является наивным.

Если tz не является None, он должен быть экземпляром подкласса tzinfo, и временная метка преобразуется в часовой пояс tz.

fromtimestamp() может вызвать OverflowError, если временная метка выходит за пределы диапазона значений, поддерживаемых функциями localtime() или gmtime() платформы C, и OSError при отказе localtime() или gmtime(). Обычно это ограничено годами с 1970 по 2038. Обратите внимание, что в системах, отличных от POSIX, которые включают високосные секунды в свое понятие временной метки, високосные секунды игнорируются fromtimestamp(), и тогда можно иметь две временные метки, отличающиеся на секунду, которые дают идентичные объекты datetime. Этот метод предпочтительнее, чем utcfromtimestamp().

Изменено в версии 3.3: Вызывайте OverflowError вместо ValueError, если временная метка находится вне диапазона значений, поддерживаемых функциями localtime() или gmtime() платформы C. Вызывайте OSError вместо ValueError при сбое localtime() или gmtime().

Изменено в версии 3.6: fromtimestamp() может возвращать экземпляры с fold, установленным на 1.

classmethod datetime.utcfromtimestamp(timestamp)¶

Возвращает UTC datetime, соответствующий временной метке POSIX, с tzinfo None. (Результирующий объект является наивным).

Это может вызвать ошибку OverflowError, если временная метка находится вне диапазона значений, поддерживаемых функцией gmtime() платформы C, и OSError при неудаче gmtime(). Обычно это ограничено годами с 1970 по 2038.

Чтобы получить осведомленный объект datetime, вызовите fromtimestamp():

datetime.fromtimestamp(timestamp, timezone.utc)

На POSIX-совместимых платформах это эквивалентно следующему выражению:

datetime(1970, 1, 1, tzinfo=timezone.utc) + timedelta(seconds=timestamp)

за исключением того, что последняя формула всегда поддерживает полный диапазон лет: от MINYEAR до MAXYEAR включительно.

Предупреждение

Поскольку наивные объекты datetime рассматриваются многими методами datetime как местное время, для представления времени в UTC предпочтительнее использовать aware datetimes. Поэтому рекомендуемый способ создания объекта, представляющего конкретную временную метку в UTC, - это вызов datetime.fromtimestamp(timestamp, tz=timezone.utc).

Изменено в версии 3.3: Вызывайте OverflowError вместо ValueError, если временная метка находится вне диапазона значений, поддерживаемых функцией gmtime() платформы C. Вызывает OSError вместо ValueError при ошибке gmtime().

Не рекомендуется, начиная с версии 3.12: Вместо datetime.fromtimestamp() используйте UTC.

classmethod datetime.fromordinal(ordinal)¶: Возвращает datetime, соответствующий пролептическому григорианскому ординалу, где 1 января года 1 имеет ординал 1. Значение ValueError повышается, если только 1 <= ordinal <= datetime.max.toordinal(). Час, минута, секунда и микросекунда результата равны 0, а tzinfo равен None.

classmethod datetime.combine(date, time, tzinfo=time.tzinfo)¶

Возвращает новый объект datetime, компоненты даты которого равны компонентам данного объекта date, а компоненты времени равны компонентам данного объекта time. Если указан аргумент tzinfo, его значение используется для установки атрибута tzinfo результата, в противном случае используется атрибут tzinfo аргумента time. Если аргумент date является объектом datetime, его компоненты времени и атрибуты tzinfo игнорируются.

Для любого datetime объекта d, d == datetime.combine(d.date(), d.time(), d.tzinfo).

Изменено в версии 3.6: Добавлен аргумент tzinfo.

classmethod datetime.fromisoformat(date_string)¶

Возвращает datetime, соответствующий дате_строки в любом допустимом формате ISO 8601, за следующими исключениями:

Смещение часового пояса может иметь дробные секунды.
Разделитель T может быть заменен любым символом юникода.
Дробные часы и минуты не поддерживаются.
Даты с уменьшенной точностью в настоящее время не поддерживаются (YYYY-MM, YYYY).
Расширенные представления даты в настоящее время не поддерживаются (±YYYYYY-MM-DD).
Порядковые даты в настоящее время не поддерживаются (YYYY-OOO).

Примеры:

>>> from datetime import datetime
>>> datetime.fromisoformat('2011-11-04')
datetime.datetime(2011, 11, 4, 0, 0)
>>> datetime.fromisoformat('20111104')
datetime.datetime(2011, 11, 4, 0, 0)
>>> datetime.fromisoformat('2011-11-04T00:05:23')
datetime.datetime(2011, 11, 4, 0, 5, 23)
>>> datetime.fromisoformat('2011-11-04T00:05:23Z')
datetime.datetime(2011, 11, 4, 0, 5, 23, tzinfo=datetime.timezone.utc)
>>> datetime.fromisoformat('20111104T000523')
datetime.datetime(2011, 11, 4, 0, 5, 23)
>>> datetime.fromisoformat('2011-W01-2T00:05:23.283')
datetime.datetime(2011, 1, 4, 0, 5, 23, 283000)
>>> datetime.fromisoformat('2011-11-04 00:05:23.283')
datetime.datetime(2011, 11, 4, 0, 5, 23, 283000)
>>> datetime.fromisoformat('2011-11-04 00:05:23.283+00:00')
datetime.datetime(2011, 11, 4, 0, 5, 23, 283000, tzinfo=datetime.timezone.utc)
>>> datetime.fromisoformat('2011-11-04T00:05:23+04:00')   
datetime.datetime(2011, 11, 4, 0, 5, 23,
    tzinfo=datetime.timezone(datetime.timedelta(seconds=14400)))

Added in version 3.7.

Изменено в версии 3.11: Ранее этот метод поддерживал только форматы, которые могли быть испущены date.isoformat() или datetime.isoformat().

classmethod datetime.fromisocalendar(year, week, day)¶: Возвращает значение datetime, соответствующее календарной дате ISO, заданной годом, неделей и днем. Компоненты datetime, не относящиеся к дате, заполняются своими обычными значениями по умолчанию. Это обратная функция datetime.isocalendar().

Added in version 3.8.

classmethod datetime.strptime(date_string, format)¶

Возвращает datetime, соответствующий дата_строки, разобранной в соответствии с форматом.

Если формат не содержит микросекунд или информации о часовом поясе, это эквивалентно:

datetime(*(time.strptime(date_string, format)[0:6]))

ValueError поднимается, если строка date_string и формат не могут быть разобраны time.strptime() или если возвращается значение, не являющееся кортежем времени. См. также strftime() и strptime() Поведение и datetime.fromisoformat().

Изменено в версии 3.13: Если в формате указаны день и месяц без года, то теперь выдается DeprecationWarning. Это сделано для того, чтобы избежать ошибки четырехлетнего високосного года в коде, пытающемся разобрать только месяц и день, поскольку год по умолчанию, используемый при отсутствии года в формате, не является високосным. Такие значения формата могут вызвать ошибку, начиная с Python 3.15. Обходной путь - всегда включать год в формат. При разборе значений date_string, не содержащих год, перед разбором явно добавьте год, который является високосным:

>>> from datetime import datetime
>>> date_string = "02/29"
>>> when = datetime.strptime(f"{date_string};1984", "%m/%d;%Y")  # Avoids leap year bug.
>>> when.strftime("%B %d")  
'February 29'

Атрибуты класса:

datetime.min¶: Самые ранние представимые datetime, datetime(MINYEAR, 1, 1, tzinfo=None).

datetime.max¶: Последние представляемые datetime, datetime(MAXYEAR, 12, 31, 23, 59, 59, 999999, tzinfo=None).

datetime.resolution¶: Наименьшая возможная разница между неравными datetime объектами, timedelta(microseconds=1).

Атрибуты экземпляра (только для чтения):

datetime.year¶: От MINYEAR до MAXYEAR включительно.

datetime.month¶: От 1 до 12 включительно.

datetime.day¶: От 1 до количества дней в данном месяце данного года.

datetime.hour¶: В range(24).

datetime.minute¶: В range(60).

datetime.second¶: В range(60).

datetime.microsecond¶: В range(1000000).

datetime.tzinfo¶: Объект, переданный в качестве аргумента tzinfo конструктору datetime, или None, если он не был передан.

datetime.fold¶: В [0, 1]. Используется для разграничения времени стен во время повторного интервала. (Повторный интервал возникает, когда часы переводятся назад по окончании летнего времени или когда смещение UTC для текущей зоны уменьшается по политическим причинам). Значения 0 и 1 означают, соответственно, более ранний и более поздний из двух моментов с одинаковым представлением стенного времени.

Added in version 3.6.

Поддерживаемые операции:

Операция	Результат
`datetime2 = datetime1 + timedelta`	(1)
`datetime2 = datetime1 - timedelta`	(2)
`timedelta = datetime1 - datetime2`	(3)
`datetime1 == datetime2` `datetime1 != datetime2`	Сравнение равенств. (4)
`datetime1 < datetime2` `datetime1 > datetime2` `datetime1 <= datetime2` `datetime1 >= datetime2`	Сравнение заказов. (5)

datetime2 - это длительность timedelta, удаленная от datetime1, перемещение вперед во времени, если timedelta.days > 0, или назад, если timedelta.days < 0. Результат имеет тот же атрибут tzinfo, что и входной datetime, и datetime2 - datetime1 == timedelta после него. Значение OverflowError повышается, если datetime2.year будет меньше MINYEAR или больше MAXYEAR. Обратите внимание, что корректировка часового пояса не выполняется, даже если входным данными является объект aware.
Вычисляет datetime2, такое, что datetime2 + timedelta == datetime1. Как и в случае сложения, результат имеет тот же атрибут tzinfo, что и входной datetime, и корректировка часового пояса не производится, даже если входные данные известны.
Вычитание datetime из datetime определено только в том случае, если оба операнда наивные, или если оба осведомлены. Если один из них осведомлен, а другой наивен, то вычитается TypeError.

Если оба наивны или оба осведомлены и имеют одинаковые атрибуты tzinfo, атрибуты tzinfo игнорируются, и в результате получается объект timedelta t такой, что datetime2 + t == datetime1. В этом случае корректировка часового пояса не производится.

Если оба значения известны и имеют разные атрибуты tzinfo, a-b действует так, как если бы a и b были сначала преобразованы к наивным временам даты UTC. В результате получается (a.replace(tzinfo=None) - a.utcoffset()) - (b.replace(tzinfo=None) - b.utcoffset()), за исключением того, что реализация никогда не переполняется.
Объекты datetime равны, если они представляют одну и ту же дату и время с учетом часового пояса.

Наивные и осведомленные datetime объекты никогда не равны.

Если оба компаранта известны и имеют один и тот же атрибут tzinfo, атрибуты tzinfo и fold игнорируются, и сравниваются базовые времена дат. Если оба компаранта известны и имеют разные атрибуты tzinfo, сравнение происходит так, как если бы компаранты были сначала преобразованы в UTC, за исключением того, что реализация никогда не переполняется. Экземпляры datetime в повторяющемся интервале никогда не равны экземплярам datetime в другом часовом поясе.
datetime1 считается меньше, чем datetime2, если datetime1 предшествует datetime2 по времени с учетом часового пояса.

Сравнение порядка между наивными и осведомленными datetime объектами повышает TypeError.

Если оба компаранта известны и имеют один и тот же атрибут tzinfo, атрибуты tzinfo и fold игнорируются, и сравниваются базовые времена дат. Если оба компаранта известны и имеют разные атрибуты tzinfo, сравнение выполняется так, как если бы компаранты были сначала преобразованы в UTC, за исключением того, что реализация никогда не переполняется.

Изменено в версии 3.3: Сравнение равенств между знающими и наивными экземплярами datetime не приводит к появлению TypeError.

Изменено в версии 3.13: Сравнение объекта datetime с экземпляром подкласса date, который не является подклассом datetime, больше не преобразует последний в date, игнорируя часть времени и часовой пояс. Поведение по умолчанию можно изменить, переопределив специальные методы сравнения в подклассах.

Методы экземпляра:

datetime.date()¶: Возвращает объект date с одинаковыми годом, месяцем и днем.

datetime.time()¶: Возвращает объект time с одинаковыми часами, минутами, секундами, микросекундами и складками. tzinfo - это None. См. также метод timetz().

Изменено в версии 3.6: Значение складки копируется в возвращаемый объект time.

datetime.timetz()¶: Возвращает объект time с теми же атрибутами часа, минуты, секунды, микросекунды, складки и tzinfo. См. также метод time().

Изменено в версии 3.6: Значение складки копируется в возвращаемый объект time.

datetime.replace(year=self.year, month=self.month, day=self.day, hour=self.hour, minute=self.minute, second=self.second, microsecond=self.microsecond, tzinfo=self.tzinfo, *, fold=0)¶

Возвращает datetime с теми же атрибутами, за исключением тех атрибутов, которые получили новые значения в зависимости от того, какие аргументы ключевого слова указаны. Обратите внимание, что можно указать tzinfo=None, чтобы создать наивный datetime из aware datetime без преобразования данных даты и времени.

Объекты datetime также поддерживаются родовой функцией copy.replace().

Изменено в версии 3.6: Добавлен параметр fold.

datetime.astimezone(tz=None)¶

Возвращает объект datetime с новым атрибутом tzinfo tz, корректируя данные о дате и времени так, чтобы в результате получилось то же время UTC, что и у self, но в местном времени tz.

Если указано, то tz должен быть экземпляром подкласса tzinfo, а его методы utcoffset() и dst() не должны возвращать None. Если self является наивным, предполагается, что он представляет время в системном часовом поясе.

При вызове без аргументов (или с tz=None) в качестве целевого часового пояса принимается локальный часовой пояс системы. Атрибут .tzinfo преобразованного экземпляра datetime будет установлен в экземпляр timezone с именем и смещением зоны, полученными из ОС.

Если self.tzinfo равен tz, то self.astimezone(tz) равен self: корректировка данных даты и времени не производится. В противном случае результатом будет местное время в часовом поясе tz, представляющее собой то же время UTC, что и self: после astz = dt.astimezone(tz), astz - astz.utcoffset() будет иметь те же данные даты и времени, что и dt - dt.utcoffset().

Если вы хотите просто присоединить объект часового пояса tz к datetime dt без преобразования данных о дате и времени, используйте dt.replace(tzinfo=tz). Если вы хотите просто удалить объект часового пояса из известного datetime dt без преобразования данных даты и времени, используйте dt.replace(tzinfo=None).

Обратите внимание, что метод по умолчанию tzinfo.fromutc() может быть переопределен в подклассе tzinfo, чтобы повлиять на результат, возвращаемый astimezone(). Если не учитывать случаи ошибок, astimezone() действует следующим образом:

def astimezone(self, tz):
    if self.tzinfo is tz:
        return self
    # Convert self to UTC, and attach the new time zone object.
    utc = (self - self.utcoffset()).replace(tzinfo=tz)
    # Convert from UTC to tz's local time.
    return tz.fromutc(utc)

Изменено в версии 3.3: Теперь tz можно опустить.

Изменено в версии 3.6: Теперь метод astimezone() можно вызывать на наивных экземплярах, которые, как предполагается, представляют системное локальное время.

datetime.utcoffset()¶: Если tzinfo является None, возвращает None, иначе возвращает self.tzinfo.utcoffset(self), и вызывает исключение, если не возвращает None или объект timedelta с величиной меньше одного дня.

Изменено в версии 3.7: Смещение UTC не ограничивается целым числом минут.

datetime.dst()¶: Если tzinfo является None, возвращает None, иначе возвращает self.tzinfo.dst(self), и вызывает исключение, если не возвращает None или объект timedelta с величиной меньше одного дня.

Изменено в версии 3.7: Смещение DST не ограничивается целым числом минут.

datetime.tzname()¶: Если tzinfo равно None, возвращает None, иначе возвращает self.tzinfo.tzname(self), вызывает исключение, если не возвращает None или строковый объект,

datetime.timetuple()¶

Возвращает time.struct_time, подобный тому, что возвращает time.localtime().

d.timetuple() эквивалентно:

time.struct_time((d.year, d.month, d.day,
                  d.hour, d.minute, d.second,
                  d.weekday(), yday, dst))

где yday = d.toordinal() - date(d.year, 1, 1).toordinal() + 1 - номер дня в текущем году, начиная с 1 для 1 января. Флаг tm_isdst результата устанавливается в соответствии с методом dst(): tzinfo - None или dst() возвращает None, tm_isdst устанавливается в -1; если dst() возвращает ненулевое значение, tm_isdst устанавливается в 1; иначе tm_isdst устанавливается в 0.

datetime.utctimetuple()¶

Если datetime экземпляра d наивен, это то же самое, что и d.timetuple(), за исключением того, что tm_isdst принудительно устанавливается в 0 независимо от того, что возвращает d.dst(). Для времени UTC никогда не действует DST.

Если d известно, то d нормализуется к времени UTC путем вычитания d.utcoffset(), и возвращается time.struct_time для нормализованного времени. tm_isdst принудительно равняется 0. Обратите внимание, что может возникнуть ошибка OverflowError, если d.year был MINYEAR или MAXYEAR и корректировка UTC выходит за границу года.

Предупреждение

Поскольку наивные объекты datetime рассматриваются многими методами datetime как местное время, предпочтительнее использовать aware datetimes для представления времени в UTC; в результате использование datetime.utctimetuple() может дать неверные результаты. Если у вас есть наивный datetime, представляющий UTC, используйте datetime.replace(tzinfo=timezone.utc), чтобы сделать его осведомленным, после чего вы можете использовать datetime.timetuple().

datetime.toordinal()¶: Возвращает пролептический григорианский ординал даты. То же, что и self.date().toordinal().

datetime.timestamp()¶

Возвращает временную метку POSIX, соответствующую экземпляру datetime. Возвращаемое значение - float, аналогичное возвращаемому time.time().

Предполагается, что наивные экземпляры datetime представляют местное время, и этот метод полагается на функцию mktime() платформы C для выполнения преобразования. Поскольку datetime поддерживает более широкий диапазон значений, чем mktime() на многих платформах, этот метод может вызывать OverflowError или OSError для времени, находящегося далеко в прошлом или в будущем.

Для экземпляров, знающих datetime, возвращаемое значение вычисляется как:

(dt - datetime(1970, 1, 1, tzinfo=timezone.utc)).total_seconds()

Added in version 3.3.

Изменено в версии 3.6: Метод timestamp() использует атрибут fold, чтобы определить время в повторяющемся интервале.

Примечание

Не существует метода, позволяющего получить временную метку POSIX непосредственно из экземпляра наивного datetime, представляющего время UTC. Если ваше приложение использует это соглашение, а системный часовой пояс не установлен на UTC, вы можете получить временную метку POSIX, предоставив tzinfo=timezone.utc:

timestamp = dt.replace(tzinfo=timezone.utc).timestamp()

или вычисляя временную метку напрямую:

timestamp = (dt - datetime(1970, 1, 1)) / timedelta(seconds=1)

datetime.weekday()¶: Возвращает день недели в виде целого числа, где понедельник равен 0, а воскресенье - 6. То же самое, что и self.date().weekday(). См. также isoweekday().

datetime.isoweekday()¶: Возвращает день недели в виде целого числа, где понедельник равен 1, а воскресенье - 7. То же самое, что и self.date().isoweekday(). См. также weekday(), isocalendar().

datetime.isocalendar()¶: Возвращает named tuple с тремя компонентами: year, week и weekday. То же самое, что и self.date().isocalendar().

datetime.isoformat(sep='T', timespec='auto')¶

Возвращает строку, представляющую дату и время в формате ISO 8601:

YYYY-MM-DDTHH:MM:SS.ffffff, если microsecond не 0
YYYY-MM-DDTHH:MM:SS, если microsecond равен 0

Если utcoffset() не возвращает None, добавляется строка, указывающая смещение UTC:

YYYY-MM-DDTHH:MM:SS.ffffff+HH:MM[:SS[.ffffff]], если microsecond не 0
YYYY-MM-DDTHH:MM:SS+HH:MM[:SS[.ffffff]], если microsecond равен 0

Примеры:

>>> from datetime import datetime, timezone
>>> datetime(2019, 5, 18, 15, 17, 8, 132263).isoformat()
'2019-05-18T15:17:08.132263'
>>> datetime(2019, 5, 18, 15, 17, tzinfo=timezone.utc).isoformat()
'2019-05-18T15:17:00+00:00'

Необязательный аргумент sep (по умолчанию 'T') представляет собой односимвольный разделитель, помещаемый между частями даты и времени результата. Например:

>>> from datetime import tzinfo, timedelta, datetime
>>> class TZ(tzinfo):
...     """A time zone with an arbitrary, constant -06:39 offset."""
...     def utcoffset(self, dt):
...         return timedelta(hours=-6, minutes=-39)
...
>>> datetime(2002, 12, 25, tzinfo=TZ()).isoformat(' ')
'2002-12-25 00:00:00-06:39'
>>> datetime(2009, 11, 27, microsecond=100, tzinfo=TZ()).isoformat()
'2009-11-27T00:00:00.000100-06:39'

Необязательный аргумент timespec задает количество дополнительных компонентов времени, которые необходимо включить (по умолчанию 'auto'). Это может быть одно из следующих значений:

'auto': То же, что и 'seconds', если microsecond равно 0, то же, что и 'microseconds', в противном случае.
'hours': Включите hour в двузначный формат HH.
'minutes': Включите hour и minute в формат HH:MM.
'seconds': Включите hour, minute и second в формат HH:MM:SS.
'milliseconds': Включить полное время, но усечь дробную часть секунды до миллисекунд. Формат HH:MM:SS.sss.
'microseconds': Включите полный рабочий день в формате HH:MM:SS.ffffff.

Примечание

Исключенные компоненты времени усекаются, а не округляются.

ValueError будет поднят при неверном аргументе timespec:

>>> from datetime import datetime
>>> datetime.now().isoformat(timespec='minutes')   
'2002-12-25T00:00'
>>> dt = datetime(2015, 1, 1, 12, 30, 59, 0)
>>> dt.isoformat(timespec='microseconds')
'2015-01-01T12:30:59.000000'

Изменено в версии 3.6: Добавлен параметр timespec.

datetime.__str__()¶: Для экземпляра datetime d, str(d) эквивалентен d.isoformat(' ').

datetime.ctime()¶

Возвращает строку, представляющую дату и время:

>>> from datetime import datetime
>>> datetime(2002, 12, 4, 20, 30, 40).ctime()
'Wed Dec  4 20:30:40 2002'

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

d.ctime() эквивалентно:

time.ctime(time.mktime(d.timetuple()))

на платформах, где родная функция C ctime() (которую вызывает time.ctime(), но которую не вызывает datetime.ctime()) соответствует стандарту C.

datetime.strftime(format)¶: Возвращает строку, представляющую дату и время, управляемую явной строкой формата. См. также strftime() и strptime() Поведение и datetime.isoformat().

datetime.__format__(format)¶: Аналогично datetime.strftime(). Это позволяет задать строку формата для объекта datetime в formatted string literals и при использовании str.format(). См. также strftime() и strptime() Поведение и datetime.isoformat().

Примеры использования: `datetime`¶

Примеры работы с объектами datetime:

>>> from datetime import datetime, date, time, timezone

>>> # Using datetime.combine()
>>> d = date(2005, 7, 14)
>>> t = time(12, 30)
>>> datetime.combine(d, t)
datetime.datetime(2005, 7, 14, 12, 30)

>>> # Using datetime.now()
>>> datetime.now()   
datetime.datetime(2007, 12, 6, 16, 29, 43, 79043)   # GMT +1
>>> datetime.now(timezone.utc)   
datetime.datetime(2007, 12, 6, 15, 29, 43, 79060, tzinfo=datetime.timezone.utc)

>>> # Using datetime.strptime()
>>> dt = datetime.strptime("21/11/06 16:30", "%d/%m/%y %H:%M")
>>> dt
datetime.datetime(2006, 11, 21, 16, 30)

>>> # Using datetime.timetuple() to get tuple of all attributes
>>> tt = dt.timetuple()
>>> for it in tt:   
...     print(it)
...
2006    # year
11      # month
21      # day
16      # hour
30      # minute
0       # second
1       # weekday (0 = Monday)
325     # number of days since 1st January
-1      # dst - method tzinfo.dst() returned None

>>> # Date in ISO format
>>> ic = dt.isocalendar()
>>> for it in ic:   
...     print(it)
...
2006    # ISO year
47      # ISO week
2       # ISO weekday

>>> # Formatting a datetime
>>> dt.strftime("%A, %d. %B %Y %I:%M%p")
'Tuesday, 21. November 2006 04:30PM'
>>> 'The {1} is {0:%d}, the {2} is {0:%B}, the {3} is {0:%I:%M%p}.'.format(dt, "day", "month", "time")
'The day is 21, the month is November, the time is 04:30PM.'

В приведенном ниже примере определен подкласс tzinfo, содержащий информацию о часовом поясе для Кабула, Афганистан, где до 1945 года использовалось +4 UTC, а затем +4:30 UTC:

from datetime import timedelta, datetime, tzinfo, timezone

class KabulTz(tzinfo):
    # Kabul used +4 until 1945, when they moved to +4:30
    UTC_MOVE_DATE = datetime(1944, 12, 31, 20, tzinfo=timezone.utc)

    def utcoffset(self, dt):
        if dt.year < 1945:
            return timedelta(hours=4)
        elif (1945, 1, 1, 0, 0) <= dt.timetuple()[:5] < (1945, 1, 1, 0, 30):
            # An ambiguous ("imaginary") half-hour range representing
            # a 'fold' in time due to the shift from +4 to +4:30.
            # If dt falls in the imaginary range, use fold to decide how
            # to resolve. See PEP495.
            return timedelta(hours=4, minutes=(30 if dt.fold else 0))
        else:
            return timedelta(hours=4, minutes=30)

    def fromutc(self, dt):
        # Follow same validations as in datetime.tzinfo
        if not isinstance(dt, datetime):
            raise TypeError("fromutc() requires a datetime argument")
        if dt.tzinfo is not self:
            raise ValueError("dt.tzinfo is not self")

        # A custom implementation is required for fromutc as
        # the input to this function is a datetime with utc values
        # but with a tzinfo set to self.
        # See datetime.astimezone or fromtimestamp.
        if dt.replace(tzinfo=timezone.utc) >= self.UTC_MOVE_DATE:
            return dt + timedelta(hours=4, minutes=30)
        else:
            return dt + timedelta(hours=4)

    def dst(self, dt):
        # Kabul does not observe daylight saving time.
        return timedelta(0)

    def tzname(self, dt):
        if dt >= self.UTC_MOVE_DATE:
            return "+04:30"
        return "+04"

Использование KabulTz сверху:

>>> tz1 = KabulTz()

>>> # Datetime before the change
>>> dt1 = datetime(1900, 11, 21, 16, 30, tzinfo=tz1)
>>> print(dt1.utcoffset())
4:00:00

>>> # Datetime after the change
>>> dt2 = datetime(2006, 6, 14, 13, 0, tzinfo=tz1)
>>> print(dt2.utcoffset())
4:30:00

>>> # Convert datetime to another time zone
>>> dt3 = dt2.astimezone(timezone.utc)
>>> dt3
datetime.datetime(2006, 6, 14, 8, 30, tzinfo=datetime.timezone.utc)
>>> dt2
datetime.datetime(2006, 6, 14, 13, 0, tzinfo=KabulTz())
>>> dt2 == dt3
True

`time` Объекты¶

Объект time представляет собой (местное) время суток, не зависящее от конкретного дня и подлежащее корректировке с помощью объекта tzinfo.

class datetime.time(hour=0, minute=0, second=0, microsecond=0, tzinfo=None, *, fold=0)¶

Все аргументы необязательны. tzinfo может быть None или экземпляром подкласса tzinfo. Остальные аргументы должны быть целыми числами в следующих диапазонах:

0 <= hour < 24,
0 <= minute < 60,
0 <= second < 60,
0 <= microsecond < 1000000,
fold in [0, 1].

Если задан аргумент, выходящий за пределы этих диапазонов, будет передан ValueError. Все аргументы по умолчанию равны 0, кроме tzinfo, который по умолчанию равен None.

Атрибуты класса:

time.min¶: Самые ранние представимые time, time(0, 0, 0, 0).

time.max¶: Последние представляемые time, time(23, 59, 59, 999999).

time.resolution¶: Наименьшая возможная разница между неравными объектами time, timedelta(microseconds=1), хотя следует учитывать, что арифметика на объектах time не поддерживается.

Атрибуты экземпляра (только для чтения):

time.hour¶: В range(24).

time.minute¶: В range(60).

time.second¶: В range(60).

time.microsecond¶: В range(1000000).

time.tzinfo¶: Объект, переданный в качестве аргумента tzinfo в конструктор time, или None, если он не был передан.

time.fold¶: В [0, 1]. Используется для разграничения времени стен во время повторного интервала. (Повторный интервал возникает, когда часы переводятся назад по окончании летнего времени или когда смещение UTC для текущей зоны уменьшается по политическим причинам). Значения 0 и 1 означают, соответственно, более ранний и более поздний из двух моментов с одинаковым представлением стенного времени.

Added in version 3.6.

Объекты time поддерживают сравнение равенства и порядка, при котором a считается меньше b, если a предшествует b по времени.

Наивные и осведомленные time объекты никогда не равны. Сравнение порядка между наивными и осведомленными time объектами приводит к возникновению TypeError.

Если оба компарада осведомлены и имеют одинаковый атрибут tzinfo, атрибуты tzinfo и fold игнорируются, и сравниваются базовые времена. Если оба компарада осведомлены и имеют разные атрибуты tzinfo, компарады сначала корректируются путем вычитания их смещений UTC (полученных из self.utcoffset()).

Изменено в версии 3.3: Сравнение равенств между знающими и наивными экземплярами time не приводит к появлению TypeError.

В булевых контекстах объект time всегда считается истинным.

Изменено в версии 3.5: До Python 3.5 объект time считался ложным, если он представлял полночь по Гринвичу. Такое поведение считалось неясным и чреватым ошибками и было удалено в Python 3.5. Подробную информацию см. в разделе bpo-13936.

Другой конструктор:

classmethod time.fromisoformat(time_string)¶

Возвращает time, соответствующий временной_строке в любом допустимом формате ISO 8601, за следующими исключениями:

Смещение часового пояса может иметь дробные секунды.
Ведущий T, который обычно требуется в случаях, когда может возникнуть двусмысленность между датой и временем, не нужен.
Дробные секунды могут содержать любое количество цифр (все, что больше 6, будет усечено).
Дробные часы и минуты не поддерживаются.

Примеры:

>>> from datetime import time
>>> time.fromisoformat('04:23:01')
datetime.time(4, 23, 1)
>>> time.fromisoformat('T04:23:01')
datetime.time(4, 23, 1)
>>> time.fromisoformat('T042301')
datetime.time(4, 23, 1)
>>> time.fromisoformat('04:23:01.000384')
datetime.time(4, 23, 1, 384)
>>> time.fromisoformat('04:23:01,000384')
datetime.time(4, 23, 1, 384)
>>> time.fromisoformat('04:23:01+04:00')
datetime.time(4, 23, 1, tzinfo=datetime.timezone(datetime.timedelta(seconds=14400)))
>>> time.fromisoformat('04:23:01Z')
datetime.time(4, 23, 1, tzinfo=datetime.timezone.utc)
>>> time.fromisoformat('04:23:01+00:00')
datetime.time(4, 23, 1, tzinfo=datetime.timezone.utc)

Added in version 3.7.

Изменено в версии 3.11: Ранее этот метод поддерживал только форматы, которые могли быть испущены time.isoformat().

Методы экземпляра:

time.replace(hour=self.hour, minute=self.minute, second=self.second, microsecond=self.microsecond, tzinfo=self.tzinfo, *, fold=0)¶

Возвращает time с тем же значением, за исключением тех атрибутов, которые получили новые значения в зависимости от того, какие аргументы ключевого слова указаны. Обратите внимание, что tzinfo=None может быть указан для создания наивного time из известного time без преобразования данных о времени.

Объекты time также поддерживаются родовой функцией copy.replace().

Изменено в версии 3.6: Добавлен параметр fold.

time.isoformat(timespec='auto')¶

Возвращает строку, представляющую время в формате ISO 8601, одно из значений:

HH:MM:SS.ffffff, если microsecond не 0
HH:MM:SS, если microsecond равен 0
HH:MM:SS.ffffff+HH:MM[:SS[.ffffff]], если utcoffset() не возвращается None
HH:MM:SS+HH:MM[:SS[.ffffff]], если microsecond равен 0, а utcoffset() не равен, возвращается None.

Необязательный аргумент timespec задает количество дополнительных компонентов времени, которые необходимо включить (по умолчанию 'auto'). Это может быть одно из следующих значений:

'auto': То же, что и 'seconds', если microsecond равно 0, то же, что и 'microseconds', в противном случае.
'hours': Включите hour в двузначный формат HH.
'minutes': Включите hour и minute в формат HH:MM.
'seconds': Включите hour, minute и second в формат HH:MM:SS.
'milliseconds': Включить полное время, но усечь дробную часть секунды до миллисекунд. Формат HH:MM:SS.sss.
'microseconds': Включите полный рабочий день в формате HH:MM:SS.ffffff.

Примечание

Исключенные компоненты времени усекаются, а не округляются.

ValueError будет поднята при недопустимом аргументе timespec.

Пример:

>>> from datetime import time
>>> time(hour=12, minute=34, second=56, microsecond=123456).isoformat(timespec='minutes')
'12:34'
>>> dt = time(hour=12, minute=34, second=56, microsecond=0)
>>> dt.isoformat(timespec='microseconds')
'12:34:56.000000'
>>> dt.isoformat(timespec='auto')
'12:34:56'

Изменено в версии 3.6: Добавлен параметр timespec.

time.__str__()¶: В течение времени t str(t) эквивалентен t.isoformat().

time.strftime(format)¶: Возвращает строку, представляющую время, управляемое явной строкой формата. См. также strftime() и strptime() Поведение и time.isoformat().

time.__format__(format)¶: Аналогично time.strftime(). Это позволяет задать строку формата для объекта time в formatted string literals и при использовании str.format(). См. также strftime() и strptime() Поведение и time.isoformat().

time.utcoffset()¶: Если tzinfo является None, возвращает None, иначе возвращает self.tzinfo.utcoffset(None), и вызывает исключение, если не возвращает None или объект timedelta с величиной меньше одного дня.

Изменено в версии 3.7: Смещение UTC не ограничивается целым числом минут.

time.dst()¶: Если tzinfo является None, возвращает None, иначе возвращает self.tzinfo.dst(None), и вызывает исключение, если не возвращает None, или объект timedelta с величиной меньше одного дня.

Изменено в версии 3.7: Смещение DST не ограничивается целым числом минут.

time.tzname()¶: Если tzinfo равно None, возвращает None, иначе возвращает self.tzinfo.tzname(None), или вызывает исключение, если не возвращает None или строковый объект.

Примеры использования: `time`¶

Примеры работы с объектом time:

>>> from datetime import time, tzinfo, timedelta
>>> class TZ1(tzinfo):
...     def utcoffset(self, dt):
...         return timedelta(hours=1)
...     def dst(self, dt):
...         return timedelta(0)
...     def tzname(self,dt):
...         return "+01:00"
...     def  __repr__(self):
...         return f"{self.__class__.__name__}()"
...
>>> t = time(12, 10, 30, tzinfo=TZ1())
>>> t
datetime.time(12, 10, 30, tzinfo=TZ1())
>>> t.isoformat()
'12:10:30+01:00'
>>> t.dst()
datetime.timedelta(0)
>>> t.tzname()
'+01:00'
>>> t.strftime("%H:%M:%S %Z")
'12:10:30 +01:00'
>>> 'The {} is {:%H:%M}.'.format("time", t)
'The time is 12:10.'

`tzinfo` Объекты¶

class datetime.tzinfo¶

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

Экземпляр (конкретный подкласс) tzinfo может быть передан конструкторам объектов datetime и time. Последние объекты рассматривают свои атрибуты как находящиеся в местном времени, а объект tzinfo поддерживает методы, раскрывающие смещение местного времени от UTC, название часового пояса и смещение DST, все относительно переданного им объекта даты или времени.

Вам нужно вывести конкретный подкласс и (как минимум) предоставить реализации стандартных методов tzinfo, необходимых для используемых вами методов datetime. Модуль datetime предоставляет timezone, простой конкретный подкласс tzinfo, который может представлять часовые пояса с фиксированным смещением от UTC, такие как сам UTC или североамериканские EST и EDT.

Особое требование для маринования: Подкласс tzinfo должен иметь метод __init__(), который может быть вызван без аргументов, иначе он может быть замаринован, но, возможно, не может быть замаринован снова. Это техническое требование, которое может быть смягчено в будущем.

Конкретному подклассу tzinfo может потребоваться реализация следующих методов. То, какие именно методы необходимы, зависит от того, как будут использоваться объекты aware datetime. Если вы сомневаетесь, просто реализуйте их все.

tzinfo.utcoffset(dt)¶

Возвращает смещение местного времени относительно UTC в виде объекта timedelta, который является положительным к востоку от UTC. Если местное время находится к западу от UTC, это значение должно быть отрицательным.

Это значение представляет собой общее смещение относительно UTC; например, если объект tzinfo представляет корректировки часового пояса и DST, utcoffset() должен возвращать их сумму. Если смещение UTC неизвестно, верните None. В противном случае возвращаемое значение должно быть объектом timedelta строго между -timedelta(hours=24) и timedelta(hours=24) (величина смещения должна быть меньше одного дня). Большинство реализаций utcoffset(), вероятно, будут выглядеть как одна из этих двух:

return CONSTANT                 # fixed-offset class
return CONSTANT + self.dst(dt)  # daylight-aware class

Если utcoffset() не возвращает None, то dst() тоже не должен возвращать None.

Реализация по умолчанию utcoffset() поднимает NotImplementedError.

Изменено в версии 3.7: Смещение UTC не ограничивается целым числом минут.

tzinfo.dst(dt)¶

Возвращает корректировку перехода на летнее время (DST) в виде объекта timedelta или None, если информация о DST неизвестна.

Верните timedelta(0), если DST не действует. Если DST действует, верните смещение как объект timedelta (подробности см. в utcoffset()). Обратите внимание, что смещение DST, если оно применимо, уже добавлено к смещению UTC, возвращаемому utcoffset(), поэтому нет необходимости обращаться к dst(), если вы не заинтересованы в получении информации о DST отдельно. Например, datetime.timetuple() вызывает метод dst() своего атрибута tzinfo, чтобы определить, как должен быть установлен флаг tm_isdst, а tzinfo.fromutc() вызывает dst(), чтобы учесть изменения DST при пересечении часовых поясов.

Экземпляр tz подкласса tzinfo, который моделирует как стандартное, так и дневное время, должен быть последовательным в этом смысле:

tz.utcoffset(dt) - tz.dst(dt)

должен возвращать один и тот же результат для каждого datetime dt с dt.tzinfo == tz. Для вменяемых подклассов tzinfo это выражение дает «стандартное смещение» часового пояса, которое не должно зависеть от даты или времени, а только от географического положения. Реализация datetime.astimezone() полагается на это, но не может обнаружить нарушения; ответственность за это лежит на программисте. Если подкласс tzinfo не может гарантировать этого, он может переопределить реализацию по умолчанию tzinfo.fromutc(), чтобы корректно работать с astimezone() независимо от этого.

Большинство реализаций dst(), вероятно, будут выглядеть как одна из этих двух:

def dst(self, dt):
    # a fixed-offset class:  doesn't account for DST
    return timedelta(0)

или:

def dst(self, dt):
    # Code to set dston and dstoff to the time zone's DST
    # transition times based on the input dt.year, and expressed
    # in standard local time.

    if dston <= dt.replace(tzinfo=None) < dstoff:
        return timedelta(hours=1)
    else:
        return timedelta(0)

Реализация по умолчанию dst() поднимает NotImplementedError.

Изменено в версии 3.7: Смещение DST не ограничивается целым числом минут.

tzinfo.tzname(dt)¶

Возвращает имя часового пояса, соответствующее объекту datetime dt, в виде строки. Модуль datetime ничего не определяет об именах строк, и нет никаких требований, чтобы они означали что-то конкретное. Например, "GMT", "UTC", "-500", "-5:00", "EDT", "US/Eastern", "America/New York" - все это допустимые ответы. Верните None, если имя строки неизвестно. Обратите внимание, что это метод, а не фиксированная строка, прежде всего потому, что некоторые подклассы tzinfo захотят возвращать разные имена в зависимости от конкретного переданного значения dt, особенно если класс tzinfo учитывает летнее время.

Реализация по умолчанию tzname() поднимает NotImplementedError.

Эти методы вызываются объектом datetime или time в ответ на их одноименные методы. Объект datetime передает себя в качестве аргумента, а объект time передает None в качестве аргумента. Поэтому методы подкласса tzinfo должны быть готовы принять аргумент dt из None или класса datetime.

Если передается None, разработчик класса сам решает, как лучше поступить. Например, возврат None уместен, если класс хочет сказать, что объекты времени не участвуют в протоколах tzinfo. Для utcoffset(None) может быть более полезным возвращать стандартное смещение UTC, поскольку не существует другой конвенции для определения стандартного смещения.

Когда объект datetime передается в ответ на метод datetime, dt.tzinfo - это тот же объект, что и self. Методы tzinfo могут полагаться на это, если только пользовательский код не вызывает методы tzinfo напрямую. Цель состоит в том, чтобы методы tzinfo интерпретировали dt как местное время и не беспокоились об объектах в других часовых поясах.

Существует еще один метод tzinfo, который подкласс может захотеть переопределить:

tzinfo.fromutc(dt)¶

Эта функция вызывается из стандартной реализации datetime.astimezone(). При вызове из нее dt.tzinfo - это self, а данные даты и времени dt должны рассматриваться как выражающие время UTC. Цель fromutc() - скорректировать данные даты и времени, вернув эквивалентное время в локальном времени self.

Большинство подклассов tzinfo смогут без проблем наследовать реализацию fromutc() по умолчанию. Она достаточно сильна, чтобы обрабатывать часовые пояса с фиксированным смещением, а также часовые пояса, учитывающие как стандартное, так и летнее время, причем последнее даже в том случае, если время перехода на DST отличается в разные годы. Примером часового пояса, с которым реализация fromutc() по умолчанию может работать не во всех случаях, является тот, в котором стандартное смещение (от UTC) зависит от конкретной прошедшей даты и времени, что может происходить по политическим причинам. Реализации astimezone() и fromutc() по умолчанию могут не дать желаемого результата, если результат - один из часов, совпадающих с моментом изменения стандартного смещения.

Пропуская код для случаев ошибок, реализация fromutc() по умолчанию действует следующим образом:

def fromutc(self, dt):
    # raise ValueError error if dt.tzinfo is not self
    dtoff = dt.utcoffset()
    dtdst = dt.dst()
    # raise ValueError if dtoff is None or dtdst is None
    delta = dtoff - dtdst  # this is self's standard offset
    if delta:
        dt += delta   # convert to standard local time
        dtdst = dt.dst()
        # raise ValueError if dtdst is None
    if dtdst:
        return dt + dtdst
    else:
        return dt

В следующем файле tzinfo_examples.py приведено несколько примеров классов tzinfo:

from datetime import tzinfo, timedelta, datetime

ZERO = timedelta(0)
HOUR = timedelta(hours=1)
SECOND = timedelta(seconds=1)

# A class capturing the platform's idea of local time.
# (May result in wrong values on historical times in
#  timezones where UTC offset and/or the DST rules had
#  changed in the past.)
import time as _time

STDOFFSET = timedelta(seconds = -_time.timezone)
if _time.daylight:
    DSTOFFSET = timedelta(seconds = -_time.altzone)
else:
    DSTOFFSET = STDOFFSET

DSTDIFF = DSTOFFSET - STDOFFSET

class LocalTimezone(tzinfo):

    def fromutc(self, dt):
        assert dt.tzinfo is self
        stamp = (dt - datetime(1970, 1, 1, tzinfo=self)) // SECOND
        args = _time.localtime(stamp)[:6]
        dst_diff = DSTDIFF // SECOND
        # Detect fold
        fold = (args == _time.localtime(stamp - dst_diff))
        return datetime(*args, microsecond=dt.microsecond,
                        tzinfo=self, fold=fold)

    def utcoffset(self, dt):
        if self._isdst(dt):
            return DSTOFFSET
        else:
            return STDOFFSET

    def dst(self, dt):
        if self._isdst(dt):
            return DSTDIFF
        else:
            return ZERO

    def tzname(self, dt):
        return _time.tzname[self._isdst(dt)]

    def _isdst(self, dt):
        tt = (dt.year, dt.month, dt.day,
              dt.hour, dt.minute, dt.second,
              dt.weekday(), 0, 0)
        stamp = _time.mktime(tt)
        tt = _time.localtime(stamp)
        return tt.tm_isdst > 0

Local = LocalTimezone()


# A complete implementation of current DST rules for major US time zones.

def first_sunday_on_or_after(dt):
    days_to_go = 6 - dt.weekday()
    if days_to_go:
        dt += timedelta(days_to_go)
    return dt


# US DST Rules
#
# This is a simplified (i.e., wrong for a few cases) set of rules for US
# DST start and end times. For a complete and up-to-date set of DST rules
# and timezone definitions, visit the Olson Database (or try pytz):
# http://www.twinsun.com/tz/tz-link.htm
# https://sourceforge.net/projects/pytz/ (might not be up-to-date)
#
# In the US, since 2007, DST starts at 2am (standard time) on the second
# Sunday in March, which is the first Sunday on or after Mar 8.
DSTSTART_2007 = datetime(1, 3, 8, 2)
# and ends at 2am (DST time) on the first Sunday of Nov.
DSTEND_2007 = datetime(1, 11, 1, 2)
# From 1987 to 2006, DST used to start at 2am (standard time) on the first
# Sunday in April and to end at 2am (DST time) on the last
# Sunday of October, which is the first Sunday on or after Oct 25.
DSTSTART_1987_2006 = datetime(1, 4, 1, 2)
DSTEND_1987_2006 = datetime(1, 10, 25, 2)
# From 1967 to 1986, DST used to start at 2am (standard time) on the last
# Sunday in April (the one on or after April 24) and to end at 2am (DST time)
# on the last Sunday of October, which is the first Sunday
# on or after Oct 25.
DSTSTART_1967_1986 = datetime(1, 4, 24, 2)
DSTEND_1967_1986 = DSTEND_1987_2006

def us_dst_range(year):
    # Find start and end times for US DST. For years before 1967, return
    # start = end for no DST.
    if 2006 < year:
        dststart, dstend = DSTSTART_2007, DSTEND_2007
    elif 1986 < year < 2007:
        dststart, dstend = DSTSTART_1987_2006, DSTEND_1987_2006
    elif 1966 < year < 1987:
        dststart, dstend = DSTSTART_1967_1986, DSTEND_1967_1986
    else:
        return (datetime(year, 1, 1), ) * 2

    start = first_sunday_on_or_after(dststart.replace(year=year))
    end = first_sunday_on_or_after(dstend.replace(year=year))
    return start, end


class USTimeZone(tzinfo):

    def __init__(self, hours, reprname, stdname, dstname):
        self.stdoffset = timedelta(hours=hours)
        self.reprname = reprname
        self.stdname = stdname
        self.dstname = dstname

    def __repr__(self):
        return self.reprname

    def tzname(self, dt):
        if self.dst(dt):
            return self.dstname
        else:
            return self.stdname

    def utcoffset(self, dt):
        return self.stdoffset + self.dst(dt)

    def dst(self, dt):
        if dt is None or dt.tzinfo is None:
            # An exception may be sensible here, in one or both cases.
            # It depends on how you want to treat them.  The default
            # fromutc() implementation (called by the default astimezone()
            # implementation) passes a datetime with dt.tzinfo is self.
            return ZERO
        assert dt.tzinfo is self
        start, end = us_dst_range(dt.year)
        # Can't compare naive to aware objects, so strip the timezone from
        # dt first.
        dt = dt.replace(tzinfo=None)
        if start + HOUR <= dt < end - HOUR:
            # DST is in effect.
            return HOUR
        if end - HOUR <= dt < end:
            # Fold (an ambiguous hour): use dt.fold to disambiguate.
            return ZERO if dt.fold else HOUR
        if start <= dt < start + HOUR:
            # Gap (a non-existent hour): reverse the fold rule.
            return HOUR if dt.fold else ZERO
        # DST is off.
        return ZERO

    def fromutc(self, dt):
        assert dt.tzinfo is self
        start, end = us_dst_range(dt.year)
        start = start.replace(tzinfo=self)
        end = end.replace(tzinfo=self)
        std_time = dt + self.stdoffset
        dst_time = std_time + HOUR
        if end <= dst_time < end + HOUR:
            # Repeated hour
            return std_time.replace(fold=1)
        if std_time < start or dst_time >= end:
            # Standard time
            return std_time
        if start <= std_time < end - HOUR:
            # Daylight saving time
            return dst_time


Eastern  = USTimeZone(-5, "Eastern",  "EST", "EDT")
Central  = USTimeZone(-6, "Central",  "CST", "CDT")
Mountain = USTimeZone(-7, "Mountain", "MST", "MDT")
Pacific  = USTimeZone(-8, "Pacific",  "PST", "PDT")

Обратите внимание, что в подклассе tzinfo, учитывающем как стандартное, так и летнее время, дважды в год возникают неизбежные тонкости в точках перехода на DST. Для конкретности рассмотрим восточное время США (UTC -0500), где EDT начинается через минуту после 1:59 (EST) во второе воскресенье марта и заканчивается через минуту после 1:59 (EDT) в первое воскресенье ноября:

  UTC   3:MM  4:MM  5:MM  6:MM  7:MM  8:MM
  EST  22:MM 23:MM  0:MM  1:MM  2:MM  3:MM
  EDT  23:MM  0:MM  1:MM  2:MM  3:MM  4:MM

start  22:MM 23:MM  0:MM  1:MM  3:MM  4:MM

  end  23:MM  0:MM  1:MM  1:MM  2:MM  3:MM

Когда начинается DST (линия «начало»), местные настенные часы переходят с 1:59 на 3:00. Настенное время в виде 2:ММ не имеет смысла в этот день, поэтому astimezone(Eastern) не даст результата с hour == 2 в день начала перехода на зимнее время. Например, при весеннем переходе 2016 года мы получим:

>>> from datetime import datetime, timezone
>>> from tzinfo_examples import HOUR, Eastern
>>> u0 = datetime(2016, 3, 13, 5, tzinfo=timezone.utc)
>>> for i in range(4):
...     u = u0 + i*HOUR
...     t = u.astimezone(Eastern)
...     print(u.time(), 'UTC =', t.time(), t.tzname())
...
05:00:00 UTC = 00:00:00 EST
06:00:00 UTC = 01:00:00 EST
07:00:00 UTC = 03:00:00 EDT
08:00:00 UTC = 04:00:00 EDT

Когда DST заканчивается (линия «end»), возникает потенциально более серьезная проблема: появляется час, который нельзя однозначно написать в местном поясном времени: последний час дневного времени. В Восточном регионе это время вида 5:MM UTC в день окончания светового дня. Местные настенные часы перескакивают с 1:59 (летнее время) обратно на 1:00 (стандартное время). Местное время в форме 1:MM неоднозначно. astimezone() имитирует поведение местных часов, сопоставляя два соседних часа UTC с одним и тем же местным часом. В примере с Востоком время UTC в форме 5:MM и 6:MM оба отображаются в 1:MM при преобразовании в Восточное, но у более раннего времени атрибут fold установлен в 0, а у более позднего - в 1. Например, при обратном переходе 2016 года мы получаем:

>>> u0 = datetime(2016, 11, 6, 4, tzinfo=timezone.utc)
>>> for i in range(4):
...     u = u0 + i*HOUR
...     t = u.astimezone(Eastern)
...     print(u.time(), 'UTC =', t.time(), t.tzname(), t.fold)
...
04:00:00 UTC = 00:00:00 EDT 0
05:00:00 UTC = 01:00:00 EDT 0
06:00:00 UTC = 01:00:00 EST 1
07:00:00 UTC = 02:00:00 EST 0

Обратите внимание, что экземпляры datetime, отличающиеся только значением атрибута fold, считаются равными при сравнении.

Приложениям, не переносящим двусмысленности времени, следует явно проверять значение атрибута fold или избегать использования гибридных подклассов tzinfo; при использовании timezone или любого другого подкласса с фиксированным смещением tzinfo (например, класса, представляющего только EST (фиксированное смещение -5 часов) или только EDT (фиксированное смещение -4 часа)) двусмысленности не возникает.

См.также

zoneinfo
Модуль datetime имеет базовый класс timezone (для работы с произвольными фиксированными смещениями от UTC) и его атрибут timezone.utc (экземпляр часового пояса UTC).

zoneinfo привносит базу данных часовых поясов IANA (также известную как база данных Olson) в Python, и ее использование рекомендуется.

IANA timezone database: База данных часовых поясов (часто называемая tz, tzdata или zoneinfo) содержит код и данные, отражающие историю местного времени для многих репрезентативных точек земного шара. Она периодически обновляется, чтобы отразить изменения, внесенные политическими органами в границы часовых поясов, смещения UTC и правила перехода на летнее время.

`timezone` Объекты¶

Класс timezone является подклассом класса tzinfo, каждый экземпляр которого представляет часовой пояс, определяемый фиксированным смещением от UTC.

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

class datetime.timezone(offset, name=None)¶

Аргумент offset должен быть указан как объект timedelta, представляющий разницу между местным временем и UTC. Он должен находиться строго между -timedelta(hours=24) и timedelta(hours=24), иначе будет задано значение ValueError.

Аргумент name является необязательным. Если он указан, то это должна быть строка, которая будет использоваться в качестве значения, возвращаемого методом datetime.tzname().

Added in version 3.2.

Изменено в версии 3.7: Смещение UTC не ограничивается целым числом минут.

timezone.utcoffset(dt)¶

Возвращает фиксированное значение, указанное при создании экземпляра timezone.

Аргумент dt игнорируется. Возвращаемое значение - экземпляр timedelta, равный разнице между местным временем и UTC.

Изменено в версии 3.7: Смещение UTC не ограничивается целым числом минут.

timezone.tzname(dt)¶

Возвращает фиксированное значение, указанное при создании экземпляра timezone.

Если в конструкторе не указано name, то имя, возвращаемое по tzname(dt), формируется из значения offset следующим образом. Если offset равно timedelta(0), то имя будет «UTC», иначе это строка в формате UTC±HH:MM, где ± - знак offset, HH и MM - две цифры offset.hours и offset.minutes соответственно.

Изменено в версии 3.6: Имя, сгенерированное из offset=timedelta(0), теперь является обычным 'UTC', а не 'UTC+00:00'.

timezone.dst(dt)¶: Всегда возвращает None.

timezone.fromutc(dt)¶: Возвращает dt + offset. Аргумент dt должен быть экземпляром aware datetime, а tzinfo установлен на self.

Атрибуты класса:

timezone.utc¶: Часовой пояс UTC, timezone(timedelta(0)).

`strftime()` и `strptime()` Поведение¶

Объекты date, datetime и time поддерживают метод strftime(format) для создания строки, представляющей время под управлением явной строки формата.

И наоборот, метод класса datetime.strptime() создает объект datetime из строки, представляющей дату и время, и соответствующей строки формата.

В таблице ниже представлено высокоуровневое сравнение strftime() и strptime():

	`strftime`	`strptime`
Использование	Преобразование объекта в строку в соответствии с заданным форматом	Разбор строки в объект `datetime`, заданный соответствующим форматом
Тип метода	Метод экземпляра	Метод класса
Метод	`date`; `datetime`; `time`	`datetime`
Подпись	`strftime(format)`	`strptime(date_string, format)`

`strftime()` и `strptime()` Коды формата¶

Эти методы принимают коды формата, которые можно использовать для разбора и форматирования дат:

>>> datetime.strptime('31/01/22 23:59:59.999999',
...                   '%d/%m/%y %H:%M:%S.%f')
datetime.datetime(2022, 1, 31, 23, 59, 59, 999999)
>>> _.strftime('%a %d %b %Y, %I:%M%p')
'Mon 31 Jan 2022, 11:59PM'

Ниже приведен список всех форматных кодов, которые требует стандарт C 1989 года, и они работают на всех платформах со стандартной реализацией C.

Директива	Значение	Пример	Примечания
`%a`	Будний день в виде сокращенного названия локали.	Sun, Mon, …, Sat (en_US); So, Mo, …, Sa (de_DE)	(1)
`%A`	Weekday в качестве полного имени локали.	Воскресенье, понедельник, …, суббота (en_US); Sonntag, Montag, …, Samstag (de_DE)	(1)
`%w`	День недели в виде десятичного числа, где 0 - воскресенье, а 6 - суббота.	0, 1, …, 6
`%d`	День месяца в виде десятичного числа с нулевой добавкой.	01, 02, …, 31	(9)
`%b`	Месяц как сокращенное название локали.	Январь, февраль, …, декабрь (en_US); Jan, Feb, …, Dez (de_DE)	(1)
`%B`	Месяц как полное имя локали.	Январь, февраль, …, декабрь (en_US); Январь, февраль, …, декабрь (de_DE)	(1)
`%m`	Месяц в виде десятичного числа с нулевой добавкой.	01, 02, …, 12	(9)
`%y`	Год без века в виде десятичного числа с нулевой добавкой.	00, 01, …, 99	(9)
`%Y`	Год с веком в виде десятичного числа.	0001, 0002, …, 2013, 2014, …, 9998, 9999	(2)
`%H`	Час (24-часовые часы) в виде десятичного числа с нулевой добавкой.	00, 01, …, 23	(9)
`%I`	Час (12-часовые часы) в виде десятичного числа с нулевой добавкой.	01, 02, …, 12	(9)
`%p`	Эквивалент AM или PM в локали.	AM, PM (en_US); утро, вечер (de_DE)	(1), (3)
`%M`	Минута в виде десятичного числа с нулевой добавкой.	00, 01, …, 59	(9)
`%S`	Второе в виде десятичного числа с нулевой добавкой.	00, 01, …, 59	(4), (9)
`%f`	Микросекунда в виде десятичного числа с нулевым добавлением до 6 цифр.	000000, 000001, …, 999999	(5)
`%z`	Смещение UTC в виде `±HHMM[SS[.ffffff]]` (пустая строка, если объект наивный).	(пусто), +0000, -0400, +1030, +063415, -030712.345216	(6)
`%Z`	Имя часового пояса (пустая строка, если объект является наивным).	(пусто), UTC, GMT	(6)
`%j`	День года в виде десятичного числа с нулевой добавкой.	001, 002, …, 366	(9)
`%U`	Номер недели года (воскресенье - первый день недели) в виде десятичного числа с нулевой добавкой. Все дни в новом году, предшествующие первому воскресенью, считаются неделей 0.	00, 01, …, 53	(7), (9)
`%W`	Номер недели в году (понедельник - первый день недели) в виде десятичного числа с нулевой добавкой. Все дни в новом году, предшествующие первому понедельнику, считаются неделей 0.	00, 01, …, 53	(7), (9)
`%c`	Соответствующее представление даты и времени в локали.	Tue Aug 16 21:30:00 1988 (en_US); Di 16 Aug 21:30:00 1988 (de_DE)	(1)
`%x`	Соответствующее представление даты в локали.	08/16/88 (Нет); 08/16/1988 (en_US); 16.08.1988 (de_DE)	(1)
`%X`	Соответствующее представление времени в локали.	21:30:00 (en_US); 21:30:00 (de_DE)	(1)
`%%`	Буквальный символ `'%'`.	%

Для удобства включены несколько дополнительных директив, не требуемых стандартом C89. Все эти параметры соответствуют значениям даты ISO 8601.

Директива	Значение	Пример	Примечания
`%G`	Год ISO 8601 с веком, представляющий год, который содержит большую часть недели ISO (`%V`).	0001, 0002, …, 2013, 2014, …, 9998, 9999	(8)
`%u`	День недели по стандарту ISO 8601 в виде десятичного числа, где 1 - понедельник.	1, 2, …, 7
`%V`	Неделя в стандарте ISO 8601 - десятичное число с понедельником в качестве первого дня недели. Неделя 01 - это неделя, содержащая 4 января.	01, 02, …, 53	(8), (9)
`%:z`	Смещение UTC в виде `±HH:MM[:SS[.ffffff]]` (пустая строка, если объект наивный).	(пусто), +00:00, -04:00, +10:30, +06:34:15, -03:07:12.345216	(6)

Они могут быть доступны не на всех платформах при использовании метода strftime(). Директивы ISO 8601 year и ISO 8601 week не являются взаимозаменяемыми с вышеуказанными директивами year и week number. Вызов strptime() с неполными или неоднозначными директивами ISO 8601 приведет к ошибке ValueError.

Полный набор поддерживаемых форматных кодов различается на разных платформах, поскольку Python вызывает функцию strftime() библиотеки Platform C, и различия между платформами обычны. Чтобы узнать полный набор кодов форматов, поддерживаемых на вашей платформе, обратитесь к документации strftime(3). Также платформы различаются по обработке неподдерживаемых спецификаторов формата.

Added in version 3.6: Были добавлены %G, %u и %V.

Added in version 3.12: %:z был добавлен.

Технические детали¶

В общем случае d.strftime(fmt) действует как time модуля time.strftime(fmt, d.timetuple()), хотя не все объекты поддерживают метод timetuple().

Для метода класса datetime.strptime() значением по умолчанию является 1900-01-01T00:00:00.000: все компоненты, не указанные в строке формата, будут взяты из значения по умолчанию. [4]

Использование datetime.strptime(date_string, format) эквивалентно:

datetime(*(time.strptime(date_string, format)[0:6]))

за исключением случаев, когда формат включает субсекундные компоненты или информацию о смещении часового пояса, которые поддерживаются в datetime.strptime, но отбрасываются в time.strptime.

Для объектов time коды формата для года, месяца и дня не должны использоваться, поскольку объекты time не имеют таких значений. Если они все же используются, то для года подставляется 1900, а для месяца и дня - 1.

Для объектов date не следует использовать коды формата часов, минут, секунд и микросекунд, поскольку объекты date не имеют таких значений. Если они все равно используются, вместо них подставляется 0.

По этой же причине обработка строк формата, содержащих кодовые точки Unicode, которые не могут быть представлены в кодировке текущей локали, также зависит от платформы. На некоторых платформах такие кодовые точки сохраняются в выводе, а на других strftime может вызвать UnicodeError или вернуть пустую строку.

Примечания:

Поскольку формат зависит от текущей локали, следует быть осторожным, делая предположения о выходном значении. Порядок полей будет отличаться (например, «месяц/день/год» от «день/месяц/год»), а выходные данные могут содержать символы, отличные от ASCII.
Метод strptime() может обрабатывать годы в полном диапазоне [1, 9999], но годы < 1000 должны быть заполнены нулями до 4-значной ширины.

Изменено в версии 3.2: В предыдущих версиях метод strftime() был ограничен годами >= 1900.

Изменено в версии 3.3: В версии 3.2 метод strftime() был ограничен годами >= 1000.
При использовании метода strptime() директива %p влияет на выходное поле часа только в том случае, если для разбора часа используется директива %I.
В отличие от модуля time, модуль datetime не поддерживает високосные секунды.
При использовании с методом strptime() директива %f принимает от одной до шести цифр и нулевые прокладки справа. %f - это расширение набора символов формата, предусмотренного стандартом C (но реализованного отдельно в объектах datetime и поэтому всегда доступного).
Для наивного объекта коды формата %z, %:z и %Z заменяются пустыми строками.

Для осознанного объекта:

%z
utcoffset() преобразуется в строку вида ±HHMM[SS[.ffffff]], где HH - двузначная строка, указывающая количество часов со смещением UTC, MM - двузначная строка, указывающая количество минут со смещением UTC, SS - двузначная строка, указывающая количество секунд со смещением UTC, и ffffff - шестизначная строка, указывающая количество микросекунд со смещением UTC. Часть ffffff опускается, если смещение составляет целое число секунд, и обе части ffffff и SS опускаются, если смещение составляет целое число минут. Например, если utcoffset() возвращает timedelta(hours=-3, minutes=-30), то %z заменяется строкой '-0330'.

Изменено в версии 3.7: Смещение UTC не ограничивается целым числом минут.

Изменено в версии 3.7: Когда методу strptime() передается директива %z, смещения UTC могут содержать двоеточие в качестве разделителя между часами, минутами и секундами. Например, '+01:00:00' будет разобрано как смещение на один час. Кроме того, указание 'Z' идентично '+00:00'.
%:z
Ведет себя так же, как %z, но между часами, минутами и секундами добавляется разделитель в виде двоеточия.

%Z
В strftime() %Z заменяется пустой строкой, если tzname() возвращает None; в противном случае %Z заменяется возвращаемым значением, которое должно быть строкой.

strptime() принимает только определенные значения для %Z:
1. любое значение в time.tzname для локали вашего компьютера
2. жестко закодированные значения UTC и GMT.
Так, у человека, живущего в Японии, допустимыми значениями могут быть JST, UTC и GMT, но, вероятно, не EST. Для недопустимых значений будет выдано сообщение ValueError.
Изменено в версии 3.2: Когда методу strptime() передается директива %z, будет создан объект datetime с информацией. В качестве tzinfo результата будет установлен экземпляр timezone.
При использовании метода strptime(), %U и %W используются в расчетах только в том случае, если указаны день недели и календарный год (%Y).
Как и %U и %W, %V используется в расчетах только в том случае, если день недели и год ISO (%G) указаны в строке формата strptime(). Также обратите внимание, что %G и %Y не являются взаимозаменяемыми.
При использовании метода strptime() ведущий ноль необязателен для форматов %d, %m, %H, %I, %M, %S, %j, %U, %W и %V. Формат %y требует ведущего нуля.
При разборе месяца и дня с помощью strptime() всегда включайте год в формат. Если в значении, которое вам нужно разобрать, отсутствует год, добавьте явный фиктивный високосный год. В противном случае при столкновении с високосным днем ваш код будет вызывать исключение, поскольку год по умолчанию, используемый парсером, не является високосным. Пользователи сталкиваются с этой ошибкой каждые четыре года…
```
>>> month_day = "02/29"
>>> datetime.strptime(f"{month_day};1984", "%m/%d;%Y")  # No leap year bug.
datetime.datetime(1984, 2, 29, 0, 0)
```
Утратил актуальность с версии 3.13, будет удален в версии 3.15: Вызовы strptime(), использующие строку формата, содержащую день месяца без года, теперь выдают DeprecationWarning. В версии 3.15 или более поздней мы можем изменить это на ошибку или изменить год по умолчанию на високосный. См. gh-70647.

Сноски

`datetime` — Основные типы даты и времени¶

Осознанные и наивные объекты¶

Константы¶

Доступные типы¶

Общие свойства¶

Определение осведомленности или наивности объекта¶

`timedelta` Объекты¶

Примеры использования: `timedelta`¶

`date` Объекты¶

Примеры использования: `date`¶

`datetime` Объекты¶

Примеры использования: `datetime`¶

`time` Объекты¶

Примеры использования: `time`¶

`tzinfo` Объекты¶

`timezone` Объекты¶

`strftime()` и `strptime()` Поведение¶

`strftime()` и `strptime()` Коды формата¶

Технические детали¶

Оглавление

Предыдущий раздел

Следующий раздел

datetime — Основные типы даты и времени¶

Осознанные и наивные объекты¶

Константы¶

Доступные типы¶

Общие свойства¶

Определение осведомленности или наивности объекта¶

timedelta Объекты¶

Примеры использования: timedelta¶

date Объекты¶

Примеры использования: date¶

datetime Объекты¶

Примеры использования: datetime¶

time Объекты¶

Примеры использования: time¶

tzinfo Объекты¶

timezone Объекты¶

strftime() и strptime() Поведение¶

strftime() и strptime() Коды формата¶

Технические детали¶

`datetime` — Основные типы даты и времени¶

`timedelta` Объекты¶

Примеры использования: `timedelta`¶

`date` Объекты¶

Примеры использования: `date`¶

`datetime` Объекты¶

Примеры использования: `datetime`¶

`time` Объекты¶

Примеры использования: `time`¶

`tzinfo` Объекты¶

`timezone` Объекты¶

`strftime()` и `strptime()` Поведение¶

`strftime()` и `strptime()` Коды формата¶