Description

flying-sheep

opened on Apr 9, 2026

Issue body actions

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?

Activity

1. flying-sheep

   added

   topic: documentationDocumentation-related issues and PRsDocumentation-related issues and PRs

   on Apr 9, 2026
2. flying-sheep commented on Apr 15, 2026

   

   flying-sheep

   on Apr 15, 2026

   Author

   More actions

   Another issue: there seems to be no reason why it takes LiteralString only, so that should be changed to str in the stubs.
3. srittau commented on Apr 15, 2026

   

   srittau

   on Apr 15, 2026

   Collaborator

   More actions

   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.
4. flying-sheep commented on Apr 15, 2026

   

   flying-sheep

   on Apr 15, 2026

   Author

   More actions

   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(...): ...
5. flying-sheep commented on May 19, 2026

   

   flying-sheep

   on May 19, 2026

   Author

   More actions

   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
6. JelleZijlstra commented on May 19, 2026

   

   JelleZijlstra

   on May 19, 2026

   Member

   More actions

   Subclasses of deprecated have no special meaning in the type system.
7. flying-sheep commented on May 19, 2026

   

   flying-sheep

   on May 19, 2026

   Author

   More actions

   let’s change that then
8. flying-sheep commented on Jun 17, 2026

   

   flying-sheep

   on Jun 17, 2026

   Author

   More actions

   @JelleZijlstra what’s necessary to change that? A whole PEP?
9. JelleZijlstra commented on Jun 18, 2026

   

   JelleZijlstra

   on Jun 18, 2026

   Member

   More actions

   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.
10. flying-sheep commented on Jun 18, 2026

    

    flying-sheep

    on Jun 18, 2026

    Author

    More actions

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

Issue actions