On Fri, Jan 29, 2016 at 11:59 PM, Serhiy Storchaka firstname.lastname@example.org wrote:
On 29.01.16 21:56, Ezio Melotti wrote:
On Fri, Jan 29, 2016 at 8:00 PM, Serhiy Storchaka email@example.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
-3flag). 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.
deprecatedand when use
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