Skip to content

gh-134160: Split extension module init from PyModule docs; emphasize multi-phase init #135126

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 3 commits into
base: main
Choose a base branch
from

Conversation

encukou
Copy link
Member

@encukou encukou commented Jun 4, 2025

#134764 moved a section around; I don't think that's enough.


  • Split extension module init from PyModule docs; emphasize multi-phase init

    There's a difference between working with module objects in general
    (which just needs garden-variety API docs), and defining the init
    function (which covers things like correctly exporting a function
    defined by the user, and lots of behaviour that's unrelated to generic
    module objects).

  • Document behaviour of single-phase init. Call it "legacy".

  • Reorganize PyModule docs.

  • Move PyInit_modulename docs from the tutorial, and PyMODINIT_FUNC docs
    from the generic macros section, to the new page.

  • Add docs

  • Add doc stubs for PYTHON_API_VERSION & PYTHON_ABI_VERSION

  • Remove incorrect refcounts.dat entry for PyModuleDef_Init;
    instead note that the function sometimes returns a borrowed reference,
    sometimes as strong one.
    (IMO, it's best to pretend PyModuleDef isn't a PyObject at all,
    but, reference docs should be correct.)


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

…asize multi-phase init

Document behaviour of single-phase init. Call it "legacy".

Reorganize PyModule docs.

Move PyInit_modulename docs from the tutorial to reference documentation.

Move PyMODINIT_FUNC docs from generic macros to the new page.

Add doc stubs for `PYTHON_API_VERSION` & `PYTHON_ABI_VERSION`

Remove incorrect refcounts.dat entry for `PyModuleDef_Init`.
This removes the "Return value: Borrowed reference." note.
Instead, note that the function sometimes returns a borrowed reference,
sometimes as strong one.
(IMO, it's best to not think of `PyModuleDef` as a `PyObject` at all,
and act like it can't be reference-counted.)

Co-authored-by: Adam Turner <[email protected]>
Copy link
Contributor

@StanFromIreland StanFromIreland left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

From a quick look, though I assume some are existing errors.

@encukou
Copy link
Member Author

encukou commented Jun 5, 2025

Thank you!

Copy link
Member

@hugovk hugovk left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thank you!

Comment on lines +5 to +6
Defining Extension Modules
--------------------------
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Use sentence case for headers:

https://devguide.python.org/documentation/style-guide/#capitalization

Suggested change
Defining Extension Modules
--------------------------
Defining extension modules
--------------------------


Building, packaging and distributing extension modules is best done with
third-party tools, and is out of scope of this document.
One suitable tool is ``setuptools``, whose documentation can be found at
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
One suitable tool is ``setuptools``, whose documentation can be found at
One suitable tool is Setuptools, whose documentation can be found at

By default, extension modules are not singletons.
For example, if the :py:attr:`sys.modules` entry is removed and the module
is re-imported, a new module object is created, and typically populated with
fresh method and type objects.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

?

Suggested change
fresh method and type objects.
fresh methods and type objects.

defining multiple initialization functions. However, importing them requires
using symbolic links or a custom importer, because by default only the
function corresponding to the filename is found.
See the *"Multiple modules in one library"* section in :pep:`489` for details.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Add a direct link to this section?

@@ -111,33 +111,11 @@ Useful macros
=============

Several useful macros are defined in the Python header files. Many are
defined closer to where they are useful (e.g. :c:macro:`Py_RETURN_NONE`).
defined closer to where they are useful (e.g. :c:macro:`Py_RETURN_NONE`,
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
defined closer to where they are useful (e.g. :c:macro:`Py_RETURN_NONE`,
defined closer to where they are useful (for example, :c:macro:`Py_RETURN_NONE`,

Comment on lines +26 to +30
One suitable tool is ``setuptools``, whose documentation can be found at
https://setuptools.readthedocs.io/en/latest/setuptools.html.

The :mod:`distutils` module, which was included in the standard library
until Python 3.12, is now maintained as part of ``setuptools``.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
One suitable tool is ``setuptools``, whose documentation can be found at
https://setuptools.readthedocs.io/en/latest/setuptools.html.
The :mod:`distutils` module, which was included in the standard library
until Python 3.12, is now maintained as part of ``setuptools``.
One suitable tool is Setuptools, whose documentation can be found at
https://setuptools.readthedocs.io/en/latest/setuptools.html.
The :mod:`distutils` module, which was included in the standard library
until Python 3.12, is now maintained as part of Setuptools.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants