8.1. datetime – Основные типы даты и времени¶datetime – Basic date and time types

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

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 всегда naive.

Объект типа 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 Objects

Объект timedelta представляет собой продолжительность, то есть разницу между двумя датами или моментами времени.

class datetime.timedelta(days=0, seconds=0, microseconds=0, milliseconds=0, minutes=0, hours=0, weeks=0)¶

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

Внутри хранятся только days, seconds и microseconds. Аргументы преобразуются в эти единицы:

• Миллисекунда преобразуется в 1000 микросекунд.
• Минута преобразуется в 60 секунд.
• Час преобразуется в 3600 секунд.
• Неделя преобразуется в 7 дней.

а затем дни, секунды и микросекунды нормализуются так, что представление уникально, с

• 0 <= microseconds < 1000000
• 0 <= seconds < 3600*24 (количество секунд в одном дне)
• -999999999 <= days <= 999999999

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

Если нормализованное значение дней выходит за указанный диапазон, возбуждается 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)  # составляет 365 дней
>>> 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 Objects

Объект 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, если метка времени выходит за пределы диапазона значений, поддерживаемого функцией localtime() платформы C. Вызывает 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. Это не совсем эквивалентно 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.

Даты можно использовать в качестве ключей словаря. В логическом контексте все объекты 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()¶

Возвращает кортеж из трёх элементов: (год по 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)¶

Возвращает строку, представляющую дату, задаваемую явной строкой формата. Коды формата, относящиеся к часам, минутам или секундам, будут иметь нулевые значения. Полный список директив форматирования см. в поведении strftime() и strptime().

date.__format__(format)¶

То же, что и date.strftime(). Это позволяет указать строку формата для объекта date при использовании str.format(). Полный список директив форматирования приведён в разделе strftime() and strptime() Behavior.

Пример подсчёта дней до события:

>>> 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) # 730920-й день после 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 Objects

Объект datetime – это единый объект, содержащий всю информацию из объекта date и объекта time. Как и объект date, datetime предполагает текущий григорианский календарь, расширенный в обе стороны; как и объект time, datetime предполагает, что в каждом дне ровно 3600*24 секунд.

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

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

Аргументы 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

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

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

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

classmethod datetime.utcfromtimestamp(timestamp)¶

Возвращает UTC datetime, соответствующий временной метке POSIX, с tzinfo None. Это может вызвать OverflowError, если временная метка выходит за пределы диапазона значений, поддерживаемого функцией gmtime() платформы C, и 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, если метка времени выходит за пределы диапазона значений, поддерживаемого функцией gmtime() платформы C. Вызывает 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 и format не могут быть проанализированы time.strptime() или если он возвращает значение, не являющееся кортежем времени. Полный список директив форматирования см. в Поведение strftime() и strptime().

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

datetime.min¶

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

datetime.max¶

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

datetime.resolution¶

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

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

datetime.year¶

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

datetime.month¶

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

datetime.day¶

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

datetime.hour¶

В range(24).

datetime.minute¶

В range(60).

datetime.second¶

В range(60).

datetime.microsecond¶

В range(1000000).

datetime.tzinfo¶

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

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

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, и никаких корректировок часового пояса не производится, даже если исходный объект является aware. Это не совсем эквивалентно 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 с теми же значениями hour, minute, second и microsecond. 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 без преобразования данных даты и времени.

datetime.astimezone(tz=None)¶

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

Если указано, tz должен быть экземпляром подкласса tzinfo, а его методы utcoffset() и dst() не должны возвращать None. self должен быть aware (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
    # Преобразует self в UTC и присоединяет новый объект временной зоны.
    utc = (self - self.utcoffset()).replace(tzinfo=tz)
    # Преобразует из UTC в местное время tz.
    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 является aware, 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() and strptime() Behavior.

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

>>> from datetime import datetime, date, time
>>> # Использование datetime.combine()
>>> d = date(2005, 7, 14)
>>> t = time(12, 30)
>>> datetime.combine(d, t)
datetime.datetime(2005, 7, 14, 12, 30)
>>> # Использование datetime.now() или 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)
>>> # Использование datetime.strptime()
>>> dt = datetime.strptime("21/11/06 16:30", "%d/%m/%y %H:%M")
>>> dt
datetime.datetime(2006, 11, 21, 16, 30)
>>> # Использование datetime.timetuple() для получения кортежа всех атрибутов
>>> 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
>>> # Дата в формате ISO
>>> ic = dt.isocalendar()
>>> for it in ic:   
...     print(it)
...
2006    # ISO year
47      # ISO week
2       # ISO weekday
>>> # Форматирование 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):
...         # Летнее время начинается в последнее воскресенье марта
...         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 +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()
>>> # Летнее время
>>> 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)
>>> # Преобразовать datetime в другой часовой пояс
>>> 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

8.1.5. time Объекты¶time Objects

Объект 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 во времени. Если один сравниваемый объект является naive, а другой aware, вызывается TypeError при попытке упорядочивающего сравнения. При сравнении на равенство наивные экземпляры никогда не равны aware-экземплярам.

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

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

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

• эффективная сериализация (pickling)

В логических контекстах объект 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__()¶

Для времени t, str(t) эквивалентно t.isoformat().

time.strftime(format)¶

Возвращает строку, представляющую время, управляемую явной строкой формата. Полный список директив форматирования см. в strftime() and strptime() Behavior.

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.'

8.1.6. Объекты tzinfo¶tzinfo Objects

class datetime.tzinfo¶

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

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

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

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

tzinfo.utcoffset(dt)¶

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

return CONSTANT                 # класс с фиксированным смещением
return CONSTANT + self.dst(dt)  # класс, учитывающий летнее время

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

Реализация по умолчанию utcoffset() возбуждает NotImplementedError.

tzinfo.dst(dt)¶

Возвращает поправку на летнее время (DST) в минутах к востоку от UTC или None, если информация о DST неизвестна. Возвращает timedelta(0), если летнее время не действует. Если летнее время действует, возвращает смещение в виде объекта 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):
    # класс с фиксированным смещением: не учитывает летнее время
    return timedelta(0)

или

def dst(self, dt):
    # Код для установки dston и dstoff в значения летнего времени часового пояса
    # переходные моменты времени на основе входного dt.year и выраженные
    # в стандартном местном времени.  Затем

    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(). Она достаточно мощная, чтобы обрабатывать часовые пояса с фиксированным смещением, а также пояса, учитывающие как стандартное, так и летнее время, причём последнее – даже если время перехода на летнее время различается в разные годы. Пример часового пояса, который реализация по умолчанию fromutc() может не всегда корректно обрабатывать, – это пояс, где стандартное смещение (от UTC) зависит от конкретной даты и времени, что может происходить по политическим причинам. Реализации по умолчанию astimezone() и fromutc() могут не дать желаемого результата, если результат приходится на часы, охватывающие момент изменения стандартного смещения.

Опуская код для обработки ошибок, реализация по умолчанию fromutc() работает следующим образом:

def fromutc(self, dt):
    # вызывает ошибку ValueError, если dt.tzinfo не равен self
    dtoff = dt.utcoffset()
    dtdst = dt.dst()
    # вызывает ValueError, если dtoff или dtdst равны None
    delta = dtoff - dtdst  # это стандартное смещение self
    if delta:
        dt += delta   # преобразовать в стандартное местное время
        dtdst = dt.dst()
        # вызывает ValueError, если dtdst равен None
    if dtdst:
        return dt + dtdst
    else:
        return dt

Пример классов tzinfo:

from datetime import tzinfo, timedelta, datetime

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

# Класс UTC.

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

    def utcoffset(self, dt):
        return ZERO

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

    def dst(self, dt):
        return ZERO

utc = UTC()

# Класс, создающий объекты tzinfo для часовых поясов с фиксированным смещением.
# Обратите внимание, что FixedOffset(0, "UTC") – это другой способ построения
# Объект tzinfo UTC.

class FixedOffset(tzinfo):
    """Фиксированное смещение в минутах к востоку от 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

# Класс, отражающий представление платформы о местном времени.

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


# Полная реализация текущих правил летнего времени для основных часовых поясов США.

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


# Правила летнего времени в США
#
# Это упрощённый набор правил для США (т.е. неверный для некоторых случаев)
# времени начала и окончания летнего времени. Полный и актуальный набор правил летнего времени
# и определений часовых поясов смотрите в базе данных Olson (или попробуйте pytz):
# http://www.twinsun.com/tz/tz-link.htm
# http://sourceforge.net/projects/pytz/ (возможно, неактуально)
#
# В США с 2007 года летнее время начинается в 2 часа ночи (стандартное время) во второе
# воскресенье марта, то есть первое воскресенье 8 марта или после него.
DSTSTART_2007 = datetime(1, 3, 8, 2)
# и заканчивается в 2 часа ночи (по летнему времени; 1 час ночи по стандартному времени) в первое воскресенье ноября.
DSTEND_2007 = datetime(1, 11, 1, 1)
# С 1987 по 2006 год летнее время начиналось в 2 часа ночи (стандартное время) в первое
# воскресенье в апреле и заканчиваться в 2 часа ночи (по летнему времени; 1 час ночи по стандартному времени) в последнее
# воскресенье октября, то есть первое воскресенье 25 октября или после него.
DSTSTART_1987_2006 = datetime(1, 4, 1, 2)
DSTEND_1987_2006 = datetime(1, 10, 25, 1)
# С 1967 по 1986 год летнее время начиналось в 2 часа ночи (стандартное время) в последнее
# воскресенье апреля (то, которое приходится на 24 апреля или позже) и заканчиваться в 2 часа ночи (по летнему времени;
# 1 час ночи по стандартному времени) в последнее воскресенье октября, которое является первым воскресеньем
# 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:
            # В одном или обоих случаях здесь может быть уместно исключение.
            # Это зависит от того, как вы хотите их обрабатывать. Реализация по умолчанию
            # fromutc() (вызываемая реализацией astimezone() по умолчанию)
            # реализация) передаёт datetime с dt.tzinfo равным self.
            return ZERO
        assert dt.tzinfo is self

        # Найти время начала и окончания перехода на летнее время в США. Для лет до 1967 года вернуть
        # ZERO – если переход на летнее время не применяется.
        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))

        # Нельзя сравнивать наивные и осведомлённые объекты, поэтому сначала удалите часовой пояс из
        # сначала dt.
        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, учитывающем как стандартное, так и летнее время, в точках перехода на летнее время возникают неизбежные тонкости. Для конкретики рассмотрим US Eastern (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

Когда начинается летнее время (строка «start»), местные часы перескакивают с 1:59 на 3:00. Местное время вида 2:MM в этот день не имеет смысла, поэтому astimezone(Eastern) не вернёт результат с hour == 2 в день перехода на летнее время. Чтобы astimezone() мог это гарантировать, метод tzinfo.dst() должен считать моменты «потерянного часа» (2:MM для восточного времени) относящимися к летнему времени.

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

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

8.1.7. Объекты timezone¶timezone Objects

Класс 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 – знак offset, а HH и MM – две цифры offset.hours и offset.minutes соответственно.

timezone.dst(dt)¶

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

timezone.fromutc(dt)¶

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

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

timezone.utc¶

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

8.1.8. Поведение strftime() и strptime()¶strftime() and strptime() Behavior

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

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

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

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

Примечания:

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

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

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

   Изменено в версии 3.3: В версии 3.2 метод strftime() был ограничен gодами >= 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 используются только в вычислениях, когда указаны день недели и год.

Сноски