[ python-Bugs-1594966 ] doctest simple usage recipe is misleading

[SourceForge.net]

Bugs item #1594966, was opened at 2006-11-12 03:31
Message generated for change (Settings changed) made by akuchling
You can respond by visiting: 
https://sourceforge.net/tracker/?func=detail&atid=105470&aid=1594966&group_id=5470

Please note that this message will contain a full copy of the comment thread,
including the initial issue submission, for this request,
not just the latest update.
Category: Documentation
Group: Python 2.5
Status: Open
Resolution: None
Priority: 5
Private: No
Submitted By: Ken Rimey (yemir)
>Assigned to: Tim Peters (tim_one)
Summary: doctest simple usage recipe is misleading

Initial Comment:

"23.2.1 Simple Usage: Checking Examples in Docstrings" sets up a trap 
for the unsuspecting developer:

    http://docs.python.org/lib/doctest-simple-testmod.html

That page recommends adding the following code to the end of a 
module using doctest:

    def _test():
        import doctest
        doctest.testmod()

    if __name__ == "__main__":
        _test()

The problem is that a reasonable person will figure that _test() has 
been defined for convenience in executing the tests from other Python 
code as follows:

    import M
    M._test()

However, that executes the doctests found in __main__, not M!

I think the recommended recipe should instead be as follows:

    if __name__ == "__main__":
        import doctest
        doctest.testmod()


----------------------------------------------------------------------

You can respond by visiting: 
https://sourceforge.net/tracker/?func=detail&atid=105470&aid=1594966&group_id=5470