Target python version based deprecation warnings for stdlib types

[FasterSpeeding]

I've not looked too deeply into this so I'm not sure if this might be considered outside the scope of pyright or come down to an issue of there not being any consistent listing for deprecated types per python version to use but recently I've been trying to switch from the generic alias present in the typing module to their collections.abc equivalents as part of a move to python 3.9 and I'm kind of struggling to avoid accidentally using the deprecated typing equivalents by instinct. I thought that it'd be a helpful feature for pyright to support warnings when deprecated types are detected like this to help developers avoid using deprecated types and also help improve awareness of when you're using deprecated types (e.g. bumped the minimum required target for a project) in type hints where they won't necessarily give off deprecation warnings at runtime.

I know in a best case scenario developers would just be aware of what's deprecated from reading changelogs but we're only humans and it'd be really helpful to dumb mistakes and missing stuff.

[erictraut]

I think this is a reasonable piece of functionality to include in pyright. PEP 585 is clear that these symbols are deprecated as of Python 3.9. Please feel free to file an enhancement request.

[JelleZijlstra]

More ambitiously, perhaps we could come up with a mechanism to mark deprecations in stub files, so type checkers can warn about them without special casing. That would require a new PEP though.

[erictraut]

Yeah, I like that idea. It would be great if this could support more than just stdlib. Here's a recent request to provide this for other libraries.

I presume that a decorator would work best here, since it's typically functions and classes that we want to deprecate (as opposed to variables, type aliases, or attributes). Perhaps the decorator could accept a bool value to accommodate static expressions involving the python version.

from typing import deprecated

# Unconditionally deprecated
@deprecated
def foo1(): ...

# Conditionally deprecated based on target Python version
@deprecated(sys.version_info >= (3, 9))
def foo2(): ...

Does it make sense for this decorator to come from the typing module, or is there another module that's more appropriate?

What runtime effect (if any) would this decorator have on a function or a class?

[JelleZijlstra]

There was recent discussion on python-ideas of an @deprecated decorator too: https://groups.google.com/g/python-ideas/c/HAg5Q5wcoLw . The idea is much more compelling to me if the decorator can also be used by static type checkers though.

A few other points to consider:

• The @deprecated(sys.version_info < (3, 9)) isn't strictly necessary, because we could instead write something like:

if sys.version_info < (3, 9):
     def foo2(): ...
else:
     @deprecated
     def foo2(): ...

Your syntax is more concise, though.

• A decorator would only allow deprecating functions and classes. That probably covers most use cases, but I could also imagine wanting to deprecate constants, instance attributes, or specific parameters to a function. A possible syntax could be def foo(x: int, y: Deprecated[str]).

[jakebailey]

There's also the feature request on Pylance for the strikethrough: microsoft/pylance-release#1783

I've seen a number of deprecation decorators take options that list out the names of the deprecated parameters, as an alternative to introducing a new type.

[hmc-cs-mdrissi]

The python-ideas chat mentioned deprecating specific overloads. I think that covers same case of deprecating a parameter and would weakly prefer. Deprecating instance attributes/constants would require something like Deprecated[X] though.