[Python-checkins] bpo-43869: Time Epoch is the same on all platforms (GH-30664)

[vstinner]

https://github.com/python/cpython/commit/a847785b40ed8819bde2dac5849dc31d15e99a74
commit: a847785b40ed8819bde2dac5849dc31d15e99a74
branch: main
author: Victor Stinner <vstinner at python.org>
committer: vstinner <vstinner at python.org>
date: 2022-01-19T11:27:11+01:00
summary:

  bpo-43869: Time Epoch is the same on all platforms (GH-30664)

files:
A Misc/NEWS.d/next/Library/2022-01-18-17-24-21.bpo-43869.NayN12.rst
M Doc/library/time.rst
M Lib/test/test_time.py

diff --git a/Doc/library/time.rst b/Doc/library/time.rst
index 3a771208519b4..d524f4ffebc75 100644
--- a/Doc/library/time.rst
+++ b/Doc/library/time.rst
@@ -21,10 +21,8 @@ An explanation of some terminology and conventions is in order.
 
 .. index:: single: epoch
 
-* The :dfn:`epoch` is the point where the time starts, and is platform
-  dependent.  For Unix and Windows, the epoch is January 1, 1970, 00:00:00 (UTC).
-  To find out what the epoch is on a given platform, look at
-  ``time.gmtime(0)``.
+* The :dfn:`epoch` is the point where the time starts, the return value of
+  ``time.gmtime(0)``. It is January 1, 1970, 00:00:00 (UTC) on all platforms.
 
 .. _leap seconds: https://en.wikipedia.org/wiki/Leap_second
 
@@ -37,7 +35,7 @@ An explanation of some terminology and conventions is in order.
 
 .. index:: single: Year 2038
 
-* The functions in this module may not handle dates and times before the epoch or
+* The functions in this module may not handle dates and times before the epoch_ or
   far in the future.  The cut-off point in the future is determined by the C
   library; for 32-bit systems, it is typically in 2038.
 
@@ -207,7 +205,7 @@ Functions
 
 .. function:: ctime([secs])
 
-   Convert a time expressed in seconds since the epoch to a string of a form:
+   Convert a time expressed in seconds since the epoch_ to a string of a form:
    ``'Sun Jun 20 23:21:05 1993'`` representing local time. The day field
    is two characters long and is space padded if the day is a single digit,
    e.g.: ``'Wed Jun  9 04:26:40 1993'``.
@@ -245,7 +243,7 @@ Functions
 
 .. function:: gmtime([secs])
 
-   Convert a time expressed in seconds since the epoch to a :class:`struct_time` in
+   Convert a time expressed in seconds since the epoch_ to a :class:`struct_time` in
    UTC in which the dst flag is always zero.  If *secs* is not provided or
    :const:`None`, the current time as returned by :func:`.time` is used.  Fractions
    of a second are ignored.  See above for a description of the
@@ -601,14 +599,10 @@ Functions
 .. function:: time() -> float
 
    Return the time in seconds since the epoch_ as a floating point
-   number. The specific date of the epoch and the handling of
-   `leap seconds`_ is platform dependent.
-   On Windows and most Unix systems, the epoch is January 1, 1970,
-   00:00:00 (UTC) and leap seconds are not counted towards the time
-   in seconds since the epoch. This is commonly referred to as
-   `Unix time <https://en.wikipedia.org/wiki/Unix_time>`_.
-   To find out what the epoch is on a given platform, look at
-   ``gmtime(0)``.
+   number. The handling of `leap seconds`_ is platform dependent.
+   On Windows and most Unix systems, the leap seconds are not counted towards
+   the time in seconds since the epoch_. This is commonly referred to as `Unix
+   time <https://en.wikipedia.org/wiki/Unix_time>`_.
 
    Note that even though the time is always returned as a floating point
    number, not all systems provide time with a better precision than 1 second.
@@ -629,8 +623,8 @@ Functions
 
 .. function:: time_ns() -> int
 
-   Similar to :func:`~time.time` but returns time as an integer number of nanoseconds
-   since the epoch_.
+   Similar to :func:`~time.time` but returns time as an integer number of
+   nanoseconds since the epoch_.
 
    .. versionadded:: 3.7
 
diff --git a/Lib/test/test_time.py b/Lib/test/test_time.py
index 1aa5874dfe272..1c444e381a552 100644
--- a/Lib/test/test_time.py
+++ b/Lib/test/test_time.py
@@ -159,6 +159,13 @@ def test_sleep(self):
         self.assertRaises(ValueError, time.sleep, -1)
         time.sleep(1.2)
 
+    def test_epoch(self):
+        # bpo-43869: Make sure that Python use the same Epoch on all platforms:
+        # January 1, 1970, 00:00:00 (UTC).
+        epoch = time.gmtime(0)
+        # Only test the date and time, ignore other gmtime() members
+        self.assertEqual(tuple(epoch)[:6], (1970, 1, 1, 0, 0, 0), epoch)
+
     def test_strftime(self):
         tt = time.gmtime(self.t)
         for directive in ('a', 'A', 'b', 'B', 'c', 'd', 'H', 'I',
diff --git a/Misc/NEWS.d/next/Library/2022-01-18-17-24-21.bpo-43869.NayN12.rst b/Misc/NEWS.d/next/Library/2022-01-18-17-24-21.bpo-43869.NayN12.rst
new file mode 100644
index 0000000000000..5486c95b0689b
--- /dev/null
+++ b/Misc/NEWS.d/next/Library/2022-01-18-17-24-21.bpo-43869.NayN12.rst
@@ -0,0 +1,2 @@
+Python uses the same time Epoch on all platforms. Add an explicit unit test
+to ensure that it's the case. Patch by Victor Stinner.