gh-106240: Add stdlib_deprecations module

[vstinner]

• Issue: Add stdlib_deprecations module #106240

---

📚 Documentation preview 📚: https://cpython-previews--106241.org.readthedocs.build/

[vstinner]

This PR is incomplete: I wrote it to propose the idea of a new "stdlib_deprecations" module: API to query if a function is deprecated or not. The API should be designed. So far, I only proposed a very basic API:

stdlib_deprecations.is_deprecated(name) returns True if a stdlib module or a stdlib module is deprecated.

stdlib_deprecations.is_capi_deprecated(name) returns True if a C API symbol is deprecated.

Internally, I wrote a dataclass which contains the following data:

• Name
• Version when the API is deprecated
• Optional version when the API is removed
• Optional message: usually explain how to replace the deprecate API

My current API doesn't provide all data. Maybe the API should be get_deprecated() instead: return the dataclass, or None if it's not deprecated.

TODO: enhance the API to support other deprecation kinds, like deprecation of a function parameter. I propose module.function:argument_name name. We already use such syntax in PyArg_ParseTuple() C API: :function_name suffix in the format string.

[vstinner]

cc @hugovk

[sobolevn]

I like the idea! 👍

[vstinner]

I changed the API to: get_deprecated(name) which returns a Deprecated object if the API is deprecated, or None if it's not.

[merwok]

Does this mean the exact call os.urandom() without args, or is it a reference to the function with parentheses added like in C documentation?

Being a Python dev and not a C dev, I take os.urandom to mean one thing and os.urandom() to mean another thing!

[vstinner]

os.urandom() has no arguments. Adding parenthesis is a hint to show that it's a function

[merwok]

OK but my point is that it’s not a great doc convention for Python. I think the functions that follow need arguments but have () too, that’s misleading.

[terryjreedy]

I presume that ssl.RAND_pseudo_bytes is the name of a function. The exact replacement is os.random, without (). I think it should be given than way.

[vstinner]

In practice, I expect that the most usual usage of a function like ssl.RAND_pseudo_bytes is to call it: ssl.RAND_pseudo_bytes(). So I prefer to specify the replacement with parenthesis as well: os.urandom(). In my current implementation, Deprecation.message is an arbitrary string, it's not designed to automate replacement by a linter or a similar tool.

[vstinner]

It seems like pylint would prefer a JSON file than a stdlib module. I'm not sure that this module is a good idea :-)

See: https://discuss.python.org/t/formalize-the-concept-of-soft-deprecation-dont-schedule-removal-in-pep-387-backwards-compatibility-policy/27957/61

[michaelfm1211]

Just from a quick look over the documentation preview, it looks like there's something wrong with the synatx. The name attribute heading for the stdlib_deprecations.Deprecated appears as .. attribute:: name in a code block. I'm unsure why though; the reST looks fine.

[vstinner]

Oh right, it was because of Attributes:: syntax: fixed

[vstinner]

I'm not sure about this approach. Linters developpers seem to prefer JSON files rather than an import.

[merwok]

Yea, the discussion thread seems to agree on a data file rather than a module.

[vstinner]

Yea, the discussion thread seems to agree on a data file rather than a module.

Right. I close my issue and its PR.