On Sun, Mar 20, 2011 at 2:18 PM, Alexander Belopolsky <alexander.belopolsky@gmail.com> wrote:
On Sun, Mar 20, 2011 at 12:07 PM, Alexander Belopolsky <alexander.belopolsky@gmail.com> wrote: ..
Let me review that page more thoroughly.
I'll focus on criticism even though, overall I find the PyMOTD:datetime page a good introduction to the datetime module. I would recommend this page to beginners, but probably *before* the official docs, so a "see also" link is probably not the right way to link PyMOTD pages. Maybe a link to PyMOTD should be added to the main docs.python.org page.
Now, what I don't like about PyMOTD:datetime.
1. Order of presentation: time, date, timedelta, datetime, tzinfo. For an introductory article, I would start with date, then do datetime and timedelta. The time objects are not that useful and aware time objects are rather exotic since time method of datetime strips tzinfo. The first example exposes the reader to the tzinfo attribute of time objects without any explanation.
2. In the first paragraph of the "Times" section: "the default of 0 is unlikely to be what you want" - this is somewhat confusing given that the following example is using the default value for microseconds and 01:02:03 time which is equally unlikely to be what someone wants in a typical application. It looks like the "unlikely" comment was about time() with no arguments and default of 0 for all components. It would be better to use a "likely" example, preferably in the PM range so that the reader is gently introduced to the 24-hour system. For example, 5pm as a typical office closing hour would be good, or say 5:45 pm as a realistic train departure time. Any of these would be better that a purely artificial time(1, 2, 3).
3. The min/max/resolution example. I don't think I ever used these attributes of the time class. Resolution is occasionally useful, but mostly for timedelta. Similarly, min and max of the other types reflect some non-obvious design choice, but for time, it is just the 24 hours in a day range.
4. The error passing float to microsecond argument example. Why are microseconds singled out? Similar error would result from passing float for hours, minutes or seconds. An example of how to generate and catch type error is not very helpful in an document about the datetime module. I would much rather see an example of how to convert fractional hours, minutes or seconds to datetime objects using timedelta constructor. (This is another case where dealing with time type is awkward because it does not support arithmetics. Another reason not to pick it as the first type to cover.)
5. The now() and today() example that I criticized in my earlier post is still present in the "canonical" version. The text preceding that example says: "there are several convenient class methods to make creating datetime instances from other common values." However, this does not match the examples which immediately follow. I would expect to see datetime.fromtimestamp() in that section, but for some reason it is covered in the "Dates" section instead.
6. In the revised "Time Zones" section, the author toned down his criticism of the approach taken by module developers. In the 2008 version, he called the tzinfo situation "ironic." Still, this section does not provide any useful examples. At the very least, it should give an example of passing tzinfo to datetime.now() to obtain current time in an aware datetime object. For 3.2 such example could use the new timezone type, but for 2.x it would be appropriate to provide an example using either pytz or a sample tzinfo implementation.
The datetime module is a difficult area to cover. As I said before, it is likely that the situation with the other modules is different. If maintainers of other modules think that their documentation will benefit from a PyMOTW link, I have no objection to that. I still -1 on adding a PyMOTW:datetime link to the datetime module reference manual.
I hope Doug will find my review of his datetime page helpful. I think PyMOTW will similarly benefit from other core developers' reviews as they consider linking PyMOTW to their documentation. However, blindly linking all pages simply because some people find Doug's work overall a better guide to stdlib than the official pages will only confuse readers. The reference manual and PyMOTW are two different works targeting different audiences. PyMOTW is more like a tutorial, trying to concisely introduce main features of each module without a claim to be comprehensive. In the reference manual on the other hand we try to be complete in feature coverage and economical in illustrative examples.
It is reasonable to expect users to read PyMOTW articles in their entirety while reading entire sections of the reference manual would mean a very boring weekend. This observation makes it hard to find a good place for a PyMOTW? Should it go in the beginning or the end of the reference manual page? In either case, it is unlikely to be noticed by a typical user who goes directly to the class or method documentation through some kind of search.
Let me flip this around Alexander: If you completely rewrite the datetime module's documentation - since I disagree with your non-narrative, or non-example driven documentation and the order in which you present various things, I *might* consider linking to it, even if *it might* be a useful resource to introductory developers. I thought adding things to the docs (one of the reasons I asked we give Doug commit rights) might be a simple, easy or lower-argument task. I see now I was wrong - almost perversely so. jesse