Issue #12947: Backport doctest documentation improvements from 3.3.
This commit is contained in:
Chris Jerdonek
parent
7c06801638
commit
d469c400ed
|
|
@ -339,7 +339,8 @@ The fine print:
|
|||
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 directive is in effect.
|
||||
: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
|
||||
|
|
@ -511,15 +512,16 @@ Some details you should read once, but won't need to remember:
|
|||
SyntaxError: invalid syntax
|
||||
|
||||
|
||||
.. _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
|
||||
doctest decides whether actual output matches an example's expected output:
|
||||
|
|
@ -573,8 +575,8 @@ doctest decides whether actual output matches an example's expected output:
|
|||
:exc:`TypeError` is raised.
|
||||
|
||||
It will also ignore the module name used in Python 3 doctest reports. Hence
|
||||
both these variations will work regardless of whether the test is run under
|
||||
Python 2.7 or Python 3.2 (or later versions):
|
||||
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') #doctest: +IGNORE_EXCEPTION_DETAIL
|
||||
Traceback (most recent call last):
|
||||
|
|
@ -590,15 +592,16 @@ doctest decides whether actual output matches an example's expected output:
|
|||
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 doctest directives and ignore them
|
||||
as irrelevant comments). For example, ::
|
||||
earlier (those releases do not support :ref:`doctest directives
|
||||
<doctest-directives>` and ignore them as irrelevant comments). 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.3 and later Python versions, even though the detail
|
||||
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
|
||||
|
|
@ -662,9 +665,40 @@ The second group of options controls how test failures are reported:
|
|||
|
||||
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
|
||||
directive: "#" "doctest:" `directive_options`
|
||||
|
|
@ -739,28 +773,7 @@ functions that run doctests, establishing different defaults. In such cases,
|
|||
disabling an option via ``-`` in a directive can be useful.
|
||||
|
||||
.. versionadded:: 2.4
|
||||
Doctest directives and the associated 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
|
||||
Support for doctest directives was added.
|
||||
|
||||
|
||||
.. _doctest-warnings:
|
||||
|
|
@ -800,7 +813,9 @@ Another bad idea is to print things that embed an object address, like ::
|
|||
>>> 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::
|
||||
The :const:`ELLIPSIS` directive gives a nice approach for the last example:
|
||||
|
||||
.. code-block:: text
|
||||
|
||||
>>> C() #doctest: +ELLIPSIS
|
||||
<__main__.C instance at 0x...>
|
||||
|
|
|
|||
Loading…
Reference in New Issue