datetime
— Основные типы даты и времени¶
Источник: Lib/datetime.py
Модуль datetime
предоставляет классы для работы с датами и временем.
Хотя арифметика даты и времени поддерживается, основное внимание в реализации уделяется эффективному извлечению атрибутов для форматирования и манипулирования выводом.
Совет
Перейдите к the format codes.
См.также
- Модуль
calendar
Общие функции, связанные с календарем.
- Модуль
time
Доступ к времени и его преобразование.
- Модуль
zoneinfo
Конкретные часовые пояса, представляющие базу данных часовых поясов IANA.
- Пакет dateutil
Сторонняя библиотека с расширенной поддержкой часовых поясов и парсинга.
- Пакет DateType
Сторонняя библиотека, которая вводит отдельные статические типы, чтобы, например, позволить static type checkers различать наивные и осознанные даты.
Осознанные и наивные объекты¶
Объекты даты и времени могут быть классифицированы как «осведомленные» или «наивные» в зависимости от того, включают ли они информацию о часовом поясе или нет.
Обладая достаточными знаниями о применимых алгоритмических и политических корректировках времени, таких как информация о часовом поясе и переходе на летнее время, осознающий объект может определить свое местоположение относительно других осознающих объектов. Осознающий объект представляет собой конкретный момент времени, который не подлежит интерпретации. [1]
Объект naive не содержит достаточно информации, чтобы однозначно определить свое местоположение относительно других объектов даты/времени. Представляет ли наивный объект всемирное координированное время (UTC), местное время или время в каком-то другом часовом поясе, зависит исключительно от программы, точно так же как от программы зависит, представляет ли конкретное число метры, мили или массу. Наивные объекты просты для понимания и работы с ними, но за счет игнорирования некоторых аспектов реальности.
Для приложений, которым требуются объекты с информацией, объекты datetime
и time
имеют необязательный атрибут информации о часовом поясе, tzinfo
, который может быть установлен на экземпляр подкласса абстрактного класса tzinfo
. Эти объекты tzinfo
получают информацию о смещении от времени UTC, названии часового пояса и о том, действует ли переход на летнее время.
Модуль datetime
предоставляет только один конкретный класс tzinfo
, класс timezone
. Класс timezone
может представлять простые часовые пояса с фиксированным смещением от UTC, такие как сам UTC или североамериканские часовые пояса EST и EDT. Поддержка часовых поясов на более глубоких уровнях детализации зависит от приложения. Правила корректировки времени во всем мире скорее политические, чем рациональные, часто меняются, и не существует стандарта, подходящего для всех приложений, кроме UTC.
Константы¶
Модуль datetime
экспортирует следующие константы:
- datetime.UTC¶
Псевдоним для синглтона часового пояса UTC
datetime.timezone.utc
.Added in version 3.11.
Доступные типы¶
- 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
Длительность, выражающая разницу между двумя экземплярами
datetime
илиdate
с микросекундным разрешением.
- class datetime.tzinfo
Абстрактный базовый класс для объектов информации о часовом поясе. Они используются классами
datetime
иtime
для предоставления настраиваемого представления о корректировке времени (например, для учета часового пояса и/или перехода на летнее время).
- class datetime.timezone
Класс, реализующий абстрактный базовый класс
tzinfo
в виде фиксированного смещения от UTC.Added in version 3.2.
Объекты этих типов неизменяемы.
Отношения подклассов:
object
timedelta
tzinfo
timezone
time
date
datetime
Общие свойства¶
Определение осведомленности или наивности объекта¶
Объекты типа date
всегда наивны.
Объект типа time
или datetime
может быть осведомленным или наивным.
Объект datetime
d является осведомленным, если выполняются оба следующих условия:
d.tzinfo
неNone
d.tzinfo.utcoffset(d)
не возвращаетсяNone
В противном случае d наивен.
Объект time
t является осведомленным, если выполняются оба следующих условия:
t.tzinfo
неNone
t.tzinfo.utcoffset(None)
не возвращаетNone
.
В противном случае t наивен.
Различие между «знающими» и «наивными» не применимо к объектам timedelta
.
timedelta
Объекты¶
Объект timedelta
представляет собой длительность, разницу между двумя экземплярами datetime
или date
.
- class datetime.timedelta(days=0, seconds=0, microseconds=0, milliseconds=0, minutes=0, hours=0, weeks=0)¶
Все аргументы необязательны и по умолчанию равны 0. Аргументы могут быть целыми или плавающими числами и могут быть положительными или отрицательными.
Внутри хранятся только дни, секунды и микросекунды. Аргументы преобразуются в эти единицы:
Миллисекунда преобразуется в 1000 микросекунд.
Минута преобразуется в 60 секунд.
Час преобразуется в 3600 секунд.
Неделя преобразуется в 7 дней.
а дни, секунды и микросекунды затем нормализуются так, чтобы представление было уникальным, с
0 <= microseconds < 1000000
0 <= seconds < 3600*24
(количество секунд в одном дне)-999999999 <= days <= 999999999
В следующем примере показано, как любые аргументы, кроме days, seconds и microseconds, «объединяются» и нормализуются в эти три результирующих атрибута:
>>> from datetime import timedelta >>> delta = timedelta( ... days=50, ... seconds=27, ... microseconds=10, ... milliseconds=29000, ... minutes=5, ... hours=8, ... weeks=2 ... ) >>> # Only days, seconds, and microseconds remain >>> delta datetime.timedelta(days=64, seconds=29156, microseconds=10)
Если какой-либо аргумент является float и в нем присутствуют дробные микросекунды, то дробные микросекунды, оставшиеся от всех аргументов, объединяются, и их сумма округляется до ближайшей микросекунды с использованием тайбрейка «круглый-половинный-четный». Если ни один из аргументов не является плавающей величиной, процессы преобразования и нормализации являются точными (информация не теряется).
Если нормализованное значение дней выходит за пределы указанного диапазона, устанавливается значение
OverflowError
.Обратите внимание, что нормализация отрицательных значений может поначалу удивить. Например:
>>> from datetime import timedelta >>> d = timedelta(microseconds=-1) >>> (d.days, d.seconds, d.microseconds) (-1, 86399, 999999)
Атрибуты класса:
- 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
.
Атрибуты экземпляра (только для чтения):
Атрибут |
Значение |
---|---|
|
Между -999999999 и 999999999 включительно |
|
От 0 до 86399 включительно |
|
От 0 до 999999 включительно |
Поддерживаемые операции:
Операция |
Результат |
---|---|
|
Сумма |
|
Разность |
|
Дельта умножается на целое число. После этого |
В общем случае |
|
|
Дельта, умноженная на плавающее значение. Результат округляется до ближайшего кратного значения timedelta.resolution с помощью функции round-half-to-even. |
|
Деление (3) общей продолжительности |
|
Дельта, деленная на float или int. Результат округляется до ближайшего кратного timedelta.resolution с помощью функции round-half-to-even. |
|
Вычисляется пол, а остаток (если он есть) отбрасывается. Во втором случае возвращается целое число. (3) |
|
Остаток вычисляется как объект |
|
Вычисляет коэффициент и остаток: |
|
Возвращает объект |
|
Эквивалентно |
|
Эквивалентно |
|
Возвращает строку в виде |
|
Возвращает строковое представление объекта |
Примечания:
Это точно, но может переполниться.
Это точное значение, которое не может переполниться.
Деление на ноль возводит в степень
ZeroDivisionError
.-timedelta.max
не может быть представлен как объектtimedelta
.Строковые представления объектов
timedelta
нормализуются аналогично их внутреннему представлению. Это приводит к несколько необычным результатам для отрицательных таймдельта. Например:>>> timedelta(hours=-5) datetime.timedelta(days=-1, seconds=68400) >>> print(_) -1 day, 19:00:00
Выражение
t2 - t3
всегда будет равно выражениюt2 + (-t3)
, за исключением случая, когда t3 равноtimedelta.max
; в этом случае первое выражение даст результат, а второе переполнится.
Помимо перечисленных выше операций, объекты timedelta
поддерживают определенные операции сложения и вычитания с объектами date
и datetime
(см. ниже).
Изменено в версии 3.2: Теперь поддерживается деление нацело и истинное деление объекта timedelta
на другой объект timedelta
, а также операции с остатком и функция divmod()
. Истинное деление и умножение объекта timedelta
на объект float
теперь поддерживаются.
Объекты timedelta
поддерживают сравнение равенства и порядка.
В булевых контекстах объект timedelta
считается истинным тогда и только тогда, когда он не равен timedelta(0)
.
Методы экземпляра:
- timedelta.total_seconds()¶
Возвращает общее количество секунд, содержащихся в длительности. Эквивалентно
td / timedelta(seconds=1)
. Для единиц измерения интервалов, отличных от секунд, используйте форму деления напрямую (например,td / timedelta(microseconds=1)
).Обратите внимание, что для очень больших временных интервалов (более 270 лет на большинстве платформ) этот метод будет терять микросекундную точность.
Added in version 3.2.
Примеры использования: timedelta
¶
Дополнительный пример нормализации:
>>> # Components of another_year add up to exactly 365 days
>>> 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 <= 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
, если временная метка находится вне диапазона значений, поддерживаемых функциейlocaltime()
платформы C, и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
.
- classmethod date.fromisoformat(date_string)¶
Возвращает
date
, соответствующий дате_строки, заданной в любом допустимом формате ISO 8601, за следующими исключениями:Даты с уменьшенной точностью в настоящее время не поддерживаются (
YYYY-MM
,YYYY
).Расширенные представления даты в настоящее время не поддерживаются (
±YYYYYY-MM-DD
).Порядковые даты в настоящее время не поддерживаются (
YYYY-OOO
).
Примеры:
>>> from datetime import date >>> date.fromisoformat('2019-12-04') datetime.date(2019, 12, 4) >>> date.fromisoformat('20191204') datetime.date(2019, 12, 4) >>> date.fromisoformat('2021-W01-1') datetime.date(2021, 1, 4)
Added in version 3.7.
Изменено в версии 3.11: Ранее этот метод поддерживал только формат
YYYY-MM-DD
.
- classmethod date.fromisocalendar(year, week, day)¶
Возвращает
date
, соответствующий календарной дате ISO, заданной годом, неделей и днем. Это обратная функцияdate.isocalendar()
.Added in version 3.8.
Атрибуты класса:
- date.min¶
Самая ранняя представляемая дата,
date(MINYEAR, 1, 1)
.
- date.max¶
Самая поздняя представляемая дата,
date(MAXYEAR, 12, 31)
.
- date.resolution¶
Наименьшая возможная разница между неравными объектами даты,
timedelta(days=1)
.
Атрибуты экземпляра (только для чтения):
- date.month¶
От 1 до 12 включительно.
- date.day¶
От 1 до количества дней в данном месяце данного года.
Поддерживаемые операции:
Операция |
Результат |
---|---|
|
|
|
Вычисляет |
|
(3) |
date1 == date2 date1 != date2 |
Сравнение равенств. (4) |
date1 < date2 date1 > date2 date1 <= date2 date1 >= date2 |
Сравнение заказов. (5) |
Примечания:
date2 сдвигается вперед во времени, если
timedelta.days > 0
, или назад, еслиtimedelta.days < 0
. После этогоdate2 - date1 == timedelta.days
.timedelta.seconds
иtimedelta.microseconds
игнорируются. ЗначениеOverflowError
повышается, еслиdate2.year
будет меньшеMINYEAR
или большеMAXYEAR
.timedelta.seconds
иtimedelta.microseconds
игнорируются.Это точное значение, которое не может переполниться.
timedelta.seconds
иtimedelta.microseconds
равны 0, аdate2 + timedelta == date1
- после.Объекты
date
равны, если они представляют одну и ту же дату.Объекты
date
, не являющиеся также экземплярамиdatetime
, никогда не равны объектамdatetime
, даже если они представляют одну и ту же дату.дата1 считается меньше даты2, если дата1 предшествует дате2 по времени. Другими словами,
date1 < date2
тогда и только тогда, когдаdate1.toordinal() < date2.toordinal()
.При сравнении порядка между объектом
date
, который не является также экземпляромdatetime
, и объектомdatetime
возникает ошибкаTypeError
.
Изменено в версии 3.13: Сравнение объекта datetime
с экземпляром подкласса date
, который не является подклассом datetime
, больше не преобразует последний в date
, игнорируя часть времени и часовой пояс. Поведение по умолчанию можно изменить, переопределив специальные методы сравнения в подклассах.
В булевых контекстах все объекты date
считаются истинными.
Методы экземпляра:
- 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
также поддерживаются родовой функциейcopy.replace()
.
- 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()¶
Возвращает объект named tuple с тремя компонентами:
year
,week
иweekday
.Календарь ISO - это широко используемый вариант григорианского календаря. [3]
Год ISO состоит из 52 или 53 полных недель, а неделя начинается в понедельник и заканчивается в воскресенье. Первая неделя года ISO - это первая (григорианская) календарная неделя года, содержащая четверг. Она называется неделей номер 1, и год ISO этого четверга совпадает с григорианским годом.
Например, 2004 год начинается в четверг, поэтому первая неделя 2004 года ISO начинается в понедельник, 29 декабря 2003 года, и заканчивается в воскресенье, 4 января 2004 года:
>>> from datetime import date >>> date(2003, 12, 29).isocalendar() datetime.IsoCalendarDate(year=2004, week=1, weekday=1) >>> date(2004, 1, 4).isocalendar() datetime.IsoCalendarDate(year=2004, week=1, weekday=7)
Изменено в версии 3.9: Результат изменился с кортежа на named tuple.
- date.isoformat()¶
Возвращает строку, представляющую дату в формате ISO 8601,
YYYY-MM-DD
:>>> from datetime import date >>> date(2002, 12, 4).isoformat() '2002-12-04'
- 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()))
на платформах, где родная функция C
ctime()
(которую вызываетtime.ctime()
, но которую не вызываетdate.ctime()
) соответствует стандарту C.
- date.strftime(format)¶
Возвращает строку, представляющую дату, управляемую явной строкой формата. Коды формата, относящиеся к часам, минутам или секундам, будут иметь значения 0. См. также strftime() и strptime() Поведение и
date.isoformat()
.
- date.__format__(format)¶
Аналогично
date.strftime()
. Это позволяет задать строку формата для объектаdate
в formatted string literals и при использованииstr.format()
. См. также strftime() и strptime() Поведение иdate.isoformat()
.
Примеры использования: 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)
>>> # Methods related to formatting string output
>>> 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.'
>>> # Methods for to extracting 'components' under different calendars
>>> 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 )
>>> # A date object is immutable; all operations produce a new object
>>> 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)¶
Аргументы год, месяц и день являются обязательными. tzinfo может быть
None
или экземпляром подклассаtzinfo
. Остальные аргументы должны быть целыми числами в следующих диапазонах:MINYEAR <= year <= MAXYEAR
,1 <= month <= 12
,1 <= day <= number of days in the given month and year
,0 <= hour < 24
,0 <= minute < 60
,0 <= second < 60
,0 <= microsecond < 1000000
,fold in [0, 1]
.
Если задан аргумент, выходящий за пределы этих диапазонов, то будет задан
ValueError
.Изменено в версии 3.6: Добавлен параметр fold.
Другие конструкторы, все методы класса:
- classmethod datetime.today()¶
Возвращает текущее локальное время даты, с
tzinfo
None
.Эквивалент:
datetime.fromtimestamp(time.time())
См. также
now()
,fromtimestamp()
.Этот метод функционально эквивалентен
now()
, но без параметраtz
.
- classmethod datetime.now(tz=None)¶
Возвращает текущую местную дату и время.
Если необязательный аргумент tz равен
None
или не указан, то это аналогичноtoday()
, но, если возможно, обеспечивает большую точность, чем можно получить при использовании временной меткиtime.time()
(например, это возможно на платформах, предоставляющих функцию Cgettimeofday()
).Если tz не является
None
, он должен быть экземпляром подклассаtzinfo
, и текущие дата и время преобразуются в часовой пояс tz.
- classmethod datetime.utcnow()¶
Возвращает текущую дату и время по Гринвичу, с
tzinfo
None
.Это похоже на
now()
, но возвращает текущую дату и время UTC в виде наивного объектаdatetime
. Более точное текущее время по Гринвичу можно получить, вызвавdatetime.now(timezone.utc)
. См. такжеnow()
.Предупреждение
Поскольку наивные объекты
datetime
рассматриваются многими методамиdatetime
как локальное время, для представления времени в UTC предпочтительнее использовать aware datetimes. Поэтому рекомендуемый способ создания объекта, представляющего текущее время в UTC, - это вызовdatetime.now(timezone.utc)
.Не рекомендуется, начиная с версии 3.12: Вместо
datetime.now()
используйтеUTC
.
- classmethod datetime.fromtimestamp(timestamp, tz=None)¶
Возвращает локальную дату и время, соответствующие временной метке POSIX, такой, как возвращает
time.time()
. Если необязательный аргумент tz равенNone
или не указан, временная метка преобразуется в локальную дату и время платформы, а возвращаемый объектdatetime
является наивным.Если tz не является
None
, он должен быть экземпляром подклассаtzinfo
, и временная метка преобразуется в часовой пояс tz.fromtimestamp()
может вызватьOverflowError
, если временная метка выходит за пределы диапазона значений, поддерживаемых функциямиlocaltime()
илиgmtime()
платформы C, иOSError
при отказеlocaltime()
илиgmtime()
. Обычно это ограничено годами с 1970 по 2038. Обратите внимание, что в системах, отличных от POSIX, которые включают високосные секунды в свое понятие временной метки, високосные секунды игнорируютсяfromtimestamp()
, и тогда можно иметь две временные метки, отличающиеся на секунду, которые дают идентичные объектыdatetime
. Этот метод предпочтительнее, чемutcfromtimestamp()
.Изменено в версии 3.3: Вызывайте
OverflowError
вместоValueError
, если временная метка находится вне диапазона значений, поддерживаемых функциямиlocaltime()
илиgmtime()
платформы C. ВызывайтеOSError
вместоValueError
при сбоеlocaltime()
илиgmtime()
.Изменено в версии 3.6:
fromtimestamp()
может возвращать экземпляры сfold
, установленным на 1.
- 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
включительно.Предупреждение
Поскольку наивные объекты
datetime
рассматриваются многими методамиdatetime
как местное время, для представления времени в UTC предпочтительнее использовать aware datetimes. Поэтому рекомендуемый способ создания объекта, представляющего конкретную временную метку в UTC, - это вызовdatetime.fromtimestamp(timestamp, tz=timezone.utc)
.Изменено в версии 3.3: Вызывайте
OverflowError
вместоValueError
, если временная метка находится вне диапазона значений, поддерживаемых функциейgmtime()
платформы C. ВызываетOSError
вместоValueError
при ошибкеgmtime()
.Не рекомендуется, начиная с версии 3.12: Вместо
datetime.fromtimestamp()
используйтеUTC
.
- classmethod datetime.fromordinal(ordinal)¶
Возвращает
datetime
, соответствующий пролептическому григорианскому ординалу, где 1 января года 1 имеет ординал 1. ЗначениеValueError
повышается, если только1 <= ordinal <= datetime.max.toordinal()
. Час, минута, секунда и микросекунда результата равны 0, аtzinfo
равенNone
.
- classmethod datetime.combine(date, time, tzinfo=time.tzinfo)¶
Возвращает новый объект
datetime
, компоненты даты которого равны компонентам данного объектаdate
, а компоненты времени равны компонентам данного объектаtime
. Если указан аргумент tzinfo, его значение используется для установки атрибутаtzinfo
результата, в противном случае используется атрибутtzinfo
аргумента time. Если аргумент date является объектомdatetime
, его компоненты времени и атрибутыtzinfo
игнорируются.Для любого
datetime
объекта d,d == datetime.combine(d.date(), d.time(), d.tzinfo)
.Изменено в версии 3.6: Добавлен аргумент tzinfo.
- classmethod datetime.fromisoformat(date_string)¶
Возвращает
datetime
, соответствующий дате_строки в любом допустимом формате ISO 8601, за следующими исключениями:Смещение часового пояса может иметь дробные секунды.
Разделитель
T
может быть заменен любым символом юникода.Дробные часы и минуты не поддерживаются.
Даты с уменьшенной точностью в настоящее время не поддерживаются (
YYYY-MM
,YYYY
).Расширенные представления даты в настоящее время не поддерживаются (
±YYYYYY-MM-DD
).Порядковые даты в настоящее время не поддерживаются (
YYYY-OOO
).
Примеры:
>>> from datetime import datetime >>> datetime.fromisoformat('2011-11-04') datetime.datetime(2011, 11, 4, 0, 0) >>> datetime.fromisoformat('20111104') 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-04T00:05:23Z') datetime.datetime(2011, 11, 4, 0, 5, 23, tzinfo=datetime.timezone.utc) >>> datetime.fromisoformat('20111104T000523') datetime.datetime(2011, 11, 4, 0, 5, 23) >>> datetime.fromisoformat('2011-W01-2T00:05:23.283') datetime.datetime(2011, 1, 4, 0, 5, 23, 283000) >>> 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)))
Added in version 3.7.
Изменено в версии 3.11: Ранее этот метод поддерживал только форматы, которые могли быть испущены
date.isoformat()
илиdatetime.isoformat()
.
- classmethod datetime.fromisocalendar(year, week, day)¶
Возвращает значение
datetime
, соответствующее календарной дате ISO, заданной годом, неделей и днем. Компоненты datetime, не относящиеся к дате, заполняются своими обычными значениями по умолчанию. Это обратная функцияdatetime.isocalendar()
.Added in version 3.8.
- classmethod datetime.strptime(date_string, format)¶
Возвращает
datetime
, соответствующий дата_строки, разобранной в соответствии с форматом.Если формат не содержит микросекунд или информации о часовом поясе, это эквивалентно:
datetime(*(time.strptime(date_string, format)[0:6]))
ValueError
поднимается, если строка date_string и формат не могут быть разобраныtime.strptime()
или если возвращается значение, не являющееся кортежем времени. См. также strftime() и strptime() Поведение иdatetime.fromisoformat()
.Изменено в версии 3.13: Если в формате указаны день и месяц без года, то теперь выдается
DeprecationWarning
. Это сделано для того, чтобы избежать ошибки четырехлетнего високосного года в коде, пытающемся разобрать только месяц и день, поскольку год по умолчанию, используемый при отсутствии года в формате, не является високосным. Такие значения формата могут вызвать ошибку, начиная с Python 3.15. Обходной путь - всегда включать год в формат. При разборе значений date_string, не содержащих год, перед разбором явно добавьте год, который является високосным:>>> from datetime import datetime >>> date_string = "02/29" >>> when = datetime.strptime(f"{date_string};1984", "%m/%d;%Y") # Avoids leap year bug. >>> when.strftime("%B %d") 'February 29'
Атрибуты класса:
- datetime.max¶
Последние представляемые
datetime
,datetime(MAXYEAR, 12, 31, 23, 59, 59, 999999, tzinfo=None)
.
- datetime.resolution¶
Наименьшая возможная разница между неравными
datetime
объектами,timedelta(microseconds=1)
.
Атрибуты экземпляра (только для чтения):
- 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 означают, соответственно, более ранний и более поздний из двух моментов с одинаковым представлением стенного времени.Added in version 3.6.
Поддерживаемые операции:
Операция |
Результат |
---|---|
|
(1) |
|
(2) |
|
(3) |
datetime1 == datetime2 datetime1 != datetime2 |
Сравнение равенств. (4) |
datetime1 < datetime2 datetime1 > datetime2 datetime1 <= datetime2 datetime1 >= datetime2 |
Сравнение заказов. (5) |
datetime2
- это длительностьtimedelta
, удаленная отdatetime1
, перемещение вперед во времени, еслиtimedelta.days > 0
, или назад, еслиtimedelta.days < 0
. Результат имеет тот же атрибутtzinfo
, что и входной datetime, иdatetime2 - datetime1 == timedelta
после него. ЗначениеOverflowError
повышается, еслиdatetime2.year
будет меньшеMINYEAR
или большеMAXYEAR
. Обратите внимание, что корректировка часового пояса не выполняется, даже если входным данными является объект aware.Вычисляет
datetime2
, такое, чтоdatetime2 + timedelta == datetime1
. Как и в случае сложения, результат имеет тот же атрибутtzinfo
, что и входной datetime, и корректировка часового пояса не производится, даже если входные данные известны.Вычитание
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())
, за исключением того, что реализация никогда не переполняется.Объекты
datetime
равны, если они представляют одну и ту же дату и время с учетом часового пояса.Наивные и осведомленные
datetime
объекты никогда не равны.Если оба компаранта известны и имеют один и тот же атрибут
tzinfo
, атрибутыtzinfo
иfold
игнорируются, и сравниваются базовые времена дат. Если оба компаранта известны и имеют разные атрибутыtzinfo
, сравнение происходит так, как если бы компаранты были сначала преобразованы в UTC, за исключением того, что реализация никогда не переполняется. Экземплярыdatetime
в повторяющемся интервале никогда не равны экземплярамdatetime
в другом часовом поясе.datetime1 считается меньше, чем datetime2, если datetime1 предшествует datetime2 по времени с учетом часового пояса.
Сравнение порядка между наивными и осведомленными
datetime
объектами повышаетTypeError
.Если оба компаранта известны и имеют один и тот же атрибут
tzinfo
, атрибутыtzinfo
иfold
игнорируются, и сравниваются базовые времена дат. Если оба компаранта известны и имеют разные атрибутыtzinfo
, сравнение выполняется так, как если бы компаранты были сначала преобразованы в UTC, за исключением того, что реализация никогда не переполняется.
Изменено в версии 3.3: Сравнение равенств между знающими и наивными экземплярами datetime
не приводит к появлению TypeError
.
Изменено в версии 3.13: Сравнение объекта datetime
с экземпляром подкласса date
, который не является подклассом datetime
, больше не преобразует последний в 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 из aware datetime без преобразования данных даты и времени.Объекты
datetime
также поддерживаются родовой функциейcopy.replace()
.Изменено в версии 3.6: Добавлен параметр fold.
- datetime.astimezone(tz=None)¶
Возвращает объект
datetime
с новым атрибутомtzinfo
tz, корректируя данные о дате и времени так, чтобы в результате получилось то же время UTC, что и у self, но в местном времени tz.Если указано, то tz должен быть экземпляром подкласса
tzinfo
, а его методыutcoffset()
иdst()
не должны возвращатьNone
. Если self является наивным, предполагается, что он представляет время в системном часовом поясе.При вызове без аргументов (или с
tz=None
) в качестве целевого часового пояса принимается локальный часовой пояс системы. Атрибут.tzinfo
преобразованного экземпляра datetime будет установлен в экземплярtimezone
с именем и смещением зоны, полученными из ОС.Если
self.tzinfo
равен tz, тоself.astimezone(tz)
равен self: корректировка данных даты и времени не производится. В противном случае результатом будет местное время в часовом поясе tz, представляющее собой то же время UTC, что и self: послеastz = dt.astimezone(tz)
,astz - astz.utcoffset()
будет иметь те же данные даты и времени, что иdt - dt.utcoffset()
.Если вы хотите просто присоединить объект часового пояса tz к datetime dt без преобразования данных о дате и времени, используйте
dt.replace(tzinfo=tz)
. Если вы хотите просто удалить объект часового пояса из известного datetime dt без преобразования данных даты и времени, используйтеdt.replace(tzinfo=None)
.Обратите внимание, что метод по умолчанию
tzinfo.fromutc()
может быть переопределен в подклассеtzinfo
, чтобы повлиять на результат, возвращаемыйastimezone()
. Если не учитывать случаи ошибок,astimezone()
действует следующим образом:def astimezone(self, tz): if self.tzinfo is tz: return self # Convert self to UTC, and attach the new time zone object. utc = (self - self.utcoffset()).replace(tzinfo=tz) # Convert from UTC to tz's local time. return tz.fromutc(utc)
Изменено в версии 3.3: Теперь tz можно опустить.
Изменено в версии 3.6: Теперь метод
astimezone()
можно вызывать на наивных экземплярах, которые, как предполагается, представляют системное локальное время.
- datetime.utcoffset()¶
Если
tzinfo
являетсяNone
, возвращаетNone
, иначе возвращаетself.tzinfo.utcoffset(self)
, и вызывает исключение, если не возвращаетNone
или объектtimedelta
с величиной меньше одного дня.Изменено в версии 3.7: Смещение UTC не ограничивается целым числом минут.
- datetime.dst()¶
Если
tzinfo
являетсяNone
, возвращаетNone
, иначе возвращаетself.tzinfo.dst(self)
, и вызывает исключение, если не возвращаетNone
или объектtimedelta
с величиной меньше одного дня.Изменено в версии 3.7: Смещение DST не ограничивается целым числом минут.
- datetime.tzname()¶
Если
tzinfo
равноNone
, возвращаетNone
, иначе возвращаетself.tzinfo.tzname(self)
, вызывает исключение, если не возвращаетNone
или строковый объект,
- datetime.timetuple()¶
Возвращает
time.struct_time
, подобный тому, что возвращаетtime.localtime()
.d.timetuple()
эквивалентно:time.struct_time((d.year, d.month, d.day, d.hour, d.minute, d.second, d.weekday(), yday, dst))
где
yday = d.toordinal() - date(d.year, 1, 1).toordinal() + 1
- номер дня в текущем году, начиная с 1 для 1 января. Флагtm_isdst
результата устанавливается в соответствии с методомdst()
:tzinfo
-None
илиdst()
возвращаетNone
,tm_isdst
устанавливается в-1
; еслиdst()
возвращает ненулевое значение,tm_isdst
устанавливается в 1; иначеtm_isdst
устанавливается в 0.
- datetime.utctimetuple()¶
Если
datetime
экземпляра d наивен, это то же самое, что иd.timetuple()
, за исключением того, чтоtm_isdst
принудительно устанавливается в 0 независимо от того, что возвращаетd.dst()
. Для времени UTC никогда не действует DST.Если d известно, то d нормализуется к времени UTC путем вычитания
d.utcoffset()
, и возвращаетсяtime.struct_time
для нормализованного времени.tm_isdst
принудительно равняется 0. Обратите внимание, что может возникнуть ошибкаOverflowError
, еслиd.year
былMINYEAR
илиMAXYEAR
и корректировка UTC выходит за границу года.Предупреждение
Поскольку наивные объекты
datetime
рассматриваются многими методамиdatetime
как местное время, предпочтительнее использовать aware datetimes для представления времени в UTC; в результате использованиеdatetime.utctimetuple()
может дать неверные результаты. Если у вас есть наивныйdatetime
, представляющий UTC, используйтеdatetime.replace(tzinfo=timezone.utc)
, чтобы сделать его осведомленным, после чего вы можете использоватьdatetime.timetuple()
.
- datetime.toordinal()¶
Возвращает пролептический григорианский ординал даты. То же, что и
self.date().toordinal()
.
- datetime.timestamp()¶
Возвращает временную метку POSIX, соответствующую экземпляру
datetime
. Возвращаемое значение -float
, аналогичное возвращаемомуtime.time()
.Предполагается, что наивные экземпляры
datetime
представляют местное время, и этот метод полагается на функциюmktime()
платформы C для выполнения преобразования. Посколькуdatetime
поддерживает более широкий диапазон значений, чемmktime()
на многих платформах, этот метод может вызыватьOverflowError
илиOSError
для времени, находящегося далеко в прошлом или в будущем.Для экземпляров, знающих
datetime
, возвращаемое значение вычисляется как:(dt - datetime(1970, 1, 1, tzinfo=timezone.utc)).total_seconds()
Added in version 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()¶
Возвращает named tuple с тремя компонентами:
year
,week
иweekday
. То же самое, что иself.date().isocalendar()
.
- datetime.isoformat(sep='T', timespec='auto')¶
Возвращает строку, представляющую дату и время в формате ISO 8601:
YYYY-MM-DDTHH:MM:SS.ffffff
, еслиmicrosecond
не 0YYYY-MM-DDTHH:MM:SS
, еслиmicrosecond
равен 0
Если
utcoffset()
не возвращаетNone
, добавляется строка, указывающая смещение UTC:YYYY-MM-DDTHH:MM:SS.ffffff+HH:MM[:SS[.ffffff]]
, еслиmicrosecond
не 0YYYY-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): ... """A time zone with an arbitrary, constant -06:39 offset.""" ... 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
.'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.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()))
на платформах, где родная функция C
ctime()
(которую вызываетtime.ctime()
, но которую не вызываетdatetime.ctime()
) соответствует стандарту C.
- datetime.strftime(format)¶
Возвращает строку, представляющую дату и время, управляемую явной строкой формата. См. также strftime() и strptime() Поведение и
datetime.isoformat()
.
- datetime.__format__(format)¶
Аналогично
datetime.strftime()
. Это позволяет задать строку формата для объектаdatetime
в formatted string literals и при использованииstr.format()
. См. также strftime() и strptime() Поведение иdatetime.isoformat()
.
Примеры использования: datetime
¶
Примеры работы с объектами datetime
:
>>> from datetime import datetime, date, time, timezone
>>> # Using datetime.combine()
>>> d = date(2005, 7, 14)
>>> t = time(12, 30)
>>> datetime.combine(d, t)
datetime.datetime(2005, 7, 14, 12, 30)
>>> # Using datetime.now()
>>> 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)
>>> # Using datetime.strptime()
>>> dt = datetime.strptime("21/11/06 16:30", "%d/%m/%y %H:%M")
>>> dt
datetime.datetime(2006, 11, 21, 16, 30)
>>> # Using datetime.timetuple() to get tuple of all attributes
>>> tt = dt.timetuple()
>>> for it in tt:
... print(it)
...
2006 # year
11 # month
21 # day
16 # hour
30 # minute
0 # second
1 # weekday (0 = Monday)
325 # number of days since 1st January
-1 # dst - method tzinfo.dst() returned None
>>> # Date in ISO format
>>> ic = dt.isocalendar()
>>> for it in ic:
... print(it)
...
2006 # ISO year
47 # ISO week
2 # ISO weekday
>>> # Formatting a 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.'
В приведенном ниже примере определен подкласс tzinfo
, содержащий информацию о часовом поясе для Кабула, Афганистан, где до 1945 года использовалось +4 UTC, а затем +4:30 UTC:
from datetime import timedelta, datetime, tzinfo, timezone
class KabulTz(tzinfo):
# Kabul used +4 until 1945, when they moved to +4:30
UTC_MOVE_DATE = datetime(1944, 12, 31, 20, tzinfo=timezone.utc)
def utcoffset(self, dt):
if dt.year < 1945:
return timedelta(hours=4)
elif (1945, 1, 1, 0, 0) <= dt.timetuple()[:5] < (1945, 1, 1, 0, 30):
# An ambiguous ("imaginary") half-hour range representing
# a 'fold' in time due to the shift from +4 to +4:30.
# If dt falls in the imaginary range, use fold to decide how
# to resolve. See PEP495.
return timedelta(hours=4, minutes=(30 if dt.fold else 0))
else:
return timedelta(hours=4, minutes=30)
def fromutc(self, dt):
# Follow same validations as in datetime.tzinfo
if not isinstance(dt, datetime):
raise TypeError("fromutc() requires a datetime argument")
if dt.tzinfo is not self:
raise ValueError("dt.tzinfo is not self")
# A custom implementation is required for fromutc as
# the input to this function is a datetime with utc values
# but with a tzinfo set to self.
# See datetime.astimezone or fromtimestamp.
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):
# Kabul does not observe daylight saving time.
return timedelta(0)
def tzname(self, dt):
if dt >= self.UTC_MOVE_DATE:
return "+04:30"
return "+04"
Использование KabulTz
сверху:
>>> tz1 = KabulTz()
>>> # Datetime before the change
>>> dt1 = datetime(1900, 11, 21, 16, 30, tzinfo=tz1)
>>> print(dt1.utcoffset())
4:00:00
>>> # Datetime after the change
>>> dt2 = datetime(2006, 6, 14, 13, 0, tzinfo=tz1)
>>> print(dt2.utcoffset())
4:30:00
>>> # Convert datetime to another time zone
>>> dt3 = dt2.astimezone(timezone.utc)
>>> dt3
datetime.datetime(2006, 6, 14, 8, 30, tzinfo=datetime.timezone.utc)
>>> dt2
datetime.datetime(2006, 6, 14, 13, 0, tzinfo=KabulTz())
>>> dt2 == 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.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 означают, соответственно, более ранний и более поздний из двух моментов с одинаковым представлением стенного времени.Added in version 3.6.
Объекты time
поддерживают сравнение равенства и порядка, при котором a считается меньше b, если a предшествует b по времени.
Наивные и осведомленные time
объекты никогда не равны. Сравнение порядка между наивными и осведомленными time
объектами приводит к возникновению TypeError
.
Если оба компарада осведомлены и имеют одинаковый атрибут tzinfo
, атрибуты tzinfo
и fold
игнорируются, и сравниваются базовые времена. Если оба компарада осведомлены и имеют разные атрибуты tzinfo
, компарады сначала корректируются путем вычитания их смещений UTC (полученных из self.utcoffset()
).
Изменено в версии 3.3: Сравнение равенств между знающими и наивными экземплярами time
не приводит к появлению TypeError
.
В булевых контекстах объект time
всегда считается истинным.
Изменено в версии 3.5: До Python 3.5 объект time
считался ложным, если он представлял полночь по Гринвичу. Такое поведение считалось неясным и чреватым ошибками и было удалено в Python 3.5. Подробную информацию см. в разделе bpo-13936.
Другой конструктор:
- classmethod time.fromisoformat(time_string)¶
Возвращает
time
, соответствующий временной_строке в любом допустимом формате ISO 8601, за следующими исключениями:Смещение часового пояса может иметь дробные секунды.
Ведущий
T
, который обычно требуется в случаях, когда может возникнуть двусмысленность между датой и временем, не нужен.Дробные секунды могут содержать любое количество цифр (все, что больше 6, будет усечено).
Дробные часы и минуты не поддерживаются.
Примеры:
>>> from datetime import time >>> time.fromisoformat('04:23:01') datetime.time(4, 23, 1) >>> time.fromisoformat('T04:23:01') datetime.time(4, 23, 1) >>> time.fromisoformat('T042301') datetime.time(4, 23, 1) >>> time.fromisoformat('04:23:01.000384') datetime.time(4, 23, 1, 384) >>> 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))) >>> time.fromisoformat('04:23:01Z') datetime.time(4, 23, 1, tzinfo=datetime.timezone.utc) >>> time.fromisoformat('04:23:01+00:00') datetime.time(4, 23, 1, tzinfo=datetime.timezone.utc)
Added in version 3.7.
Изменено в версии 3.11: Ранее этот метод поддерживал только форматы, которые могли быть испущены
time.isoformat()
.
Методы экземпляра:
- time.replace(hour=self.hour, minute=self.minute, second=self.second, microsecond=self.microsecond, tzinfo=self.tzinfo, *, fold=0)¶
Возвращает
time
с тем же значением, за исключением тех атрибутов, которые получили новые значения в зависимости от того, какие аргументы ключевого слова указаны. Обратите внимание, чтоtzinfo=None
может быть указан для создания наивногоtime
из известногоtime
без преобразования данных о времени.Объекты
time
также поддерживаются родовой функциейcopy.replace()
.Изменено в версии 3.6: Добавлен параметр fold.
- time.isoformat(timespec='auto')¶
Возвращает строку, представляющую время в формате ISO 8601, одно из значений:
HH:MM:SS.ffffff
, еслиmicrosecond
не 0HH:MM:SS
, еслиmicrosecond
равен 0HH: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
.'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.isoformat()
.
- time.__format__(format)¶
Аналогично
time.strftime()
. Это позволяет задать строку формата для объектаtime
в formatted string literals и при использованииstr.format()
. См. также strftime() и strptime() Поведение иtime.isoformat()
.
- time.utcoffset()¶
Если
tzinfo
являетсяNone
, возвращаетNone
, иначе возвращаетself.tzinfo.utcoffset(None)
, и вызывает исключение, если не возвращаетNone
или объектtimedelta
с величиной меньше одного дня.Изменено в версии 3.7: Смещение UTC не ограничивается целым числом минут.
- time.dst()¶
Если
tzinfo
являетсяNone
, возвращаетNone
, иначе возвращаетself.tzinfo.dst(None)
, и вызывает исключение, если не возвращаетNone
, или объектtimedelta
с величиной меньше одного дня.Изменено в версии 3.7: Смещение DST не ограничивается целым числом минут.
- time.tzname()¶
Если
tzinfo
равноNone
, возвращаетNone
, иначе возвращаетself.tzinfo.tzname(None)
, или вызывает исключение, если не возвращаетNone
или строковый объект.
Примеры использования: 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.Особое требование для маринования: Подкласс
tzinfo
должен иметь метод__init__()
, который может быть вызван без аргументов, иначе он может быть замаринован, но, возможно, не может быть замаринован снова. Это техническое требование, которое может быть смягчено в будущем.Конкретному подклассу
tzinfo
может потребоваться реализация следующих методов. То, какие именно методы необходимы, зависит от того, как будут использоваться объекты awaredatetime
. Если вы сомневаетесь, просто реализуйте их все.
- tzinfo.utcoffset(dt)¶
Возвращает смещение местного времени относительно UTC в виде объекта
timedelta
, который является положительным к востоку от UTC. Если местное время находится к западу от UTC, это значение должно быть отрицательным.Это значение представляет собой общее смещение относительно UTC; например, если объект
tzinfo
представляет корректировки часового пояса и DST,utcoffset()
должен возвращать их сумму. Если смещение UTC неизвестно, вернитеNone
. В противном случае возвращаемое значение должно быть объектомtimedelta
строго между-timedelta(hours=24)
иtimedelta(hours=24)
(величина смещения должна быть меньше одного дня). Большинство реализацийutcoffset()
, вероятно, будут выглядеть как одна из этих двух:return CONSTANT # fixed-offset class return CONSTANT + self.dst(dt) # daylight-aware class
Если
utcoffset()
не возвращаетNone
, тоdst()
тоже не должен возвращатьNone
.Реализация по умолчанию
utcoffset()
поднимаетNotImplementedError
.Изменено в версии 3.7: Смещение UTC не ограничивается целым числом минут.
- tzinfo.dst(dt)¶
Возвращает корректировку перехода на летнее время (DST) в виде объекта
timedelta
илиNone
, если информация о DST неизвестна.Верните
timedelta(0)
, если DST не действует. Если DST действует, верните смещение как объектtimedelta
(подробности см. вutcoffset()
). Обратите внимание, что смещение DST, если оно применимо, уже добавлено к смещению UTC, возвращаемомуutcoffset()
, поэтому нет необходимости обращаться кdst()
, если вы не заинтересованы в получении информации о DST отдельно. Например,datetime.timetuple()
вызывает методdst()
своего атрибутаtzinfo
, чтобы определить, как должен быть установлен флагtm_isdst
, аtzinfo.fromutc()
вызываетdst()
, чтобы учесть изменения DST при пересечении часовых поясов.Экземпляр tz подкласса
tzinfo
, который моделирует как стандартное, так и дневное время, должен быть последовательным в этом смысле:tz.utcoffset(dt) - tz.dst(dt)
должен возвращать один и тот же результат для каждого
datetime
dt сdt.tzinfo == tz
. Для вменяемых подклассовtzinfo
это выражение дает «стандартное смещение» часового пояса, которое не должно зависеть от даты или времени, а только от географического положения. Реализацияdatetime.astimezone()
полагается на это, но не может обнаружить нарушения; ответственность за это лежит на программисте. Если подклассtzinfo
не может гарантировать этого, он может переопределить реализацию по умолчаниюtzinfo.fromutc()
, чтобы корректно работать сastimezone()
независимо от этого.Большинство реализаций
dst()
, вероятно, будут выглядеть как одна из этих двух:def dst(self, dt): # a fixed-offset class: doesn't account for DST return timedelta(0)
или:
def dst(self, dt): # Code to set dston and dstoff to the time zone's DST # transition times based on the input dt.year, and expressed # in standard local time. if dston <= dt.replace(tzinfo=None) < dstoff: return timedelta(hours=1) else: return timedelta(0)
Реализация по умолчанию
dst()
поднимаетNotImplementedError
.Изменено в версии 3.7: Смещение DST не ограничивается целым числом минут.
- tzinfo.tzname(dt)¶
Возвращает имя часового пояса, соответствующее объекту
datetime
dt, в виде строки. Модульdatetime
ничего не определяет об именах строк, и нет никаких требований, чтобы они означали что-то конкретное. Например,"GMT"
,"UTC"
,"-500"
,"-5:00"
,"EDT"
,"US/Eastern"
,"America/New York"
- все это допустимые ответы. ВернитеNone
, если имя строки неизвестно. Обратите внимание, что это метод, а не фиксированная строка, прежде всего потому, что некоторые подклассыtzinfo
захотят возвращать разные имена в зависимости от конкретного переданного значения dt, особенно если классtzinfo
учитывает летнее время.Реализация по умолчанию
tzname()
поднимаетNotImplementedError
.
Эти методы вызываются объектом datetime
или time
в ответ на их одноименные методы. Объект datetime
передает себя в качестве аргумента, а объект time
передает None
в качестве аргумента. Поэтому методы подкласса tzinfo
должны быть готовы принять аргумент dt из None
или класса datetime
.
Если передается None
, разработчик класса сам решает, как лучше поступить. Например, возврат None
уместен, если класс хочет сказать, что объекты времени не участвуют в протоколах tzinfo
. Для utcoffset(None)
может быть более полезным возвращать стандартное смещение UTC, поскольку не существует другой конвенции для определения стандартного смещения.
Когда объект datetime
передается в ответ на метод datetime
, dt.tzinfo
- это тот же объект, что и self. Методы tzinfo
могут полагаться на это, если только пользовательский код не вызывает методы tzinfo
напрямую. Цель состоит в том, чтобы методы tzinfo
интерпретировали dt как местное время и не беспокоились об объектах в других часовых поясах.
Существует еще один метод tzinfo
, который подкласс может захотеть переопределить:
- tzinfo.fromutc(dt)¶
Эта функция вызывается из стандартной реализации
datetime.astimezone()
. При вызове из нееdt.tzinfo
- это self, а данные даты и времени dt должны рассматриваться как выражающие время UTC. Цельfromutc()
- скорректировать данные даты и времени, вернув эквивалентное время в локальном времени self.Большинство подклассов
tzinfo
смогут без проблем наследовать реализациюfromutc()
по умолчанию. Она достаточно сильна, чтобы обрабатывать часовые пояса с фиксированным смещением, а также часовые пояса, учитывающие как стандартное, так и летнее время, причем последнее даже в том случае, если время перехода на DST отличается в разные годы. Примером часового пояса, с которым реализацияfromutc()
по умолчанию может работать не во всех случаях, является тот, в котором стандартное смещение (от UTC) зависит от конкретной прошедшей даты и времени, что может происходить по политическим причинам. Реализацииastimezone()
иfromutc()
по умолчанию могут не дать желаемого результата, если результат - один из часов, совпадающих с моментом изменения стандартного смещения.Пропуская код для случаев ошибок, реализация
fromutc()
по умолчанию действует следующим образом:def fromutc(self, dt): # raise ValueError error if dt.tzinfo is not self dtoff = dt.utcoffset() dtdst = dt.dst() # raise ValueError if dtoff is None or dtdst is None delta = dtoff - dtdst # this is self's standard offset if delta: dt += delta # convert to standard local time dtdst = dt.dst() # raise ValueError if dtdst is None if dtdst: return dt + dtdst else: return dt
В следующем файле tzinfo_examples.py
приведено несколько примеров классов tzinfo
:
from datetime import tzinfo, timedelta, datetime
ZERO = timedelta(0)
HOUR = timedelta(hours=1)
SECOND = timedelta(seconds=1)
# A class capturing the platform's idea of local time.
# (May result in wrong values on historical times in
# timezones where UTC offset and/or the DST rules had
# changed in the past.)
import time as _time
STDOFFSET = timedelta(seconds = -_time.timezone)
if _time.daylight:
DSTOFFSET = timedelta(seconds = -_time.altzone)
else:
DSTOFFSET = STDOFFSET
DSTDIFF = DSTOFFSET - STDOFFSET
class LocalTimezone(tzinfo):
def fromutc(self, dt):
assert dt.tzinfo is self
stamp = (dt - datetime(1970, 1, 1, tzinfo=self)) // SECOND
args = _time.localtime(stamp)[:6]
dst_diff = DSTDIFF // SECOND
# Detect fold
fold = (args == _time.localtime(stamp - dst_diff))
return datetime(*args, microsecond=dt.microsecond,
tzinfo=self, fold=fold)
def utcoffset(self, dt):
if self._isdst(dt):
return DSTOFFSET
else:
return STDOFFSET
def dst(self, dt):
if self._isdst(dt):
return DSTDIFF
else:
return ZERO
def tzname(self, dt):
return _time.tzname[self._isdst(dt)]
def _isdst(self, dt):
tt = (dt.year, dt.month, dt.day,
dt.hour, dt.minute, dt.second,
dt.weekday(), 0, 0)
stamp = _time.mktime(tt)
tt = _time.localtime(stamp)
return tt.tm_isdst > 0
Local = LocalTimezone()
# A complete implementation of current DST rules for major US time zones.
def first_sunday_on_or_after(dt):
days_to_go = 6 - dt.weekday()
if days_to_go:
dt += timedelta(days_to_go)
return dt
# US DST Rules
#
# This is a simplified (i.e., wrong for a few cases) set of rules for US
# DST start and end times. For a complete and up-to-date set of DST rules
# and timezone definitions, visit the Olson Database (or try pytz):
# http://www.twinsun.com/tz/tz-link.htm
# https://sourceforge.net/projects/pytz/ (might not be up-to-date)
#
# In the US, since 2007, DST starts at 2am (standard time) on the second
# Sunday in March, which is the first Sunday on or after Mar 8.
DSTSTART_2007 = datetime(1, 3, 8, 2)
# and ends at 2am (DST time) on the first Sunday of Nov.
DSTEND_2007 = datetime(1, 11, 1, 2)
# From 1987 to 2006, DST used to start at 2am (standard time) on the first
# Sunday in April and to end at 2am (DST time) on the last
# Sunday of October, which is the first Sunday on or after Oct 25.
DSTSTART_1987_2006 = datetime(1, 4, 1, 2)
DSTEND_1987_2006 = datetime(1, 10, 25, 2)
# From 1967 to 1986, DST used to start at 2am (standard time) on the last
# Sunday in April (the one on or after April 24) and to end at 2am (DST time)
# on the last Sunday of October, which is the first Sunday
# on or after Oct 25.
DSTSTART_1967_1986 = datetime(1, 4, 24, 2)
DSTEND_1967_1986 = DSTEND_1987_2006
def us_dst_range(year):
# Find start and end times for US DST. For years before 1967, return
# start = end for no DST.
if 2006 < year:
dststart, dstend = DSTSTART_2007, DSTEND_2007
elif 1986 < year < 2007:
dststart, dstend = DSTSTART_1987_2006, DSTEND_1987_2006
elif 1966 < year < 1987:
dststart, dstend = DSTSTART_1967_1986, DSTEND_1967_1986
else:
return (datetime(year, 1, 1), ) * 2
start = first_sunday_on_or_after(dststart.replace(year=year))
end = first_sunday_on_or_after(dstend.replace(year=year))
return start, end
class USTimeZone(tzinfo):
def __init__(self, hours, reprname, stdname, dstname):
self.stdoffset = timedelta(hours=hours)
self.reprname = reprname
self.stdname = stdname
self.dstname = dstname
def __repr__(self):
return self.reprname
def tzname(self, dt):
if self.dst(dt):
return self.dstname
else:
return self.stdname
def utcoffset(self, dt):
return self.stdoffset + self.dst(dt)
def dst(self, dt):
if dt is None or dt.tzinfo is None:
# An exception may be sensible here, in one or both cases.
# It depends on how you want to treat them. The default
# fromutc() implementation (called by the default astimezone()
# implementation) passes a datetime with dt.tzinfo is self.
return ZERO
assert dt.tzinfo is self
start, end = us_dst_range(dt.year)
# Can't compare naive to aware objects, so strip the timezone from
# dt first.
dt = dt.replace(tzinfo=None)
if start + HOUR <= dt < end - HOUR:
# DST is in effect.
return HOUR
if end - HOUR <= dt < end:
# Fold (an ambiguous hour): use dt.fold to disambiguate.
return ZERO if dt.fold else HOUR
if start <= dt < start + HOUR:
# Gap (a non-existent hour): reverse the fold rule.
return HOUR if dt.fold else ZERO
# DST is off.
return ZERO
def fromutc(self, dt):
assert dt.tzinfo is self
start, end = us_dst_range(dt.year)
start = start.replace(tzinfo=self)
end = end.replace(tzinfo=self)
std_time = dt + self.stdoffset
dst_time = std_time + HOUR
if end <= dst_time < end + HOUR:
# Repeated hour
return std_time.replace(fold=1)
if std_time < start or dst_time >= end:
# Standard time
return std_time
if start <= std_time < end - HOUR:
# Daylight saving time
return dst_time
Eastern = USTimeZone(-5, "Eastern", "EST", "EDT")
Central = USTimeZone(-6, "Central", "CST", "CDT")
Mountain = USTimeZone(-7, "Mountain", "MST", "MDT")
Pacific = USTimeZone(-8, "Pacific", "PST", "PDT")
Обратите внимание, что в подклассе tzinfo
, учитывающем как стандартное, так и летнее время, дважды в год возникают неизбежные тонкости в точках перехода на DST. Для конкретности рассмотрим восточное время США (UTC -0500), где EDT начинается через минуту после 1:59 (EST) во второе воскресенье марта и заканчивается через минуту после 1:59 (EDT) в первое воскресенье ноября:
UTC 3:MM 4:MM 5:MM 6:MM 7:MM 8:MM
EST 22:MM 23:MM 0:MM 1:MM 2:MM 3:MM
EDT 23:MM 0:MM 1:MM 2:MM 3:MM 4:MM
start 22:MM 23:MM 0:MM 1:MM 3:MM 4:MM
end 23:MM 0:MM 1:MM 1:MM 2:MM 3:MM
Когда начинается DST (линия «начало»), местные настенные часы переходят с 1:59 на 3:00. Настенное время в виде 2:ММ не имеет смысла в этот день, поэтому 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 заканчивается (линия «end»), возникает потенциально более серьезная проблема: появляется час, который нельзя однозначно написать в местном поясном времени: последний час дневного времени. В Восточном регионе это время вида 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 часа)) двусмысленности не возникает.
См.также
zoneinfo
Модуль
datetime
имеет базовый классtimezone
(для работы с произвольными фиксированными смещениями от UTC) и его атрибутtimezone.utc
(экземпляр часового пояса UTC).
zoneinfo
привносит базу данных часовых поясов IANA (также известную как база данных Olson) в Python, и ее использование рекомендуется.
- IANA timezone database
База данных часовых поясов (часто называемая 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()
.Added in version 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 должен быть экземпляром awaredatetime
, аtzinfo
установлен наself
.
Атрибуты класса:
- timezone.utc¶
Часовой пояс UTC,
timezone(timedelta(0))
.
strftime()
и strptime()
Поведение¶
Объекты date
, datetime
и time
поддерживают метод strftime(format)
для создания строки, представляющей время под управлением явной строки формата.
И наоборот, метод класса datetime.strptime()
создает объект datetime
из строки, представляющей дату и время, и соответствующей строки формата.
В таблице ниже представлено высокоуровневое сравнение strftime()
и strptime()
:
|
|
|
---|---|---|
Использование |
Преобразование объекта в строку в соответствии с заданным форматом |
Разбор строки в объект |
Тип метода |
Метод экземпляра |
Метод класса |
Метод |
||
Подпись |
|
|
strftime()
и strptime()
Коды формата¶
Эти методы принимают коды формата, которые можно использовать для разбора и форматирования дат:
>>> datetime.strptime('31/01/22 23:59:59.999999',
... '%d/%m/%y %H:%M:%S.%f')
datetime.datetime(2022, 1, 31, 23, 59, 59, 999999)
>>> _.strftime('%a %d %b %Y, %I:%M%p')
'Mon 31 Jan 2022, 11:59PM'
Ниже приведен список всех форматных кодов, которые требует стандарт C 1989 года, и они работают на всех платформах со стандартной реализацией C.
Директива |
Значение |
Пример |
Примечания |
---|---|---|---|
|
Будний день в виде сокращенного названия локали. |
Sun, Mon, …, Sat
(en_US);
So, Mo, …, Sa
(de_DE)
|
(1) |
|
Weekday в качестве полного имени локали. |
Воскресенье, понедельник, …, суббота (en_US);
Sonntag, Montag, …,
Samstag (de_DE)
|
(1) |
|
День недели в виде десятичного числа, где 0 - воскресенье, а 6 - суббота. |
0, 1, …, 6 |
|
|
День месяца в виде десятичного числа с нулевой добавкой. |
01, 02, …, 31 |
(9) |
|
Месяц как сокращенное название локали. |
Январь, февраль, …, декабрь (en_US);
Jan, Feb, …, Dez
(de_DE)
|
(1) |
|
Месяц как полное имя локали. |
Январь, февраль, …, декабрь (en_US);
Январь, февраль, …, декабрь (de_DE)
|
(1) |
|
Месяц в виде десятичного числа с нулевой добавкой. |
01, 02, …, 12 |
(9) |
|
Год без века в виде десятичного числа с нулевой добавкой. |
00, 01, …, 99 |
(9) |
|
Год с веком в виде десятичного числа. |
0001, 0002, …, 2013, 2014, …, 9998, 9999 |
(2) |
|
Час (24-часовые часы) в виде десятичного числа с нулевой добавкой. |
00, 01, …, 23 |
(9) |
|
Час (12-часовые часы) в виде десятичного числа с нулевой добавкой. |
01, 02, …, 12 |
(9) |
|
Эквивалент AM или PM в локали. |
AM, PM (en_US);
утро, вечер (de_DE)
|
(1), (3) |
|
Минута в виде десятичного числа с нулевой добавкой. |
00, 01, …, 59 |
(9) |
|
Второе в виде десятичного числа с нулевой добавкой. |
00, 01, …, 59 |
(4), (9) |
|
Микросекунда в виде десятичного числа с нулевым добавлением до 6 цифр. |
000000, 000001, …, 999999 |
(5) |
|
Смещение UTC в виде |
(пусто), +0000, -0400, +1030, +063415, -030712.345216 |
(6) |
|
Имя часового пояса (пустая строка, если объект является наивным). |
(пусто), UTC, GMT |
(6) |
|
День года в виде десятичного числа с нулевой добавкой. |
001, 002, …, 366 |
(9) |
|
Номер недели года (воскресенье - первый день недели) в виде десятичного числа с нулевой добавкой. Все дни в новом году, предшествующие первому воскресенью, считаются неделей 0. |
00, 01, …, 53 |
(7), (9) |
|
Номер недели в году (понедельник - первый день недели) в виде десятичного числа с нулевой добавкой. Все дни в новом году, предшествующие первому понедельнику, считаются неделей 0. |
00, 01, …, 53 |
(7), (9) |
|
Соответствующее представление даты и времени в локали. |
Tue Aug 16 21:30:00
1988 (en_US);
Di 16 Aug 21:30:00
1988 (de_DE)
|
(1) |
|
Соответствующее представление даты в локали. |
08/16/88 (Нет);
08/16/1988 (en_US);
16.08.1988 (de_DE)
|
(1) |
|
Соответствующее представление времени в локали. |
21:30:00 (en_US);
21:30:00 (de_DE)
|
(1) |
|
Буквальный символ |
% |
Для удобства включены несколько дополнительных директив, не требуемых стандартом C89. Все эти параметры соответствуют значениям даты ISO 8601.
Директива |
Значение |
Пример |
Примечания |
---|---|---|---|
|
Год ISO 8601 с веком, представляющий год, который содержит большую часть недели ISO ( |
0001, 0002, …, 2013, 2014, …, 9998, 9999 |
(8) |
|
День недели по стандарту ISO 8601 в виде десятичного числа, где 1 - понедельник. |
1, 2, …, 7 |
|
|
Неделя в стандарте ISO 8601 - десятичное число с понедельником в качестве первого дня недели. Неделя 01 - это неделя, содержащая 4 января. |
01, 02, …, 53 |
(8), (9) |
|
Смещение UTC в виде |
(пусто), +00:00, -04:00, +10:30, +06:34:15, -03:07:12.345216 |
(6) |
Они могут быть доступны не на всех платформах при использовании метода strftime()
. Директивы ISO 8601 year и ISO 8601 week не являются взаимозаменяемыми с вышеуказанными директивами year и week number. Вызов strptime()
с неполными или неоднозначными директивами ISO 8601 приведет к ошибке ValueError
.
Полный набор поддерживаемых форматных кодов различается на разных платформах, поскольку Python вызывает функцию strftime()
библиотеки Platform C, и различия между платформами обычны. Чтобы узнать полный набор кодов форматов, поддерживаемых на вашей платформе, обратитесь к документации strftime(3). Также платформы различаются по обработке неподдерживаемых спецификаторов формата.
Added in version 3.6: Были добавлены %G
, %u
и %V
.
Added in version 3.12: %:z
был добавлен.
Технические детали¶
В общем случае 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.
По этой же причине обработка строк формата, содержащих кодовые точки Unicode, которые не могут быть представлены в кодировке текущей локали, также зависит от платформы. На некоторых платформах такие кодовые точки сохраняются в выводе, а на других strftime
может вызвать UnicodeError
или вернуть пустую строку.
Примечания:
Поскольку формат зависит от текущей локали, следует быть осторожным, делая предположения о выходном значении. Порядок полей будет отличаться (например, «месяц/день/год» от «день/месяц/год»), а выходные данные могут содержать символы, отличные от ASCII.
Метод
strptime()
может обрабатывать годы в полном диапазоне [1, 9999], но годы < 1000 должны быть заполнены нулями до 4-значной ширины.Изменено в версии 3.2: В предыдущих версиях метод
strftime()
был ограничен годами >= 1900.Изменено в версии 3.3: В версии 3.2 метод
strftime()
был ограничен годами >= 1000.При использовании метода
strptime()
директива%p
влияет на выходное поле часа только в том случае, если для разбора часа используется директива%I
.В отличие от модуля
time
, модульdatetime
не поддерживает високосные секунды.При использовании с методом
strptime()
директива%f
принимает от одной до шести цифр и нулевые прокладки справа.%f
- это расширение набора символов формата, предусмотренного стандартом C (но реализованного отдельно в объектах datetime и поэтому всегда доступного).Для наивного объекта коды формата
%z
,%:z
и%Z
заменяются пустыми строками.Для осознанного объекта:
%z
utcoffset()
преобразуется в строку вида±HHMM[SS[.ffffff]]
, гдеHH
- двузначная строка, указывающая количество часов со смещением UTC,MM
- двузначная строка, указывающая количество минут со смещением UTC,SS
- двузначная строка, указывающая количество секунд со смещением UTC, иffffff
- шестизначная строка, указывающая количество микросекунд со смещением UTC. Частьffffff
опускается, если смещение составляет целое число секунд, и обе частиffffff
иSS
опускаются, если смещение составляет целое число минут. Например, еслиutcoffset()
возвращаетtimedelta(hours=-3, minutes=-30)
, то%z
заменяется строкой'-0330'
.
Изменено в версии 3.7: Смещение UTC не ограничивается целым числом минут.
Изменено в версии 3.7: Когда методу
strptime()
передается директива%z
, смещения UTC могут содержать двоеточие в качестве разделителя между часами, минутами и секундами. Например,'+01:00:00'
будет разобрано как смещение на один час. Кроме того, указание'Z'
идентично'+00:00'
.%:z
Ведет себя так же, как
%z
, но между часами, минутами и секундами добавляется разделитель в виде двоеточия.%Z
В
strftime()
%Z
заменяется пустой строкой, еслиtzname()
возвращаетNone
; в противном случае%Z
заменяется возвращаемым значением, которое должно быть строкой.strptime()
принимает только определенные значения для%Z
:любое значение в
time.tzname
для локали вашего компьютеражестко закодированные значения
UTC
иGMT
.
Так, у человека, живущего в Японии, допустимыми значениями могут быть
JST
,UTC
иGMT
, но, вероятно, неEST
. Для недопустимых значений будет выдано сообщениеValueError
.
Изменено в версии 3.2: Когда методу
strptime()
передается директива%z
, будет создан объектdatetime
с информацией. В качествеtzinfo
результата будет установлен экземплярtimezone
.При использовании метода
strptime()
,%U
и%W
используются в расчетах только в том случае, если указаны день недели и календарный год (%Y
).Как и
%U
и%W
,%V
используется в расчетах только в том случае, если день недели и год ISO (%G
) указаны в строке форматаstrptime()
. Также обратите внимание, что%G
и%Y
не являются взаимозаменяемыми.При использовании метода
strptime()
ведущий ноль необязателен для форматов%d
,%m
,%H
,%I
,%M
,%S
,%j
,%U
,%W
и%V
. Формат%y
требует ведущего нуля.При разборе месяца и дня с помощью
strptime()
всегда включайте год в формат. Если в значении, которое вам нужно разобрать, отсутствует год, добавьте явный фиктивный високосный год. В противном случае при столкновении с високосным днем ваш код будет вызывать исключение, поскольку год по умолчанию, используемый парсером, не является високосным. Пользователи сталкиваются с этой ошибкой каждые четыре года…>>> month_day = "02/29" >>> datetime.strptime(f"{month_day};1984", "%m/%d;%Y") # No leap year bug. datetime.datetime(1984, 2, 29, 0, 0)
Утратил актуальность с версии 3.13, будет удален в версии 3.15: Вызовы
strptime()
, использующие строку формата, содержащую день месяца без года, теперь выдаютDeprecationWarning
. В версии 3.15 или более поздней мы можем изменить это на ошибку или изменить год по умолчанию на високосный. См. gh-70647.
Сноски