On Fri, Jan 29, 2016 at 8:00 PM, Serhiy Storchaka email@example.com wrote:
On 29.01.16 19:11, Ezio Melotti wrote:
Python offers two kinds of deprecation warnings:
PendingDeprecationWarning\ s were silenced by default. Starting from Python 2.7,
DeprecationWarning\ s are also silenced by default [#]_ [#]_.
Since this distinction is no longer true:
PendingDeprecationWarningshould not be used
DeprecationWarningwill be used for all deprecations
PendingDeprecationWarningwon't be removed, and 3rd-party projects are allowed to use it as they see fit.
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.
These are the steps required to deprecate and remove an API:
propose to deprecate an API on a tracker issue or on python-dev and decide in which version it will be removed.
attach to the issue a patch to deprecate the API that:
- adds a
DeprecationWarningto 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.
May be worth to mention also
FutureWarning. AFAIK it is used if the method will not be removed in future, but it's behavior will be changed in incompatible way.
Good point. I'll investigate a bit and add it.
- adds the deprecation to the documentation
Needed explicit link to the "Documenting the deprecations" section.
- adds a test to verify that the warning is raised
- possibly updates code/examples that uses the deprecated API
after review, apply the patch to the current in-development branch and close the issue.
attach to a separate issue a patch to remove the API that:
- removes the API and the warning
- removes the tests for the API and for the deprecation
- removes the API documentation
once the designated branch is available, apply the patch and close the issue.
There is a special case for pickling. Existing pickle data created in old Python releases can contain references to deprecated classes or factory functions. Either we should keep old names (even non-public) as aliases to new names or add new mapping for 3 to 3 translation in _compat_pickle.py or new module.
If I understand correctly, this only affects pickleable APIs that have been moved/renamed. You could argue that if we are willing to break code that uses the old names, then we could do the same to old pickles. Keeping the names around will allow both code and pickles to keep working and we will effectively have an indefinite deprecation without removal. If it can be done in a _compat_pickle.py it might be ok.
This is also another issue that I forgot to mention -- I would like to always set a version where the API will be removed, but sometimes this might mean Python 4. (FTR the reason is not to "clean up" the language ASAP, but to provide a clear timeline for both the API users and the core-devs. This is also based on the assumption that no deprecated code will stay around forever; even if it's not remove in the immediate future, at some point it will.)
Do you think it's fine using Python 4, or is it better to have indefinite (for some value of indefinite) deprecations? (Do we also expect to have 3.10, 3.11, etc. after 3.9, or will we just move to 4.0 even though we might not have major incompatible changes?)
Regardless of the decision, I want the documentation to actually match the code, so as long as the code is there and it is deprecated, the doc should say that it is there and it is deprecated. If the API is deprecated indefinitely, the docs should say so (and possibly say why too).
Documenting the deprecations
- All deprecations should be documented in the docs, using the
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.
Best Regards, Ezio Melotti