Changeset 391 for python/trunk/Doc/library/doctest.rst

Timestamp:

Mar 19, 2014, 11:31:01 PM (11 years ago)

Author:

dmik

Message:

python: Merge vendor 2.7.6 to trunk.

Location:

python/trunk

Files:

• . (modified) (1 prop)
• Doc/library/doctest.rst (modified) (25 diffs)

python/trunk/Doc/library/doctest.rst

@@ +1 @@
+:keepdoctest:
+
 :mod:`doctest` --- Test interactive Python examples
 ===================================================
@@ -96 +98 @@
 
 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
+``-v`` to the script, and :mod:`doctest` prints a detailed log of what
 it's trying, and prints a summary at the end::
 
@@ -164 +166 @@
 number of examples that failed.
 
-Run it with the :option:`-v` switch instead::
+Run it with the ``-v`` switch instead::
 
    python M.py -v
@@ -173 +175 @@
 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
+``sys.argv`` is not examined by :func:`testmod` (so passing ``-v`` or not
 has no effect).
 
@@ -243 +245 @@
 
 Like :func:`testmod`, :func:`testfile`'s verbosity can be set with the
-:option:`-v` command-line switch or with the optional keyword argument
+``-v`` command-line switch or with the optional keyword argument
 *verbose*.
 
@@ -300 +302 @@
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-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.
+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.
 
 ::
@@ -339 +334 @@
   is expected.
 
-  .. versionchanged:: 2.4
+  .. versionadded:: 2.4
      ``<BLANKLINE>`` was added; there was no way to use expected output containing
      empty lines in previous versions.
+
+* All hard tab characters are expanded to spaces, using 8-column tab stops.
+  Tabs in output generated by the tested code are not modified.  Because any
+  hard tabs in the sample output *are* expanded, this means that if the code
+  output includes hard tabs, the only way the doctest can pass is if the
+  :const:`NORMALIZE_WHITESPACE` option or :ref:`directive <doctest-directives>`
+  is in effect.
+  Alternatively, the test can be rewritten to capture the output and compare it
+  to an expected value as part of the test.  This handling of tabs in the
+  source was arrived at through trial and error, and has proven to be the least
+  error prone way of handling them.  It is possible to use a different
+  algorithm for handling tabs by writing a custom :class:`DocTestParser` class.
+
+  .. versionchanged:: 2.4
+     Expanding tabs to spaces is new; previous versions tried to preserve hard tabs,
+     with confusing results.
 
 * Output to stdout is captured, but not output to stderr (exception tracebacks
@@ -356 +367 @@
 
   Otherwise, the backslash will be interpreted as part of the string. For example,
-  the "\\" above would be interpreted as a newline character.  Alternatively, you
+  the ``\n`` above would be interpreted as a newline character.  Alternatively, you
   can double each backslash in the doctest version (and not use a raw string)::
 
@@ -439 +450 @@
 exception's type and detail, and the rest are ignored.
 
+.. versionchanged:: 2.4
+   Previous versions were unable to handle multi-line exception details.
+
 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::
@@ -470 +484 @@
   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.
+* When the :const:`IGNORE_EXCEPTION_DETAIL` doctest option is specified,
+  everything following the leftmost colon and any module information in the
+  exception name is ignored.
 
 * The interactive shell omits the traceback header line for some
@@ -499 +514 @@
      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.
-
-
+
+.. _option-flags-and-directives:
 .. _doctest-options:
 
-Option Flags and Directives
-^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Option Flags
+^^^^^^^^^^^^
 
 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).
+:ref:`doctest directives <doctest-directives>`.
 
 The first group of options define test semantics, controlling aspects of how
@@ -565 +577 @@
    :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
+   It will also ignore the module name used in Python 3 doctest reports. Hence
+   both of these variations will work with the flag specified, regardless of
+   whether the test is run under Python 2.7 or Python 3.2 (or later versions)::
+
+      >>> raise CustomError('message')
+      Traceback (most recent call last):
+      CustomError: message
+
+      >>> raise CustomError('message')
+      Traceback (most recent call last):
+      my_module.CustomError: message
+
+   Note that :const:`ELLIPSIS` can also be used to ignore the
+   details of the exception message, but such a test may still fail based
+   on whether or not the module details are printed as part of the
+   exception name. Using :const:`IGNORE_EXCEPTION_DETAIL` and the details
+   from Python 2.3 is also the only clear way to write a doctest that doesn't
+   care about the exception detail yet continues to pass under Python 2.3 or
+   earlier (those releases do not support :ref:`doctest directives
+   <doctest-directives>` and ignore them as irrelevant comments). For example::
+
+      >>> (1, 2)[3] = 'moo'
       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".
+   passes under Python 2.3 and later Python versions with the flag specified,
+   even though the detail
+   changed in Python 2.4 to say "does not" instead of "doesn't".
+
+   .. versionchanged:: 2.7
+      :const:`IGNORE_EXCEPTION_DETAIL` now also ignores any information
+      relating to the module containing the exception under test
 
 
@@ -590 +621 @@
 
    The SKIP flag can also be used for temporarily "commenting out" examples.
+
+.. versionadded:: 2.5
 
 
@@ -635 +668 @@
    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:
+
+.. versionadded:: 2.4
+   The 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.
+
+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-directives:
+
+Directives
+^^^^^^^^^^
+
+Doctest directives may be used to modify the :ref:`option flags
+<doctest-options>` for an individual example.  Doctest directives are
+special Python comments following an example's source code:
 
 .. productionlist:: doctest
@@ -655 +719 @@
 For example, this test passes::
 
-   >>> print range(20) #doctest: +NORMALIZE_WHITESPACE
+   >>> 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]
@@ -664 +728 @@
 so::
 
-   >>> print range(20) # doctest:+ELLIPSIS
+   >>> print range(20) # doctest: +ELLIPSIS
    [0, 1, ..., 18, 19]
 
-Multiple directives can be used on a single physical line, separated by commas::
+Multiple directives can be used on a single physical line, separated by
+commas::
 
    >>> print range(20) # doctest: +ELLIPSIS, +NORMALIZE_WHITESPACE
@@ -693 +758 @@
 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
+.. versionadded:: 2.4
+   Support for doctest directives was added.
 
 
@@ -949 +989 @@
 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::
+test suites from modules and text files containing doctests.  To integrate with
+:mod:`unittest` test discovery, include a :func:`load_tests` function in your
+test module::
 
    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)
+   import my_module_with_doctests
+
+   def load_tests(loader, tests, ignore):
+       tests.addTests(doctest.DocTestSuite(my_module_with_doctests))
+       return tests
 
 There are two main functions for creating :class:`unittest.TestSuite` instances
@@ -1037 +1076 @@
    .. versionchanged:: 2.5
       The parameter *encoding* was added.
+
+   .. note::
+      Unlike :func:`testmod` and :class:`DocTestFinder`, this function raises
+      a :exc:`ValueError` if *module* contains no docstrings.  You can prevent
+      this error by passing a :class:`DocTestFinder` instance as the
+      *test_finder* argument with its *exclude_empty* keyword argument set
+      to ``False``::
+
+         >>> finder = doctest.DocTestFinder(exclude_empty=False)
+         >>> suite = doctest.DocTestSuite(test_finder=finder)
 
 
@@ -1177 +1226 @@
 
    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.
+   constructor arguments are used to initialize the attributes of the same names.
 
    .. versionadded:: 2.4
 
-   :class:`DocTest` defines the following member variables.  They are initialized by
+   :class:`DocTest` defines the following attributes.  They are initialized by
    the constructor, and should not be modified directly.
 
@@ -1235 +1283 @@
 
    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.
+   output.  The constructor arguments are used to initialize the attributes of the
+   same names.
 
    .. versionadded:: 2.4
 
-   :class:`Example` defines the following member variables.  They are initialized by
+   :class:`Example` defines the following attributes.  They are initialized by
    the constructor, and should not be modified directly.
 
@@ -1431 +1479 @@
    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.
+   iff the command-line switch ``-v`` is used.
 
    The optional keyword argument *optionflags* can be used to control how the test
@@ -1746 +1794 @@
 .. exception:: DocTestFailure(test, example, got)
 
-   An exception thrown by :class:`DocTestRunner` to signal that a doctest example's
+   An exception raised 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:
+   used to initialize the attributes of the same names.
+
+:exc:`DocTestFailure` defines the following attributes:
 
 
@@ -1770 +1818 @@
 .. 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:
+   An exception raised by :class:`DocTestRunner` to signal that a doctest
+   example raised an unexpected exception.  The constructor arguments are used
+   to initialize the attributes of the same names.
+
+:exc:`UnexpectedException` defines the following attributes:
 
 
@@ -1857 +1905 @@
    Trying to guess where one ends and the other begins is too error-prone, and that
    also makes for a confusing test.
-