Skip to content

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

Merged
encukou merged 5 commits into
python:mainfrom
encukou:prefer-multi-phase-i
Jun 13, 2025
Merged

gh-134160: Split extension module init from PyModule docs; emphasize multi-phase init#135126
encukou merged 5 commits into
python:mainfrom
encukou:prefer-multi-phase-i

Conversation

@encukou

@encukouencukou commented Jun 4, 2025•
edited by github-actions Bot
Loading

Copy link
Copy Markdown
Member

#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/

@encukou@AA-Turner
pythongh-134160: Split extension module init from PyModule docs; emph…
39b670d
…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 <9087854+AA-Turner@users.noreply.github.com>
@encukou
encukou requested a review from AA-TurnerJune 4, 2025 12:34
@bedevere-appbedevere-appBot mentioned this pull request Jun 4, 2025
Open
@encukouencukou mentioned this pull request Jun 4, 2025
Closed
StanFromIreland
StanFromIreland reviewed Jun 4, 2025
View reviewed changes

@StanFromIrelandStanFromIreland left a comment •
edited
Loading

Copy link
Copy Markdown
Member

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.

Comment threadDoc/c-api/extension-modules.rst Outdated
Comment threadDoc/c-api/extension-modules.rst Outdated
Comment threadDoc/c-api/extension-modules.rst Outdated
Comment threadDoc/c-api/extension-modules.rst Outdated
@encukou@StanFromIreland
Apply suggestions from code review
e706afd
Co-authored-by: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com>
@encukou

encukou commented Jun 5, 2025

Copy link
Copy Markdown
MemberAuthor

Thank you!

@encukouencukou mentioned this pull request Jun 10, 2025
Merged
hugovk
hugovk approved these changes Jun 11, 2025
View reviewed changes

@hugovkhugovk left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

Thank you!

Comment threadDoc/c-api/extension-modules.rst Outdated
Comment threadDoc/c-api/extension-modules.rst Outdated
Comment threadDoc/c-api/extension-modules.rst
Comment threadDoc/c-api/extension-modules.rst Outdated
Comment threadDoc/c-api/intro.rst Outdated
Comment threadDoc/extending/building.rst Outdated
@encukou@hugovk
Apply suggestions from code review
a53f207
Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>
StanFromIreland
StanFromIreland reviewed Jun 12, 2025
View reviewed changes
Comment threadDoc/extending/building.rst Outdated
@encukou@StanFromIreland
Update Setuptools URL
5380348
Co-authored-by: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com>
@encukouencukou added the needs backport to 3.14 bugs and security fixes label Jun 13, 2025
@encukou
encukou merged commit f4bc3a9 into python:mainJun 13, 2025
@miss-islington-app

miss-islington-appBot commented Jun 13, 2025

Copy link
Copy Markdown

Thanks @encukou for the PR 🌮🎉.. I'm working now to backport this PR to: 3.14.
🐍🍒⛏🤖 I'm not a witch! I'm not a witch!

@encukou
encukou deleted the prefer-multi-phase-i branch June 13, 2025 14:39
miss-islington pushed a commit to miss-islington/cpython that referenced this pull request Jun 13, 2025
@encukou@AA-Turner
@StanFromIreland@hugovk@miss-islington
pythongh-134160: Split extension module init from PyModule docs; emph…
1f7a3ff
…asize multi-phase init (pythonGH-135126)
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.)
(cherry picked from commit f4bc3a9)
Co-authored-by: Petr Viktorin <encukou@gmail.com>
Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com>
Co-authored-by: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com>
Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>
@bedevere-app

bedevere-appBot commented Jun 13, 2025

Copy link
Copy Markdown

GH-135470 is a backport of this pull request to the 3.14 branch.

@bedevere-appbedevere-appBot removed the needs backport to 3.14 bugs and security fixes label Jun 13, 2025
hugovk added a commit that referenced this pull request Jun 16, 2025
@miss-islington@encukou
@AA-Turner@StanFromIreland@hugovk
[3.14]gh-134160: Split extension module init from PyModule docs; emp…
0e0ad7b
…hasize multi-phase init (GH-135126) (#135470)
Co-authored-by: Petr Viktorin <encukou@gmail.com>
Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com>
Co-authored-by: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com>
Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>
lkollar pushed a commit to lkollar/cpython that referenced this pull request Jun 19, 2025
@encukou@AA-Turner
@StanFromIreland@hugovk@lkollar
pythongh-134160: Split extension module init from PyModule docs; emph…
807196f
…asize multi-phase init (pythonGH-135126)
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 <9087854+AA-Turner@users.noreply.github.com>
Co-authored-by: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com>
Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>
@encukouencukou mentioned this pull request Jul 9, 2025
Merged
Pranjal095 pushed a commit to Pranjal095/cpython that referenced this pull request Jul 12, 2025
@encukou@AA-Turner
@StanFromIreland@hugovk@Pranjal095
pythongh-134160: Split extension module init from PyModule docs; emph…
289f36b
…asize multi-phase init (pythonGH-135126)
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 <9087854+AA-Turner@users.noreply.github.com>
Co-authored-by: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com>
Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>
taegyunkim pushed a commit to taegyunkim/cpython that referenced this pull request Aug 4, 2025
@encukou@AA-Turner
@StanFromIreland@hugovk@taegyunkim
pythongh-134160: Split extension module init from PyModule docs; emph…
6edcbba
…asize multi-phase init (pythonGH-135126)
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 <9087854+AA-Turner@users.noreply.github.com>
Co-authored-by: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com>
Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>
Agent-Hellboy pushed a commit to Agent-Hellboy/cpython that referenced this pull request Aug 19, 2025
@encukou@AA-Turner
@StanFromIreland@hugovk@Agent-Hellboy
pythongh-134160: Split extension module init from PyModule docs; emph…
57e1f84
…asize multi-phase init (pythonGH-135126)
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 <9087854+AA-Turner@users.noreply.github.com>
Co-authored-by: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com>
Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>
Sign up for freeto join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@StanFromIrelandStanFromIrelandStanFromIreland left review comments
@hugovkhugovkhugovk approved these changes
@AA-TurnerAA-TurnerAwaiting requested review from AA-Turner
@ericsnowcurrentlyericsnowcurrentlyAwaiting requested review from ericsnowcurrentlyericsnowcurrently is a code owner

Assignees

No one assigned

Labels

skip news

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

3 participants

@encukou@hugovk@StanFromIreland