[python-committers] Deprecation Policy PEP

Senthil Kumaran senthil at uthcode.com
Fri Jan 29 12:33:50 EST 2016


+1 to this proposal. I reviewed the contents and I feel it is comprehensive.

It should be easy to follow for any deprecations. Also, we should give some
examples of how
the deprecated-removed directive will be used.

Since our policy itself is very subjective (for good reasons), I propose
that we be little rigorous in
documenting or implementing it. By that I mean.

.. deprecated-removed:

1. Should provide a) since and b) removed versions. It does it today.
2. Clarify what `versionmodified` option means. i don't know or can't
figure out in relation to point 1.
3. Provide alternative option for deprecated-removed directive. This is
going to be immensely helpful if folks are concerned with 2 to 3 migration
and will be eager to adopt the approach suggested by the documentation. We
don't do this today. This point is worth discussing.

-- 
Senthil




On Fri, Jan 29, 2016 at 9:11 AM, Ezio Melotti <ezio.melotti at gmail.com>
wrote:

> Hi,
> in the past I suggested to document our deprecation policy on a PEP.
> Since the issue came up again on a few issues on the tracker and on
> #python-dev, I adapted the content of my previous email and wrote a
> PEP.
>
> Attached you can find the full text, including references to the
> previous discussions on python-dev and related issues.
>
> Best Regards,
> Ezio Melotti
>
> ---------
>
> PEP: XXX
> Title: Deprecation Policy
> Version: $Revision$
> Last-Modified: $Date$
> Author: Ezio Melotti <ezio.melotti at gmail.com>
> Status: Draft
> Type: Process
> Content-Type: text/x-rst
> Created: 29-Jan-2016
> Post-History:
>
>
> Abstract
> ========
>
> The goal of this PEP is to document when and how to deprecate
> APIs in the Python language and in the standard library.
>
>
> Rationale
> =========
>
> Python doesn't currently have a documented policy regarding
> deprecations.  This leads to repeated discussions and
> inconsistencies in how we handle and document deprecations
> [#]_ [#]_ [#]_ [#]_ [#]_ [#]_ [#]_.
>
>
> What and when to deprecate
> ==========================
>
> * An API can be deprecated if a better alternative exists, if the
>   implementation is incorrect or obsolete, or if the name or module
>   has been changed.  If possible, an alternative should be provided.
> * If the API is public, it must go through the deprecation
>   process.  If the API is private or provisional, it might.
> * The number of releases before an API is removed is decided
>   on a case-by-case basis depending on widely used the API is,
>   in which Python versions the alternative is available, which
>   Python versions are currently supported by different operating
>   systems, distros, and projects, and how easy it is to replace
>   the API.
> * 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 .
>
>
> Porting from 2.x to 3.x
> -----------------------
>
> Some APIs that are available in Python 2.7 might get deprecated
> in Python 3, and people that upgrade directly from 2.7 to 3.X might
> not see any warnings.
>
> 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;
> * deprecation warnings can be backported to 2.7 and enabled
>   using the ``-3`` flag;
>
>
> 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.
>
>
> Deprecation Progression
> =======================
>
> In the past, the following deprecation progression has been used:
>
> 1. in release ``3.X`` a ``PendingDeprecationWarning`` is added
> 2. in release ``3.X+1`` it becomes a ``DeprecationWarning``
> 3. in release ``3.X+2`` the API is removed
>
> The warning were occasionally left for more than one release,
> either intentionally or because no one remembered to update them.
>
> Since ``PendingDeprecationWarning`` should no longer be used, this
> can be simplified to:
>
> 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.
>
>
> 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
>   * adds the deprecation to the documentation
>   * 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.
>
>
> Deprecation Messages
> ====================
>
> When a deprecated API is used, a ``DeprecationWarning`` should
> be raised.  The message should mention that the API is
> deprecated, and if possible it should indicate when it will be
> removed and what should be used instead.
>
> These messages are intended for developers, and are therefore
> hidden by default to prevent end-users to see them.
>
> These messages should be enabled by default in places where only
> developers will see them, such as tests [#]_ and in the interactive
> interpreter [#]_.
>
>
> Documenting the deprecations
> ============================
>
> * All deprecations should be documented in the docs, using the
>   ``deprecated-removed`` directive.
> * If an alternative is available, it should be mentioned, possibly
>   including examples.
> * Each "what's new" document should include either a section or a
>   link to a separate document [#]_ listing all the new deprecations,
>   the APIs that have been removed and possibly the planned
>   removals for the upcoming releases.  This could be generated
>   automatically with Sphinx.
> * Simply removing the documentation for deprecated APIs is
>   not acceptable, since people that see the API used in the
>   code won't know if they can still use the API or not.
>
>
> Deprecation warnings rendering
> ------------------------------
>
> On one hand deprecation warnings should be clearly visible, on the
> other hand we want to avoid riddling the docs with red boxes [#]_.
>
> In order to find a balance between the two:
>
> * Individual functions/methods/attributes should have a label next
>   to the name to indicate the deprecation, and a more verbose
>   description underneath.  The label will be red, the description
>   doesn't have to [#]_.
> * Modules and classes can use a red warning box.  If the
>   documentation spans more than a single screen of text, additional
>   warning labels can be added to the individual functions/methods.
> * Links to deprecated objects should be marked differently.
>
> This will require some tweak to the ``deprecated-removed``
> directive, in order to produce different CSS classes for
> modules/classes, functions/methods/attributes, and links.
>
>
> Updating deprecated code
> ========================
>
> As mentioned above, the error messages and documentation should
> provide an alternative whenever possible.  When the alternative
> is not straightforward, more complex examples or a new section
> can added to the documentation to explain how to convert the code.
>
> Another option is to write scripts that can automatically update
> Python code to use the new alternative.  This requires:
>
> 1. writing a 3to3 tool similar to (and possibly based on) 2to3;
> 2. documenting clearly its API and providing several examples;
> 3. providing fixers for deprecated APIs that can be used to
>    automatically update deprecated code;
>
> This can be done as a GSoC project, and if done correctly, it will
> provide an easy way for people to upgrade their codebases.
>
>
> See also
> ========
>
> * :pep:`387` -- Backwards Compatibility Policy
> * :pep:`4` -- Deprecation of Standard Modules
>
>
> References
> ==========
>
> .. [#] Deprecation Policy
>    (https://mail.python.org/pipermail/python-dev/2011-October/114199.html)
>
> .. [#] Deprecation Policy
>    (https://mail.python.org/pipermail/python-dev/2014-January/132069.html)
>
> .. [#] deprecated in 3.2/3.3, should be removed in 3.5 or ???
>    (https://bugs.python.org/issue13248)
>
> .. [#] DeprecationWarning for PEP 479 (generator_stop)
>    (http://bugs.python.org/issue26136)
>
> .. [#] Deprecate threading.Thread.isDaemon etc
>    (http://bugs.python.org/issue24203)
>
> .. [#] Remove the Deprecated API in trace module
>    (http://bugs.python.org/issue26069)
>
> .. [#] Resurrect inspect.getargspec() in 3.6
>    (http://bugs.python.org/issue25486)
>
> .. [#] What's New in Python 2.7 -- Changes to the Handling of
>    Deprecation Warnings (https://docs.python.org/3/whatsnew/2.7.html)
>
> .. [#] Silence DeprecationWarning by default
>    (https://bugs.python.org/issue7319)
>
> .. [#] Enable warnings by default in unittest
>    (https://bugs.python.org/issue10535)
>
> .. [#] DeprecationWarnings should be visible by default in the
>    interactive REPL (https://bugs.python.org/issue24294)
>
> .. [#] Django has a "Django Deprecation Timeline" page
>    (https://docs.djangoproject.com/en/dev/internals/deprecation/)
>
> .. [#] Consistent documentation practices for security concerns
>    and considerations (https://bugs.python.org/issue13515)
>
> .. [#] Put "deprecated" warnings first
>    (http://bugs.python.org/issue25467)
>
>
> Copyright
> =========
>
> This document has been placed in the public domain.
> _______________________________________________
> python-committers mailing list
> python-committers at python.org
> https://mail.python.org/mailman/listinfo/python-committers
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/python-committers/attachments/20160129/b8a44aa9/attachment-0001.html>


More information about the python-committers mailing list