type hint of function exceptions

[dfroger]

edit: I've rather asked on https://mail.python.org/archives/list/typing-sig@python.org/, it's waiting moderation.

Hi everyone,

I've read https://stackoverflow.com/questions/44282268/python-type-hinting-with-exceptions and especially the https://jonathan-scholbach.github.io/2023/02/06/what-does-it-mean-to-be-exceptional/ blog post, but I want to keep coding with exceptions rather than returning Ok | Err.

Here is a simple pattern I'm thinking to use, to let a function indicate the Exceptions it may raised, which can be used:

• by the developper as documentation,
• by the static type checker for exhaustiveness

from typing import NoReturn, cast, TypeAlias


class SomeError(Exception):
    ...


class AnotherError(Exception):
    ...


class StillAnotherError(Exception):
    ...


FooError: TypeAlias = ValueError | SomeError | AnotherError


def assert_never(value: NoReturn) -> NoReturn:
    # This also works at runtime as well
    assert False, f"This code should never be reached, got: {value}"


def foo(i: int):
    if i == 0:
        raise ValueError("Must not be zero")
    elif i == 1:
        raise SomeError("Must not be one")
    elif i == 2:
        raise AnotherError("Must not be two")
    print("that's ok")


try:
    foo(0)
except Exception as e:
    e = cast(FooError, e)
    if isinstance(e, ValueError):
        print("value error")
    elif isinstance(e, SomeError):
        print("some error")
    else:
        assert_never(e)
        raise

It's far from being perfect, but it's simple and not too much intrusive nor obscure.

In the above example, mypy can tell me which exception I forgot to manage:

foo.py:43: error: Argument 1 to "assert_never" has incompatible type "AnotherError"; expected "NoReturn"  [arg-type]
Found 1 error in 1 file (checked 1 source file)

What do you thing of this?

Thanks!