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

Исходный код: Lib/datetime.py

Модуль datetime предоставляет классы для работы с датами и временем как простыми, так и сложными способами. Хотя поддерживаются арифметические операции с датами и временем, основное внимание уделяется эффективному извлечению атрибутов для форматирования и обработки вывода. Для смежных функций см. также модули time и calendar.

Существует два типа объектов дат и времени: «наивные» и «осознанные».

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

Наивный объект не содержит достаточной информации, чтобы однозначно определить своё положение относительно других объектов даты/времени. Представляет ли наивный объект координированное универсальное время (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.

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

Объекты типа date всегда наивные.

Объект типа time или datetime может быть наивным или осознанным. Объект datetime d является осознанным, если d.tzinfo не None и d.tzinfo.utcoffset(d) не возвращает None. Если d.tzinfo равно None, или если d.tzinfo не равно None, но d.tzinfo.utcoffset(d) возвращает None, d является наивным. Объект time t является осознанным, если t.tzinfo не None и t.tzinfo.utcoffset(None) не возвращает None. В противном случае t является наивным.

Различие между наивным и осознанным не применяется к объектам timedelta.

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

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

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

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

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

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

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

timedelta.min

Наименьший отрицательный объект timedelta, timedelta(-999999999).

timedelta.max

Наибольший положительный объект timedelta, timedelta(days=999999999, hours=23, minutes=59, seconds=59, microseconds=999999).

timedelta.resolution

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

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

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

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

Примечания:

1. Это точно, но может привести к переполнению.
2. Это точно и не может привести к переполнению.
3. Деление на 0 вызывает ZeroDivisionError.
4. -timedelta.max не может быть представлен как объект timedelta.

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

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

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

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

Сравнения объектов timedelta поддерживаются с объектом timedelta, представляющим меньшую продолжительность, считающуюся меньшим timedelta. Для предотвращения падения сравнений смешанных типов на стандартное сравнение по адресу объекта, при сравнении объекта timedelta с объектом другого типа, возбуждается TypeError, если сравнение не является == или !=. В последних случаях возвращаются False или True соответственно.

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

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

timedelta.total_seconds()

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

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

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

Пример использования:

>>> from datetime import timedelta
>>> year = timedelta(days=365)
>>> another_year = timedelta(weeks=40, days=84, hours=23,
...                          minutes=50, seconds=600)  # adds up to 365 days
>>> year.total_seconds()
31536000.0
>>> year == another_year
True
>>> ten_years = 10 * year
>>> ten_years, ten_years.days // 365
(datetime.timedelta(days=3650), 10)
>>> nine_years = ten_years - year
>>> nine_years, nine_years.days // 365
(datetime.timedelta(days=3285), 9)
>>> three_years = nine_years // 3
>>> three_years, three_years.days // 365
(datetime.timedelta(days=1095), 3)
>>> abs(three_years - ten_years) == 2 * three_years + year
True

Объекты date

Объект date представляет дату (год, месяц и день) в идеализированном календаре, текущем григорианском календаре, бесконечно продолженном в обоих направлениях. 1 января года 1 называется днём номер 1, 2 января года 1 называется днём номер 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 в формате, выводимом функцией date.isoformat(). В частности, эта функция поддерживает строки в формате(ах) YYYY-MM-DD.

Внимание

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

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

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

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)

Возвращает дату со значением, совпадающим со значениями всех параметров, за исключением тех, для которых заданы новые значения в ключевых аргументах. Например, если d == date(2002, 12, 31), то d.replace(day=26) == 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 — широко используемая разновидность григорианского календаря. См. https://www.staff.science.uu.nl/~gent0113/calendar/isocalendar.htm для лучшего объяснения.

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

Например, 2004 год начинается в четверг, поэтому первая неделя года ISO 2004 начинается в понедельник, 29 декабря 2003 года, и заканчивается в воскресенье, 4 января 2004 года, так что date(2003, 12, 29).isocalendar() == (2004, 1, 1) и date(2004, 1, 4).isocalendar() == (2004, 1, 7).

date.isoformat()

Возвращает строку, представляющую дату в формате ISO 8601, 'ГГГГ-ММ-ДД'. Например, date(2002, 12, 4).isoformat() == '2002-12-04'.

date.__str__()

Для даты d, str(d) эквивалентно d.isoformat().

date.ctime()

Возвращает строку, представляющую дату, например, 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

Пример работы с date:

>>> from datetime import date
>>> d = date.fromordinal(730920) # 730920th day after 1. 1. 0001
>>> d
datetime.date(2002, 3, 11)
>>> 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 )
>>> d.isoformat()
'2002-03-11'
>>> d.strftime("%d/%m/%y")
'11/03/02'
>>> d.strftime("%A %d. %B %Y")
'Monday 11. March 2002'
>>> 'The {1} is {0:%d}, the {2} is {0:%B}.'.format(d, "day", "month")
'The day is 11, the month is March.'

Объекты datetime

Объект datetime — это единый объект, содержащий всю информацию из объекта date и объекта time. Как и объект date, datetime предполагает текущий григорианский календарь, расширенный в обоих направлениях; как и объект времени, 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.

New in version 3.6: Добавлен аргумент fold.

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

classmethod datetime.today()

Возвращает текущее локальное значение datetime с tzinfo None. Это эквивалентно datetime.fromtimestamp(time.time()). См. также now(), fromtimestamp().

classmethod datetime.now(tz=None)

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

Если tz не None, он должен быть экземпляром подкласса tzinfo, и текущая дата и время преобразуются в часовой пояс tz. В этом случае результат эквивалентен tz.fromutc(datetime.utcnow().replace(tzinfo=tz)). См. также today(), utcnow().

classmethod datetime.utcnow()

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

classmethod datetime.fromtimestamp(timestamp, tz=None)

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

Если tz не None, он должен быть экземпляром подкласса tzinfo, и метка времени преобразуется в часовой пояс tz. В этом случае результат эквивалентен tz.fromutc(datetime.utcfromtimestamp(timestamp).replace(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 включительно.

Изменено в версии 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.

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

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 могут использоваться в качестве ключей словарей. Во всех контекстах с Boolean значениями все объекты datetime считаются истинными.

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

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 летнее время никогда не действует.

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

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

Возвращает кортеж из 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.

Если utcoffset() не возвращает None, добавляется строка, указывающая смещение относительно UTC: YYYY-MM-DDTHH:MM:SS.ffffff+HH:MM[:SS[.ffffff]] или, если microsecond равно 0, YYYY-MM-DDTHH:MM:SS+HH:MM[:SS[.ffffff]].

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

>>> from datetime import tzinfo, timedelta, datetime
>>> class TZ(tzinfo):
...     def utcoffset(self, dt): return timedelta(minutes=-399)
...
>>> datetime(2002, 12, 25, tzinfo=TZ()).isoformat(' ')
'2002-12-25 00:00:00-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()

Возвращает строку, представляющую дату и время, например 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().

Примеры работы с объектами datetime:

>>> from datetime import datetime, date, time
>>> # 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() or datetime.utcnow()
>>> datetime.now()   
datetime.datetime(2007, 12, 6, 16, 29, 43, 79043)   # GMT +1
>>> datetime.utcnow()   
datetime.datetime(2007, 12, 6, 15, 29, 43, 79060)
>>> # 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 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.'

Использование datetime с tzinfo:

>>> 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):
...             # 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):
...         # 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
...
...         # 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")
...
...         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):
...         return timedelta(0)
...
...     def tzname(self, dt):
...         if dt >= self.UTC_MOVE_DATE:
...             return "+04:30"
...         else:
...             return "+04"
...
...     def  __repr__(self):
...         return f"{self.__class__.__name__}()"
...
>>> 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.utctimetuple() == dt3.utctimetuple()
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, где a считается меньше b, когда a предшествует b во времени. Если один сравниваемый элемент является неявным, а другой — осознанным, возникает TypeError при попытке сравнения. Для сравнения на равенство неявные экземпляры никогда не равны осознанным экземплярам.

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

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

• хеширование, использование в качестве ключа словаря
• эффективное сохранение в двоичном формате

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

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

classmethod time.fromisoformat(time_string)

Возвращает time, соответствующий time_string в одном из форматов, выдаваемых time.isoformat(). Конкретно, эта функция поддерживает строки в формате(ах) HH[:MM[:SS[.fff[fff]]]][+HH:MM[:SS[.ffffff]]].

Внимание

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

Добавлено в версии 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. Если utcoffset() не возвращает None, к строке добавляется смещение от UTC: HH:MM:SS.ffffff+HH:MM[:SS[.ffffff]] или, если self.microsecond равно 0, HH:MM:SS+HH:MM[:SS[.ffffff]].

Необязательный аргумент 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, необходимых для методов datetime, которые вы используете. Модуль datetime предоставляет простой конкретный подкласс tzinfo, timezone, который может представлять часовые пояса с фиксированным смещением от UTC, например, сам UTC или североамериканские EST и EDT.

Экземпляр (конкретного подкласса) tzinfo может быть передан в конструкторы объектов datetime и time. Последние объекты рассматривают свои атрибуты как находящиеся в местном времени, и объект tzinfo поддерживает методы, раскрывающие смещение местного времени от UTC, имя часового пояса и смещение DST, все относительно объекта даты или времени, переданного им.

Особое требование для сериализации: подкласс 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.  Then

    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 начинается (строка «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

Когда Летнее Время заканчивается (строка «конец»), возникает потенциально более серьезная проблема: есть час, который нельзя однозначно указать в локальном времени: последний час летнего времени. В Восточной зоне это время в формате 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), для создания строки, представляющей время под управлением явного формата строки. В общем случае, d.strftime(fmt) действует подобно методу time.strftime(fmt, d.timetuple()) модуля time, хотя не все объекты поддерживают метод timetuple().

Обратно, метод класса datetime.strptime() создает объект datetime из строки, представляющей дату и время, и соответствующей строки формата. datetime.strptime(date_string, format) эквивалентно datetime(*(time.strptime(date_string, format)[0:6])), за исключением случаев, когда формат включает компоненты с дробной частью секунды или смещение часового пояса, которые поддерживаются в datetime.strptime, но отбрасываются time.strptime.

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

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

Для метода класса datetime.strptime() значение по умолчанию — 1900-01-01T00:00:00.000: любые компоненты, не указанные в строке формата, будут взяты из значения по умолчанию. 2

Полный набор поддерживаемых кодов формата зависит от платформы, потому что Python вызывает функцию платформенной библиотеки C strftime(), и платформенные различия распространены. Чтобы увидеть полный набор кодов формата, поддерживаемых на вашей платформе, обратитесь к документации strftime(3).

По той же причине обработка строк формата, содержащих символы Юникода, которые нельзя представить в кодировке текущего языка, также зависит от платформы. На некоторых платформах такие символы сохраняются неизменными в выводе, а на других strftime может вызвать UnicodeError или вернуть пустую строку вместо этого.

Ниже приведен список всех кодов формата, которые требуются стандартом C (версия 1989 года), и они работают на всех платформах с стандартной реализацией C. Обратите внимание, что версия стандарта C 1999 года добавила дополнительные коды формата.

Для удобства включены несколько дополнительных директив, не требуемых стандартом C89. Эти параметры соответствуют значениям даты ISO 8601. Они могут быть недоступны на всех платформах при использовании метода strftime(). Директивы года ISO 8601 и недели ISO 8601 не взаимозаменяемы с вышеперечисленными директивами года и номера недели. Вызов strptime() с неполными или неоднозначными директивами ISO 8601 приведет к исключению ValueError.

Примечания:

1. Поскольку формат зависит от текущей локали, необходимо быть внимательным при предположениях о значении вывода. Порядок полей будет отличаться (например, "месяц/день/год" против "день/месяц/год"), а вывод может содержать символы Юникода, закодированные с помощью кодировки по умолчанию локали (например, если текущая локали — ja_JP, кодировка по умолчанию может быть любой из eucJP, SJIS, или utf-8; используйте locale.getlocale() для определения кодировки текущей локали).

2. Метод strptime() может анализировать годы в полном диапазоне [1, 9999], но годы < 1000 должны быть дополнены нулями до 4 цифр.

   Изменено в версии 3.2: В предыдущих версиях метод strftime() был ограничен годами >= 1900.

   Изменено в версии 3.3: В версии 3.2 метод strftime() был ограничен годами >= 1000.

3. При использовании с методом strptime(), директива %p влияет только на поле часа вывода, если директива %I используется для анализа часа.
4. В отличие от модуля time, модуль datetime не поддерживает високосных секунд.
5. При использовании с методом strptime(), директива %f принимает от одного до шести цифр и заполняет нулями справа. %f является расширением набора символов форматирования в стандарте C (но реализовано отдельно в объектах datetime, и поэтому всегда доступно).

6. Для неявного объекта форматы %z и %Z заменяются на пустые строки.

   Для явного объекта:

   %z

   utcoffset() преобразуется в строку формата ±HHMM[SS[.ffffff]], где HH — строка из 2 цифр, задающая количество часов смещения от UTC, MM — строка из 2 цифр, задающая количество минут смещения от UTC, SS — строка из 2 цифр, задающая количество секунд смещения от UTC, а ffffff — строка из 6 цифр, задающая количество микросекунд смещения от UTC. Часть ffffff опускается, если смещение является целым числом секунд, а обе части ffffff и SS опускаются, если смещение является целым числом минут. Например, если utcoffset() возвращает timedelta(hours=-3, minutes=-30), %z заменяется строкой '-0330'.

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

   Изменено в версии 3.7: Когда директива %z предоставляется методу strptime(), смещения от UTC могут иметь двоеточие в качестве разделителя между часами, минутами и секундами. Например, '+01:00:00' будет анализироваться как смещение на один час. Кроме того, предоставление 'Z' идентично '+00:00'.

   %Z

   Если tzname() возвращает None, %Z заменяется на пустую строку. В противном случае %Z заменяется возвращаемым значением, которое должно быть строкой.

   Изменено в версии 3.2: Когда директива %z предоставляется методу strptime(), будет создан явный объект datetime. Поле tzinfo результата будет установлено на экземпляр timezone.

7. При использовании с методом strptime(), %U и %W используются только в расчетах, когда указан день недели и календарный год (%Y).
8. Подобно %U и %W, %V используется только в расчетах, когда в строке формата strptime() указан день недели и год ISO (%G). Также обратите внимание, что %G и %Y не взаимозаменяемы.
9. При использовании с методом strptime(), ведущий ноль является необязательным для форматов %d, %m, %H, %I, %M, %S, %J, %U, %W, и %V. Для формата %y ведущий ноль требуется.

Примечания

1

Если, конечно, мы игнорируем эффекты Относительности

2

Передача datetime.strptime('Feb 29', '%b %d') завершится неудачей, так как 1900 не является високосным годом.