gh-92417: Update docs and examples of doctest.IGNORE_EXCEPTION_DETAIL for Py>=3

[CAM-Gerlach]

Part of issue #92417 and followup to @AlexWaygood 's PR #92420 .

Following #92420 , there's still a chunk of text in the doctest library docs referring to compatibility with Python <3.2, and workarounds to support Python <2.4, in the description of doctest.EXCEPTION_DETAIL which it seems should be elided as well.

It substantially complicates the description of doctest.IGNORE_EXCEPTION_DETAIL and doesn't seem to be of any use for modern Python, beyond what is already noted in the versionchanged notice. Furthermore, it made the section pretty difficult to understand and parse for me even as a native English speaker, technical writer/copyeditor and reasonably experianced Python developer; I had to re-read it several times to fully grasp the intended meaning.

Therefore, I simplified the section to remove the outdated material and focus on the functionality relevant to modern Python, while retaining the existing versionchanged note that already captured the key version differences clearly.

Sidenote, I'm a triager now, so I'm not sure why I still can't set the PR tags and such when creating the PR, but can perfectly fine after it is created (causing the skip-news check to initially fail and resulting in additional noise on the PR).

[AlexWaygood]

I'd like to review this — @JelleZijlstra, can you give me a day or two before merging? :)

[AlexWaygood]

I believe that the example on lines 576-582 is meant to illustrate how this option creates cross-compatibility between Python 2 and 3. In Python 3, the fully qualified name of the exception is, I believe, always shown:

>>> class CustomError(Exception): ...
...
>>> raise CustomError('message')
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
__main__.CustomError: message

So, maybe that should also go.

[AlexWaygood]

In general, I'm worried that this part of the doctest API seems like it might be there only to provide cross-compatibility between Python 2 and Python 3. If that's the case, rather than just deleting all documentation about it, we should maybe just deprecate the feature?

[CAM-Gerlach]

To respond to your high-level feedback, it took several re-readings of the original to ensure I was clear, but unless I'm grossly misunderstanding it, this overall feature seems to have substantially broader applicability than just differences between older Python versions (and newer/future Python versions, for that matter).

Just for the built-in exception classes, error messages may vary on newer Python versions as well (as there has been a comprehensive effort in the past couple to rewrite them to be clearer and more understandable), potentially even across bugfix releases. Beyond that, non-builtin exceptions may change their error messages at any time, which may or may not be under control of the doctest author. And there could also be situations where part of the error message may not be entirely deterministic, or may intentionally not match the exact output for illustrative purposes.

Therefore, this feature would seem to have significant utility beyond one particular example of older Python version differences (minus the examples and guidance I removed that were specific to older Python versions). To avoid this, we could introduce a new option, IGNORE_EXCEPTION_MESSAGE, that just ignores the message but not the module (as IGNORE_EXCEPTION_DETAIL originally did), but that call would be above my pay grade.

The outstanding use case for ignoring the module name of the exception appears to be smaller, but still arguably present; it should mean doctests would not fail if the location of the exception class was refactored to a different or renamed module across versions of Python, a third-party library or the user's own code, so long as its class was the same. There may be an argument to be made that this lack of strictness may be less desirable than just differences in the displayed text, but that would be a backwards-incompatible change that could break existing passing doctests, so there would need to be a compelling benefit to remove it which I'm not sure is worth it.

I see @tim-one is marked as the (inactive) doctest maintainer in the Experts Index, and from git blame it looks like @ncoghlan committed the original addition based on an initial patch by @regebro . Pinging them to see if they have any insight on this.

[CAM-Gerlach]

@rhettinger Could you explain why the needs backport to 3.9 label was removed? Both 3.10 and 3.9 are still in bugfix mode, the change only affects compatibility with Python releases (2.3 and 2.7) that were EoL back when 3.9 was first released, and besides beyond just removing very-outdated material, it fixes a substantive defect given said explanations make the documentation difficult to understand and follow, as evidenced by both @AlexWaygood and my own initial confusion over what specifically this option did. Thanks.

[regebro]

IIRC the IGNORE_EXCEPTION_* things were indeed added exactly for 2/3 compatibility, but I agree with you, it's also useful in cases where a module gets refactored, or where maybe you support a future.module import etc, so I think it shouldn't be removed completely.

The changes now look reasonable to me.

[AlexWaygood]

@CAM-Gerlach, I'd prefer to wait for Tim's feedback, since he's been requested for review :)

I feel like if this feature is still relevant for Python 3, we should probably replace the Python 2 examples with Python 3 examples. But most of the docs around this feature seem to currently be focused around py2/3 compatibility, and I don't have enough experience with the feature to really suggest any alternatives.

[CAM-Gerlach]

I feel like if this feature is still relevant for Python 3, we should probably replace the Python 2 examples with Python 3 examples. But most of the docs around this feature seem to currently be focused around py2/3 compatibility, and I don't have enough experience with the feature to really suggest any alternatives.

The example for message is already fully version-agnostic; I've tweaked the example for module names to be more appropriate and well as implemented the wording revision to the Ellipses reference suggested in response to your comment above to match. The remaining examples that were removed were just specific workarounds for earlier Py<3 versions that are no longer needed/relevant.

[AlexWaygood]

LGTM, but I'd still prefer to wait a little longer to see if Tim has any feedback :)

[serhiy-storchaka]

Please keep an example without module name.

The module name is not output if it is "builtins" or "__main__". Some extension types can have __module__ incorrectly set to "builtins", because it is the default, it is not rare case.

[CAM-Gerlach]

Thanks; I included examples both with, without and with a different module name, using the plausible real-world examples you list above.

[serhiy-storchaka]

Technically, it ignores not only the module name, but the full qualified name except the name of the exception type (the last component). I would perhaps merge it with the previous paragraph: "... the exception detail (such as the full qualified name or arguments) ..."

It may be worth to explain why this directive is needed: the full qualified name and message can be different between different versions of Python or other libraries and between the Python and the C implementations.

[CAM-Gerlach]

Thanks; I rewrote the section accordingly to clarify the points you raised and explain why it is needed. I also clarified some potentially confusing/hard to understand phrasing and fixed the code block syntax highlighting, among other minor improvements.

[JelleZijlstra]

This looks good to me as it explains the feature clearly without talking about long-dead Python 2.3 compatibility. I'll leave merging this to others though.

[miss-islington]

Thanks @CAM-Gerlach for the PR, and @ambv for merging it 🌮🎉.. I'm working now to backport this PR to: 3.9, 3.10, 3.11.
🐍🍒⛏🤖

[bedevere-bot]

GH-92962 is a backport of this pull request to the 3.11 branch.

[bedevere-bot]

GH-92963 is a backport of this pull request to the 3.10 branch.

[bedevere-bot]

GH-92964 is a backport of this pull request to the 3.9 branch.