Clarify `warnings.deprecated` public API

[flying-sheep]

Documentation

The current docs only specify that it sets the __deprecated__ attribute on the deprecated item.

Pydantic relies on its full API: the fact that it’s a class, and that its instances have all passed parameters in attributes: deprecated(**kw).__dict__ == kw basically.

Two questions:

1. Is that safe or might deprecated get e.g. refactored into a function at some point?
2. Can we subclass it and add parameters? Will type checkers understand this and still mark a @our_deprecated_subclass(...) def ... as deprecated? See How to extend warnings.deprecated? typing#2256

maybe related to #138165

Linked PRs

• gh-150076: Fix the documented signature of warnings.deprecated #153879
• [3.15] gh-150076: Fix the documented signature of warnings.deprecated (GH-153879) #154487
• [3.14] gh-150076: Fix the documented signature of warnings.deprecated (GH-153879) #154488
• [3.13] gh-150076: Fix the documented signature of warnings.deprecated (GH-153879) #154489

[Viicos]

For context, this was discussed here during the implementation: #104004 (comment). It would maybe make sense to explicitly document it. For reference, typeshed already documents it as a class.