[Python-ideas] Linking Doug's stdlib documentation to our main modules doc.

Jesse Noller jnoller at gmail.com
Mon Mar 21 00:05:20 CET 2011


On Sun, Mar 20, 2011 at 2:18 PM, Alexander Belopolsky
<alexander.belopolsky at gmail.com> wrote:
> On Sun, Mar 20, 2011 at 12:07 PM, Alexander Belopolsky
> <alexander.belopolsky at 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



More information about the Python-ideas mailing list