@@ -19,9 +19,16 @@ An explanation of some terminology and conventions is in order.
19
19
20
20
.. index :: single: epoch
21
21
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.
25
32
26
33
.. index :: single: Year 2038
27
34
@@ -572,12 +579,27 @@ The module defines the following functions and data items:
572
579
573
580
.. function :: time()
574
581
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
+
576
591
Note that even though the time is always returned as a floating point
577
592
number, not all systems provide time with a better precision than 1 second.
578
593
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.
581
603
582
604
.. data :: timezone
583
605
0 commit comments