`datetime.md`

305 строк · 19.5 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/3.15/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.15/library/datetime.html#module-datetime) предоставляет различные объекты для работы с датой и временем. Перед использованием любой из этих функций в исходный код необходимо включить заголовочный файл `datetime.h` (обратите внимание: он не включается макросом `Python.h`), а также вызвать макрос [`PyDateTime_IMPORT`](https://python-all.ru/3.15/c-api/datetime.html#c.PyDateTime_IMPORT), обычно – в функции инициализации модуля. Этот макрос помещает указатель на C-структуру в статическую переменную [`PyDateTimeAPI`](https://python-all.ru/3.15/c-api/datetime.html#c.PyDateTimeAPI), которая используется последующими макросами.1011#### `PyDateTime_IMPORT()`1213Импортирует C API datetime.1415В случае успеха заполняет указатель [`PyDateTimeAPI`](https://python-all.ru/3.15/c-api/datetime.html#c.PyDateTimeAPI). При неудаче устанавливает `PyDateTimeAPI` в `NULL` и возбуждает исключение. Вызывающий код должен проверить, не произошла ли ошибка, с помощью [`PyErr_Occurred()`](https://python-all.ru/3.15/c-api/exceptions.html#c.PyErr_Occurred):1617```c18PyDateTime_IMPORT;19if (PyErr_Occurred()) { /* очистка */ }20```2122> **Предупреждение**23>24> Это несовместимо с под-интерпретаторами.2526Изменено в версии 3.15: Теперь этот макрос потокобезопасен.2728#### `type PyDateTime_CAPI`2930Структура, содержащая поля для C API datetime.3132Поля этой структуры являются закрытыми и могут изменяться.3334Не используйте её напрямую; предпочтительнее использовать `PyDateTime_*` API.3536#### `PyDateTime_CAPI *PyDateTimeAPI`3738Динамически выделяемый объект, содержащий C API datetime.3940Эта переменная доступна только после успешного выполнения [`PyDateTime_IMPORT`](https://python-all.ru/3.15/c-api/datetime.html#c.PyDateTime_IMPORT).4142Изменено в версии 3.15: К этой переменной не следует обращаться напрямую, так как прямой доступ не является потокобезопасным. Вместо этого используйте [`PyDateTime_IMPORT()`](https://python-all.ru/3.15/c-api/datetime.html#c.PyDateTime_IMPORT).4344#### `type PyDateTime_Date`4546Этот подтип [`PyObject`](https://python-all.ru/3.15/c-api/structures.html#c.PyObject) представляет объект даты Python.4748#### `type PyDateTime_DateTime`4950Этот подтип [`PyObject`](https://python-all.ru/3.15/c-api/structures.html#c.PyObject) представляет объект datetime Python.5152#### `type PyDateTime_Time`5354Этот подтип [`PyObject`](https://python-all.ru/3.15/c-api/structures.html#c.PyObject) представляет объект времени Python.5556#### `type PyDateTime_Delta`5758Этот подтип [`PyObject`](https://python-all.ru/3.15/c-api/structures.html#c.PyObject) представляет разность между двумя значениями datetime.5960#### `PyTypeObject PyDateTime_DateType`6162Этот экземпляр [`PyTypeObject`](https://python-all.ru/3.15/c-api/type.html#c.PyTypeObject) представляет тип date в Python; это тот же объект, что и [`datetime.date`](https://python-all.ru/3.15/library/datetime.html#datetime.date) на уровне Python.6364#### `PyTypeObject PyDateTime_DateTimeType`6566Этот экземпляр [`PyTypeObject`](https://python-all.ru/3.15/c-api/type.html#c.PyTypeObject) представляет тип datetime в Python; это тот же объект, что и [`datetime.datetime`](https://python-all.ru/3.15/library/datetime.html#datetime.datetime) на уровне Python.6768#### `PyTypeObject PyDateTime_TimeType`6970Этот экземпляр [`PyTypeObject`](https://python-all.ru/3.15/c-api/type.html#c.PyTypeObject) представляет тип time в Python; это тот же объект, что и [`datetime.time`](https://python-all.ru/3.15/library/datetime.html#datetime.time) на уровне Python.7172#### `PyTypeObject PyDateTime_DeltaType`7374Этот экземпляр [`PyTypeObject`](https://python-all.ru/3.15/c-api/type.html#c.PyTypeObject) представляет тип Python для разницы между двумя значениями datetime; это тот же объект, что и [`datetime.timedelta`](https://python-all.ru/3.15/library/datetime.html#datetime.timedelta) в слое Python.7576#### `PyTypeObject PyDateTime_TZInfoType`7778Этот экземпляр [`PyTypeObject`](https://python-all.ru/3.15/c-api/type.html#c.PyTypeObject) представляет тип информации о часовом поясе Python; это тот же объект, что и [`datetime.tzinfo`](https://python-all.ru/3.15/library/datetime.html#datetime.tzinfo) в слое Python.7980Макрос для доступа к синглтону UTC:8182#### `PyObject *PyDateTime_TimeZone_UTC`8384Возвращает синглтон часового пояса, представляющий UTC, тот же объект, что и [`datetime.timezone.utc`](https://python-all.ru/3.15/library/datetime.html#datetime.timezone.utc).8586Добавлено в версии 3.7.8788Макросы проверки типа:8990#### `int PyDate_Check(PyObject *ob)`9192Возвращает истину, если *ob* имеет тип [`PyDateTime_DateType`](https://python-all.ru/3.15/c-api/datetime.html#c.PyDateTime_DateType) или является подтипом `PyDateTime_DateType`. *ob* не должен быть `NULL`. Эта функция всегда завершается успешно.9394#### `int PyDate_CheckExact(PyObject *ob)`9596Возвращает истину, если *ob* имеет тип [`PyDateTime_DateType`](https://python-all.ru/3.15/c-api/datetime.html#c.PyDateTime_DateType). *ob* не должен быть `NULL`. Эта функция всегда завершается успешно.9798#### `int PyDateTime_Check(PyObject *ob)`99100Возвращает истину, если *ob* имеет тип [`PyDateTime_DateTimeType`](https://python-all.ru/3.15/c-api/datetime.html#c.PyDateTime_DateTimeType) или является подтипом `PyDateTime_DateTimeType`. *ob* не должен быть `NULL`. Эта функция всегда завершается успешно.101102#### `int PyDateTime_CheckExact(PyObject *ob)`103104Возвращает истину, если *ob* имеет тип [`PyDateTime_DateTimeType`](https://python-all.ru/3.15/c-api/datetime.html#c.PyDateTime_DateTimeType). *ob* не должен быть `NULL`. Эта функция всегда завершается успешно.105106#### `int PyTime_Check(PyObject *ob)`107108Возвращает истину, если *ob* имеет тип [`PyDateTime_TimeType`](https://python-all.ru/3.15/c-api/datetime.html#c.PyDateTime_TimeType) или является подтипом `PyDateTime_TimeType`. *ob* не должен быть `NULL`. Эта функция всегда завершается успешно.109110#### `int PyTime_CheckExact(PyObject *ob)`111112Возвращает истину, если *ob* имеет тип [`PyDateTime_TimeType`](https://python-all.ru/3.15/c-api/datetime.html#c.PyDateTime_TimeType). *ob* не должен быть `NULL`. Эта функция всегда завершается успешно.113114#### `int PyDelta_Check(PyObject *ob)`115116Возвращает истину, если *ob* имеет тип [`PyDateTime_DeltaType`](https://python-all.ru/3.15/c-api/datetime.html#c.PyDateTime_DeltaType) или является подтипом `PyDateTime_DeltaType`. *ob* не должен быть `NULL`. Эта функция всегда завершается успешно.117118#### `int PyDelta_CheckExact(PyObject *ob)`119120Возвращает истину, если *ob* имеет тип [`PyDateTime_DeltaType`](https://python-all.ru/3.15/c-api/datetime.html#c.PyDateTime_DeltaType). *ob* не должен быть `NULL`. Эта функция всегда завершается успешно.121122#### `int PyTZInfo_Check(PyObject *ob)`123124Возвращает истину, если *ob* имеет тип [`PyDateTime_TZInfoType`](https://python-all.ru/3.15/c-api/datetime.html#c.PyDateTime_TZInfoType) или является подтипом `PyDateTime_TZInfoType`. *ob* не должен быть `NULL`. Эта функция всегда завершается успешно.125126#### `int PyTZInfo_CheckExact(PyObject *ob)`127128Возвращает истину, если *ob* имеет тип [`PyDateTime_TZInfoType`](https://python-all.ru/3.15/c-api/datetime.html#c.PyDateTime_TZInfoType). *ob* не должен быть `NULL`. Эта функция всегда завершается успешно.129130Макросы для создания объектов:131132#### `PyObject *PyDate_FromDate(int year, int month, int day)`133134*Возвращаемое значение: новая ссылка.*135136Возвращает объект [`datetime.date`](https://python-all.ru/3.15/library/datetime.html#datetime.date) с указанными годом, месяцем и днём.137138#### `PyObject *PyDateTime_FromDateAndTime(int year, int month, int day, int hour, int minute, int second, int usecond)`139140*Возвращаемое значение: новая ссылка.*141142Возвращает объект [`datetime.datetime`](https://python-all.ru/3.15/library/datetime.html#datetime.datetime) с указанными годом, месяцем, днём, часом, минутой, секундой и микросекундой.143144#### `PyObject *PyDateTime_FromDateAndTimeAndFold(int year, int month, int day, int hour, int minute, int second, int usecond, int fold)`145146*Возвращаемое значение: новая ссылка.*147148Возвращает объект [`datetime.datetime`](https://python-all.ru/3.15/library/datetime.html#datetime.datetime) с указанными годом, месяцем, днём, часом, минутой, секундой, микросекундой и fold.149150Добавлено в версии 3.6.151152#### `PyObject *PyTime_FromTime(int hour, int minute, int second, int usecond)`153154*Возвращаемое значение: новая ссылка.*155156Возвращает объект [`datetime.time`](https://python-all.ru/3.15/library/datetime.html#datetime.time) с указанными часом, минутой, секундой и микросекундой.157158#### `PyObject *PyTime_FromTimeAndFold(int hour, int minute, int second, int usecond, int fold)`159160*Возвращаемое значение: новая ссылка.*161162Возвращает объект [`datetime.time`](https://python-all.ru/3.15/library/datetime.html#datetime.time) с указанными часом, минутой, секундой, микросекундой и fold.163164Добавлено в версии 3.6.165166#### `PyObject *PyDelta_FromDSU(int days, int seconds, int useconds)`167168*Возвращаемое значение: новая ссылка.*169170Возвращает объект [`datetime.timedelta`](https://python-all.ru/3.15/library/datetime.html#datetime.timedelta), представляющий указанное количество дней, секунд и микросекунд. Нормализация выполняется так, чтобы результирующие значения микросекунд и секунд находились в диапазонах, описанных для объектов `datetime.timedelta`.171172#### `PyObject *PyTimeZone_FromOffset(PyObject *offset)`173174*Возвращаемое значение: новая ссылка.*175176Возвращает объект [`datetime.timezone`](https://python-all.ru/3.15/library/datetime.html#datetime.timezone) с безымянным фиксированным смещением, заданным аргументом *offset*.177178Добавлено в версии 3.7.179180#### `PyObject *PyTimeZone_FromOffsetAndName(PyObject *offset, PyObject *name)`181182*Возвращаемое значение: новая ссылка.*183184Возвращает объект [`datetime.timezone`](https://python-all.ru/3.15/library/datetime.html#datetime.timezone) с фиксированным смещением, заданным аргументом *offset*, и с именем часового пояса *name*.185186Добавлено в версии 3.7.187188Макросы для извлечения полей из объектов даты. Аргументом должен быть экземпляр [`PyDateTime_Date`](https://python-all.ru/3.15/c-api/datetime.html#c.PyDateTime_Date), включая подклассы (например, [`PyDateTime_DateTime`](https://python-all.ru/3.15/c-api/datetime.html#c.PyDateTime_DateTime)). Аргумент не должен быть `NULL`, и тип не проверяется:189190#### `int PyDateTime_GET_YEAR(PyDateTime_Date *o)`191192Возвращает год в виде положительного int.193194#### `int PyDateTime_GET_MONTH(PyDateTime_Date *o)`195196Возвращает месяц в виде int от 1 до 12.197198#### `int PyDateTime_GET_DAY(PyDateTime_Date *o)`199200Возвращает день в виде int от 1 до 31.201202Макросы для извлечения полей из объектов datetime. Аргументом должен быть экземпляр [`PyDateTime_DateTime`](https://python-all.ru/3.15/c-api/datetime.html#c.PyDateTime_DateTime), включая подклассы. Аргумент не должен быть `NULL`, тип не проверяется:203204#### `int PyDateTime_DATE_GET_HOUR(PyDateTime_DateTime *o)`205206Возвращает часы в виде целого числа от 0 до 23.207208#### `int PyDateTime_DATE_GET_MINUTE(PyDateTime_DateTime *o)`209210Возвращает минуты в виде целого числа от 0 до 59.211212#### `int PyDateTime_DATE_GET_SECOND(PyDateTime_DateTime *o)`213214Возвращает секунды в виде целого числа от 0 до 59.215216#### `int PyDateTime_DATE_GET_MICROSECOND(PyDateTime_DateTime *o)`217218Возвращает микросекунды в виде целого числа от 0 до 999999.219220#### `int PyDateTime_DATE_GET_FOLD(PyDateTime_DateTime *o)`221222Возвращает fold в виде целого числа от 0 до 1.223224Добавлено в версии 3.6.225226#### `PyObject *PyDateTime_DATE_GET_TZINFO(PyDateTime_DateTime *o)`227228Возвращает tzinfo (может быть `None`).229230Добавлено в версии 3.10.231232Макросы для извлечения полей из объектов time. Аргумент должен быть экземпляром [`PyDateTime_Time`](https://python-all.ru/3.15/c-api/datetime.html#c.PyDateTime_Time), включая подклассы. Аргумент не должен быть `NULL`, при этом тип не проверяется:233234#### `int PyDateTime_TIME_GET_HOUR(PyDateTime_Time *o)`235236Возвращает часы в виде целого числа от 0 до 23.237238#### `int PyDateTime_TIME_GET_MINUTE(PyDateTime_Time *o)`239240Возвращает минуты в виде целого числа от 0 до 59.241242#### `int PyDateTime_TIME_GET_SECOND(PyDateTime_Time *o)`243244Возвращает секунды в виде целого числа от 0 до 59.245246#### `int PyDateTime_TIME_GET_MICROSECOND(PyDateTime_Time *o)`247248Возвращает микросекунды в виде целого числа от 0 до 999999.249250#### `int PyDateTime_TIME_GET_FOLD(PyDateTime_Time *o)`251252Возвращает fold в виде целого числа от 0 до 1.253254Добавлено в версии 3.6.255256#### `PyObject *PyDateTime_TIME_GET_TZINFO(PyDateTime_Time *o)`257258Возвращает tzinfo (может быть `None`).259260Добавлено в версии 3.10.261262Макросы для извлечения полей из объектов timedelta. Аргумент должен быть экземпляром [`PyDateTime_Delta`](https://python-all.ru/3.15/c-api/datetime.html#c.PyDateTime_Delta), включая подклассы. Аргумент не должен быть `NULL`, при этом тип не проверяется:263264#### `int PyDateTime_DELTA_GET_DAYS(PyDateTime_Delta *o)`265266Возвращает количество дней в виде целого числа от -999999999 до 999999999.267268Добавлено в версии 3.3.269270#### `int PyDateTime_DELTA_GET_SECONDS(PyDateTime_Delta *o)`271272Возвращает количество секунд в виде целого числа от 0 до 86399.273274Добавлено в версии 3.3.275276#### `int PyDateTime_DELTA_GET_MICROSECONDS(PyDateTime_Delta *o)`277278Возвращает количество микросекунд в виде целого числа от 0 до 999999.279280Добавлено в версии 3.3.281282Макросы для удобства модулей, реализующих DB API:283284#### `PyObject *PyDateTime_FromTimestamp(PyObject *args)`285286*Возвращаемое значение: новая ссылка.*287288Создаёт и возвращает новый объект [`datetime.datetime`](https://python-all.ru/3.15/library/datetime.html#datetime.datetime), используя кортеж аргументов, подходящий для передачи в [`datetime.datetime.fromtimestamp()`](https://python-all.ru/3.15/library/datetime.html#datetime.datetime.fromtimestamp).289290#### `PyObject *PyDate_FromTimestamp(PyObject *args)`291292*Возвращаемое значение: новая ссылка.*293294Создаёт и возвращает новый объект [`datetime.date`](https://python-all.ru/3.15/library/datetime.html#datetime.date), используя кортеж аргументов, подходящий для передачи в [`datetime.date.fromtimestamp()`](https://python-all.ru/3.15/library/datetime.html#datetime.date.fromtimestamp).295296# Внутренние данные297298Следующие символы предоставляются C API, но должны считаться только внутренними.299300#### `PyDateTime_CAPSULE_NAME`301302Имя капсулы datetime для передачи в [`PyCapsule_Import()`](https://python-all.ru/3.15/c-api/capsule.html#c.PyCapsule_Import).303304Только для внутреннего использования. Вместо этого используйте [`PyDateTime_IMPORT`](https://python-all.ru/3.15/c-api/datetime.html#c.PyDateTime_IMPORT).305