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:
>> 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.