datetime — Базовые типы для представления даты и времени

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

Модуль datetime предоставляет классы для управления датами и временем.

В то время как поддерживается арифметика даты и времени, основное внимание в реализации уделяется эффективному извлечению атрибутов для форматирования и манипулирования выводом.

См.также

Модуль calendar
Общие календарные функции.
Модуль time
Доступ к времени и преобразования.
Пакет dateutil
Сторонняя библиотека с расширенной поддержкой часовых поясов и парсинга.

Знающие и наивные объекты

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

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

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

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

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

Константы

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

datetime.MINYEAR

Наименьшее допустимое число лет в объекте date или datetime. MINYEAR есть 1.

datetime.MAXYEAR

Наибольшее допустимое число лет в объекте date или datetime. MAXYEAR содержит 9999.

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

class datetime.date

Идеализированная наивная дата, предполагая, что нынешний григорианский календарь всегда был, и всегда будет, по сути. Атрибуты: year, month и day.

class datetime.time

Идеализированное время, независимо от конкретного дня, при условии, что каждый день имеет ровно 24* 60* 60 секунд. (Здесь нет понятия «високосные секунды».) Атрибуты: hour, minute, second, microsecond и tzinfo.

class datetime.datetime

Сочетание даты и времени. Атрибуты: year, month, day, hour, minute, second, microsecond и tzinfo.

class datetime.timedelta

Длительность, выражающая разницу между двумя date, time или datetime сущности с микросекундным разрешением.

class datetime.tzinfo

Абстрактный базовый класс для информационных объектов часового пояса. Он используется datetime и классами time, чтобы обеспечить настраиваемое понятие корректировки времени (например, составлять часового пояса и/или летнее время).

class datetime.timezone

Класс, который осуществляет абстрактный базовый класс tzinfo как фиксированное смещение от UTC.

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

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

Отношения подкласса:

object
    timedelta
    tzinfo
        timezone
    time
    date
        datetime

Общие свойства

Типы date, datetime, time и timezone содержат следующие общие функции:

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

Определение того, является ли объект знающим или наивным

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

Объект типа time или datetime может быть знающим или наивным.

Объект datetime d знающий, если выполняются оба из следующих утверждений:

  1. d.tzinfo не является None
  2. d.tzinfo.utcoffset(d) не возвращает None

Иначе d наивен.

Объект time t знающий, если выполняются оба из следующих утвержений:

  1. t.tzinfo не является None
  2. t.tzinfo.utcoffset(None) не возвращает None.

Иначе t наивен.

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

Объекты timedelta

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

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

>>> from datetime import timedelta
>>> delta = timedelta(
...     days=50,
...     seconds=27,
...     microseconds=10,
...     milliseconds=29000,
...     minutes=5,
...     hours=8,
...     weeks=2
... )
>>> # Остались только дни, секунды и микросекунды
>>> delta
datetime.timedelta(days=64, seconds=29156, microseconds=10)

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

Если нормализованное значение дней находится вне обозначенного диапазона, подимается 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.

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

Атрибут Значение
days От -999999999 до 999999999 включительно
seconds От 0 до 86399 включительно
microseconds От 0 до 999999 включительно

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

Операция Результат
t1 = t2 + t3
Сумма t2 и t3. После этого t1-t2 ==
t3 и t1-t3 == t2 являются true. (1)
t1 = t2 - t3 Разность t2 и t3. После этого t1 == t2 - t3 и t2 == t1 + t3 являются true. (1)(6)
t1 = t2 * i or t1 = i * t2 Дельта, умноженная на целое число. Впоследствии t1 // i == t2 является true, представленное i != 0.
  В общем, t1 * i == t1 * (i-1) + t1 является true. (1)
t1 = t2 * f or t1 = f * t2 Дельта, умноженная на число с плавающей точкой. Результат округляется до ближайшего кратного timedelta.resolution с использованием округления наполовину к четному.
f = t2 / t3 Деление (3) общей длительности t2 на единицу интервала t3. Возвращает объект float.
t1 = t2 / f or t1 = t2 / i Дельта делится на число с float или int. Результат округляется до ближайшего кратного timedelta.resolution с использованием округления от половины до четности.
t1 = t2 // i или t1 = t2 // t3 Целочисленное деление, а остаток (если есть) выбрасывается. Во втором случае возвращается целое число. (3)
t1 = t2 % t3 Остаток рассчитывается как timedelta объект. (3)
q, r = divmod(t1, t2) Вычисляет частное и остальное: q = t1 // t2 (3) и r = t1 % t2. q является целым числом, а r timedelta объект.
+t1 Возвращает timedelta объект с некоторым значением. (2)
-t1 Экавивалент timedelta(-t1.days, -t1.seconds, -t1.microseconds), и t1* -1. (1)(4)
abs(t) Эквивалентно +t при t.days >= 0 и -t когда t.days < 0. (2)
str(t) Возвращает строку в форме [D day[s], ][H]H:MM:SS[.UUUUUU], где D является отрицательным для отрицательных t. (5)
repr(t) Возвращает строковое представление объекта timedelta как требование конструктора с каноническим атрибутом значения.

Примечания:

  1. Это точно, но может быть переполнено.

  2. Это точно и не может быть переполнено.

  3. Деление на 0 поднимает ZeroDivisionError.

  4. -timedelta.max не представляется как объект timedelta.

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

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

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

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

Изменено в версии 3.2: Теперь поддерживается целочисленное деление и истинное деление объекта timedelta другим объектом timedelta, а также операции остатка и функция divmod(). Теперь поддерживается истинное деление и умножение объекта timedelta на объект float.

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

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

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

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

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

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

Методы сущности:

timedelta.total_seconds()

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

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

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

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

Дополнительный пример нормализации:

>>> # Компоненты another_year складываются ровно в 365 дней
>>> from datetime import timedelta
>>> year = timedelta(days=365)
>>> another_year = timedelta(weeks=40, days=84, hours=23,
...                          minutes=50, seconds=600)
>>> year == another_year
True
>>> year.total_seconds()
31536000.0

Примеры timedelta арифметики:

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

Объекты date

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

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

class datetime.date(year, month, day)

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

  • MINYEAR <= year <= MAXYEAR
  • 1 <= month <= 12
  • 1 <= day <= количество дней в данном месяце и году

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

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

classmethod date.today()

Возврат текущей локальной даты.

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

classmethod date.fromtimestamp(timestamp)

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

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

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

classmethod date.fromordinal(ordinal)

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

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

classmethod date.fromisoformat(date_string)

Возвращает date, соответствующий date_string, заданному в формате YYYY-MM-DD:

>>> from datetime import date
>>> date.fromisoformat('2019-12-04')
datetime.date(2019, 12, 4)

Это обратная сторона date.isoformat(). Он поддерживает только формат YYYY-MM-DD.

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

classmethod date.fromisocalendar(year, week, day)

Возвращает date, соответствующий дате календаря ISO, указанной по году, неделе и дню. Это инверсия функции date.isocalendar().

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

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

date.min

Самая ранняя представимая дата, date(MINYEAR, 1, 1).

date.max

Последняя представляемая дата, date(MAXYEAR, 12, 31).

date.resolution

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

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

date.year

Между MINYEAR и MAXYEAR включительно.

date.month

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

date.day

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

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

Операция Результат
date2 = date1 + timedelta date2 - это timedelta.days дней, удаленных от date1. (1)
date2 = date1 - timedelta Вычисляет date2 так, что date2 + timedelta == date1. (2)
timedelta = date1 - date2 (3)
date1 < date2 date1 считается меньше date2, когда date1 предшествует date2 во времени.(4)

Примечания:

  1. date2 перемещается вперед во времени, если timedelta.days > 0, или назад, если timedelta.days < 0. Позже date2 - date1 == timedelta.days. timedelta.seconds и timedelta.microseconds игнорируются. OverflowError поднимается, если date2.year будет меньше MINYEAR или больше MAXYEAR.
  2. timedelta.seconds и timedelta.microseconds игнорируются.
  3. Это точно и не может переполняться. timedelta.seconds и timedelta.microseconds равны 0, а dat2 + timedelta = = date1 после.
  4. Другими словами, date1 < date2 тогда и только тогда, когда date1.toordinal() < date2.toordinal(). Сравнение дат вызывает TypeError, если другое сравнение также не является объектом date. Однако вместо этого возвращается значение NotImplemented, если другое сравнение имеет значение timetuple() атрибут. Этот хук дает возможность другим видам объектов даты реализовать сравнение смешанного типа. Если нет, то при сравнении объекта date с объектом другого типа возникает объект TypeError, если сравнение не является == или !=. Последние случаи возвращают False или True соответственно.

В логических контекстах все объекты date считаются True.

Методы сущности:

date.replace(year=self.year, month=self.month, day=self.day)

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

Пример:

>>> from datetime import date
>>> d = date(2002, 12, 31)
>>> d.replace(day=26)
datetime.date(2002, 12, 26)
date.timetuple()

Возвращает time.struct_time, например, возвращаемый time.localtime().

Часы, минуты и секунды равны 0, а флаг перехода на летнее и зимнее время равен -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 является широко используемый вариантом григорианского календаря. [3]

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

Например, 2004 год начинается в четверг, поэтому первая неделя 2004 года ISO начинается в понедельник, 29 декабря 2003 года, и заканчивается в воскресенье, 4 января 2004 года:

>>> from datetime import date
>>> date(2003, 12, 29).isocalendar()
(2004, 1, 1)
>>> date(2004, 1, 4).isocalendar()
(2004, 1, 7)
date.isoformat()

Возвращает строку, представляющей дату в формате ISO 8601, YYYY-MM-DD:

>>> from datetime import date
>>> date(2002, 12, 4).isoformat()
'2002-12-04'

Это обратная сторона date.fromisoformat().

date.__str__()

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

date.ctime()

Возвращает строку, представляющую дату:

>>> from datetime import date
>>> date(2002, 12, 4).ctime()
'Wed Dec  4 00:00:00 2002'

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

time.ctime(time.mktime(d.timetuple()))

на платформах, где родная функция ctime() (который time.ctime() вызывает, но который не вызывает date.ctime()) соответствует стандарту C.

date.strftime(format)

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

date.__format__(format)

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

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

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

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

>>> # Методы, связанные с форматированием вывода строки
>>> d.isoformat()
'2002-03-11'
>>> d.strftime("%d/%m/%y")
'11/03/02'
>>> d.strftime("%A %d. %B %Y")
'Monday 11. March 2002'
>>> d.ctime()
'Mon Mar 11 00:00:00 2002'
>>> 'The {1} is {0:%d}, the {2} is {0:%B}.'.format(d, "day", "month")
'The day is 11, the month is March.'

>>> # Способы извлечения "компонентов" под разными календарями
>>> t = d.timetuple()
>>> for i in t:     
...     print(i)
2002                # год
3                   # месяц
11                  # день
0
0
0
0                   # день недели (0 = понедельник)
70                  # 70th day in the year
-1
>>> ic = d.isocalendar()
>>> for i in ic:    
...     print(i)
2002                # ISO год
11                  # ISO номер недели
1                   # ISO номер дня ( 1 = понедельник )

>>> # Объект даты является неизменяемым; все операции создают новый объект
>>> d.replace(year=2005)
datetime.date(2005, 3, 11)

Объекты datetime

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

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

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

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

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

  • MINYEAR <= year <= MAXYEAR,
  • 1 <= month <= 12,
  • 1 <= day <= nколичество дней в данном месяце и году,
  • 0 <= hour < 24,
  • 0 <= minute < 60,
  • 0 <= second < 60,
  • 0 <= microsecond < 1000000,
  • fold in [0, 1].

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

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

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

classmethod datetime.today()

Возвращает текущее значение локальной datetime с tzinfo None.

Эквивалентный:

datetime.fromtimestamp(time.time())

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

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

classmethod datetime.now(tz=None)

Возврат текущей локальной даты и времени.

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

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

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

classmethod datetime.utcnow()

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

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

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

Поскольку наивные объекты datetime рассматривают много методов datetime как локальный времен, это предпочтено, чтобы использовать осведомленный datetimes, чтобы представлять времена в UTC. Таким образом, рекомендуется создать объект, представляющий текущее время в UTC, путем вызова метода datetime.now(timezone.utc).

classmethod datetime.fromtimestamp(timestamp, tz=None)

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

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

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

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

Изменено в версии 3.6: fromtimestamp() может возвратить сущности с набором fold к 1.

classmethod datetime.utcfromtimestamp(timestamp)

Возвращает UTC- datetime, соответствующий временной метке POSIX, со значением tzinfo None. (Результирующий объект наивен.)

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

Чтобы получить Знающий объект datetime, вызовите fromtimestamp():

datetime.fromtimestamp(timestamp, timezone.utc)

На платформах, совместимых с POSIX, это эквивалентно следующему выражению:

datetime(1970, 1, 1, tzinfo=timezone.utc) + timedelta(seconds=timestamp)

за исключением последней формулы всегда поддерживает полный диапазон лет: от MINYEAR до MAXYEAR включительно.

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

Поскольку наивные объекты datetime рассматривают много методов datetime как времена локальная, это предпочтено, чтобы использовать осведомленный datetimes, чтобы представлять времена в UTC. Таким образом, рекомендуется создать объект, представляющий определенную временную метку в формате UTC, путем вызова метода datetime.fromtimestamp(timestamp, tz=timezone.utc).

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

classmethod datetime.fromordinal(ordinal)

Возвращает datetime, соответствующий пролептическому григорианскому порядковому номеру, где 1 января 1 года имеет порядковый номер 1. Поднимется ValueError, если не 1 <= ordinal <= datetime.max.toordinal(). Все часы, минуты, секунды и микросекунды результата равны 0, а tzinfo равно None.

classmethod datetime.combine(date, time, tzinfo=self.tzinfo)

Возвращает новый объект datetime, компоненты даты которого равны данным объектам date, а компоненты времени равны данным объектам time. Если задан аргумент tzinfo, то его значение является используемый для установки tzinfo атрибут результата, в противном случае tzinfo атрибут аргумента time является используемый.

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

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

classmethod datetime.fromisoformat(date_string)

Возвращает datetime, соответствующий date_string в одном из форматов, выдаваемых date.isoformat() и datetime.isoformat().

В частности, эта функция поддерживает строки в формате:

YYYY-MM-DD [*HH [: MM [: SS [.fff [fff]]]] [+HH:MM [: SS [.ffffff]]]]

где * может совпадать с любым отдельным символ.

Осторожно

Он не поддерживает парсинг произвольной ISO 8601 строки - только предназначен как обратная операция datetime.isoformat(). Более полнофункциональный ISO 8601 парсер, dateutil.parser.isoparse доступен в стороннем пакете dateutil.

Примеры:

>>> from datetime import datetime
>>> datetime.fromisoformat('2011-11-04')
datetime.datetime(2011, 11, 4, 0, 0)
>>> datetime.fromisoformat('2011-11-04T00:05:23')
datetime.datetime(2011, 11, 4, 0, 5, 23)
>>> datetime.fromisoformat('2011-11-04 00:05:23.283')
datetime.datetime(2011, 11, 4, 0, 5, 23, 283000)
>>> datetime.fromisoformat('2011-11-04 00:05:23.283+00:00')
datetime.datetime(2011, 11, 4, 0, 5, 23, 283000, tzinfo=datetime.timezone.utc)
>>> datetime.fromisoformat('2011-11-04T00:05:23+04:00')   
datetime.datetime(2011, 11, 4, 0, 5, 23,
    tzinfo=datetime.timezone(datetime.timedelta(seconds=14400)))

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

classmethod datetime.fromisocalendar(year, week, day)

Возвращает datetime, соответствующий дате календаря ISO, указанной по году, неделе и дню. Компоненты недаты даты и времени населены с их нормальным дефолтом значения. Это инверсия функции datetime.isocalendar().

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

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, если ни один не был передан.

datetime.fold

В [0, 1]. Используется для устранения неоднозначности времени стенки в течение повторяющегося интервала. (Повторный интервал возникает, когда часы откатываются в конце летнего времени или когда смещение UTC для текущей зоны уменьшается по политическим причинам.) значение 0 (1) представляет более ранний (более поздний) из двух моментов с одним и тем же представлением времени стенки.

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

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

Операция Результат
datetime2 = datetime1 + timedelta (1)
datetime2 = datetime1 - timedelta (2)
timedelta = datetime1 - datetime2 (3)
datetime1 < datetime2 Сравнивнение datetime с datetime. (4)

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

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

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

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

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

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

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

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

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

    Примечание

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

Методы сущности:

datetime.date()

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

datetime.time()

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

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

datetime.timetz()

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

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

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

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

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

datetime.astimezone(tz=None)

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

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

Если вызван без аргументов (или с tz=None) локальный системный часовой пояс принимается для целевого часового пояса. .tzinfo атрибут конвертированной сущности datetime будет установлен в сущность timezone с зональным именем и возмещен полученный из ОС.

Если self.tzinfo- tz, то self.astimezone(tz) равно self: корректировка данных даты или времени не производится. В противном случае результатом будет локальное время в часовом поясе tz, представляющее то же время UTC, что и self: после astz = dt.astimezone(tz), astz - astz.utcoffset() будет иметь те же данные даты и времени, что и dt - dt.utcoffset().

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

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

datetime.utcoffset()

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

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

datetime.dst()

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

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

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 is 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 объекты обрабатываются многими datetime методами как локализованное время, предпочтительно использовать знающие даты для представления времени в UTC; в результате использование utcfromtimetuple может привести к вводящим в заблуждение результатам. Если у вас есть наивный datetime, представляющий UTC, используйте datetime.replace(tzinfo=timezone.utc), чтобы сделать его знающим, и в этот момент вы можете использовать datetime.timetuple().

datetime.toordinal()

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

datetime.timestamp()

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

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

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

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

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

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

Примечание

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

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

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

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

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

datetime.isoweekday()

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

datetime.isocalendar()

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

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

Возвращает строку, представляющую дату и время в формате ISO 8601:

Если utcoffset() не возвращает None, строка дополняется, предоставленным UTC смещением:

  • YYYY-MM-DDTHH:MM:SS.ffffff+HH:MM[:SS[.ffffff]], если microsecond не 0
  • YYYY-MM-DDTHH:MM:SS+HH:MM[:SS[.ffffff]], если microsecond - 0

Примеры:

>>> from datetime import datetime, timezone
>>> datetime(2019, 5, 18, 15, 17, 8, 132263).isoformat()
'2019-05-18T15:17:08.132263'
>>> datetime(2019, 5, 18, 15, 17, tzinfo=timezone.utc).isoformat()
'2019-05-18T15:17:00+00:00'

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

>>> from datetime import tzinfo, timedelta, datetime
>>> class TZ(tzinfo):
...     """Часовой пояс с произвольным постоянным смещением -06:39."""
...     def utcoffset(self, dt):
...         return timedelta(hours=-6, minutes=-39)
...
>>> datetime(2002, 12, 25, tzinfo=TZ()).isoformat(' ')
'2002-12-25 00:00:00-06:39'
>>> datetime(2009, 11, 27, microsecond=100, tzinfo=TZ()).isoformat()
'2009-11-27T00:00:00.000100-06:39'

Дополнительный аргумент timespec указывает количество дополнительных компонентов времени для включения (по умолчанию - 'auto'). Он может быть одним из следующих:

  • 'auto': то же, что и 'seconds', если microsecond 0, то же, что и 'microseconds' иначе.
  • 'hours': включить hour в двухзначный формат HH.
  • 'minutes': включить hour и minute в формате HH:MM.
  • 'seconds': включить hour, minute и second в формате HH:MM:SS.
  • 'milliseconds': включить полный рабочий день, но усечь дробную вторую часть до миллисекунд. Формат HH:MM:SS.sss.
  • 'microseconds': включить полный рабочий день в формате HH:MM:SS.ffffff.

Примечание

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

ValueError будет вызван для недопустимого аргумента timespec:

>>> from datetime import datetime
>>> datetime.now().isoformat(timespec='minutes')   
'2002-12-25T00:00'
>>> dt = datetime(2015, 1, 1, 12, 30, 59, 0)
>>> dt.isoformat(timespec='microseconds')
'2015-01-01T12:30:59.000000'

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

datetime.__str__()

Для datetime сущность d str(d) эквивалентно d.isoformat(' ').

datetime.ctime()

Возвращает строка, представляющий дату и время:

>>> from datetime import datetime
>>> datetime(2002, 12, 4, 20, 30, 40).ctime()
'Wed Dec  4 20:30:40 2002'

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

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

time.ctime(time.mktime(d.timetuple()))

на платформах, где родная функция ctime() (которая time.ctime() вызывает, но не вызываема datetime.ctime()) соответствует стандарту C.

datetime.strftime(format)

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

datetime.__format__(format)

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

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

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

>>> from datetime import datetime, date, time, timezone

>>> # Использование 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.now()   
datetime.datetime(2007, 12, 6, 16, 29, 43, 79043)   # GMT +1
>>> datetime.now(timezone.utc)   
datetime.datetime(2007, 12, 6, 15, 29, 43, 79060, tzinfo=datetime.timezone.utc)

>>> # Использование 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    # год
11      # месяц
21      # день
16      # час
30      # минута
0       # секунда
1       # день недели (0 = понедельник)
325     # количество дней с 1 января
-1      # dst - метод tzinfo.dst() возвращает None

>>> # Дата в ISO формате
>>> ic = dt.isocalendar()
>>> for it in ic:   
...     print(it)
...
2006    # ISO год
47      # ISO неделя
2       # ISO день недели

>>> # Форматирование даты и времени
>>> 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.'

Приведенный ниже пример определяет tzinfo подкласса сбор информации часового пояса для Кабула, Афганистан, который использует +4 UTC до 1945 и затем +4:30 UTC после этого:

from datetime import timedelta, datetime, tzinfo, timezone

class KabulTz(tzinfo):
    # Кабул используемый +4 до 1945 года, когда они перешли в +4:30
    UTC_MOVE_DATE = datetime(1944, 12, 31, 20, tzinfo=timezone.utc)

    def utcoffset(self, dt):
        if dt.year < 1945:
            return timedelta(hours=4)
        elif (1945, 1, 1, 0, 0) <= dt.timetuple()[:5] < (1945, 1, 1, 0, 30):
            # Неоднозначный ("мнимый") полуторачасовой диапазон, представляющий "кратность" по
            # времени вследствие сдвига от + 4 до + 4:30. Если dt попадает в воображаемый
            # диапазон, используйте fold, чтобы решить, как разрешить. См. PEP495.
            return timedelta(hours=4, minutes=(30 if dt.fold else 0))
        else:
            return timedelta(hours=4, minutes=30)

    def fromutc(self, dt):
        # Выполнить те же проверки, что и в datetime.tzinfo
        if not isinstance(dt, datetime):
            raise TypeError("fromutc() requires a datetime argument")
        if dt.tzinfo is not self:
            raise ValueError("dt.tzinfo is not self")

        # Для fromutc требуется пользовательская реализация, так как входным значением
        # этой функции является datetime с utc значения, но tzinfo со значением self. См.
        # datetime.astimezone или fromtimestamp.
        if dt.replace(tzinfo=timezone.utc) >= self.UTC_MOVE_DATE:
            return dt + timedelta(hours=4, minutes=30)
        else:
            return dt + timedelta(hours=4)

    def dst(self, dt):
        # Кабул не соблюдает летнее время.
        return timedelta(0)

    def tzname(self, dt):
        if dt >= self.UTC_MOVE_DATE:
            return "+04:30"
        return "+04"

Использование KabulTz сверху:

>>> tz1 = KabulTz()

>>> # Дата-время перед изменением
>>> dt1 = datetime(1900, 11, 21, 16, 30, tzinfo=tz1)
>>> print(dt1.utcoffset())
4:00:00

>>> # Дата-время после изменения
>>> dt2 = datetime(2006, 6, 14, 13, 0, tzinfo=tz1)
>>> print(dt2.utcoffset())
4:30:00

>>> # Преобразование даты и времени в другой часовой пояс
>>> dt3 = dt2.astimezone(timezone.utc)
>>> dt3
datetime.datetime(2006, 6, 14, 8, 30, tzinfo=datetime.timezone.utc)
>>> dt2
datetime.datetime(2006, 6, 14, 13, 0, tzinfo=KabulTz())
>>> dt2 == dt3
True

Объекты time

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

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

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

  • 0 <= hour < 24
  • 0 <= minute < 60
  • 0 <= second < 60
  • 0 <= microsecond < 1000000
  • fold in [0, 1].

Если аргумент вне тех диапазонов дан, поднимается ValueError. Все значения по умолчанию - 0, кроме tzinfo, по умолчанию - None.

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

time.min

Самый ранний представимый time, time(0, 0, 0, 0).

time.max

Последняя представляемая time, time(23, 59, 59, 999999).

time.resolution

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

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

time.hour

В range(24).

time.minute

В range(60).

time.second

В range(60).

time.microsecond

В range(1000000).

time.tzinfo

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

time.fold

В [0, 1]. Используется для устранения неоднозначности временного сгиба в течение повторяющегося интервала. (Повторный интервал возникает, когда часы откатываются в конце летнего времени или когда смещение UTC для текущей зоны уменьшается по политическим причинам.) значение 0 (1) представляет более ранний (более поздний) из двух моментов с одним и тем же представлением временем сгиба.

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

time объекты поддерживают сравнение time с time, где a считается меньше b, когда a предшествует b во времени. Если один компаранд наивен, и другой знающий, поднимается TypeError, если предпринято сравнение по порядку. Для сравнения равенства наивные сущности никогда не равны знающим сущностям.

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

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

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

Изменено в версии 3.5: До Python 3.5 объект time считался ложным, если он представлял полночь в UTC. Такое поведение считалось неясным и подверженным ошибкам и было удалено в Python 3.5. Полную информацию см. в разделе bpo-13936.

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

classmethod time.fromisoformat(time_string)

Возвращает time, соответствующий time_string в одном из форматов, выдаваемых time.isoformat(). В частности, эта функция поддерживает строки в формате:

HH [:MM [:SS [.fff [fff]]]] [+HH:MM [:SS [.ffffff]]]

Осторожно

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

Примеры:

>>> from datetime import time
>>> time.fromisoformat('04:23:01')
datetime.time(4, 23, 1)
>>> time.fromisoformat('04:23:01.000384')
datetime.time(4, 23, 1, 384)
>>> time.fromisoformat('04:23:01+04:00')
datetime.time(4, 23, 1, tzinfo=datetime.timezone(datetime.timedelta(seconds=14400)))

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

Методы сущности:

time.replace(hour=self.hour, minute=self.minute, second=self.second, microsecond=self.microsecond, tzinfo=self.tzinfo, *, fold=0)

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

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

time.isoformat(timespec='auto')

Возвращает строку, представляющий время в формате ISO 8601, одним из:

  • HH:MM:SS.ffffff, если microsecond не равно 0
  • HH:MM:SS, если microsecond равно 0
  • HH:MM:SS.ffffff+HH:MM[:SS[.ffffff]], если utcoffset() не возвращает None
  • HH:MM:SS+HH:MM[:SS[.ffffff]], если microsecond равно 0 и utcoffset() не возвращает None

Дополнительный аргумент timespec указывает количество дополнительных компонентов времени для включения (по умолчанию - 'auto'). Это может быть одно из следующих:

  • 'auto': то же, что и 'seconds', если microsecond 0, то же, что и 'microseconds' иначе.
  • 'hours': включить hour в двухзначный формат HH.
  • 'minutes': включить hour и minute в формате HH:MM.
  • 'seconds': включить hour, minute и second в формате HH:MM:SS.
  • 'milliseconds': включить полный рабочий день, но усечь дробную вторую часть до миллисекунд. Формат HH:MM:SS.sss.
  • 'microseconds': включить полный рабочий день в формате HH:MM:SS.ffffff.

Примечание

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

Будет поднято ValueError для недопустимого аргумента timespec.

Пример:

>>> from datetime import time
>>> time(hour=12, minute=34, second=56, microsecond=123456).isoformat(timespec='minutes')
'12:34'
>>> dt = time(hour=12, minute=34, second=56, microsecond=0)
>>> dt.isoformat(timespec='microseconds')
'12:34:56.000000'
>>> dt.isoformat(timespec='auto')
'12:34:56'

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

time.__str__()

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

time.strftime(format)

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

time.__format__(format)

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

time.utcoffset()

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

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

time.dst()

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

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

time.tzname()

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

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

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

>>> from datetime import time, tzinfo, timedelta
>>> class TZ1(tzinfo):
...     def utcoffset(self, dt):
...         return timedelta(hours=1)
...     def dst(self, dt):
...         return timedelta(0)
...     def tzname(self,dt):
...         return "+01:00"
...     def  __repr__(self):
...         return f"{self.__class__.__name__}()"
...
>>> t = time(12, 10, 30, tzinfo=TZ1())
>>> t
datetime.time(12, 10, 30, tzinfo=TZ1())
>>> t.isoformat()
'12:10:30+01:00'
>>> t.dst()
datetime.timedelta(0)
>>> t.tzname()
'+01:00'
>>> t.strftime("%H:%M:%S %Z")
'12:10:30 +01:00'
>>> 'The {} is {:%H:%M}.'.format("time", t)
'The time is 12:10.'

Объекты tzinfo

class datetime.tzinfo

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

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

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

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

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

tzinfo.utcoffset(dt)

Возвращаемое смещение локального времени от UTC в виде объекта timedelta, положительного к востоку от UTC. Если время локальная к западу от UTC, это должно быть отрицательно.

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

return CONSTANT                 # класс с фиксированным смещением
return CONSTANT + self.dst(dt)  # дневной класс

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

Экстремальное значение по умолчанию utcoffset() поднимает NotImplementedError.

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

tzinfo.dst(dt)

Возвращает корректировку на DST время в качестве объекта timedelta или None, если информация о DTS неизвестна.

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

Экземпляр tz подкласса tzinfo, которое моделирует как стандартное, так и дневное время, должно быть согласованным в этом смысле:

tz.utcoffset(dt) - tz.dst(dt)

должен возвратить тот же результат для каждого datetime dt с dt.tzinfo == tz. Для нормальных подклассов tzinfo, это выражение приводит к «стандартному смещению часового пояса», которое не должно зависеть от даты или времени, но только от географическом положении. Реализация datetime.astimezone() опирается на это, но не может выявить нарушения; программист несет ответственность за это. Если tzinfo подкласс не может гарантировать это, он может быть в состоянии переопределить реализацию по умолчанию tzinfo.fromutc(), чтобы правильно работать с astimezone() независимо.

Большинство реализаций dst(), вероятно, будет выглядеть как одна из этих двух:

def dst(self, dt):
    # класс с фиксированным смещением: не учитывает DST
    return timedelta(0)

или:

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

    if dston <= dt.replace(tzinfo=None) < dstoff:
        return timedelta(hours=1)
    else:
        return timedelta(0)

Экстремальное значение по умолчанию dst() поднимет NotImplementedError.

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

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):
    # поднимается ошибка CreateError, если dt.tzinfo не является self
    dtoff = dt.utcoffset()
    dtdst = dt.dst()
    # поднимается CreateError, если dtoff содержит значение None, а dtdst - значение None
    delta = dtoff - dtdst  # this is self's standard offset
    if delta:
        dt += delta   # преобразовать в локальное стандартное время
        dtdst = dt.dst()
        # поднимается CreateError, если dtdst имеет значение None
    if dtdst:
        return dt + dtdst
    else:
        return dt

В следующем файле tzinfo_examples.py есть несколько примеров классов tzinfo:

Обратите внимание, что есть неизбежная тонкость дважды в год в tzinfo подклассе, составляющем и стандарт и летнее время в точках перехода DST. Для конкретики рассмотрим 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

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

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

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

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

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

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

См.также

dateutil.tz

Модуль datetime имеет базовый класс timezone (для обработки произвольных фиксированных смещений от UTC) и его timezone.utc атрибут (экземпляр часового пояса UTC).

Библиотека dateutil.tz выводит IANA база данных часовых поясов (также известную как база данных Olson) в Python, и рекомендуется его использование.

IANA база данных часовых поясов
База данных часовых поясов (часто называемая tz, tzdata или zoneinfo) содержит код и данные, представляющие историю локальная времени для многих репрезентативных местоположений по всему миру. Он периодически обновляется для отражения изменений, внесенных политическими органами в границы часового пояса, смещения UTC и правила перехода на летнее время.

Объекты timezone

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

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

class datetime.timezone(offset, name=None)

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

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

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

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

timezone.utcoffset(dt)

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

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

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

timezone.tzname(dt)

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

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

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

timezone.dst(dt)

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

timezone.fromutc(dt)

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

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

timezone.utc

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

strftime() и strptime() поведение

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

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

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

  strftime strptime
Использование Преобразовать объект в строку в соответствии с заданным форматом Парсинг строки в объект datetime, учитывая соответствующий формат
Тип метода Метод экземпляра Метод класса
Метод из date; datetime; time datetime
Сигнатура strftime(format) strptime(date_string, format)

strftime() и strptime() коды формата

Ниже приведен список всех форматов кодов, которые требует стандарт 1989 C, и эти работы на всех платформах со стандартной реализацией C.

Директива Значение Пример Прим.
%a Будний день как сокращенное название в локали.
Sun, Mon, …, Sat (en_US);
So, Mo, …, Sa (de_DE)
 (1)
%A День недели как полное название в локали.
Sunday, Monday, …, Saturday (en_US);
Sonntag, Montag, …, Samstag (de_DE)
 (1)
%w День недели в виде десятичного числа, где 0 - воскресенье, а 6 - суббота. 0, 1, …, 6  
%d День месяца в виде десятичного числа с лидирующими нулями. 01, 02, …, 31 (9)
%b Месяц как сокращенное название локали.
Jan, Feb, …, Dec (en_US);
Jan, Feb, …, Dez (de_DE)
 (1)
%B Месяц как полное имя в локали.
January, February, …, December (en_US);
Januar, Februar, …, Dezember (de_DE)
 (1)
%m Месяц в виде десятичного числа с лидирующими нулями. 01, 02, …, 12 (9)
%y Год без века в виде десятичного числа с лидирующими нулями. 00, 01, …, 99 (9)
%Y Год с веком как десятичное число. 0001, 0002, …, 2013, 2014, …, 9998, 9999 (2)
%H Час (24-часовые часы) в виде десятичного числа с нулевым числом. 00, 01, …, 23 (9)
%I Час (12-часовые часы) в виде десятичного числа с нулевым числом. 01, 02, …, 12 (9)
%p Языковой стандарт эквивалентен AM или PM.
AM, PM (en_US);
am, pm (de_DE)
 (1), (3)
%M Минута в виде десятичного числа с нулевым числом. 00, 01, …, 59 (9)
%S Секунда в виде десятичного числа с нулевым заполнением. 00, 01, …, 59 (4), (9)
%f Микросекунда - десятичное число, заполненное нулем слева. 000000, 000001, …, 999999 (5)
%z Смещение UTC в формате ±HHMM[SS[.ffffff]] (пустая строка, если объект наивен). (empty), +0000, -0400, +1030, +063415, -030712.345216 (6)
%Z Имя часового пояса (пустая строка, если объект является наивным). (empty), UTC, EST, CST  
%j День года в виде десятичного числа с нулевым числом. 001, 002, …, 366 (9)
%U Номер недели года (воскресенье как первый день недели) в виде нулевого десятичного числа. Все дни в новом году, предшествующие первому воскресенью, считаются 0 в неделе. 00, 01, …, 53 (7), (9)
%W Номер недели года (понедельник как первый день недели) в виде десятичного числа. Все дни в новом году, предшествующие первому понедельнику, считаются неделями 0. 00, 01, …, 53 (7), (9)
%c Соответствующее представление даты и времени языкового стандарта.
Tue Aug 16 21:30:00 1988 (en_US);
Di 16 Aug 21:30:00 1988 (de_DE)
 (1)
%x Соответствующее представление rдаты языкового стандарта.
08/16/88 (None);
08/16/1988 (en_US);
16.08.1988 (de_DE)
 (1)
%X Соответствующее представление времени языкового стандарта.
21:30:00 (en_US);
21:30:00 (de_DE)
 (1)
%% А литерал '%' символ. %  

Для удобства включены несколько дополнительных директив, не требуемых стандартом C89. Все эти параметры соответствуют ISO 8601 значениям дат.

Директива Значение Пример Прим.
%G ISO 8601 год с веком, представляющим год, который содержит большую часть ISO недели (%V). 0001, 0002, …, 2013, 2014, …, 9998, 9999 (8)
%u День недели ISO 8601 в виде десятичного числа, где 1 - понедельник. 1, 2, …, 7  
%V Неделя ISO 8601 в виде десятичного числа с понедельником в качестве первого дня недели. Неделя 01 - это неделя, содержащая 4 января. 01, 02, …, 53 (8), (9)

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

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

Добавлено в версии 3.6: Были добавлены %G, %u и %V.

Техническая деталь

В широком смысле, d.strftime(fmt) действует как time модуля time.strftime(fmt, d.timetuple()), хотя не все объекты поддерживают метод timetuple().

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

Использование datetime.strptime(date_string, format) эквивалентно:

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

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

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

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

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

Примечания:

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

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

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

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

  3. Когда используемая с методом strptime(), директива %p только затрагивает поле часа вывода, если используется директива %I, чтобы распарсить час.

  4. В отличие от модуля time, модуль datetime не поддерживает високосные секунды.

  5. Когда используемый с методом strptime(), директива %f принимает от одной до шести цифр и набивающих нулей справа. %f - расширение набора символов формата в стандарте C (но реализованное отдельно в объектах datetime и, следовательно, всегда доступное).

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

    Для знающего объекта:

    %z

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

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

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

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

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

  7. Когда используются с методом strptime(), %U и %W - только используются в вычислениях, когда определен день недели и календарный год (%Y).

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

  9. Когда используемый с методом strptime(), ведущий ноль опционален для форматов %d, %m, %H, %I, %M, %S, %J, %U, %W и %V. Формат %y требует начального нуля.

Сноски

[1]Если есть, мы игнорируем эффекты Относительности
[2]Это соответствует определению «пролептического Григорианского» календаря в Дершовица и книге Рейнгольда Календарные расчеты, где это базовый календарь для всех вычислений. Смотрите в книге алгоритмы преобразования между пролептическими Григорианскими ординалами и многими другими календарными системами.
[3]См. R. H. van Gent’s руководство по математике календаря ISO 8601 для хорошего объяснения.
[4]Предача datetime.strptime('Feb 29', '%b %d') провалится, так как 1900 не високосный год.