Akira Li added the comment:
Alexander Belopolsky added the comment:
- It is not the job of the time module documentation to warn about
"many functions in the stdlib." What are these functions, BTW?
The e-mail linked in the first message of this issue msg226539 enumerates some of the functions:
- What is "calendar time in POSIX encoding"? This sounds like what time.asctime() returns.
It is the language used by C standard for time() function:
The time function determines the current calendar time. The encoding of the value is unspecified.
I think an improvement would be to spell Epoch with a capital E and define it as "The time zero hours, zero minutes, zero seconds, on January 1, 1970 Coordinated Universal Time (UTC)." See http://pubs.opengroup.org/onlinepubs/9699919799.
The word *epoch* (lowercase) is used by C standard.
It is not enough to say that time module uses POSIX epoch (Epoch) e.g., a machine may use "right" zoneinfo (the same epoch year 1970) but the timestamp for the same UTC time are different by number of leap seconds (10+25 since 2012).
POSIX encoding implies that the formula works:
utc_time = datetime(1970, 1, 1) + timedelta(seconds=posix_timestamp)
if time.time() doesn't return posix_timestamp than "many functions in the stdlib" will break.
It is possible to inspect all stdlib functions that use time module and determine for some of them whether they will break if gmtime(0) is not 1970 or "right" zoneinfo is used or any non-POSIX time encoding is used. But it is hard to maintain such a list because any future code change may affect the behavior. I prefer a vague statement ("many functions") over a possible lie (the documentation shouldn't make promises that the implementation can't keep).
POSIX language is (intentionally) vague and avoids SI seconds vs. UT1 (mean solar) seconds distinction. I don't consider systems where "seconds" doesn't mean SI seconds used by UTC time scale.