Класс datetime() модуля datetime

Создание объекта даты и времени.

Синтаксис:

import datetime

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

Параметры:

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

• year - год в пределах datetime.MINYEAR <= year <= datetime.MAXYEAR,

• month - месяц в пределах 1 <= month <= 12,

• day - день в пределах 1 <= day <= n_day, n_day - количество дней в данном месяце и году,

• hour=0 - часы в пределах 0 <= hour < 24,

• minute=0 - часы в пределах 0 <= minute < 60,

• second=0 - секунды в пределах 0 <= second < 60,

• microsecond=0 - микросекунды в пределах 0 <= microsecond < 1000000,

• tzinfo=None - может быть None или экземпляром подкласса datetime.tzinfo. Дополнительно смотрите модуль zoneinfo (добавлен в Python 3.9) - конкретная реализация часового пояса для поддержки базы данных часовых поясов IANA,

• fold=0 - [0, 1].

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

Возвращаемое значение:

• объект даты и времени datetime.datetime().

Описание:

Класс datetime() модуля datetime это отдельный объект, объединяющий всю информацию из объекта даты datetime.date и объекта времени datetime.time.

• Как и объект даты datetime.date() и datetime.time() предполагает использование текущего григорианского календаря в обоих направлениях.

• Подобно объекту времени datetime.time(), datetime.datetime() предполагает, что каждый день есть ровно 3600 * 24 секунд.

Поддерживаемые операции с объектом datetime.datetime() рассматриваются ниже.

Методы экземпляра класса datetime.datetime() рассматриваются в следующем разделе.

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

• dt.year - возвращает год как целое число,

• dt.month - возвращает месяц как число от 1 до 12 включительно,

• dt.day - возвращает день от 1 до количества дней в данном месяце данного года,

• dt.hour - возвращает час в диапазоне range(24),

• dt.minute - возвращает минуты в диапазоне range(60),

• dt.second - возвращает секунды в диапазоне range(60),

• dt.microsecond - возвращает секунды в диапазоне range(1000000),

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

• dt.fold - возвращает зимнее 0 или летнее 1 время. Используется для устранения неоднозначности времени в момент перехода с зимнего на летнее время и обратно, когда смещение UTC для текущей зоны уменьшается или увеличивается.

>>> import datetime
>>> date = datetime.datetime(2021, 7, 14)
>>> date
# datetime.datetime(2021, 7, 14, 0, 0)
>>> print(date.day, date.month, date.year)
# 14 7 2021
>>> print(date.hour, date.minute, date.second)
0 0 0

Создание объекта datetime.datetime другими способами:

• Текущая локальная дата и время datetime.datetime.today(),

• Текущая локальная дата и время datetime.datetime.now(),

• Текущая дата и время UTC datetime.datetime.utcnow(),

• Из timestamp datetime.datetime.fromtimestamp(),

• Дата и время UTC из timestamp datetime.datetime.utcfromtimestamp(),

• Из datetime.date + datetime.time datetime.datetime.combine(),

• Из строки ISO datetime.datetime.fromisoformat(),

• Из календарной даты ISO, datetime.datetime.fromisocalendar(),

• Из строки datetime.datetime.strptime().

---

datetime.datetime.today():

Метод datetime.datetime.today() возвращает текущую локальную дату и время с tzinfo=None.

• Метод эквивалентен вызову datetime.datetime.fromtimestamp(time.time()),

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

>>> import datetime
>>> datetime.datetime.today()
# datetime.datetime(2020, 5, 5, 14, 56, 40, 902733)

Смотрите также метод datetime.datetime.fromtimestamp().

datetime.datetime.now(tz=None):

Метод datetime.datetime.now() возвращает текущую локальную дату и время.

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

Если параметр tz не None, то это должен быть экземпляр подкласса datetime.tzinfo, а текущие дата и время конвертируются в часовой пояс tz. Дополнительно смотрите модуль zoneinfo (добавлен в Python 3.9) - конкретная реализация часового пояса для поддержки базы данных часовых поясов IANA.

>>> import datetime
>>> datetime.datetime.now()
# datetime.datetime(2020, 5, 5, 15, 5, 3, 204585)

Смотрите также метод создания объекта даты и времени datetime.datetime.utcnow().

datetime.datetime.utcnow():

Метод datetime.datetime.utcnow() возвращает текущую дату и время UTC, с tzinfo=None.

Метод похож на datetime.datetime.now(), но возвращает текущую дату и время UTC как "наивный" объект модуля datetime. Узнать текущую дату и время UTC можно вызвав datetime.datetime.now(datetime.timezone.utc).

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

>>> import datetime
>>> datetime.datetime.utcnow()
# datetime.datetime(2020, 5, 5, 12, 12, 53, 436626)

# рекомендуемый способ создания объекта c текущим временем в UTC
>>> datetime.datetime.now(datetime.timezone.utc)
# datetime.datetime(2020, 5, 5, 12, 13, 17, 243930, tzinfo=datetime.timezone.utc)

datetime.datetime.fromtimestamp(timestamp, tz=None):

Метод datetime.datetime.fromtimestamp() возвращает локальную дату и время, соответствующие метке времени POSIX time.time().

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

Если аргумент tz не None, то это должен быть экземпляр подкласса datetime.tzinfo, а временная метка преобразуется в часовой пояс tz. Дополнительно смотрите модуль zoneinfo (добавлен в Python 3.9) - конкретная реализация часового пояса для поддержки базы данных часовых поясов IANA.

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

>>> import datetime, time
>>> sec = time.time()
>>> sec
# 1588681784.4106905
>>> datetime.datetime.fromtimestamp(sec)
# datetime.datetime(2020, 5, 5, 15, 29, 44, 410691)

Этот метод предпочтительнее, чем datetime.datetime.utcfromtimestamp().

datetime.datetime.utcfromtimestamp(timestamp):

Метод datetime.datetime.utcfromtimestamp() возвращает дату и время UTC, соответствующие метке времени POSIX, с tz=None. Полученный объект "наивный".

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

Чтобы получить осведомленный объект datetime, вызовите fromtimestamp ():

datetime.datetime.fromtimestamp(timestamp, timezone.utc)

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

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

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

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

>>> import datetime, time
>>> sec = time.time()
>>> sec
# 1588682447.241077
>>> datetime.datetime.fromtimestamp(sec, datetime.timezone.utc)
# datetime.datetime(2020, 5, 5, 12, 40, 47, 241077, tzinfo=datetime.timezone.utc)

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

Метод datetime.datetime.combine() возвращает новый объект datetime.datetime(), компоненты даты date которого равны переданному объекту datetime.date, а компоненты времени time равны переданному объекту datetime.time.

Если указан аргумент tzinfo, то его значение используется для установки атрибута результата tzinfo, в противном случае используется атрибут tzinfo аргумента time.

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

>>> import datetime 
# дата
>>> date = datetime.date.today()
# время
>>> time = datetime.time(23, 55)
# интервал
>>> delta = datetime.timedelta(minutes=30)
# соединяем все вместе
>>> datetime.datetime.combine(date, time) + delta
# datetime.datetime(2020, 5, 6, 0, 25)

datetime.datetime.fromisoformat(date_string):

Метод datetime.datetime.fromisoformat() возвращает дату и время datetime.datetime(), соответствующую строке date_string, в любом допустимом формате ISO 8601 со следующими исключениями:

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

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

• Порядковые даты в настоящее время не поддерживаются.

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

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

Примеры:

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

datetime.datetime.fromisocalendar(year, week, day):

Метод datetime.datetime.fromisocalendar() возвращает объект даты и времени, соответствующих календарной дате ISO, указанной в атрибутах year, week, day. Не-дата компоненты datetime заполняются их обычными значениями по умолчанию.

Это обратный метод datetime.isocalendar().

>>> import datetime
>>> datetime.datetime.isocalendar(2021, 19, 2)
# datetime.datetime(2020, 5, 5, 0, 0)

>>> dt = datetime.datetime.now()
>>> dt.isocalendar()
# (2020, 19, 2)

datetime.datetime.strptime(date_string, format):

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

Метод эквивалентен:

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

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

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

>>> import datetime
>>> date_str = 'Fri, 24 Apr 2021 16:22:54 +0000'
>>> format = '%a, %d %b %Y %H:%M:%S +0000'
>>> datetime.datetime.strptime(date_str, format)
# datetime.datetime(2021, 4, 24, 16, 22, 54)

>>> date_str = '24.12.2020 16:22'
>>> format = '%d.%m.%Y %H:%M'
>>> datetime.datetime.strptime(date_str, format)
# datetime.datetime(2020, 12, 24, 16, 22)

---

Поддерживаемые операции datetime.datetime():

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

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

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

3. Вычитание datetime.datetime() из datetime.datetime() определяется только в том случае, если оба операнда "наивны" или оба "осведомленные". Если один "осведомленный", а другой "наивный", то возникает исключение TypeError. Если оба являются "наивными" или оба "осведомленными" и имеют одинаковый атрибут tzinfo, то атрибуты tzinfo игнорируются и в результате получается td - объект datetime.timedelta, такой что datetime2 + td == datetime1. В этом случае настройки часового пояса не выполняются. Если оба осведомлены и имеют разные атрибуты tzinfo, a-b действует так, как если бы сначала a и b были сначала преобразованы в наивные даты UTC. В результате (a.replace(tzinfo=None) - a.utcoffset()) - (b.replace(tzinfo=None) - b.utcoffset()) за исключением того, что реализация никогда не переполняется.

4. datetime1 считается меньше datetime2, когда datetime1 предшествует datetime2 во времени. При сравнении "наивного" объекта с "осведомленным" вызывается TypeError. При сравнений на равенство "наивные" экземпляры никогда не будут равны "осведомленным". Если оба объекта "осведомлены" и имеют один и тот же атрибут tzinfo, то общий атрибут tzinfo игнорируется и сравниваются базовые значения времени. Если оба объекта "осведомлены" и имеют разные атрибуты tzinfo, то объекты сначала корректируются путем вычитания их смещений UTC, полученных из self.utcoffset().

Примечание.

Сравнение объектов datetime.datetime() вызывает исключение TypeError, если один из объектов сравнения не является объектом datetime.datetime().

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

В противном случае, когда объект datetime.datetime() сравнивается с объектом другого типа, то вызывается исключение TypeError.