[Python-ideas] doctest

[Devin Jeanpierre]

On Fri, Mar 2, 2012 at 6:07 AM, David Townshend <aquavitae69 at gmail.com> wrote:
> That was just a quick example of another approach to the problem. Sure,
> there are some issues to work out, but I don't believe this is an
> insurmountable problem.

Nor do I. I was attempting to offer constructive criticism on the
basis that this is a serious suggestion, and deserves attention. Sorry
that I gave the wrong impression.

> Once again, I'm sure we could find a way around this. Perhaps it would also
> be acceptable to define the compare function inside the docstring, or in
> this case inside a rst comment.

I mentioned it earlier, but I think you missed it: I was actually
thinking inside the doctest itself. Your system of global assignment
works as-is if you do it inside the doctests themselves (except for
threads, but who runs doctests in multiple threads? gah!)

> So what about, say, a defaultdict or a WeakSet? What exactly would a naive
> user expect?

WeakSets shouldn't be tested like this, their contents are
nondeterministic. Any expectations can be broken by unfortunate race
conditions, and there is no way around this. Sometimes users might
expect the impossible, but what they expect is irrelevant in such a
case. So forget WeakSets.


I think that a naive user would expect, w.r.t. all these things, that
he copy-pasted a shell session, it would "just work". Where we can fix
doctest to align with such lofty expectations, at least in the common
cases -- such as with dicts and defaultdicts and so on -- is it really
so bad?

Or, for a different argument -- surely, if the natural way to write an
example in a tutorial is to show a dict as a return value, then we
should be able to test that with minimal fuss? Doctest is supposed to
serve the documentation, not the other way around; and the harder
things are, the higher the barrier to entry is, and the fewer people
actually do it. Because testing is important, it's important that
testing be as easy as reasonable and possible.

-- Devin