[Python-Dev] Process to remove a Python feature
On Wed, 2 May 2018 at 02:12 Victor Stinner <vstinner at redhat.com> wrote:
> 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
> 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
> Slow deprecation:
> * 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?
Python 2 is still supported, so I assume so.
> 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
> users unhappy?
I don't see why removing features that already raise a DeprecationWarning
would require bumping the major version number. Personally, I assumed
either Python 3.9 or 3.10 would be the version where we were okay clearing
out the stuff that had been raising DeprecationWarning for years.
> Should we always document in which version a feature will be removed?
We should at least open an issue to track when the removal is scheduled.
But if we know ahead of time then I so no reason not to document it.
> 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.
Right, which is why we should open an issue immediately. I had a "remove
pyvenv" issue open and assigned to myself for years while I waited for
Python 3.8 development to open. Staring at that issue for so long made sure
I didn't forget. ;)
> Maybe we should create a tool to list features scheduled for removal,
> and open a discussion to check each removal?
I don't know if a tool is necessary. We could have a meta issue or text
file somewhere to track what's to be removed in a certain version.
> 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
> party modules).
> 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?
I thought that already was the policy. ;) I think the real question is what
is people's definition of a "good reason". For instance, I'm all for
removing unsupported code so we don't have to maintain it, even if it's
just from code modernization and such (i.e. pruning down the stdlib). But I
also know others disagree with me and are fine just having modules sit
there as long as the issue rate is low enough to not notice. It's just one
of those things we don't have an official policy on (yet?).
> Python-Dev mailing list
> Python-Dev at python.org
-------------- next part --------------
An HTML attachment was scrubbed...