On Fri, 29 Jan 2016 at 11:57 Ezio Melotti ezio.melotti@gmail.com wrote:
On Fri, Jan 29, 2016 at 8:00 PM, Serhiy Storchaka storchaka@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:
propose to deprecate an API on a tracker issue or on python-dev and decide in which version it will be removed.
attach to the issue a patch to deprecate the API that:
- adds a
DeprecationWarning
to the codeSome 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