mirrors/cpython
1
0
Fork 0
mirror of https://github.com/python/cpython.git synced 2025-10-05 22:51:56 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 8

bpo-29026: Clarify documentation of time.time (GH-34) (GH-418)

Browse source 
(cherry picked from commit 23557d59b8)
This commit is contained in:
Mariatta 2017-03-02 21:50:46 -08:00 • committed by GitHub
parent 80fbacc936
commit 8c851fa3d3
1 changed files with 35 additions and 7 deletions
Download patch file Download diff file Expand all files Collapse all files

42
Doc/library/time.rst
View file

@ -17,11 +17,23 @@ semantics of these functions varies among platforms.
An explanation of some terminology and conventions is in order. An explanation of some terminology and conventions is in order.
.. _epoch:
.. index:: single: epoch .. index:: single: epoch
* The :dfn:`epoch` is the point where the time starts. On January 1st of that * The :dfn:`epoch` is the point where the time starts, and is platform
year, at 0 hours, the "time since the epoch" is zero. For Unix, the epoch is dependent. For Unix, the epoch is January 1, 1970, 00:00:00 (UTC).
1970. To find out what the epoch is, look at ``gmtime(0)``. To find out what the epoch is on a given platform, look at
``time.gmtime(0)``.
.. _leap seconds: https://en.wikipedia.org/wiki/Leap_second
.. index:: seconds since the epoch
* The term :dfn:`seconds since the epoch` refers to the total number
of elapsed seconds since the epoch, typically excluding
`leap seconds`_. Leap seconds are excluded from this total on all
POSIX-compliant platforms.
.. index:: single: Year 2038 .. index:: single: Year 2038
@ -463,7 +475,7 @@ The module defines the following functions and data items:
(2) (2)
The range really is ``0`` to ``61``; value ``60`` is valid in The range really is ``0`` to ``61``; value ``60`` is valid in
timestamps representing leap seconds and value ``61`` is supported timestamps representing `leap seconds`_ and value ``61`` is supported
for historical reasons. for historical reasons.
(3) (3)
@ -572,12 +584,28 @@ The module defines the following functions and data items:
.. function:: time() .. function:: time()
Return the time in seconds since the epoch as a floating point number. 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)``.
Note that even though the time is always returned as a floating point 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. number, not all systems provide time with a better precision than 1 second.
While this function normally returns non-decreasing values, it can return a While this function normally returns non-decreasing values, it can return a
lower value than a previous call if the system clock has been set back between lower value than a previous call if the system clock has been set back
the two calls. between the two calls.
The number returned by :func:`.time` may be converted into a more common
time format (i.e. year, month, day, hour, etc...) in UTC by passing it to
:func:`gmtime` function or in local time by passing it to the
:func:`localtime` function. In both cases a
:class:`struct_time` object is returned, from which the components
of the calendar date may be accessed as attributes.
.. data:: timezone .. data:: timezone