[Python-ideas] doctest

[Mike Graham]

On Fri, Mar 2, 2012 at 1:27 PM, Mike Meyer <mwm at mired.org> wrote:
> So the question is - why isn't dealing with this the responsibility of
> the test writer? Yeah, it's not quite the spirit of documentation to
> turn a dictionary into a sorted list in the output, but neither is
> littering the documentation with +LITERAL_EVAL and the like.

Currently the test-writer is not empowered to exercise this
responsibility most effectively. Earlier, an example was presented
that one should write

>>> d = make_dict(...)
>>> d == {'a': 42, 'b': 23, 'c': None}
True

rather than the implied

>>> d = make_dict(...)
{'a': 42, 'b': 23, 'c': None}

Using the former is certainly necessary today, but it's far from
ideal. The documentor is stuck either writing the documentation
clearly (the latter case) or testably (the former). The hope is to
find a way to let people more easily write documentation that is both
clear and testable.

One thing that covers some--but far from all--cases is to
ast.literal_eval or eval the output, since very often that output line
is a repr of a Python expression. To be reasonable, this might require
a directive in both cases and certainly requires one in the latter
case. Though there are still tons of situations this cannot cover, it
would allow people writing documentation to avoid ugly constructs like
the first code snippet in a not-tiny set of cases.

As for littering your code with "+doctest BLAH_BLAH", I don't think
this is all that harmful. It allows the documentation writer get
features she wants and will not display to the user in the processed
documentation. There are already directives like this today and though
ugly, they are conventional.

Mike