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

Объекты Aware и Naive

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

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

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

Для приложений, требующих aware объектов, 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.

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

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. Аргументы могут быть целыми или дробными числами, положительными или отрицательными.

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

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

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

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

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

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

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

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

   >>> 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, заданной в формате YYYY-MM-DD:

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

Это обратное преобразование к date.isoformat(). Поддерживается только формат YYYY-MM-DD.

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

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

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

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

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

Аргументы год, месяц и день обязательны. 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 в одном из форматов, выдаваемых date.isoformat() и datetime.isoformat().

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

YYYY-MM-DD[*HH[:MM[:SS[.fff[fff]]]][+HH:MM[:SS[.ffffff]]]]

где * может соответствовать любому символу.

Внимание

Это не поддерживает разбор произвольных строк ISO 8601 — она предназначена только для обратной операции datetime.isoformat(). Более полнофункциональный парсер ISO 8601, dateutil.parser.isoparse доступен в пакете сторонних разработчиков dateutil.

Примеры:

>>> from datetime import datetime
>>> datetime.fromisoformat('2011-11-04')
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-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.

classmethod datetime.fromisocalendar(year, week, day)

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

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

classmethod datetime.strptime(date_string, format)

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

Это эквивалентно:

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

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

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

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 с тем же часом, минутой, секундой, микросекундой и флагом. tzinfo — None. См. также метод timetz().

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

datetime.timetz()

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

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

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

Возвращает datetime с теми же атрибутами, за исключением тех, для которых заданы новые значения с помощью переданных ключевых аргументов. Обратите внимание, что tzinfo=None может быть указан для создания «неявного» datetime из «явного» 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(). Для времени UTC летнее время никогда не действует.

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

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

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

datetime.toordinal()

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

datetime.timestamp()

Возвращает метку времени POSIX, соответствующую экземпляру 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 непосредственно из неявного экземпляра datetime, представляющего время UTC. Если ваше приложение использует эту конвенцию, и часовой пояс вашей системы не установлен на UTC, вы можете получить метку времени POSIX, передав tzinfo=timezone.utc:

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

или вычислив метку времени непосредственно:

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

datetime.weekday()

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

datetime.isoweekday()

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

datetime.isocalendar()

Возвращает кортеж с тремя компонентами: 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.__format__(format)

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

>>> 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 в одном из форматов, выведенных функцией time.isoformat(). В частности, эта функция поддерживает строки в формате:

HH[:MM[:SS[.fff[fff]]]][+HH:MM[:SS[.ffffff]]]

Внимание

Эта функция не поддерживает разбор произвольных строк ISO 8601. Она предназначена только для обратной операции функции time.isoformat().

Примеры:

>>> from datetime import time
>>> time.fromisoformat('04:23:01')
datetime.time(4, 23, 1)
>>> 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)))

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

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

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

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

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’s метод 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() без проблем. Она достаточно универсальна для обработки часовых поясов с фиксированным смещением, а также часовых поясов, учитывающих стандартное и летнее время, и даже если времена перехода DST отличаются в разные годы. Примером часового пояса, который реализация по умолчанию метода fromutc() может не обработать корректно во всех случаях, является такой, где стандартное смещение (от UTC) зависит от конкретной даты и времени, что может произойти по политическим причинам. Реализации по умолчанию методов astimezone() и fromutc() могут не дать желаемого результата, если результат относится к часам, которые пересекают момент изменения стандартного смещения.

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

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

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

from datetime import tzinfo, timedelta, datetime

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

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

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

DSTDIFF = DSTOFFSET - STDOFFSET

class LocalTimezone(tzinfo):

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

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

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

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

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

Local = LocalTimezone()


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

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


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

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

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


class USTimeZone(tzinfo):

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

    def __repr__(self):
        return self.reprname

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

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

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

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


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

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

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

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

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

Когда DST начинается (строка «начало»), местные часы перескакивают с 1:59 до 3:00. Время в формате 2: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():