How to write literate doctests with PyLit¶
Python Doctest Module¶
Doctests are a literate way of testing a Python script. They are supported by the doctest block syntax in reStructuredText.
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 emphasised, this has the flavor of “literate testing” or “executable documentation”.
—Python Library Reference for the doctest module
Doctest and PyLit¶
The most common way to use the doctest module is to check examples in all
docstrings of a module with
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.
I.e., 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.
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:
#> python testmod_literate.py 0 failures in 14 tests
is a “literate version” of the example in the doctest module doc adapted for being tested with
Test this file with:
#> pylit --doctest testfile_literate.py 0 failures in 19 tests It imports itself in the usage example and has a non-testing (albeit silly) default action if called from the command line. Sources: `<testfile_literate.py>`_, `<testfile_literate.py.txt>`_