Skip to content

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

Open
@ericsnowcurrently

Description

@ericsnowcurrently

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.

Metadata

Metadata

Assignees

No one assigned

    Labels

    3.11only security fixes3.12only security fixes3.13bugs and security fixesdocsDocumentation in the Doc dir

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions