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.

Activity

added
docsDocumentation in the Doc dir
3.11only security fixes
3.12only security fixes
3.13bugs and security fixes
on Nov 9, 2023
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[/+] on Nov 9, 2023
Lincoln-developer

Lincoln-developer commented on Nov 16, 2023

@Lincoln-developer
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

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

        Participants

        @ericsnowcurrently@Lincoln-developer

        Issue actions

          The Attributes of Exception Objects are not Clearly Documented and Easily Discoverable · Issue #111917 · python/cpython