Documentation

The errors tutorial, chapter 8.3 contains an example that could be improved, as the highlighted subjects (exception ordering and matching) are not that easy to follow: https://docs.python.org/3/tutorial/errors.html

The issue was discussed here:
https://discuss.python.org/t/exception-tutorial-confusion/97456

Original:
A class in an except clause matches exceptions which are instances of the class itself or one of its derived classes (but not the other way around — an except clause listing a derived class does not match instances of its base classes). For example, the following code will print B, C, D in that order:

class B(Exception): pass class C(B): pass class D(C): pass for cls in [B, C, D]: try: raise cls() except D: print("D") except C: print("C") except B: print("B")

Note that if the except clauses were reversed (with except B first), it would have printed B, B, B — the first matching except clause is triggered.

Suggested Update
Code examples created by Guido van Rossum, see https://discuss.python.org/t/exception-tutorial-confusion/97456/5.
A class in an except clause matches exceptions which are instances of the class itself or one of its derived classes (but not the other way around — an except clause listing a derived class does not match instances of its base classes).

For example, the following code will print B, C in that order:

class B(Exception): pass class C(B): pass for cls in [B, C]: try: raise cls() except C: # Matches C but not B. print("C") except B: # Matches B; not reached for C. print("B")

Note that if the except clauses were reversed (with except B first), it would have printed B, B — the first matching except clause is triggered, like in the following example:

for cls in [B, C]: try: raise cls() except B: # Matches B and C both. print("B") except C: # Not reached (the previous clause ate B and C) print("C")

Linked PRs

• gh-136228: Clarify example in exception handling section #136257