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.

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

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

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

В дополнение к перечисленным выше операциям, объекты 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

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

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

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. Это не совсем эквивалентно date1 + (-timedelta), потому что -timedelta в отдельности может переполниться в случаях, когда date1 - timedelta не переполняется. 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 соответственно.

Даты могут использоваться в качестве ключей словарей. Во всех контекстах boolean все объекты date рассматриваются как истинные.

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

date.replace(year, month, 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.'

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)

Аргументы год, месяц и день обязательны. 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

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

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

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() ошибке.

classmethod datetime.utcfromtimestamp(timestamp)

Возвращает datetime UTC, соответствующий временной метке 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)

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

classmethod datetime.strptime(date_string, format)

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

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

datetime.min

Самый ранний представимый объект datetime, datetime(MINYEAR, 1, 1, tzinfo=None).

datetime.max

Самый поздний представимый объект datetime, datetime(MAXYEAR, 12, 31, 23, 59, 59, 999999, tzinfo=None).

datetime.resolution

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

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

datetime.year

От MINYEAR до MAXYEAR включительно.

datetime.month

От 1 до 12 включительно.

datetime.day

От 1 до количества дней в заданном месяце заданного года.

datetime.hour

В range(24).

datetime.minute

В range(60).

datetime.second

В range(60).

datetime.microsecond

В range(1000000).

datetime.tzinfo

Объект, переданный в качестве аргумента tzinfo конструктору datetime, или None если он не был передан.

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

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, и корректировка часовых поясов не выполняется даже если входной объект осознан. Это не совсем эквивалентно datetime1 + (-timedelta), потому что -timedelta в изоляции может переполниться в случаях, когда datetime1 - timedelta не переполняется.

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 с теми же часами, минутами, секундами и микросекундами. tzinfo — None. См. также метод timetz().

datetime.timetz()

Возвращает объект time с теми же атрибутами hour, minute, second, microsecond и tzinfo. См. также метод time().

datetime.replace([year[, month[, day[, hour[, minute[, second[, microsecond[, tzinfo]]]]]]]])

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

datetime.astimezone(tz=None)

Возвращает объект datetime с новым атрибутом tzinfo tz, корректируя данные даты и времени таким образом, чтобы результат представлял то же время в UTC, что и self, но в локальном времени tz.

Если указан, tz должен быть экземпляром подкласса tzinfo, и его методы utcoffset() и dst() не должны возвращать None. self должен быть с часовым поясом (self.tzinfo не должен быть None, а self.utcoffset() не должен возвращать None).

Если вызов происходит без аргументов (или с 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(). Обсуждение класса tzinfo объясняет случаи на границах перехода летнего времени, когда этого нельзя добиться (проблема только если tz моделирует как стандартное, так и летнее время).

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

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.

Если 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.

Примечание

Нет метода для получения временной метки 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')

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

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     # doctest: +ELLIPSIS
datetime.datetime(2006, 6, 14, 14, 0, tzinfo=<GMT2 object at 0x...>)
>>> dt2     # doctest: +ELLIPSIS
datetime.datetime(2006, 6, 14, 13, 0, tzinfo=<GMT1 object at 0x...>)
>>> dt2.utctimetuple() == dt3.utctimetuple()
True

5. Объекты time

Объект time представляет (местное) время суток, независимо от конкретного дня и может быть скорректирован с помощью объекта tzinfo.

class datetime.time(hour=0, minute=0, second=0, microsecond=0, tzinfo=None)

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

• 0 <= hour < 24
• 0 <= minute < 60
• 0 <= second < 60
• 0 <= microsecond < 1000000.

Если задан аргумент вне этих диапазонов, генерируется 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 с 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[, minute[, second[, microsecond[, tzinfo]]]]])

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

time.isoformat()

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

time.__str__()

Для объекта time 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                               # doctest: +ELLIPSIS
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.'

6. Объекты 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 в минутах к востоку от 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() вызывает свой атрибут tzinfo’s метод 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.

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() заключается в корректировке данных даты и времени, возвращая эквивалентное значение datetime в местном времени 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

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

# A UTC class.

class UTC(tzinfo):
    """UTC"""

    def utcoffset(self, dt):
        return ZERO

    def tzname(self, dt):
        return "UTC"

    def dst(self, dt):
        return ZERO

utc = UTC()

# A class building tzinfo objects for fixed-offset time zones.
# Note that FixedOffset(0, "UTC") is a different way to build a
# UTC tzinfo object.

class FixedOffset(tzinfo):
    """Fixed offset in minutes east from UTC."""

    def __init__(self, offset, name):
        self.__offset = timedelta(minutes=offset)
        self.__name = name

    def utcoffset(self, dt):
        return self.__offset

    def tzname(self, dt):
        return self.__name

    def dst(self, dt):
        return ZERO

# A class capturing the platform's idea of local time.

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 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; 1am standard time) on the first Sunday of Nov.
DSTEND_2007 = datetime(1, 11, 1, 1)
# 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; 1am standard 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, 1)
# 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;
# 1am standard 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

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

        # Find start and end times for US DST. For years before 1967, return
        # ZERO for no DST.
        if 2006 < dt.year:
            dststart, dstend = DSTSTART_2007, DSTEND_2007
        elif 1986 < dt.year < 2007:
            dststart, dstend = DSTSTART_1987_2006, DSTEND_1987_2006
        elif 1966 < dt.year < 1987:
            dststart, dstend = DSTSTART_1967_1986, DSTEND_1967_1986
        else:
            return ZERO

        start = first_sunday_on_or_after(dststart.replace(year=dt.year))
        end = first_sunday_on_or_after(dstend.replace(year=dt.year))

        # Can't compare naive to aware objects, so strip the timezone from
        # dt first.
        if start <= dt.replace(tzinfo=None) < end:
            return HOUR
        else:
            return ZERO

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. Чтобы astimezone() гарантировало это, метод tzinfo.dst() должен рассматривать времена в «пропущенном часу» (2:MM для Восточного) как относящиеся к летнему времени.

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

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

7. Объекты timezone

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

class datetime.timezone(offset[, name])

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

Аргумент name является необязательным. Если указан, он должен быть строкой, которая используется в качестве значения, возвращаемого методом tzname(dt). В противном случае, метод tzname(dt) возвращает строку ‘UTCsHH:MM’, где s — знак offset, HH и MM — две цифры соответственно offset.hours и offset.minutes.

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

timezone.utcoffset(dt)

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

timezone.tzname(dt)

Возвращает фиксированное значение, указанное при создании экземпляра timezone, или строку ‘UTCsHH:MM’, где s — знак смещения, HH и MM — двузначные числа, представляющие соответственно offset.hours и offset.minutes.

timezone.dst(dt)

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

timezone.fromutc(dt)

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

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

timezone.utc

Временная зона UTC, timezone(timedelta(0)).

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])).

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

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

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

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

Примечания:

1. Поскольку формат зависит от текущей локали, следует с осторожностью делать предположения о значении вывода. Порядок полей будет разным (например, «месяц/день/год» против «день/месяц/год»), а вывод может содержать символы Unicode, закодированные с помощью кодировки по умолчанию локали (например, если текущая локаль — 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 используются только в расчетах, когда указаны день недели и год.

Примечания