bpo-29026: Clarify documentation of time.time#34
Uh oh!
There was an error while loading. Please reload this page.
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.
vstinner commented Feb 12, 2017
Thank you for the new doc. It contains more info on timezone (UTC) and leap seconds (excluded). |
vstinner left a comment
vstinner left a comment There was a problem hiding this comment.
Sorry, I saw a few more minor issues.
| 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).
Doc/library/time.rst Outdated
| .. 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.
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.
|
vstinner commented Feb 16, 2017
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. Closespython#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
* fix missing `PyLazyImport_CheckExact` * fix missing lazy-related symbols * fix missing lazy-related symbols * `extern` seems enough * Export _PyImport_LoadLazyImportTstate for JIT
6 participants
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