How to extend warnings.deprecated?

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?

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

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.

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(...): ...

@JelleZijlstra

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

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

let’s change that then

@JelleZijlstra

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

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.

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

Navigation Menu

Repository navigation

How to extend `warnings.deprecated`? #2256

Metadata

Assignees

Labels

Projects

Milestone

Relationships

Development

How to extend warnings.deprecated? #2256

Description

Activity

flying-sheep commented on Apr 15, 2026

srittau commented on Apr 15, 2026

flying-sheep commented on Apr 15, 2026

flying-sheep commented on May 19, 2026

JelleZijlstra commented on May 19, 2026

flying-sheep commented on May 19, 2026

flying-sheep commented on Jun 17, 2026

JelleZijlstra commented on Jun 18, 2026

flying-sheep commented on Jun 18, 2026

Metadata

Metadata

Assignees

Labels

Projects

Milestone

Relationships

Development

Issue actions

How to extend `warnings.deprecated`? #2256