Hi, in the past I suggested to document our deprecation policy on a PEP. Since the issue came up again on a few issues on the tracker and on #python-dev, I adapted the content of my previous email and wrote a PEP.
Attached you can find the full text, including references to the previous discussions on python-dev and related issues.
Best Regards, Ezio Melotti
PEP: XXX Title: Deprecation Policy Version: $Revision$ Last-Modified: $Date$ Author: Ezio Melotti firstname.lastname@example.org Status: Draft Type: Process Content-Type: text/x-rst Created: 29-Jan-2016 Post-History:
The goal of this PEP is to document when and how to deprecate APIs in the Python language and in the standard library.
Python doesn't currently have a documented policy regarding deprecations. This leads to repeated discussions and inconsistencies in how we handle and document deprecations [#]_ [#]_ [#]_ [#]_ [#]_ [#]_ [#]_.
3.X, it shouldn't be removed before
3.X+2. This should also take into account which Python versions are currently .
Some APIs that are available in Python 2.7 might get deprecated in Python 3, and people that upgrade directly from 2.7 to 3.X might not see any warnings.
In order to make porting code to 3.X easier:
Python offers two kinds of deprecation warnings:
PendingDeprecationWarning\ s were silenced by
default. Starting from Python 2.7,
are also silenced by default [#]_ [#]_.
Since this distinction is no longer true:
PendingDeprecationWarningshould not be used
DeprecationWarningwill be used for all deprecations
PendingDeprecationWarning won't be removed, and 3rd-party
projects are allowed to use it as they see fit.
In the past, the following deprecation progression has been used:
3.X+1it becomes a
3.X+2the API is removed
The warning were occasionally left for more than one release, either intentionally or because no one remembered to update them.
PendingDeprecationWarning should no longer be used, this
can be simplified to:
3.X+Nthe API is removed
N can be
>=1, should be decided beforehand, and should be
These are the steps required to deprecate and remove an API:
propose to deprecate an API on a tracker issue or on python-dev and decide in which version it will be removed.
attach to the issue a patch to deprecate the API that:
DeprecationWarningto the code
after review, apply the patch to the current in-development branch and close the issue.
attach to a separate issue a patch to remove the API that:
When a deprecated API is used, a
be raised. The message should mention that the API is
deprecated, and if possible it should indicate when it will be
removed and what should be used instead.
These messages are intended for developers, and are therefore hidden by default to prevent end-users to see them.
These messages should be enabled by default in places where only developers will see them, such as tests [#]_ and in the interactive interpreter [#]_.
On one hand deprecation warnings should be clearly visible, on the other hand we want to avoid riddling the docs with red boxes [#]_.
In order to find a balance between the two:
This will require some tweak to the
directive, in order to produce different CSS classes for
modules/classes, functions/methods/attributes, and links.
As mentioned above, the error messages and documentation should provide an alternative whenever possible. When the alternative is not straightforward, more complex examples or a new section can added to the documentation to explain how to convert the code.
Another option is to write scripts that can automatically update Python code to use the new alternative. This requires:
This can be done as a GSoC project, and if done correctly, it will provide an easy way for people to upgrade their codebases.
387-- Backwards Compatibility Policy
4-- Deprecation of Standard Modules
.. [#] Deprecation Policy (https://mail.python.org/pipermail/python-dev/2011-October/114199.html)
.. [#] Deprecation Policy (https://mail.python.org/pipermail/python-dev/2014-January/132069.html)
.. [#] deprecated in 3.2/3.3, should be removed in 3.5 or ??? (https://bugs.python.org/issue13248)
.. [#] DeprecationWarning for PEP 479 (generator_stop) (http://bugs.python.org/issue26136)
.. [#] Deprecate threading.Thread.isDaemon etc (http://bugs.python.org/issue24203)
.. [#] Remove the Deprecated API in trace module (http://bugs.python.org/issue26069)
.. [#] Resurrect inspect.getargspec() in 3.6 (http://bugs.python.org/issue25486)
.. [#] What's New in Python 2.7 -- Changes to the Handling of Deprecation Warnings (https://docs.python.org/3/whatsnew/2.7.html)
.. [#] Silence DeprecationWarning by default (https://bugs.python.org/issue7319)
.. [#] Enable warnings by default in unittest (https://bugs.python.org/issue10535)
.. [#] DeprecationWarnings should be visible by default in the interactive REPL (https://bugs.python.org/issue24294)
.. [#] Django has a "Django Deprecation Timeline" page (https://docs.djangoproject.com/en/dev/internals/deprecation/)
.. [#] Consistent documentation practices for security concerns and considerations (https://bugs.python.org/issue13515)
.. [#] Put "deprecated" warnings first (http://bugs.python.org/issue25467)
This document has been placed in the public domain.