From a847785b40ed8819bde2dac5849dc31d15e99a74 Mon Sep 17 00:00:00 2001 From: Victor Stinner Date: Wed, 19 Jan 2022 11:27:11 +0100 Subject: bpo-43869: Time Epoch is the same on all platforms (GH-30664) --- Doc/library/time.rst | 28 +++++++++------------- Lib/test/test_time.py | 7 ++++++ .../2022-01-18-17-24-21.bpo-43869.NayN12.rst | 2 ++ 3 files changed, 20 insertions(+), 17 deletions(-) create mode 100644 Misc/NEWS.d/next/Library/2022-01-18-17-24-21.bpo-43869.NayN12.rst diff --git a/Doc/library/time.rst b/Doc/library/time.rst index 3a77120..d524f4f 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 `_. - 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 `_. 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 1aa5874..1c444e3 100644 --- a/Lib/test/test_time.py +++ b/Lib/test/test_time.py @@ -159,6 +159,13 @@ class TimeTestCase(unittest.TestCase): 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 0000000..5486c95 --- /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. -- cgit v0.12