[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 0.1 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: https://docs.python.org/3/tutorial/floatingpoint.html 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: http://bugs.python.org/issue4775 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. _______________________________________________ Datetime-SIG mailing list [email protected] https://mail.python.org/mailman/listinfo/datetime-sig The PSF Code of Conduct applies to this mailing list: https://www.python.org/psf/codeofconduct/
