[Python-Dev] Process to remove a Python feature
vstinner at redhat.com
Wed May 2 05:11:16 EDT 2018
As a follow-up to the "[Python-Dev] (Looking for) A Retrospective on
the Move to Python 3" thread, I will like to clarify how a feature
should be removed from Python.
We have multiple tools:
* Emit a PendingDeprecationWarning warning at runtime for *slow*
deprecation (remove a feature in at least 3 cycles)
* Emit a DeprecationWarning warning at runtime for fast deprecation
(remove a feature in 2 cycles)
* Document that a feature is deprecated in the module documentation
* "What's New in Python X.Y?" documents: especially Deprecated,
Removed and Porting to Python X.Y sections.
* Communicate on python-dev, Twitter, Python Insider blog, etc.
* Collaborate with major Python projects to help them to migrate the alternative
IMHO a feature should not be removed if there is no alternative, or if
the alternative is too new.
The usual process is:
* Document the deprecation and emit DeprecationWarning in version N
* Document the removal and remove the feature in version N+1
* Document the deprecation and emit PendingDeprecationWarning in version N
* Emit a DeprecationWarning in version N+1
* Document the removal and remove the feature in version N+2
The hidden ghost is the old rule:
"keep old APIs around to make porting from Python 2 easier"
Is this rule still applicable?
Does it mean that the Python 3 release following Python 2 end-of-life
(2020) will be our next feared "Python 4"? Are we going to remove all
deprecated features at once, to maximize incompatibilities and make
Should we always document in which version a feature will be removed?
Some features are deprecated since many versions, and the deprecated
features are still there. In most cases, it's because of the Python 2
Sometimes, we forget to remove features which has been scheduled for
removal in a specific version.
Maybe we should create a tool to list features scheduled for removal,
and open a discussion to check each removal?
Ten years ago, I wanted to remove most modules and many functions from
the standard library. Now my experience showed me that *each* removal
is very painful, hurt more projects than expected, and takes longer
than 3 years to be fully effective (no longer used in most common 3rd
The usual issue is to write a single code base working on all Python
versions. For example, the new alternative is only available on recent
Python versions, which requires to have at least two code paths to
support all versions. Sometimes, there are 3 code paths...
For a recent example, see "remove platform.linux_distribution()":
Removing a feature from the C API is more complex, since there is no
portable way to emit a deprecation warning at compilation. There is
Py_DEPRECATED() which seems to only be available on GCC (3.1 and
Maybe we should stop to remove features, except if there is really a
good reason to do that?
More information about the Python-Dev