GV

GeezerVison

The World Wide Web, restored to 800 pixels of glory.

Home|About|Gaming cabinet|Archives|How it works|Starter sites

On this site

  • Sign in
  • ActionsCI/CD and automation
  • CodespacesCloud development environments
  • All Features
  • Documentation
  • Training
  • Certifications
  • Build with Copilot
  • Customize Copilot
  • Integrations
  • Trending repos
  • GitHub Sponsors
  • Developer articles
  • Enterprises

This view

  • Original page
  • New address

GeezerVison is showing github.com — gh-134160: Split extension module init from PyModule docs; emphasize multi-phase init by encukou · Pull Request #135126 · python/cpython

Conversation

@encukou

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

Uh oh!

There was an error while loading. Please reload this page.

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.)

  • Issue: Docs Examples Focus on Outdated Single-Phase Init Modules and Static Types #134160

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

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
All reactions
@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 <[email protected]>
@encukou
encukou requested a review from AA-Turner June 4, 2025 12:34
@encukou
encukou requested a review from ericsnowcurrently as a code owner June 4, 2025 12:34
@bedevere-app bedevere-app Bot added the awaiting core review label Jun 4, 2025
@bedevere-app bedevere-app Bot mentioned this pull request Jun 4, 2025
Docs Examples Focus on Outdated Single-Phase Init Modules and Static Types #134160
Open
@encukou encukou mentioned this pull request Jun 4, 2025
GH-134160: Prefer multi-phase initialisation in docs #134764
Closed
@encukou encukou added the skip news label Jun 4, 2025
StanFromIreland
StanFromIreland reviewed Jun 4, 2025
View reviewed changes

@StanFromIreland StanFromIreland left a comment •
edited
Loading

Uh oh!

There was an error while loading. Please reload this page.

Copy link
Copy Markdown
Member

There was a problem hiding this 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.

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
All reactions
Comment thread Doc/c-api/extension-modules.rst Resolved

Uh oh!

There was an error while loading. Please reload this page.
Comment thread Doc/c-api/extension-modules.rst Resolved

Uh oh!

There was an error while loading. Please reload this page.
Comment thread Doc/c-api/extension-modules.rst Resolved

Uh oh!

There was an error while loading. Please reload this page.
Comment thread Doc/c-api/extension-modules.rst Resolved

Uh oh!

There was an error while loading. Please reload this page.
@encukou @StanFromIreland
Apply suggestions from code review
e706afd 
Co-authored-by: Stan Ulbrych <[email protected]>
@encukou

encukou commented Jun 5, 2025

Copy link
Copy Markdown
Member Author

Thank you!
StanFromIreland reacted with thumbs up emoji
All reactions
  • 👍 1 reaction

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
@encukou
Single-phase init shares objects across interpreters
fe2f5b6
@encukou encukou mentioned this pull request Jun 10, 2025
PEP 489: Fix syntax highlighting python/peps#4456
Merged
hugovk
hugovk approved these changes Jun 11, 2025
View reviewed changes

@hugovk hugovk left a comment

Copy link
Copy Markdown
Member

There was a problem hiding this comment.

Choose a reason for hiding this comment

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

Thank you!

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
All reactions
Comment thread Doc/c-api/extension-modules.rst Resolved

Uh oh!

There was an error while loading. Please reload this page.
Comment thread Doc/c-api/extension-modules.rst Resolved

Uh oh!

There was an error while loading. Please reload this page.
Comment thread Doc/c-api/extension-modules.rst Resolved

Uh oh!

There was an error while loading. Please reload this page.
Comment thread Doc/c-api/extension-modules.rst Resolved

Uh oh!

There was an error while loading. Please reload this page.
Comment thread Doc/c-api/intro.rst Resolved

Uh oh!

There was an error while loading. Please reload this page.
Comment thread Doc/extending/building.rst Resolved

Uh oh!

There was an error while loading. Please reload this page.
@bedevere-app bedevere-app Bot added awaiting merge and removed awaiting core review labels Jun 11, 2025
@encukou @hugovk
Apply suggestions from code review
a53f207 
Co-authored-by: Hugo van Kemenade <[email protected]>
StanFromIreland
StanFromIreland reviewed Jun 12, 2025
View reviewed changes
Comment thread Doc/extending/building.rst Resolved

Uh oh!

There was an error while loading. Please reload this page.
@encukou @StanFromIreland
Update Setuptools URL
5380348 
Co-authored-by: Stan Ulbrych <[email protected]>
@encukou encukou added the needs backport to 3.14 bugs and security fixes label Jun 13, 2025
@encukou
encukou merged commit f4bc3a9 into python:main Jun 13, 2025
@bedevere-app bedevere-app Bot removed the awaiting merge label Jun 13, 2025
@miss-islington-app

miss-islington-app Bot 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!
All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
@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 <[email protected]>
Co-authored-by: Adam Turner <[email protected]>
Co-authored-by: Stan Ulbrych <[email protected]>
Co-authored-by: Hugo van Kemenade <[email protected]>
@bedevere-app

bedevere-app Bot commented Jun 13, 2025

Copy link
Copy Markdown

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

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
@bedevere-app bedevere-app Bot 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 <[email protected]>
Co-authored-by: Adam Turner <[email protected]>
Co-authored-by: Stan Ulbrych <[email protected]>
Co-authored-by: Hugo van Kemenade <[email protected]>
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 <[email protected]>
Co-authored-by: Stan Ulbrych <[email protected]>
Co-authored-by: Hugo van Kemenade <[email protected]>
@encukou encukou mentioned this pull request Jul 9, 2025
gh-121028: Soft-deprecate sys.api_version #136463
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 <[email protected]>
Co-authored-by: Stan Ulbrych <[email protected]>
Co-authored-by: Hugo van Kemenade <[email protected]>
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 <[email protected]>
Co-authored-by: Stan Ulbrych <[email protected]>
Co-authored-by: Hugo van Kemenade <[email protected]>
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 <[email protected]>
Co-authored-by: Stan Ulbrych <[email protected]>
Co-authored-by: Hugo van Kemenade <[email protected]>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@StanFromIreland StanFromIreland StanFromIreland left review comments
@hugovk hugovk hugovk approved these changes
@AA-Turner AA-Turner Awaiting requested review from AA-Turner
@ericsnowcurrently ericsnowcurrently Awaiting requested review from ericsnowcurrently ericsnowcurrently is a code owner

Uh oh!

There was an error while loading. Please reload this page.

Assignees

No one assigned

Labels

skip news

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

Uh oh!

There was an error while loading. Please reload this page.

3 participants

@encukou @hugovk @StanFromIreland
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
You are visitor 01402503 — GeezerVison does not store the pages you look up.
Best viewed with Netscape Navigator 4.7 or Internet Explorer 6 at 800×600. No cookies required.