On 29.01.16 19:11, Ezio Melotti wrote:
Deprecation Warnings
Python offers two kinds of deprecation warnings:
PendingDeprecationWarning
DeprecationWarning
Initially, only
PendingDeprecationWarning
\ s were silenced by default. Starting from Python 2.7,DeprecationWarning
\ s are also silenced by default [#]_ [#]_.Since this distinction is no longer true:
PendingDeprecationWarning
should not be usedDeprecationWarning
will be used for all deprecations
PendingDeprecationWarning
won't be removed, and 3rd-party projects are allowed to use it as they see fit.
What about adding deprecations in bugfix releases? If current behavior is obviously incorrect and should be fixed in development branch, but this can break existing code that implicitly depends on current behavior. Can we add documentation-only warnings or use PendingDeprecationWarning if possible?
Deprecation Process
These are the steps required to deprecate and remove an API:
propose to deprecate an API on a tracker issue or on python-dev and decide in which version it will be removed.
attach to the issue a patch to deprecate the API that:
- adds a
DeprecationWarning
to the code
Some deprecation can be documentation-only.
May be worth to mention also FutureWarning
. AFAIK it is used if the
method will not be removed in future, but it's behavior will be changed
in incompatible way.
- adds the deprecation to the documentation
Needed explicit link to the "Documenting the deprecations" section.
- adds a test to verify that the warning is raised
- possibly updates code/examples that uses the deprecated API
after review, apply the patch to the current in-development branch and close the issue.
attach to a separate issue a patch to remove the API that:
- removes the API and the warning
- removes the tests for the API and for the deprecation
- removes the API documentation
once the designated branch is available, apply the patch and close the issue.
There is a special case for pickling. Existing pickle data created in old Python releases can contain references to deprecated classes or factory functions. Either we should keep old names (even non-public) as aliases to new names or add new mapping for 3 to 3 translation in _compat_pickle.py or new module.
Documenting the deprecations
- All deprecations should be documented in the docs, using the
deprecated-removed
directive.
When use deprecated
and when use deprecated-removed
?