iSharkFly-Open
/
python-peps
mirror of https://github.com/python/peps.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

PEP 387: Add Soft Deprecation section (#3182)

This commit is contained in:
Victor Stinner 2023-07-03 21:25:05 +02:00 committed by GitHub
parent 51ba3ec235
commit 57b1d94a4f
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
2 changed files with 28 additions and 3 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
.github/CODEOWNERS vendored
View File

@ -241,7 +241,7 @@ pep-0378.txt @rhettinger
# pep-0384.txt
pep-0385.txt @pitrou @birkenfeld
# pep-0386.txt
pep-0387.txt @benjaminp
pep-0387.txt @benjaminp @vstinner
# pep-0389.txt
# pep-0390.txt
pep-0391.txt @vsajip

29
pep-0387.txt
View File

@ -4,12 +4,13 @@ Version: $Revision$
Last-Modified: $Date$
Author: Benjamin Peterson <benjamin@python.org>
PEP-Delegate: Brett Cannon <brett@python.org>
Discussions-To: https://discuss.python.org/t/pep-387-backwards-compatibilty-policy/4421
Status: Active
Type: Process
Content-Type: text/x-rst
Created: 18-Jun-2009
Post-History: 19-Jun-2009, 12-Jun-2020
Post-History: `19-Jun-2009 <https://mail.python.org/archives/list/python-dev@python.org/thread/YAZQHFUCYEYIX5MIG6LFJLCVQ5ORVUM6/>`__,
`12-Jun-2020 <https://discuss.python.org/t/pep-387-backwards-compatibilty-policy/4421>`__,
`16-Jun-2023 <https://discuss.python.org/t/formalize-the-concept-of-soft-deprecation-dont-schedule-removal-in-pep-387-backwards-compatibility-policy/27957>`__
Abstract
@ -114,6 +115,30 @@ Basic policy for backwards compatibility
platforms).
Soft Deprecation
================
A soft deprecation can be used when using an API which should no longer
be used to write new code, but it remains safe to continue using it in
existing code. The API remains documented and tested, but will not be
developed further (no enhancement).
The main difference between a "soft" and a (regular) "hard" deprecation
is that the soft deprecation does not imply scheduling the removal of
the deprecated API.
Another difference is that a soft deprecation does not issue a warning:
it's only mentioned in the documentation, whereas usually a "hard"
deprecation issues a ``DeprecationWarning`` warning at runtime. The
documentation of a soft deprecation should explain why the API should be
avoided, and if possible propose a replacement.
If the decision is made to deprecate (in the regular sense) a feature
that is currently soft deprecated, the deprecation must follow the
`Backwards Compatibility Rules`_ (i.e., there is no exception because
the feature is already soft deprecated).
Making Incompatible Changes
===========================