gh-67795: Accept any real numbers as timestamp and timeout

Functions that take timestamp or timeout arguments now accept any
real numbers, not only integers or floats, although this does not
improve precision.

Author: serhiy-storchaka

Doc/library/datetime.rst

@@ -535,6 +535,9 @@ Other constructors, all class methods:
       :c:func:`localtime` function. Raise :exc:`OSError` instead of
       :exc:`ValueError` on :c:func:`localtime` failure.
 
+   .. versionchanged:: next
+      Accepts any real number as *timestamp*, not only integer or float.
+
 
 .. classmethod:: date.fromordinal(ordinal)
 
@@ -1020,6 +1023,10 @@ Other constructors, all class methods:
    .. versionchanged:: 3.6
       :meth:`fromtimestamp` may return instances with :attr:`.fold` set to 1.
 
+   .. versionchanged:: next
+      Accepts any real number as *timestamp*, not only integer or float.
+
+
 .. classmethod:: datetime.utcfromtimestamp(timestamp)
 
    Return the UTC :class:`.datetime` corresponding to the POSIX timestamp, with
@@ -1060,6 +1067,9 @@ Other constructors, all class methods:
 
       Use :meth:`datetime.fromtimestamp` with :const:`UTC` instead.
 
+   .. versionchanged:: next
+      Accepts any real number as *timestamp*, not only integer or float.
+
 
 .. classmethod:: datetime.fromordinal(ordinal)
 

Doc/library/os.rst

@@ -3618,7 +3618,8 @@ features:
      where each member is an int expressing nanoseconds.
    - If *times* is not ``None``,
      it must be a 2-tuple of the form ``(atime, mtime)``
-     where each member is an int or float expressing seconds.
+     where each member is a real number expressing seconds,
+     rounded down to nanoseconds.
    - If *times* is ``None`` and *ns* is unspecified,
      this is equivalent to specifying ``ns=(atime_ns, mtime_ns)``
      where both times are the current time.
@@ -3645,6 +3646,9 @@ features:
    .. versionchanged:: 3.6
       Accepts a :term:`path-like object`.
 
+   .. versionchanged:: next
+      Accepts any real numbers as *times*, not only integers or floats.
+
 
 .. function:: walk(top, topdown=True, onerror=None, followlinks=False)
 
@@ -4050,7 +4054,7 @@ Naturally, they are all only available on Linux.
    the timer will fire when the timer's clock
    (set by *clockid* in :func:`timerfd_create`) reaches *initial* seconds.
 
-   The timer's interval is set by the *interval* :py:class:`float`.
+   The timer's interval is set by the *interval* real number.
    If *interval* is zero, the timer only fires once, on the initial expiration.
    If *interval* is greater than zero, the timer fires every time *interval*
    seconds have elapsed since the previous expiration.

Doc/library/select.rst

@@ -129,8 +129,9 @@ The module defines the following:
 
    Empty iterables are allowed, but acceptance of three empty iterables is
    platform-dependent. (It is known to work on Unix but not on Windows.)  The
-   optional *timeout* argument specifies a time-out as a floating-point number
-   in seconds.  When the *timeout* argument is omitted the function blocks until
+   optional *timeout* argument specifies a time-out in seconds; it may be
+   a non-integer to specify fractions of seconds.
+   When the *timeout* argument is omitted the function blocks until
    at least one file descriptor is ready.  A time-out value of zero specifies a
    poll and never blocks.
 
@@ -164,6 +165,9 @@ The module defines the following:
       :pep:`475` for the rationale), instead of raising
       :exc:`InterruptedError`.
 
+   .. versionchanged:: next
+      Accepts any real number as *timeout*, not only integer or float.
+
 
 .. data:: PIPE_BUF
 
@@ -270,6 +274,9 @@ object.
       :pep:`475` for the rationale), instead of raising
       :exc:`InterruptedError`.
 
+   .. versionchanged:: next
+      Accepts any real number as *timeout*, not only integer or float.
+
 
 .. _epoll-objects:
 
@@ -368,14 +375,19 @@ Edge and Level Trigger Polling (epoll) Objects
 
 .. method:: epoll.poll(timeout=None, maxevents=-1)
 
-   Wait for events. timeout in seconds (float)
+   Wait for events.
+   If *timeout* is given, it specifies the length of time in seconds
+   (may be non-integer) which the system will wait for events before returning.
 
    .. versionchanged:: 3.5
       The function is now retried with a recomputed timeout when interrupted by
       a signal, except if the signal handler raises an exception (see
       :pep:`475` for the rationale), instead of raising
       :exc:`InterruptedError`.
 
+   .. versionchanged:: next
+      Accepts any real number as *timeout*, not only integer or float.
+
 
 .. _poll-objects:
 
@@ -464,6 +476,9 @@ linearly scanned again. :c:func:`!select` is *O*\ (*highest file descriptor*), w
       :pep:`475` for the rationale), instead of raising
       :exc:`InterruptedError`.
 
+   .. versionchanged:: next
+      Accepts any real number as *timeout*, not only integer or float.
+
 
 .. _kqueue-objects:
 
@@ -496,7 +511,7 @@ Kqueue Objects
 
    - changelist must be an iterable of kevent objects or ``None``
    - max_events must be 0 or a positive integer
-   - timeout in seconds (floats possible); the default is ``None``,
+   - timeout in seconds (non-integers are possible); the default is ``None``,
      to wait forever
 
    .. versionchanged:: 3.5
@@ -505,6 +520,9 @@ Kqueue Objects
       :pep:`475` for the rationale), instead of raising
       :exc:`InterruptedError`.
 
+   .. versionchanged:: next
+      Accepts any real number as *timeout*, not only integer or float.
+
 
 .. _kevent-objects:
 

Doc/library/signal.rst

@@ -478,11 +478,11 @@ The :mod:`signal` module defines the following functions:
    .. versionadded:: 3.3
 
 
-.. function:: setitimer(which, seconds, interval=0.0)
+.. function:: setitimer(which, seconds, interval=0)
 
    Sets given interval timer (one of :const:`signal.ITIMER_REAL`,
    :const:`signal.ITIMER_VIRTUAL` or :const:`signal.ITIMER_PROF`) specified
-   by *which* to fire after *seconds* (float is accepted, different from
+   by *which* to fire after *seconds* (rounded up to microseconds, different from
    :func:`alarm`) and after that every *interval* seconds (if *interval*
    is non-zero). The interval timer specified by *which* can be cleared by
    setting *seconds* to zero.
@@ -493,13 +493,18 @@ The :mod:`signal` module defines the following functions:
    :const:`signal.ITIMER_VIRTUAL` sends :const:`SIGVTALRM`,
    and :const:`signal.ITIMER_PROF` will deliver :const:`SIGPROF`.
 
-   The old values are returned as a tuple: (delay, interval).
+   The old values are returned as a two-tuple of floats:
+   (``delay``, ``interval``).
 
    Attempting to pass an invalid interval timer will cause an
    :exc:`ItimerError`.
 
    .. availability:: Unix.
 
+   .. versionchanged:: next
+      Accepts any real numbers as *seconds* and *interval*, not only integers
+      or floats.
+
 
 .. function:: getitimer(which)
 
@@ -676,6 +681,9 @@ The :mod:`signal` module defines the following functions:
       by a signal not in *sigset* and the signal handler does not raise an
       exception (see :pep:`475` for the rationale).
 
+   .. versionchanged:: next
+      Accepts any real number as *timeout*, not only integer or float.
+
 
 .. _signal-example:
 

Doc/library/socket.rst

@@ -1407,11 +1407,14 @@ The :mod:`socket` module also offers various network-related services:
 
 .. function:: setdefaulttimeout(timeout)
 
-   Set the default timeout in seconds (float) for new socket objects.  When
+   Set the default timeout in seconds (real number) for new socket objects.  When
    the socket module is first imported, the default is ``None``.  See
    :meth:`~socket.settimeout` for possible values and their respective
    meanings.
 
+   .. versionchanged:: next
+      Accepts any real number, not only integer or float.
+
 
 .. function:: sethostname(name)
 
@@ -2073,7 +2076,7 @@ to sockets.
 .. method:: socket.settimeout(value)
 
    Set a timeout on blocking socket operations.  The *value* argument can be a
-   nonnegative floating-point number expressing seconds, or ``None``.
+   nonnegative real number expressing seconds, or ``None``.
    If a non-zero value is given, subsequent socket operations will raise a
    :exc:`timeout` exception if the timeout period *value* has elapsed before
    the operation has completed.  If zero is given, the socket is put in
@@ -2085,6 +2088,9 @@ to sockets.
       The method no longer toggles :const:`SOCK_NONBLOCK` flag on
       :attr:`socket.type`.
 
+   .. versionchanged:: next
+      Accepts any real number, not only integer or float.
+
 
 .. method:: socket.setsockopt(level, optname, value: int)
 .. method:: socket.setsockopt(level, optname, value: buffer)

Doc/library/threading.rst

@@ -608,7 +608,7 @@ since it is impossible to detect the termination of alien threads.
       timeout occurs.
 
       When the *timeout* argument is present and not ``None``, it should be a
-      floating-point number specifying a timeout for the operation in seconds
+      real number specifying a timeout for the operation in seconds
       (or fractions thereof). As :meth:`~Thread.join` always returns ``None``,
       you must call :meth:`~Thread.is_alive` after :meth:`~Thread.join` to
       decide whether a timeout happened -- if the thread is still alive, the
@@ -632,6 +632,9 @@ since it is impossible to detect the termination of alien threads.
 
          May raise :exc:`PythonFinalizationError`.
 
+      .. versionchanged:: next
+         Accepts any real number as *timeout*, not only integer or float.
+
    .. attribute:: name
 
       A string used for identification purposes only. It has no semantics.
@@ -764,7 +767,7 @@ All methods are executed atomically.
       If a call with *blocking* set to ``True`` would block, return ``False``
       immediately; otherwise, set the lock to locked and return ``True``.
 
-      When invoked with the floating-point *timeout* argument set to a positive
+      When invoked with the *timeout* argument set to a positive
       value, block for at most the number of seconds specified by *timeout*
       and as long as the lock cannot be acquired.  A *timeout* argument of ``-1``
       specifies an unbounded wait.  It is forbidden to specify a *timeout*
@@ -783,6 +786,9 @@ All methods are executed atomically.
       .. versionchanged:: 3.14
          Lock acquisition can now be interrupted by signals on Windows.
 
+      .. versionchanged:: next
+         Accepts any real number as *timeout*, not only integer or float.
+
 
    .. method:: release()
 
@@ -863,7 +869,7 @@ call release as many times the lock has been acquired can lead to deadlock.
          * If no thread owns the lock, acquire the lock and return immediately.
 
          * If another thread owns the lock, block until we are able to acquire
-           lock, or *timeout*, if set to a positive float value.
+           lock, or *timeout*, if set to a positive value.
 
          * If the same thread owns the lock, acquire the lock again, and
            return immediately. This is the difference between :class:`Lock` and
@@ -890,6 +896,9 @@ call release as many times the lock has been acquired can lead to deadlock.
       .. versionchanged:: 3.2
          The *timeout* parameter is new.
 
+      .. versionchanged:: next
+         Accepts any real number as *timeout*, not only integer or float.
+
 
    .. method:: release()
 
@@ -1023,7 +1032,7 @@ item to the buffer only needs to wake up one consumer thread.
       occurs.  Once awakened or timed out, it re-acquires the lock and returns.
 
       When the *timeout* argument is present and not ``None``, it should be a
-      floating-point number specifying a timeout for the operation in seconds
+      real number specifying a timeout for the operation in seconds
       (or fractions thereof).
 
       When the underlying lock is an :class:`RLock`, it is not released using
@@ -1150,6 +1159,9 @@ Semaphores also support the :ref:`context management protocol <with-locks>`.
       .. versionchanged:: 3.2
          The *timeout* parameter is new.
 
+      .. versionchanged:: next
+         Accepts any real number as *timeout*, not only integer or float.
+
    .. method:: release(n=1)
 
       Release a semaphore, incrementing the internal counter by *n*.  When it
@@ -1250,7 +1262,7 @@ method.  The :meth:`~Event.wait` method blocks until the flag is true.
       the internal flag did not become true within the given wait time.
 
       When the timeout argument is present and not ``None``, it should be a
-      floating-point number specifying a timeout for the operation in seconds,
+      real number specifying a timeout for the operation in seconds,
       or fractions thereof.
 
       .. versionchanged:: 3.1

Doc/library/time.rst

@@ -189,7 +189,7 @@ Functions
    .. versionadded:: 3.7
 
 
-.. function:: clock_settime(clk_id, time: float)
+.. function:: clock_settime(clk_id, time)
 
    Set the time of the specified clock *clk_id*.  Currently,
    :data:`CLOCK_REALTIME` is the only accepted value for *clk_id*.
@@ -201,6 +201,9 @@ Functions
 
    .. versionadded:: 3.3
 
+   .. versionchanged:: next
+      Accepts any real number as *time*, not only integer or float.
+
 
 .. function:: clock_settime_ns(clk_id, time: int)
 
@@ -223,6 +226,9 @@ Functions
    ``asctime(localtime(secs))``. Locale information is not used by
    :func:`ctime`.
 
+   .. versionchanged:: next
+      Accepts any real number, not only integer or float.
+
 
 .. function:: get_clock_info(name)
 
@@ -258,6 +264,9 @@ Functions
    :class:`struct_time` object. See :func:`calendar.timegm` for the inverse of this
    function.
 
+   .. versionchanged:: next
+      Accepts any real number, not only integer or float.
+
 
 .. function:: localtime([secs])
 
@@ -271,6 +280,9 @@ Functions
    :c:func:`gmtime` failure. It's common for this to be restricted to years
    between 1970 and 2038.
 
+   .. versionchanged:: next
+      Accepts any real number, not only integer or float.
+
 
 .. function:: mktime(t)
 
@@ -382,8 +394,7 @@ Functions
 .. function:: sleep(secs)
 
    Suspend execution of the calling thread for the given number of seconds.
-   The argument may be a floating-point number to indicate a more precise sleep
-   time.
+   The argument may be a non-integer to indicate a more precise sleep time.
 
    If the sleep is interrupted by a signal and no exception is raised by the
    signal handler, the sleep is restarted with a recomputed timeout.
@@ -428,6 +439,9 @@ Functions
    .. versionchanged:: 3.13
       Raises an auditing event.
 
+   .. versionchanged:: next
+      Accepts any real number, not only integer or float.
+
 .. index::
    single: % (percent); datetime format
 

Doc/whatsnew/3.15.rst

@@ -279,6 +279,11 @@ Other language changes
   and ends with a forward slash (``/``).
   (Contributed by Serhiy Storchaka in :gh:`134716`.)
 
+* Functions that take timestamp or timeout arguments now accept any
+  real numbers, not only integers or floats, although this does not
+  improve precision.
+  (Contributed by Serhiy Storchaka in :gh:`67795`.)
+
 
 New modules
 ===========