Skip to content

Commit 31ce20b

Browse files
committed
bpo-29026: Clarity documentation of time.time
Clarify the documentation of time.time by more precisely defining what is meant by "seconds since the epoch" on most platforms. Additionally explain how gmtime and localtime may be used to extract calendar components and convert to a more common date format.
1 parent e7ffb99 commit 31ce20b

File tree

1 file changed

+28
-6
lines changed

1 file changed

+28
-6
lines changed

Doc/library/time.rst

Lines changed: 28 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -19,9 +19,16 @@ An explanation of some terminology and conventions is in order.
1919

2020
.. index:: single: epoch
2121

22-
* The :dfn:`epoch` is the point where the time starts. On January 1st of that
23-
year, at 0 hours, the "time since the epoch" is zero. For Unix, the epoch is
24-
1970. To find out what the epoch is, look at ``gmtime(0)``.
22+
* The :dfn:`epoch` is the point where the time starts, and is platform
23+
dependent. For Unix, the epoch is January 1, 1970, 00:00:00 (UTC).
24+
To find out what the epoch is on a given platform, look at ``gmtime(0)``.
25+
26+
.. index:: seconds since the epoch
27+
28+
* The term :dfn:`seconds since the epoch` refers to the total number
29+
of elapsed seconds since the epoch, typically excluding
30+
`leap seconds <https://en.wikipedia.org/wiki/Leap_second>`_.
31+
Leap seconds are excluded from this total on all POSIX-compliant platforms.
2532

2633
.. index:: single: Year 2038
2734

@@ -572,12 +579,27 @@ The module defines the following functions and data items:
572579

573580
.. function:: time()
574581

575-
Return the time in seconds since the epoch as a floating point number.
582+
Return the time in seconds since the epoch as a floating point
583+
number. The specific date of the epoch and the handling of
584+
`leap seconds <https://en.wikipedia.org/wiki/Leap_second>`_
585+
is platform dependent.
586+
On Windows and most Unix systems, the epoch is January 1, 1970,
587+
00:00:00 (UTC) and leap seconds are not counted towards the time
588+
in seconds since the epoch. This is commonly referred to as
589+
`Unix time <https://en.wikipedia.org/wiki/Unix_time>`_.
590+
576591
Note that even though the time is always returned as a floating point
577592
number, not all systems provide time with a better precision than 1 second.
578593
While this function normally returns non-decreasing values, it can return a
579-
lower value than a previous call if the system clock has been set back between
580-
the two calls.
594+
lower value than a previous call if the system clock has been set back
595+
between the two calls.
596+
597+
The number returned by :func:`time` may be converted into a more common
598+
time format (i.e. year, month, day, hour, etc...) in UTC by passing it to
599+
:func:`gmtime` function or in local time by passing it to the
600+
:func:`localtime` function. In both cases a :class:`struct_time` object
601+
is returned, from which the components of the calendar date may be accessed
602+
as attributes.
581603

582604
.. data:: timezone
583605

0 commit comments

Comments
 (0)