datetime – Основные типы даты и времени¶datetime – Basic date and time types

Осведомлённые и наивные объекты¶Aware and naive objects

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

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

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

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

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

Константы¶Constants

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

datetime.MINYEAR¶

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

datetime.MAXYEAR¶

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

datetime.UTC¶

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

Добавлено в версии 3.12.

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

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.

Добавлено в версии 3.2.

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

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

timedelta объекты¶timedelta objects

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

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

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

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

• Миллисекунда преобразуется в 1000 микросекунд.

• Минута преобразуется в 60 секунд.

• Час преобразуется в 3600 секунд.

• Неделя преобразуется в 7 дней.

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

• 0 <= microseconds < 1000000

• 0 <= seconds < 3600*24 (количество секунд в одном дне)

• -999999999 <= days <= 999999999

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

>>> import datetime as dt
>>> delta = dt.timedelta(
...     days=50,
...     seconds=27,
...     microseconds=10,
...     milliseconds=29000,
...     minutes=5,
...     hours=8,
...     weeks=2
... )
>>> # Остаются только дни, секунды и микросекунды
>>> delta
datetime.timedelta(days=64, seconds=29156, microseconds=10)

Совет

import datetime as dt вместо import datetime или from datetime import datetime, чтобы избежать путаницы между модулем и классом. См. Как я импортирую модуль datetime в Python.

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

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

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

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

Поскольку строковое представление объектов timedelta может сбивать с толку, используйте следующий рецепт, чтобы получить более читаемый формат:

>>> def pretty_timedelta(td):
...     if td.days >= 0:
...         return str(td)
...     return f'-({-td!s})'
...
>>> d = timedelta(hours=-1)
>>> str(d)  # неудобно для человека
'-1 day, 23:00:00'
>>> pretty_timedelta(d)
'-(1:00:00)'

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

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.

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

timedelta.days¶

От -999,999,999 до 999,999,999 включительно.

timedelta.seconds¶

От 0 до 86,399 включительно.

Внимание

Это довольно распространённая ошибка, когда код непреднамеренно использует этот атрибут, хотя на самом деле предполагается получить значение total_seconds() вместо этого:

>>> import datetime as dt
>>> duration = dt.timedelta(seconds=11235813)
>>> duration.days, duration.seconds
(130, 3813)
>>> duration.total_seconds()
11235813.0

timedelta.microseconds¶

От 0 до 999,999 включительно.

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

Примечания:

1. Это точное, но может привести к переполнению.

2. Это точное и не может привести к переполнению.

3. Деление на ноль вызывает ZeroDivisionError.

4. -timedelta.max не представимо в виде объекта timedelta.

5. Строковые представления timedelta объектов нормализуются аналогично их внутреннему представлению. Это приводит к несколько необычным результатам для отрицательных объектов timedelta. Например:

   >>> timedelta(hours=-5)
   datetime.timedelta(days=-1, seconds=68400)
   >>> print(_)
   -1 day, 19:00:00
   

6. Выражение t2 - t3 всегда будет равно выражению t2 + (-t3), за исключением случая, когда t3 равно timedelta.max; в этом случае первое выражение даст результат, а второе вызовет переполнение.

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

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

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

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

timedelta.total_seconds()¶

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

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

Добавлено в версии 3.2.

>>> # Компоненты another_year в сумме составляют ровно 365 дней
>>> import datetime as dt
>>> year = dt.timedelta(days=365)
>>> another_year = dt.timedelta(weeks=40, days=84, hours=23,
...                             minutes=50, seconds=600)
>>> year == another_year
True
>>> year.total_seconds()
31536000.0

>>> import datetime as dt
>>> year = dt.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 objects

Объект 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 timestamp, такую, как возвращает time.time().

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

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

Изменено в версии 3.15: Принимает любое действительное число в качестве timestamp, а не только целое или число с плавающей запятой.

classmethod date.fromordinal(ordinal)¶

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

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

classmethod date.fromisoformat(date_string)¶

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

1. Даты с пониженной точностью в настоящее время не поддерживаются (YYYY-MM, YYYY).

2. Расширенные представления дат в настоящее время не поддерживаются (±YYYYYY-MM-DD).

3. Порядковые даты в настоящее время не поддерживаются (YYYY-OOO).

Примеры:

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

Добавлено в версии 3.7.

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

classmethod date.fromisocalendar(year, week, day)¶

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

Добавлено в версии 3.8.

classmethod date.strptime(date_string, format)¶

Возвращает date, соответствующий date_string, разобранной в соответствии с format. Это эквивалентно:

date(*(time.strptime(date_string, format)[0:3]))

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

Примечание

Если format указывает день месяца (%d) без года, ValueError возникает. Это позволяет избежать ошибки, связанной с високосным годом, которая происходит раз в четыре года в коде, пытающемся разобрать только месяц и день, поскольку год по умолчанию, используемый при отсутствии года в формате, не является високосным. Обходной путь – всегда включать год в ваш format. При разборе значений date_string, не содержащих года, явно добавьте високосный год перед разбором:

>>> import datetime as dt
>>> date_string = "02/29"
>>> when = dt.date.strptime(f"{date_string};1984", "%m/%d;%Y")  # Избегает ошибки високосного года.
>>> when.strftime("%B %d")
'February 29'

Добавлено в версии 3.14.

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

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 до количества дней в указанном месяце указанного года.

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

Примечания:

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

2. timedelta.seconds и timedelta.microseconds игнорируются.

3. Это точная операция и не может вызвать переполнение. timedelta.seconds и timedelta.microseconds равны 0, а date2 + timedelta == date1 после.

4. Объекты date равны, если они представляют одну и ту же дату.

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

5. date1 считается меньше date2, когда date1 предшествует date2 во времени. Другими словами, date1 < date2 тогда и только тогда, когда date1.toordinal() < date2.toordinal().

   Сравнение порядка между объектом date, не являющимся также экземпляром datetime, и объектом datetime возбуждает TypeError.

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

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

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

Возвращает новый объект date с теми же значениями, но с обновлёнными указанными параметрами.

Пример:

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

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

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()¶

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

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

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

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

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

Изменено в версии 3.9: Результат изменён с кортежа на именованный кортеж.

date.isoformat()¶

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

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

date.__str__()¶

Для даты d str(d) эквивалентно d.isoformat().

date.ctime()¶

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

>>> import datetime as dt
>>> dt.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)¶

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

date.__format__(format)¶

То же, что date.strftime(). Это позволяет задавать строку форматирования для объекта date в форматированных строковых литералах и при использовании str.format(). См. также Поведение strftime() и strptime() и date.isoformat().

>>> import time
>>> import datetime as dt
>>> today = dt.date.today()
>>> today
datetime.date(2007, 12, 5)
>>> today == dt.date.fromtimestamp(time.time())
True
>>> my_birthday = dt.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

>>> import datetime as dt
>>> d = dt.date.fromordinal(730920) # 730920-й день после 1.1.0001
>>> d
datetime.date(2002, 3, 11)

>>> # Методы, связанные с форматированием строкового вывода
>>> 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.'

>>> # Методы для извлечения «компонентов» в разных календарях
>>> 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 )

>>> # Объект date является неизменяемым; все операции создают новый объект
>>> d.replace(year=2005)
datetime.date(2005, 3, 11)

datetime объекты¶datetime objects

Объект 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)¶

Аргументы year, month и day обязательны. 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().

Примечание

Последующие вызовы datetime.now() могут возвращать один и тот же момент времени в зависимости от точности базовых часов.

classmethod datetime.utcnow()¶

Возвращает текущие дату и время UTC, с tzinfo None.

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

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

Поскольку наивные объекты datetime многими методами datetime рассматриваются как местное время, для представления времени в UTC предпочтительнее использовать осведомлённые объекты datetime. Поэтому рекомендуемый способ создания объекта, представляющего текущее время в 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, если метка времени выходит за диапазон значений, поддерживаемых платформенными функциями C localtime() или gmtime(), и OSError при ошибке localtime() или gmtime(). Обычно это ограничено годами с 1970 по 2038. Обратите внимание, что на системах, не совместимых с POSIX, которые включают високосные секунды в своё представление метки времени, високосные секунды игнорируются fromtimestamp(), и поэтому возможно иметь две метки времени, различающиеся на секунду, которые дают идентичные объекты datetime. Этот метод предпочтительнее utcfromtimestamp().

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

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

Изменено в версии 3.15: Принимает любое действительное число в качестве timestamp, а не только целое или число с плавающей запятой.

classmethod datetime.utcfromtimestamp(timestamp)¶

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

Это может возбуждать OverflowError, если метка времени выходит за диапазон значений, поддерживаемых платформенной функцией C gmtime(), и 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-даты. Поэтому рекомендуемый способ создания объекта для конкретной метки времени в UTC – вызов datetime.fromtimestamp(timestamp, tz=timezone.utc).

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

Изменено в версии 3.15: Принимает любое действительное число в качестве timestamp, а не только целое или число с плавающей запятой.

Устарело с версии 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, соответствующий строке date_string в любом допустимом формате ISO 8601, за следующими исключениями:

1. Смещения часовых поясов могут содержать доли секунды.

2. Разделитель T может быть заменён любым отдельным символом Unicode.

3. Доли часов и минут не поддерживаются.

4. Даты с пониженной точностью в настоящее время не поддерживаются (YYYY-MM, YYYY).

5. Расширенные представления дат в настоящее время не поддерживаются (±YYYYYY-MM-DD).

6. Порядковые даты в настоящее время не поддерживаются (YYYY-OOO).

Примеры:

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

Добавлено в версии 3.7.

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

classmethod datetime.fromisocalendar(year, week, day)¶

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

Добавлено в версии 3.8.

classmethod datetime.strptime(date_string, format)¶

Возвращает объект datetime, соответствующий date_string, разобранный в соответствии с format.

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

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

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

Изменено в версии 3.15: Если format задаёт день месяца (%d) без указания года, вызывается ValueError. Это предотвращает ошибку из-за разницы високосных годов, проявляющуюся раз в четыре года: код, разбирающий только месяц и день, использует по умолчанию невисокосный год, так как год в формате не указан. Обходной путь – всегда указывать год в format. Если разбираются значения date_string без года, перед разбором явно добавьте високосный год:

>>> import datetime as dt
>>> date_string = "02/29"
>>> when = dt.datetime.strptime(f"{date_string};1984", "%m/%d;%Y")  # Избегает ошибки високосного года.
>>> 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 представляют соответственно более ранний и более поздний из двух моментов с одинаковым представлением поясного времени.

Добавлено в версии 3.6.

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

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

2. Вычисляет datetime2, такой что datetime2 + timedelta == datetime1. Как и при сложении, результат имеет тот же атрибут tzinfo, что и исходный datetime, и корректировка часового пояса не выполняется, даже если исходный объект осведомлён.

3. Вычитание datetime из datetime определено только если оба операнда наивны или оба осведомлены. Если один осведомлён, а другой наивен, возникает TypeError.

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

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

4. Объекты datetime равны, если они представляют одну и ту же дату и время с учётом часового пояса.

   Наивные и осознающие объекты datetime никогда не равны.

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

5. datetime1 считается меньше datetime2, когда datetime1 предшествует datetime2 во времени с учётом часового пояса.

   Операция сравнения порядка между наивными и осознающими объектами datetime вызывает TypeError.

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

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

datetime.date()¶

Возвращает объект date с тем же годом, месяцем и днём.

datetime.time()¶

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

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

datetime.timetz()¶

Возвращает объект time с теми же атрибутами hour, minute, second, microsecond, fold и tzinfo. См. также метод time().

Изменено в версии 3.6: Значение fold копируется в возвращаемый объект 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 из осознающего без преобразования данных даты и времени.

Объекты 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().

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

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

def astimezone(self, tz):
    if self.tzinfo is tz:
        return self
    # Преобразует self в UTC и присоединяет новый объект часового пояса.
    utc = (self - self.utcoffset()).replace(tzinfo=tz)
    # Преобразует из UTC в местное время tz.
    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(). DST никогда не действует для времени UTC.

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

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

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

datetime.toordinal()¶

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

datetime.timestamp()¶

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

Naive datetime instances are assumed to represent local time and this method relies on platform C functions to perform the conversion. Since datetime supports a wider range of values than the platform C functions on many platforms, this method may raise OverflowError or OSError for times far in the past or far in the future.

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

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

Примечание

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

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

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

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

Добавлено в версии 3.3.

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

Changed in version 3.6: This method no longer relies on the platform C mktime() function to perform conversions.

datetime.weekday()¶

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

datetime.isoweekday()¶

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

datetime.isocalendar()¶

Возвращает именованный кортеж с тремя компонентами: 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

Примеры:

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

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

>>> import datetime as dt
>>> class TZ(dt.tzinfo):
...     """Часовой пояс с произвольным постоянным смещением -06:39."""
...     def utcoffset(self, when):
...         return dt.timedelta(hours=-6, minutes=-39)
...
>>> dt.datetime(2002, 12, 25, tzinfo=TZ()).isoformat(' ')
'2002-12-25 00:00:00-06:39'
>>> dt.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:

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

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

datetime.__str__()¶

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

datetime.ctime()¶

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

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

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

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 в форматированных строковых литералах и при использовании str.format(). См. также Поведение strftime() и strptime() и datetime.isoformat().

>>> import datetime as dt

>>> # Использование datetime.combine()
>>> d = dt.date(2005, 7, 14)
>>> t = dt.time(12, 30)
>>> dt.datetime.combine(d, t)
datetime.datetime(2005, 7, 14, 12, 30)

>>> # Использование datetime.now()
>>> dt.datetime.now()
datetime.datetime(2007, 12, 6, 16, 29, 43, 79043)   # GMT +1
>>> dt.datetime.now(dt.timezone.utc)
datetime.datetime(2007, 12, 6, 15, 29, 43, 79060, tzinfo=datetime.timezone.utc)

>>> # Использование datetime.strptime()
>>> my_datetime = dt.datetime.strptime("21/11/06 16:30", "%d/%m/%y %H:%M")
>>> my_datetime
datetime.datetime(2006, 11, 21, 16, 30)

>>> # Использование datetime.timetuple() для получения кортежа всех атрибутов
>>> tt = my_datetime.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

>>> # Дата в формате ISO
>>> ic = my_datetime.isocalendar()
>>> for it in ic:
...     print(it)
...
2006    # ISO year
47      # ISO week
2       # ISO weekday

>>> # Форматирование datetime
>>> my_datetime.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(my_datetime, "day", "month", "time")
'The day is 21, the month is November, the time is 04:30PM.'

import datetime as dt

class KabulTz(dt.tzinfo):
    # В Кабуле до 1945 года использовали +4, затем перешли на +4:30
    UTC_MOVE_DATE = dt.datetime(1944, 12, 31, 20, tzinfo=dt.timezone.utc)

    def utcoffset(self, when):
        if when.year < 1945:
            return dt.timedelta(hours=4)
        elif (1945, 1, 1, 0, 0) <= when.timetuple()[:5] < (1945, 1, 1, 0, 30):
            # Неоднозначный («мнимый») получасовой диапазон, представляющий
            # «складку» во времени из-за перехода с +4 на +4:30.
            # Если when попадает в мнимый диапазон, используйте fold, чтобы решить, как
            # разрешить неоднозначность. См. PEP 495.
            return dt.timedelta(hours=4, minutes=(30 if when.fold else 0))
        else:
            return dt.timedelta(hours=4, minutes=30)

    def fromutc(self, when):
        # Следуйте тем же проверкам, что и в datetime.tzinfo
        if not isinstance(when, dt.datetime):
            raise TypeError("fromutc() requires a datetime argument")
        if when.tzinfo is not self:
            raise ValueError("when.tzinfo is not self")

        # Для fromutc требуется собственная реализация, так как
        # входные данные для этой функции – это datetime со значениями UTC
        # но с tzinfo, установленным на self.
        # См. datetime.astimezone или fromtimestamp.
        if when.replace(tzinfo=dt.timezone.utc) >= self.UTC_MOVE_DATE:
            return when + dt.timedelta(hours=4, minutes=30)
        else:
            return when + dt.timedelta(hours=4)

    def dst(self, when):
        # В Кабуле не соблюдается летнее время.
        return dt.timedelta(0)

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

>>> tz1 = KabulTz()

>>> # Datetime до изменения
>>> dt1 = dt.datetime(1900, 11, 21, 16, 30, tzinfo=tz1)
>>> print(dt1.utcoffset())
4:00:00

>>> # Datetime после изменения
>>> dt2 = dt.datetime(2006, 6, 14, 13, 0, tzinfo=tz1)
>>> print(dt2.utcoffset())
4:30:00

>>> # Преобразовать datetime в другой часовой пояс
>>> dt3 = dt2.astimezone(dt.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 objects

Объект 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 представляют соответственно более ранний и более поздний из двух моментов с одинаковым представлением поясного времени.

Добавлено в версии 3.6.

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

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

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

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

Другие конструкторы:

classmethod time.fromisoformat(time_string)¶

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

1. Смещения часовых поясов могут содержать доли секунды.

2. Ведущий символ T, обычно обязательный в случаях, когда возможна неоднозначность между датой и временем, не требуется.

3. Доли секунды могут содержать любое количество цифр (всё, что больше 6, будет усечено).

4. Доли часов и минут не поддерживаются.

Примеры:

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

Добавлено в версии 3.7.

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

classmethod time.strptime(date_string, format)¶

Возвращает объект time, соответствующий date_string, разобранный в соответствии с format.

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

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

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

Добавлено в версии 3.14.

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

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.

Пример:

>>> import datetime as dt
>>> dt.time(hour=12, minute=34, second=56, microsecond=123456).isoformat(timespec='minutes')
'12:34'
>>> my_time = dt.time(hour=12, minute=34, second=56, microsecond=0)
>>> my_time.isoformat(timespec='microseconds')
'12:34:56.000000'
>>> my_time.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 в строковых литералах с форматированием и при использовании 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 или строковый объект.

>>> import datetime as dt
>>> class TZ1(dt.tzinfo):
...     def utcoffset(self, when):
...         return dt.timedelta(hours=1)
...     def dst(self, when):
...         return dt.timedelta(0)
...     def tzname(self, when):
...         return "+01:00"
...     def  __repr__(self):
...         return f"{self.__class__.__name__}()"
...
>>> t = dt.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 объекты¶tzinfo objects

class datetime.tzinfo¶

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

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

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

Особое требование для сериализации с помощью pickle: подкласс 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                 # класс с фиксированным смещением
return CONSTANT + self.dst(dt)  # класс, учитывающий летнее время

Если 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(), вероятно, будут выглядеть как один из этих двух вариантов:

import datetime as dt

def dst(self, when):
    # класс с фиксированным смещением: не учитывает летнее время
    return dt.timedelta(0)

или:

import datetime as dt

def dst(self, when):
    # Код для установки dston и dstoff в значения летнего времени часового пояса
    # время перехода на основе входного when.year, выраженное
    # в стандартном местном времени.

    if dston <= when.replace(tzinfo=None) < dstoff:
        return dt.timedelta(hours=1)
    else:
        return dt.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() – скорректировать данные даты и времени, вернув эквивалентный datetime в местном времени self.

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

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

import datetime as dt

def fromutc(self, when):
    # вызывает ValueError, если when.tzinfo не является self
    dtoff = when.utcoffset()
    dtdst = when.dst()
    # вызывает ValueError, если dtoff или dtdst равны None
    delta = dtoff - dtdst  # это стандартное смещение self
    if delta:
        when += delta   # преобразовать в стандартное местное время
        dtdst = when.dst()
        # вызывает ValueError, если dtdst равен None
    if dtdst:
        return when + dtdst
    else:
        return when

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

import datetime as dt

# Класс, отражающий представление платформы о местном времени.
# (Может приводить к неверным значениям для исторических моментов в
#  часовых поясах, где UTC-смещение и/или правила летнего времени
#  менялись в прошлом.)
import time

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

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

DSTDIFF = DSTOFFSET - STDOFFSET


class LocalTimezone(dt.tzinfo):

    def fromutc(self, when):
        assert when.tzinfo is self
        stamp = (when - dt.datetime(1970, 1, 1, tzinfo=self)) // SECOND
        args = time.localtime(stamp)[:6]
        dst_diff = DSTDIFF // SECOND
        # Обнаружение fold
        fold = (args == time.localtime(stamp - dst_diff))
        return dt.datetime(*args, microsecond=when.microsecond,
                           tzinfo=self, fold=fold)

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

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

    def tzname(self, when):
        return time.tzname[self._isdst(when)]

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


Local = LocalTimezone()


# Полная реализация текущих правил летнего времени для основных часовых поясов США.

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


# Правила летнего времени в США
#
# Это упрощённый набор правил для США (т.е. неверный для некоторых случаев)
# времени начала и окончания летнего времени. Полный и актуальный набор правил летнего времени
# и определений часовых поясов смотрите в базе данных Olson (или попробуйте pytz):
# http://www.twinsun.com/tz/tz-link.htm
# https://sourceforge.net/projects/pytz/ (возможно, не актуально)
#
# В США с 2007 года летнее время начинается в 2 часа ночи (стандартное время) во второе
# воскресенье марта, то есть первое воскресенье 8 марта или после него.
DSTSTART_2007 = dt.datetime(1, 3, 8, 2)
# и заканчивается в 2 часа ночи (летнее время) в первое воскресенье ноября.
DSTEND_2007 = dt.datetime(1, 11, 1, 2)
# С 1987 по 2006 год летнее время начиналось в 2 часа ночи (стандартное время) в первое
# воскресенье апреля и заканчивалось в 2 часа ночи (летнее время) в последнее
# воскресенье октября, то есть первое воскресенье 25 октября или после него.
DSTSTART_1987_2006 = dt.datetime(1, 4, 1, 2)
DSTEND_1987_2006 = dt.datetime(1, 10, 25, 2)
# С 1967 по 1986 год летнее время начиналось в 2 часа ночи (стандартное время) в последнее
# воскресенье апреля (то есть 24 апреля или после него) и заканчивалось в 2 часа ночи (летнее время)
# в последнее воскресенье октября, которое является первым воскресеньем
# 25 октября или позднее.
DSTSTART_1967_1986 = dt.datetime(1, 4, 24, 2)
DSTEND_1967_1986 = DSTEND_1987_2006


def us_dst_range(year):
    # Найти время начала и окончания перехода на летнее время в США. Для лет до 1967 года вернуть
    # start = end, если летнее время не применяется.
    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 (dt.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(dt.tzinfo):

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

    def __repr__(self):
        return self.reprname

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

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

    def dst(self, when):
        if when is None or when.tzinfo is None:
            # В одном или обоих случаях здесь может быть уместно исключение.
            # Это зависит от того, как вы хотите их обрабатывать. Реализация по умолчанию
            # fromutc() (вызываемая реализацией astimezone() по умолчанию)
            # передаёт объект datetime, у которого when.tzinfo равен self.
            return ZERO
        assert when.tzinfo is self
        start, end = us_dst_range(when.year)
        # Нельзя сравнивать наивные и осведомлённые объекты, поэтому сначала удалите часовой пояс из
        # when.
        when = when.replace(tzinfo=None)
        if start + HOUR <= when < end - HOUR:
            # Действует летнее время.
            return HOUR
        if end - HOUR <= when < end:
            # Fold (неоднозначный час): используйте when.fold для разрешения неоднозначности.
            return ZERO if when.fold else HOUR
        if start <= when < start + HOUR:
            # Gap (несуществующий час): примените обратное правило fold.
            return HOUR if when.fold else ZERO
        # Летнее время не действует.
        return ZERO

    def fromutc(self, when):
        assert when.tzinfo is self
        start, end = us_dst_range(when.year)
        start = start.replace(tzinfo=self)
        end = end.replace(tzinfo=self)
        std_time = when + self.stdoffset
        dst_time = std_time + HOUR
        if end <= dst_time < end + HOUR:
            # Повторяющийся час
            return std_time.replace(fold=1)
        if std_time < start or dst_time >= end:
            # Стандартное время
            return std_time
        if start <= std_time < end - HOUR:
            # Летнее время
            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")