`datetime.md`

301 строк · 19.0 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/3.14/c-api/datetime.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# Объекты даты и времени89Модуль [`datetime`](https://python-all.ru/3.14/library/datetime.html#module-datetime) предоставляет различные объекты для работы с датой и временем. Перед использованием любой из этих функций в исходный код необходимо включить заголовочный файл `datetime.h` (обратите внимание: он не включается макросом `Python.h`), а также вызвать макрос [`PyDateTime_IMPORT`](https://python-all.ru/3.14/c-api/datetime.html#c.PyDateTime_IMPORT), обычно – в функции инициализации модуля. Этот макрос помещает указатель на C-структуру в статическую переменную [`PyDateTimeAPI`](https://python-all.ru/3.14/c-api/datetime.html#c.PyDateTimeAPI), которая используется последующими макросами.1011#### `PyDateTime_IMPORT()`1213Импортирует C API datetime.1415В случае успеха заполняет указатель [`PyDateTimeAPI`](https://python-all.ru/3.14/c-api/datetime.html#c.PyDateTimeAPI). При неудаче устанавливает `PyDateTimeAPI` в `NULL` и возбуждает исключение. Вызывающий код должен проверить, не произошла ли ошибка, с помощью [`PyErr_Occurred()`](https://python-all.ru/3.14/c-api/exceptions.html#c.PyErr_Occurred):1617```c18PyDateTime_IMPORT;19if (PyErr_Occurred()) { /* очистка */ }20```2122> **Предупреждение**23>24> Это несовместимо с под-интерпретаторами.2526#### `type PyDateTime_CAPI`2728Структура, содержащая поля для C API datetime.2930Поля этой структуры являются закрытыми и могут изменяться.3132Не используйте её напрямую; предпочтительнее использовать `PyDateTime_*` API.3334#### `PyDateTime_CAPI *PyDateTimeAPI`3536Динамически выделяемый объект, содержащий C API datetime.3738Эта переменная доступна только после успешного выполнения [`PyDateTime_IMPORT`](https://python-all.ru/3.14/c-api/datetime.html#c.PyDateTime_IMPORT).3940#### `type PyDateTime_Date`4142Этот подтип [`PyObject`](https://python-all.ru/3.14/c-api/structures.html#c.PyObject) представляет объект даты Python.4344#### `type PyDateTime_DateTime`4546Этот подтип [`PyObject`](https://python-all.ru/3.14/c-api/structures.html#c.PyObject) представляет объект datetime Python.4748#### `type PyDateTime_Time`4950Этот подтип [`PyObject`](https://python-all.ru/3.14/c-api/structures.html#c.PyObject) представляет объект времени Python.5152#### `type PyDateTime_Delta`5354Этот подтип [`PyObject`](https://python-all.ru/3.14/c-api/structures.html#c.PyObject) представляет разность между двумя значениями datetime.5556#### `PyTypeObject PyDateTime_DateType`5758Этот экземпляр [`PyTypeObject`](https://python-all.ru/3.14/c-api/type.html#c.PyTypeObject) представляет тип date в Python; это тот же объект, что и [`datetime.date`](https://python-all.ru/3.14/library/datetime.html#datetime.date) на уровне Python.5960#### `PyTypeObject PyDateTime_DateTimeType`6162Этот экземпляр [`PyTypeObject`](https://python-all.ru/3.14/c-api/type.html#c.PyTypeObject) представляет тип datetime в Python; это тот же объект, что и [`datetime.datetime`](https://python-all.ru/3.14/library/datetime.html#datetime.datetime) на уровне Python.6364#### `PyTypeObject PyDateTime_TimeType`6566Этот экземпляр [`PyTypeObject`](https://python-all.ru/3.14/c-api/type.html#c.PyTypeObject) представляет тип time в Python; это тот же объект, что и [`datetime.time`](https://python-all.ru/3.14/library/datetime.html#datetime.time) на уровне Python.6768#### `PyTypeObject PyDateTime_DeltaType`6970Этот экземпляр [`PyTypeObject`](https://python-all.ru/3.14/c-api/type.html#c.PyTypeObject) представляет тип Python для разницы между двумя значениями datetime; это тот же объект, что и [`datetime.timedelta`](https://python-all.ru/3.14/library/datetime.html#datetime.timedelta) в слое Python.7172#### `PyTypeObject PyDateTime_TZInfoType`7374Этот экземпляр [`PyTypeObject`](https://python-all.ru/3.14/c-api/type.html#c.PyTypeObject) представляет тип информации о часовом поясе Python; это тот же объект, что и [`datetime.tzinfo`](https://python-all.ru/3.14/library/datetime.html#datetime.tzinfo) в слое Python.7576Макрос для доступа к синглтону UTC:7778#### `PyObject *PyDateTime_TimeZone_UTC`7980Возвращает синглтон часового пояса, представляющий UTC, тот же объект, что и [`datetime.timezone.utc`](https://python-all.ru/3.14/library/datetime.html#datetime.timezone.utc).8182Добавлено в версии 3.7.8384Макросы проверки типа:8586#### `int PyDate_Check(PyObject *ob)`8788Возвращает истину, если *ob* имеет тип [`PyDateTime_DateType`](https://python-all.ru/3.14/c-api/datetime.html#c.PyDateTime_DateType) или является подтипом `PyDateTime_DateType`. *ob* не должен быть `NULL`. Эта функция всегда завершается успешно.8990#### `int PyDate_CheckExact(PyObject *ob)`9192Возвращает истину, если *ob* имеет тип [`PyDateTime_DateType`](https://python-all.ru/3.14/c-api/datetime.html#c.PyDateTime_DateType). *ob* не должен быть `NULL`. Эта функция всегда завершается успешно.9394#### `int PyDateTime_Check(PyObject *ob)`9596Возвращает истину, если *ob* имеет тип [`PyDateTime_DateTimeType`](https://python-all.ru/3.14/c-api/datetime.html#c.PyDateTime_DateTimeType) или является подтипом `PyDateTime_DateTimeType`. *ob* не должен быть `NULL`. Эта функция всегда завершается успешно.9798#### `int PyDateTime_CheckExact(PyObject *ob)`99100Возвращает истину, если *ob* имеет тип [`PyDateTime_DateTimeType`](https://python-all.ru/3.14/c-api/datetime.html#c.PyDateTime_DateTimeType). *ob* не должен быть `NULL`. Эта функция всегда завершается успешно.101102#### `int PyTime_Check(PyObject *ob)`103104Возвращает истину, если *ob* имеет тип [`PyDateTime_TimeType`](https://python-all.ru/3.14/c-api/datetime.html#c.PyDateTime_TimeType) или является подтипом `PyDateTime_TimeType`. *ob* не должен быть `NULL`. Эта функция всегда завершается успешно.105106#### `int PyTime_CheckExact(PyObject *ob)`107108Возвращает истину, если *ob* имеет тип [`PyDateTime_TimeType`](https://python-all.ru/3.14/c-api/datetime.html#c.PyDateTime_TimeType). *ob* не должен быть `NULL`. Эта функция всегда завершается успешно.109110#### `int PyDelta_Check(PyObject *ob)`111112Возвращает истину, если *ob* имеет тип [`PyDateTime_DeltaType`](https://python-all.ru/3.14/c-api/datetime.html#c.PyDateTime_DeltaType) или является подтипом `PyDateTime_DeltaType`. *ob* не должен быть `NULL`. Эта функция всегда завершается успешно.113114#### `int PyDelta_CheckExact(PyObject *ob)`115116Возвращает истину, если *ob* имеет тип [`PyDateTime_DeltaType`](https://python-all.ru/3.14/c-api/datetime.html#c.PyDateTime_DeltaType). *ob* не должен быть `NULL`. Эта функция всегда завершается успешно.117118#### `int PyTZInfo_Check(PyObject *ob)`119120Возвращает истину, если *ob* имеет тип [`PyDateTime_TZInfoType`](https://python-all.ru/3.14/c-api/datetime.html#c.PyDateTime_TZInfoType) или является подтипом `PyDateTime_TZInfoType`. *ob* не должен быть `NULL`. Эта функция всегда завершается успешно.121122#### `int PyTZInfo_CheckExact(PyObject *ob)`123124Возвращает истину, если *ob* имеет тип [`PyDateTime_TZInfoType`](https://python-all.ru/3.14/c-api/datetime.html#c.PyDateTime_TZInfoType). *ob* не должен быть `NULL`. Эта функция всегда завершается успешно.125126Макросы для создания объектов:127128#### `PyObject *PyDate_FromDate(int year, int month, int day)`129130*Возвращаемое значение: новая ссылка.*131132Возвращает объект [`datetime.date`](https://python-all.ru/3.14/library/datetime.html#datetime.date) с указанными годом, месяцем и днём.133134#### `PyObject *PyDateTime_FromDateAndTime(int year, int month, int day, int hour, int minute, int second, int usecond)`135136*Возвращаемое значение: новая ссылка.*137138Возвращает объект [`datetime.datetime`](https://python-all.ru/3.14/library/datetime.html#datetime.datetime) с указанными годом, месяцем, днём, часом, минутой, секундой и микросекундой.139140#### `PyObject *PyDateTime_FromDateAndTimeAndFold(int year, int month, int day, int hour, int minute, int second, int usecond, int fold)`141142*Возвращаемое значение: новая ссылка.*143144Возвращает объект [`datetime.datetime`](https://python-all.ru/3.14/library/datetime.html#datetime.datetime) с указанными годом, месяцем, днём, часом, минутой, секундой, микросекундой и fold.145146Добавлено в версии 3.6.147148#### `PyObject *PyTime_FromTime(int hour, int minute, int second, int usecond)`149150*Возвращаемое значение: новая ссылка.*151152Возвращает объект [`datetime.time`](https://python-all.ru/3.14/library/datetime.html#datetime.time) с указанными часом, минутой, секундой и микросекундой.153154#### `PyObject *PyTime_FromTimeAndFold(int hour, int minute, int second, int usecond, int fold)`155156*Возвращаемое значение: новая ссылка.*157158Возвращает объект [`datetime.time`](https://python-all.ru/3.14/library/datetime.html#datetime.time) с указанными часом, минутой, секундой, микросекундой и fold.159160Добавлено в версии 3.6.161162#### `PyObject *PyDelta_FromDSU(int days, int seconds, int useconds)`163164*Возвращаемое значение: новая ссылка.*165166Возвращает объект [`datetime.timedelta`](https://python-all.ru/3.14/library/datetime.html#datetime.timedelta), представляющий указанное количество дней, секунд и микросекунд. Нормализация выполняется так, чтобы результирующие значения микросекунд и секунд находились в диапазонах, описанных для объектов `datetime.timedelta`.167168#### `PyObject *PyTimeZone_FromOffset(PyObject *offset)`169170*Возвращаемое значение: новая ссылка.*171172Возвращает объект [`datetime.timezone`](https://python-all.ru/3.14/library/datetime.html#datetime.timezone) с безымянным фиксированным смещением, заданным аргументом *offset*.173174Добавлено в версии 3.7.175176#### `PyObject *PyTimeZone_FromOffsetAndName(PyObject *offset, PyObject *name)`177178*Возвращаемое значение: новая ссылка.*179180Возвращает объект [`datetime.timezone`](https://python-all.ru/3.14/library/datetime.html#datetime.timezone) с фиксированным смещением, заданным аргументом *offset*, и с именем часового пояса *name*.181182Добавлено в версии 3.7.183184Макросы для извлечения полей из объектов даты. Аргументом должен быть экземпляр [`PyDateTime_Date`](https://python-all.ru/3.14/c-api/datetime.html#c.PyDateTime_Date), включая подклассы (например, [`PyDateTime_DateTime`](https://python-all.ru/3.14/c-api/datetime.html#c.PyDateTime_DateTime)). Аргумент не должен быть `NULL`, и тип не проверяется:185186#### `int PyDateTime_GET_YEAR(PyDateTime_Date *o)`187188Возвращает год в виде положительного int.189190#### `int PyDateTime_GET_MONTH(PyDateTime_Date *o)`191192Возвращает месяц в виде int от 1 до 12.193194#### `int PyDateTime_GET_DAY(PyDateTime_Date *o)`195196Возвращает день в виде int от 1 до 31.197198Макросы для извлечения полей из объектов datetime. Аргументом должен быть экземпляр [`PyDateTime_DateTime`](https://python-all.ru/3.14/c-api/datetime.html#c.PyDateTime_DateTime), включая подклассы. Аргумент не должен быть `NULL`, тип не проверяется:199200#### `int PyDateTime_DATE_GET_HOUR(PyDateTime_DateTime *o)`201202Возвращает часы в виде целого числа от 0 до 23.203204#### `int PyDateTime_DATE_GET_MINUTE(PyDateTime_DateTime *o)`205206Возвращает минуты в виде целого числа от 0 до 59.207208#### `int PyDateTime_DATE_GET_SECOND(PyDateTime_DateTime *o)`209210Возвращает секунды в виде целого числа от 0 до 59.211212#### `int PyDateTime_DATE_GET_MICROSECOND(PyDateTime_DateTime *o)`213214Возвращает микросекунды в виде целого числа от 0 до 999999.215216#### `int PyDateTime_DATE_GET_FOLD(PyDateTime_DateTime *o)`217218Возвращает fold в виде целого числа от 0 до 1.219220Добавлено в версии 3.6.221222#### `PyObject *PyDateTime_DATE_GET_TZINFO(PyDateTime_DateTime *o)`223224Возвращает tzinfo (может быть `None`).225226Добавлено в версии 3.10.227228Макросы для извлечения полей из объектов time. Аргумент должен быть экземпляром [`PyDateTime_Time`](https://python-all.ru/3.14/c-api/datetime.html#c.PyDateTime_Time), включая подклассы. Аргумент не должен быть `NULL`, при этом тип не проверяется:229230#### `int PyDateTime_TIME_GET_HOUR(PyDateTime_Time *o)`231232Возвращает часы в виде целого числа от 0 до 23.233234#### `int PyDateTime_TIME_GET_MINUTE(PyDateTime_Time *o)`235236Возвращает минуты в виде целого числа от 0 до 59.237238#### `int PyDateTime_TIME_GET_SECOND(PyDateTime_Time *o)`239240Возвращает секунды в виде целого числа от 0 до 59.241242#### `int PyDateTime_TIME_GET_MICROSECOND(PyDateTime_Time *o)`243244Возвращает микросекунды в виде целого числа от 0 до 999999.245246#### `int PyDateTime_TIME_GET_FOLD(PyDateTime_Time *o)`247248Возвращает fold в виде целого числа от 0 до 1.249250Добавлено в версии 3.6.251252#### `PyObject *PyDateTime_TIME_GET_TZINFO(PyDateTime_Time *o)`253254Возвращает tzinfo (может быть `None`).255256Добавлено в версии 3.10.257258Макросы для извлечения полей из объектов timedelta. Аргумент должен быть экземпляром [`PyDateTime_Delta`](https://python-all.ru/3.14/c-api/datetime.html#c.PyDateTime_Delta), включая подклассы. Аргумент не должен быть `NULL`, при этом тип не проверяется:259260#### `int PyDateTime_DELTA_GET_DAYS(PyDateTime_Delta *o)`261262Возвращает количество дней в виде целого числа от -999999999 до 999999999.263264Добавлено в версии 3.3.265266#### `int PyDateTime_DELTA_GET_SECONDS(PyDateTime_Delta *o)`267268Возвращает количество секунд в виде целого числа от 0 до 86399.269270Добавлено в версии 3.3.271272#### `int PyDateTime_DELTA_GET_MICROSECONDS(PyDateTime_Delta *o)`273274Возвращает количество микросекунд в виде целого числа от 0 до 999999.275276Добавлено в версии 3.3.277278Макросы для удобства модулей, реализующих DB API:279280#### `PyObject *PyDateTime_FromTimestamp(PyObject *args)`281282*Возвращаемое значение: новая ссылка.*283284Создаёт и возвращает новый объект [`datetime.datetime`](https://python-all.ru/3.14/library/datetime.html#datetime.datetime), используя кортеж аргументов, подходящий для передачи в [`datetime.datetime.fromtimestamp()`](https://python-all.ru/3.14/library/datetime.html#datetime.datetime.fromtimestamp).285286#### `PyObject *PyDate_FromTimestamp(PyObject *args)`287288*Возвращаемое значение: новая ссылка.*289290Создаёт и возвращает новый объект [`datetime.date`](https://python-all.ru/3.14/library/datetime.html#datetime.date), используя кортеж аргументов, подходящий для передачи в [`datetime.date.fromtimestamp()`](https://python-all.ru/3.14/library/datetime.html#datetime.date.fromtimestamp).291292# Внутренние данные293294Следующие символы предоставляются C API, но должны считаться только внутренними.295296#### `PyDateTime_CAPSULE_NAME`297298Имя капсулы datetime для передачи в [`PyCapsule_Import()`](https://python-all.ru/3.14/c-api/capsule.html#c.PyCapsule_Import).299300Только для внутреннего использования. Вместо этого используйте [`PyDateTime_IMPORT`](https://python-all.ru/3.14/c-api/datetime.html#c.PyDateTime_IMPORT).301