Raising Errors and Custom Exception Classes

New words in this topic, in plain English. Come back here whenever one feels fuzzy.

raise

The statement that creates and signals an exception.

Custom exception

An error class you define yourself, usually a one-line subclass of Exception.

Exception chaining

Linking a new exception to the one that caused it, so both appear in the traceback.

__cause__

The attribute holding the original exception when you write raise X from original.

__context__

The attribute holding the exception that was being handled when a new one was raised.

Re-raise

A bare raise inside an except block, which passes the same exception upward.

add_note

A method (Python 3.11) that attaches extra explanatory text to an exception.

assert

A statement that raises AssertionError if a condition is false. Used for checking your own assumptions.

1. 1

   Add a third child

   In the first example add class PaymentFailed(ShopError): pass, raise it from a new branch in buy, and check that the catch-all except ShopError handler reports it without any other change.

2. 2

   Remove the from

   In the second example change from original to nothing. Run it. Is e.__cause__ filled in now? Print e.__context__ instead and compare. This is the difference between a deliberate cause and an accident.

3. 3

   Try from None

   Change the raise to raise ConfigError("invalid port setting") from None and print both attributes. from None hides the original on purpose, which is useful when the internal error would only confuse the caller.

Errors are the best teachers. Make each change, read the error, guess what went wrong, then reveal the answer.

def check(age):
    if age < 0:
        raise "age is negative"
    return age

check(-1)

class MissingSetting(Exception):
    pass

settings = {}
try:
    value = settings["port"]
except KeyError:
    raise MissingSetting("port is not set")

1. 1

   raise ValueError("age must not be negative") creates an exception object and raises it. Choose a built-in class when it fits: ValueError for a right type with a wrong value, TypeError for the wrong type, KeyError or IndexError for missing items, FileNotFoundError for a missing file. Write a message that says what was wrong and, if possible, what value was received. The message is often all you see in a log (a file where a program writes down what happened).

2. 2

   When none of the built-in names describe your problem, make your own. A custom exception is a class that inherits from Exception (it gets everything Exception has, and is counted as a kind of Exception): class OrderError(Exception): pass. That one line is enough. (class and inheritance are explained fully in Topic 8.1; for now read it as "make a new kind of error called OrderError, which is a kind of Exception".) Callers can now write except OrderError: and handle exactly your problem, without catching unrelated errors.

3. 3

   Build small families. A library usually defines one base class (class ShopError(Exception): pass) and specific children (class OutOfStock(ShopError): pass). Callers who want to handle anything from your library catch ShopError; callers who care about one case catch OutOfStock. Name classes after what went wrong, end the name with Error when it is an error, and keep the base inheriting from Exception, never from BaseException.

4. 4

   Exception chaining keeps the story of what happened. Inside an except block you often want to raise a different, more meaningful exception while keeping the original. (Recall from Topic 7.1: except ... as e gives the caught error a name.) raise OrderError("cannot read order") from original stores the original in __cause__. The traceback then prints both errors, joined by the words "The above exception was the direct cause of the following exception".

5. 5

   If you raise a new exception inside an except block without from, Python still links the old one, in __context__. It then says "During handling of the above exception, another exception occurred". Use from None to hide the original on purpose. (Names with double underscores, like __cause__, are attributes that Python itself creates and uses. You only read them.)

6. 6

   A bare raise (with nothing after it) inside an except block re-raises the exception being handled, with its original traceback. Use it when you want to log or clean up and then let the error continue upward. Writing raise e instead works too but adds a confusing extra line to the traceback; prefer the bare form.

7. 7

   Python 3.11 added add_note(): e.add_note("while loading order 17") attaches extra text that is shown under the message in the traceback and kept in e.__notes__. It lets code in the middle add context without replacing the exception.

8. 8

   Finally, assert condition, "message" raises AssertionError when the condition is false. Use it to check your own assumptions (for example, that an internal function was given a sorted list). Never use it to validate user input or files. Python removes assertions entirely when it runs with the -O option (a switch that turns on optimisations), so the check would silently disappear.

• ↔

  Deep hierarchies versus flat ones. Many specific classes let callers be precise, but each one is something to document and keep stable. Start with one base and a few children you actually catch separately.

• ↔

  Translating errors versus letting them through. Wrapping a low-level error in a domain error hides vendor details and gives a better message, but loses nothing only if you chain with from. Without chaining you lose the real cause.

• Done when you can raise a built-in exception with a message that includes the bad value.

• Done when you can define a base exception and two children, and catch the parent and a child.

• Done when you can explain raise ... from, __cause__ and from None.

• Done when you can re-raise with a bare raise and add a note with add_note.

• Done when you can say why assert must not validate user input.