From 694dee4f9884ce7d131932ccefd598cbeee714c1 Mon Sep 17 00:00:00 2001 From: Sebastian Rittau Date: Wed, 22 Jul 2026 14:30:08 +0200 Subject: [PATCH 1/3] Add a policy for using `@deprecated` Closes: #12092 --- CONTRIBUTING.md | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d7fba6c402ad..c6dd2cdb68a2 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -320,6 +320,26 @@ documentation. Whenever you find them disagreeing, model the type information after the actual implementation and file an issue on the project's tracker to fix their documentation. +### Deprecations (using the `@deprecated` decorator) + +Generally depractions using the `@deprecated` decorator are added more +liberally in typeshed than runtime deprecation warnings. Here are some +guidelines that can be deviated from in special cases. + +Use `@deprecated` if and only if + +- a feature is deprecated at runtime (either using `@deprecated` or with a + runtime warning); or +- a feature is documented to be deprecated (either in external documention, + in docstrings, or comments). + +For standard library items that are not deprecated in all Python versions +currently supported by typeshed (usually using the wording "Deprecated since" in the +documentation) use `@deprecated` for + +- all versions starting with the "Deprecated since" version plus +- all versions for which an alternative is available. + ### Docstrings Typeshed stubs should not include duplicated docstrings from the source code. From ad714c0f7b8dcdf2c980c34d8625bc35bfe209b9 Mon Sep 17 00:00:00 2001 From: Sebastian Rittau Date: Wed, 22 Jul 2026 14:33:25 +0200 Subject: [PATCH 2/3] Wording improvements --- CONTRIBUTING.md | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c6dd2cdb68a2..22ac1227a045 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -330,14 +330,13 @@ Use `@deprecated` if and only if - a feature is deprecated at runtime (either using `@deprecated` or with a runtime warning); or -- a feature is documented to be deprecated (either in external documention, - in docstrings, or comments). +- a feature is documented to be deprecated (e.g. in API documention, + docstrings, or comments). -For standard library items that are not deprecated in all Python versions -currently supported by typeshed (usually using the wording "Deprecated since" in the -documentation) use `@deprecated` for +For standard library features that are not deprecated in all Python versions +currently supported by typeshed use `@deprecated` for -- all versions starting with the "Deprecated since" version plus +- all versions starting with the "Deprecated since" version, plus - all versions for which an alternative is available. ### Docstrings From 8c61499b0ecd6bcbc1c87e6c71d7e4df967a9f6c Mon Sep 17 00:00:00 2001 From: Sebastian Rittau Date: Wed, 22 Jul 2026 16:07:10 +0200 Subject: [PATCH 3/3] Typo --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 22ac1227a045..232b830135ab 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -322,7 +322,7 @@ project's tracker to fix their documentation. ### Deprecations (using the `@deprecated` decorator) -Generally depractions using the `@deprecated` decorator are added more +Generally deprecactions using the `@deprecated` decorator are added more liberally in typeshed than runtime deprecation warnings. Here are some guidelines that can be deviated from in special cases.