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

Ezio Melotti ezio.melotti at gmail.com
Sat Jan 25 14:29:53 CET 2014

Hi, a couple of years ago I suggested to define and document our deprecation policy in this thread: https://mail.python.org/pipermail/python-dev/2011-October/114199.html I didn't receive many replies and eventually nothing was done. Lately the same issue came up on #python-dev and Larry and Nick suggested me to bring this up again. Nick also suggested to document our deprecation policy in PEP 5 (Guidelines for Language Evolution: http://www.python.org/dev/peps/pep-0005/ ).

I'm including below the full text of the original email.

Best Regards, Ezio Melotti

Hi, our current deprecation policy is not so well defined (see e.g. 0), and it seems to me that it's something like:

  1. deprecate something and add a DeprecationWarning;
  2. forget about it after a while;
  3. wait a few versions until someone notices it;
  4. actually remove it;

I suggest to follow the following process:

  1. deprecate something and add a DeprecationWarning;
  2. decide how long the deprecation should last;
  3. use the deprecated-remove[1] directive to document it;
  4. add a test that fails after the update so that we remember to remove it[2];

Other related issues:

PendingDeprecationWarnings:

Deprecation Progression: Before, we more or less used to deprecated in release X and remove in X+1, or add a PDW in X, DW in X+1, and remove it in X+2. I suggest we drop this scheme and just use DW until X+N, where N is

=1 and depends on what is being removed. We can decide to leave the DW for 2-3 versions before removing something widely used, or just deprecate in X and remove in X+1 for things that are less used.

Porting from 2.x to 3.x: Some people will update directly from 2.7 to 3.2 or even later versions (3.3, 3.4, ...), without going through earlier 3.x versions. If something is deprecated on 3.2 but not in 2.7 and then is removed in 3.3, people updating from 2.7 to 3.3 won't see any warning, and this will make the porting even more difficult. I suggest that:

Documenting the deprecations: In order to advertise the deprecations, they should be documented:

Testing the deprecations: Tests that fail when a new release is made and the version number is bumped should be added to make sure we don't forget to remove it. The test should have a related issue with a patch to remove the deprecated function and the test. Setting the priority of the issue to release blocker or deferred blocker can be done in addition/instead, but that works well only when N == 1 (the priority could be updated for every release though). The tests could be marked with an expected failure to give some time after the release to remove them. All the deprecation-related tests might be added to the same file, or left in the test file of their module.

Where to add this: Once we agree about the process we should write it down somewhere. Possible candidates are:

Best Regards, Ezio Melotti

[1]: deprecated-removed doesn't seem to be documented in the documenting doc, but it was added here: http://hg.python.org/cpython/rev/03296316a892 [2]: see e.g. http://hg.python.org/cpython/file/default/Lib/unittest/test/test_case.py#l1187 [3]: we could also introduce a MetaDeprecationWarning and make PendingDeprecationWarning inherit from it so that it can be used to pending-deprecate itself. Once PendingDeprecationWarning is gone, the MetaDeprecationWarning will become useless and can then be used to meta-deprecate itself. [4]: https://docs.djangoproject.com/en/dev/internals/deprecation/ [5]: http://www.python.org/dev/peps/pep-0387/

More information about the Python-Dev mailing list