[python-committers] Deprecation Policy PEP

[Serhiy Storchaka]

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.

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

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.

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