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 and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
time.time() documentation should mention UTC timezone #73212
Comments
The documentation of the time.time() mentions "epoch" which it doesn't define epoch. If I recall correctly, it's January 1st, 1970 on most OS and most implementations of Python, except of IronPython which uses a different epoch. https://docs.python.org/dev/library/time.html#time.time Moreover, the timezone is not defined. In practice, it's UTC, so it would be nice to document it. I opened this issue because I wasn't sure if time.time() is impacted by DST or not. The answer is no. Maybe the behaviour of time.time() on DST should also be documentation. Hint: it is not impacted by DST since it uses UTC timezone. Related question on StackOverflow: |
time.time() is not quite UTC on Unix: it usually (*) doesn't include leap seconds, which UTC does. The Wikipedia page has a good definition and explanation: https://en.wikipedia.org/wiki/Unix_time (*) "usually" because POSIX defines time() to not include leap seconds, but on some older or not quite POSIX compliant Unix systems, leap seconds are included. |
Handling time is a complex task, so we should enhance the doc to help users. If there are multiple cases, we can list them: "time.time() uses UTC timezone with or without leap seconds". Maybe with a link to https://en.wikipedia.org/wiki/Unix_time ? |
I would be happy to work on a documentation patch for this - I'll try to have something up by tomorrow evening if no one beats me to it. |
I looked at the documentation and implementation and made a patch to hopefully clarify the issue. I also have some comments:
|
Another suggestion: mention localtime() and gmtime() in time() documentation to explain how to convert such timestamp to a more common date format. |
I had some checks performed on a Windows platform using the following snippet: # valid for 2016
import time
def check():
t = time.gmtime()
print(46*86400*365 + 11*86400 + (t.tm_yday-1)*86400 + t.tm_hour*3600 + t.tm_min*60 + t.tm_sec)
print(time.time())
print(time.gmtime(0))
check() This ensures that the time since the epoch is counted excluding leap seconds if the first two lines of output are approximately the same (to nearest second), and finally that the epoch is the Unix epoch. On Python 3.6.0 (v3.6.0:41df79263a11, Dec 23 2016, 07:18:10) [MSC v.1900 32 bit (Intel)] on win32 I see: 1482502941 Unless there is major variation among windows versions on how FILETIMEs are calculated and the results of basic system calls, I feel fairly confident now that the calculation of time since the epoch in CPython is the same on Windows as it is in POSIX-compliant platforms. |
As we have moved to GitHub and mandatory reviews with Pull Requests, I have created a new patch in PR#34 which incorporates Victor's suggestions. |
Hi, does this need backport to 2.7? |
Mariatta: "Hi, does this need backport to 2.7? I'm getting a lot of conflicts while trying to do that... Not sure how to proceed." I think it's ok to leave Python 2.7 doc unchanged. It's only a minor doc enhancement, the 2.7 doc is still correct. I close the issue. |
Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.
Show more details
GitHub fields:
bugs.python.org fields:
The text was updated successfully, but these errors were encountered: