[python-committers] Deprecation Policy PEP
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>
> > On 29.01.16 19:11, Ezio Melotti wrote:
> >> 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.
-------------- next part --------------
An HTML attachment was scrubbed...
More information about the python-committers