[python-committers] Deprecation Policy PEP

Brett Cannon brett at python.org
Fri Jan 29 15:02:09 EST 2016


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

> On Fri, Jan 29, 2016 at 8:00 PM, Serhiy Storchaka <storchaka at gmail.com>
> wrote:
> > On 29.01.16 19:11, Ezio Melotti wrote:
> [SNIP]
> >> 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.
> >
>
> Do you have examples where this has been done?
> I don't see the point of telling doc readers that a feature is
> deprecated but keeping the same information hidden to developers.  If
> the actual warnings cause some issue, then the issue should be
> addresses (the issue of being noisy has already been addressed by
> silencing them by default), but having doc-only deprecation warnings
> seems inconsistent and potentially confusing.
>

I have an example. When the concept of create_module()/exec_module() came
into being for importlib, we wanted to deprecate load_module(). The problem
is that while we had worked out the new API, we had not figured out how
best to update C extension modules yet to the new API. We knew that
load_module() usage should be discouraged, but we didn't want to trigger a
DeprecationWarning while the stdlib itself had not stopped using it. So we
documented it as deprecated without raising a DeprecationWarning.

-Brett
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/python-committers/attachments/20160129/ab2d379e/attachment-0001.html>


More information about the python-committers mailing list