GV

GeezerVison

The World Wide Web, restored to 800 pixels of glory.

Home|About|Gaming cabinet|Archives|How it works|Starter sites

On this site

  • Sign in
  • ActionsCI/CD and automation
  • CodespacesCloud development environments
  • All Features
  • Documentation
  • Training
  • Certifications
  • Build with Copilot
  • Customize Copilot
  • Integrations
  • Trending repos
  • GitHub Sponsors
  • Developer articles
  • Enterprises

This view

  • Original page
  • New address

GeezerVison is showing github.com — The Attributes of Exception Objects are not Clearly Documented and Easily Discoverable · Issue #111917 · python/cpython

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

New issue
Copy link
New issue
Copy link
Closed
Closed
The Attributes of Exception Objects are not Clearly Documented and Easily Discoverable#111917
Copy link
Labels
docsDocumentation in the Doc dirDocumentation in the Doc dir

Description

@ericsnowcurrently
ericsnowcurrently
opened on Nov 9, 2023
Issue body actions

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:
  • https://docs.python.org/3.12/library/traceback.html
    • __traceback__ - mentioned at the top
    • __traceback__ - used in examples
    • __traceback__ - implies that TracebackException.stack (ergo StackSummary/FrameSummary) is a substitute
    • __cause__ - mentions it's involved with exception chaining
    • __cause__ - describes a corresponding TracebackExeption attr
    • __context__ - mentions it's involved with exception chaining
    • __context__ - describes a corresponding TracebackExeption attr
    • __suppress_context__ - describes a corresponding TracebackExeption attr
    • __notes__ - describes a corresponding TracebackException attr
    • talks about the relationship between __cause__, __context__, and __suppress_context__
    • indicates how __cause__ and __context__ relate to exception formatting (e.g. sys.excepthook())
  • https://docs.python.org/3.12/library/exceptions.html
    • __cause__ - explains how this gets set
    • __context__ - explains how this gets set
    • __suppress_context__ - explains what this is for
    • explains the relationship between __cause__, __context__, and __suppress_context__
    • __traceback__ - explains how to use a legacy way of setting the traceback from Python code
    • args - explains how this gets set
    • explains (twice) how __traceback__, __cause__, __context__, and __notes__ are propagated to ExceptionGroup subgroups
  • https://docs.python.org/3.12/reference/simple_stmts.html
    • __cause__ - explains how this is set via raise exc1 from exc2 and what caveats apply
    • __context__ - explains how this is set
    • __suppress_context__ - mentions its effect
    • __traceback__ - explains how this is set
  • https://docs.python.org/3.12/reference/datamodel.html
    • __traceback__ - explains how it is set when exception unwinding hits an exception handler
  • https://docs.python.org/3.12/reference/expressions.html
    • __traceback__ - explains how to replace the traceback on an exception thrown into a generator
  • https://docs.python.org/3.12/library/types.html
    • __traceback__ - mentions that traceback objects can be found there
  • https://docs.python.org/3.12/library/dis.html
    • __cause__ - RAISE_VARARGS sets it for raise exc1 from exc2
  • https://docs.python.org/3.12/c-api/exceptions.html
    • __cause__ - explains how to get and set this
    • __context__ - explains how to get and set this
    • __traceback__ - explains how to get and set this
    • args - explains how to get and set this

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:

  • a table in https://docs.python.org/3.12/library/exceptions.html indicating which builtin exception types have which attributes
  • a link in https://docs.python.org/3.12/library/types.html to the language reference entry

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:

  • Missing Signature Info for Builtin Exceptions in help() and Docs #111405
  • https://peps.python.org/pep-3134/

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. ↩

Reacted by Alex, Civ Ysh K and Gabriel Kakizaki

Activity

  1. ericsnowcurrently
    added
    docsDocumentation in the Doc dirDocumentation in the Doc dir
    3.11only security fixesonly security fixes
    3.12only security fixesonly security fixes
    3.13only security fixesonly security fixes
    on Nov 9, 2023
  2. 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[/+] on Nov 9, 2023

  3. Lincoln-developer commented on Nov 16, 2023

    @Lincoln-developer
    Lincoln-developer
    on Nov 16, 2023 · Hidden as outdated
    show commentMore actions
  4. StanFromIreland
    removed
    3.11only security fixesonly security fixes
    3.12only security fixesonly security fixes
    3.13only security fixesonly security fixes
    on Aug 20, 2026
  5. github-project-automation
    added this to docs issueson Aug 20, 2026
  6. github-project-automation
    moved this to Todo in docs issueson Aug 20, 2026

  7. StanFromIreland commented on Aug 20, 2026

    @StanFromIreland
    StanFromIreland
    on Aug 20, 2026
    Member
    More actions

    Closing as completed by d05a180.

  8. StanFromIreland
    closed this as completedon Aug 20, 2026
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

    docsDocumentation in the Doc dirDocumentation in the Doc dir

    Projects

    • docs issues
      Status
      Todo
      Show more project fields

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions
    You are visitor 01402520 — GeezerVison does not store the pages you look up.
    Best viewed with Netscape Navigator 4.7 or Internet Explorer 6 at 800×600. No cookies required.