gh-158285: Deprecate socket.ALG_SET_PUBKEY, ALG_OP_SIGN and ALG_OP_VERIFY

[MannXo]

Deprecates socket.ALG_SET_PUBKEY, ALG_OP_SIGN and ALG_OP_VERIFY for removal in 3.21, following encukou's +1 on the issue.

None of the three is in mainline include/uapi/linux/if_alg.h, so CPython always uses its own fallbacks from Modules/socketmodule.h (6, 2, 3). On Linux 5.10 and later, 6 is ALG_SET_DRBG_ENTROPY.

The change follows the pattern ast uses for its deprecated classes in 3.16:

• socket.py pops the three names after from _socket import * and leaves them out of socket.__all__, so from socket import * stays silent.
• A module __getattr__ returns the old value through warnings._deprecated(..., remove=(3, 21)).

_socket itself is unchanged, so _socket.ALG_SET_PUBKEY still exists without a warning. I left the C side alone because _socket is private and the fallback defines go at removal time anyway. If you would rather _socket warned too, a module __getattr__ like the one zlib uses for __version__ would do it, and I can add that.

Docs: a deprecated-removed note on the ALG_* entry in socket.rst, What's New 3.16 "New deprecations", "Pending removal in Python 3.21", and a Library NEWS entry.

Testing: the new GeneralModuleTests.test_deprecated_alg_constants is skipped where _socket lacks the constants, so it runs on Linux only. I built with --with-pydebug on macOS, where AF_ALG does not exist, so I ran it with the three values set on _socket before importing socket. It passes with the change, and without it fails on assertNotIn(name, socket.__all__) for all three. ./python.exe -m test test_socket test___all__ passes (755 run, 261 skipped). Accessing the names warns at the caller's line:

DeprecationWarning: 'socket.ALG_SET_PUBKEY' is deprecated and slated for removal in Python 3.21

The docs build with --nitpicky adds no warnings (check-warnings.py --fail-if-regression --fail-if-improved passes), and sphinx-lint and ruff are clean.

• Issue: _socket.ALG_SET_PUBKEY is a wrong internal value from libkcapi (changed in 2022) #158285

[read-the-docs-community]

Documentation build overview

📚 cpython-previews | 🛠️ Build #34821929 | 📁 Comparing 73671ff against main (3330712)

  🔍 Preview build  

9 files changed · ± 9 modified

± Modified

• deprecations/index.html
• deprecations/pending-removal-in-3.21.html
• library/socket.html
• whatsnew/3.12.html
• whatsnew/3.13.html
• whatsnew/3.14.html
• whatsnew/3.15.html
• whatsnew/3.16.html
• whatsnew/changelog.html

[CheViana]

Would it make sense to

1. fix and add more info to comment in

   cpython/Modules/socketmodule.h

   Line 211 in 0f5abe6

   # ifndef ALG_SET_PUBKEY

   ? as "Linux 4.8" comment is sort of erroneous

2. add info to https://docs.python.org/3/library/socket.html#socket.SOL_ALG perhaps link to https://github.com/torvalds/linux/blob/master/Documentation/crypto/userspace-if.rst

3. generally make sure python socket ALG_* constants agree with ones in https://github.com/torvalds/linux/blob/72d3fcf802c45d00b300f25b848a93c3a2bd7c7e/include/uapi/linux/if_alg.h#L49 - as it would have 2 params (ALG_SET_AEAD_ASSOCLEN and ALG_SET_AEAD_AUTHSIZE) when if_alg.h has 7 params listed. kind of make sense to either list all or none?

Happy to contribute another PR if that's out of scope for this one