python/steering-council

Update PEP 387 Backwards Compatibility Policy: Add Soft Deprecation

vstinner opened this issue · 2 comments

vstinner commented

Please consider my update of PEP 387 Backwards Compatibility Policy: Add Soft Deprecation.
https://peps.python.org/pep-0387/

=> please review PR: python/peps#3182

  • The PEP has been discussed in threads listed in its Post-History header
  • The PEP was announced on Discuss (link in Post-History)
  • The PEP includes all relevant Suggested Sections
  • The PEP includes endorsements from the projects/groups/people it helps
  • The PEP has a CODEOWNERS entry

The rationale to add soft deprecations:

  • Prevent core developers to eaggerly remove soft deprecated code: soft deprecated APIs are not planned for removal
  • No warnings, whereas regular "hard" deprecations usually emit DeprecationWarning: soft deprecation is only in the documentation
  • We can more freely mark old APIs as soft deprecated to help users to choose between variants of similar APIs (which one is "the good one"?).

At the beginning, I proposed to issue a SoftDeprecationWarning warning at runtime. But warnings are calling for action, whereas a soft deprecation does not call for action: it's perfectly fine to continue using it. I updated my PR to no longer issue warnings.

Note: It was proposed to export the list of deprecated APIs as a JSON file, or a new stdlib_deprecations module: but that's not directly related to PEP 387 change. It will be discussed separately.

Yhg1s commented

The SC agrees with the proposal and accepts the PEP update.

  • 👍2
vstinner commented

Thanks for investivating my case 😁