[Python-Dev] Deprecation policy

[Nick Coghlan]

On 26 January 2014 12:30, Raymond Hettinger <raymond.hettinger at gmail.com> wrote:
>
> On Jan 25, 2014, at 5:29 AM, Ezio Melotti <ezio.melotti at gmail.com> wrote:
>
> Nick also suggested to document
> our deprecation policy in PEP 5 (Guidelines for Language Evolution:
> http://www.python.org/dev/peps/pep-0005/ ).
>
>
> Here's a few thoughts on deprecations:
>
> * If we care at all about people moving to Python 3, then we'll stop
> doing anything that makes the process more difficult.  For someone
> moving from Python 2.7, it really doesn't matter if something that
> existed in 2.7 got deprecated in 3.1 and removed in 3.3; from their
> point-of-view, it just one more thing that won't work.
>
> * The notion of PendingDeprecationWarnings didn't work out very well.
> Conceptually, it was a nice idea, but in practice no one was benefitting
> from it.  The warnings slowed down working, but not yet deprecated code.
> And no one was actually seeing the pending deprecations.
>
> * When a module becomes obsolete (say optparse vs argparse), there
> isn't really anything wrong with just leaving it in and making the docs
> indicate that something better is available.  AFAICT, there isn't much
> value in actually removing the older tool.
>
> * A good use for deprecations is for features that were flat-out misdesigned
> and prone to error.  For those, there is nothing wrong with deprecating them
> right away.  Once deprecated though, there doesn't need to be a rush to
> actually remove it -- that just makes it harder for people with currently
> working code to upgrade to newer versions of Python.
>
> * When I became a core developer well over a decade ago, I was a little
> deprecation happy (old stuff must go, keep everything nice and clean, etc).
> What I learned though is that deprecations are very hard on users and that
> the purported benefits usually aren't really important.

+1 to what Raymond send - unless something is actively causing us
maintenance hassles or is a genuine bug magnet (cf.
contextlib.nested), we should be very cautious about forcing users to
change their code, especially in the context of raising additional
barriers to migration from Python 2 to Python 3.

Ezio's suggestions make sense as a policy for how to handle the
situation when we *do* decide something needs programmatic
deprecation, but I think there needs to be an explicit caveat that
programmatic deprecation should be a last resort. Wherever possible,
we should also provide a PyPI module that helps address the issue in a
cross-version compatible way (whether through a dedicated upstream
and/or backport module like contextlib2 or by adding features to
existing cross-version compatibility modules like six and future)

As an example that hopefully helps illustrate the two different cases,
the shift to enabling proper SSL/TLS verification by default would
qualify as a worthy use of programmatic deprecation (since the current
insecure-by-default behaviour is a genuine bug magnet that leads to
security flaws), but I'm not yet convinced that we actually gain any
significant benefit from deprecating the legacy import plugin APIs.

While PEP 451 nominally approved deprecating the latter, on the basis
that deprecating them will make importlib easier to maintain, they
received a stay of execution in 3.4 because the extension module
import system currently still needs them, and there are other valid
use cases that PEP 451 doesn't currently cover, At this point, I have
come to believe that retaining the existing
strictly-more-powerful-but-also-harder-to-use-correctly plugin API is
a better way to handle those more complex use cases rather than
inventing something new on top of PEP 451, as the latter approach
would make things *harder* to maintain (due to increased complexity
and needing to manage the deprecation process), and provide a worse
experience for users implementing custom import hooks that need to
support multiple versions (due to the introduction of new
cross-version compatibility issues).

Cheers,
Nick.

-- 
Nick Coghlan   |   ncoghlan at gmail.com   |   Brisbane, Australia