bpo-29026: Clarify documentation of time.time (GH-34) (GH-418) · python/cpython@8c851fa (original) (raw)
`@@ -17,11 +17,23 @@ semantics of these functions varies among platforms.
`
17
17
``
18
18
`An explanation of some terminology and conventions is in order.
`
19
19
``
``
20
`+
.. _epoch:
`
``
21
+
20
22
`.. index:: single: epoch
`
21
23
``
22
``
`` -
- The :dfn:
epochis 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)``.
``
24
`` +
- The :dfn:
epochis the point where the time starts, and is platform
``
``
25
`+
dependent. For Unix, the epoch is January 1, 1970, 00:00:00 (UTC).
`
``
26
`+
To find out what the epoch is on a given platform, look at
`
``
27
``time.gmtime(0)``.
``
28
+
``
29
`+
.. _leap seconds: https://en.wikipedia.org/wiki/Leap_second
`
``
30
+
``
31
`+
.. index:: seconds since the epoch
`
``
32
+
``
33
`` +
- The term :dfn:
seconds since the epochrefers to the total number
``
``
34
`+
of elapsed seconds since the epoch, typically excluding
`
``
35
`` +
leap seconds_. Leap seconds are excluded from this total on all
``
``
36
`+
POSIX-compliant platforms.
`
25
37
``
26
38
`.. index:: single: Year 2038
`
27
39
``
`@@ -463,7 +475,7 @@ The module defines the following functions and data items:
`
463
475
``
464
476
` (2)
`
465
477
``` The range really is 0 to 61; value 60 is valid in
`466`
``
``` -
timestamps representing leap seconds and value ``61`` is supported
``
478
timestamps representing `leap seconds`_ and value ``61`` is supported
467
479
` for historical reasons.
`
468
480
``
469
481
` (3)
`
`@@ -572,12 +584,28 @@ The module defines the following functions and data items:
`
572
584
``
573
585
`.. function:: time()
`
574
586
``
575
``
`-
Return the time in seconds since the epoch as a floating point number.
`
``
587
`+
Return the time in seconds since the epoch_ as a floating point
`
``
588
`+
number. The specific date of the epoch and the handling of
`
``
589
`` +
leap seconds_ is platform dependent.
``
``
590
`+
On Windows and most Unix systems, the epoch is January 1, 1970,
`
``
591
`+
00:00:00 (UTC) and leap seconds are not counted towards the time
`
``
592
`+
in seconds since the epoch. This is commonly referred to as
`
``
593
`` +
Unix time <https://en.wikipedia.org/wiki/Unix_time>_.
``
``
594
`+
To find out what the epoch is on a given platform, look at
`
``
595
``gmtime(0)``.
``
596
+
576
597
` Note that even though the time is always returned as a floating point
`
577
598
` number, not all systems provide time with a better precision than 1 second.
`
578
599
` 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.
`
``
600
`+
lower value than a previous call if the system clock has been set back
`
``
601
`+
between the two calls.
`
``
602
+
``
603
`` +
The number returned by :func:.time may be converted into a more common
``
``
604
`+
time format (i.e. year, month, day, hour, etc...) in UTC by passing it to
`
``
605
`` +
:func:gmtime function or in local time by passing it to the
``
``
606
`` +
:func:localtime function. In both cases a
``
``
607
`` +
:class:struct_time object is returned, from which the components
``
``
608
`+
of the calendar date may be accessed as attributes.
`
581
609
``
582
610
`.. data:: timezone
`
583
611
``