pythongh-110850 Partially revert "pythongh-106316: Remove pytime.h he…

…ader file (python#106317)"

This reverts commit 46d7761,
and returns to the  status quo (3.12).

Tests are left in _testinternalcapi; this sounds appropriate for
underscored functions.

.github/CODEOWNERS

@@ -127,6 +127,7 @@ Lib/test/test_time.py         @pganssle @abalkin
 Modules/timemodule.c          @pganssle @abalkin
 Python/pytime.c               @pganssle @abalkin
 Include/internal/pycore_time.h  @pganssle @abalkin
+Include/pytime.h              @pganssle @abalkin
 
 # Email and related
 **/*mail*                     @python/email-team

Doc/whatsnew/3.13.rst

@@ -1739,9 +1739,6 @@ Removed
   (:pep:`590`).
   (Contributed by Victor Stinner in :gh:`106023`.)
 
-* Remove ``cpython/pytime.h`` header file: it only contained private functions.
-  (Contributed by Victor Stinner in :gh:`106316`.)
-
 * Remove ``_PyInterpreterState_Get()`` alias to
   :c:func:`PyInterpreterState_Get()` which was kept for backward compatibility
   with Python 3.8. The `pythoncapi-compat project

Include/Python.h

@@ -97,6 +97,7 @@
 #include "weakrefobject.h"
 #include "structseq.h"
 #include "cpython/picklebufobject.h"
+#include "cpython/pytime.h"
 #include "codecs.h"
 #include "pyerrors.h"
 #include "pythread.h"

Include/cpython/pytime.h

@@ -0,0 +1,293 @@
+// The _PyTime_t API is not supported for public use, and may be changed or
+// removed at any time.
+// See Include/internal/pycore_time.h for details of the current
+// implementation.
+
+#ifndef Py_LIMITED_API
+#ifndef Py_PYTIME_H
+#define Py_PYTIME_H
+
+/**************************************************************************
+Symbols and macros to supply platform-independent interfaces to time related
+functions and constants
+**************************************************************************/
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+#ifdef __clang__
+struct timeval;
+#endif
+
+/* _PyTime_t: Python timestamp with subsecond precision. It can be used to
+   store a duration, and so indirectly a date (related to another date, like
+   UNIX epoch). */
+typedef int64_t _PyTime_t;
+// _PyTime_MIN nanoseconds is around -292.3 years
+#define _PyTime_MIN INT64_MIN
+// _PyTime_MAX nanoseconds is around +292.3 years
+#define _PyTime_MAX INT64_MAX
+#define _SIZEOF_PYTIME_T 8
+
+typedef enum {
+    /* Round towards minus infinity (-inf).
+       For example, used to read a clock. */
+    _PyTime_ROUND_FLOOR=0,
+    /* Round towards infinity (+inf).
+       For example, used for timeout to wait "at least" N seconds. */
+    _PyTime_ROUND_CEILING=1,
+    /* Round to nearest with ties going to nearest even integer.
+       For example, used to round from a Python float. */
+    _PyTime_ROUND_HALF_EVEN=2,
+    /* Round away from zero
+       For example, used for timeout. _PyTime_ROUND_CEILING rounds
+       -1e-9 to 0 milliseconds which causes bpo-31786 issue.
+       _PyTime_ROUND_UP rounds -1e-9 to -1 millisecond which keeps
+       the timeout sign as expected. select.poll(timeout) must block
+       for negative values." */
+    _PyTime_ROUND_UP=3,
+    /* _PyTime_ROUND_TIMEOUT (an alias for _PyTime_ROUND_UP) should be
+       used for timeouts. */
+    _PyTime_ROUND_TIMEOUT = _PyTime_ROUND_UP
+} _PyTime_round_t;
+
+
+/* Convert a time_t to a PyLong. */
+PyAPI_FUNC(PyObject *) _PyLong_FromTime_t(
+    time_t sec);
+
+/* Convert a PyLong to a time_t. */
+PyAPI_FUNC(time_t) _PyLong_AsTime_t(
+    PyObject *obj);
+
+/* Convert a number of seconds, int or float, to time_t. */
+PyAPI_FUNC(int) _PyTime_ObjectToTime_t(
+    PyObject *obj,
+    time_t *sec,
+    _PyTime_round_t);
+
+/* Convert a number of seconds, int or float, to a timeval structure.
+   usec is in the range [0; 999999] and rounded towards zero.
+   For example, -1.2 is converted to (-2, 800000). */
+PyAPI_FUNC(int) _PyTime_ObjectToTimeval(
+    PyObject *obj,
+    time_t *sec,
+    long *usec,
+    _PyTime_round_t);
+
+/* Convert a number of seconds, int or float, to a timespec structure.
+   nsec is in the range [0; 999999999] and rounded towards zero.
+   For example, -1.2 is converted to (-2, 800000000). */
+PyAPI_FUNC(int) _PyTime_ObjectToTimespec(
+    PyObject *obj,
+    time_t *sec,
+    long *nsec,
+    _PyTime_round_t);
+
+
+/* Create a timestamp from a number of seconds. */
+PyAPI_FUNC(_PyTime_t) _PyTime_FromSeconds(int seconds);
+
+/* Macro to create a timestamp from a number of seconds, no integer overflow.
+   Only use the macro for small values, prefer _PyTime_FromSeconds(). */
+#define _PYTIME_FROMSECONDS(seconds) \
+            ((_PyTime_t)(seconds) * (1000 * 1000 * 1000))
+
+/* Create a timestamp from a number of nanoseconds. */
+PyAPI_FUNC(_PyTime_t) _PyTime_FromNanoseconds(_PyTime_t ns);
+
+/* Create a timestamp from a number of microseconds.
+ * Clamp to [_PyTime_MIN; _PyTime_MAX] on overflow. */
+PyAPI_FUNC(_PyTime_t) _PyTime_FromMicrosecondsClamp(_PyTime_t us);
+
+/* Create a timestamp from nanoseconds (Python int). */
+PyAPI_FUNC(int) _PyTime_FromNanosecondsObject(_PyTime_t *t,
+    PyObject *obj);
+
+/* Convert a number of seconds (Python float or int) to a timestamp.
+   Raise an exception and return -1 on error, return 0 on success. */
+PyAPI_FUNC(int) _PyTime_FromSecondsObject(_PyTime_t *t,
+    PyObject *obj,
+    _PyTime_round_t round);
+
+/* Convert a number of milliseconds (Python float or int, 10^-3) to a timestamp.
+   Raise an exception and return -1 on error, return 0 on success. */
+PyAPI_FUNC(int) _PyTime_FromMillisecondsObject(_PyTime_t *t,
+    PyObject *obj,
+    _PyTime_round_t round);
+
+/* Convert a timestamp to a number of seconds as a C double. */
+PyAPI_FUNC(double) _PyTime_AsSecondsDouble(_PyTime_t t);
+
+/* Convert timestamp to a number of milliseconds (10^-3 seconds). */
+PyAPI_FUNC(_PyTime_t) _PyTime_AsMilliseconds(_PyTime_t t,
+    _PyTime_round_t round);
+
+/* Convert timestamp to a number of microseconds (10^-6 seconds). */
+PyAPI_FUNC(_PyTime_t) _PyTime_AsMicroseconds(_PyTime_t t,
+    _PyTime_round_t round);
+
+/* Convert timestamp to a number of nanoseconds (10^-9 seconds). */
+PyAPI_FUNC(_PyTime_t) _PyTime_AsNanoseconds(_PyTime_t t);
+
+#ifdef MS_WINDOWS
+// Convert timestamp to a number of 100 nanoseconds (10^-7 seconds).
+PyAPI_FUNC(_PyTime_t) _PyTime_As100Nanoseconds(_PyTime_t t,
+    _PyTime_round_t round);
+#endif
+
+/* Convert timestamp to a number of nanoseconds (10^-9 seconds) as a Python int
+   object. */
+PyAPI_FUNC(PyObject *) _PyTime_AsNanosecondsObject(_PyTime_t t);
+
+#ifndef MS_WINDOWS
+/* Create a timestamp from a timeval structure.
+   Raise an exception and return -1 on overflow, return 0 on success. */
+PyAPI_FUNC(int) _PyTime_FromTimeval(_PyTime_t *tp, struct timeval *tv);
+#endif
+
+/* Convert a timestamp to a timeval structure (microsecond resolution).
+   tv_usec is always positive.
+   Raise an exception and return -1 if the conversion overflowed,
+   return 0 on success. */
+PyAPI_FUNC(int) _PyTime_AsTimeval(_PyTime_t t,
+    struct timeval *tv,
+    _PyTime_round_t round);
+
+/* Similar to _PyTime_AsTimeval() but don't raise an exception on overflow.
+   On overflow, clamp tv_sec to _PyTime_t min/max. */
+PyAPI_FUNC(void) _PyTime_AsTimeval_clamp(_PyTime_t t,
+    struct timeval *tv,
+    _PyTime_round_t round);
+
+/* Convert a timestamp to a number of seconds (secs) and microseconds (us).
+   us is always positive. This function is similar to _PyTime_AsTimeval()
+   except that secs is always a time_t type, whereas the timeval structure
+   uses a C long for tv_sec on Windows.
+   Raise an exception and return -1 if the conversion overflowed,
+   return 0 on success. */
+PyAPI_FUNC(int) _PyTime_AsTimevalTime_t(
+    _PyTime_t t,
+    time_t *secs,
+    int *us,
+    _PyTime_round_t round);
+
+#if defined(HAVE_CLOCK_GETTIME) || defined(HAVE_KQUEUE)
+/* Create a timestamp from a timespec structure.
+   Raise an exception and return -1 on overflow, return 0 on success. */
+PyAPI_FUNC(int) _PyTime_FromTimespec(_PyTime_t *tp, struct timespec *ts);
+
+/* Convert a timestamp to a timespec structure (nanosecond resolution).
+   tv_nsec is always positive.
+   Raise an exception and return -1 on error, return 0 on success. */
+PyAPI_FUNC(int) _PyTime_AsTimespec(_PyTime_t t, struct timespec *ts);
+
+/* Similar to _PyTime_AsTimespec() but don't raise an exception on overflow.
+   On overflow, clamp tv_sec to _PyTime_t min/max. */
+PyAPI_FUNC(void) _PyTime_AsTimespec_clamp(_PyTime_t t, struct timespec *ts);
+#endif
+
+
+// Compute t1 + t2. Clamp to [_PyTime_MIN; _PyTime_MAX] on overflow.
+PyAPI_FUNC(_PyTime_t) _PyTime_Add(_PyTime_t t1, _PyTime_t t2);
+
+/* Compute ticks * mul / div.
+   Clamp to [_PyTime_MIN; _PyTime_MAX] on overflow.
+   The caller must ensure that ((div - 1) * mul) cannot overflow. */
+PyAPI_FUNC(_PyTime_t) _PyTime_MulDiv(_PyTime_t ticks,
+    _PyTime_t mul,
+    _PyTime_t div);
+
+/* Structure used by time.get_clock_info() */
+typedef struct {
+    const char *implementation;
+    int monotonic;
+    int adjustable;
+    double resolution;
+} _Py_clock_info_t;
+
+/* Get the current time from the system clock.
+
+   If the internal clock fails, silently ignore the error and return 0.
+   On integer overflow, silently ignore the overflow and clamp the clock to
+   [_PyTime_MIN; _PyTime_MAX].
+
+   Use _PyTime_GetSystemClockWithInfo() to check for failure. */
+PyAPI_FUNC(_PyTime_t) _PyTime_GetSystemClock(void);
+
+/* Get the current time from the system clock.
+ * On success, set *t and *info (if not NULL), and return 0.
+ * On error, raise an exception and return -1.
+ */
+PyAPI_FUNC(int) _PyTime_GetSystemClockWithInfo(
+    _PyTime_t *t,
+    _Py_clock_info_t *info);
+
+/* Get the time of a monotonic clock, i.e. a clock that cannot go backwards.
+   The clock is not affected by system clock updates. The reference point of
+   the returned value is undefined, so that only the difference between the
+   results of consecutive calls is valid.
+
+   If the internal clock fails, silently ignore the error and return 0.
+   On integer overflow, silently ignore the overflow and clamp the clock to
+   [_PyTime_MIN; _PyTime_MAX].
+
+   Use _PyTime_GetMonotonicClockWithInfo() to check for failure. */
+PyAPI_FUNC(_PyTime_t) _PyTime_GetMonotonicClock(void);
+
+/* Get the time of a monotonic clock, i.e. a clock that cannot go backwards.
+   The clock is not affected by system clock updates. The reference point of
+   the returned value is undefined, so that only the difference between the
+   results of consecutive calls is valid.
+
+   Fill info (if set) with information of the function used to get the time.
+
+   Return 0 on success, raise an exception and return -1 on error. */
+PyAPI_FUNC(int) _PyTime_GetMonotonicClockWithInfo(
+    _PyTime_t *t,
+    _Py_clock_info_t *info);
+
+
+/* Converts a timestamp to the Gregorian time, using the local time zone.
+   Return 0 on success, raise an exception and return -1 on error. */
+PyAPI_FUNC(int) _PyTime_localtime(time_t t, struct tm *tm);
+
+/* Converts a timestamp to the Gregorian time, assuming UTC.
+   Return 0 on success, raise an exception and return -1 on error. */
+PyAPI_FUNC(int) _PyTime_gmtime(time_t t, struct tm *tm);
+
+/* Get the performance counter: clock with the highest available resolution to
+   measure a short duration.
+
+   If the internal clock fails, silently ignore the error and return 0.
+   On integer overflow, silently ignore the overflow and clamp the clock to
+   [_PyTime_MIN; _PyTime_MAX].
+
+   Use _PyTime_GetPerfCounterWithInfo() to check for failure. */
+PyAPI_FUNC(_PyTime_t) _PyTime_GetPerfCounter(void);
+
+/* Get the performance counter: clock with the highest available resolution to
+   measure a short duration.
+
+   Fill info (if set) with information of the function used to get the time.
+
+   Return 0 on success, raise an exception and return -1 on error. */
+PyAPI_FUNC(int) _PyTime_GetPerfCounterWithInfo(
+    _PyTime_t *t,
+    _Py_clock_info_t *info);
+
+
+// Create a deadline.
+// Pseudo code: _PyTime_GetMonotonicClock() + timeout.
+PyAPI_FUNC(_PyTime_t) _PyDeadline_Init(_PyTime_t timeout);
+
+// Get remaining time from a deadline.
+// Pseudo code: deadline - _PyTime_GetMonotonicClock().
+PyAPI_FUNC(_PyTime_t) _PyDeadline_Get(_PyTime_t deadline);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* Py_PYTIME_H */
+#endif /* Py_LIMITED_API */