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).