[docs] [issue29026] time.time() documentation should mention UTC timezone

Eric Appelt report at bugs.python.org
Thu Dec 22 23:58:56 EST 2016

Eric Appelt added the comment:

I looked at the documentation and implementation and made a patch to hopefully clarify the issue. I also have some comments:

- The term "epoch" is actually defined at the top of the page with instructions for how to determine it, i.e. run "gmtime(0)".

- I added a definition for the term "seconds since the epoch" since this typically means the number of seconds that have elapsed since the epoch excluding leap seconds, although it may vary by platform.

- I'm a bit uncomfortable with potential confusion regarding Windows, since the Windows epoch begins on 1601, although we adjust it to 1970: https://github.com/python/cpython/blob/d739274e7b69f63263054cc24684e7e637264350/Python/pytime.c#L536-L539 I didn't add a note in the patch as I am not a windows developer, but I wonder if there could be some confusion.

- Even though its redundant with the top of the page, I added specific clarification to time.time() as it appears that most readers are going to navigate to that anchor specifically and not read the discussion of what we mean by "epoch" above.

- I need to test my assertion that Windows does not count leap seconds. I'm pretty sure but not 100% confident that I am correct from what I read, but I need to find someone with a windows machine tomorrow and actually check it. The windows documentation for the FILETIME structure suggests that leap seconds might be counted - https://msdn.microsoft.com/en-us/library/windows/desktop/ms724284(v=vs.85).aspx - but I think this is just an oversight in the documentation.

- Just out of personal curiousity does anyone have an example of a legacy UNIX system that counts leap seconds in the epoch? This seems tricky to do as I would presume that the OS would need some table that would be updated whenever the astronomers declare a new leap second.

keywords: +patch
Added file: http://bugs.python.org/file46005/29026_unixtime_v1.patch

Python tracker <report at bugs.python.org>

More information about the docs mailing list