How to extend `warnings.deprecated`?

[flying-sheep]

We need more metadata for our deprecation decorator, but the spec doesn’t say how deprecated marks an API. So the only way to mark something as deprecated it is by creating an API with the same exact signature and replace it with warnings.deprecated at the type level:

if TYPE_CHECKING:
 from warnings import deprecated
else:
 def deprecated[F](msg: str) -> Callable[[F], F]: ...

We need to define deprecated(msg: str, version: packaging.Version) and have it work with the type system. How?

[flying-sheep]

Another issue: there seems to be no reason why it takes LiteralString only, so that should be changed to str in the stubs.

[srittau]

Another issue: there seems to be no reason why it takes LiteralString only, so that should be changed to str in the stubs.

LiteralString is used intentionally, see python/typeshed#11699.

[flying-sheep]

This goes back to the original issue then:

How do I keep the property of seeing the deprecation (strike-through function call) and its message, but can also add e.g. a mandatory version parameter and extra behavior to the decorator?

The following hack is very unpythonic and easy to get wrong:

@deprecated("some message")
@deprecated_at("3.5")
def f(...): ...

[flying-sheep]

So deprecated is a class: python/cpython#150076

I want to add keyword arguments. So how about we say this?

in subclasses, msg should stay a position-only argument at position 0 so type checkers can display it

cc @JelleZijlstra

[JelleZijlstra]

Subclasses of deprecated have no special meaning in the type system.

[flying-sheep]

let’s change that then

[flying-sheep]

@JelleZijlstra what’s necessary to change that? A whole PEP?

[JelleZijlstra]

At a minimum we should have a discussion on discuss.python.org. A small extension like the ones you suggested above shouldn't need a PEP.

[flying-sheep]

Done: https://discuss.python.org/t/proposal-allow-extending-warnings-deprecated/107794