# Proposal: allow extending \`warnings.deprecated\` **URL:** \ **Category:** Typing\ **Created:** [June 18, 2026, 9:57am UTC](https://discuss.python.org/t/proposal-allow-extending-warnings-deprecated/107794 "2026-06-18T09:57:08Z")\ **Posts on this page:** 3\ **Page:** 1
**Author:** ![flying-sheep](https://sea2.discourse-cdn.com/flex002/user_avatar/discuss.python.org/flying-sheep/32/1254_2.png) [@flying-sheep](https://discuss.python.org/u/flying-sheep)\ **Post date:** [June 18, 2026, 9:57am UTC](https://discuss.python.org/t/proposal-allow-extending-warnings-deprecated/107794/1 "2026-06-18T09:57:08Z")
Many projects have function/class deprecation decorators that add additional metadata other than just a deprecation message. Unfortunately, it’s not really possible to get both that metadata and also `warnings.deprecated`’s type checker integration in one decorator invocation: - you can replace `warnings.deprecated` at runtime while making the type system it’s being used, but that requires a decorator that has a compatible signature. - you can add a custom decorator to be applied in addition to it, but that is easy to forget and hard to enforce, whereas configuring a static checker to ban `warnings.deprecated` in favor of a custom decorator is easy. I therefore propose to slightly amend the spec: 1. define `warnings.deprecated` to be a class (it already is in practice, but let’s make that official) 2. explicitly allow sub-classing it: define that type checkers should mark as deprecated not only each item decorated with an instance of `deprecated`, but alternatively also an instance of one of its sub-classes 3. define the first argument of a `deprecated` / sub-class instantiation as to be interpreted as deprecation message if it is a static string / `LiteralString` (type checkers are supposed to display this deprecation message, and this would define what “deprecation” message means in the context of subclasses. Maybe also specify that type checkers / language servers shouldn’t be limited to display _only_ that deprecation message) This way people can make sub-classes of `deprecated`, add more arguments to it, and still have static checks work. I think it would be smart if language servers and type checkers just display the added keyword arguments after the deprecation message, e.g. using this function `@my_deprecated("Old and busted", version=(1, 3), replacement="pkg.bar") def foo(...): ...` would show something like > `pkg.foo` is deprecated: “Old and busted” (version: (1, 3), replacement: pkg.bar) See also: - Original PEP discussion: [PEP 702: Marking deprecations using the type system](https://discuss.python.org/t/pep-702-marking-deprecations-using-the-type-system/23036) - People with the same use case: [Wrapping `warnings.deprecated`?](https://discuss.python.org/t/wrapping-warnings-deprecated/82940) - Partially related: [More deprecation decorators](https://discuss.python.org/t/more-deprecation-decorators/55503) cc @Jelle ---
**Author:** ![Daverball](https://sea2.discourse-cdn.com/flex002/user_avatar/discuss.python.org/daverball/32/15931_2.png) [@Daverball](https://discuss.python.org/u/Daverball)\ **Post date:** [June 18, 2026, 11:13am UTC](https://discuss.python.org/t/proposal-allow-extending-warnings-deprecated/107794/2 "2026-06-18T11:13:46Z")
This seems like a decent first step to make this feature a little bit more flexible, however, I would like to eventually see something even more flexible and generally useful akin to `typing.dataclass_transform` and also not necessarily limited to just deprecation warnings, but being designed for other kinds of statically detectable type errors and warnings as well, including completely custom ones. I outlined some of my thoughts about this in a previous topic about a new `SpecialForm`: ["Wrong" Special Form - #28 by Daverball](https://discuss.python.org/t/wrong-special-form/103832/28) ---
**Author:** ![peterc](https://avatars.discourse-cdn.com/v4/letter/p/f9ae1b/32.png) [@peterc](https://discuss.python.org/u/peterc)\ **Post date:** [June 18, 2026, 11:51am UTC](https://discuss.python.org/t/proposal-allow-extending-warnings-deprecated/107794/3 "2026-06-18T11:51:52Z")
That is an idea. A general enough implementation also grants us the the @experimental decorator that was proposed not long ago