How to write literate doctests with PyLit

- - - -

Contents

1 Python Doctest Module
2 Doctest and PyLit
3 Checking Examples in Docstrings and Documentation text
4 Checking Examples in a Literate Source File

1 Python Doctest Module

Doctests are a literate way of testing a Python script. They are -supported by the doctest block syntax in reStructured Text.

-
The doctest module searches strings for pieces of text that look like -interactive Python sessions, and then executes those sessions to verify -that they work exactly as shown.
-
There are several common ways to use doctest:
-
-
To check that a module's docstrings are up-to-date by verifying that all -interactive examples still work as documented.
-
To perform regression testing by verifying that interactive examples -from a test file or a test object work as expected.
-
To write tutorial documentation for a package, liberally illustrated -with input-output examples. Depending on whether the examples or the -expository text are emphasized, this has the flavor of "literate -testing" or "executable documentation".
-
-
—Python Library Reference for the doctest module
-

2 Doctest and PyLit

The most common way to use the doctest module is to check examples in all -docstrings of a module with doctest.testmod(), e.g.

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

You can also check a text file as if it were a docstring by calling -doctest from the command line, e.g.

-sh> python -c "import doctest; doctest.testfile('example.py.txt')"
-

However, both methods will not check doctest blocks in comments. This is -why they will fail to find doctests in the text blocks of a literate source -in code format. (See the tutorial for discussion.)

You can of course convert your source to text form and run -doctest.testfile on it. To simplify the task, Pylit supports -Python doctests in a literate source with an option:

-sh> pylit --doctest example.py
-

will check a literate source file for all doctests regardless of their -location in docstrings or text parts. It can work with both, text or code -format.

In order to do this, it will read the file, transform a code source to text -format on-the-fly and feed the result to a DocTestParser object. -This means, no text source file will be created if pylit --doctest is -called on a code source file.

This way, it is possible to separate basic examples in doc strings from -additional test in the literate source.

3 Checking Examples in Docstrings and Documentation text

testmod_literate.py

is a "literate version" of the example in the doctest module doc that -does a self test when called as __main__.

It calls pylit.run_doctest to find tests in both docstrings and -documentation blocks.

Test this file with:

-sh> python testmod_literate.py
-0 failures in 14 tests
-

4 Checking Examples in a Literate Source File

testfile_literate.py

is a "literate version" of the example in the doctest module doc -adapted for beeing tested with pylit --doctest.

Test this file with:

-sh> pylit --doctest testfile_literate.py
-0 failures in 19 tests
-

- -