[python-committers] Deprecation Policy PEP

Martin Panter vadmium+py at gmail.com
Fri Jan 29 21:08:24 EST 2016


> What and when to deprecate
> ==========================
>
> * The number of releases before an API is removed is decided
>   on a case-by-case basis depending on widely used the API is

depending on [how] widely used

> * In general it's better to be conservative, and if the API is
>   deprecated in ``3.X``, it shouldn't be removed before ``3.X+2``.
>   This should also take into account which Python versions are
>   currently .

which Python versions are [current].

More explicitly, I would say as a guideline, if the proposed
alternative is unavailable in 3.Y, consider waiting until 3.Y becomes
unsupported or unused before removing (or even fully deprecating) an
API.

> Porting from 2.x to 3.x
> -----------------------
>
> In order to make porting code to 3.X easier:
>
> * nothing that is available and not deprecated in 2.7 should be
>   removed from Python 3 as long as 2.7 is officially supported;

What about an API not documented in Python 3, like
http.client.HTTPMessage.getallmatchingheaders()
<https://bugs.python.org/issue5053>? In this case I think the method
was rendered useless in 3.0 and it is not worth fixing.

Also I presume you mean not originally deprecated in 2.7.0. In other
words adding a “python2 -3” warning in the next 2.7 bug fix doesn’t
give me a license to remove an API from 3.6.

> Deprecation Progression
> =======================
>
> 1. in release ``3.X`` a ``DeprecationWarning`` is added
> 2. in release ``3.X+N`` the API is removed
>
> ``N`` can be ``>=1``, should be decided beforehand, and should be
> documented explicitly.

How do we decide on the value of N for something that has to wait
until 2.7 is dead? Just estimate based on anticipated future release
dates? E.g. inspect.getargspec(). In some cases I think indefinite
deprecation is better.

> Deprecation Process
> ===================

> 2. attach to the issue a patch to deprecate the API that:
>
>   * adds a ``DeprecationWarning`` to the code
>   * adds the deprecation to the documentation
>   * adds a test to verify that the warning is raised

Often people propose a test that will detect when the version changes
to >= X+N and complains if the API has not been removed. Should this
be encouraged or discouraged?

>   * possibly updates code/examples that uses the deprecated API

Also adjust any tests to suppress the new warning. Code to do this
typically looks like

with warnings.catch_warnings():
    warnings.simplefilter("ignore", DeprecationWarning)
    deprecated.api()

> 3. after review, apply the patch to the current in-development
>    branch and close the issue.

Also apply similar changes to 2.7 if applicable?

> Documenting the deprecations
> ============================
>
> * All deprecations should be documented in the docs, using the
>   ``deprecated-removed`` directive.

If an undocumented API is being deprecated, you may not have to touch
the main documentation (but still consider a notice in What’s New).


More information about the python-committers mailing list