bpo-29026: Clarify documentation of time.time #34
Conversation
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.
|
Thank you for the new doc. It contains more info on timezone (UTC) and leap seconds (excluded). |
Doc/library/time.rst
Outdated
| 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>`_. |
There was a problem hiding this comment.
IMHO it's worth it to repeat here:
To find out what the epoch is on a given platform, look at gmtime(0).
There was a problem hiding this comment.
Repeated in d387bf7
Doc/library/time.rst
Outdated
| @@ -572,12 +579,27 @@ The module defines the following functions and data items: | |||
|
|
|||
| .. 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 | |||
There was a problem hiding this comment.
You should add a link on the "epoch" word to its definition.
There was a problem hiding this comment.
Added link in d387bf7
Doc/library/time.rst
Outdated
| 1970. To find out what the epoch is, look at ``gmtime(0)``. | ||
| * The :dfn:`epoch` is the point where the time starts, and is platform | ||
| dependent. For Unix, the epoch is January 1, 1970, 00:00:00 (UTC). | ||
| To find out what the epoch is on a given platform, look at ``gmtime(0)``. |
There was a problem hiding this comment.
I assume gmtime(0) is time.gmtime(0) here. If I'm correct, we can use this as an opportunity to make it clearer.
There was a problem hiding this comment.
I changed it to time.gmtime(0) where it first appears in d387bf7. However, when the statement is repeated in the documentation of time.time, I retain gmtime(0) as this appears to be the convention used in all the function docs for the module.
There was a problem hiding this comment.
Oops, failed to amend commit before pushing, I fixed to use doc conventions in 263a4f4
Doc/library/time.rst
Outdated
|
|
||
| * The term :dfn:`seconds since the epoch` refers to the total number | ||
| of elapsed seconds since the epoch, typically excluding | ||
| `leap seconds <https://en.wikipedia.org/wiki/Leap_second>`_. |
There was a problem hiding this comment.
I'd say add
.. `leap seconds`: https://en.wikipedia.org/wiki/Leap_secondand use
`leap-seconds`_everytime you need the Wikipedia article.
(I might the syntax got wrong so please try first :))
There was a problem hiding this comment.
Added in d387bf7, also changed one other mention of leap seconds to link.
There was a problem hiding this comment.
Whoops, failed to add to amended commit before push - added that other mention in 263a4f4
Codecov Report
@@ Coverage Diff @@
## master #34 +/- ##
==========================================
+ Coverage 82.37% 82.38% +0.01%
==========================================
Files 1427 1428 +1
Lines 350948 351138 +190
==========================================
+ Hits 289088 289294 +206
+ Misses 61860 61844 -16Continue to review full report at Codecov.
|
|
Thanks! I merged the PR. |
* 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. * bpo-29026: Minor improvements for time.time doc * bpo-29026: Consistency fixes for time.time doc (cherry picked from commit 23557d5)
* 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. * bpo-29026: Minor improvements for time.time doc * bpo-29026: Consistency fixes for time.time doc (cherry picked from commit 23557d5)
ghost
mentioned this pull request
munmap pages on shutdown, keep FILE open
API documentation. Closes python#16
* fix: mark interpreter frames as tier 2 or not * Test: Added tests for python#33 --------- Co-authored-by: Ken Jin <[email protected]>
…h_recent_assumptions Warn for string cmp with new string warning assumptions
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.
@Haypo
https://bugs.python.org/issue29026