gh-149716: Document PySlot_DATA for Py_mod_gil and Py_mod_multiple_interpreters

[Taeknology]

Fixes #149716.

Summary

Adds short code examples to the documentation of two module slot IDs
(Py_mod_gil since 3.13, Py_mod_multiple_interpreters since 3.12).
The examples mirror the existing one under Py_mod_abi and make it
explicit that PySlot_DATA (not PySlot_INT64 / PySlot_UINT64)
is the correct slot-definition macro for these two slots, because
their values (Py_MOD_GIL_*, Py_MOD_MULTIPLE_INTERPRETERS_*,
Py_MOD_PER_INTERPRETER_GIL_SUPPORTED) are defined as (void *)N
in Include/moduleobject.h, and PySlot_DATA casts to void *
(Include/slots.h).

Changes

• Doc/c-api/module.rst: add a PySlot_DATA(...) code-block to each
  of the two slot sections, in the same 4-part style (intro sentence +
  .. code-block:: c + 6-space code + .. versionadded::) as the
  existing Py_mod_abi example.

The Py_mod_multiple_interpreters example shows
Py_MOD_PER_INTERPRETER_GIL_SUPPORTED (rather than the default
_SUPPORTED) since that is the value extension authors most often need
to set explicitly. Likewise the Py_mod_gil example shows
Py_MOD_GIL_NOT_USED (rather than the default _USED).

Notes

• Docs-only change; no Misc/NEWS.d entry per the
  devguide.
• RST format mirrors Py_mod_abi byte-for-byte (3-space body
  indentation, 6-space code indentation, identical directive order).

• Issue: Unclear which slot definition macro to use #149716

[python-cla-bot]

All commit authors signed the Contributor License Agreement.

[read-the-docs-community]

Documentation build overview

📚 cpython-previews | 🛠️ Build #33042986 | 📁 Comparing 4726cfd against main (68ebc05)

  🔍 Preview build  

123 files changed · + 1 added · ± 122 modified

+ Added

• howto/abi3t-migration.html

± Modified

• bugs.html
• glossary.html
• index.html
• c-api/complex.html
• c-api/exceptions.html
• c-api/import.html
• c-api/interp-lifecycle.html
• c-api/long.html
• c-api/module.html
• c-api/perfmaps.html
• and 112 more...

[encukou]

PySlot_DATA is only for the new PySlot arrays; not for the older PyModuleDef_Slot (where every value is a pointer, hence the type).
I'd word it like this:

Suggested change

	as in:
	For historical reasons, the values are declared as pointers (``void *``).
	When using :c:type:`PySlot` arrays, use :c:macro:`PySlot_DATA` for
	:c:macro:`!Py_mod_multiple_interpreters`:

[encukou]

Suggested change

	A suitable slot value can be defined using the :c:macro:`PySlot_DATA` macro,
	as in:
	For historical reasons, the values are declared as pointers (``void *``).
	When using :c:type:`PySlot` arrays, use :c:macro:`PySlot_DATA` for
	:c:macro:`!Py_mod_gil`:

[Taeknology]

Applied both, thanks.

I left Py_mod_abi as is — its value is a real pointer, so the void * note doesn't fit there. Can change it too if you want.

[encukou]

Thank you!

I left Py_mod_abi as is — its value is a real pointer, so the void * note doesn't fit there.

Perfect :)

[miss-islington-app]

Thanks @Taeknology for the PR, and @encukou for merging it 🌮🎉.. I'm working now to backport this PR to: 3.15.
🐍🍒⛏🤖

[bedevere-app]

GH-151322 is a backport of this pull request to the 3.15 branch.