[docs] [issue22356] mention explicitly that stdlib assumes gmtime(0) epoch is 1970

[Akira Li]

Akira Li added the comment:

> Alexander Belopolsky added the comment:
>
> 1. 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:

  https://mail.python.org/pipermail/python-ideas/2014-September/029228.html

> 2. 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.

----------

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue22356>
_______________________________________