[python-committers] Deprecation Policy PEP

[Ezio Melotti]

On Fri, Jan 29, 2016 at 11:59 PM, Serhiy Storchaka <storchaka at gmail.com> wrote:
> On 29.01.16 21:56, Ezio Melotti wrote:
>>
>> On Fri, Jan 29, 2016 at 8:00 PM, Serhiy Storchaka <storchaka at gmail.com>
>> wrote:
>>>
>>> What about adding deprecations in bugfix releases? If current behavior is
>>> obviously incorrect and should be fixed in development branch, but this
>>> can
>>> break existing code that implicitly depends on current behavior. Can we
>>> add
>>> documentation-only warnings or use PendingDeprecationWarning if possible?
>>
>>
>> Usually deprecations are added in minor releases -- I don't know if we
>> added DeprecationWarnings in bugfix releases before.  Adding
>> documentation-only warnings in previous releases shouldn't be a
>> problem.  We already did this in the 2.7 docs for APIs that have been
>> deprecated/renamed/removed in 3.x.
>> If for example we deprecate something in 3.6, I see no harm in adding
>> a doc warning to the 2.7/3.5 docs stating that the feature is
>> deprecated starting from 3.6 and removed in 3.8.
>> I don't think we need to add DWs/PWDs though.
>
>
> We already added DeprecationWarnings in bugfix releases of 2.7 (but only
> enabled using the ``-3`` flag). There is no such mechanism for backporting
> warnings in 3.x, but there is a need. I'm interesting wherever using
> PendingDeprecationWarning instead of DeprecationWarnings is good enough for
> this as well as they are less intrusive.
>

If both are silenced by default, what makes PDW less intrusive?
For 2.7 the situation is a bit different because we have the -3 flag,
but for 3.x I think doc warnings are enough.

>>> 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.
>
>
> An attribute of a module. While in theory we can add a warning using a hack
> with replacing a module with module subclass instance, nobody does this in
> the stdlib.
>

Good point.  For this case having a doc-only warning should be ok, as
it's not worth the trouble required to raise an actual warning.
Perhaps this also requires a longer deprecation period, to give the
desv more time to notice.

> Removing some special behavior can be considered as needed a deprecation
> period. For example the change of datetime.time.__bool__ (made without a
> deprecation in issue13936) or ElementTree.Element.__bool__ (added indefinite
> FutureWarning).
>
>> If I understand correctly, this only affects pickleable APIs that have
>> been moved/renamed.
>
>
> Since most Python classes are pickleable by default, this affects modules,
> Python classes with stable structure that doesn't have unpickleable
> attributes, classes specially designed for pickling, simple subclasses of
> pickleable classes, and factory functions or methods that are used for
> pickle representation.
>

What I meant is that it shouldn't affect API that get removed, but
only the ones that have been moved/renamed (e.g. assertEquals ->
assertEqual).
If an API is gone, keeping the name around wouldn't help for pickle, would it?

>> If it can be done in a _compat_pickle.py it might be ok.
>
>
> Currently _compat_pickle.py is used only for pickles created in 2.x. We need
> parallel mechanism for 3.x pickles. I think this mechanism should be
> documented in the same document that specifies API removal, i.e. in this
> PEP.
>
>>> When use ``deprecated`` and when use ``deprecated-removed``?
>>
>>
>> If we agree to always specify when the API will be removed, then we
>> won't need to use "deprecated" anymore.
>> If we want to keep using indefinite deprecations we will use it for them.
>>
>> This should be specified in the PEP once we reach a consensus.
>
>
> May be define that the "deprecated" directive has term to next change of
> mayor version number (Python 4 currently)? It can be prolonged further, but
> the existing of the API beyond this term shouldn't be expected.
>

So make deprecated:: 3.6 a shorthand for deprecated-removed:: 3.6 4.0?
It could be done, but I'm not sure it's worth it.

Best Regards,
Ezio Melotti