<div dir="ltr">+1 to this proposal. I reviewed the contents and I feel it is comprehensive.<div><br><div><div>It should be easy to follow for any deprecations. Also, we should give some examples of how</div></div><div>the <span style="font-size:12.8px">deprecated-removed directive will be used. </span></div><div><br></div><div>Since our policy itself is very subjective (for good reasons), I propose that we be little rigorous in</div><div>documenting or implementing it. By that I mean.</div><div><br></div><div>.. <span style="font-size:12.8px">deprecated-removed: <br></span></div><div><span style="font-size:12.8px"><br></span></div><div><span style="font-size:12.8px">1. Should provide a) since and b) removed versions. It does it today.</span></div><div><span style="font-size:12.8px">2. Clarify what `versionmodified` option means. i don't know or can't figure out in relation to point 1.</span></div><div><span style="font-size:12.8px">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.</span></div><div><span style="font-size:12.8px"><br></span></div><div><span style="font-size:12.8px">-- </span></div><div><span style="font-size:12.8px">Senthil</span></div><div><span style="font-size:12.8px"><br></span></div><div><br></div><div><span style="font-size:12.8px"><br></span></div></div></div><div class="gmail_extra"><br><div class="gmail_quote">On Fri, Jan 29, 2016 at 9:11 AM, Ezio Melotti <span dir="ltr"><<a href="mailto:ezio.melotti@gmail.com" target="_blank">ezio.melotti@gmail.com</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">Hi,<br>
in the past I suggested to document our deprecation policy on a PEP.<br>
Since the issue came up again on a few issues on the tracker and on<br>
#python-dev, I adapted the content of my previous email and wrote a<br>
PEP.<br>
<br>
Attached you can find the full text, including references to the<br>
previous discussions on python-dev and related issues.<br>
<br>
Best Regards,<br>
Ezio Melotti<br>
<br>
---------<br>
<br>
PEP: XXX<br>
Title: Deprecation Policy<br>
Version: $Revision$<br>
Last-Modified: $Date$<br>
Author: Ezio Melotti <<a href="mailto:ezio.melotti@gmail.com">ezio.melotti@gmail.com</a>><br>
Status: Draft<br>
Type: Process<br>
Content-Type: text/x-rst<br>
Created: 29-Jan-2016<br>
Post-History:<br>
<br>
<br>
Abstract<br>
========<br>
<br>
The goal of this PEP is to document when and how to deprecate<br>
APIs in the Python language and in the standard library.<br>
<br>
<br>
Rationale<br>
=========<br>
<br>
Python doesn't currently have a documented policy regarding<br>
deprecations. This leads to repeated discussions and<br>
inconsistencies in how we handle and document deprecations<br>
[#]_ [#]_ [#]_ [#]_ [#]_ [#]_ [#]_.<br>
<br>
<br>
What and when to deprecate<br>
==========================<br>
<br>
* An API can be deprecated if a better alternative exists, if the<br>
implementation is incorrect or obsolete, or if the name or module<br>
has been changed. If possible, an alternative should be provided.<br>
* If the API is public, it must go through the deprecation<br>
process. If the API is private or provisional, it might.<br>
* The number of releases before an API is removed is decided<br>
on a case-by-case basis depending on widely used the API is,<br>
in which Python versions the alternative is available, which<br>
Python versions are currently supported by different operating<br>
systems, distros, and projects, and how easy it is to replace<br>
the API.<br>
* In general it's better to be conservative, and if the API is<br>
deprecated in ``3.X``, it shouldn't be removed before ``3.X+2``.<br>
This should also take into account which Python versions are<br>
currently .<br>
<br>
<br>
Porting from 2.x to 3.x<br>
-----------------------<br>
<br>
Some APIs that are available in Python 2.7 might get deprecated<br>
in Python 3, and people that upgrade directly from 2.7 to 3.X might<br>
not see any warnings.<br>
<br>
In order to make porting code to 3.X easier:<br>
<br>
* nothing that is available and not deprecated in 2.7 should be<br>
removed from Python 3 as long as 2.7 is officially supported;<br>
* deprecation warnings can be backported to 2.7 and enabled<br>
using the ``-3`` flag;<br>
<br>
<br>
Deprecation Warnings<br>
====================<br>
<br>
Python offers two kinds of deprecation warnings:<br>
<br>
* ``PendingDeprecationWarning``<br>
* ``DeprecationWarning``<br>
<br>
Initially, only ``PendingDeprecationWarning``\ s were silenced by<br>
default. Starting from Python 2.7, ``DeprecationWarning``\ s<br>
are also silenced by default [#]_ [#]_.<br>
<br>
Since this distinction is no longer true:<br>
<br>
* ``PendingDeprecationWarning`` should not be used<br>
* ``DeprecationWarning`` will be used for all deprecations<br>
<br>
``PendingDeprecationWarning`` won't be removed, and 3rd-party<br>
projects are allowed to use it as they see fit.<br>
<br>
<br>
Deprecation Progression<br>
=======================<br>
<br>
In the past, the following deprecation progression has been used:<br>
<br>
1. in release ``3.X`` a ``PendingDeprecationWarning`` is added<br>
2. in release ``3.X+1`` it becomes a ``DeprecationWarning``<br>
3. in release ``3.X+2`` the API is removed<br>
<br>
The warning were occasionally left for more than one release,<br>
either intentionally or because no one remembered to update them.<br>
<br>
Since ``PendingDeprecationWarning`` should no longer be used, this<br>
can be simplified to:<br>
<br>
1. in release ``3.X`` a ``DeprecationWarning`` is added<br>
2. in release ``3.X+N`` the API is removed<br>
<br>
``N`` can be ``>=1``, should be decided beforehand, and should be<br>
documented explicitly.<br>
<br>
<br>
Deprecation Process<br>
===================<br>
<br>
These are the steps required to deprecate and remove an API:<br>
<br>
1. propose to deprecate an API on a tracker issue or on python-dev<br>
and decide in which version it will be removed.<br>
<br>
2. attach to the issue a patch to deprecate the API that:<br>
<br>
* adds a ``DeprecationWarning`` to the code<br>
* adds the deprecation to the documentation<br>
* adds a test to verify that the warning is raised<br>
* possibly updates code/examples that uses the deprecated API<br>
<br>
3. after review, apply the patch to the current in-development<br>
branch and close the issue.<br>
<br>
4. attach to a separate issue a patch to remove the API that:<br>
<br>
* removes the API and the warning<br>
* removes the tests for the API and for the deprecation<br>
* removes the API documentation<br>
<br>
5. once the designated branch is available, apply the patch and<br>
close the issue.<br>
<br>
<br>
Deprecation Messages<br>
====================<br>
<br>
When a deprecated API is used, a ``DeprecationWarning`` should<br>
be raised. The message should mention that the API is<br>
deprecated, and if possible it should indicate when it will be<br>
removed and what should be used instead.<br>
<br>
These messages are intended for developers, and are therefore<br>
hidden by default to prevent end-users to see them.<br>
<br>
These messages should be enabled by default in places where only<br>
developers will see them, such as tests [#]_ and in the interactive<br>
interpreter [#]_.<br>
<br>
<br>
Documenting the deprecations<br>
============================<br>
<br>
* All deprecations should be documented in the docs, using the<br>
``deprecated-removed`` directive.<br>
* If an alternative is available, it should be mentioned, possibly<br>
including examples.<br>
* Each "what's new" document should include either a section or a<br>
link to a separate document [#]_ listing all the new deprecations,<br>
the APIs that have been removed and possibly the planned<br>
removals for the upcoming releases. This could be generated<br>
automatically with Sphinx.<br>
* Simply removing the documentation for deprecated APIs is<br>
not acceptable, since people that see the API used in the<br>
code won't know if they can still use the API or not.<br>
<br>
<br>
Deprecation warnings rendering<br>
------------------------------<br>
<br>
On one hand deprecation warnings should be clearly visible, on the<br>
other hand we want to avoid riddling the docs with red boxes [#]_.<br>
<br>
In order to find a balance between the two:<br>
<br>
* Individual functions/methods/attributes should have a label next<br>
to the name to indicate the deprecation, and a more verbose<br>
description underneath. The label will be red, the description<br>
doesn't have to [#]_.<br>
* Modules and classes can use a red warning box. If the<br>
documentation spans more than a single screen of text, additional<br>
warning labels can be added to the individual functions/methods.<br>
* Links to deprecated objects should be marked differently.<br>
<br>
This will require some tweak to the ``deprecated-removed``<br>
directive, in order to produce different CSS classes for<br>
modules/classes, functions/methods/attributes, and links.<br>
<br>
<br>
Updating deprecated code<br>
========================<br>
<br>
As mentioned above, the error messages and documentation should<br>
provide an alternative whenever possible. When the alternative<br>
is not straightforward, more complex examples or a new section<br>
can added to the documentation to explain how to convert the code.<br>
<br>
Another option is to write scripts that can automatically update<br>
Python code to use the new alternative. This requires:<br>
<br>
1. writing a 3to3 tool similar to (and possibly based on) 2to3;<br>
2. documenting clearly its API and providing several examples;<br>
3. providing fixers for deprecated APIs that can be used to<br>
automatically update deprecated code;<br>
<br>
This can be done as a GSoC project, and if done correctly, it will<br>
provide an easy way for people to upgrade their codebases.<br>
<br>
<br>
See also<br>
========<br>
<br>
* :pep:`387` -- Backwards Compatibility Policy<br>
* :pep:`4` -- Deprecation of Standard Modules<br>
<br>
<br>
References<br>
==========<br>
<br>
.. [#] Deprecation Policy<br>
(<a href="https://mail.python.org/pipermail/python-dev/2011-October/114199.html" rel="noreferrer" target="_blank">https://mail.python.org/pipermail/python-dev/2011-October/114199.html</a>)<br>
<br>
.. [#] Deprecation Policy<br>
(<a href="https://mail.python.org/pipermail/python-dev/2014-January/132069.html" rel="noreferrer" target="_blank">https://mail.python.org/pipermail/python-dev/2014-January/132069.html</a>)<br>
<br>
.. [#] deprecated in 3.2/3.3, should be removed in 3.5 or ???<br>
(<a href="https://bugs.python.org/issue13248" rel="noreferrer" target="_blank">https://bugs.python.org/issue13248</a>)<br>
<br>
.. [#] DeprecationWarning for PEP 479 (generator_stop)<br>
(<a href="http://bugs.python.org/issue26136" rel="noreferrer" target="_blank">http://bugs.python.org/issue26136</a>)<br>
<br>
.. [#] Deprecate threading.Thread.isDaemon etc<br>
(<a href="http://bugs.python.org/issue24203" rel="noreferrer" target="_blank">http://bugs.python.org/issue24203</a>)<br>
<br>
.. [#] Remove the Deprecated API in trace module<br>
(<a href="http://bugs.python.org/issue26069" rel="noreferrer" target="_blank">http://bugs.python.org/issue26069</a>)<br>
<br>
.. [#] Resurrect inspect.getargspec() in 3.6<br>
(<a href="http://bugs.python.org/issue25486" rel="noreferrer" target="_blank">http://bugs.python.org/issue25486</a>)<br>
<br>
.. [#] What's New in Python 2.7 -- Changes to the Handling of<br>
Deprecation Warnings (<a href="https://docs.python.org/3/whatsnew/2.7.html" rel="noreferrer" target="_blank">https://docs.python.org/3/whatsnew/2.7.html</a>)<br>
<br>
.. [#] Silence DeprecationWarning by default<br>
(<a href="https://bugs.python.org/issue7319" rel="noreferrer" target="_blank">https://bugs.python.org/issue7319</a>)<br>
<br>
.. [#] Enable warnings by default in unittest<br>
(<a href="https://bugs.python.org/issue10535" rel="noreferrer" target="_blank">https://bugs.python.org/issue10535</a>)<br>
<br>
.. [#] DeprecationWarnings should be visible by default in the<br>
interactive REPL (<a href="https://bugs.python.org/issue24294" rel="noreferrer" target="_blank">https://bugs.python.org/issue24294</a>)<br>
<br>
.. [#] Django has a "Django Deprecation Timeline" page<br>
(<a href="https://docs.djangoproject.com/en/dev/internals/deprecation/" rel="noreferrer" target="_blank">https://docs.djangoproject.com/en/dev/internals/deprecation/</a>)<br>
<br>
.. [#] Consistent documentation practices for security concerns<br>
and considerations (<a href="https://bugs.python.org/issue13515" rel="noreferrer" target="_blank">https://bugs.python.org/issue13515</a>)<br>
<br>
.. [#] Put "deprecated" warnings first<br>
(<a href="http://bugs.python.org/issue25467" rel="noreferrer" target="_blank">http://bugs.python.org/issue25467</a>)<br>
<br>
<br>
Copyright<br>
=========<br>
<br>
This document has been placed in the public domain.<br>
_______________________________________________<br>
python-committers mailing list<br>
<a href="mailto:python-committers@python.org">python-committers@python.org</a><br>
<a href="https://mail.python.org/mailman/listinfo/python-committers" rel="noreferrer" target="_blank">https://mail.python.org/mailman/listinfo/python-committers</a><br>
</blockquote></div><br></div>