On Mar 6, 2014, at 11:50 AM, Tim Peters <tim.peters@gmail.com> wrote:
[Bruce Leban <bruce@leapyear.org>]
... Just because you wrote the docs doesn't mean you know what they mean to other readers. The point of documentation is to explain it to someone who doesn't know what it does after all.
[Tim]
Of course. What's your point here?
[Alexander Belopolsky <alexander.belopolsky@gmail.com>]
I am with Bruce here. I tried to digest your notes on timezone algebra [1] for years and I still don't understand it.
[1] http://hg.python.org/cpython/file/b07400659dba/Lib/datetime.py#l1922
But those aren't user docs - they're notes for developers who are deeply steeped in internal details. And they're hard! Mucking with "all possible" time zones raises mountains of excruciatingly subtle details and corner cases. The masses of tedious "algebra" were needed to justify how the internals get away with doing "so little" - and to explain why the code still wouldn't work right in all cases if the "standard offset" of a single time zone changed (or changes) over time.
Do you claim you still don't understand when bool(time) returns True and False? Those are user docs. I don't claim that reading them will make anyone feel good ;-), but I do believe the computation is described clearly enough to enable a reasonable user to predict the result in all cases.
I don’t think a reasonable user would predict that midnight UTC in a timezone with a UTC offset of +5 would be false, while midnight UTC in a timezone with a UTC offset of -5 would not be false.
_______________________________________________ Python-ideas mailing list Python-ideas@python.org https://mail.python.org/mailman/listinfo/python-ideas Code of Conduct: http://python.org/psf/codeofconduct/
----------------- Donald Stufft PGP: 0x6E3CBCE93372DCFA // 7C6B 7C5D 5E2B 6356 A926 F04F 6E3C BCE9 3372 DCFA