bpo-29026: Clarify documentation of time.time by appeltel · Pull Request #34 · python/cpython (original) (raw)

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 our terms of service andprivacy statement. We’ll occasionally send you account related emails.

Already on GitHub?Sign in to your account

Conversation14 Commits3 Checks0 Files changed

Conversation

This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.Learn more about bidirectional Unicode characters

[ Show hidden characters]({{ revealButtonHref }})

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

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).

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.

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`_.

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 at gmtime(0).

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@@ -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

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.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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)``.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I assume gmtime(0) is time.gmtime(0) here. If I'm correct, we can use this as an opportunity to make it clearer.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

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


* 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`_.

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_second

and use

everytime you need the Wikipedia article.

(I might the syntax got wrong so please try first :))

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Added in d387bf7, also changed one other mention of leap seconds to link.

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

Merging #34 into master will increase coverage by 0.01%.
The diff coverage is n/a.

@@ 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.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update e7ffb99...263a4f4. Read the comment docs.

Mariatta referenced this pull request in Mariatta/cpython

Mar 3, 2017

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)

Mariatta referenced this pull request in Mariatta/cpython

Mar 3, 2017

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)

Mariatta added a commit that referenced this pull request

Mar 3, 2017

(cherry picked from commit 23557d5)

Mariatta added a commit that referenced this pull request

Mar 3, 2017

(cherry picked from commit 23557d5)

@ghost ghost mentioned this pull request