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

Осознанные и наивные объекты¶

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

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

datetime.UTC¶

Псевдоним для синглтона часового пояса UTC datetime.timezone.utc.

Добавлено в версии 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.

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

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

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

object
    timedelta
    tzinfo
        timezone
    time
    date
        datetime

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

Следующий пример иллюстрирует, как любые аргументы, кроме дней, секунд и микросекунд, «объединяются» и нормализуются по этим трем результирующим атрибутам:

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

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

Если нормализованное значение дней выходит за пределы указанного диапазона, значение OverflowError повышается.

Обратите внимание, что нормализация отрицательных значений поначалу может вызвать удивление. Например:

>>> from datetime import timedelta
>>> d = timedelta(microseconds=-1)
>>> (d.days, d.seconds, d.microseconds)
(-1, 86399, 999999)

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

timedelta.min¶

Самый негативный timedelta объект, timedelta(-999999999).

timedelta.max¶

Самый позитивный timedelta объект, timedelta(days=999999999, hours=23, minutes=59, seconds=59, microseconds=999999).

timedelta.resolution¶

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

Обратите внимание, что из-за нормализации, timedelta.max > -timedelta.min. -timedelta.max не может быть представлен как объект timedelta.

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

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

Записи:

1. Это точно, но может привести к переполнению.

2. Это точно и не может привести к переполнению.

3. При делении на 0 получается ZeroDivisionError.

4. -timedelta.max не может быть представлен как объект timedelta.

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

   >>> timedelta(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 (см. ниже).

timedelta объекты поддерживают сравнение по равенству и порядку.

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

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

timedelta.total_seconds()¶

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

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

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

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

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

Изменено в версии 3.3: Поднимите значение OverflowError вместо ValueError, если временная метка выходит за пределы диапазона значений, поддерживаемых функцией платформы C localtime(). Поднимите значение OSError вместо ValueError при ошибке c:func: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, заданному в любом допустимом формате ISO 8601, за следующими исключениями:

1. Даты с пониженной точностью в настоящее время не поддерживаются (YYYY-MM, YYYY).

2. Расширенные представления данных в настоящее время не поддерживаются (±YYYYYY-MM-DD).

3. Порядковые даты в настоящее время не поддерживаются (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)

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

Изменено в версии 3.11: Ранее этот метод поддерживал только формат YYYY-MM-DD.

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 до количества дней в данном месяце данного года.

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

Записи:

1. дата 2 перемещается вперед по времени, если 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, а data2 + timedelta == дата через 1 секунду.

4. date объекты равны, если они представляют одну и ту же дату.

5. дата 1 считается меньшей, чем дата 2, тогда дата 1 предшествует дате 2 по времени. Другими словами, date1 < date2 тогда и только тогда, когда date1.toordinal() < date2.toordinal().

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

Возвращает объект 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().

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

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

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

• MINYEAR <= year <= MAXYEAR,

• 1 <= month <= 12,

• 1 <= day <= number of days in the given month and year,

• 0 <= hour < 24,

• 0 <= minute < 60,

• 0 <= second < 60,

• 0 <= microsecond < 1000000,

• fold in [0, 1].

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

Изменено в версии 3.6: Добавлен параметр fold.

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

classmethod datetime.today()¶

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

Эквивалентно:

datetime.fromtimestamp(time.time())

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

Этот метод функционально эквивалентен 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.now(timezone.utc). Смотрите также now().

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

Поскольку наивные объекты datetime обрабатываются многими методами datetime как местное время, предпочтительнее использовать осведомленные даты для представления времени в 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(), и тогда возможно иметь две временные метки, отличающиеся на секунду, которые дают идентичные объекты datetime. Этот метод предпочтительнее, чем utcfromtimestamp().

Изменено в версии 3.3: Поднимите значение OverflowError вместо ValueError, если временная метка выходит за пределы диапазона значений, поддерживаемых функциями платформы C localtime() или gmtime(). Поднимите OSError вместо ValueError при ошибке : c:func: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 как местное время, предпочтительнее использовать осведомленные даты для представления времени в UTC. Таким образом, рекомендуемый способ создания объекта, представляющего определенную временную метку в UTC, заключается в вызове datetime.fromtimestamp(timestamp, tz=timezone.utc).

Изменено в версии 3.3: Поднимите значение OverflowError вместо ValueError, если временная метка выходит за пределы диапазона значений, поддерживаемых функцией платформы C gmtime(). Поднимите значение OSError вместо ValueError при ошибке c:func: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, в любом допустимом формате ISO 8601, за следующими исключениями:

1. Смещение часовых поясов может составлять доли секунд.

2. Разделитель T может быть заменен любым отдельным символом юникода.

3. Дробные часы и минуты не поддерживаются.

4. Даты с пониженной точностью в настоящее время не поддерживаются (YYYY-MM, YYYY).

5. Расширенные представления данных в настоящее время не поддерживаются (±YYYYYY-MM-DD).

6. Порядковые даты в настоящее время не поддерживаются (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)))

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

Изменено в версии 3.11: Ранее этот метод поддерживал только форматы, которые могли быть заданы как date.isoformat() или datetime.isoformat().

classmethod datetime.fromisocalendar(year, week, day)¶

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

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

classmethod datetime.strptime(date_string, format)¶

Возвращает datetime, соответствующий date_string, проанализированный в соответствии с форматом.

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

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

ValueError вызывается, если date_string и format не могут быть проанализированы с помощью time.strptime() или если оно возвращает значение, которое не является временным кортежем. Смотрите также strftime() и strptime() Поведение и datetime.fromisoformat().

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

datetime.min¶

Самый ранний из представленных datetime, datetime(MINYEAR, 1, 1, tzinfo=None).

datetime.max¶

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

datetime.resolution¶

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

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

datetime.year¶

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

datetime.month¶

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

datetime.day¶

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

datetime.hour¶

В range(24).

datetime.minute¶

В range(60).

datetime.second¶

В range(60).

datetime.microsecond¶

В range(1000000).

datetime.tzinfo¶

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

datetime.fold¶

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

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

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

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

2. Вычисляет значение datetime2 таким образом, что значение datetime2 + timedelta == дата и время 1. Что касается добавления, то результат имеет тот же атрибут 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. datetime объекты равны, если они представляют одну и ту же дату и время с учетом часового пояса.

   Наивные и осознающие datetime объекты никогда не бывают равны. datetime объекты никогда не бывают равны date объектам, которые также не являются экземплярами datetime, даже если они представляют одну и ту же дату.

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

5. datetime1 считается меньшим, чем datetime2, если datetime1 предшествует datetime2 по времени, принимая во внимание часовой пояс.

   При сравнении порядка между наивными и осознанными объектами datetime, а также объектом datetime и объектом date, который также не является экземпляром datetime, возникает проблема TypeError.

   Если оба параметра сравнения известны и имеют один и тот же атрибут tzinfo, атрибуты tzinfo и fold игнорируются и сравниваются базовые даты. Если оба параметра сравнения известны и имеют разные атрибуты tzinfo, сравнение выполняется так, как если бы значения сравнения были сначала преобразованы в даты и время UTC, за исключением того, что реализация никогда не переполняется.

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

datetime.date()¶

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

datetime.time()¶

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

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

datetime.timetz()¶

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

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

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

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

Изменено в версии 3.6: Добавлен параметр fold.

datetime.astimezone(tz=None)¶

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

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

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

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

Если вы просто хотите привязать объект часового пояса tz к дате-времени 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, else возвращает self.tzinfo.utcoffset(self) и создает исключение, если последнее не возвращает None или timedelta объект с магнитудой менее одного дня.

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

datetime.dst()¶

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

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

datetime.tzname()¶

Если tzinfo равно None, возвращает None, else возвращает 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 <8>>> задается значение -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; в результате использование datetime.utctimetuple() может привести к ошибочным результатам. Если у вас есть наивный 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()¶

Возвращает значение named tuple, состоящее из трех компонентов: year, week и weekday. То же, что и self.date().isocalendar().

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

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

• YYYY-MM-DDTHH:MM:SS.ffffff, если microsecond не равно 0

• YYYY-MM-DDTHH:MM:SS, если microsecond равно 0

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

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

на платформах, где встроенная функция 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().

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

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"

>>> 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.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 объекты поддерживают сравнение на равенство и порядок, где a считается меньшим, чем b, когда a предшествует b по времени.

Наивные и осознающие time объекты никогда не бывают одинаковыми. Сравнение порядка между наивными и осознающими time объектами приводит к возникновению TypeError.

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

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

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

classmethod time.fromisoformat(time_string)¶

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

1. Смещение часовых поясов может составлять доли секунд.

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

3. Доли секунды могут содержать любое количество цифр (все, что превышает 6, будет усечено).

4. Дробные часы и минуты не поддерживаются.

Примеры:

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

Добавлено в версии 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, без преобразования данных о времени.

Изменено в версии 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.isoformat().

time.__format__(format)¶

Аналогично time.strftime(). Это позволяет указать строку формата для объекта time в formatted string literals и при использовании str.format(). См. также strftime() и strptime() Поведение и time.isoformat().

time.utcoffset()¶

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

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

time.dst()¶

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

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

time.tzname()¶

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

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

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

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

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

tzinfo.utcoffset(dt)¶

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

Это представляет собой общее смещение от UTC; например, если объект tzinfo представляет как настройки часового пояса, так и переход на летнее время, 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, если информация о летнем времени неизвестна.

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

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 уместен, если класс хочет сказать, что объекты time не участвуют в протоколах 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() без проблем. Он достаточно надежен для работы с часовыми поясами с фиксированным смещением, а также с часовыми поясами, учитывающими как стандартное, так и летнее время, причем последнее учитывается даже в том случае, если время перехода на летнее время в разные годы разное. Примером часового пояса, с которым реализация по умолчанию 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 возникают неизбежные тонкости, учитывающие как стандартное, так и летнее время в точках перехода на летнее время. Для конкретности рассмотрим восточное время США (UTC -0500), где EDT начинается через минуту после 1:59 (EST) во второе воскресенье марта и заканчивается через минуту после 1:59 (EDT) в первое воскресенье ноября:

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

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

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

Когда начинается переход на летнее время (строка «start»), местные настенные часы переводятся с 1:59 на 3:00. Время на стене в форме 2:MM на самом деле не имеет смысла в этот день, поэтому astimezone(Eastern) не даст результата с hour == 2 в день начала летнего времени. Например, при весеннем переходе вперед в 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

Когда заканчивается летнее время (строка «end»), возникает потенциально более серьезная проблема: в местном настенном времени есть час, который не может быть однозначно указан по буквам: последний час дневного времени. По Восточному времени это время соответствует 5:MM UTC в день окончания дневного времени. Местные настенные часы снова переводятся с 1:59 (дневное время) на 1:00 (стандартное время). Местное время, указанное в 1:MM, не соответствует действительности. astimezone() имитирует поведение местных часов, преобразуя два соседних часа UTC в один и тот же местный час. В примере с восточным временем UTC в виде 5:ММ и 6:ММ при преобразовании в восточное время время по Гринвичу преобразуется в 1:ММ, но для более раннего времени атрибуту 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 других подклассов с фиксированным смещением неоднозначностей не возникает.3>>> подкласс (например, класс, представляющий только EST (фиксированное смещение -5 часов) или только EDT (фиксированное смещение -4 часа)).

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 не ограничено целым числом минут.