8000 [3.9] gh-92417: Update docs and examples of doctest.IGNORE_EXCEPTION_DETAIL for Py>=3 (GH-92502) by miss-islington · Pull Request #92964 · python/cpython · GitHub
[go: up one dir, main page]
Skip to content

[3.9] gh-92417: Update docs and examples of doctest.IG 8000 NORE_EXCEPTION_DETAIL for Py>=3 (GH-92502) #92964

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
May 19, 2022
Merged

[3.9] gh-92417: Update docs and examples of doctest.IGNORE_EXCEPTION_DETAIL for Py>=3 (GH-92502) #92964

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
8000
Diff view
48 changes: 21 additions & 27 deletions Doc/library/doctest.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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: 8000 `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
Expand Down
0