Skip to content

The Attributes of Exception Objects are not Clearly Documented and Easily Discoverable #111917

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.

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

Open
ericsnowcurrently opened this issue Nov 9, 2023 · 1 comment
Labels
3.11 only security fixes 3.12 only security fixes 3.13 bugs and security fixes docs Documentation in the Doc dir

Comments

@ericsnowcurrently
Copy link
Member

All exception objects (instances of BaseException) have the following12 unique attributes:

  • __cause__
  • __context__
  • __suppress_context__
  • __traceback__
  • __notes__ (only set if exc.add_note() was called)
  • args

The Problem

The documentation doesn't have a good place to go to find out what attributes to expect on exception objects. There are some explicit enumerations on the Built-in Exceptions page for specific exception types (e.g. ImportError), which is fine (see below), as well as one-off mentions of individual attributes spread around the docs, but no one place to go if you are asking "what attributes do exceptions have"?

The closest we have is the attribute list for traceback.TracebackException.

Here's what I've found in the docs currently:

Like I said, if you want the full picture then currently you have to piece things together.

Furthermore, the following details are not clearly specified (unless I missed something):

  • does raise exc only support exceptions?
  • must __cause__ be an exception?
  • must __context__ be an exception?
  • must __traceback__ be a TracebackType object?
  • what breaks if __notes__ was set to a string? to something other than a list?
  • ...

Expectations

Without having given it much deep thought, I'd expect the following:

  • an entry in the language reference detailing the interface all exceptions (i.e. BaseException) are expected to satisfy
  • a note in https://docs.python.org/3.12/library/exceptions.html pointing to that entry
  • the various other places that currently provide details about these attributes should point to the language reference entry instead

Additionally, the following might be worth doing:

Prior art for detailing attributes of core types includes work we did a while back for the import system, both related to modules and importers.

Also see:

Footnotes

  1. Arguably, msg or message should also be an attribute of BaseException, but that's out of scope for this issue.

  2. Some builtin exceptions types have additional specific attributes. See gh-111405.

@ericsnowcurrently ericsnowcurrently added docs Documentation in the Doc dir 3.11 only security fixes 3.12 only security fixes 3.13 bugs and security fixes labels Nov 9, 2023
@ericsnowcurrently ericsnowcurrently changed the title The Attributes of Exception Objects are Clearly Documented and Easily Discoverable The Attributes of Exception Objects are not Clearly Documented and Easily Discoverable Nov 9, 2023
@Lincoln-developer
Copy link
Contributor

Hey, kindly I would love to work on this issue if you don't mind. Thanks.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
3.11 only security fixes 3.12 only security fixes 3.13 bugs and security fixes docs Documentation in the Doc dir
Projects
None yet
Development

No branches or pull requests

2 participants