> **Источник:** https://python-all.ru/3.13/c-api/datetime.html
>
> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.

---

# Объекты даты и времени

Модуль [`datetime`](https://python-all.ru/3.13/library/datetime.html#module-datetime) предоставляет различные объекты для работы с датой и временем. Перед использованием любой из этих функций в исходный код необходимо включить заголовочный файл `datetime.h` (обратите внимание: он не включается макросом `Python.h`), а также вызвать макрос [`PyDateTime_IMPORT`](https://python-all.ru/3.13/c-api/datetime.html#c.PyDateTime_IMPORT), обычно – в функции инициализации модуля. Этот макрос помещает указатель на C-структуру в статическую переменную [`PyDateTimeAPI`](https://python-all.ru/3.13/c-api/datetime.html#c.PyDateTimeAPI), которая используется последующими макросами.

#### `PyDateTime_IMPORT()`

Импортирует C API datetime.

В случае успеха заполняет указатель [`PyDateTimeAPI`](https://python-all.ru/3.13/c-api/datetime.html#c.PyDateTimeAPI). При неудаче устанавливает `PyDateTimeAPI` в `NULL` и возбуждает исключение. Вызывающий код должен проверить, не произошла ли ошибка, с помощью [`PyErr_Occurred()`](https://python-all.ru/3.13/c-api/exceptions.html#c.PyErr_Occurred):

```c
PyDateTime_IMPORT;
if (PyErr_Occurred()) { /* очистка */ }
```

> **Предупреждение**
>
> Это несовместимо с под-интерпретаторами.

#### `type PyDateTime_CAPI`

Структура, содержащая поля для C API datetime.

Поля этой структуры являются закрытыми и могут изменяться.

Не используйте её напрямую; предпочтительнее использовать `PyDateTime_*` API.

#### `PyDateTime_CAPI *PyDateTimeAPI`

Динамически выделяемый объект, содержащий C API datetime.

Эта переменная доступна только после успешного выполнения [`PyDateTime_IMPORT`](https://python-all.ru/3.13/c-api/datetime.html#c.PyDateTime_IMPORT).

#### `type PyDateTime_Date`

Этот подтип [`PyObject`](https://python-all.ru/3.13/c-api/structures.html#c.PyObject) представляет объект даты Python.

#### `type PyDateTime_DateTime`

Этот подтип [`PyObject`](https://python-all.ru/3.13/c-api/structures.html#c.PyObject) представляет объект datetime Python.

#### `type PyDateTime_Time`

Этот подтип [`PyObject`](https://python-all.ru/3.13/c-api/structures.html#c.PyObject) представляет объект времени Python.

#### `type PyDateTime_Delta`

Этот подтип [`PyObject`](https://python-all.ru/3.13/c-api/structures.html#c.PyObject) представляет разность между двумя значениями datetime.

#### `PyTypeObject PyDateTime_DateType`

Этот экземпляр [`PyTypeObject`](https://python-all.ru/3.13/c-api/type.html#c.PyTypeObject) представляет тип date в Python; это тот же объект, что и [`datetime.date`](https://python-all.ru/3.13/library/datetime.html#datetime.date) на уровне Python.

#### `PyTypeObject PyDateTime_DateTimeType`

Этот экземпляр [`PyTypeObject`](https://python-all.ru/3.13/c-api/type.html#c.PyTypeObject) представляет тип datetime в Python; это тот же объект, что и [`datetime.datetime`](https://python-all.ru/3.13/library/datetime.html#datetime.datetime) на уровне Python.

#### `PyTypeObject PyDateTime_TimeType`

Этот экземпляр [`PyTypeObject`](https://python-all.ru/3.13/c-api/type.html#c.PyTypeObject) представляет тип time в Python; это тот же объект, что и [`datetime.time`](https://python-all.ru/3.13/library/datetime.html#datetime.time) на уровне Python.

#### `PyTypeObject PyDateTime_DeltaType`

Этот экземпляр [`PyTypeObject`](https://python-all.ru/3.13/c-api/type.html#c.PyTypeObject) представляет тип Python для разницы между двумя значениями datetime; это тот же объект, что и [`datetime.timedelta`](https://python-all.ru/3.13/library/datetime.html#datetime.timedelta) в слое Python.

#### `PyTypeObject PyDateTime_TZInfoType`

Этот экземпляр [`PyTypeObject`](https://python-all.ru/3.13/c-api/type.html#c.PyTypeObject) представляет тип информации о часовом поясе Python; это тот же объект, что и [`datetime.tzinfo`](https://python-all.ru/3.13/library/datetime.html#datetime.tzinfo) в слое Python.

Макрос для доступа к синглтону UTC:

#### `PyObject *PyDateTime_TimeZone_UTC`

Возвращает синглтон часового пояса, представляющий UTC, тот же объект, что и [`datetime.timezone.utc`](https://python-all.ru/3.13/library/datetime.html#datetime.timezone.utc).

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

Макросы проверки типа:

#### `int PyDate_Check(PyObject *ob)`

Возвращает истину, если *ob* имеет тип [`PyDateTime_DateType`](https://python-all.ru/3.13/c-api/datetime.html#c.PyDateTime_DateType) или является подтипом `PyDateTime_DateType`. *ob* не должен быть `NULL`. Эта функция всегда завершается успешно.

#### `int PyDate_CheckExact(PyObject *ob)`

Возвращает истину, если *ob* имеет тип [`PyDateTime_DateType`](https://python-all.ru/3.13/c-api/datetime.html#c.PyDateTime_DateType). *ob* не должен быть `NULL`. Эта функция всегда завершается успешно.

#### `int PyDateTime_Check(PyObject *ob)`

Возвращает истину, если *ob* имеет тип [`PyDateTime_DateTimeType`](https://python-all.ru/3.13/c-api/datetime.html#c.PyDateTime_DateTimeType) или является подтипом `PyDateTime_DateTimeType`. *ob* не должен быть `NULL`. Эта функция всегда завершается успешно.

#### `int PyDateTime_CheckExact(PyObject *ob)`

Возвращает истину, если *ob* имеет тип [`PyDateTime_DateTimeType`](https://python-all.ru/3.13/c-api/datetime.html#c.PyDateTime_DateTimeType). *ob* не должен быть `NULL`. Эта функция всегда завершается успешно.

#### `int PyTime_Check(PyObject *ob)`

Возвращает истину, если *ob* имеет тип [`PyDateTime_TimeType`](https://python-all.ru/3.13/c-api/datetime.html#c.PyDateTime_TimeType) или является подтипом `PyDateTime_TimeType`. *ob* не должен быть `NULL`. Эта функция всегда завершается успешно.

#### `int PyTime_CheckExact(PyObject *ob)`

Возвращает истину, если *ob* имеет тип [`PyDateTime_TimeType`](https://python-all.ru/3.13/c-api/datetime.html#c.PyDateTime_TimeType). *ob* не должен быть `NULL`. Эта функция всегда завершается успешно.

#### `int PyDelta_Check(PyObject *ob)`

Возвращает истину, если *ob* имеет тип [`PyDateTime_DeltaType`](https://python-all.ru/3.13/c-api/datetime.html#c.PyDateTime_DeltaType) или является подтипом `PyDateTime_DeltaType`. *ob* не должен быть `NULL`. Эта функция всегда завершается успешно.

#### `int PyDelta_CheckExact(PyObject *ob)`

Возвращает истину, если *ob* имеет тип [`PyDateTime_DeltaType`](https://python-all.ru/3.13/c-api/datetime.html#c.PyDateTime_DeltaType). *ob* не должен быть `NULL`. Эта функция всегда завершается успешно.

#### `int PyTZInfo_Check(PyObject *ob)`

Возвращает истину, если *ob* имеет тип [`PyDateTime_TZInfoType`](https://python-all.ru/3.13/c-api/datetime.html#c.PyDateTime_TZInfoType) или является подтипом `PyDateTime_TZInfoType`. *ob* не должен быть `NULL`. Эта функция всегда завершается успешно.

#### `int PyTZInfo_CheckExact(PyObject *ob)`

Возвращает истину, если *ob* имеет тип [`PyDateTime_TZInfoType`](https://python-all.ru/3.13/c-api/datetime.html#c.PyDateTime_TZInfoType). *ob* не должен быть `NULL`. Эта функция всегда завершается успешно.

Макросы для создания объектов:

#### `PyObject *PyDate_FromDate(int year, int month, int day)`

*Возвращаемое значение: новая ссылка.*

Возвращает объект [`datetime.date`](https://python-all.ru/3.13/library/datetime.html#datetime.date) с указанными годом, месяцем и днём.

#### `PyObject *PyDateTime_FromDateAndTime(int year, int month, int day, int hour, int minute, int second, int usecond)`

*Возвращаемое значение: новая ссылка.*

Возвращает объект [`datetime.datetime`](https://python-all.ru/3.13/library/datetime.html#datetime.datetime) с указанными годом, месяцем, днём, часом, минутой, секундой и микросекундой.

#### `PyObject *PyDateTime_FromDateAndTimeAndFold(int year, int month, int day, int hour, int minute, int second, int usecond, int fold)`

*Возвращаемое значение: новая ссылка.*

Возвращает объект [`datetime.datetime`](https://python-all.ru/3.13/library/datetime.html#datetime.datetime) с указанными годом, месяцем, днём, часом, минутой, секундой, микросекундой и fold.

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

#### `PyObject *PyTime_FromTime(int hour, int minute, int second, int usecond)`

*Возвращаемое значение: новая ссылка.*

Возвращает объект [`datetime.time`](https://python-all.ru/3.13/library/datetime.html#datetime.time) с указанными часом, минутой, секундой и микросекундой.

#### `PyObject *PyTime_FromTimeAndFold(int hour, int minute, int second, int usecond, int fold)`

*Возвращаемое значение: новая ссылка.*

Возвращает объект [`datetime.time`](https://python-all.ru/3.13/library/datetime.html#datetime.time) с указанными часом, минутой, секундой, микросекундой и fold.

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

#### `PyObject *PyDelta_FromDSU(int days, int seconds, int useconds)`

*Возвращаемое значение: новая ссылка.*

Возвращает объект [`datetime.timedelta`](https://python-all.ru/3.13/library/datetime.html#datetime.timedelta), представляющий указанное количество дней, секунд и микросекунд. Нормализация выполняется так, чтобы результирующие значения микросекунд и секунд находились в диапазонах, описанных для объектов `datetime.timedelta`.

#### `PyObject *PyTimeZone_FromOffset(PyObject *offset)`

*Возвращаемое значение: новая ссылка.*

Возвращает объект [`datetime.timezone`](https://python-all.ru/3.13/library/datetime.html#datetime.timezone) с безымянным фиксированным смещением, заданным аргументом *offset*.

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

#### `PyObject *PyTimeZone_FromOffsetAndName(PyObject *offset, PyObject *name)`

*Возвращаемое значение: новая ссылка.*

Возвращает объект [`datetime.timezone`](https://python-all.ru/3.13/library/datetime.html#datetime.timezone) с фиксированным смещением, заданным аргументом *offset*, и с именем часового пояса *name*.

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

Макросы для извлечения полей из объектов даты. Аргументом должен быть экземпляр [`PyDateTime_Date`](https://python-all.ru/3.13/c-api/datetime.html#c.PyDateTime_Date), включая подклассы (например, [`PyDateTime_DateTime`](https://python-all.ru/3.13/c-api/datetime.html#c.PyDateTime_DateTime)). Аргумент не должен быть `NULL`, и тип не проверяется:

#### `int PyDateTime_GET_YEAR(PyDateTime_Date *o)`

Возвращает год в виде положительного int.

#### `int PyDateTime_GET_MONTH(PyDateTime_Date *o)`

Возвращает месяц в виде int от 1 до 12.

#### `int PyDateTime_GET_DAY(PyDateTime_Date *o)`

Возвращает день в виде int от 1 до 31.

Макросы для извлечения полей из объектов datetime. Аргументом должен быть экземпляр [`PyDateTime_DateTime`](https://python-all.ru/3.13/c-api/datetime.html#c.PyDateTime_DateTime), включая подклассы. Аргумент не должен быть `NULL`, тип не проверяется:

#### `int PyDateTime_DATE_GET_HOUR(PyDateTime_DateTime *o)`

Возвращает часы в виде целого числа от 0 до 23.

#### `int PyDateTime_DATE_GET_MINUTE(PyDateTime_DateTime *o)`

Возвращает минуты в виде целого числа от 0 до 59.

#### `int PyDateTime_DATE_GET_SECOND(PyDateTime_DateTime *o)`

Возвращает секунды в виде целого числа от 0 до 59.

#### `int PyDateTime_DATE_GET_MICROSECOND(PyDateTime_DateTime *o)`

Возвращает микросекунды в виде целого числа от 0 до 999999.

#### `int PyDateTime_DATE_GET_FOLD(PyDateTime_DateTime *o)`

Возвращает fold в виде целого числа от 0 до 1.

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

#### `PyObject *PyDateTime_DATE_GET_TZINFO(PyDateTime_DateTime *o)`

Возвращает tzinfo (может быть `None`).

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

Макросы для извлечения полей из объектов time. Аргумент должен быть экземпляром [`PyDateTime_Time`](https://python-all.ru/3.13/c-api/datetime.html#c.PyDateTime_Time), включая подклассы. Аргумент не должен быть `NULL`, при этом тип не проверяется:

#### `int PyDateTime_TIME_GET_HOUR(PyDateTime_Time *o)`

Возвращает часы в виде целого числа от 0 до 23.

#### `int PyDateTime_TIME_GET_MINUTE(PyDateTime_Time *o)`

Возвращает минуты в виде целого числа от 0 до 59.

#### `int PyDateTime_TIME_GET_SECOND(PyDateTime_Time *o)`

Возвращает секунды в виде целого числа от 0 до 59.

#### `int PyDateTime_TIME_GET_MICROSECOND(PyDateTime_Time *o)`

Возвращает микросекунды в виде целого числа от 0 до 999999.

#### `int PyDateTime_TIME_GET_FOLD(PyDateTime_Time *o)`

Возвращает fold в виде целого числа от 0 до 1.

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

#### `PyObject *PyDateTime_TIME_GET_TZINFO(PyDateTime_Time *o)`

Возвращает tzinfo (может быть `None`).

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

Макросы для извлечения полей из объектов timedelta. Аргумент должен быть экземпляром [`PyDateTime_Delta`](https://python-all.ru/3.13/c-api/datetime.html#c.PyDateTime_Delta), включая подклассы. Аргумент не должен быть `NULL`, при этом тип не проверяется:

#### `int PyDateTime_DELTA_GET_DAYS(PyDateTime_Delta *o)`

Возвращает количество дней в виде целого числа от -999999999 до 999999999.

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

#### `int PyDateTime_DELTA_GET_SECONDS(PyDateTime_Delta *o)`

Возвращает количество секунд в виде целого числа от 0 до 86399.

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

#### `int PyDateTime_DELTA_GET_MICROSECONDS(PyDateTime_Delta *o)`

Возвращает количество микросекунд в виде целого числа от 0 до 999999.

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

Макросы для удобства модулей, реализующих DB API:

#### `PyObject *PyDateTime_FromTimestamp(PyObject *args)`

*Возвращаемое значение: новая ссылка.*

Создаёт и возвращает новый объект [`datetime.datetime`](https://python-all.ru/3.13/library/datetime.html#datetime.datetime), используя кортеж аргументов, подходящий для передачи в [`datetime.datetime.fromtimestamp()`](https://python-all.ru/3.13/library/datetime.html#datetime.datetime.fromtimestamp).

#### `PyObject *PyDate_FromTimestamp(PyObject *args)`

*Возвращаемое значение: новая ссылка.*

Создаёт и возвращает новый объект [`datetime.date`](https://python-all.ru/3.13/library/datetime.html#datetime.date), используя кортеж аргументов, подходящий для передачи в [`datetime.date.fromtimestamp()`](https://python-all.ru/3.13/library/datetime.html#datetime.date.fromtimestamp).

# Внутренние данные

Следующие символы предоставляются C API, но должны считаться только внутренними.

#### `PyDateTime_CAPSULE_NAME`

Имя капсулы datetime для передачи в [`PyCapsule_Import()`](https://python-all.ru/3.13/c-api/capsule.html#c.PyCapsule_Import).

Только для внутреннего использования. Вместо этого используйте [`PyDateTime_IMPORT`](https://python-all.ru/3.13/c-api/datetime.html#c.PyDateTime_IMPORT).