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

Внутренне хранятся только 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()

Возвращает кортеж из 3 элементов, (год ISO, номер недели ISO, день недели ISO).

ISO-календарь — широко используемая разновидность григорианского календаря. 3

Год ISO состоит из 52 или 53 полных недель, при этом неделя начинается с понедельника и заканчивается с воскресенья. Первая неделя года ISO — первая (григорианская) неделя года, содержащая четверг. Это неделя номер 1, и год ISO этого четверга такой же, как его григорианский год.

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

>>> from datetime import date
>>> date(2003, 12, 29).isocalendar()
(2004, 1, 1)
>>> date(2004, 1, 4).isocalendar()
(2004, 1, 7)

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)

Аргументы year, month и day являются обязательными. tzinfo может быть None, или экземпляром подкласса tzinfo. Остальные аргументы должны быть целыми числами в следующих диапазонах:

• MINYEAR <= year <= MAXYEAR,
• 1 <= month <= 12,
• 1 <= day <= number of days in the given month and year,
• 0 <= hour < 24,
• 0 <= minute < 60,
• 0 <= second < 60,
• 0 <= microsecond < 1000000,
• fold in [0, 1].

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

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

Другие конструкторы, все методы класса:

classmethod datetime.today()

Возвращает текущее локальное время с tzinfo None.

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

datetime.fromtimestamp(time.time())

См. также now(), fromtimestamp().

Этот метод функционально эквивалентен now(), но без параметра tz.

classmethod datetime.now(tz=None)

Возвращает текущую локальную дату и время.

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

Если tz не None, он должен быть экземпляром подкласса tzinfo, и текущая дата и время преобразуются в часовой пояс tz.

Эта функция предпочтительнее today() и utcnow().

classmethod datetime.utcnow()

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

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

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

Поскольку простые объекты datetime обрабатываются многими методами datetime как местное время, предпочтительно использовать объекты с часовым поясом для представления времени в UTC. Таким образом, рекомендуемый способ создания объекта, представляющего текущее время в UTC, — это вызов datetime.now(timezone.utc).

classmethod datetime.fromtimestamp(timestamp, tz=None)

Возвращает локальную дату и время, соответствующие метке времени POSIX, например, возвращаемой функцией time.time(). Если необязательный аргумент tz равен None или не указан, метка времени преобразуется в локальную дату и время платформы, и возвращаемый объект datetime является простым.

Если tz не None, он должен быть экземпляром подкласса tzinfo, и метка времени преобразуется в часовой пояс tz.

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

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

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

classmethod datetime.utcfromtimestamp(timestamp)

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

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

Для получения объекта datetime с часовым поясом, вызовите fromtimestamp():

datetime.fromtimestamp(timestamp, timezone.utc)

На POSIX-совместимых платформах это эквивалентно следующему выражению:

datetime(1970, 1, 1, tzinfo=timezone.utc) + timedelta(seconds=timestamp)

за исключением того, что последняя формула всегда поддерживает весь диапазон лет: от MINYEAR до MAXYEAR включительно.

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

Поскольку простые объекты datetime обрабатываются многими методами datetime как местное время, предпочтительно использовать объекты с часовым поясом для представления времени в UTC. Таким образом, рекомендуемый способ создания объекта, представляющего конкретную метку времени в UTC, — это вызов datetime.fromtimestamp(timestamp, tz=timezone.utc).

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

classmethod datetime.fromordinal(ordinal)

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

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

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

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

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

classmethod datetime.fromisoformat(date_string)

Возвращает datetime, соответствующий date_string в одном из форматов, выдаваемых 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 и format не могут быть обработаны 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(). Для времени UTC смещение DST никогда не используется.

Если 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 timestamp, соответствующее экземпляру datetime. Возвращаемое значение — float, подобное возвращаемому time.time().

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

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

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

Новое в версии 3.3.

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

Примечание

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

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

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

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

datetime.weekday()

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

datetime.isoweekday()

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

datetime.isocalendar()

Возвращает кортеж из 3 элементов (год ISO, номер недели ISO, день недели ISO). То же, что и 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() по умолчанию. Она достаточно надёжна для работы с часовыми поясами с фиксированным смещением, а также с часовыми поясами, учитывающими как стандартное, так и летнее время, и даже если моменты перехода к летнему времени отличаются в разные годы. Примером часового пояса, который реализация метода 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, учитывающем и стандартное, и летнее время, неизбежны тонкости дважды в год в моменты перехода к летнему времени. Для ясности рассмотрим часовой пояс Восточного времени США (UTC -0500), где EDT начинается через минуту после 1:59 (EST) во второе воскресенье марта и заканчивается через минуту после 1:59 (EDT) в первое воскресенье ноября:

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

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

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

Когда DST начинается (строка «start»), локальные часы мгновенно перескакивают с 1:59 на 3:00. Время 2:MM в таком формате не имеет смысла в этот день, поэтому astimezone(Eastern) не вернёт результат с hour == 2 в день начала DST. Например, при переходе на летнее время в 2016 году получаем:

>>> from datetime import datetime, timezone
>>> from tzinfo_examples import HOUR, Eastern
>>> u0 = datetime(2016, 3, 13, 5, tzinfo=timezone.utc)
>>> for i in range(4):
...     u = u0 + i*HOUR
...     t = u.astimezone(Eastern)
...     print(u.time(), 'UTC =', t.time(), t.tzname())
...
05:00:00 UTC = 00:00:00 EST
06:00:00 UTC = 01:00:00 EST
07:00:00 UTC = 03:00:00 EDT
08:00:00 UTC = 04:00:00 EDT

Когда DST заканчивается (строка «end»), возникает потенциально более серьёзная проблема: есть час, который не может быть однозначно выражен в локальном времени: последний час летнего времени. В Восточном часовом поясе это время вида 5:MM UTC в день окончания летнего времени. Локальные часы мгновенно перескакивают с 1:59 (летнее время) обратно на 1:00 (стандартное время). Локальные времена вида 1:MM являются неоднозначными. astimezone() имитирует поведение локальных часов, сопоставляя два смежных часа UTC одному локальному часу. В примере с Восточным часовым поясом UTC-времена вида 5:MM и 6:MM оба отображаются как 1:MM при преобразовании в Восточное время, но для более ранних времён атрибут fold установлен в 0, а для более поздних — в 1. Например, при переходе на зимнее время в 2016 году получаем:

>>> u0 = datetime(2016, 11, 6, 4, tzinfo=timezone.utc)
>>> for i in range(4):
...     u = u0 + i*HOUR
...     t = u.astimezone(Eastern)
...     print(u.time(), 'UTC =', t.time(), t.tzname(), t.fold)
...
04:00:00 UTC = 00:00:00 EDT 0
05:00:00 UTC = 01:00:00 EDT 0
06:00:00 UTC = 01:00:00 EST 1
07:00:00 UTC = 02:00:00 EST 0

Обратите внимание, что экземпляры datetime, отличающиеся только значением атрибута fold, считаются равными при сравнении.

Приложения, которые не могут работать с неоднозначностями во времени, должны явно проверять значение атрибута fold или избегать использования гибридных подклассов tzinfo; неоднозначностей нет при использовании timezone или любого другого подкласса tzinfo с фиксированным смещением (например, класса, представляющего только EST (фиксированное смещение -5 часов) или только EDT (фиксированное смещение -4 часа)).

Объекты timezone

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

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

class datetime.timezone(offset, name=None)

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

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

Новая в версии 3.2.

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

timezone.utcoffset(dt)

Возвращает фиксированное значение, заданное при создании экземпляра timezone.

Аргумент dt игнорируется. Возвращаемое значение — экземпляр timedelta, равный разнице между местным временем и UTC.

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

timezone.tzname(dt)

Возвращает фиксированное значение, заданное при создании экземпляра timezone.

Если имя не указано в конструкторе, имя, возвращаемое tzname(dt), генерируется из значения 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():