rest25/library/doctest.rst => rest262/library/doctest.rst
n1- 
2:mod:`doctest` --- Test interactive Python examples
3===================================================
4
5.. module:: doctest
n5+   :synopsis: Test pieces of code within docstrings.
6.. moduleauthor:: Tim Peters <tim@python.org>
7.. sectionauthor:: Tim Peters <tim@python.org>
8.. sectionauthor:: Moshe Zadka <moshez@debian.org>
9.. sectionauthor:: Edward Loper <edloper@users.sourceforge.net>
n10- 
11- 
12
13
14The :mod:`doctest` module searches for pieces of text that look like interactive
15Python sessions, and then executes those sessions to verify that they work
16exactly as shown.  There are several common ways to use doctest:
17
18* To check that a module's docstrings are up-to-date by verifying that all
19  interactive examples still work as documented.
65       265252859812191058636308480000000L
66
67       It must also not be ridiculously large:
68       >>> factorial(1e100)
69       Traceback (most recent call last):
70           ...
71       OverflowError: n too large
72       """
n73- 
74- 
75-.. % allow LaTeX to break here.
76- 
77-::
78
79       import math
80       if not n >= 0:
81           raise ValueError("n must be >= 0")
82       if math.floor(n) != n:
83           raise ValueError("n must be exact integer")
84       if n+1 == n:  # catch a value like 1e300
85           raise OverflowError("n too large")
86       result = 1
87       factor = 2
88       while factor <= n:
89           result *= factor
90           factor += 1
91       return result
92
n93-   def _test():
n86+ 
87+   if __name__ == "__main__":
94       import doctest
95       doctest.testmod()
n96- 
97-   if __name__ == "__main__":
98-       _test()
99
100If you run :file:`example.py` directly from the command line, :mod:`doctest`
101works its magic::
102
103   $ python example.py
104   $
105
106There's no output!  That's normal, and it means all the examples worked.  Pass
128
129   Trying:
130       factorial(1e100)
131   Expecting:
132       Traceback (most recent call last):
133           ...
134       OverflowError: n too large
135   ok
n136-   1 items had no tests:
137-       __main__._test
138   2 items passed all tests:
139      1 tests in __main__
140      8 tests in __main__.factorial
n141-   9 tests in 3 items.
n130+   9 tests in 2 items.
142   9 passed and 0 failed.
143   Test passed.
144   $
145
146That's all you need to know to start making productive use of :mod:`doctest`!
147Jump in.  The following sections provide full details.  Note that there are many
148examples of doctests in the standard Python test suite and libraries.
149Especially useful examples can be found in the standard test file
153.. _doctest-simple-testmod:
154
155Simple Usage: Checking Examples in Docstrings
156---------------------------------------------
157
158The simplest way to start using doctest (but not necessarily the way you'll
159continue to do it) is to end each module :mod:`M` with::
160
n161-   def _test():
n150+   if __name__ == "__main__":
162       import doctest
163       doctest.testmod()
n164- 
165-   if __name__ == "__main__":
166-       _test()
167
168:mod:`doctest` then examines docstrings in module :mod:`M`.
169
170Running the module as a script causes the examples in the docstrings to get
171executed and verified::
172
173   python M.py
174
183
184and a detailed report of all examples tried is printed to standard output, along
185with assorted summaries at the end.
186
187You can force verbose mode by passing ``verbose=True`` to :func:`testmod`, or
188prohibit it by passing ``verbose=False``.  In either of those cases,
189``sys.argv`` is not examined by :func:`testmod` (so passing :option:`-v` or not
190has no effect).
n177+ 
178+Since Python 2.6, there is also a command line shortcut for running
179+:func:`testmod`.  You can instruct the Python interpreter to run the doctest
180+module directly from the standard library and pass the module name(s) on the
181+command line::
182+ 
183+   python -m doctest -v example.py
184+ 
185+This will import :file:`example.py` as a standalone module and run
186+:func:`testmod` on it.  Note that this may not work correctly if the file is
187+part of a package and imports other submodules from that package.
191
192For more information on :func:`testmod`, see section :ref:`doctest-basic-api`.
193
194
195.. _doctest-simple-testfile:
196
197Simple Usage: Checking Examples in a Text File
198----------------------------------------------
242
243By default, :func:`testfile` looks for files in the calling module's directory.
244See section :ref:`doctest-basic-api` for a description of the optional arguments
245that can be used to tell it to look for files in other locations.
246
247Like :func:`testmod`, :func:`testfile`'s verbosity can be set with the
248:option:`-v` command-line switch or with the optional keyword argument
249*verbose*.
n247+ 
248+Since Python 2.6, there is also a command line shortcut for running
249+:func:`testfile`.  You can instruct the Python interpreter to run the doctest
250+module directly from the standard library and pass the file name(s) on the
251+command line::
252+ 
253+   python -m doctest -v example.txt
254+ 
255+Because the file name does not end with :file:`.py`, :mod:`doctest` infers that
256+it must be run with :func:`testfile`, not :func:`testmod`.
250
251For more information on :func:`testfile`, see section :ref:`doctest-basic-api`.
252
253
254.. _doctest-how-it-works:
255
256How It Works
257------------
411
412   Traceback (most recent call last):
413   Traceback (innermost last):
414
415The traceback header is followed by an optional traceback stack, whose contents
416are ignored by doctest.  The traceback stack is typically omitted, or copied
417verbatim from an interactive session.
418
n419-The traceback stack is followed by the most interesting part:  the line(s)
n426+The traceback stack is followed by the most interesting part: the line(s)
420containing the exception type and detail.  This is usually the last line of a
n421-traceback, but can extend across multiple lines if the exception has a multi-
n428+traceback, but can extend across multiple lines if the exception has a
422-line detail::
429+multi-line detail::
423
424   >>> raise ValueError('multi\n    line\ndetail')
425   Traceback (most recent call last):
426     File "<stdin>", line 1, in ?
427   ValueError: multi
428       line
429   detail
430
719Warnings
720^^^^^^^^
721
722:mod:`doctest` is serious about requiring exact matches in expected output.  If
723even a single character doesn't match, the test fails.  This will probably
724surprise you a few times, as you learn exactly what Python does and doesn't
725guarantee about output.  For example, when printing a dict, Python doesn't
726guarantee that the key-value pairs will be printed in any particular order, so a
n727-test like
n734+test like ::
728- 
729-.. % Hey! What happened to Monty Python examples?
730-.. % Tim: ask Guido -- it's his example!
731- 
732-::
733
734   >>> foo()
735   {"Hermione": "hippogryph", "Harry": "broomstick"}
736
737is vulnerable!  One workaround is to do ::
738
739   >>> foo() == {"Hermione": "hippogryph", "Harry": "broomstick"}
740   True
799   form.
800
801   Test examples in the file named *filename*.  Return ``(failure_count,
802   test_count)``.
803
804   Optional argument *module_relative* specifies how the filename should be
805   interpreted:
806
n807-* If *module_relative* is ``True`` (the default), then *filename* specifies an
n809+   * If *module_relative* is ``True`` (the default), then *filename* specifies an
808     OS-independent module-relative path.  By default, this path is relative to the
809     calling module's directory; but if the *package* argument is specified, then it
810     is relative to that package.  To ensure OS-independence, *filename* should use
811     ``/`` characters to separate path segments, and may not be an absolute path
812     (i.e., it may not begin with ``/``).
813
n814-* If *module_relative* is ``False``, then *filename* specifies an OS-specific
n816+   * If *module_relative* is ``False``, then *filename* specifies an OS-specific
815     path.  The path may be absolute or relative; relative paths are resolved with
816     respect to the current working directory.
817
818   Optional argument *name* gives the name of the test; by default, or if ``None``,
819   ``os.path.basename(filename)`` is used.
820
821   Optional argument *package* is a Python package or the name of a Python package
822   whose directory should be used as the base directory for a module-relative
958       suite.addTest(doctest.DocTestSuite(mod))
959   runner = unittest.TextTestRunner()
960   runner.run(suite)
961
962There are two main functions for creating :class:`unittest.TestSuite` instances
963from text files and modules with doctests:
964
965
n966-.. function:: DocFileSuite([module_relative][, package][, setUp][, tearDown][, globs][, optionflags][, parser][, encoding])
n968+.. function:: DocFileSuite(*paths, [module_relative][, package][, setUp][, tearDown][, globs][, optionflags][, parser][, encoding])
967
968   Convert doctest tests from one or more text files to a
969   :class:`unittest.TestSuite`.
970
971   The returned :class:`unittest.TestSuite` is to be run by the unittest framework
972   and runs the interactive examples in each file.  If an example in any file
973   fails, then the synthesized unit test fails, and a :exc:`failureException`
974   exception is raised showing the name of the file containing the test and a
976
977   Pass one or more paths (as strings) to text files to be examined.
978
979   Options may be provided as keyword arguments:
980
981   Optional argument *module_relative* specifies how the filenames in *paths*
982   should be interpreted:
983
n984-* If *module_relative* is ``True`` (the default), then each filename specifies
n986+   * If *module_relative* is ``True`` (the default), then each filename in
985-     an OS-independent module-relative path.  By default, this path is relative to
987+     *paths* specifies an OS-independent module-relative path.  By default, this
986-     the calling module's directory; but if the *package* argument is specified, then
988+     path is relative to the calling module's directory; but if the *package*
987-     it is relative to that package.  To ensure OS-independence, each filename should
989+     argument is specified, then it is relative to that package.  To ensure
988-     use ``/`` characters to separate path segments, and may not be an absolute path
990+     OS-independence, each filename should use ``/`` characters to separate path
989-     (i.e., it may not begin with ``/``).
991+     segments, and may not be an absolute path (i.e., it may not begin with
992+     ``/``).
990
n991-* If *module_relative* is ``False``, then each filename specifies an OS-specific
n994+   * If *module_relative* is ``False``, then each filename in *paths* specifies
992-     path.  The path may be absolute or relative; relative paths are resolved with
995+     an OS-specific path.  The path may be absolute or relative; relative paths
993-     respect to the current working directory.
996+     are resolved with respect to the current working directory.
994
n995-   Optional argument *package* is a Python package or the name of a Python package
n998+   Optional argument *package* is a Python package or the name of a Python
999+   package whose directory should be used as the base directory for
1000+   module-relative filenames in *paths*.  If no package is specified, then the
996-   whose directory should be used as the base directory for module-relative
1001+   calling module's directory is used as the base directory for module-relative
997-   filenames.  If no package is specified, then the calling module's directory is
1002+   filenames.  It is an error to specify *package* if *module_relative* is
998-   used as the base directory for module-relative filenames.  It is an error to
1003+   ``False``.
999-   specify *package* if *module_relative* is ``False``.
1000
n1001-   Optional argument *setUp* specifies a set-up function for the test suite.  This
n1005+   Optional argument *setUp* specifies a set-up function for the test suite.
1002-   is called before running the tests in each file.  The *setUp* function will be
1006+   This is called before running the tests in each file.  The *setUp* function
1003-   passed a :class:`DocTest` object.  The setUp function can access the test
1004-   globals as the *globs* attribute of the test passed.
1005- 
1006-   Optional argument *tearDown* specifies a tear-down function for the test suite.
1007-   This is called after running the tests in each file.  The *tearDown* function
1008   will be passed a :class:`DocTest` object.  The setUp function can access the
1009   test globals as the *globs* attribute of the test passed.
n1009+ 
1010+   Optional argument *tearDown* specifies a tear-down function for the test
1011+   suite.  This is called after running the tests in each file.  The *tearDown*
1012+   function will be passed a :class:`DocTest` object.  The setUp function can
1013+   access the test globals as the *globs* attribute of the test passed.
1010
1011   Optional argument *globs* is a dictionary containing the initial global
1012   variables for the tests.  A new copy of this dictionary is created for each
1013   test.  By default, *globs* is a new empty dictionary.
1014
1015   Optional argument *optionflags* specifies the default doctest options for the
1016   tests, created by or-ing together individual option flags.  See section
n1017-   :ref:`doctest-options`. See function :func:`set_unittest_reportflags` below for
n1021+   :ref:`doctest-options`. See function :func:`set_unittest_reportflags` below
1018-   a better way to set reporting options.
1022+   for a better way to set reporting options.
1019
n1020-   Optional argument *parser* specifies a :class:`DocTestParser` (or subclass) that
n1024+   Optional argument *parser* specifies a :class:`DocTestParser` (or subclass)
1021-   should be used to extract tests from the files.  It defaults to a normal parser
1025+   that should be used to extract tests from the files.  It defaults to a normal
1022-   (i.e., ``DocTestParser()``).
1026+   parser (i.e., ``DocTestParser()``).
1023
1024   Optional argument *encoding* specifies an encoding that should be used to
1025   convert the file to unicode.
1026
1027   .. versionadded:: 2.4
1028
1029   .. versionchanged:: 2.5
n1030-      The global ``__file__`` was added to the globals provided to doctests loaded
n1034+      The global ``__file__`` was added to the globals provided to doctests
1031-      from a text file using :func:`DocFileSuite`.
1035+      loaded from a text file using :func:`DocFileSuite`.
1032
1033   .. versionchanged:: 2.5
1034      The parameter *encoding* was added.
1035
1036
1037.. function:: DocTestSuite([module][, globs][, extraglobs][, test_finder][, setUp][, tearDown][, checker])
1038
1039   Convert doctest tests for a module to a :class:`unittest.TestSuite`.
1050
1051   Optional argument *globs* is a dictionary containing the initial global
1052   variables for the tests.  A new copy of this dictionary is created for each
1053   test.  By default, *globs* is a new empty dictionary.
1054
1055   Optional argument *extraglobs* specifies an extra set of global variables, which
1056   is merged into *globs*.  By default, no extra globals are used.
1057
n1058-   Optional argument *test_finder* is the :class:`DocTestFinder` object (or a drop-
n1062+   Optional argument *test_finder* is the :class:`DocTestFinder` object (or a
1059-   in replacement) that is used to extract doctests from the module.
1063+   drop-in replacement) that is used to extract doctests from the module.
1060
1061   Optional arguments *setUp*, *tearDown*, and *optionflags* are the same as for
1062   function :func:`DocFileSuite` above.
1063
1064   .. versionadded:: 2.3
1065
1066   .. versionchanged:: 2.4
1067      The parameters *globs*, *extraglobs*, *test_finder*, *setUp*, *tearDown*, and
1123The basic API is a simple wrapper that's intended to make doctest easy to use.
1124It is fairly flexible, and should meet most users' needs; however, if you
1125require more fine-grained control over testing, or wish to extend doctest's
1126capabilities, then you should use the advanced API.
1127
1128The advanced API revolves around two container classes, which are used to store
1129the interactive examples extracted from doctest cases:
1130
n1131-* :class:`Example`: A single python statement, paired with its expected output.
n1135+* :class:`Example`: A single python :term:`statement`, paired with its expected
1136+  output.
1132
1133* :class:`DocTest`: A collection of :class:`Example`\ s, typically extracted
1134  from a single docstring or text file.
1135
1136Additional processing classes are defined to find, parse, and run, and check
1137doctest examples:
1138
1139* :class:`DocTestFinder`: Finds all docstrings in a given module, and uses a
1171.. class:: DocTest(examples, globs, name, filename, lineno, docstring)
1172
1173   A collection of doctest examples that should be run in a single namespace.  The
1174   constructor arguments are used to initialize the member variables of the same
1175   names.
1176
1177   .. versionadded:: 2.4
1178
n1179-:class:`DocTest` defines the following member variables.  They are initialized
n1184+   :class:`DocTest` defines the following member variables.  They are initialized by
1180-by the constructor, and should not be modified directly.
1185+   the constructor, and should not be modified directly.
1181
1182
n1183-.. attribute:: DocTest.examples
n1188+   .. attribute:: examples
1184
n1185-   A list of :class:`Example` objects encoding the individual interactive Python
n1190+      A list of :class:`Example` objects encoding the individual interactive Python
1186-   examples that should be run by this test.
1191+      examples that should be run by this test.
1187
1188
n1189-.. attribute:: DocTest.globs
n1194+   .. attribute:: globs
1190
n1191-   The namespace (aka globals) that the examples should be run in. This is a
n1196+      The namespace (aka globals) that the examples should be run in. This is a
1192-   dictionary mapping names to values.  Any changes to the namespace made by the
1197+      dictionary mapping names to values.  Any changes to the namespace made by the
1193-   examples (such as binding new variables) will be reflected in :attr:`globs`
1198+      examples (such as binding new variables) will be reflected in :attr:`globs`
1194-   after the test is run.
1199+      after the test is run.
1195
1196
n1197-.. attribute:: DocTest.name
n1202+   .. attribute:: name
1198
n1199-   A string name identifying the :class:`DocTest`.  Typically, this is the name of
n1204+      A string name identifying the :class:`DocTest`.  Typically, this is the name
1200-   the object or file that the test was extracted from.
1205+      of the object or file that the test was extracted from.
1201
1202
n1203-.. attribute:: DocTest.filename
n1208+   .. attribute:: filename
1204
n1205-   The name of the file that this :class:`DocTest` was extracted from; or ``None``
n1210+      The name of the file that this :class:`DocTest` was extracted from; or
1206-   if the filename is unknown, or if the :class:`DocTest` was not extracted from a
1211+      ``None`` if the filename is unknown, or if the :class:`DocTest` was not
1207-   file.
1212+      extracted from a file.
1208
1209
n1210-.. attribute:: DocTest.lineno
n1215+   .. attribute:: lineno
1211
n1212-   The line number within :attr:`filename` where this :class:`DocTest` begins, or
n1217+      The line number within :attr:`filename` where this :class:`DocTest` begins, or
1213-   ``None`` if the line number is unavailable.  This line number is zero-based with
1218+      ``None`` if the line number is unavailable.  This line number is zero-based
1214-   respect to the beginning of the file.
1219+      with respect to the beginning of the file.
1215
1216
n1217-.. attribute:: DocTest.docstring
n1222+   .. attribute:: docstring
1218
n1219-   The string that the test was extracted from, or 'None' if the string is
n1224+      The string that the test was extracted from, or 'None' if the string is
1220-   unavailable, or if the test was not extracted from a string.
1225+      unavailable, or if the test was not extracted from a string.
1221
1222
1223.. _doctest-example:
1224
1225Example Objects
1226^^^^^^^^^^^^^^^
1227
1228
1229.. class:: Example(source, want[, exc_msg][, lineno][, indent][, options])
1230
1231   A single interactive example, consisting of a Python statement and its expected
1232   output.  The constructor arguments are used to initialize the member variables
1233   of the same names.
1234
1235   .. versionadded:: 2.4
1236
n1237-:class:`Example` defines the following member variables.  They are initialized
n1242+   :class:`Example` defines the following member variables.  They are initialized by
1238-by the constructor, and should not be modified directly.
1243+   the constructor, and should not be modified directly.
1239
1240
n1241-.. attribute:: Example.source
n1246+   .. attribute:: source
1242
n1243-   A string containing the example's source code.  This source code consists of a
n1248+      A string containing the example's source code.  This source code consists of a
1244-   single Python statement, and always ends with a newline; the constructor adds a
1249+      single Python statement, and always ends with a newline; the constructor adds
1245-   newline when necessary.
1246- 
1247- 
1248-.. attribute:: Example.want
1249- 
1250-   The expected output from running the example's source code (either from stdout,
1251-   or a traceback in case of exception).  :attr:`want` ends with a newline unless
1252-   no output is expected, in which case it's an empty string.  The constructor adds
1253-   a newline when necessary.
1250+      a newline when necessary.
1254
1255
n1253+   .. attribute:: want
1254+ 
1255+      The expected output from running the example's source code (either from
1256+      stdout, or a traceback in case of exception).  :attr:`want` ends with a
1257+      newline unless no output is expected, in which case it's an empty string.  The
1258+      constructor adds a newline when necessary.
1259+ 
1260+ 
1256-.. attribute:: Example.exc_msg
1261+   .. attribute:: exc_msg
1257
n1258-   The exception message generated by the example, if the example is expected to
n1263+      The exception message generated by the example, if the example is expected to
1259-   generate an exception; or ``None`` if it is not expected to generate an
1264+      generate an exception; or ``None`` if it is not expected to generate an
1260-   exception.  This exception message is compared against the return value of
1265+      exception.  This exception message is compared against the return value of
1261-   :func:`traceback.format_exception_only`.  :attr:`exc_msg` ends with a newline
1266+      :func:`traceback.format_exception_only`.  :attr:`exc_msg` ends with a newline
1262-   unless it's ``None``.  The constructor adds a newline if needed.
1267+      unless it's ``None``.  The constructor adds a newline if needed.
1263
1264
n1265-.. attribute:: Example.lineno
n1270+   .. attribute:: lineno
1266
n1267-   The line number within the string containing this example where the example
n1272+      The line number within the string containing this example where the example
1268-   begins.  This line number is zero-based with respect to the beginning of the
1273+      begins.  This line number is zero-based with respect to the beginning of the
1269-   containing string.
1274+      containing string.
1270
1271
n1272-.. attribute:: Example.indent
n1277+   .. attribute:: indent
1273
n1274-   The example's indentation in the containing string, i.e., the number of space
n1279+      The example's indentation in the containing string, i.e., the number of space
1275-   characters that precede the example's first prompt.
1280+      characters that precede the example's first prompt.
1276
1277
n1278-.. attribute:: Example.options
n1283+   .. attribute:: options
1279
n1280-   A dictionary mapping from option flags to ``True`` or ``False``, which is used
n1285+      A dictionary mapping from option flags to ``True`` or ``False``, which is used
1281-   to override default options for this example.  Any option flags not contained in
1286+      to override default options for this example.  Any option flags not contained
1282-   this dictionary are left at their default value (as specified by the
1287+      in this dictionary are left at their default value (as specified by the
1283-   :class:`DocTestRunner`'s :attr:`optionflags`). By default, no options are set.
1288+      :class:`DocTestRunner`'s :attr:`optionflags`). By default, no options are set.
1284
1285
1286.. _doctest-doctestfinder:
1287
1288DocTestFinder objects
1289^^^^^^^^^^^^^^^^^^^^^
1290
1291
1306   If the optional argument *recurse* is false, then :meth:`DocTestFinder.find`
1307   will only examine the given object, and not any contained objects.
1308
1309   If the optional argument *exclude_empty* is false, then
1310   :meth:`DocTestFinder.find` will include tests for objects with empty docstrings.
1311
1312   .. versionadded:: 2.4
1313
n1314-:class:`DocTestFinder` defines the following method:
n1319+   :class:`DocTestFinder` defines the following method:
1315
1316
n1317-.. method:: DocTestFinder.find(obj[, name][, module][, globs][, extraglobs])
n1322+   .. method:: find(obj[, name][, module][, globs][, extraglobs])
1318
n1319-   Return a list of the :class:`DocTest`\ s that are defined by *obj*'s docstring,
n1324+      Return a list of the :class:`DocTest`\ s that are defined by *obj*'s
1320-   or by any of its contained objects' docstrings.
1325+      docstring, or by any of its contained objects' docstrings.
1321
n1322-   The optional argument *name* specifies the object's name; this name will be used
n1327+      The optional argument *name* specifies the object's name; this name will be
1323-   to construct names for the returned :class:`DocTest`\ s.  If *name* is not
1328+      used to construct names for the returned :class:`DocTest`\ s.  If *name* is
1324-   specified, then ``obj.__name__`` is used.
1329+      not specified, then ``obj.__name__`` is used.
1325
n1326-   The optional parameter *module* is the module that contains the given object.
n1331+      The optional parameter *module* is the module that contains the given object.
1327-   If the module is not specified or is None, then the test finder will attempt to
1332+      If the module is not specified or is None, then the test finder will attempt
1328-   automatically determine the correct module.  The object's module is used:
1333+      to automatically determine the correct module.  The object's module is used:
1329
n1330-* As a default namespace, if *globs* is not specified.
n1335+      * As a default namespace, if *globs* is not specified.
1331
n1332-* To prevent the DocTestFinder from extracting DocTests from objects that are
n1337+      * To prevent the DocTestFinder from extracting DocTests from objects that are
1333-     imported from other modules.  (Contained objects with modules other than
1338+        imported from other modules.  (Contained objects with modules other than
1334-     *module* are ignored.)
1339+        *module* are ignored.)
1335
n1336-* To find the name of the file containing the object.
n1341+      * To find the name of the file containing the object.
1337
n1338-* To help find the line number of the object within its file.
n1343+      * To help find the line number of the object within its file.
1339
n1340-   If *module* is ``False``, no attempt to find the module will be made.  This is
n1345+      If *module* is ``False``, no attempt to find the module will be made.  This is
1341-   obscure, of use mostly in testing doctest itself: if *module* is ``False``, or
1346+      obscure, of use mostly in testing doctest itself: if *module* is ``False``, or
1342-   is ``None`` but cannot be found automatically, then all objects are considered
1347+      is ``None`` but cannot be found automatically, then all objects are considered
1343-   to belong to the (non-existent) module, so all contained objects will
1348+      to belong to the (non-existent) module, so all contained objects will
1344-   (recursively) be searched for doctests.
1349+      (recursively) be searched for doctests.
1345
n1346-   The globals for each :class:`DocTest` is formed by combining *globs* and
n1351+      The globals for each :class:`DocTest` is formed by combining *globs* and
1347-   *extraglobs* (bindings in *extraglobs* override bindings in *globs*).  A new
1352+      *extraglobs* (bindings in *extraglobs* override bindings in *globs*).  A new
1348-   shallow copy of the globals dictionary is created for each :class:`DocTest`.  If
1353+      shallow copy of the globals dictionary is created for each :class:`DocTest`.
1349-   *globs* is not specified, then it defaults to the module's *__dict__*, if
1354+      If *globs* is not specified, then it defaults to the module's *__dict__*, if
1350-   specified, or ``{}`` otherwise.  If *extraglobs* is not specified, then it
1355+      specified, or ``{}`` otherwise.  If *extraglobs* is not specified, then it
1351-   defaults to ``{}``.
1356+      defaults to ``{}``.
1352
1353
1354.. _doctest-doctestparser:
1355
1356DocTestParser objects
1357^^^^^^^^^^^^^^^^^^^^^
1358
1359
1360.. class:: DocTestParser()
1361
1362   A processing class used to extract interactive examples from a string, and use
1363   them to create a :class:`DocTest` object.
1364
1365   .. versionadded:: 2.4
1366
n1367-:class:`DocTestParser` defines the following methods:
n1372+   :class:`DocTestParser` defines the following methods:
1368
1369
n1370-.. method:: DocTestParser.get_doctest(string, globs, name, filename, lineno)
n1375+   .. method:: get_doctest(string, globs, name, filename, lineno)
1371
n1372-   Extract all doctest examples from the given string, and collect them into a
n1377+      Extract all doctest examples from the given string, and collect them into a
1373-   :class:`DocTest` object.
1378+      :class:`DocTest` object.
1374
n1375-   *globs*, *name*, *filename*, and *lineno* are attributes for the new
n1380+      *globs*, *name*, *filename*, and *lineno* are attributes for the new
1376-   :class:`DocTest` object.  See the documentation for :class:`DocTest` for more
1381+      :class:`DocTest` object.  See the documentation for :class:`DocTest` for more
1377-   information.
1382+      information.
1378
1379
n1380-.. method:: DocTestParser.get_examples(string[, name])
n1385+   .. method:: get_examples(string[, name])
1381
n1382-   Extract all doctest examples from the given string, and return them as a list of
n1387+      Extract all doctest examples from the given string, and return them as a list
1383-   :class:`Example` objects.  Line numbers are 0-based.  The optional argument
1388+      of :class:`Example` objects.  Line numbers are 0-based.  The optional argument
1384-   *name* is a name identifying this string, and is only used for error messages.
1389+      *name* is a name identifying this string, and is only used for error messages.
1385
1386
n1387-.. method:: DocTestParser.parse(string[, name])
n1392+   .. method:: parse(string[, name])
1388
n1389-   Divide the given string into examples and intervening text, and return them as a
n1394+      Divide the given string into examples and intervening text, and return them as
1390-   list of alternating :class:`Example`\ s and strings. Line numbers for the
1395+      a list of alternating :class:`Example`\ s and strings. Line numbers for the
1391-   :class:`Example`\ s are 0-based.  The optional argument *name* is a name
1396+      :class:`Example`\ s are 0-based.  The optional argument *name* is a name
1392-   identifying this string, and is only used for error messages.
1397+      identifying this string, and is only used for error messages.
1393
1394
1395.. _doctest-doctestrunner:
1396
1397DocTestRunner objects
1398^^^^^^^^^^^^^^^^^^^^^
1399
1400
1428   iff the command-line switch :option:`-v` is used.
1429
1430   The optional keyword argument *optionflags* can be used to control how the test
1431   runner compares expected output to actual output, and how it displays failures.
1432   For more information, see section :ref:`doctest-options`.
1433
1434   .. versionadded:: 2.4
1435
n1436-:class:`DocTestParser` defines the following methods:
n1441+   :class:`DocTestParser` defines the following methods:
1437
1438
n1439-.. method:: DocTestRunner.report_start(out, test, example)
n1444+   .. method:: report_start(out, test, example)
1440
n1441-   Report that the test runner is about to process the given example. This method
n1446+      Report that the test runner is about to process the given example. This method
1442-   is provided to allow subclasses of :class:`DocTestRunner` to customize their
1447+      is provided to allow subclasses of :class:`DocTestRunner` to customize their
1443-   output; it should not be called directly.
1448+      output; it should not be called directly.
1444
n1445-   *example* is the example about to be processed.  *test* is the test containing
n1450+      *example* is the example about to be processed.  *test* is the test
1446-   *example*.  *out* is the output function that was passed to
1451+      *containing example*.  *out* is the output function that was passed to
1447-   :meth:`DocTestRunner.run`.
1452+      :meth:`DocTestRunner.run`.
1448
1449
n1450-.. method:: DocTestRunner.report_success(out, test, example, got)
n1455+   .. method:: report_success(out, test, example, got)
1451
n1452-   Report that the given example ran successfully.  This method is provided to
n1457+      Report that the given example ran successfully.  This method is provided to
1453-   allow subclasses of :class:`DocTestRunner` to customize their output; it should
1458+      allow subclasses of :class:`DocTestRunner` to customize their output; it
1454-   not be called directly.
1459+      should not be called directly.
1455
n1456-   *example* is the example about to be processed.  *got* is the actual output from
n1461+      *example* is the example about to be processed.  *got* is the actual output
1457-   the example.  *test* is the test containing *example*.  *out* is the output
1462+      from the example.  *test* is the test containing *example*.  *out* is the
1458-   function that was passed to :meth:`DocTestRunner.run`.
1463+      output function that was passed to :meth:`DocTestRunner.run`.
1459
1460
n1461-.. method:: DocTestRunner.report_failure(out, test, example, got)
n1466+   .. method:: report_failure(out, test, example, got)
1462
n1463-   Report that the given example failed.  This method is provided to allow
n1468+      Report that the given example failed.  This method is provided to allow
1464-   subclasses of :class:`DocTestRunner` to customize their output; it should not be
1469+      subclasses of :class:`DocTestRunner` to customize their output; it should not
1465-   called directly.
1470+      be called directly.
1466
n1467-   *example* is the example about to be processed.  *got* is the actual output from
n1472+      *example* is the example about to be processed.  *got* is the actual output
1468-   the example.  *test* is the test containing *example*.  *out* is the output
1473+      from the example.  *test* is the test containing *example*.  *out* is the
1469-   function that was passed to :meth:`DocTestRunner.run`.
1474+      output function that was passed to :meth:`DocTestRunner.run`.
1470
1471
n1472-.. method:: DocTestRunner.report_unexpected_exception(out, test, example, exc_info)
n1477+   .. method:: report_unexpected_exception(out, test, example, exc_info)
1473
n1474-   Report that the given example raised an unexpected exception. This method is
n1479+      Report that the given example raised an unexpected exception. This method is
1475-   provided to allow subclasses of :class:`DocTestRunner` to customize their
1480+      provided to allow subclasses of :class:`DocTestRunner` to customize their
1476-   output; it should not be called directly.
1481+      output; it should not be called directly.
1477
n1478-   *example* is the example about to be processed. *exc_info* is a tuple containing
n1483+      *example* is the example about to be processed. *exc_info* is a tuple
1479-   information about the unexpected exception (as returned by
1484+      containing information about the unexpected exception (as returned by
1480-   :func:`sys.exc_info`). *test* is the test containing *example*.  *out* is the
1485+      :func:`sys.exc_info`). *test* is the test containing *example*.  *out* is the
1481-   output function that was passed to :meth:`DocTestRunner.run`.
1486+      output function that was passed to :meth:`DocTestRunner.run`.
1482
1483
n1484-.. method:: DocTestRunner.run(test[, compileflags][, out][, clear_globs])
n1489+   .. method:: run(test[, compileflags][, out][, clear_globs])
1485
n1486-   Run the examples in *test* (a :class:`DocTest` object), and display the results
n1491+      Run the examples in *test* (a :class:`DocTest` object), and display the
1487-   using the writer function *out*.
1492+      results using the writer function *out*.
1488
n1489-   The examples are run in the namespace ``test.globs``.  If *clear_globs* is true
n1494+      The examples are run in the namespace ``test.globs``.  If *clear_globs* is
1490-   (the default), then this namespace will be cleared after the test runs, to help
1495+      true (the default), then this namespace will be cleared after the test runs,
1491-   with garbage collection. If you would like to examine the namespace after the
1496+      to help with garbage collection. If you would like to examine the namespace
1492-   test completes, then use *clear_globs=False*.
1497+      after the test completes, then use *clear_globs=False*.
1493
n1494-   *compileflags* gives the set of flags that should be used by the Python compiler
n1499+      *compileflags* gives the set of flags that should be used by the Python
1495-   when running the examples.  If not specified, then it will default to the set of
1500+      compiler when running the examples.  If not specified, then it will default to
1496-   future-import flags that apply to *globs*.
1501+      the set of future-import flags that apply to *globs*.
1497
n1498-   The output of each example is checked using the :class:`DocTestRunner`'s output
n1503+      The output of each example is checked using the :class:`DocTestRunner`'s
1499-   checker, and the results are formatted by the :meth:`DocTestRunner.report_\*`
1504+      output checker, and the results are formatted by the
1500-   methods.
1505+      :meth:`DocTestRunner.report_\*` methods.
1501
1502
n1503-.. method:: DocTestRunner.summarize([verbose])
n1508+   .. method:: summarize([verbose])
1504
n1505-   Print a summary of all the test cases that have been run by this DocTestRunner,
n1510+      Print a summary of all the test cases that have been run by this DocTestRunner,
1506-   and return a tuple ``(failure_count, test_count)``.
1511+      and return a :term:`named tuple` ``TestResults(failed, attempted)``.
1507
n1508-   The optional *verbose* argument controls how detailed the summary is.  If the
n1513+      The optional *verbose* argument controls how detailed the summary is.  If the
1509-   verbosity is not specified, then the :class:`DocTestRunner`'s verbosity is used.
1514+      verbosity is not specified, then the :class:`DocTestRunner`'s verbosity is
1515+      used.
1516+ 
1517+      .. versionchanged:: 2.6
1518+         Use a named tuple.
1510
1511
1512.. _doctest-outputchecker:
1513
1514OutputChecker objects
1515^^^^^^^^^^^^^^^^^^^^^
1516
1517
1520   A class used to check the whether the actual output from a doctest example
1521   matches the expected output.  :class:`OutputChecker` defines two methods:
1522   :meth:`check_output`, which compares a given pair of outputs, and returns true
1523   if they match; and :meth:`output_difference`, which returns a string describing
1524   the differences between two outputs.
1525
1526   .. versionadded:: 2.4
1527
n1528-:class:`OutputChecker` defines the following methods:
n1537+   :class:`OutputChecker` defines the following methods:
1529
1530
n1531-.. method:: OutputChecker.check_output(want, got, optionflags)
n1540+   .. method:: check_output(want, got, optionflags)
1532
n1533-   Return ``True`` iff the actual output from an example (*got*) matches the
n1542+      Return ``True`` iff the actual output from an example (*got*) matches the
1534-   expected output (*want*).  These strings are always considered to match if they
1543+      expected output (*want*).  These strings are always considered to match if
1535-   are identical; but depending on what option flags the test runner is using,
1544+      they are identical; but depending on what option flags the test runner is
1536-   several non-exact match types are also possible.  See section
1545+      using, several non-exact match types are also possible.  See section
1537-   :ref:`doctest-options` for more information about option flags.
1546+      :ref:`doctest-options` for more information about option flags.
1538
1539
n1540-.. method:: OutputChecker.output_difference(example, got, optionflags)
n1549+   .. method:: output_difference(example, got, optionflags)
1541
n1542-   Return a string describing the differences between the expected output for a
n1551+      Return a string describing the differences between the expected output for a
1543-   given example (*example*) and the actual output (*got*).  *optionflags* is the
1552+      given example (*example*) and the actual output (*got*).  *optionflags* is the
1544-   set of option flags used to compare *want* and *got*.
1553+      set of option flags used to compare *want* and *got*.
1545
1546
1547.. _doctest-debugging:
1548
1549Debugging
1550---------
1551
1552Doctest provides several mechanisms for debugging doctest examples:
1605     --Return--
1606     > <doctest a[2]>(1)?()->None
1607     -> f(3)
1608     (Pdb) cont
1609     (0, 3)
1610     >>>
1611
1612  .. versionchanged:: 2.4
n1613-     The ability to use ``pdb.set_trace()`` usefully inside doctests was added.
n1622+     The ability to use :func:`pdb.set_trace` usefully inside doctests was added.
1614
1615Functions that convert doctests to Python code, and possibly run the synthesized
1616code under the debugger:
1617
1618
1619.. function:: script_from_examples(s)
1620
1621   Convert text with examples to a script.
1682   control of the Python debugger, :mod:`pdb`.
1683
1684   A shallow copy of ``module.__dict__`` is used for both local and global
1685   execution context.
1686
1687   Optional argument *pm* controls whether post-mortem debugging is used.  If *pm*
1688   has a true value, the script file is run directly, and the debugger gets
1689   involved only if the script terminates via raising an unhandled exception.  If
n1690-   it does, then post-mortem debugging is invoked, via ``pdb.post_mortem()``,
n1699+   it does, then post-mortem debugging is invoked, via :func:`pdb.post_mortem`,
1691   passing the traceback object from the unhandled exception.  If *pm* is not
1692   specified, or is false, the script is run under the debugger from the start, via
t1693-   passing an appropriate :func:`execfile` call to ``pdb.run()``.
t1702+   passing an appropriate :func:`execfile` call to :func:`pdb.run`.
1694
1695   .. versionadded:: 2.3
1696
1697   .. versionchanged:: 2.4
1698      The *pm* argument was added.
1699
1700
1701.. function:: debug_src(src[, pm][, globs])
Legends
Colors
 Added 
Changed
Deleted
Links
(f)irst change
(n)ext change
(t)op