TypingError: type checker will emit error with a message specified in typing stubs

[Akuli]

Some ways to call certain functions are just wrong, and are known to be a bug. For example, passing type=bool to argparse's add_argument method doesn't work. To make type checkers warn about this, typeshed can currently do something like this:

@overload
def add_argument(self, unrelated args, type: Type[bool], more unrelated args) -> NoReturn: ...
@overload
def add_argument(self, unrelated args) -> None: ...

When add_argument is used wrongly, you would then get errors:

import argparse
parser = argparse.ArgumentParser(description="My parser")
parser.add_argument("--my_bool", type=bool)
print(parser.parse_args())  # Error: statement is unreachable

This approach has a couple problems:

• The type checker's error message doesn't say "you passed in type=bool and it's wrong". It says "statement is unreachable".
• The type checker's error message appears on a different line than where the buggy code is.
• Unreachable code warnings are disabled by default in mypy, even with --strict.

The solution I would like: if you declare the return type as TypingError["foo bar"], the type checker will display an error message foo bar. This is similar to how #error works in the C preprocessor.

Stub:

@overload
def add_argument(
    self, unrelated args, type: Type[bool], more unrelated args
) -> TypingError["type=bool doesn't work, see https://stackoverflow.com/q/15008758"]: ...
@overload
def add_argument(self, unrelated args) -> None: ...

Python file:

import argparse
parser = argparse.ArgumentParser(description="My parser")
parser.add_argument("--my_bool", type=bool)  # Error: type=bool doesn't work, see https://stackoverflow.com/q/15008758
print(parser.parse_args())

[erictraut]

How common is this use case? Have you seen more than just this one case?

[AlexWaygood]

Here are two other places in typeshed where we have NoReturn overloads that kinda-sorta-half work, where this feature would be useful:

• builtins.pow (first overload): https://github.com/python/typeshed/blob/fabd8428572dcc20b7ae7919e16d9b4c87cf3da2/stdlib/builtins.pyi#L1330
• datetime.date.__sub__ (second overload): https://github.com/python/typeshed/blob/fabd8428572dcc20b7ae7919e16d9b4c87cf3da2/stdlib/datetime.pyi#L72

I'm sure there are yet more examples, but these two are just off the top of my head.

[Akuli]

A couple more examples where unreachable code warnings don't do a good job of explaining what's wrong:

• wave.Wave_read.getmark and a few other wave methods unconditionally raise an error.
• mmap objects have a __delitem__ that always raises TypeError: mmap doesn't support item deletion.

[erictraut]

Thanks for the additional examples. That's really helpful.

If we were to add support for this, I'd prefer not to model it as a return type annotation for a couple of reasons.

First, I want to avoid adding more type annotations that accept string literals as type arguments but do not expect the string to be treated as a quoted type expression. Both Literal and Annotated already break this rule, and type checkers like pyright need to include a bunch of complex and fragile special-case handling for these cases. Let's not add more of these unless there's a really compelling reason to do so.

Second, the return type seems like it should be independent of any special error message that is emitted. In some cases, NoReturn is the correct return type because that overload will always generate an exception. In that case, code after the call should be marked unreachable. Other times, a different return type may be appropriate, but it's still desirable to emit an error message.

I think a decorator is a better option for this particular use case. There have been some good discussions around a standardized decorator for @deprecated. This feels like a very similar use case, and I think we could address both use cases with the same solution/pattern.

Here's a rough idea of what that might look like.

from typing import overload, deprecated, runtime_error

# Use of "runtime_error" decorator, always emits error diagnostic
@overload
@runtime_error("Calling pow() with a mod of 0 will result in a runtime exception")
def pow(base: int, exp: int, mod: Literal[0]) -> NoReturn: ...
@overload
def pow(base: int, exp: int, mod: int) -> int: ...
@overload
def pow(base: int, exp: _PositiveInteger, mod: None = ...) -> int: ...

# Use of "deprecated" decorator; this can be presented differently if
# desired (e.g. crossed-out text at the call site)
@overload
def foo(x: int) -> int: ...
@overload
@deprecated("Option value of 'old' is deprecated")
def foo(x: int, *, option: Literal["old"]) -> int: ...
@overload
def foo(x: int, *, option: str) -> int: ...

Thoughts?

[Akuli]

I like the idea of using a decorator, and also adding a similar @deprecated decorator while we're at it. We could combine the two into just a single decorator, but separating them means that users can disable deprecation warnings without also having to suppress errors for type=bool and the like. IDEs and langservers can also mark the function call as deprecated instead of a generic "warning" or "error".

I don't think @runtime_error is a good name for this. For example, passing type=bool to argparse will not actually error at runtime; it will silently eat up the next argument passed on command line and always return True to the rest of your code. If we don't want to go with @typing_error, shortening it to just @error wouldn't be great either, because it's too likely to conflict with a symbol defined in a stub file. How about @type_checker_error?

[AlexWaygood]

I also like the idea of a decorator. How about @always_errors?

[graingert]

asyncio's loop kwarg removal in 3.10 would apply here too