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 used
* ``DeprecationWarning`` 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:
1. propose to deprecate an API on a tracker issue or on python-dev
and decide in which version it will be removed.
2. 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
3. after review, apply the patch to the current in-development
branch and close the issue.
4. 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
5. 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``?
_______________________________________________
python-committers mailing list
python-committers@python.org
https://mail.python.org/mailman/listinfo/python-committers
