[Python-Dev] Deprecation policy (original) (raw)

Nick Coghlan ncoghlan at gmail.com
Sun Jan 26 04:28:15 CET 2014

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

More information about the Python-Dev mailing list