[Python-Dev] Unit testing (again)

[Tim Peters]

[Guido]
> You're lucky that doctest doesn't return dictionaries!  For functions
> that return dictionaries, it's much more natural *for documentation
> purposes* to write
>
>   >>> book()
>   {'Fred': 'mom', 'Ron': 'Snape'}
>
> than the necessary work-around.  You may deny that's a problem, but
> once we've explained dictionaries to our users, we can expect them to
> understand that if they see instead
>
>   >>> book()
>   {'Ron': 'Snape', 'Fred': 'mom'}
>
> they will understand that that's the same thing.  Writing it this way
> is easier to read than
>
>   >>> book() == {'Ron': 'Snape', 'Fred': 'mom'}
>   1
>
> I always have to look twice when I see something like that.

>>> sortdict(book())
{'Fred': 'mom', 'Ron': 'Snape'}

Explicit is better etc.  If I have a module that's going to be showing a lot
of dict output, I'll write a little "sortdict" function at the top of the
docs and explain why it's there.  It's clear from c.l.py postings over the
years that lots of people *don't* grasp that dicts are "unordered".
Introducing a sortdict() function serves a useful pedagogical purpose for
them too.

More subtle than dicts for most people is examples showing floating-point
output.  This isn't reliable across platforms (and, e.g., it's no
coincidence that most of the .ratio() etc examples in difflib.py are
contrived to return values exactly representable in binary floating-point;
but simple fractions like 3/4 are also easiest for people to visualize, so
that also makes for good examples).

> They [difflib.py docstring docs] are also more voluminous than I'd
> like the docs for difflib to be...

Not me -- there's nothing in them that I as a potential user don't need to
know.  But then I think the Library docs are too terse in general.  Indeed,
Fredrick makes part of his living selling a 300-page book supplying
desperately needed Library examples <0.5 wink>.

WRT difflib.py, it's OK by me if Fred throws out the examples when LaTeXing
the module docstring, because a user can still get the info *from* the
docstrings.  For that matter, he may as well throw out everything except the
first line or two of each method description, if you want bare-bones minimal
docs for the manual.

no-denying-that-examples-take-space-but-what's-painful-to-include-
    in-the-latex-docs-is-trivial-to-maintain-in-the-code-ly y'rs  - tim