Deprecate typing.no_type_check_decorator

[AlexWaygood]

Feature or enhancement

We should deprecate typing.no_type_check_decorator, with a view to removing it in Python 3.15.

Pitch

The typing documentation describes typing.no_type_check_decorator like this:

Decorator to give another decorator the no_type_check() effect.

This wraps the decorator with something that wraps the decorated function in no_type_check().

In 2023, this is frankly misleading for users of the typing module. Unlike its twin @no_type_check, no major type checker has yet added support for no_type_check_decorator, despite the fact that it was added to the typing module in Python 3.5. If it's been 8 years and it still hasn't had support added by any major type checker, it's unlikely to ever be usable or useful. Meanwhile, the decorator is fairly obscure, and you can achieve the same effect using other tools such as @typing.no_type_check and typing.Annotated. There have been a few feature requests to type checkers over the years asking them to add support, but none of them have a significant number of upvotes.

We should simply deprecate @no_type_check_decorator, with a view to removing it in Python 3.15. (Note that I do not propose deprecating @no_type_check, which is supported by mypy and reasonably popular among mypy users.)

Previous discussion

• @typing.no_type_check_decorator is nonfunctional mypy#6583
• no_type_check_decorator doesn't work google/pytype#1452
• typing.no_type_check is not understood microsoft/pyright#1448 (this issue is about no_type_check rather than no_type_check_decorator, but it shows that pyright is unlikely to ever support either decorator, unlike mypy which supports the former but not the latter)

Linked PRs

• gh-106309: Deprecate typing.no_type_check_decorator #106312

[AlexWaygood]

@agronholm, I see that typeguard is one of the very few libraries that makes use of this decorator: https://github.com/agronholm/typeguard/blob/f377be389765ed0db104b41d78fce3c45e72e149/tests/dummymodule.py#L46-L48.

Does typeguard have special handling for @no_type_check_decorator? Would you oppose us removing it? Do you know if it's used by users of typeguard?

Typeguard's a fairly high-profile runtime type-checking library, so this gives me pause.

[AlexWaygood]

Oh, I see it says here in the docs for typeguard:

Warning

The @no_type_check_decorator decorator is not currently recognized by Typeguard.

I suppose that answers my question :)

[agronholm]

Yep, as of right now, typeguard doesn't have the facilities to support it.

[jgarvin]

I just learned of this because I'm subscribed to tickets on mypy and pytype for this.

I think this is worthwhile functionality and the only reason that it's not being used is because it's not implemented in mypy which leads what the other checkers tend to do -- a chicken and egg problem.

Without this feature, there is no ergonomic way to use type annotations for data other than types, in a code base that is statically typed. Typically the way that you would use this data is with a class decorator, and without this feature a class decorator can't declare that it has the same power as @no_type_check, so you must manually put @no_type_check on every class where you use annotations for data.

The closest solution is Annotated which is very verbose compared to just putting the data you want in the annotation position, especially if you don't intend to provide real types at all in which case you are writing Annotated(unused, actual_data) instead of just actual_data.

You can try and encode data within types so that static checkers will allow your annotations, but this is severely hindered by how limited the python static type system is. A completely reasonable thing to do would be something like this:

@generate_cpp_binding
class MyClass:
    x: pick_based_on_version(u32, u64, version)

However all static checkers currently either forbid having a function call in the annotation position, or have indicated their intention to do so. This might seem odd for someone used to Python, but C++/D/Rust all allow compile time execution of code that can be used to influence what types are used for function-arguments/members/etc.

In the absence of this feature the easier thing for users to do if they want to use the annotation syntax for their own data is to just not use static checking at all. CPython has no problem with letting you put arbitrary expressions in annotation position and inspecting the results later.

[JelleZijlstra]

@jgarvin are you sure you are talking about no_type_check_decorator and not @no_type_check? Only the former is being deprecated.

[AlexWaygood]

@jgarvin I think it's really unlikely any type checker is going to add support for this feature any time soon, unfortunately. The mypy issue requesting that mypy add support has been open for four years, and has 0 upvotes -- and mypy doesn't even support adding @no_type_check on classes yet (python/mypy#607). Speaking as a mypy triager, I think adding support for @no_type_check_decorator would be very far from the top of the agenda of the mypy core team, even if we reversed the deprecation.

As a practical matter, I honestly think it's time to pull the plug and say that this feature has failed, at this point. I'm sorry that this isn't the result that you want.

I would advise you to manually add @no_type_check to all classes you're decorating with generate_cpp_binding:

@generate_cpp_binding
@no_type_check
class MyClass:
    x: pick_based_on_version(u32, u64, version)

Or perhaps do something like this:

if TYPE_CHECKING:
    from typing import no_type_check as generate_cpp_binding
else:
    from my_library import generate_cpp_binding

@generate_cpp_binding
class MyClass:
    x: pick_based_on_version(u32, u64, version)

But, as previously mentioned, mypy doesn't even support @no_type_check on classes currently.

[AlexWaygood]

the only reason that it's not being used is because it's not implemented in mypy which leads what the other checkers tend to do -- a chicken and egg problem.

For what it's worth, this isn't true, by the way — pyre and pyright frequently implement support for experimental features long before mypy does, and the pyright and pyre teams have brought forward several proposals for substantially enhancing the type system that have been accepted. If any other type checker wanted to add support for this feature before mypy, I don't think they would hold off from doing so.