> 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). _______________________________________________ python-committers mailing list python-committers@python.org https://mail.python.org/mailman/listinfo/python-committers
