diff --git a/docs/spec/exceptions.rst b/docs/spec/exceptions.rst new file mode 100644 index 000000000..aae3fe2c1 --- /dev/null +++ b/docs/spec/exceptions.rst @@ -0,0 +1,63 @@ +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") diff --git a/docs/spec/index.rst b/docs/spec/index.rst index 3e77898ce..6e5e5c00b 100644 --- a/docs/spec/index.rst +++ b/docs/spec/index.rst @@ -19,6 +19,7 @@ Specification for the Python type system callables constructors overload + exceptions dataclasses typeddict tuples