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

[Skip Montanaro]

I was just reminded by an update to another bug I had submitted that I was
assigned bug #434143.  Anything that uses time.mktime will fail if the time
tuple it is passed is "too old".  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.

The context in which this arose was a user trying to generate a calendar
using the calendar module.

    https://sourceforge.net/tracker/?func=detail&aid=434143&group_id=5470&atid=105470

I think this is a difficult problem to solve properly without adding an
alternative to time.mktime and making some changes to the various modules
that use it (calendar, imaplib and rfc822 in the current CVS tree).  I
propose instead to make a few documentation changes:

    * in Modules/timemodule.c, make the error message more vague ;-)

    * in Doc/lib/lib{time,calendar}.tex indicate that the "epoch" is
      platform-dependent

I'm more than happy to add the necessary ifdefs to Modules/timemodule.c if
we can settle on what the actual epochs are for the various platforms.  For
Unix it is 1970-01-01.  For Macs I think it is 1900-01-01.  Is it 1904-01-01
on Windows?

If you have a moment, please have a look at the above sourceforge url.  I'd
like to get this off my plate in the next few days.

Skip