[Datetime-SIG] Another round on error-checking
Tim Peters
tim.peters at gmail.com
Fri Sep 4 02:32:11 CEST 2015
[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" ;-) ).
More information about the Datetime-SIG
mailing list