cannot accurately check the type of a decorated function's parameter

[davidism]

In Flask, @app.errorhandler() is used to create a decorator that will decorate a user function that takes one argument, a type of exception. We've tried the following to type annotate this decorator, but have been unsuccessful in getting useful type checking out.

from __future__ import annotations
import typing as t

# ErrorBound = t.TypeVar("ErrorBound", bound=t.Type[Exception])
# HandlerCallable = t.Callable[[ErrorBound], None]
HandlerCallable = t.Callable[[Exception], None]
HandlerDecorator = t.TypeVar("HandlerDecorator", bound=HandlerCallable)

def handler(code: t.Type[Exception]) -> t.Callable[[HandlerDecorator], HandlerDecorator]:
    def wrapper(f: HandlerDecorator) -> HandlerDecorator:
        return f

    return wrapper

# This is the basic use case. It should pass.
@handler(ValueError)
def one(e: ValueError) -> None:
    pass

# This should pass. It's not required to match the decorator
# argument to the decorated parameter, although that would b a nice bonus.
@handler(ValueError)
def two(e: Exception) -> None:
    pass

# This should also pass. It is possible to stack the decorator,
# and the user should be able to annotate that their function
# takes a union of Exceptions.
@handler(ValueError)
@handler(TypeError)
def three(e: ValueError | TypeError) -> None:
    pass

# This should fail, str is not a type of exception.
@handler(ValueError)
@handler(TypeError)
def four(e: str) -> None:
    pass

With the uncommented types at the top, only the two function passes. Mypy requires that the argument type is exactly Exception.

If the TypeVar and alternate HandlerCallable are uncommented, all four functions pass, but the four function should fail. I've come to understand that this is not the correct way to use TypeVar because it's treated as Any. However, I can't think of another way to express "the argument of this function can be any exception type".

[erictraut]

If you want to support stacked decorators, you'll need to explicitly specialize the first of the decorators. There's currently no way to explicitly specialize a generic function in the Python type system, but you can specialize a generic class. So my recommendation is to switch to a generic class for your decorator.

from __future__ import annotations
import typing as t

ErrorBound = t.TypeVar("ErrorBound", bound=Exception)
HandlerCallable = t.Callable[[ErrorBound], None]

class handler(t.Generic[ErrorBound]):
    def __init__(self, code: t.Type[ErrorBound]) -> None:
        ...

    def __call__(
        self, wrapped: HandlerCallable[ErrorBound]
    ) -> HandlerCallable[ErrorBound]:
        return wrapped

@handler(ValueError)
def one(e: ValueError) -> None:
    pass

@handler(ValueError)
def two(e: Exception) -> None:
    pass

@handler(ValueError)
@handler[TypeError | ValueError](TypeError)
def three(e: ValueError | TypeError) -> None:
    pass

@handler(ValueError)
@handler[TypeError | ValueError](TypeError)
def four(e: str) -> None:
    pass

[erictraut]

I think mypy is correct in generating errors in your original code sample, so I don't think this should be considered a mypy bug.

[davidism]

I agree the errors are correct, this issue was more about how to allow "any exception" as the type of the decorated function's parameter.

Thanks for the example, that makes sense, although I was hoping for a more straightforward solution. handler is actually a method on the Flask object, I don't think having nested callable classes is particularly standard, and it messes with the Sphinx documentation output.

It's probably unlikely that users will annotate their own code like @handler[TypeError | ValueError](TypeError), that's just too confusing to teach.

[erictraut]

If you don't need to support stacked decorators, then I there's a simpler solution that is similar to your original sample.

ErrorBound = t.TypeVar("ErrorBound", bound=Exception)
HandlerCallable = t.Callable[[ErrorBound], None]
HandlerDecorator = t.TypeVar("HandlerDecorator", bound=HandlerCallable[t.Any])

def handler(
    code: t.Type[ErrorBound],
) -> t.Callable[[HandlerCallable[ErrorBound]], HandlerCallable[ErrorBound]]:
    def wrapper(f: HandlerDecorator) -> HandlerDecorator:
        return f

    return wrapper

[davidism]

I need to support stacked decorators, and preferably would not want to try to teach users how to use generics, which won't be particularly convenient or useful for the way these callbacks are written.

It seems like there aren't other ideas about this right now. For the use case above, I'm fine with using Any for the argument and not matching the decorator arg to the function arg.