rstdocs/examples/literate-doctests/index.txt

   1 .. -*- rst-mode -*-
   2 ..
   3   restindex
   4       crumb: Doctests
   5       page-title: PyLit - Tutorial - Doctests
   6       file: testmod_literate.py
   7       file: testfile_literate.py
   8   /restindex
   9
  10 How to write literate doctests with PyLit
  11 =========================================
  12
  13 .. sectnum::
  14 .. contents::
  15
  16
  17 Python Doctest Module
  18 ---------------------
  19
  20 *Doctests* are a literate way of testing a Python script.  They are
  21 supported by the `doctest block`_ syntax in reStructured Text.
  22
  23   The `doctest module`_ searches strings for pieces of text that look like
  24   interactive Python sessions, and then executes those sessions to verify
  25   that they work exactly as shown.
  26
  27   There are several common ways to use doctest:
  28
  29   * To check that a module's docstrings are up-to-date by verifying that all
  30     interactive examples still work as documented.
  31
  32   * To perform regression testing by verifying that interactive examples
  33     from a test file or a test object work as expected.
  34
  35   * To write tutorial documentation for a package, liberally illustrated
  36     with input-output examples. Depending on whether the examples or the
  37     expository text are emphasized, this has the flavor of "literate
  38     testing" or "executable documentation".
  39
  40   -- Python Library Reference for the `doctest module`_
  41
  42
  43 Doctest and PyLit
  44 -----------------
  45
  46 The most common way to use the doctest module is to check examples in all
  47 *docstrings* of a module with ``doctest.testmod()``, e.g. ::
  48
  49     if __name__ == "__main__":
  50         import doctest
  51         doctest.testmod()
  52
  53 You can also check a *text* file as if it were a docstring by calling
  54 doctest from the command line, e.g. ::
  55
  56     sh> python -c "import doctest; doctest.testfile('example.py.txt')"
  57
  58 However, both methods will not check doctest blocks in comments. This is
  59 why they will fail to find doctests in the text blocks of a literate source
  60 in code format. (See the tutorial_ for discussion.)
  61
  62 You can of course convert your source to text form and run
  63 `doctest.testfile` on it. To simplify the task, Pylit supports
  64 `Python doctests`_ in a literate source with an option::
  65
  66     sh> pylit --doctest example.py
  67
  68 will check a literate source file for all doctests regardless of their
  69 location in docstrings or text parts. It can work with both, text or code
  70 format.
  71
  72 In order to do this, it will read the file, transform a code source to text
  73 format on-the-fly and feed the result to a DocTestParser_ object.
  74 I.e., no text source file will be created if ``pylit --doctest`` is
  75 called on a code source file.
  76
  77 This way, it is possible to separate basic examples in doc strings from
  78 additional test in the literate source.
  79
  80
  81 Checking Examples in Docstrings and Documentation text
  82 ------------------------------------------------------
  83
  84 testmod_literate.py_
  85   is a "literate version" of the example in the `doctest module`_ doc that
  86   does a self test when called as `__main__`.
  87
  88   It calls `pylit.run_doctest` to find tests in both docstrings and
  89   documentation blocks.
  90
  91   Test this file with::
  92
  93      sh> python testmod_literate.py
  94      0 failures in 14 tests
  95
  96
  97 Checking Examples in a Literate Source File
  98 -------------------------------------------
  99
 100 testfile_literate.py_
 101   is a "literate version" of the example in the `doctest module`_ doc
 102   adapted for beeing tested with ``pylit --doctest``.
 103
 104   Test this file with::
 105
 106      sh> pylit --doctest testfile_literate.py
 107      0 failures in 19 tests
 108
 109
 110 .. References
 111    ==========
 112
 113 .. _doctest module:
 114 .. _Python doctests: http://docs.python.org/lib/module-doctest.html
 115 .. _DocTestParser: http://docs.python.org/lib/doctest-DocTestParser.html
 116 .. _Advanced API: http://docs.python.org/lib/doctest-advanced-api.html
 117
 118 .. _tutorial: ../tutorial/index.html#doctests
 119 .. _testmod_literate.py: testmod_literate.py
 120 .. _testfile_literate.py: testfile_literate.py
 121
 122
 123 .. _parsed-literal block:
 124     http://docutils.sf.net/docs/ref/rst/directives.html#parsed-literal-block
 125 .. _doctest block:
 126     http://docutils.sf.net/docs/ref/rst/restructuredtext.html#doctest-blocks
 127
 128