On Sat, Jan 30, 2016 at 4:08 AM, Martin Panter <vadmium+py@gmail.com> wrote:
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 before3.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.
The goal is to avoid unnecessary breakage. In this case the code will need to be fixed regardless, so the best we can do is to add a -3 warning to 2.7 .
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.
Yes, even if you could argue that even removing things that were already deprecated will make porting more difficult. Perhaps I should rephrase the section focusing the working on making the porting easier.
Deprecation Progression
- in release
3.XaDeprecationWarningis added- in release
3.X+Nthe API is removed
Ncan 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.
An estimation is fine. I would use 4.0 for indefinite deprecations. If we use the rst directives to collect all the deprecated APIs in a single page, we can go through them once 2.7 is dead.
Deprecation Process
- attach to the issue a patch to deprecate the API that:
- adds a
DeprecationWarningto 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?
I did it once and it ended up breaking tests in the middle of the next release. For the sake of the release managers, I don't think it should be done, especially if we come up with a better way to track deprecations.
- 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()
For tests there should be a convenience function in test.support.
- 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-removeddirective.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).