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

[Antoine Pitrou]

On Mon, 20 May 2013 09:37:32 -0400
"R. David Murray" <rdmurray at bitdance.com> wrote:
> On Mon, 20 May 2013 12:45:57 +0200, Antoine Pitrou <solipsis at pitrou.net> 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.
> 
> That's why I added the 'failfast' option to doctest.

I didn't know that. Is it propagated by regrtest? I never use doctest
standalone.

> > Also the difficulty of editing them. For some reason, my editor doesn't
> > offer me facilities to edit interactive prompt session snippets.
> 
> I don't have much problem with lacking tailored facilities for this
> in vim.  I suppose that is a matter of personal style.  I *would* like to
> teach it the proper indentation, but I haven't been bothered enough yet
> to do it.  (After all, weren't you the one who told me the lack of tab
> key indentation at the interactive prompt after you enabled completion
> by default wasn't an issue because one could just use space to indent? :)

An interpreter prompt session is throwaway, so you can pretty much
indent as you like (which may not be very pretty in a tests file).
Besides, I was thinking about the prompts ('>>> ' and '... '), not the
indentation itself.

Regards

Antoine.