[Python-Dev] Would like to add Edward Loper as a Python developer

[Tim Peters]

[John Belmonte]
> I noticed that the "whole file doctests" item didn't make it to the
> DoctestIdeas page.

There's more on the wiki now, but no real details.  Code for it exists in
the doctest.py now on tim-doctest-branch.

> I was looking for more details about that.

Here's the class documentation.  In context (but not in isolation as here),
it's clear that it creates a unittest.TestSuite:

def DocFileSuite(*paths, **kw):
    """Creates a suite of doctest files.

    One or more text file paths are given as strings.  These should
    use "/" characters to separate path segments.  Paths are relative
    to the directory of the calling module, or relative to the package
    passed as a keyword argument.

    A number of options may be provided as keyword arguments:

    package
      The name of a Python package.  Text-file paths will be
      interpreted relative to the directory containing this package.
      The package may be supplied as a package object or as a dotted
      package name.

    setUp
      The name of a set-up function.  This is called before running the
      tests in each file.

    tearDown
      The name of a tear-down function.  This is called after running the
      tests in each file.

    globs
      A dictionary containing initial global variables for the tests.
    """

For concrete examples, put the Zope3 source code on a wall, and throw darts
at it.

> I've found that for tutorial narratives, I really don't want to bother
> with expected output.

Do you show any output at all?  If not, this isn't for you.

> For complex software, the output may not always be the same anyway.

We want to focus on invariant (guaranteed) behavior in tests.  I think the
same is true of good docs.  If you can't say anything about the output, you
can't test it, and the documentation must be fuzzy too.

> Also, it's not fun to manipulate input code that has prompts and is
> within a multi-line string.

The files DocFileSuite chews on are text files, not necessarily acceptable
input to Python (in fact, they never are in practice).  So the multi-line
string concern doesn't exist in these.  Mucking with prompts is indeed a
price of entry.

> Syntax highlighting is not available, for one thing.

That depends on the editor, but I agree it's at best clumsy to set up.

> I've made my own tutorial generator.  Given this input script:
>
>      ## Double hash comments treated as meta comments and not output to
>      ## the tutorial.
>
>      """
>      Triple-quote comments that start in the first column are treated as
>      tutorial text.
>
>      First we'll import some modules:
>      """
>      import os
>
>      """
>      Some code follows.  In addition to hash comments, and triple-quote
>      comments not starting in the first column are preserved.  Note that
>      code blocks such as functions must end with a blank line, just as
>      is done in the interactive interpreter.
>      """
>
>      def foo():
>          """foo description here"""
>          print 'hello'  # be friendly
>
>      #my_path = 'foo/bar'
>      my_path = os.path.join('foo', 'bar')
>      my_path
>      foo()
>
> the output is:
>
>      Triple-quote comments that start in the first column are treated as
>      tutorial text.
>
>      First we'll import some modules:
>
>          >>> import os
>
>      Some code follows.  In addition to hash comments, and triple-quote
>      comments not starting in the first column are preserved.  Note that
>      code blocks such as functions must end with a blank line, just as
>      is done in the interactive interpreter.
>
>          >>> def foo():
>          ...     """foo description here"""
>          ...     print 'hello'  # be friendly
>          ...
>          >>> #my_path = 'foo/bar'
>          >>> my_path = os.path.join('foo', 'bar')
>          >>> my_path
>          'foo/bar'
>          >>> foo()
>          hello

So if you put your output in a file, you could feed it exactly as-is to
DocFileSuite(), and it would create a unittest for you that verified the
output in your examples is in fact what it claims to be.