Formalize the concept of "soft deprecation" (don't schedule removal) in PEP 387 "Backwards Compatibility Policy"

[encukou (Petr Viktorin)]

Having N:M replacements is perfectly fine.
But writing them all down should be a prerequisite for removing API.

[vstinner (Victor Stinner)]

@encukou

But writing them all down should be a prerequisite for removing API.

Over the last years, IMO the quality of instructions to get rid of deprecated and removed functions improved in What’s New In Python documents. Sure, there is always room for enhancement, and contributions are welcomed Recently, I enhanced imp removal docs (Python 3.12) to provide recipes to replace removed APIs.

The most difficult part is to provide a solution working on old and new Python versions. If possible, a solution for that should always be provided.

[oscarbenjamin]

@brettcannon

To be clear, this random example is one which can’t have a 1:1 replacement because the old API didn’t fit into the import APIs well and everyone used the old API in varying ways.

I expect that there is usually not going to be an exact one to one replacement but it is good to remember that it is what the reader ideally wants. If a perfect replacement can be provided then there is probably not a good reason for deprecation in the first place (just have the old API call the replacement and leave it soft-deprecated). Usually though there will be easy replacements for the most obvious/common usage even if a perfect replacement is not possible.

Mainly it is just good to show any clear example of how the deprecated API might have been used and what a better/updated version could be. Remember that the reader might not have heard of this API before and might have no idea how to use it. Just learning the API enough to confirm a fix might be the bulk of the work from their perspective.