<div dir="ltr"><br><br><div class="gmail_quote"><div dir="ltr">On Fri, 29 Jan 2016 at 11:57 Ezio Melotti <<a href="mailto:ezio.melotti@gmail.com">ezio.melotti@gmail.com</a>> wrote:<br></div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">On Fri, Jan 29, 2016 at 8:00 PM, Serhiy Storchaka <<a href="mailto:storchaka@gmail.com" target="_blank">storchaka@gmail.com</a>> wrote:<br>
> On 29.01.16 19:11, Ezio Melotti wrote:<br>[SNIP]<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>
><br>
><br>
> Some deprecation can be documentation-only.<br>
><br>
<br>
Do you have examples where this has been done?<br>
I don't see the point of telling doc readers that a feature is<br>
deprecated but keeping the same information hidden to developers.  If<br>
the actual warnings cause some issue, then the issue should be<br>
addresses (the issue of being noisy has already been addressed by<br>
silencing them by default), but having doc-only deprecation warnings<br>
seems inconsistent and potentially confusing.<br></blockquote><div><br></div><div>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.</div><div><br></div><div>-Brett</div></div></div>