Move the 3k reST doc tree in place.

1 files changed, 1869 insertions, 0 deletions

diff --git a/Doc/library/doctest.rst b/Doc/library/doctest.rst
new file mode 100644
index 0000000..23f96e4
--- /dev/null
+++ b/Doc/library/doctest.rst
@@ -0,0 +1,1869 @@
+:mod:`doctest` --- Test interactive Python examples
+===================================================
+
+.. module:: doctest
+   :synopsis: Test pieces of code within docstrings.
+.. moduleauthor:: Tim Peters <tim@python.org>
+.. sectionauthor:: Tim Peters <tim@python.org>
+.. sectionauthor:: Moshe Zadka <moshez@debian.org>
+.. sectionauthor:: Edward Loper <edloper@users.sourceforge.net>
+
+
+The :mod:`doctest` module searches 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 emphasized, this has the flavor of "literate testing" or "executable
+  documentation".
+
+Here's a complete but small example module::
+
+   """
+   This is the "example" module.
+
+   The example module supplies one function, factorial().  For example,
+
+   >>> factorial(5)
+   120
+   """
+
+   def factorial(n):
+       """Return the factorial of n, an exact integer >= 0.
+
+       If the result is small enough to fit in an int, return an int.
+       Else return a long.
+
+       >>> [factorial(n) for n in range(6)]
+       [1, 1, 2, 6, 24, 120]
+       >>> [factorial(long(n)) for n in range(6)]
+       [1, 1, 2, 6, 24, 120]
+       >>> factorial(30)
+       265252859812191058636308480000000L
+       >>> factorial(30L)
+       265252859812191058636308480000000L
+       >>> factorial(-1)
+       Traceback (most recent call last):
+           ...
+       ValueError: n must be >= 0
+
+       Factorials of floats are OK, but the float must be an exact integer:
+       >>> factorial(30.1)
+       Traceback (most recent call last):
+           ...
+       ValueError: n must be exact integer
+       >>> factorial(30.0)
+       265252859812191058636308480000000L
+
+       It must also not be ridiculously large:
+       >>> factorial(1e100)
+       Traceback (most recent call last):
+           ...
+       OverflowError: n too large
+       """
+
+
+.. % allow LaTeX to break here.
+
+::
+
+       import math
+       if not n >= 0:
+           raise ValueError("n must be >= 0")
+       if math.floor(n) != n:
+           raise ValueError("n must be exact integer")
+       if n+1 == n:  # catch a value like 1e300
+           raise OverflowError("n too large")
+       result = 1
+       factor = 2
+       while factor <= n:
+           result *= factor
+           factor += 1
+       return result
+
+   def _test():
+       import doctest
+       doctest.testmod()
+
+   if __name__ == "__main__":
+       _test()
+
+If you run :file:`example.py` directly from the command line, :mod:`doctest`
+works its magic::
+
+   $ python example.py
+   $
+
+There's no output!  That's normal, and it means all the examples worked.  Pass
+:option:`-v` to the script, and :mod:`doctest` prints a detailed log of what
+it's trying, and prints a summary at the end::
+
+   $ python example.py -v
+   Trying:
+       factorial(5)
+   Expecting:
+       120
+   ok
+   Trying:
+       [factorial(n) for n in range(6)]
+   Expecting:
+       [1, 1, 2, 6, 24, 120]
+   ok
+   Trying:
+       [factorial(long(n)) for n in range(6)]
+   Expecting:
+       [1, 1, 2, 6, 24, 120]
+   ok
+
+And so on, eventually ending with::
+
+   Trying:
+       factorial(1e100)
+   Expecting:
+       Traceback (most recent call last):
+           ...
+       OverflowError: n too large
+   ok
+   1 items had no tests:
+       __main__._test
+   2 items passed all tests:
+      1 tests in __main__
+      8 tests in __main__.factorial
+   9 tests in 3 items.
+   9 passed and 0 failed.
+   Test passed.
+   $
+
+That's all you need to know to start making productive use of :mod:`doctest`!
+Jump in.  The following sections provide full details.  Note that there are many
+examples of doctests in the standard Python test suite and libraries.
+Especially useful examples can be found in the standard test file
+:file:`Lib/test/test_doctest.py`.
+
+
+.. _doctest-simple-testmod:
+
+Simple Usage: Checking Examples in Docstrings
+---------------------------------------------
+
+The simplest way to start using doctest (but not necessarily the way you'll
+continue to do it) is to end each module :mod:`M` with::
+
+   def _test():
+       import doctest
+       doctest.testmod()
+
+   if __name__ == "__main__":
+       _test()
+
+:mod:`doctest` then examines docstrings in module :mod:`M`.
+
+Running the module as a script causes the examples in the docstrings to get
+executed and verified::
+
+   python M.py
+
+This won't display anything unless an example fails, in which case the failing
+example(s) and the cause(s) of the failure(s) are printed to stdout, and the
+final line of output is ``***Test Failed*** N failures.``, where *N* is the
+number of examples that failed.
+
+Run it with the :option:`-v` switch instead::
+
+   python M.py -v
+
+and a detailed report of all examples tried is printed to standard output, along
+with assorted summaries at the end.
+
+You can force verbose mode by passing ``verbose=True`` to :func:`testmod`, or
+prohibit it by passing ``verbose=False``.  In either of those cases,
+``sys.argv`` is not examined by :func:`testmod` (so passing :option:`-v` or not
+has no effect).
+
+Since Python 2.6, there is also a command line shortcut for running
+:func:`testmod`.  You can instruct the Python interpreter to run the doctest
+module directly from the standard library and pass the module name(s) on the
+command line::
+
+   python -m doctest -v example.py
+
+This will import :file:`example.py` as a standalone module and run
+:func:`testmod` on it.  Note that this may not work correctly if the file is
+part of a package and imports other submodules from that package.
+
+For more information on :func:`testmod`, see section :ref:`doctest-basic-api`.
+
+
+.. _doctest-simple-testfile:
+
+Simple Usage: Checking Examples in a Text File
+----------------------------------------------
+
+Another simple application of doctest is testing interactive examples in a text
+file.  This can be done with the :func:`testfile` function::
+
+   import doctest
+   doctest.testfile("example.txt")
+
+That short script executes and verifies any interactive Python examples
+contained in the file :file:`example.txt`.  The file content is treated as if it
+were a single giant docstring; the file doesn't need to contain a Python
+program!   For example, perhaps :file:`example.txt` contains this::
+
+   The ``example`` module
+   ======================
+
+   Using ``factorial``
+   -------------------
+
+   This is an example text file in reStructuredText format.  First import
+   ``factorial`` from the ``example`` module:
+
+       >>> from example import factorial
+
+   Now use it:
+
+       >>> factorial(6)
+       120
+
+Running ``doctest.testfile("example.txt")`` then finds the error in this
+documentation::
+
+   File "./example.txt", line 14, in example.txt
+   Failed example:
+       factorial(6)
+   Expected:
+       120
+   Got:
+       720
+
+As with :func:`testmod`, :func:`testfile` won't display anything unless an
+example fails.  If an example does fail, then the failing example(s) and the
+cause(s) of the failure(s) are printed to stdout, using the same format as
+:func:`testmod`.
+
+By default, :func:`testfile` looks for files in the calling module's directory.
+See section :ref:`doctest-basic-api` for a description of the optional arguments
+that can be used to tell it to look for files in other locations.
+
+Like :func:`testmod`, :func:`testfile`'s verbosity can be set with the
+:option:`-v` command-line switch or with the optional keyword argument
+*verbose*.
+
+Since Python 2.6, there is also a command line shortcut for running
+:func:`testfile`.  You can instruct the Python interpreter to run the doctest
+module directly from the standard library and pass the file name(s) on the
+command line::
+
+   python -m doctest -v example.txt
+
+Because the file name does not end with :file:`.py`, :mod:`doctest` infers that
+it must be run with :func:`testfile`, not :func:`testmod`.
+
+For more information on :func:`testfile`, see section :ref:`doctest-basic-api`.
+
+
+.. _doctest-how-it-works:
+
+How It Works
+------------
+
+This section examines in detail how doctest works: which docstrings it looks at,
+how it finds interactive examples, what execution context it uses, how it
+handles exceptions, and how option flags can be used to control its behavior.
+This is the information that you need to know to write doctest examples; for
+information about actually running doctest on these examples, see the following
+sections.
+
+
+.. _doctest-which-docstrings:
+
+Which Docstrings Are Examined?
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The module docstring, and all function, class and method docstrings are
+searched.  Objects imported into the module are not searched.
+
+In addition, if ``M.__test__`` exists and "is true", it must be a dict, and each
+entry maps a (string) name to a function object, class object, or string.
+Function and class object docstrings found from ``M.__test__`` are searched, and
+strings are treated as if they were docstrings.  In output, a key ``K`` in
+``M.__test__`` appears with name ::
+
+   <name of M>.__test__.K
+
+Any classes found are recursively searched similarly, to test docstrings in
+their contained methods and nested classes.
+
+.. versionchanged:: 2.4
+   A "private name" concept is deprecated and no longer documented.
+
+
+.. _doctest-finding-examples:
+
+How are Docstring Examples Recognized?
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+In most cases a copy-and-paste of an interactive console session works fine, but
+doctest isn't trying to do an exact emulation of any specific Python shell.  All
+hard tab characters are expanded to spaces, using 8-column tab stops.  If you
+don't believe tabs should mean that, too bad:  don't use hard tabs, or write
+your own :class:`DocTestParser` class.
+
+.. versionchanged:: 2.4
+   Expanding tabs to spaces is new; previous versions tried to preserve hard tabs,
+   with confusing results.
+
+::
+
+   >>> # comments are ignored
+   >>> x = 12
+   >>> x
+   12
+   >>> if x == 13:
+   ...     print "yes"
+   ... else:
+   ...     print "no"
+   ...     print "NO"
+   ...     print "NO!!!"
+   ...
+   no
+   NO
+   NO!!!
+   >>>
+
+Any expected output must immediately follow the final ``'>>> '`` or ``'... '``
+line containing the code, and the expected output (if any) extends to the next
+``'>>> '`` or all-whitespace line.
+
+The fine print:
+
+* Expected output cannot contain an all-whitespace line, since such a line is
+  taken to signal the end of expected output.  If expected output does contain a
+  blank line, put ``<BLANKLINE>`` in your doctest example each place a blank line
+  is expected.
+
+  .. versionchanged:: 2.4
+     ``<BLANKLINE>`` was added; there was no way to use expected output containing
+     empty lines in previous versions.
+
+* Output to stdout is captured, but not output to stderr (exception tracebacks
+  are captured via a different means).
+
+* If you continue a line via backslashing in an interactive session, or for any
+  other reason use a backslash, you should use a raw docstring, which will
+  preserve your backslashes exactly as you type them::
+
+     >>> def f(x):
+     ...     r'''Backslashes in a raw docstring: m\n'''
+     >>> print f.__doc__
+     Backslashes in a raw docstring: m\n
+
+  Otherwise, the backslash will be interpreted as part of the string. For example,
+  the "\\" above would be interpreted as a newline character.  Alternatively, you
+  can double each backslash in the doctest version (and not use a raw string)::
+
+     >>> def f(x):
+     ...     '''Backslashes in a raw docstring: m\\n'''
+     >>> print f.__doc__
+     Backslashes in a raw docstring: m\n
+
+* The starting column doesn't matter::
+
+     >>> assert "Easy!"
+           >>> import math
+               >>> math.floor(1.9)
+               1.0
+
+  and as many leading whitespace characters are stripped from the expected output
+  as appeared in the initial ``'>>> '`` line that started the example.
+
+
+.. _doctest-execution-context:
+
+What's the Execution Context?
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+By default, each time :mod:`doctest` finds a docstring to test, it uses a
+*shallow copy* of :mod:`M`'s globals, so that running tests doesn't change the
+module's real globals, and so that one test in :mod:`M` can't leave behind
+crumbs that accidentally allow another test to work.  This means examples can
+freely use any names defined at top-level in :mod:`M`, and names defined earlier
+in the docstring being run. Examples cannot see names defined in other
+docstrings.
+
+You can force use of your own dict as the execution context by passing
+``globs=your_dict`` to :func:`testmod` or :func:`testfile` instead.
+
+
+.. _doctest-exceptions:
+
+What About Exceptions?
+^^^^^^^^^^^^^^^^^^^^^^
+
+No problem, provided that the traceback is the only output produced by the
+example:  just paste in the traceback. [#]_ Since tracebacks contain details
+that are likely to change rapidly (for example, exact file paths and line
+numbers), this is one case where doctest works hard to be flexible in what it
+accepts.
+
+Simple example::
+
+   >>> [1, 2, 3].remove(42)
+   Traceback (most recent call last):
+     File "<stdin>", line 1, in ?
+   ValueError: list.remove(x): x not in list
+
+That doctest succeeds if :exc:`ValueError` is raised, with the ``list.remove(x):
+x not in list`` detail as shown.
+
+The expected output for an exception must start with a traceback header, which
+may be either of the following two lines, indented the same as the first line of
+the example::
+
+   Traceback (most recent call last):
+   Traceback (innermost last):
+
+The traceback header is followed by an optional traceback stack, whose contents
+are ignored by doctest.  The traceback stack is typically omitted, or copied
+verbatim from an interactive session.
+
+The traceback stack is followed by the most interesting part: the line(s)
+containing the exception type and detail.  This is usually the last line of a
+traceback, but can extend across multiple lines if the exception has a
+multi-line detail::
+
+   >>> raise ValueError('multi\n    line\ndetail')
+   Traceback (most recent call last):
+     File "<stdin>", line 1, in ?
+   ValueError: multi
+       line
+   detail
+
+The last three lines (starting with :exc:`ValueError`) are compared against the
+exception's type and detail, and the rest are ignored.
+
+Best practice is to omit the traceback stack, unless it adds significant
+documentation value to the example.  So the last example is probably better as::
+
+   >>> raise ValueError('multi\n    line\ndetail')
+   Traceback (most recent call last):
+       ...
+   ValueError: multi
+       line
+   detail
+
+Note that tracebacks are treated very specially.  In particular, in the
+rewritten example, the use of ``...`` is independent of doctest's
+:const:`ELLIPSIS` option.  The ellipsis in that example could be left out, or
+could just as well be three (or three hundred) commas or digits, or an indented
+transcript of a Monty Python skit.
+
+Some details you should read once, but won't need to remember:
+
+* Doctest can't guess whether your expected output came from an exception
+  traceback or from ordinary printing.  So, e.g., an example that expects
+  ``ValueError: 42 is prime`` will pass whether :exc:`ValueError` is actually
+  raised or if the example merely prints that traceback text.  In practice,
+  ordinary output rarely begins with a traceback header line, so this doesn't
+  create real problems.
+
+* Each line of the traceback stack (if present) must be indented further than
+  the first line of the example, *or* start with a non-alphanumeric character.
+  The first line following the traceback header indented the same and starting
+  with an alphanumeric is taken to be the start of the exception detail.  Of
+  course this does the right thing for genuine tracebacks.
+
+* When the :const:`IGNORE_EXCEPTION_DETAIL` doctest option is is specified,
+  everything following the leftmost colon is ignored.
+
+* The interactive shell omits the traceback header line for some
+  :exc:`SyntaxError`\ s.  But doctest uses the traceback header line to
+  distinguish exceptions from non-exceptions.  So in the rare case where you need
+  to test a :exc:`SyntaxError` that omits the traceback header, you will need to
+  manually add the traceback header line to your test example.
+
+* For some :exc:`SyntaxError`\ s, Python displays the character position of the
+  syntax error, using a ``^`` marker::
+
+     >>> 1 1
+       File "<stdin>", line 1
+         1 1
+           ^
+     SyntaxError: invalid syntax
+
+  Since the lines showing the position of the error come before the exception type
+  and detail, they are not checked by doctest.  For example, the following test
+  would pass, even though it puts the ``^`` marker in the wrong location::
+
+     >>> 1 1
+     Traceback (most recent call last):
+       File "<stdin>", line 1
+         1 1
+         ^
+     SyntaxError: invalid syntax
+
+.. versionchanged:: 2.4
+   The ability to handle a multi-line exception detail, and the
+   :const:`IGNORE_EXCEPTION_DETAIL` doctest option, were added.
+
+
+.. _doctest-options:
+
+Option Flags and Directives
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+A number of option flags control various aspects of doctest's behavior.
+Symbolic names for the flags are supplied as module constants, which can be
+or'ed together and passed to various functions.  The names can also be used in
+doctest directives (see below).
+
+The first group of options define test semantics, controlling aspects of how
+doctest decides whether actual output matches an example's expected output:
+
+
+.. data:: DONT_ACCEPT_TRUE_FOR_1
+
+   By default, if an expected output block contains just ``1``, an actual output
+   block containing just ``1`` or just ``True`` is considered to be a match, and
+   similarly for ``0`` versus ``False``.  When :const:`DONT_ACCEPT_TRUE_FOR_1` is
+   specified, neither substitution is allowed.  The default behavior caters to that
+   Python changed the return type of many functions from integer to boolean;
+   doctests expecting "little integer" output still work in these cases.  This
+   option will probably go away, but not for several years.
+
+
+.. data:: DONT_ACCEPT_BLANKLINE
+
+   By default, if an expected output block contains a line containing only the
+   string ``<BLANKLINE>``, then that line will match a blank line in the actual
+   output.  Because a genuinely blank line delimits the expected output, this is
+   the only way to communicate that a blank line is expected.  When
+   :const:`DONT_ACCEPT_BLANKLINE` is specified, this substitution is not allowed.
+
+
+.. data:: NORMALIZE_WHITESPACE
+
+   When specified, all sequences of whitespace (blanks and newlines) are treated as
+   equal.  Any sequence of whitespace within the expected output will match any
+   sequence of whitespace within the actual output. By default, whitespace must
+   match exactly. :const:`NORMALIZE_WHITESPACE` is especially useful when a line of
+   expected output is very long, and you want to wrap it across multiple lines in
+   your source.
+
+
+.. data:: ELLIPSIS
+
+   When specified, an ellipsis marker (``...``) in the expected output can match
+   any substring in the actual output.  This includes substrings that span line
+   boundaries, and empty substrings, so it's best to keep usage of this simple.
+   Complicated uses can lead to the same kinds of "oops, it matched too much!"
+   surprises that ``.*`` is prone to in regular expressions.
+
+
+.. data:: IGNORE_EXCEPTION_DETAIL
+
+   When specified, an example that expects an exception passes if an exception of
+   the expected type is raised, even if the exception detail does not match.  For
+   example, an example expecting ``ValueError: 42`` will pass if the actual
+   exception raised is ``ValueError: 3*14``, but will fail, e.g., if
+   :exc:`TypeError` is raised.
+
+   Note that a similar effect can be obtained using :const:`ELLIPSIS`, and
+   :const:`IGNORE_EXCEPTION_DETAIL` may go away when Python releases prior to 2.4
+   become uninteresting.  Until then, :const:`IGNORE_EXCEPTION_DETAIL` is the only
+   clear way to write a doctest that doesn't care about the exception detail yet
+   continues to pass under Python releases prior to 2.4 (doctest directives appear
+   to be comments to them).  For example, ::
+
+      >>> (1, 2)[3] = 'moo' #doctest: +IGNORE_EXCEPTION_DETAIL
+      Traceback (most recent call last):
+        File "<stdin>", line 1, in ?
+      TypeError: object doesn't support item assignment
+
+   passes under Python 2.4 and Python 2.3.  The detail changed in 2.4, to say "does
+   not" instead of "doesn't".
+
+
+.. data:: SKIP
+
+   When specified, do not run the example at all.  This can be useful in contexts
+   where doctest examples serve as both documentation and test cases, and an
+   example should be included for documentation purposes, but should not be
+   checked.  E.g., the example's output might be random; or the example might
+   depend on resources which would be unavailable to the test driver.
+
+   The SKIP flag can also be used for temporarily "commenting out" examples.
+
+
+.. data:: COMPARISON_FLAGS
+
+   A bitmask or'ing together all the comparison flags above.
+
+The second group of options controls how test failures are reported:
+
+
+.. data:: REPORT_UDIFF
+
+   When specified, failures that involve multi-line expected and actual outputs are
+   displayed using a unified diff.
+
+
+.. data:: REPORT_CDIFF
+
+   When specified, failures that involve multi-line expected and actual outputs
+   will be displayed using a context diff.
+
+
+.. data:: REPORT_NDIFF
+
+   When specified, differences are computed by ``difflib.Differ``, using the same
+   algorithm as the popular :file:`ndiff.py` utility. This is the only method that
+   marks differences within lines as well as across lines.  For example, if a line
+   of expected output contains digit ``1`` where actual output contains letter
+   ``l``, a line is inserted with a caret marking the mismatching column positions.
+
+
+.. data:: REPORT_ONLY_FIRST_FAILURE
+
+   When specified, display the first failing example in each doctest, but suppress
+   output for all remaining examples.  This will prevent doctest from reporting
+   correct examples that break because of earlier failures; but it might also hide
+   incorrect examples that fail independently of the first failure.  When
+   :const:`REPORT_ONLY_FIRST_FAILURE` is specified, the remaining examples are
+   still run, and still count towards the total number of failures reported; only
+   the output is suppressed.
+
+
+.. data:: REPORTING_FLAGS
+
+   A bitmask or'ing together all the reporting flags above.
+
+"Doctest directives" may be used to modify the option flags for individual
+examples.  Doctest directives are expressed as a special Python comment
+following an example's source code:
+
+.. productionlist:: doctest
+   directive: "#" "doctest:" `directive_options`
+   directive_options: `directive_option` ("," `directive_option`)\*
+   directive_option: `on_or_off` `directive_option_name`
+   on_or_off: "+" \| "-"
+   directive_option_name: "DONT_ACCEPT_BLANKLINE" \| "NORMALIZE_WHITESPACE" \| ...
+
+Whitespace is not allowed between the ``+`` or ``-`` and the directive option
+name.  The directive option name can be any of the option flag names explained
+above.
+
+An example's doctest directives modify doctest's behavior for that single
+example.  Use ``+`` to enable the named behavior, or ``-`` to disable it.
+
+For example, this test passes::
+
+   >>> print range(20) #doctest: +NORMALIZE_WHITESPACE
+   [0,   1,  2,  3,  4,  5,  6,  7,  8,  9,
+   10,  11, 12, 13, 14, 15, 16, 17, 18, 19]
+
+Without the directive it would fail, both because the actual output doesn't have
+two blanks before the single-digit list elements, and because the actual output
+is on a single line.  This test also passes, and also requires a directive to do
+so::
+
+   >>> print range(20) # doctest:+ELLIPSIS
+   [0, 1, ..., 18, 19]
+
+Multiple directives can be used on a single physical line, separated by commas::
+
+   >>> print range(20) # doctest: +ELLIPSIS, +NORMALIZE_WHITESPACE
+   [0,    1, ...,   18,    19]
+
+If multiple directive comments are used for a single example, then they are
+combined::
+
+   >>> print range(20) # doctest: +ELLIPSIS
+   ...                 # doctest: +NORMALIZE_WHITESPACE
+   [0,    1, ...,   18,    19]
+
+As the previous example shows, you can add ``...`` lines to your example
+containing only directives.  This can be useful when an example is too long for
+a directive to comfortably fit on the same line::
+
+   >>> print range(5) + range(10,20) + range(30,40) + range(50,60)
+   ... # doctest: +ELLIPSIS
+   [0, ..., 4, 10, ..., 19, 30, ..., 39, 50, ..., 59]
+
+Note that since all options are disabled by default, and directives apply only
+to the example they appear in, enabling options (via ``+`` in a directive) is
+usually the only meaningful choice.  However, option flags can also be passed to
+functions that run doctests, establishing different defaults.  In such cases,
+disabling an option via ``-`` in a directive can be useful.
+
+.. versionchanged:: 2.4
+   Constants :const:`DONT_ACCEPT_BLANKLINE`, :const:`NORMALIZE_WHITESPACE`,
+   :const:`ELLIPSIS`, :const:`IGNORE_EXCEPTION_DETAIL`, :const:`REPORT_UDIFF`,
+   :const:`REPORT_CDIFF`, :const:`REPORT_NDIFF`,
+   :const:`REPORT_ONLY_FIRST_FAILURE`, :const:`COMPARISON_FLAGS` and
+   :const:`REPORTING_FLAGS` were added; by default ``<BLANKLINE>`` in expected
+   output matches an empty line in actual output; and doctest directives were
+   added.
+
+.. versionchanged:: 2.5
+   Constant :const:`SKIP` was added.
+
+There's also a way to register new option flag names, although this isn't useful
+unless you intend to extend :mod:`doctest` internals via subclassing:
+
+
+.. function:: register_optionflag(name)
+
+   Create a new option flag with a given name, and return the new flag's integer
+   value.  :func:`register_optionflag` can be used when subclassing
+   :class:`OutputChecker` or :class:`DocTestRunner` to create new options that are
+   supported by your subclasses.  :func:`register_optionflag` should always be
+   called using the following idiom::
+
+      MY_FLAG = register_optionflag('MY_FLAG')
+
+   .. versionadded:: 2.4
+
+
+.. _doctest-warnings:
+
+Warnings
+^^^^^^^^
+
+:mod:`doctest` is serious about requiring exact matches in expected output.  If
+even a single character doesn't match, the test fails.  This will probably
+surprise you a few times, as you learn exactly what Python does and doesn't
+guarantee about output.  For example, when printing a dict, Python doesn't
+guarantee that the key-value pairs will be printed in any particular order, so a
+test like
+
+.. % Hey! What happened to Monty Python examples?
+.. % Tim: ask Guido -- it's his example!
+
+::
+
+   >>> foo()
+   {"Hermione": "hippogryph", "Harry": "broomstick"}
+
+is vulnerable!  One workaround is to do ::
+
+   >>> foo() == {"Hermione": "hippogryph", "Harry": "broomstick"}
+   True
+
+instead.  Another is to do ::
+
+   >>> d = foo().items()
+   >>> d.sort()
+   >>> d
+   [('Harry', 'broomstick'), ('Hermione', 'hippogryph')]
+
+There are others, but you get the idea.
+
+Another bad idea is to print things that embed an object address, like ::
+
+   >>> id(1.0) # certain to fail some of the time
+   7948648
+   >>> class C: pass
+   >>> C()   # the default repr() for instances embeds an address
+   <__main__.C instance at 0x00AC18F0>
+
+The :const:`ELLIPSIS` directive gives a nice approach for the last example::
+
+   >>> C() #doctest: +ELLIPSIS
+   <__main__.C instance at 0x...>
+
+Floating-point numbers are also subject to small output variations across
+platforms, because Python defers to the platform C library for float formatting,
+and C libraries vary widely in quality here. ::
+
+   >>> 1./7  # risky
+   0.14285714285714285
+   >>> print 1./7 # safer
+   0.142857142857
+   >>> print round(1./7, 6) # much safer
+   0.142857
+
+Numbers of the form ``I/2.**J`` are safe across all platforms, and I often
+contrive doctest examples to produce numbers of that form::
+
+   >>> 3./4  # utterly safe
+   0.75
+
+Simple fractions are also easier for people to understand, and that makes for
+better documentation.
+
+
+.. _doctest-basic-api:
+
+Basic API
+---------
+
+The functions :func:`testmod` and :func:`testfile` provide a simple interface to
+doctest that should be sufficient for most basic uses.  For a less formal
+introduction to these two functions, see sections :ref:`doctest-simple-testmod`
+and :ref:`doctest-simple-testfile`.
+
+
+.. function:: testfile(filename[, module_relative][, name][, package][, globs][, verbose][, report][, optionflags][, extraglobs][, raise_on_error][, parser][, encoding])
+
+   All arguments except *filename* are optional, and should be specified in keyword
+   form.
+
+   Test examples in the file named *filename*.  Return ``(failure_count,
+   test_count)``.
+
+   Optional argument *module_relative* specifies how the filename should be
+   interpreted:
+
+   * If *module_relative* is ``True`` (the default), then *filename* specifies an
+     OS-independent module-relative path.  By default, this path is relative to the
+     calling module's directory; but if the *package* argument is specified, then it
+     is relative to that package.  To ensure OS-independence, *filename* should use
+     ``/`` characters to separate path segments, and may not be an absolute path
+     (i.e., it may not begin with ``/``).
+
+   * If *module_relative* is ``False``, then *filename* specifies an OS-specific
+     path.  The path may be absolute or relative; relative paths are resolved with
+     respect to the current working directory.
+
+   Optional argument *name* gives the name of the test; by default, or if ``None``,
+   ``os.path.basename(filename)`` is used.
+
+   Optional argument *package* is a Python package or the name of a Python package
+   whose directory should be used as the base directory for a module-relative
+   filename.  If no package is specified, then the calling module's directory is
+   used as the base directory for module-relative filenames.  It is an error to
+   specify *package* if *module_relative* is ``False``.
+
+   Optional argument *globs* gives a dict to be used as the globals when executing
+   examples.  A new shallow copy of this dict is created for the doctest, so its
+   examples start with a clean slate. By default, or if ``None``, a new empty dict
+   is used.
+
+   Optional argument *extraglobs* gives a dict merged into the globals used to
+   execute examples.  This works like :meth:`dict.update`:  if *globs* and
+   *extraglobs* have a common key, the associated value in *extraglobs* appears in
+   the combined dict.  By default, or if ``None``, no extra globals are used.  This
+   is an advanced feature that allows parameterization of doctests.  For example, a
+   doctest can be written for a base class, using a generic name for the class,
+   then reused to test any number of subclasses by passing an *extraglobs* dict
+   mapping the generic name to the subclass to be tested.
+
+   Optional argument *verbose* prints lots of stuff if true, and prints only
+   failures if false; by default, or if ``None``, it's true if and only if ``'-v'``
+   is in ``sys.argv``.
+
+   Optional argument *report* prints a summary at the end when true, else prints
+   nothing at the end.  In verbose mode, the summary is detailed, else the summary
+   is very brief (in fact, empty if all tests passed).
+
+   Optional argument *optionflags* or's together option flags.  See section
+   :ref:`doctest-options`.
+
+   Optional argument *raise_on_error* defaults to false.  If true, an exception is
+   raised upon the first failure or unexpected exception in an example.  This
+   allows failures to be post-mortem debugged. Default behavior is to continue
+   running examples.
+
+   Optional argument *parser* specifies a :class:`DocTestParser` (or subclass) that
+   should be used to extract tests from the files.  It defaults to a normal parser
+   (i.e., ``DocTestParser()``).
+
+   Optional argument *encoding* specifies an encoding that should be used to
+   convert the file to unicode.
+
+   .. versionadded:: 2.4
+
+   .. versionchanged:: 2.5
+      The parameter *encoding* was added.
+
+
+.. function:: testmod([m][, name][, globs][, verbose][, report][, optionflags][, extraglobs][, raise_on_error][, exclude_empty])
+
+   All arguments are optional, and all except for *m* should be specified in
+   keyword form.
+
+   Test examples in docstrings in functions and classes reachable from module *m*
+   (or module :mod:`__main__` if *m* is not supplied or is ``None``), starting with
+   ``m.__doc__``.
+
+   Also test examples reachable from dict ``m.__test__``, if it exists and is not
+   ``None``.  ``m.__test__`` maps names (strings) to functions, classes and
+   strings; function and class docstrings are searched for examples; strings are
+   searched directly, as if they were docstrings.
+
+   Only docstrings attached to objects belonging to module *m* are searched.
+
+   Return ``(failure_count, test_count)``.
+
+   Optional argument *name* gives the name of the module; by default, or if
+   ``None``, ``m.__name__`` is used.
+
+   Optional argument *exclude_empty* defaults to false.  If true, objects for which
+   no doctests are found are excluded from consideration. The default is a backward
+   compatibility hack, so that code still using :meth:`doctest.master.summarize` in
+   conjunction with :func:`testmod` continues to get output for objects with no
+   tests. The *exclude_empty* argument to the newer :class:`DocTestFinder`
+   constructor defaults to true.
+
+   Optional arguments *extraglobs*, *verbose*, *report*, *optionflags*,
+   *raise_on_error*, and *globs* are the same as for function :func:`testfile`
+   above, except that *globs* defaults to ``m.__dict__``.
+
+   .. versionchanged:: 2.3
+      The parameter *optionflags* was added.
+
+   .. versionchanged:: 2.4
+      The parameters *extraglobs*, *raise_on_error* and *exclude_empty* were added.
+
+   .. versionchanged:: 2.5
+      The optional argument *isprivate*, deprecated in 2.4, was removed.
+
+There's also a function to run the doctests associated with a single object.
+This function is provided for backward compatibility.  There are no plans to
+deprecate it, but it's rarely useful:
+
+
+.. function:: run_docstring_examples(f, globs[, verbose][, name][, compileflags][, optionflags])
+
+   Test examples associated with object *f*; for example, *f* may be a module,
+   function, or class object.
+
+   A shallow copy of dictionary argument *globs* is used for the execution context.
+
+   Optional argument *name* is used in failure messages, and defaults to
+   ``"NoName"``.
+
+   If optional argument *verbose* is true, output is generated even if there are no
+   failures.  By default, output is generated only in case of an example failure.
+
+   Optional argument *compileflags* gives the set of flags that should be used by
+   the Python compiler when running the examples.  By default, or if ``None``,
+   flags are deduced corresponding to the set of future features found in *globs*.
+
+   Optional argument *optionflags* works as for function :func:`testfile` above.
+
+
+.. _doctest-unittest-api:
+
+Unittest API
+------------
+
+As your collection of doctest'ed modules grows, you'll want a way to run all
+their doctests systematically.  Prior to Python 2.4, :mod:`doctest` had a barely
+documented :class:`Tester` class that supplied a rudimentary way to combine
+doctests from multiple modules. :class:`Tester` was feeble, and in practice most
+serious Python testing frameworks build on the :mod:`unittest` module, which
+supplies many flexible ways to combine tests from multiple sources.  So, in
+Python 2.4, :mod:`doctest`'s :class:`Tester` class is deprecated, and
+:mod:`doctest` provides two functions that can be used to create :mod:`unittest`
+test suites from modules and text files containing doctests.  These test suites
+can then be run using :mod:`unittest` test runners::
+
+   import unittest
+   import doctest
+   import my_module_with_doctests, and_another
+
+   suite = unittest.TestSuite()
+   for mod in my_module_with_doctests, and_another:
+       suite.addTest(doctest.DocTestSuite(mod))
+   runner = unittest.TextTestRunner()
+   runner.run(suite)
+
+There are two main functions for creating :class:`unittest.TestSuite` instances
+from text files and modules with doctests:
+
+
+.. function:: DocFileSuite([module_relative][, package][, setUp][, tearDown][, globs][, optionflags][, parser][, encoding])
+
+   Convert doctest tests from one or more text files to a
+   :class:`unittest.TestSuite`.
+
+   The returned :class:`unittest.TestSuite` is to be run by the unittest framework
+   and runs the interactive examples in each file.  If an example in any file
+   fails, then the synthesized unit test fails, and a :exc:`failureException`
+   exception is raised showing the name of the file containing the test and a
+   (sometimes approximate) line number.
+
+   Pass one or more paths (as strings) to text files to be examined.
+
+   Options may be provided as keyword arguments:
+
+   Optional argument *module_relative* specifies how the filenames in *paths*
+   should be interpreted:
+
+   * If *module_relative* is ``True`` (the default), then each filename specifies
+     an OS-independent module-relative path.  By default, this path is relative to
+     the calling module's directory; but if the *package* argument is specified, then
+     it is relative to that package.  To ensure OS-independence, each filename should
+     use ``/`` characters to separate path segments, and may not be an absolute path
+     (i.e., it may not begin with ``/``).
+
+   * If *module_relative* is ``False``, then each filename specifies an OS-specific
+     path.  The path may be absolute or relative; relative paths are resolved with
+     respect to the current working directory.
+
+   Optional argument *package* is a Python package or the name of a Python package
+   whose directory should be used as the base directory for module-relative
+   filenames.  If no package is specified, then the calling module's directory is
+   used as the base directory for module-relative filenames.  It is an error to
+   specify *package* if *module_relative* is ``False``.
+
+   Optional argument *setUp* specifies a set-up function for the test suite.  This
+   is called before running the tests in each file.  The *setUp* function will be
+   passed a :class:`DocTest` object.  The setUp function can access the test
+   globals as the *globs* attribute of the test passed.
+
+   Optional argument *tearDown* specifies a tear-down function for the test suite.
+   This is called after running the tests in each file.  The *tearDown* function
+   will be passed a :class:`DocTest` object.  The setUp function can access the
+   test globals as the *globs* attribute of the test passed.
+
+   Optional argument *globs* is a dictionary containing the initial global
+   variables for the tests.  A new copy of this dictionary is created for each
+   test.  By default, *globs* is a new empty dictionary.
+
+   Optional argument *optionflags* specifies the default doctest options for the
+   tests, created by or-ing together individual option flags.  See section
+   :ref:`doctest-options`. See function :func:`set_unittest_reportflags` below for
+   a better way to set reporting options.
+
+   Optional argument *parser* specifies a :class:`DocTestParser` (or subclass) that
+   should be used to extract tests from the files.  It defaults to a normal parser
+   (i.e., ``DocTestParser()``).
+
+   Optional argument *encoding* specifies an encoding that should be used to
+   convert the file to unicode.
+
+   .. versionadded:: 2.4
+
+   .. versionchanged:: 2.5
+      The global ``__file__`` was added to the globals provided to doctests loaded
+      from a text file using :func:`DocFileSuite`.
+
+   .. versionchanged:: 2.5
+      The parameter *encoding* was added.
+
+
+.. function:: DocTestSuite([module][, globs][, extraglobs][, test_finder][, setUp][, tearDown][, checker])
+
+   Convert doctest tests for a module to a :class:`unittest.TestSuite`.
+
+   The returned :class:`unittest.TestSuite` is to be run by the unittest framework
+   and runs each doctest in the module.  If any of the doctests fail, then the
+   synthesized unit test fails, and a :exc:`failureException` exception is raised
+   showing the name of the file containing the test and a (sometimes approximate)
+   line number.
+
+   Optional argument *module* provides the module to be tested.  It can be a module
+   object or a (possibly dotted) module name.  If not specified, the module calling
+   this function is used.
+
+   Optional argument *globs* is a dictionary containing the initial global
+   variables for the tests.  A new copy of this dictionary is created for each
+   test.  By default, *globs* is a new empty dictionary.
+
+   Optional argument *extraglobs* specifies an extra set of global variables, which
+   is merged into *globs*.  By default, no extra globals are used.
+
+   Optional argument *test_finder* is the :class:`DocTestFinder` object (or a
+   drop-in replacement) that is used to extract doctests from the module.
+
+   Optional arguments *setUp*, *tearDown*, and *optionflags* are the same as for
+   function :func:`DocFileSuite` above.
+
+   .. versionadded:: 2.3
+
+   .. versionchanged:: 2.4
+      The parameters *globs*, *extraglobs*, *test_finder*, *setUp*, *tearDown*, and
+      *optionflags* were added; this function now uses the same search technique as
+      :func:`testmod`.
+
+Under the covers, :func:`DocTestSuite` creates a :class:`unittest.TestSuite` out
+of :class:`doctest.DocTestCase` instances, and :class:`DocTestCase` is a
+subclass of :class:`unittest.TestCase`. :class:`DocTestCase` isn't documented
+here (it's an internal detail), but studying its code can answer questions about
+the exact details of :mod:`unittest` integration.
+
+Similarly, :func:`DocFileSuite` creates a :class:`unittest.TestSuite` out of
+:class:`doctest.DocFileCase` instances, and :class:`DocFileCase` is a subclass
+of :class:`DocTestCase`.
+
+So both ways of creating a :class:`unittest.TestSuite` run instances of
+:class:`DocTestCase`.  This is important for a subtle reason: when you run
+:mod:`doctest` functions yourself, you can control the :mod:`doctest` options in
+use directly, by passing option flags to :mod:`doctest` functions.  However, if
+you're writing a :mod:`unittest` framework, :mod:`unittest` ultimately controls
+when and how tests get run.  The framework author typically wants to control
+:mod:`doctest` reporting options (perhaps, e.g., specified by command line
+options), but there's no way to pass options through :mod:`unittest` to
+:mod:`doctest` test runners.
+
+For this reason, :mod:`doctest` also supports a notion of :mod:`doctest`
+reporting flags specific to :mod:`unittest` support, via this function:
+
+
+.. function:: set_unittest_reportflags(flags)
+
+   Set the :mod:`doctest` reporting flags to use.
+
+   Argument *flags* or's together option flags.  See section
+   :ref:`doctest-options`.  Only "reporting flags" can be used.
+
+   This is a module-global setting, and affects all future doctests run by module
+   :mod:`unittest`:  the :meth:`runTest` method of :class:`DocTestCase` looks at
+   the option flags specified for the test case when the :class:`DocTestCase`
+   instance was constructed.  If no reporting flags were specified (which is the
+   typical and expected case), :mod:`doctest`'s :mod:`unittest` reporting flags are
+   or'ed into the option flags, and the option flags so augmented are passed to the
+   :class:`DocTestRunner` instance created to run the doctest.  If any reporting
+   flags were specified when the :class:`DocTestCase` instance was constructed,
+   :mod:`doctest`'s :mod:`unittest` reporting flags are ignored.
+
+   The value of the :mod:`unittest` reporting flags in effect before the function
+   was called is returned by the function.
+
+   .. versionadded:: 2.4
+
+
+.. _doctest-advanced-api:
+
+Advanced API
+------------
+
+The basic API is a simple wrapper that's intended to make doctest easy to use.
+It is fairly flexible, and should meet most users' needs; however, if you
+require more fine-grained control over testing, or wish to extend doctest's
+capabilities, then you should use the advanced API.
+
+The advanced API revolves around two container classes, which are used to store
+the interactive examples extracted from doctest cases:
+
+* :class:`Example`: A single python statement, paired with its expected output.
+
+* :class:`DocTest`: A collection of :class:`Example`\ s, typically extracted
+  from a single docstring or text file.
+
+Additional processing classes are defined to find, parse, and run, and check
+doctest examples:
+
+* :class:`DocTestFinder`: Finds all docstrings in a given module, and uses a
+  :class:`DocTestParser` to create a :class:`DocTest` from every docstring that
+  contains interactive examples.
+
+* :class:`DocTestParser`: Creates a :class:`DocTest` object from a string (such
+  as an object's docstring).
+
+* :class:`DocTestRunner`: Executes the examples in a :class:`DocTest`, and uses
+  an :class:`OutputChecker` to verify their output.
+
+* :class:`OutputChecker`: Compares the actual output from a doctest example with
+  the expected output, and decides whether they match.
+
+The relationships among these processing classes are summarized in the following
+diagram::
+
+                               list of:
+   +------+                   +---------+
+   |module| --DocTestFinder-> | DocTest | --DocTestRunner-> results
+   +------+    |        ^     +---------+     |       ^    (printed)
+               |        |     | Example |     |       |
+               v        |     |   ...   |     v       |
+              DocTestParser   | Example |   OutputChecker
+                              +---------+
+
+
+.. _doctest-doctest:
+
+DocTest Objects
+^^^^^^^^^^^^^^^
+
+
+.. class:: DocTest(examples, globs, name, filename, lineno, docstring)
+
+   A collection of doctest examples that should be run in a single namespace.  The
+   constructor arguments are used to initialize the member variables of the same
+   names.
+
+   .. versionadded:: 2.4
+
+:class:`DocTest` defines the following member variables.  They are initialized
+by the constructor, and should not be modified directly.
+
+
+.. attribute:: DocTest.examples
+
+   A list of :class:`Example` objects encoding the individual interactive Python
+   examples that should be run by this test.
+
+
+.. attribute:: DocTest.globs
+
+   The namespace (aka globals) that the examples should be run in. This is a
+   dictionary mapping names to values.  Any changes to the namespace made by the
+   examples (such as binding new variables) will be reflected in :attr:`globs`
+   after the test is run.
+
+
+.. attribute:: DocTest.name
+
+   A string name identifying the :class:`DocTest`.  Typically, this is the name of
+   the object or file that the test was extracted from.
+
+
+.. attribute:: DocTest.filename
+
+   The name of the file that this :class:`DocTest` was extracted from; or ``None``
+   if the filename is unknown, or if the :class:`DocTest` was not extracted from a
+   file.
+
+
+.. attribute:: DocTest.lineno
+
+   The line number within :attr:`filename` where this :class:`DocTest` begins, or
+   ``None`` if the line number is unavailable.  This line number is zero-based with
+   respect to the beginning of the file.
+
+
+.. attribute:: DocTest.docstring
+
+   The string that the test was extracted from, or 'None' if the string is
+   unavailable, or if the test was not extracted from a string.
+
+
+.. _doctest-example:
+
+Example Objects
+^^^^^^^^^^^^^^^
+
+
+.. class:: Example(source, want[, exc_msg][, lineno][, indent][, options])
+
+   A single interactive example, consisting of a Python statement and its expected
+   output.  The constructor arguments are used to initialize the member variables
+   of the same names.
+
+   .. versionadded:: 2.4
+
+:class:`Example` defines the following member variables.  They are initialized
+by the constructor, and should not be modified directly.
+
+
+.. attribute:: Example.source
+
+   A string containing the example's source code.  This source code consists of a
+   single Python statement, and always ends with a newline; the constructor adds a
+   newline when necessary.
+
+
+.. attribute:: Example.want
+
+   The expected output from running the example's source code (either from stdout,
+   or a traceback in case of exception).  :attr:`want` ends with a newline unless
+   no output is expected, in which case it's an empty string.  The constructor adds
+   a newline when necessary.
+
+
+.. attribute:: Example.exc_msg
+
+   The exception message generated by the example, if the example is expected to
+   generate an exception; or ``None`` if it is not expected to generate an
+   exception.  This exception message is compared against the return value of
+   :func:`traceback.format_exception_only`.  :attr:`exc_msg` ends with a newline
+   unless it's ``None``.  The constructor adds a newline if needed.
+
+
+.. attribute:: Example.lineno
+
+   The line number within the string containing this example where the example
+   begins.  This line number is zero-based with respect to the beginning of the
+   containing string.
+
+
+.. attribute:: Example.indent
+
+   The example's indentation in the containing string, i.e., the number of space
+   characters that precede the example's first prompt.
+
+
+.. attribute:: Example.options
+
+   A dictionary mapping from option flags to ``True`` or ``False``, which is used
+   to override default options for this example.  Any option flags not contained in
+   this dictionary are left at their default value (as specified by the
+   :class:`DocTestRunner`'s :attr:`optionflags`). By default, no options are set.
+
+
+.. _doctest-doctestfinder:
+
+DocTestFinder objects
+^^^^^^^^^^^^^^^^^^^^^
+
+
+.. class:: DocTestFinder([verbose][, parser][, recurse][, exclude_empty])
+
+   A processing class used to extract the :class:`DocTest`\ s that are relevant to
+   a given object, from its docstring and the docstrings of its contained objects.
+   :class:`DocTest`\ s can currently be extracted from the following object types:
+   modules, functions, classes, methods, staticmethods, classmethods, and
+   properties.
+
+   The optional argument *verbose* can be used to display the objects searched by
+   the finder.  It defaults to ``False`` (no output).
+
+   The optional argument *parser* specifies the :class:`DocTestParser` object (or a
+   drop-in replacement) that is used to extract doctests from docstrings.
+
+   If the optional argument *recurse* is false, then :meth:`DocTestFinder.find`
+   will only examine the given object, and not any contained objects.
+
+   If the optional argument *exclude_empty* is false, then
+   :meth:`DocTestFinder.find` will include tests for objects with empty docstrings.
+
+   .. versionadded:: 2.4
+
+:class:`DocTestFinder` defines the following method:
+
+
+.. method:: DocTestFinder.find(obj[, name][, module][, globs][, extraglobs])
+
+   Return a list of the :class:`DocTest`\ s that are defined by *obj*'s docstring,
+   or by any of its contained objects' docstrings.
+
+   The optional argument *name* specifies the object's name; this name will be used
+   to construct names for the returned :class:`DocTest`\ s.  If *name* is not
+   specified, then ``obj.__name__`` is used.
+
+   The optional parameter *module* is the module that contains the given object.
+   If the module is not specified or is None, then the test finder will attempt to
+   automatically determine the correct module.  The object's module is used:
+
+   * As a default namespace, if *globs* is not specified.
+
+   * To prevent the DocTestFinder from extracting DocTests from objects that are
+     imported from other modules.  (Contained objects with modules other than
+     *module* are ignored.)
+
+   * To find the name of the file containing the object.
+
+   * To help find the line number of the object within its file.
+
+   If *module* is ``False``, no attempt to find the module will be made.  This is
+   obscure, of use mostly in testing doctest itself: if *module* is ``False``, or
+   is ``None`` but cannot be found automatically, then all objects are considered
+   to belong to the (non-existent) module, so all contained objects will
+   (recursively) be searched for doctests.
+
+   The globals for each :class:`DocTest` is formed by combining *globs* and
+   *extraglobs* (bindings in *extraglobs* override bindings in *globs*).  A new
+   shallow copy of the globals dictionary is created for each :class:`DocTest`.  If
+   *globs* is not specified, then it defaults to the module's *__dict__*, if
+   specified, or ``{}`` otherwise.  If *extraglobs* is not specified, then it
+   defaults to ``{}``.
+
+
+.. _doctest-doctestparser:
+
+DocTestParser objects
+^^^^^^^^^^^^^^^^^^^^^
+
+
+.. class:: DocTestParser()
+
+   A processing class used to extract interactive examples from a string, and use
+   them to create a :class:`DocTest` object.
+
+   .. versionadded:: 2.4
+
+:class:`DocTestParser` defines the following methods:
+
+
+.. method:: DocTestParser.get_doctest(string, globs, name, filename, lineno)
+
+   Extract all doctest examples from the given string, and collect them into a
+   :class:`DocTest` object.
+
+   *globs*, *name*, *filename*, and *lineno* are attributes for the new
+   :class:`DocTest` object.  See the documentation for :class:`DocTest` for more
+   information.
+
+
+.. method:: DocTestParser.get_examples(string[, name])
+
+   Extract all doctest examples from the given string, and return them as a list of
+   :class:`Example` objects.  Line numbers are 0-based.  The optional argument
+   *name* is a name identifying this string, and is only used for error messages.
+
+
+.. method:: DocTestParser.parse(string[, name])
+
+   Divide the given string into examples and intervening text, and return them as a
+   list of alternating :class:`Example`\ s and strings. Line numbers for the
+   :class:`Example`\ s are 0-based.  The optional argument *name* is a name
+   identifying this string, and is only used for error messages.
+
+
+.. _doctest-doctestrunner:
+
+DocTestRunner objects
+^^^^^^^^^^^^^^^^^^^^^
+
+
+.. class:: DocTestRunner([checker][, verbose][, optionflags])
+
+   A processing class used to execute and verify the interactive examples in a
+   :class:`DocTest`.
+
+   The comparison between expected outputs and actual outputs is done by an
+   :class:`OutputChecker`.  This comparison may be customized with a number of
+   option flags; see section :ref:`doctest-options` for more information.  If the
+   option flags are insufficient, then the comparison may also be customized by
+   passing a subclass of :class:`OutputChecker` to the constructor.
+
+   The test runner's display output can be controlled in two ways. First, an output
+   function can be passed to :meth:`TestRunner.run`; this function will be called
+   with strings that should be displayed.  It defaults to ``sys.stdout.write``.  If
+   capturing the output is not sufficient, then the display output can be also
+   customized by subclassing DocTestRunner, and overriding the methods
+   :meth:`report_start`, :meth:`report_success`,
+   :meth:`report_unexpected_exception`, and :meth:`report_failure`.
+
+   The optional keyword argument *checker* specifies the :class:`OutputChecker`
+   object (or drop-in replacement) that should be used to compare the expected
+   outputs to the actual outputs of doctest examples.
+
+   The optional keyword argument *verbose* controls the :class:`DocTestRunner`'s
+   verbosity.  If *verbose* is ``True``, then information is printed about each
+   example, as it is run.  If *verbose* is ``False``, then only failures are
+   printed.  If *verbose* is unspecified, or ``None``, then verbose output is used
+   iff the command-line switch :option:`-v` is used.
+
+   The optional keyword argument *optionflags* can be used to control how the test
+   runner compares expected output to actual output, and how it displays failures.
+   For more information, see section :ref:`doctest-options`.
+
+   .. versionadded:: 2.4
+
+:class:`DocTestParser` defines the following methods:
+
+
+.. method:: DocTestRunner.report_start(out, test, example)
+
+   Report that the test runner is about to process the given example. This method
+   is provided to allow subclasses of :class:`DocTestRunner` to customize their
+   output; it should not be called directly.
+
+   *example* is the example about to be processed.  *test* is the test containing
+   *example*.  *out* is the output function that was passed to
+   :meth:`DocTestRunner.run`.
+
+
+.. method:: DocTestRunner.report_success(out, test, example, got)
+
+   Report that the given example ran successfully.  This method is provided to
+   allow subclasses of :class:`DocTestRunner` to customize their output; it should
+   not be called directly.
+
+   *example* is the example about to be processed.  *got* is the actual output from
+   the example.  *test* is the test containing *example*.  *out* is the output
+   function that was passed to :meth:`DocTestRunner.run`.
+
+
+.. method:: DocTestRunner.report_failure(out, test, example, got)
+
+   Report that the given example failed.  This method is provided to allow
+   subclasses of :class:`DocTestRunner` to customize their output; it should not be
+   called directly.
+
+   *example* is the example about to be processed.  *got* is the actual output from
+   the example.  *test* is the test containing *example*.  *out* is the output
+   function that was passed to :meth:`DocTestRunner.run`.
+
+
+.. method:: DocTestRunner.report_unexpected_exception(out, test, example, exc_info)
+
+   Report that the given example raised an unexpected exception. This method is
+   provided to allow subclasses of :class:`DocTestRunner` to customize their
+   output; it should not be called directly.
+
+   *example* is the example about to be processed. *exc_info* is a tuple containing
+   information about the unexpected exception (as returned by
+   :func:`sys.exc_info`). *test* is the test containing *example*.  *out* is the
+   output function that was passed to :meth:`DocTestRunner.run`.
+
+
+.. method:: DocTestRunner.run(test[, compileflags][, out][, clear_globs])
+
+   Run the examples in *test* (a :class:`DocTest` object), and display the results
+   using the writer function *out*.
+
+   The examples are run in the namespace ``test.globs``.  If *clear_globs* is true
+   (the default), then this namespace will be cleared after the test runs, to help
+   with garbage collection. If you would like to examine the namespace after the
+   test completes, then use *clear_globs=False*.
+
+   *compileflags* gives the set of flags that should be used by the Python compiler
+   when running the examples.  If not specified, then it will default to the set of
+   future-import flags that apply to *globs*.
+
+   The output of each example is checked using the :class:`DocTestRunner`'s output
+   checker, and the results are formatted by the :meth:`DocTestRunner.report_\*`
+   methods.
+
+
+.. method:: DocTestRunner.summarize([verbose])
+
+   Print a summary of all the test cases that have been run by this DocTestRunner,
+   and return a tuple ``(failure_count, test_count)``.
+
+   The optional *verbose* argument controls how detailed the summary is.  If the
+   verbosity is not specified, then the :class:`DocTestRunner`'s verbosity is used.
+
+
+.. _doctest-outputchecker:
+
+OutputChecker objects
+^^^^^^^^^^^^^^^^^^^^^
+
+
+.. class:: OutputChecker()
+
+   A class used to check the whether the actual output from a doctest example
+   matches the expected output.  :class:`OutputChecker` defines two methods:
+   :meth:`check_output`, which compares a given pair of outputs, and returns true
+   if they match; and :meth:`output_difference`, which returns a string describing
+   the differences between two outputs.
+
+   .. versionadded:: 2.4
+
+:class:`OutputChecker` defines the following methods:
+
+
+.. method:: OutputChecker.check_output(want, got, optionflags)
+
+   Return ``True`` iff the actual output from an example (*got*) matches the
+   expected output (*want*).  These strings are always considered to match if they
+   are identical; but depending on what option flags the test runner is using,
+   several non-exact match types are also possible.  See section
+   :ref:`doctest-options` for more information about option flags.
+
+
+.. method:: OutputChecker.output_difference(example, got, optionflags)
+
+   Return a string describing the differences between the expected output for a
+   given example (*example*) and the actual output (*got*).  *optionflags* is the
+   set of option flags used to compare *want* and *got*.
+
+
+.. _doctest-debugging:
+
+Debugging
+---------
+
+Doctest provides several mechanisms for debugging doctest examples:
+
+* Several functions convert doctests to executable Python programs, which can be
+  run under the Python debugger, :mod:`pdb`.
+
+* The :class:`DebugRunner` class is a subclass of :class:`DocTestRunner` that
+  raises an exception for the first failing example, containing information about
+  that example. This information can be used to perform post-mortem debugging on
+  the example.
+
+* The :mod:`unittest` cases generated by :func:`DocTestSuite` support the
+  :meth:`debug` method defined by :class:`unittest.TestCase`.
+
+* You can add a call to :func:`pdb.set_trace` in a doctest example, and you'll
+  drop into the Python debugger when that line is executed.  Then you can inspect
+  current values of variables, and so on.  For example, suppose :file:`a.py`
+  contains just this module docstring::
+
+     """
+     >>> def f(x):
+     ...     g(x*2)
+     >>> def g(x):
+     ...     print x+3
+     ...     import pdb; pdb.set_trace()
+     >>> f(3)
+     9
+     """
+
+  Then an interactive Python session may look like this::
+
+     >>> import a, doctest
+     >>> doctest.testmod(a)
+     --Return--
+     > <doctest a[1]>(3)g()->None
+     -> import pdb; pdb.set_trace()
+     (Pdb) list
+       1     def g(x):
+       2         print x+3
+       3  ->     import pdb; pdb.set_trace()
+     [EOF]
+     (Pdb) print x
+     6
+     (Pdb) step
+     --Return--
+     > <doctest a[0]>(2)f()->None
+     -> g(x*2)
+     (Pdb) list
+       1     def f(x):
+       2  ->     g(x*2)
+     [EOF]
+     (Pdb) print x
+     3
+     (Pdb) step
+     --Return--
+     > <doctest a[2]>(1)?()->None
+     -> f(3)
+     (Pdb) cont
+     (0, 3)
+     >>>
+
+  .. versionchanged:: 2.4
+     The ability to use :func:`pdb.set_trace` usefully inside doctests was added.
+
+Functions that convert doctests to Python code, and possibly run the synthesized
+code under the debugger:
+
+
+.. function:: script_from_examples(s)
+
+   Convert text with examples to a script.
+
+   Argument *s* is a string containing doctest examples.  The string is converted
+   to a Python script, where doctest examples in *s* are converted to regular code,
+   and everything else is converted to Python comments.  The generated script is
+   returned as a string. For example, ::
+
+      import doctest
+      print doctest.script_from_examples(r"""
+          Set x and y to 1 and 2.
+          >>> x, y = 1, 2
+
+          Print their sum:
+          >>> print x+y
+          3
+      """)
+
+   displays::
+
+      # Set x and y to 1 and 2.
+      x, y = 1, 2
+      #
+      # Print their sum:
+      print x+y
+      # Expected:
+      ## 3
+
+   This function is used internally by other functions (see below), but can also be
+   useful when you want to transform an interactive Python session into a Python
+   script.
+
+   .. versionadded:: 2.4
+
+
+.. function:: testsource(module, name)
+
+   Convert the doctest for an object to a script.
+
+   Argument *module* is a module object, or dotted name of a module, containing the
+   object whose doctests are of interest.  Argument *name* is the name (within the
+   module) of the object with the doctests of interest.  The result is a string,
+   containing the object's docstring converted to a Python script, as described for
+   :func:`script_from_examples` above.  For example, if module :file:`a.py`
+   contains a top-level function :func:`f`, then ::
+
+      import a, doctest
+      print doctest.testsource(a, "a.f")
+
+   prints a script version of function :func:`f`'s docstring, with doctests
+   converted to code, and the rest placed in comments.
+
+   .. versionadded:: 2.3
+
+
+.. function:: debug(module, name[, pm])
+
+   Debug the doctests for an object.
+
+   The *module* and *name* arguments are the same as for function
+   :func:`testsource` above.  The synthesized Python script for the named object's
+   docstring is written to a temporary file, and then that file is run under the
+   control of the Python debugger, :mod:`pdb`.
+
+   A shallow copy of ``module.__dict__`` is used for both local and global
+   execution context.
+
+   Optional argument *pm* controls whether post-mortem debugging is used.  If *pm*
+   has a true value, the script file is run directly, and the debugger gets
+   involved only if the script terminates via raising an unhandled exception.  If
+   it does, then post-mortem debugging is invoked, via :func:`pdb.post_mortem`,
+   passing the traceback object from the unhandled exception.  If *pm* is not
+   specified, or is false, the script is run under the debugger from the start, via
+   passing an appropriate :func:`exec` call to :func:`pdb.run`.
+
+   .. versionadded:: 2.3
+
+   .. versionchanged:: 2.4
+      The *pm* argument was added.
+
+
+.. function:: debug_src(src[, pm][, globs])
+
+   Debug the doctests in a string.
+
+   This is like function :func:`debug` above, except that a string containing
+   doctest examples is specified directly, via the *src* argument.
+
+   Optional argument *pm* has the same meaning as in function :func:`debug` above.
+
+   Optional argument *globs* gives a dictionary to use as both local and global
+   execution context.  If not specified, or ``None``, an empty dictionary is used.
+   If specified, a shallow copy of the dictionary is used.
+
+   .. versionadded:: 2.4
+
+The :class:`DebugRunner` class, and the special exceptions it may raise, are of
+most interest to testing framework authors, and will only be sketched here.  See
+the source code, and especially :class:`DebugRunner`'s docstring (which is a
+doctest!) for more details:
+
+
+.. class:: DebugRunner([checker][, verbose][, optionflags])
+
+   A subclass of :class:`DocTestRunner` that raises an exception as soon as a
+   failure is encountered.  If an unexpected exception occurs, an
+   :exc:`UnexpectedException` exception is raised, containing the test, the
+   example, and the original exception.  If the output doesn't match, then a
+   :exc:`DocTestFailure` exception is raised, containing the test, the example, and
+   the actual output.
+
+   For information about the constructor parameters and methods, see the
+   documentation for :class:`DocTestRunner` in section :ref:`doctest-advanced-api`.
+
+There are two exceptions that may be raised by :class:`DebugRunner` instances:
+
+
+.. exception:: DocTestFailure(test, example, got)
+
+   An exception thrown by :class:`DocTestRunner` to signal that a doctest example's
+   actual output did not match its expected output. The constructor arguments are
+   used to initialize the member variables of the same names.
+
+:exc:`DocTestFailure` defines the following member variables:
+
+
+.. attribute:: DocTestFailure.test
+
+   The :class:`DocTest` object that was being run when the example failed.
+
+
+.. attribute:: DocTestFailure.example
+
+   The :class:`Example` that failed.
+
+
+.. attribute:: DocTestFailure.got
+
+   The example's actual output.
+
+
+.. exception:: UnexpectedException(test, example, exc_info)
+
+   An exception thrown by :class:`DocTestRunner` to signal that a doctest example
+   raised an unexpected exception.  The constructor arguments are used to
+   initialize the member variables of the same names.
+
+:exc:`UnexpectedException` defines the following member variables:
+
+
+.. attribute:: UnexpectedException.test
+
+   The :class:`DocTest` object that was being run when the example failed.
+
+
+.. attribute:: UnexpectedException.example
+
+   The :class:`Example` that failed.
+
+
+.. attribute:: UnexpectedException.exc_info
+
+   A tuple containing information about the unexpected exception, as returned by
+   :func:`sys.exc_info`.
+
+
+.. _doctest-soapbox:
+
+Soapbox
+-------
+
+As mentioned in the introduction, :mod:`doctest` has grown to have three primary
+uses:
+
+#. Checking examples in docstrings.
+
+#. Regression testing.
+
+#. Executable documentation / literate testing.
+
+These uses have different requirements, and it is important to distinguish them.
+In particular, filling your docstrings with obscure test cases makes for bad
+documentation.
+
+When writing a docstring, choose docstring examples with care. There's an art to
+this that needs to be learned---it may not be natural at first.  Examples should
+add genuine value to the documentation.  A good example can often be worth many
+words. If done with care, the examples will be invaluable for your users, and
+will pay back the time it takes to collect them many times over as the years go
+by and things change.  I'm still amazed at how often one of my :mod:`doctest`
+examples stops working after a "harmless" change.
+
+Doctest also makes an excellent tool for regression testing, especially if you
+don't skimp on explanatory text.  By interleaving prose and examples, it becomes
+much easier to keep track of what's actually being tested, and why.  When a test
+fails, good prose can make it much easier to figure out what the problem is, and
+how it should be fixed.  It's true that you could write extensive comments in
+code-based testing, but few programmers do. Many have found that using doctest
+approaches instead leads to much clearer tests.  Perhaps this is simply because
+doctest makes writing prose a little easier than writing code, while writing
+comments in code is a little harder.  I think it goes deeper than just that:
+the natural attitude when writing a doctest-based test is that you want to
+explain the fine points of your software, and illustrate them with examples.
+This in turn naturally leads to test files that start with the simplest
+features, and logically progress to complications and edge cases.  A coherent
+narrative is the result, instead of a collection of isolated functions that test
+isolated bits of functionality seemingly at random.  It's a different attitude,
+and produces different results, blurring the distinction between testing and
+explaining.
+
+Regression testing is best confined to dedicated objects or files.  There are
+several options for organizing tests:
+
+* Write text files containing test cases as interactive examples, and test the
+  files using :func:`testfile` or :func:`DocFileSuite`.  This is recommended,
+  although is easiest to do for new projects, designed from the start to use
+  doctest.
+
+* Define functions named ``_regrtest_topic`` that consist of single docstrings,
+  containing test cases for the named topics.  These functions can be included in
+  the same file as the module, or separated out into a separate test file.
+
+* Define a ``__test__`` dictionary mapping from regression test topics to
+  docstrings containing test cases.
+
+.. rubric:: Footnotes
+
+.. [#] Examples containing both expected output and an exception are not supported.
+   Trying to guess where one ends and the other begins is too error-prone, and that
+   also makes for a confusing test.
+