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.

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

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

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

class datetime.tzinfo

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

class datetime.timezone

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

Введено в версии 3.2.

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

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

object
    timedelta
    tzinfo
        timezone
    time
    date
        datetime

Объекты timedelta

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

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. Деление на 0 вызывает ZeroDivisionError.
4. -timedelta.max не может быть представлен как объект timedelta.

5. Строковые представления объектов 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 поддерживаются с некоторыми оговорками.

Сравнения == или != всегда возвращают bool, независимо от типа сравниваемого объекта:

>>> from datetime import timedelta
>>> delta1 = timedelta(seconds=57)
>>> delta2 = timedelta(hours=25, seconds=2)
>>> delta2 != delta1
True
>>> delta2 == 5
False

Для всех других сравнений (таких как < и >), когда объект timedelta сравнивается с объектом другого типа, возникает TypeError:

>>> delta2 > delta1
True
>>> delta2 > 5
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: '>' not supported between instances of 'datetime.timedelta' and 'int'

В контекстах булевых значений объект 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, за исключением порядковых дат (например, YYYY-DDD):

>>> 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. Другими словами, date1 < date2 тогда и только тогда, когда date1.toordinal() < date2.toordinal(). Сравнение дат вызывает TypeError, если другой операнд не является также объектом date. Однако, вместо этого возвращается NotImplemented, если у другого операнда есть атрибут timetuple(). Этот крючок дает другим типам объектов дат возможность реализовать сравнение смешанных типов. Если нет, при сравнении объекта date с объектом другого типа, генерируется TypeError, за исключением случаев сравнения == или !=. В последних случаях возвращаются False или True соответственно.

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

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

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

classmethod datetime.fromordinal(ordinal)

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

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

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

Для любого объекта datetime d, d == datetime.combine(d.date(), d.time(), d.tzinfo). Если date — объект datetime, его компоненты времени и атрибуты tzinfo игнорируются.

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

classmethod datetime.fromisoformat(date_string)

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

1. Смещения часовых поясов могут иметь дробные секунды.
2. Разделитель T может быть заменён любым одиночным символом Юникода.
3. Порядковые даты в настоящее время не поддерживаются.
4. Дробные часы и минуты не поддерживаются.

Примеры:

>>> 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 заполняются своими стандартными значениями по умолчанию. Это обратная функция 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. datetime1 считается меньше datetime2, когда datetime1 предшествует datetime2 во времени.

   Если один из сравниваемых объектов является наивным, а другой — осознающим часовой пояс, генерируется TypeError, если попытка сравнения по порядку. Для сравнения на равенство наивные экземпляры никогда не равны осознающим часовой пояс.

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

   Изменено в версии 3.3: Сравнения на равенство осознающих и наивных экземпляров datetime больше не вызывают TypeError.

   Примечание

   Для предотвращения возвращения к умолчанию по умолчанию сравнения по адресам объектов, сравнение datetime обычно вызывает TypeError, если другой сравниваемый объект не является также объектом datetime. Однако, NotImplemented возвращается вместо этого, если у другого сравниваемого объекта есть атрибут timetuple(). Этот хук позволяет другим видам объектов дат реализовывать сравнение смешанных типов. Если нет, когда объект datetime сравнивается с объектом другого типа, TypeError генерируется, если сравнение не является == или !=. В последнем случае возвращается False или True соответственно.

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

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

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

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

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

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

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

datetime.utcoffset()

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

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

datetime.dst()

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

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

datetime.tzname()

Если tzinfo есть None, возвращает None, иначе возвращает self.tzinfo.tzname(self), генерирует исключение, если последнее не возвращает None или строковый объект.

datetime.timetuple()

Возвращает time.struct_time, такой как возвращается методом time.localtime().

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

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

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

datetime.utctimetuple()

Если экземпляр datetime d неявный, это то же самое, что d.timetuple(), за исключением того, что tm_isdst принудительно установлено в 0 независимо от того, что возвращает d.dst(). 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 для очень далёких во времени значений.

Для осознанных экземпляров 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, к строке добавляется смещение от UTC:

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

Примеры:

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

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

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

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

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

Примечание

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

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

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

Новое в версии 3.6: Добавлен аргумент timespec.

datetime.__str__()

Для объекта datetime d, str(d) эквивалентно d.isoformat(' ').

datetime.ctime()

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

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

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

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

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

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

datetime.strftime(format)

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

datetime.__format__(format)

То же самое, что и datetime.strftime(). Это позволяет указать строку формата для объекта datetime в строках формата и при использовании 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 поддерживают сравнение time с time, где a считается меньше b, когда a предшествует b во времени. Если один из операндов не учитывает часовой пояс, а другой учитывает, при попытке сравнения по порядку будет поднято исключение TypeError. При сравнении на равенство неявные объекты никогда не равны объектам, учитывающим часовой пояс.

Если оба операнда учитывают часовой пояс и имеют одинаковый атрибут tzinfo, общий атрибут tzinfo игнорируется, и сравниваются базовые времена. Если оба операнда учитывают часовой пояс и имеют разные атрибуты tzinfo, операнды сначала корректируются путем вычитания их смещений UTC (полученных из self.utcoffset()). Чтобы предотвратить сравнение смешанных типов, возвращающихся к сравнению по адресу объекта, когда объект time сравнивается с объектом другого типа, будет поднято исключение TypeError, за исключением случаев сравнения по типу, возвращающего False или True.

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

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

classmethod time.fromisoformat(time_string)

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

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

Примеры:

.. doctest::

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

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

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

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

tzinfo.utcoffset(dt)

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

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

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

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

По умолчанию реализация utcoffset() вызывает NotImplementedError.

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

tzinfo.dst(dt)

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

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

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

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

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

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

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

или:

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

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

По умолчанию реализация dst() вызывает NotImplementedError.

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

tzinfo.tzname(dt)

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

По умолчанию реализация tzname() вызывает NotImplementedError.

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

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

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

Есть еще один метод tzinfo, который подкласс может переопределить:

tzinfo.fromutc(dt)

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

Большинство подклассов tzinfo должны иметь возможность унаследовать реализацию метода fromutc() по умолчанию без проблем. Она достаточно надежна для обработки часовых поясов с фиксированным смещением, часовых поясов, учитывающих стандартное и летнее время, и последнего, даже если времена перехода к летнему времени отличаются в разные годы. Примером часового пояса, который реализация метода 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 начинается (строка «начало»), местные часы перескакивают с 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 заканчивается (строка «конец»), возникает потенциально более серьезная проблема: есть час, который нельзя однозначно выразить в местном времени: последний час летнего времени. В часовом поясе Восточного побережья это моменты вида 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'