[Datetime-SIG] Fwd: Calendar vs timespan calculations...

Tim Peters tim.peters at gmail.com
Wed Aug 5 17:43:03 CEST 2015

[Chris Barker]
> But naive time is not some arbitrary system unto itself. And while it
> is naive about time zones, and has no DST transitions, it is very much
> an implementation of a particular calendar system.
> And when you add a tzinfo object with methods like utcoffset(), then
> you are very strongly implying that it is now UTC. Oh, and
> datetime.datetime.utcnow() kind of implies that, too.

Much the same can be said about every other programming language on
Earth with a standard implementation of dates and times that includes
some notion of time zones.  They all ignore leap seconds, and all
implement the same approximation to real-life UTC as Python (although
not all support the same range of years. not all accept Gregorian
dates before the date that calendar system was first adopted, some
support Julian dates, ...), and all call it "UTC" anyway.

> The docs do clearly state "no leap seconds" in numerous places. But
> nudges like me bring it up enough that maybe a bit more in the docs
> would be helpful.
> I'll contemplate a doc patch.

I'd say the _body_ of the docs are quite involved enough already.
Adding more warnings about things few people actually care about would
be a disservice to most users.

Here's an analogy.  That Python supports the literal


strongly implies that _means_ "one tenth" exactly.  But it doesn't,
We see "bug reports" related to that many times every year.  It's the
F-est of FAQs.

But it's again something that's not news to anyone with any
experience.  "Floating point" is all most programmers need to hear
about that, just like "ignores leap seconds" is all most programmers
need to hear about Python's treatment of UTC.  "Been there, done that,
same as everyone else" in both cases.

The docs would be ill-served too by droning on about the differences
between real numbers and binary floating-point.  Most programmers
already have some understanding of that, while others need a _lot_ of
words to disabuse them of even their shallowest illusions ;-)

Instead I wrote an appendix on the topic for the Tutorial, which may
well be the most frequently referenced piece of the docs in replies to
bug reports:


That's worked well.  A wordy intro is there to point to when someone
really needs it, but the language and library docs aren't cluttered
with it.

A similar approach may be appropriate for going on at length about the
subtleties of Python's UTC vs real-life UTC vs POSIX vs ... Most users
truly don't care, but it "would be nice" to have a full account for
those who do.

It's hard to provide guidance on what such a thing should cover,
because bug reports related to it are historically rare.  Here's the
most directly relevant one I could find, from about 5 years ago:


Perhaps ironically, that wasn't filed by someone with little knowledge
of time schemes, but by someone with "too much" knowledge ;-)  So
that's a challenge:  a writeup has to be easy to understand for rank
newbies yet use technical terms so precisely that bona fide experts
are satisfied too.

It's also hard to know where to stop.  If you want to explain
_everything_ about "real life" UTC, then you have to explain all this
too (pasted from Wikipedia's article on "Unix time"):

The present form of UTC, with leap seconds, is defined only from 1
January 1972 onwards. Prior to that, since 1 January 1961 there was an
older form of UTC in which not only were there occasional time steps,
which were by non-integer numbers of seconds, but also the UTC second
was slightly longer than the SI second, and periodically changed to
continuously approximate the Earth's rotation. Prior to 1961 there was
no UTC, and prior to 1958 there was no widespread atomic timekeeping;
in these eras, some approximation of GMT (based directly on the
Earth's rotation) was used instead of an atomic timescale.

Who cares about any of that?  Hardly anyone - but some people do.

More information about the Datetime-SIG mailing list