[Datetime-SIG] Another round on error-checking

[Tim Peters]

[Alex]
> Doc patches from good writers are always welcome, but in this case, I don't
> see what needs to be added to what the reference manual already says:

The docs lack a coherent, friendly overview.  For example, I don't
think they even mention "naive time".  The docs you quote here are
"buried" in a footnote on a table of datetime operations.  They're
accurate, but provide no context, motivation, or exposition of the
_model_.  Chris's

    "remove the tzinfo object, do the math, tack the tzinfo back on"

explains a whole lot about classic arithmetic in one brief &
comprehensible sentence.


> """
> Subtraction of a datetime from a datetime is defined only if both operands
> are naive, or if both are aware. If one is aware and the other is naive,
> TypeError is raised.

I wrote almost all this stuff to begin with, but right now even I'm
already half asleep ;-)


> If both are naive, or both are aware and have the same tzinfo attribute, the
> tzinfo attributes are ignored, and the result is a timedelta object t such
> that datetime2 + t == datetime1.

Assuming the reader already digested the similarly legalistic footnote
just above about what "datetime + timedelta" does.  In
reference-manual style, you can't jump in just anywhere, because the
details are too numerous and involved to keep repeating them.


> No time zone adjustments are done in this case.
>
> If both are aware and have different tzinfo attributes, a-b acts as if a and
> b were first converted to naive UTC datetimes first. The result is
> (a.replace(tzinfo=None) - a.utcoffset()) -(b.replace(tzinfo=None) -
> b.utcoffset()) except that the implementation never overflows.
> """

And stuff like "except that the implementation never overflows" is
important in a spec (it's a constraint on allowable implementations of
the spec), but of approximately no interest to 99.997% of  users.


> https://docs.python.org/3/library/datetime.html#datetime.datetime
>
> The only improvement that comes to mind is to make "Supported operations:" a
> linkable section.

As above, it's not that the docs lack sufficient detail - they're
_buried_ in detail.  Something more akin to the ever-popular "binary
floating-point" tutorial appendix would probably be more useful to
most users.  Just the high-order bits, with pragmatic advice (like "if
you need timeline arithmetic, use UTC - don't be a sucker" ;-) ).