PyTime C API

New in version 3.13.

The clock C API provides access to system clocks. It is similar to the Python time module.

For C API related to the datetime module, see DateTime Objects.


type PyTime_t

A timestamp or duration in nanoseconds, represented as a signed 64-bit integer.

The reference point for timestamps depends on the clock used. For example, PyTime_Time() returns timestamps relative to the UNIX epoch.

The supported range is around [-292.3 years; +292.3 years]. Using the Unix epoch (January 1st, 1970) as reference, the supported date range is around [1677-09-21; 2262-04-11]. The exact limits are exposed as constants:

PyTime_t PyTime_MIN

Minimum value of PyTime_t.

PyTime_t PyTime_MAX

Maximum value of PyTime_t.

Clock Functions

The following functions take a pointer to a PyTime_t that they set to the value of a particular clock. Details of each clock are given in the documentation of the corresponding Python function.

The functions return 0 on success, or -1 (with an exception set) on failure.

On integer overflow, they set the PyExc_OverflowError exception and set *result to the value clamped to the [PyTime_MIN; PyTime_MAX] range. (On current systems, integer overflows are likely caused by misconfigured system time.)

As any other C API (unless otherwise specified), the functions must be called with the GIL held.

int PyTime_Monotonic(PyTime_t *result)

Read the monotonic clock. See time.monotonic() for important details on this clock.

int PyTime_PerfCounter(PyTime_t *result)

Read the performance counter. See time.perf_counter() for important details on this clock.

int PyTime_Time(PyTime_t *result)

Read the “wall clock” time. See time.time() for details important on this clock.

Conversion functions

double PyTime_AsSecondsDouble(PyTime_t t)

Convert a timestamp to a number of seconds as a C double.

The function cannot fail, but note that double has limited accuracy for large values.