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

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

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

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

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

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

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

Модуль datetime экспортирует следующие константы:

datetime.MINYEAR

Наименьшее значение года, разрешенное в объектах date или datetime. MINYEAR равно 1.

datetime.MAXYEAR

Наибольшее значение года, разрешенное в объектах date или datetime. MAXYEAR равно 9999.

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

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

8.1.2. Объекты 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(-1, 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).

Обратите внимание, что для очень больших промежутков времени (более 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(3650), 10)
>>> nine_years = ten_years - year
>>> nine_years, nine_years.days // 365
(datetime.timedelta(3285), 9)
>>> three_years = nine_years // 3;
>>> three_years, three_years.days // 365
(datetime.timedelta(1095), 3)
>>> abs(three_years - ten_years) == 2 * three_years + year
True

8.1.3. Объекты date

Объект date представляет дату (год, месяц и день) в идеализированном календаре, текущем григорианском календаре, бесконечно продолженном в обоих направлениях. 1 января года 1 называется днем 1, 2 января года 1 называется днем 2 и так далее. Это соответствует определению «пролептического григорианского» календаря в книге Dershowitz и Reingold «Расчеты календарей», где это базовый календарь для всех вычислений. См. книгу для алгоритмов преобразования между пролептическими григорианскими порядковыми номерами и многими другими календарными системами.

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.

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

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, а 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, 'YYYY-MM-DD'. Например, 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.'

8.1.4. Объекты 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)

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

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

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

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

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

classmethod datetime.today()

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

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. Сознательное текущее время 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.strptime(date_string, format)

Возвращает datetime, соответствующий date_string, разобранный в соответствии с format. Это эквивалентно 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 — это продолжительность 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 могут использоваться в качестве ключей словарей. В контексте булевых выражений все объекты 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, представляющий целое число минут с величиной меньше одного дня.

datetime.dst()

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

datetime.tzname()

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

datetime.timetuple()

Возвращает time.struct_time, такой как возвращается методом time.localtime(). d.timetuple() эквивалентно time.struct_time((d.year, d.month, d.day, d.hour, d.minute, d.second, d.weekday(), yday, dst)), где yday = d.toordinal() - date(d.year, 1, 1).toordinal() + 1 — номер дня в текущем году, начиная с 1 для 1 января. Флаг tm_isdst результата устанавливается в соответствии с методом dst(): если tzinfo равно None или метод dst() возвращает None, то tm_isdst устанавливается в -1; в противном случае, если dst() возвращает ненулевое значение, tm_isdst устанавливается в 1; иначе tm_isdst устанавливается в 0.

datetime.utctimetuple()

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

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

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

Возвращает тройку (год ISO, номер недели ISO, день недели ISO). То же самое, что и self.date().isocalendar().

datetime.isoformat(sep='T', timespec='auto')

Возвращает строку, представляющую дату и время в формате ISO 8601, YYYY-MM-DDTHH:MM:SS.mmmmmm или, если microsecond равно 0, YYYY-MM-DDTHH:MM:SS

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

Необязательный аргумент 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.mmmmmm.

Примечание

Исключенные компоненты времени усекаются, а не округляются.

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
>>> class GMT1(tzinfo):
...     def utcoffset(self, dt):
...         return timedelta(hours=1) + self.dst(dt)
...     def dst(self, dt):
...         # DST starts last Sunday in March
...         d = datetime(dt.year, 4, 1)   # ends last Sunday in October
...         self.dston = d - timedelta(days=d.weekday() + 1)
...         d = datetime(dt.year, 11, 1)
...         self.dstoff = d - timedelta(days=d.weekday() + 1)
...         if self.dston <=  dt.replace(tzinfo=None) < self.dstoff:
...             return timedelta(hours=1)
...         else:
...             return timedelta(0)
...     def tzname(self,dt):
...          return "GMT +1"
...
>>> class GMT2(tzinfo):
...     def utcoffset(self, dt):
...         return timedelta(hours=2) + self.dst(dt)
...     def dst(self, dt):
...         d = datetime(dt.year, 4, 1)
...         self.dston = d - timedelta(days=d.weekday() + 1)
...         d = datetime(dt.year, 11, 1)
...         self.dstoff = d - timedelta(days=d.weekday() + 1)
...         if self.dston <=  dt.replace(tzinfo=None) < self.dstoff:
...             return timedelta(hours=1)
...         else:
...             return timedelta(0)
...     def tzname(self,dt):
...         return "GMT +2"
...
>>> gmt1 = GMT1()
>>> # Daylight Saving Time
>>> dt1 = datetime(2006, 11, 21, 16, 30, tzinfo=gmt1)
>>> dt1.dst()
datetime.timedelta(0)
>>> dt1.utcoffset()
datetime.timedelta(0, 3600)
>>> dt2 = datetime(2006, 6, 14, 13, 0, tzinfo=gmt1)
>>> dt2.dst()
datetime.timedelta(0, 3600)
>>> dt2.utcoffset()
datetime.timedelta(0, 7200)
>>> # Convert datetime to another time zone
>>> dt3 = dt2.astimezone(GMT2())
>>> dt3     
datetime.datetime(2006, 6, 14, 14, 0, tzinfo=<GMT2 object at 0x...>)
>>> dt2     
datetime.datetime(2006, 6, 14, 13, 0, tzinfo=<GMT1 object at 0x...>)
>>> dt2.utctimetuple() == dt3.utctimetuple()
True

8.1.5. Объекты 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.

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

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

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

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.mmmmmm или, если microsecond равно 0, HH:MM:SS. Если utcoffset() не возвращает None, добавляется строка длиной 6 символов, представляющая смещение от UTC в часах и минутах со знаком: HH:MM:SS.mmmmmm+HH:MM или, если self.microsecond равно 0, HH:MM:SS+HH:MM.

Необязательный аргумент 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.mmmmmm.

Примечание

Исключённые компоненты времени усекаются, а не округляются.

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, представляющий целое число минут с величиной меньше одного дня.

time.dst()

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

time.tzname()

Если tzinfo равно None, возвращает None, иначе возвращает self.tzinfo.tzname(None), или генерирует исключение, если последнее не возвращает None или объект строки.

Пример:

>>> from datetime import time, tzinfo, timedelta
>>> class GMT1(tzinfo):
...     def utcoffset(self, dt):
...         return timedelta(hours=1)
...     def dst(self, dt):
...         return timedelta(0)
...     def tzname(self,dt):
...         return "Europe/Prague"
...
>>> t = time(12, 10, 30, tzinfo=GMT1())
>>> t                               
datetime.time(12, 10, 30, tzinfo=<GMT1 object at 0x...>)
>>> gmt = GMT1()
>>> t.isoformat()
'12:10:30+01:00'
>>> t.dst()
datetime.timedelta(0)
>>> t.tzname()
'Europe/Prague'
>>> t.strftime("%H:%M:%S %Z")
'12:10:30 Europe/Prague'
>>> 'The {} is {:%H:%M}.'.format("time", t)
'The time is 12:10.'

8.1.6. Объекты tzinfo

class datetime.tzinfo

Это абстрактный базовый класс, что означает, что этот класс не должен создаваться напрямую. Вам нужно создать конкретный подкласс и (по крайней мере) предоставить реализации стандартных методов tzinfo, необходимых методам datetime, которые вы используете. Модуль datetime предоставляет простой конкретный подкласс tzinfo, timezone, который может представлять часовые пояса с фиксированным смещением от UTC, например, UTC сам по себе или североамериканские EST и EDT.

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

Особое требование для сериализации: Подкласс tzinfo должен иметь метод __init__(), который может вызываться без аргументов, иначе он может быть сериализован, но возможно, не будет десериализован повторно. Это техническое требование, которое может быть ослаблено в будущем.

Конкретный подкласс tzinfo может потребовать реализации следующих методов. Точно какие методы необходимы, зависит от использования объектов aware datetime. В случае сомнений, просто реализуйте их все.

tzinfo.utcoffset(dt)

Возвращает смещение местного времени от UTC в минутах к востоку от UTC. Если местное время западнее UTC, это должно быть отрицательным. Обратите внимание, что это предназначено для того, чтобы быть общим смещением от UTC; например, если объект tzinfo представляет и часовой пояс, и корректировки DST, utcoffset() должен вернуть их сумму. Если смещение от UTC неизвестно, возвращает None. Иначе возвращаемое значение должно быть объектом timedelta, указывающим на целое число минут в диапазоне от -1439 до 1439 включительно (1440 = 24*60; величина смещения должна быть меньше одного дня). Большинство реализаций utcoffset() будут, вероятно, выглядеть так:

return CONSTANT                 # fixed-offset class
return CONSTANT + self.dst(dt)  # daylight-aware class

Если utcoffset() не возвращает None, dst() также не должно возвращать None.

По умолчанию реализация utcoffset() вызывает NotImplementedError.

tzinfo.dst(dt)

Возвращает корректировку летнего времени (DST) в минутах к востоку от UTC или None , если информация о DST неизвестна. Возвращает timedelta(0) , если DST не активен. Если DST активен, возвращает смещение в виде объекта timedelta (см. utcoffset() для подробностей). Обратите внимание, что смещение DST, если применимо, уже добавлено к смещению UTC, возвращаемому utcoffset(), поэтому нет необходимости обращаться к dst(), если вас интересует только информация о DST. Например, datetime.timetuple() вызывает метод dst() своего атрибута tzinfo для определения того, как должен быть установлен флаг 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.

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:

from datetime import tzinfo, timedelta, datetime, timezone

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

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

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

DSTDIFF = DSTOFFSET - STDOFFSET

class LocalTimezone(tzinfo):

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

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

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

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

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

Local = LocalTimezone()


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

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


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

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

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


class USTimeZone(tzinfo):

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

    def __repr__(self):
        return self.reprname

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

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

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

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


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

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

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

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

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

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

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

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

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

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

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

8.1.7. Объекты 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.

timezone.utcoffset(dt)

Возвращает фиксированное значение, указанное при создании экземпляра timezone. Аргумент dt игнорируется. Возвращаемое значение — экземпляр timedelta, равный разнице между местным временем и 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)).

8.1.8. 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 коды формата для года, месяца и дня не должны использоваться, так как у объектов time таких значений нет. Если они всё же используются, то 1900 подставляется для года, а 1 для месяца и дня.

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

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

Ниже приведён список всех кодов формата, которые требуются стандартом 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() преобразуется в строку длиной 5 символов в формате +HHMM или -HHMM, где HH — двузначная строка, указывающая количество часов смещения от UTC, а MM — двузначная строка, указывающая количество минут смещения от UTC. Например, если utcoffset() возвращает timedelta(hours=-3, minutes=-30), %z заменяется строкой '-0330'.

   %Z

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

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

7. При использовании с методом strptime(), %U и %W используются только в расчётах, когда указан день недели и год (%Y).
8. Аналогично %U и %W, %V используется только в расчётах, когда день недели и год ISO (%G) указаны в строке формата strptime(). Также обратите внимание, что %G и %Y не взаимозаменяемы.

Примечания

1

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