Uh oh!
There was an error while loading.Please reload this page.
- Notifications
You must be signed in to change notification settings - Fork32k
bpo-29026: Clarify documentation of time.time#34
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to ourterms of service andprivacy statement. We’ll occasionally send you account related emails.
Already on GitHub?Sign in to your account
Uh oh!
There was an error while loading.Please reload this page.
Conversation
Clarify the documentation of time.time by moreprecisely defining what is meant by "seconds sincethe epoch" on most platforms. Additionally explainhow gmtime and localtime may be used to extractcalendar components and convert to a more commondate format.
Thank you for the new doc. It contains more info on timezone (UTC) and leap seconds (excluded). |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
Sorry, I saw a few more minor issues.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
IMHO it's worth it to repeat here:
To find out what the epoch is on a given platform, look atgmtime(0).
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
Repeated ind387bf7
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
You should add a link on the "epoch" word to its definition.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
Added link ind387bf7
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
I assumegmtime(0) istime.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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
I changed it totime.gmtime(0) where it first appears ind387bf7. However, when the statement is repeated in the documentation oftime.time, I retaingmtime(0) as this appears to be the convention used in all the function docs for the module.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
Added ind387bf7, also changed one other mention of leap seconds to link.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
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 -16 Continue to review full report at Codecov.
|
Thanks! I merged the PR. |
* bpo-29026: Clarity documentation of time.timeClarify the documentation of time.time by moreprecisely defining what is meant by "seconds sincethe epoch" on most platforms. Additionally explainhow gmtime and localtime may be used to extractcalendar components and convert to a more commondate format.* bpo-29026: Minor improvements for time.time doc* bpo-29026: Consistency fixes for time.time doc(cherry picked from commit23557d5)
* bpo-29026: Clarity documentation of time.timeClarify the documentation of time.time by moreprecisely defining what is meant by "seconds sincethe epoch" on most platforms. Additionally explainhow gmtime and localtime may be used to extractcalendar components and convert to a more commondate format.* bpo-29026: Minor improvements for time.time doc* bpo-29026: Consistency fixes for time.time doc(cherry picked from commit23557d5)
munmap pages on shutdown, keep FILE open
API documentation.Closespython#16
* fix: mark interpreter frames as tier 2 or not* Test: Added tests forpython#33---------Co-authored-by: Ken Jin <28750310+Fidget-Spinner@users.noreply.github.com>
…h_recent_assumptionsWarn 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