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

Объекты с и без информации о часовом поясе

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

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

Объект без информации о часовом поясе не содержит достаточной информации для однозначного определения своего положения относительно других объектов дат/времени. Представляет ли объект без информации о часовом поясе время по координированному всемирному времени (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.

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

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

класс datetime.date

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

класс datetime.time

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

класс datetime.datetime

Сочетание даты и времени. Атрибуты: year, month, day, hour, minute, second, microsecond и tzinfo.

класс datetime.timedelta

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

класс datetime.tzinfo

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

класс datetime.timezone

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

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

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

Взаимосвязи между подклассами:

object
    timedelta
    tzinfo
        timezone
    time
    date
        datetime

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

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

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

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

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

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

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

Примечания:

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.

>>> # 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

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

Изменено в версии 3.3: Вызывается OverflowError вместо ValueError, если временная метка выходит за пределы диапазона значений, поддерживаемых платформенной функцией C localtime(). Вызывается 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, соответствующую строке date_string в любом допустимом формате ISO 8601, с следующими исключениями:

1. Даты с уменьшенной точностью в настоящее время не поддерживаются (YYYY-MM, YYYY).
2. Расширенные представления дат в настоящее время не поддерживаются (±YYYYYY-MM-DD).
3. Порядковые даты в настоящее время не поддерживаются (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)

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

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

classmethod date.fromisocalendar(year, week, day)

Возвращает date, соответствующую дате ISO-календаря, указанной годом, неделей и днём. Это обратная функция date.isocalendar().

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

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

date.min

Самая ранняя представимая дата, date(MINYEAR, 1, 1).

date.max

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

date.resolution

Наименьшее возможное различие между неравными объектами date, 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 равны, если они представляют одну и ту же дату.
5. date1 считается меньше date2, когда date1 предшествует date2 во времени. Другими словами, date1 < date2 тогда и только тогда, когда date1.toordinal() < date2.toordinal().

В контексте булевых значений все объекты 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.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 года:

>>> 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: Результат изменён с кортежа на именованный кортеж.

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

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

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

Аргументы 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().

classmethod datetime.utcnow()

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

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

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

Поскольку объекты datetime без учета часового пояса многими методами datetime интерпретируются как локальное время, рекомендуется использовать даты и время с учетом часового пояса для представления времени в UTC. В связи с этим, рекомендуемый способ создания объекта, представляющего текущее время в 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.

classmethod datetime.utcfromtimestamp(timestamp)

Возвращает UTC datetime, соответствующий 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 без временной зоны многими методами рассматриваются как местное время, рекомендуется использовать даты со временной зоной для представления времени в формате UTC. В связи с этим рекомендуемый способ создания объекта, представляющего определённую метку времени в UTC, — это вызов datetime.fromtimestamp(timestamp, tz=timezone.utc).

Изменено в версии 3.3: Исключение OverflowError вместо ValueError при выходе метки времени за пределы диапазона значений, поддерживаемого платформенной функцией C gmtime(). Исключение 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, соответствующий date_string в любом допустимом формате ISO 8601, с перечисленными ниже исключениями:

1. Смещения временной зоны могут содержать дробные секунды.
2. Разделитель T может быть заменён любым одиночным символом Юникода.
3. Дробные часы и минуты не поддерживаются.
4. Даты с уменьшенной точностью в настоящее время не поддерживаются (YYYY-MM, YYYY).
5. Расширенные представления дат в настоящее время не поддерживаются (±YYYYYY-MM-DD).
6. Порядковые даты в настоящее время не поддерживаются (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)))

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

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

classmethod datetime.fromisocalendar(year, week, day)

Возвращает datetime, соответствующий дате ISO-календаря, указанной годом, неделей и днём. Не являющиеся датой компоненты даты заполняются стандартными значениями по умолчанию. Это обратное к функции 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().

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

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 были сначала преобразованы в простые даты и время UTC. Результат — (a.replace(tzinfo=None) - a.utcoffset()) - (b.replace(tzinfo=None) - b.utcoffset()) за исключением того, что реализация никогда не переполняется.

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

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

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

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

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

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

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

datetime.date()

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

datetime.time()

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

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

datetime.timetz()

Возвращает объект time с тем же часом, минутой, секундой, микросекундой, значением 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 без преобразования данных даты и времени.

Изменено в версии 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
    # Convert self to UTC, and attach the new timezone 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(). 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 timestamp, соответствующее экземпляру datetime. Возвращаемое значение — float, подобное возвращаемому time.time().

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

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

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

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

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

Примечание

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

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

или вычислив 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()

Возвращает кортеж с именованными полями с тремя компонентами: 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, добавляется строка, указывающая смещение по Гринвичу:

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

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

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"

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

Примеры:

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

Добавлен в версии 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 без преобразования данных времени.

Изменено в версии 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 в форматированных строковых литералах и при использовании 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 или объект типа строка.

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

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

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

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

tzinfo.utcoffset(dt)

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

Это представляет общее смещение от UTC; например, если объект tzinfo представляет как часовую зону, так и корректировки по летнему времени, 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 , если информация о летнем времени неизвестна.

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

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() по умолчанию действует так:

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, учитывающем как стандартное, так и летнее время, неизбежны тонкости дважды в год, в моменты перехода к летнему времени. Для конкретности рассмотрим часовой пояс Восточного времени США (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 начинается (строка «start»), местные часы перескакивают с 1:59 на 3:00. Временная метка вида 2:MM в этот день не имеет смысла, поэтому astimezone(Eastern) не выдаст результат с hour == 2 в день начала DST. Например, во время весеннего перехода 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 часа)).

Объекты timezone

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

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

class datetime.timezone(offset, name=None)

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

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

Добавлен в версии 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 должен быть осознанным экземпляром datetime с tzinfo установленным на self.

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

timezone.utc

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

strftime() и strptime() поведение

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

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

Ниже приведена сравнительная таблица 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'