[Python-Dev] Purpose of Doctests [Was: Best practices for Enum]

[Antoine Pitrou]

On Mon, 20 May 2013 23:32:10 +1000
Steven D'Aprano <steve at pearwood.info> wrote:
> On 20/05/13 20:45, Antoine Pitrou wrote:
> > On Sat, 18 May 2013 23:41:59 -0700
> > Raymond Hettinger <raymond.hettinger at gmail.com> wrote:
> >>
> >> We should continue to encourage users to make thorough unit tests
> >> and to leave doctests for documentation.  That said, it should be
> >> recognized that some testing is better than no testing.  And doctests
> >> may be attractive in that regard because it is almost effortless to
> >> cut-and-paste a snippet from the interactive prompt.  That isn't a
> >> best practice, but it isn't a worst practice either.
> >
> > There are other reasons to hate doctest, such as the obnoxious
> > error reporting.  Having to wade through ten pages of output to find
> > what went wrong is no fun.
> 
> Ten pages of broken unit tests are no picnic either.

You didn't understand the objection. I'm talking about *one* broken
doctest in a sea of non-broken ones. For some reason doctest (or its
unittest driver) insists on either displaying everything, or nothing.
It doesn't only print the errors and leave the rest silent.

> > Also the difficulty of editing them. For some reason, my editor doesn't
> > offer me facilities to edit interactive prompt session snippets.
> 
> Your text editor doesn't allow you to edit text? Even Notepad allows that!
> 
> Seriously, what editor are you using that doesn't allow you to edit pasted snippets?

I don't know if you're intentionally being stupid. Of course I can edit
them *by hand*. But I'll have to re-create by hand the various
artifacts of an interpreter session, e.g. the prompts.

Regards

Antoine.