PEP: Procedure for Adding New Modules (please comment)

[Fredrik Lundh]

Paul Winkler wrote:
> I based my suggestion (doctest at minimum, preferably unittest) on the note at
> the end of the documentation for doctest:
>
> """
> The first word in doctest is "doc", and that's why the author wrote doctest: to
> keep documentation up to date. It so happens that doctest makes a pleasant
> unit testing environment, but that's not its primary purpose.
>
> Choose docstring examples with care. There's an art to this that needs to be
> learned -- it may not be natural at first. Examples should add genuine value
> to the documentation. ...
> """

for the record, I strongly prefer doctest over unittest also for
"real" unit testing (sorry, steve ;-).

the trick is to use doctest not only to make sure the module's
docstrings are up to date, but more importantly, to make sure
that your test programs work as documented!

here's an excerpt from SRE's doctest-based test program:

def check(pattern, string, *groups):
    # pattern, string to match, zero or more groups to check
    r'''

    # Test ?P< and ?P= extensions
    >>> check('(?P<foo_123', '') # Unterminated group identifier
    Traceback (most recent call last):
    error: unterminated name

    ... 495 more use cases ...

    >>> check(r'([ac])+x', 'aacx', 0, 1)
    ('aacx', 'c')

    '''
    p = re.compile(pattern).match(string)
    if m: return apply(m.group, groups)
    return None

with this approach, I write tests many times faster than with
any other framework -- mostly because I can focus on writing
code that exercises the library, without really having to think
much about how to verify the results: just print them out, run
doctest once, make sure the output look right, copy it into the
test script, and you're done.

(if I wanted to use tools that required me to think hard all the
time, I wouldn't use Python in the first place ;-)

Cheers /F