stubtest and @deprecated

[srittau]

Bug Report

The @warnings.deprecated decorator adds a few dunders to classes it decorates. This causes stubtest to complain about differences between stub and implementation, unless these changes are added manually to the stubs. I think we should special case @deprecated to ignore these differences.

To Reproduce

For example, adding the following test to StubtestUnit:

    @collect_cases
    def test_deprecated(self) -> Iterator[Case]:
        yield Case(
            stub="""
            from warnings import deprecated

            @deprecated("")
            class Foo: ...
            """,
            runtime="""
            from warnings import deprecated

            @deprecated("")
            class Foo:
                pass
            """,
            error=None,
        )

causes the following error when running the tests with Python 3.13:

E           AssertionError: error: test_module.Foo.__deprecated__ is not present in stub
E             Stub: in file test_module.pyi
E             MISSING
E             Runtime:
E             ''
E             
E             error: test_module.Foo.__init_subclass__ is not present in stub
E             Stub: in file test_module.pyi
E             MISSING
E             Runtime: in file /opt/pyenv/versions/3.13.8/lib/python3.13/warnings.py:621
E             def (*args, **kwargs)
E             
E             error: test_module.Foo.__new__ is not present in stub
E             Stub: in file test_module.pyi
E             MISSING
E             Runtime: in file /opt/pyenv/versions/3.13.8/lib/python3.13/warnings.py
E             def (*args, **kwargs)
E             
E             Found 3 errors (checked 1 module)
E             
E           assert {'test_module....Foo.__new__'} == set()
E             
E             Extra items in the left set:
E             'test_module.Foo.__deprecated__'
E             'test_module.Foo.__new__'
E             'test_module.Foo.__init_subclass__'
E             Use -v to get more diff

Interestingly, this is different from what we see in typeshed (python/typeshed#14893):

error: jwcrypto.jwt.JWTMissingKeyID.__init_subclass__ is inconsistent, stub does not have *args parameter "args"
Stub: in file /home/runner/work/typeshed/typeshed/stubs/jwcrypto/jwcrypto/jwt.pyi:139
def (cls: type[builtins.object])
Runtime: in file /opt/hostedtoolcache/Python/3.13.8/x64/lib/python3.13/warnings.py:621
def (*args, **kwargs)

Your Environment

• Mypy version used: master for the test above, 1.18.2 in typeshed CI
• Mypy command-line flags:
• Mypy configuration options from mypy.ini (and other config files):
• Python version used: 3.13

[tyralla]

I think we should special case @deprecated to ignore these differences.

Or, alternatively, let Mypy add the methods internally?

[srittau]

This would probably be even better as it means that the methods would be recognized during type checking.

[sterliakov]

We can only add __deprecated__ - __init_subclass__ and __new__ only cause trouble because they aren't explicitly declared in stubs and yet do not resolve to object.{__init_subclass__,__new__} after being wrapped by deprecated. Those two can only be ignored by stubtest, if I understand the flow correctly.

I'm also not sure that we should generate __deprecated__: I consider it an implementation detail. Removing @deprecated should not be semver-breaking (after all, you restore some deprecated functionality, not remove it), and it can only be non-breaking if you treat __deprecated__ as a private implementation detail, not to be put in stubs or added by the type checker. If you declare __deprecated__ as part of a public interface, you cannot un-deprecate anything without letting it rot for N versions, and I hardly see the whole process - do you add a @deprecated metaclass property __deprecated__ to print a deprecation warning when it's accessed? Sounds painful...

[JelleZijlstra]

Yes, I'm not convinced we should be generating those methods in mypy. The __init_subclass__ and __new__ are meant to preserve the same interface, they just wrap the existing one and add deprecation notices. So type checkers shouldn't change their behavior based on the presence of these generated methods.