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.

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

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 нормализуются аналогично их внутреннему представлению. Это приводит к несколько необычным результатам для отрицательных timedeltas. Например:

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

Возвращает текущее локальное время datetime, с 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, разобранной по формату format.

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

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 с тем же часом, минутой, секундой, микросекундой и значением 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.год был MINYEAR или MAXYEAR, и корректировка UTC перетекает через границу года.

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

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

datetime.toordinal()

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

datetime.timestamp()

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

Неявные экземпляры 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 своего атрибута 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
# https://sourceforge.net/projects/pytz/ (might not be up-to-date)
#
# In the US, since 2007, DST starts at 2am (standard time) on the second
# Sunday in March, which is the first Sunday on or after Mar 8.
DSTSTART_2007 = datetime(1, 3, 8, 2)
# and ends at 2am (DST time) on the first Sunday of Nov.
DSTEND_2007 = datetime(1, 11, 1, 2)
# From 1987 to 2006, DST used to start at 2am (standard time) on the first
# Sunday in April and to end at 2am (DST time) on the last
# Sunday of October, which is the first Sunday on or after Oct 25.
DSTSTART_1987_2006 = datetime(1, 4, 1, 2)
DSTEND_1987_2006 = datetime(1, 10, 25, 2)
# From 1967 to 1986, DST used to start at 2am (standard time) on the last
# Sunday in April (the one on or after April 24) and to end at 2am (DST time)
# on the last Sunday of October, which is the first Sunday
# on or after Oct 25.
DSTSTART_1967_1986 = datetime(1, 4, 24, 2)
DSTEND_1967_1986 = DSTEND_1987_2006

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

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


class USTimeZone(tzinfo):

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

    def __repr__(self):
        return self.reprname

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

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

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

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


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

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

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

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

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

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