[Python-Dev] Please have a look at proposed doc changes for time epoch

[Tim Peters]

[Skip Montanaro]
> ...
> Unfortunately, by trying to be precise, the message that goes along
> with the ValueError that's raised, it's a little misleading:
>
>     ValueError: year out of range (00-99, 1900-*)
>
> Obviously, on Unix systems the baseline date is more like 1970.  I
> suspect this error message was written when Python was being
> developed mostly (or entirely) on Macs.

C mktime is broken all over the place.  Since the tm_year member of a struct
tm is defined as the number of years since 1900, reasonable implementers
should have assumed the committee intended that years before 1970 weren't
anything special -- but apparently only the Mac implementers were reasonable
<0.9 wink>.  C99 spells this out in severe detail, making clear that there's
nothing special even about negative tm_year offsets (they're for years
before 1900, of course).

> ...
>    * in Modules/timemodule.c, make the error message more vague ;-)
>
>   * in Doc/lib/lib{time,calendar}.tex indicate that the "epoch" is
>     platform-dependent

The defn. of mktime makes no reference to epoch (indeed, the C std doesn't
mention "the epoch" anywhere!), so that's mixing concepts that shouldn't get
mixed even when making excuses for bad implementations.  If we can't fix it
ourselves, better to say that mktime simply isn't well-defined across
platforms.

> Is it 1904-01-01 on Windows?

The MS docs say:

    mktime returns the specified calendar time encoded as a value of
    type time_t. If timeptr references a date before midnight,
    January 1, 1970, or if the calendar time cannot be represented,
    the function returns –1 cast to type time_t.