[Python-checkins] gh-92417: Update docs and examples of doctest.IGNORE_EXCEPTION_DETAIL for Py>=3 (GH-92502) (GH-92964)
ambv
webhook-mailer at python.org
Thu May 19 11:21:30 EDT 2022
https://github.com/python/cpython/commit/3bc3c89612484474aeb9b59d17d989dab7854e10
commit: 3bc3c89612484474aeb9b59d17d989dab7854e10
branch: 3.9
author: Miss Islington (bot) <31488909+miss-islington at users.noreply.github.com>
committer: ambv <lukasz at langa.pl>
date: 2022-05-19T17:21:23+02:00
summary:
gh-92417: Update docs and examples of doctest.IGNORE_EXCEPTION_DETAIL for Py>=3 (GH-92502) (GH-92964)
(cherry picked from commit 97b9c1096feff77a564787ef520cc7d4e1d1c45f)
files:
M Doc/library/doctest.rst
diff --git a/Doc/library/doctest.rst b/Doc/library/doctest.rst
index a77322f83acbd..3d2bb27ec2356 100644
--- a/Doc/library/doctest.rst
+++ b/Doc/library/doctest.rst
@@ -568,41 +568,35 @@ doctest decides whether actual output matches an example's expected output:
.. 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.
+ When specified, doctests expecting exceptions pass so long as an exception
+ of the expected type is raised, even if the details
+ (message and fully-qualified exception name) don't match.
- 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)::
+ For example, an example expecting ``ValueError: 42`` will pass if the actual
+ exception raised is ``ValueError: 3*14``, but will fail if, say, a
+ :exc:`TypeError` is raised instead.
+ It will also ignore any fully-qualified name included before the
+ exception class, which can vary between implementations and versions
+ of Python and the code/libraries in use.
+ Hence, all three of these variations will work with the flag specified:
- >>> raise CustomError('message')
+ .. code-block:: pycon
+
+ >>> raise Exception('message')
Traceback (most recent call last):
- CustomError: message
+ Exception: message
- >>> raise CustomError('message')
+ >>> raise Exception('message')
Traceback (most recent call last):
- my_module.CustomError: message
+ builtins.Exception: 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'
+ >>> raise Exception('message')
Traceback (most recent call last):
- File "<stdin>", line 1, in <module>
- TypeError: object doesn't support item assignment
+ __main__.Exception: message
- 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".
+ 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 the module name is present or matches exactly.
.. versionchanged:: 3.2
:const:`IGNORE_EXCEPTION_DETAIL` now also ignores any information relating
More information about the Python-checkins
mailing list