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

---

# PyTime C API

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

C API для работы с часами предоставляет доступ к системным часам. Оно аналогично модулю Python [`time`](https://python-all.ru/3.16/library/time.html#module-time).

Для C API, связанного с модулем [`datetime`](https://python-all.ru/3.16/library/datetime.html#module-datetime), см. [Объекты даты и времени](https://python-all.ru/3.16/c-api/datetime.html#datetimeobjects).

## Типы

#### `type PyTime_t`

Отметка времени или длительность в наносекундах, представленная как 64-битное целое число со знаком.

Точка отсчета для отметок времени зависит от используемых часов. Например, [`PyTime_Time()`](https://python-all.ru/3.16/c-api/time.html#c.PyTime_Time) возвращает отметки времени относительно эпохи UNIX.

Поддерживаемый диапазон составляет примерно \[-292.3 года; +292.3 года\]. Используя эпоху Unix (1 января 1970 г.) в качестве точки отсчёта, поддерживаемый диапазон дат составляет примерно \[1677-09-21; 2262-04-11\]. Точные границы представлены в виде констант:

#### `PyTime_t PyTime_MIN`

Минимальное значение [`PyTime_t`](https://python-all.ru/3.16/c-api/time.html#c.PyTime_t).

#### `PyTime_t PyTime_MAX`

Максимальное значение [`PyTime_t`](https://python-all.ru/3.16/c-api/time.html#c.PyTime_t).

## Функции часов

Следующие функции принимают указатель на [PyTime\_t](https://python-all.ru/3.16/c-api/time.html#c.PyTime_t), который они устанавливают в значение конкретных часов. Подробности о каждом типе часов приведены в документации соответствующей функции Python.

Функции возвращают `0` в случае успеха или `-1` (с установленным исключением) при ошибке.

При целочисленном переполнении они устанавливают исключение [`PyExc_OverflowError`](https://python-all.ru/3.16/c-api/exceptions.html#c.PyExc_OverflowError) и устанавливают `*result` в значение, ограниченное диапазоном `[PyTime_MIN; PyTime_MAX]`. (В современных системах целочисленные переполнения, скорее всего, вызваны неправильной конфигурацией системного времени.)

Как и любой другой C API (если не указано иное), функции должны вызываться с [присоединённым состоянием потока](https://python-all.ru/3.16/glossary.html#term-attached-thread-state).

#### `int PyTime_Monotonic(PyTime_t *result)`

Читает монотонные часы. См. [`time.monotonic()`](https://python-all.ru/3.16/library/time.html#time.monotonic) для получения важных подробностей об этих часах.

#### `int PyTime_PerfCounter(PyTime_t *result)`

Читает счётчик производительности. См. [`time.perf_counter()`](https://python-all.ru/3.16/library/time.html#time.perf_counter) для получения важных подробностей об этих часах.

#### `int PyTime_Time(PyTime_t *result)`

Читает время «настенных часов». См. [`time.time()`](https://python-all.ru/3.16/library/time.html#time.time) для получения важных подробностей об этих часах.

## Функции сырых часов

Аналогичны функциям часов, но не устанавливают исключение при ошибке и не требуют от вызывающего кода наличия [присоединённого состояния потока](https://python-all.ru/3.16/glossary.html#term-attached-thread-state).

В случае успеха функции возвращают `0`.

При ошибке они устанавливают `*result` в `0` и возвращают `-1`, *не* устанавливая исключение. Чтобы выяснить причину ошибки, [присоедините](https://python-all.ru/3.16/glossary.html#term-attached-thread-state) [состояние потока](https://python-all.ru/3.16/glossary.html#term-thread-state), и вызовите обычную (не-`Raw`) функцию. Обратите внимание, что обычная функция может выполниться успешно после того, как `Raw` потерпела неудачу.

#### `int PyTime_MonotonicRaw(PyTime_t *result)`

Похож на [`PyTime_Monotonic()`](https://python-all.ru/3.16/c-api/time.html#c.PyTime_Monotonic), но не устанавливает исключение при ошибке и не требует [присоединённого состояния потока](https://python-all.ru/3.16/glossary.html#term-attached-thread-state).

#### `int PyTime_PerfCounterRaw(PyTime_t *result)`

Похож на [`PyTime_PerfCounter()`](https://python-all.ru/3.16/c-api/time.html#c.PyTime_PerfCounter), но не устанавливает исключение при ошибке и не требует [присоединённого состояния потока](https://python-all.ru/3.16/glossary.html#term-attached-thread-state).

#### `int PyTime_TimeRaw(PyTime_t *result)`

Похож на [`PyTime_Time()`](https://python-all.ru/3.16/c-api/time.html#c.PyTime_Time), но не устанавливает исключение при ошибке и не требует [присоединённого состояния потока](https://python-all.ru/3.16/glossary.html#term-attached-thread-state).

## Функции преобразования

#### `double PyTime_AsSecondsDouble(PyTime_t t)`

Преобразует временную метку в количество секунд в виде double языка C.

Функция не может завершиться ошибкой, но учтите, что double имеет ограниченную точность для больших значений.