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

Осознанные и наивные объекты¶

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

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

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

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

Только один конкретный класс tzinfo, класс timezone, поставляется модулем datetime. Класс 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

Следующий пример иллюстрирует, как любые аргументы, кроме 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)

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

Если нормализованное значение дней лежит вне указанного диапазона, то повышается значение OverflowError.

Обратите внимание, что нормализация отрицательных значений может поначалу удивить. Например:

>>> from datetime import timedelta
>>> d = timedelta(microseconds=-1)
>>> (d.days, d.seconds, d.microseconds)
(-1, 86399, 999999)

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

timedelta.min¶

Самый негативный объект timedelta, timedelta(-999999999).

timedelta.max¶

Самый позитивный объект timedelta, timedelta(days=999999999, hours=23, minutes=59, seconds=59, microseconds=999999).

timedelta.resolution¶

Наименьшая возможная разница между неравными timedelta объектами, timedelta(microseconds=1).

Обратите внимание, что из-за нормализации timedelta.max > -timedelta.min. -timedelta.max не может быть представлен как объект timedelta.

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

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

Примечания:

1. Это точное значение, но возможно переполнение.

2. Это точный показатель, который не может переполниться.

3. Деление на 0 приводит к появлению ZeroDivisionError.

4. -timedelta.max не может быть представлен как объект timedelta.

5. Строковые представления объектов timedelta нормализуются аналогично их внутреннему представлению. Это приводит к несколько необычным результатам для отрицательных таймдельта. Например:

   >>> timedelta(hours=-5)
   datetime.timedelta(days=-1, seconds=68400)
   >>> print(_)
   -1 day, 19:00:00
   

6. Выражение t2 - t3 всегда будет равно выражению t2 + (-t3), за исключением случая, когда t3 равно timedelta.max; в этом случае первое выражение даст результат, а второе переполнится.

Помимо перечисленных выше операций, объекты timedelta поддерживают определенные сложения и вычитания с объектами date и datetime (см. ниже).

Сравнение объектов timedelta поддерживается, с некоторыми оговорками.

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

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

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

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

В булевых контекстах объект timedelta считается истинным тогда и только тогда, когда он не равен timedelta(0).

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

timedelta.total_seconds()¶

Возвращает общее количество секунд, содержащихся в длительности. Эквивалентно td / timedelta(seconds=1). Для единиц измерения интервала, отличных от секунд, используйте непосредственно форму деления (например, td / timedelta(microseconds=1)).

Обратите внимание, что для очень больших временных интервалов (более 270 лет на большинстве платформ) этот метод будет терять микросекундную точность.

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

>>> # Components of another_year add up to exactly 365 days
>>> from datetime import timedelta
>>> year = timedelta(days=365)
>>> another_year = timedelta(weeks=40, days=84, hours=23,
...                          minutes=50, seconds=600)
>>> year == another_year
True
>>> year.total_seconds()
31536000.0

>>> from datetime import timedelta
>>> year = timedelta(days=365)
>>> ten_years = 10 * year
>>> ten_years
datetime.timedelta(days=3650)
>>> ten_years.days // 365
10
>>> nine_years = ten_years - year
>>> nine_years
datetime.timedelta(days=3285)
>>> three_years = nine_years // 3
>>> three_years, three_years.days // 365
(datetime.timedelta(days=1095), 3)

date Объекты¶

Объект date представляет дату (год, месяц и день) в идеализированном календаре, текущем григорианском календаре, бесконечно расширенном в обоих направлениях.

1 января года 1 называется днем номер 1, 2 января года 1 называется днем номер 2, и так далее. 2

class datetime.date(year, month, day)¶

Все аргументы являются обязательными. Аргументы должны быть целыми числами в следующих диапазонах:

• MINYEAR <= year <= MAXYEAR

• 1 <= month <= 12

• 1 <= day <= number of days in the given month and year

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

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

classmethod date.today()¶

Возвращает текущую местную дату.

Это эквивалентно date.fromtimestamp(time.time()).

classmethod date.fromtimestamp(timestamp)¶

Возвращает локальную дату, соответствующую временной метке POSIX, такую, как возвращает time.time().

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

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

classmethod date.fromordinal(ordinal)¶

Возвращает дату, соответствующую пролептическому григорианскому ординалу, где 1 января года 1 имеет ординал 1.

ValueError поднимается, если только 1 <= ordinal <= date.max.toordinal(). Для любой даты d, date.fromordinal(d.toordinal()) == d.

classmethod date.fromisoformat(date_string)¶

Возвращает date, соответствующий дате_строки, заданной в формате 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¶

Наименьшая возможная разница между неравными объектами даты, 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, и дата2 + timedelta == дата1 после.

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

Возвращает объект named tuple с тремя компонентами: year, week и weekday.

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

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

Например, 2004 год начинается в четверг, поэтому первая неделя 2004 года ISO начинается в понедельник, 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: Результат изменился с кортежа на named tuple.

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 в formatted string literals и при использовании str.format(). Полный список директив форматирования приведен в разделе strftime() и strptime() Поведение.

>>> import time
>>> from datetime import date
>>> today = date.today()
>>> today
datetime.date(2007, 12, 5)
>>> today == date.fromtimestamp(time.time())
True
>>> my_birthday = date(today.year, 6, 24)
>>> if my_birthday < today:
...     my_birthday = my_birthday.replace(year=today.year + 1)
>>> my_birthday
datetime.date(2008, 6, 24)
>>> time_to_birthday = abs(my_birthday - today)
>>> time_to_birthday.days
202

>>> from datetime import date
>>> d = date.fromordinal(730920) # 730920th day after 1. 1. 0001
>>> d
datetime.date(2002, 3, 11)

>>> # Methods related to formatting string output
>>> d.isoformat()
'2002-03-11'
>>> d.strftime("%d/%m/%y")
'11/03/02'
>>> d.strftime("%A %d. %B %Y")
'Monday 11. March 2002'
>>> d.ctime()
'Mon Mar 11 00:00:00 2002'
>>> 'The {1} is {0:%d}, the {2} is {0:%B}.'.format(d, "day", "month")
'The day is 11, the month is March.'

>>> # Methods for to extracting 'components' under different calendars
>>> t = d.timetuple()
>>> for i in t:     
...     print(i)
2002                # year
3                   # month
11                  # day
0
0
0
0                   # weekday (0 = Monday)
70                  # 70th day in the year
-1
>>> ic = d.isocalendar()
>>> for i in ic:    
...     print(i)
2002                # ISO year
11                  # ISO week number
1                   # ISO day number ( 1 = Monday )

>>> # A date object is immutable; all operations produce a new object
>>> d.replace(year=2005)
datetime.date(2005, 3, 11)

datetime Объекты¶

Объект datetime - это один объект, содержащий всю информацию из объекта date и объекта time.

Как объект date, datetime предполагает, что текущий григорианский календарь распространяется в обе стороны; как объект time, datetime предполагает, что в каждом дне ровно 3600*24 секунды.

Конструктор:

class datetime.datetime(year, month, day, hour=0, minute=0, second=0, microsecond=0, tzinfo=None, *, fold=0)¶

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

• MINYEAR <= year <= MAXYEAR,

• 1 <= month <= 12,

• 1 <= day <= number of days in the given month and year,

• 0 <= hour < 24,

• 0 <= minute < 60,

• 0 <= second < 60,

• 0 <= microsecond < 1000000,

• fold in [0, 1].

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

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

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

classmethod datetime.today()¶

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

Эквивалент:

datetime.fromtimestamp(time.time())

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

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

classmethod datetime.now(tz=None)¶

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

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

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

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

classmethod datetime.utcnow()¶

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

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

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

Поскольку наивные объекты datetime рассматриваются многими методами datetime как местное время, предпочтительнее использовать aware datetimes для представления времени в 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 как местное время, предпочтительнее использовать aware datetimes для представления времени в 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). Если дата является объектом datetime, ее компоненты времени и атрибуты tzinfo игнорируются.

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

classmethod datetime.fromisoformat(date_string)¶

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

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

classmethod datetime.strptime(date_string, format)¶

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

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

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

Если строка даты_ и формат не могут быть разобраны командой ValueError или если возвращается значение, не являющееся кортежем времени, то возникает ошибка 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 - это длительность временной дельты, удаленной от datetime1, двигаясь вперед во времени, если timedelta.days > 0, или назад, если timedelta.days < 0. Результат имеет тот же атрибут tzinfo, что и входной datetime, и datetime2 - datetime1 == временная дельта после. Если datetime2.year будет меньше OverflowError или больше MINYEAR, то возникает ошибка MAXYEAR. Обратите внимание, что корректировка часового пояса не выполняется, даже если входной информацией является объект aware.

2. Вычисляет datetime2 так, что datetime2 + timedelta == datetime1. Что касается сложения, результат имеет тот же атрибут tzinfo, что и входной datetime, и никакие корректировки часового пояса не выполняются, даже если входные данные известны.

3. Вычитание datetime из datetime определяется только в том случае, если оба операнда наивные, или если оба осведомлены. Если один из них осознан, а другой наивен, то возникает TypeError.

   Если оба наивны, или оба осведомлены и имеют одинаковые атрибуты tzinfo, атрибуты tzinfo игнорируются, и результатом является объект timedelta t такой, что datetime2 + t == datetime1. В этом случае корректировка часового пояса не производится.

   Если оба известны и имеют разные атрибуты tzinfo, a-b действует так, как если бы a и b сначала были преобразованы в наивные даты UTC. В результате получается (a.replace(tzinfo=None) - a.utcoffset()) - (b.replace(tzinfo=None) - b.utcoffset()), за исключением того, что реализация никогда не переполняется.

4. datetime1 считается меньше, чем datetime2, если datetime1 предшествует datetime2 по времени.

   Если один компаранд наивный, а другой - осведомленный, то при попытке сравнения по порядку выдается сообщение TypeError. При сравнении на равенство наивные экземпляры никогда не равны осведомленным экземплярам.

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

   Изменено в версии 3.3: Сравнение равенства между осознанными и наивными экземплярами datetime не приводит к появлению TypeError.

   Примечание

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

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

datetime.date()¶

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

datetime.time()¶

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

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

datetime.timetz()¶

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

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

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

Возвращает datetime с теми же атрибутами, за исключением тех атрибутов, которые получили новые значения в зависимости от того, какие аргументы ключевых слов указаны. Обратите внимание, что tzinfo=None может быть указано для создания наивного времени даты из известного времени даты без преобразования данных даты и времени.

Добавлено в версии 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). Если вы просто хотите удалить объект часового пояса из известного времени dt без преобразования данных даты и времени, используйте dt.replace(tzinfo=None).

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

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

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

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

datetime.utcoffset()¶

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

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

datetime.dst()¶

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

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

datetime.tzname()¶

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

datetime.timetuple()¶

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

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

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

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

datetime.utctimetuple()¶

Если datetime экземпляр d наивен, это то же самое, что и d.timetuple(), за исключением того, что tm_isdst принудительно принимает значение 0 независимо от того, что возвращает d.dst(). DST никогда не действует для времени UTC.

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

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

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

datetime.toordinal()¶

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

datetime.timestamp()¶

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

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

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

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

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

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

Примечание

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

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

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

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

datetime.weekday()¶

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

datetime.isoweekday()¶

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

datetime.isocalendar()¶

Возвращает named tuple с тремя компонентами: 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 в formatted string literals и при использовании 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 Объекты¶

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

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

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


class USTimeZone(tzinfo):

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

    def __repr__(self):
        return self.reprname

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

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

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

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


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

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

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

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

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

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

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

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

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

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

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

timezone Объекты¶

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

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

class datetime.timezone(offset, name=None)¶

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

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

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

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

timezone.utcoffset(dt)¶

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

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

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

timezone.tzname(dt)¶

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

Если в конструкторе не указано name, то имя, возвращаемое tzname(dt), формируется из значения offset следующим образом. Если offset равно timedelta(0), то имя будет «UTC», иначе это строка в формате UTC±HH:MM, где ± - знак offset, HH и MM - две цифры offset.hours и offset.minutes соответственно.

Изменено в версии 3.6: Имя, сгенерированное из offset=timedelta(0), теперь является простым „UTC“, а не 'UTC+00:00'.

timezone.dst(dt)¶

Всегда возвращает None.

timezone.fromutc(dt)¶

Возвращает dt + offset. Аргумент dt должен быть известным экземпляром datetime, с tzinfo, установленным в self.

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

timezone.utc¶

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

strftime() и strptime() Поведение¶

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

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

В таблице ниже представлено высокоуровневое сравнение strftime() и strptime():