exceptions.rst

Exceptions

Some type checking behaviors, such as type narrowing and reachability analysis, require a type checker to understand code flow. Code flow normally proceeds from one statement to the next, but some statements such as for, while and return can change the code flow. Similarly, try/except/finally statements affect code flow and therefore can affect type evaluation. For example:

x = None
try:
    some_function()
    x = 1
except NotImplementedError:
    pass

# The type of `x` at this point could be None if `some_function` raises
# an exception or `Literal[1]` if it doesn't, so a type checker may
# choose to narrow its type based on this analysis.
reveal_type(x)  # Literal[1] | None

Context Managers

A context manager may optionally "suppress" exceptions by returning True (or some other truthy value) from its __exit__ method. When such a context manager is used, any exceptions that are raised and otherwise uncaught within the with block are caught by the context manager, and control continues immediately after the with block. If a context manager does not suppress exceptions (as is typically the case), any exceptions that are raised and otherwise uncaught within the with block propagate beyond the with block.

Type checkers that employ code flow analysis must be able to distinguish between these two cases. This is done by examining the return type annotation of the __exit__ method of the context manager.

If the return type of the __exit__ method is specifically bool or Literal[True], a type checker should assume that exceptions can be suppressed. For any other return type, a type checker should assume that exceptions are not suppressed. Examples include: Any, Literal[False], None, and bool | None.

This convention was chosen because most context managers do not suppress exceptions, and it is common for their __exit__ method to be annotated as returning bool | None. Context managers that suppress exceptions are relatively rare, so they are considered a special case.

For example, the following context manager suppresses exceptions:

class Suppress:
    def __enter__(self) -> None:
        pass

    def __exit__(self, exc_type, exc_value, traceback) -> bool:
        return True

with Suppress():
    raise ValueError("This exception is suppressed")

# The exception is suppressed, so this line is reachable.
print("Code is reachable")