[Python-checkins] cpython (2.7): Issue #12947: Backport doctest documentation improvements from 3.3.
chris.jerdonek
python-checkins at python.org
Wed Oct 10 16:21:27 CEST 2012
http://hg.python.org/cpython/rev/15bfa778ec21
changeset: 79637:15bfa778ec21
branch: 2.7
parent: 79614:b2f282991973
user: Chris Jerdonek <chris.jerdonek at gmail.com>
date: Wed Oct 10 07:13:56 2012 -0700
summary:
Issue #12947: Backport doctest documentation improvements from 3.3.
files:
Doc/library/doctest.rst | 85 +++++++++++++++++-----------
1 files changed, 50 insertions(+), 35 deletions(-)
diff --git a/Doc/library/doctest.rst b/Doc/library/doctest.rst
--- a/Doc/library/doctest.rst
+++ b/Doc/library/doctest.rst
@@ -339,7 +339,8 @@
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 @@
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 @@
: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 @@
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 @@
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 @@
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 @@
>>> 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...>
--
Repository URL: http://hg.python.org/cpython
More information about the Python-checkins
mailing list