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

R. David Murray rdmurray at bitdance.com
Mon May 20 16:45:31 CEST 2013


On Mon, 20 May 2013 15:57:35 +0200, Antoine Pitrou <solipsis at pitrou.net> wrote:
> 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.

I don't think so.  That's a good idea, though.

> > > 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.

True.  I don't find typing >>> or ... very burdensome, though.  Less
even than fixing the alignment after hitting tab :)

--David


More information about the Python-Dev mailing list