doc/examples/testmod_literate.py.txt

   1 ..  #!/usr/bin/env python
   2   # -*- coding: iso-8859-1 -*-
   3
   4 :Date:      $Date$
   5 :Version:   SVN-Revision $Revision$
   6 :URL:       $URL:  $
   7 :Copyright: 2006 Guenter Milde.
   8             Released without any warranty under the terms of the
   9             GNU General Public License (v. 2 or later)
  10
  11 testmod_literate
  12 ================
  13
  14 The module docstring should give a concise description of the working,
  15 details are in the literate source so the docstrings are not bloated::
  16
  17   """
  18   This is the "testmod_literate" module.
  19
  20   It supplies one function, `factorial()`.  For example,
  21
  22   >>> factorial(5)
  23   120
  24
  25   """
  26
  27   __docformat__ = 'restructuredtext'
  28
  29
  30 **Beware:** as the docstring is not parsed as separate unit but as part of
  31 the file, there must be a blank line also after the last doctest block.
  32 Otherwise `doctest` expects ``"""`` to be part of the output.
  33
  34
  35 factorial
  36 ---------
  37 The functions docstring can be kept concise and additional discussion
  38 referred to the text part of the literate source::
  39
  40   def factorial(n):
  41       """Return the factorial of `n`, an exact integer >= 0.
  42
  43       >>> [factorial(n) for n in range(6)]
  44       [1, 1, 2, 6, 24, 120]
  45       >>> factorial(30)
  46       265252859812191058636308480000000L
  47
  48       Factorials of floats are OK, but the float must be an exact integer:
  49
  50       >>> factorial(30.0)
  51       265252859812191058636308480000000L
  52
  53       """
  54
  55       import math
  56       if not n >= 0:
  57           raise ValueError("n must be >= 0")
  58       if math.floor(n) != n:
  59           raise ValueError("n must be exact integer")
  60       if n+1 == n:  # catch a value like 1e300
  61           raise OverflowError("n too large")
  62       result = 1
  63       factor = 2
  64       while factor <= n:
  65           result *= factor
  66           factor += 1
  67       return result
  68
  69
  70 Discussion and test
  71 ~~~~~~~~~~~~~~~~~~~
  72
  73 `factorial()` accepts input as int, long or float:
  74
  75       >>> factorial(30)
  76       265252859812191058636308480000000L
  77       >>> factorial(30L)
  78       265252859812191058636308480000000L
  79       >>> factorial(30.0)
  80       265252859812191058636308480000000L
  81
  82 However, the float must be an exact integer and it must also not be
  83 ridiculously large:
  84
  85       >>> factorial(30.1)
  86       Traceback (most recent call last):
  87           ...
  88       ValueError: n must be exact integer
  89
  90       >>> factorial(1e100)
  91       Traceback (most recent call last):
  92           ...
  93       OverflowError: n too large
  94
  95 The factorial of negative values is not defined:
  96
  97       >>> factorial(-1)
  98       Traceback (most recent call last):
  99           ...
 100       ValueError: n must be >= 0
 101
 102 The type of the return value depends on the size of the result.
 103
 104   If the result is small enough to fit in an int, return an int.
 105   Else return a long:
 106
 107       >>> [factorial(n) for n in range(6)]
 108       [1, 1, 2, 6, 24, 120]
 109       >>> [factorial(long(n)) for n in range(6)]
 110       [1, 1, 2, 6, 24, 120]
 111       >>> factorial(30)
 112       265252859812191058636308480000000L
 113       >>> factorial(30L)
 114       265252859812191058636308480000000L
 115
 116
 117 Self Test
 118 ---------
 119
 120 The traditional test function parses the docstrings of all objects in this
 121 module. It misses doctests in comments::
 122
 123   def _test():
 124       import doctest
 125       doctest.testmod()
 126
 127 Test all doctest blocks (both in docstrings and in text parts (well
 128 formatted comments) if the module is called as `__main__` (i.e. from the
 129 command line)::
 130
 131   def _test_all_doctests():
 132       import pylit, sys
 133       pylit.run_doctest(infile=sys.argv[0], txt2code=False,
 134                         globs=sys.modules.get('__main__').__dict__)
 135
 136 (Future versions of `pylit` might contain a convenience function for a simpler
 137 invocation of this test.)
 138
 139 Doctests can still be disabled or commented - make sure they are not
 140 recognised as text block (no double colon here):
 141
 142   # a silly doctest
 143   # >>> False
 144   # True
 145
 146 or (with non-canonical comments)::
 147
 148   # a silly doctest
 149   #>>> False
 150   #True
 151
 152 Doctests in doc-strings can be skipped with the `strip` option::
 153
 154   def _test_text_doctests():
 155       import pylit, sys
 156       pylit.run_doctest(infile=sys.argv[0], txt2code=False, strip=True
 157                         globs=sys.modules.get('__main__').__dict__)
 158
 159
 160
 161 Do a self test::
 162
 163   if __name__ == "__main__":
 164       #_test()
 165       _test_all_doctests()