This issue tracker has been migrated to GitHub, and is currently read-only.
For more information, see the GitHub FAQs in the Python's Developer Guide.

classification
Title: Fix documentation of epoch/time.time
Type: enhancement Stage: resolved
Components: Documentation Versions: Python 3.11
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: docs@python Nosy List: Ofekmeister, docs@python, miguendes, p-ganssle, vstinner
Priority: normal Keywords: patch

Created on 2021-04-16 15:15 by Ofekmeister, last changed 2022-04-11 14:59 by admin. This issue is now closed.

Pull Requests
URL Status Linked Edit
PR 25777 merged miguendes, 2021-05-01 10:51
PR 30664 merged vstinner, 2022-01-18 16:21
Messages (8)
msg391214 - (view) Author: Ofek Lev (Ofekmeister) * Date: 2021-04-16 15:15
The descriptions for the following:

- https://docs.python.org/3/library/time.html#epoch
- https://docs.python.org/3/library/time.html#time.time

indicate that it is platform dependent. However, that is likely untrue. See the brief discussion here: https://github.com/DataDog/integrations-core/pull/6692#discussion_r427469097
msg391215 - (view) Author: STINNER Victor (vstinner) * (Python committer) Date: 2021-04-16 15:21
On Windows 10 (build 20H2), I get:

Python 3.10.0a7+ (heads/master:b136b1aac4, Apr 16 2021, 14:36:39) [MSC v.1928 64 bit (AMD64)] on win32
>>> import time
>>> time.gmtime(0)
time.struct_time(tm_year=1970, tm_mon=1, tm_mday=1, tm_hour=0, tm_min=0, tm_sec=0, tm_wday=3, tm_yday=1, tm_isdst=0)
msg391216 - (view) Author: STINNER Victor (vstinner) * (Python committer) Date: 2021-04-16 15:22
time.time doc says "On Windows and most Unix systems, the epoch is January 1, 1970, 00:00:00 (UTC)"

The epoch doc says "For Unix, the epoch is January 1, 1970, 00:00:00 (UTC)".

At least, the epoch doc can be completed to also mention that it's the same on Windows.
msg391218 - (view) Author: STINNER Victor (vstinner) * (Python committer) Date: 2021-04-16 15:31
"platform dependent" was added in 2017 by the commit (bpo-29026): 

commit 23557d59b819f57800ddef0b1373acef8e024670
Author: Eric Appelt <eric.appelt@gmail.com>
Date:   Thu Feb 16 05:00:45 2017 -0500

    bpo-29026: Clarify documentation of time.time (#34)
    
    * 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

---

MS-DOS (no longer supported by Python since 2014) uses 1980-01-01 epoch.

The Windows FILETIME type uses 1601-01-01 epoch. Python has convention functions to the Unix 1970-01-01 Epoch:

static __int64 secs_between_epochs = 11644473600; /* Seconds between 1.1.1601 and 1.1.1970 */

static void
FILE_TIME_to_time_t_nsec(FILETIME *in_ptr, time_t *time_out, int* nsec_out)
{
    /* XXX endianness. Shouldn't matter, as all Windows implementations are little-endian */
    /* Cannot simply cast and dereference in_ptr,
       since it might not be aligned properly */
    __int64 in;
    memcpy(&in, in_ptr, sizeof(in));
    *nsec_out = (int)(in % 10000000) * 100; /* FILETIME is in units of 100 nsec. */
    *time_out = Py_SAFE_DOWNCAST((in / 10000000) - secs_between_epochs, __int64, time_t);
}

void
_Py_time_t_to_FILE_TIME(time_t time_in, int nsec_in, FILETIME *out_ptr)
{
    /* XXX endianness */
    __int64 out;
    out = time_in + secs_between_epochs;
    out = out * 10000000 + nsec_in / 100;
    memcpy(out_ptr, &out, sizeof(out));
}

More epochs for more fun:
https://en.wikipedia.org/wiki/Epoch_(computing)#Notable_epoch_dates_in_computing
msg392583 - (view) Author: Miguel Brito (miguendes) * Date: 2021-05-01 10:52
Seen that no one is working on this issue I created an PR to clarify the docs.

https://github.com/python/cpython/pull/25777
msg410875 - (view) Author: STINNER Victor (vstinner) * (Python committer) Date: 2022-01-18 15:55
New changeset ff7703c4b609a697ada8165fd1c52a73404b6d07 by Miguel Brito in branch 'main':
bpo-43869: Improve epoch docs (GH-25777)
https://github.com/python/cpython/commit/ff7703c4b609a697ada8165fd1c52a73404b6d07
msg410876 - (view) Author: STINNER Victor (vstinner) * (Python committer) Date: 2022-01-18 16:25
I was going to close the change, but I had a last look and... oh... I found that the Python test suite checks that the Epoch is 1970-01-01 at 00:00 since 2008! I wrote GH-30664 to add an explicit test and I updated the doc.
msg410934 - (view) Author: STINNER Victor (vstinner) * (Python committer) Date: 2022-01-19 10:27
New changeset a847785b40ed8819bde2dac5849dc31d15e99a74 by Victor Stinner in branch 'main':
  bpo-43869: Time Epoch is the same on all platforms (GH-30664)
https://github.com/python/cpython/commit/a847785b40ed8819bde2dac5849dc31d15e99a74
History
Date User Action Args
2022-04-11 14:59:44adminsetgithub: 88035
2022-01-19 10:27:50vstinnersetstatus: open -> closed
resolution: fixed
stage: patch review -> resolved
2022-01-19 10:27:36vstinnersetmessages: + msg410934
2022-01-18 17:49:46iritkatrielsetversions: + Python 3.11, - Python 3.6, Python 3.7, Python 3.8, Python 3.9, Python 3.10
2022-01-18 16:25:39vstinnersetmessages: + msg410876
2022-01-18 16:21:09vstinnersetpull_requests: + pull_request28865
2022-01-18 15:55:37vstinnersetmessages: + msg410875
2021-05-01 10:52:18miguendessetmessages: + msg392583
2021-05-01 10:51:35miguendessetkeywords: + patch
nosy: + miguendes

pull_requests: + pull_request24467
stage: patch review
2021-04-16 15:31:39vstinnersetmessages: + msg391218
2021-04-16 15:22:52vstinnersetmessages: + msg391216
2021-04-16 15:21:01vstinnersetnosy: + vstinner
messages: + msg391215
2021-04-16 15:15:58Ofekmeistercreate