Fix documentation of epoch/time.time

[ofek]

BPO	43869
Nosy	@vstinner, @ofek, @pganssle, @miguendes
PRs	bpo-43869: Improve epoch docs #25777 bpo-43869: Time Epoch is the same on all platforms #30664

^{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:

assignee = None
closed_at = <Date 2022-01-19.10:27:50.486>
created_at = <Date 2021-04-16.15:15:58.550>
labels = ['3.11', 'type-feature', 'docs']
title = 'Fix documentation of epoch/time.time'
updated_at = <Date 2022-01-19.10:27:50.485>
user = 'https://github.com/ofek'

bugs.python.org fields:

activity = <Date 2022-01-19.10:27:50.485>
actor = 'vstinner'
assignee = 'docs@python'
closed = True
closed_date = <Date 2022-01-19.10:27:50.486>
closer = 'vstinner'
components = ['Documentation']
creation = <Date 2021-04-16.15:15:58.550>
creator = 'Ofekmeister'
dependencies = []
files = []
hgrepos = []
issue_num = 43869
keywords = ['patch']
message_count = 8.0
messages = ['391214', '391215', '391216', '391218', '392583', '410875', '410876', '410934']
nosy_count = 5.0
nosy_names = ['vstinner', 'docs@python', 'Ofekmeister', 'p-ganssle', 'miguendes']
pr_nums = ['25777', '30664']
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue43869'
versions = ['Python 3.11']

Linked PRs

• gh-88035: update doc-string of epoch in timemodule.c #118076
• [3.12] gh-88035: update doc-string of epoch in timemodule.c (GH-118076) #118097

[ofek]

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: DataDog/integrations-core#6692 (comment)

[vstinner]

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)

[vstinner]

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.

[vstinner]

"platform dependent" was added in 2017 by the commit (bpo-29026):

commit 23557d5
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

[miguendes]

Seen that no one is working on this issue I created an PR to clarify the docs.

#25777

[vstinner]

New changeset ff7703c by Miguel Brito in branch 'main':
bpo-43869: Improve epoch docs (GH-25777)
ff7703c

[vstinner]

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 #74849 to add an explicit test and I updated the doc.

[vstinner]

New changeset a847785 by Victor Stinner in branch 'main':
bpo-43869: Time Epoch is the same on all platforms (GH-30664)
a847785