doc/examples/testfile_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 testfile_literate
  12 =================
  13
  14 Import
  15 ------
  16
  17 As this module is not loaded when the file is tested with
  18 ``pylit --doctest``, the first doctest must import it before any of its
  19 objects can be used.
  20 An elegant solution is to give a usage example in the module's docstring::
  21
  22   """
  23   This is the "testfile_literate" module.
  24
  25   It supplies one function, `factorial()` that returns the factorial of its
  26   argument, e.g.:
  27
  28   >>> import testfile_literate
  29   >>> testfile_literate.factorial(5)
  30   120
  31
  32   """
  33
  34   __docformat__ = 'restructuredtext'
  35
  36
  37 .. attention:: As the docstring is not parsed as separate unit but as part of the
  38          file, there must be a blank line also after the last doctest block.
  39          Otherwise `doctest` expects ``"""`` to be part of the output.
  40
  41 Alternatives for easier access to the defined objects are:
  42
  43   >>> import testfile_literate as fac
  44   >>> fac.factorial(5)
  45   120
  46
  47   >>> from testfile_literate import *
  48   >>> factorial(5)
  49   120
  50
  51 This imports the *code source* of the literal script:
  52
  53 * ``testfile_literate.py`` must be present in the PYTHONPATH or the current
  54   working directory.
  55
  56 * The doctest examples in the file argument to ``pylit --doctest`` (be it
  57   text source or code source) are tested with the code definitions in the
  58   last saved version of the code source.
  59
  60
  61 factorial
  62 ---------
  63
  64 The functions docstring can be kept concise and additional discussion
  65 referred to the text part of the literate source::
  66
  67   def factorial(n):
  68       """Return the factorial of `n`, an exact integer >= 0.
  69
  70       >>> [factorial(n) for n in range(6)]
  71       [1, 1, 2, 6, 24, 120]
  72       >>> factorial(30)
  73       265252859812191058636308480000000L
  74
  75       Factorials of floats are OK, but the float must be an exact integer:
  76
  77       >>> factorial(30.0)
  78       265252859812191058636308480000000L
  79
  80       """
  81
  82       import math
  83       if not n >= 0:
  84           raise ValueError("n must be >= 0")
  85       if math.floor(n) != n:
  86           raise ValueError("n must be exact integer")
  87       if n+1 == n:  # catch a value like 1e300
  88           raise OverflowError("n too large")
  89       result = 1
  90       factor = 2
  91       while factor <= n:
  92           result *= factor
  93           factor += 1
  94       return result
  95
  96
  97 Discussion and test
  98 ~~~~~~~~~~~~~~~~~~~
  99
 100 `factorial()` accepts input as int, long or float:
 101
 102       >>> factorial(30)
 103       265252859812191058636308480000000L
 104       >>> factorial(30L)
 105       265252859812191058636308480000000L
 106       >>> factorial(30.0)
 107       265252859812191058636308480000000L
 108
 109 However, the float must be an exact integer and it must also not be
 110 ridiculously large:
 111
 112       >>> factorial(30.1)
 113       Traceback (most recent call last):
 114           ...
 115       ValueError: n must be exact integer
 116
 117       >>> factorial(1e100)
 118       Traceback (most recent call last):
 119           ...
 120       OverflowError: n too large
 121
 122 The factorial of negative values is not defined:
 123
 124       >>> factorial(-1)
 125       Traceback (most recent call last):
 126           ...
 127       ValueError: n must be >= 0
 128
 129 The type of the return value depends on the size of the result.
 130
 131   If the result is small enough to fit in an int, return an int.
 132   Else return a long:
 133
 134       >>> [factorial(n) for n in range(6)]
 135       [1, 1, 2, 6, 24, 120]
 136       >>> [factorial(long(n)) for n in range(6)]
 137       [1, 1, 2, 6, 24, 120]
 138       >>> factorial(30)
 139       265252859812191058636308480000000L
 140       >>> factorial(30L)
 141       265252859812191058636308480000000L
 142
 143
 144 Default Action
 145 --------------
 146
 147 The script is tested by calling ``pylit --doctest testfile_literate.py``
 148 or ``pylit --doctest testfile_literate.py.txt``.
 149
 150 This is especially handy for scripts that should perform some default
 151 action other than a self test, e.g.
 152
 153 Print the first 10 natural numbers and their factorials if
 154 called as `__main__` (i.e. from the command line)::
 155
 156   if __name__ == "__main__":
 157       print "n n!"
 158       for n in range(10):
 159           print n, factorial(n)