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: Start "Extending and embedding" with a Diataxis-style tutorial by encukou · Pull Request #142314 · python/cpython

Conversation

@encukou

@encukou encukou commented Dec 5, 2025 •
edited by github-actions Bot
Loading

Uh oh!

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

Copy link
Copy Markdown
Member

The "Extending and embedding" section of the docs starts with a "tutorial", which is now outdated (it uses soft-deprecated API), but it also doesn't quite work as a tutorial (in the Diátaxis sense).

This PR pulls out the bits needed for a simple extension module: it's as simple as it can get to expose a C function. Topics that need lengthy explanation are left out (this includes crucial ones like refcounting & error handling, put also modern things like ABI info or free-threading support).
The code is updated to modern, non-deprecated API -- specifically, PEP 793's PyModExport.

The remainder of the existing chapter is renamed to "Using the C API: Assorted topics", to mirror the later chapter “Defining Extension Types: Assorted Topics”. This title was somewhat fitting even without the tutorial part taken out.
Care is taken to not remove any information, unless it's duplicated or no longer relevant. An “assorted topics” section works nicely here.

It would be nice to pull more bits out into dedicated explanation or tutorial pages; that's out of scope for this PR.

I apologize for any typos; I found reviewers are much better at finding them than I am (especially after I've been rewriting drafts for days).

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

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

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
edgarrmondragon reacted with heart emoji
All reactions
  • ❤️ 1 reaction
encukou added 7 commits December 5, 2025 17:29
@encukou
New first chapter of a C API tutorial
4d31b9a
@encukou
Reword more
4c2b982
@encukou
Start from the beginning
1525795
@encukou
TMP
dc844dd
@encukou
Full draft
32ae620
@encukou
Ruthlessly miminise explanation
13d5efa 
See: https://diataxis.fr/tutorials/#ruthlessly-minimise-explanation
@encukou
Re-add some reference tragets
7f1014e
@encukou encukou added the docs Documentation in the Doc dir label Dec 5, 2025
@github-project-automation github-project-automation Bot added this to Docs PRs Dec 5, 2025
@github-project-automation github-project-automation Bot moved this to Todo in Docs PRs Dec 5, 2025
@bedevere-app bedevere-app Bot added the awaiting core review label Dec 5, 2025
@bedevere-app bedevere-app Bot mentioned this pull request Dec 5, 2025
Docs Examples Focus on Outdated Single-Phase Init Modules and Static Types #134160
Open
@encukou
Typo fix
4c61bf4
merwok
merwok reviewed Dec 5, 2025
View reviewed changes
Comment thread Doc/extending/first-extension-module.rst Resolved

Uh oh!

There was an error while loading. Please reload this page.
merwok
merwok reviewed Dec 5, 2025
View reviewed changes
Comment thread Doc/extending/first-extension-module.rst Resolved

Uh oh!

There was an error while loading. Please reload this page.
merwok
merwok reviewed Dec 5, 2025
View reviewed changes
Comment thread Doc/extending/first-extension-module.rst Resolved

Uh oh!

There was an error while loading. Please reload this page.
merwok
merwok reviewed Dec 5, 2025
View reviewed changes
Comment thread Doc/extending/first-extension-module.rst Resolved

Uh oh!

There was an error while loading. Please reload this page.
merwok
merwok reviewed Dec 5, 2025
View reviewed changes
Comment thread Doc/extending/first-extension-module.rst Resolved

Uh oh!

There was an error while loading. Please reload this page.
merwok
merwok reviewed Dec 5, 2025
View reviewed changes
Comment thread Doc/extending/index.rst
Comment on lines +48 to +54
first-extension-module.rst
extending.rst
newtypes_tutorial.rst
newtypes.rst
building.rst
windows.rst
embedding.rst

@merwok merwok Dec 5, 2025

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.

Suggested change
first-extension-module.rst
extending.rst
newtypes_tutorial.rst
newtypes.rst
building.rst
windows.rst
embedding.rst
first-extension-module
extending
newtypes_tutorial
newtypes
building
windows
embedding

Sorry, something went wrong.

Uh oh!

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

@encukou encukou Dec 10, 2025

Copy link
Copy Markdown
Member Author

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.

Why change this? All of CPython's toctrees have the .rst suffixes.

Sorry, something went wrong.

Uh oh!

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

@merwok merwok Dec 12, 2025

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.

It’s not required, so is a little cleaner (like we don’t have to do import './module.py'), but maybe Sphinx didn’t support that when it was first created and now that’s the style we have.

Sorry, something went wrong.

Uh oh!

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

@encukou encukou Dec 16, 2025

Copy link
Copy Markdown
Member Author

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.

Oh. Makes sense!
But I think the first such change should be its own PR, so it's easily revertable if anything goes wrong. This PR is big enough on its own.

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
All reactions
merwok
merwok reviewed Dec 5, 2025
View reviewed changes
Comment thread Doc/extending/first-extension-module.rst Resolved

Uh oh!

There was an error while loading. Please reload this page.
merwok
merwok reviewed Dec 5, 2025
View reviewed changes
Comment thread Doc/extending/first-extension-module.rst Resolved

Uh oh!

There was an error while loading. Please reload this page.
StanFromIreland
StanFromIreland reviewed Dec 5, 2025
View reviewed changes
Comment thread Doc/extending/first-extension-module.rst Resolved

Uh oh!

There was an error while loading. Please reload this page.
encukou and others added 4 commits December 10, 2025 11:32
@encukou @StanFromIreland @merwok
Apply suggestions from code review
0d91185 
Co-authored-by: Stan Ulbrych <[email protected]>
Co-authored-by: Éric <[email protected]>
@encukou
Address more review comments
2902a8b
@encukou
tart with the headers
276d8cd
@encukou
str->bytes is *encoding*
2306fcd
@encukou

encukou commented Dec 10, 2025

Copy link
Copy Markdown
Member Author

I've changed things so the first compilation is after adding #includes. Not finding Python.h headers is a reasonable failure mode, and it makes sense to debug that together with any other tool issues.
All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
encukou added 3 commits December 12, 2025 14:03
@encukou
Merge in the main branch
a312862
@encukou
Link to the list of recommended tools in the Python Packaging User Guide
ae85969
@encukou
Fix line highlight
27af529
@encukou
Move signature check up
7069412
@encukou encukou added the skip news label Dec 12, 2025
encukou added 2 commits December 12, 2025 16:22
@encukou
Use meson-python
54e2999
@encukou
Use 'sampleproject' for the project name
f92562c
@encukou

encukou commented Dec 12, 2025

Copy link
Copy Markdown
Member Author

The “now run your build tool” section stood out as the most no-tutorial-i part of the tutorial, so I tried the tools from the PyPA recommendation list and chose the most straightforward one: meson-python.
(It'd be setuptools if it weren't for pypa/distutils#387)

I put notes on using other tools in an appendix.
All reactions

Sorry, something went wrong.

Uh oh!

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

ngoldbaum commented Dec 12, 2025

Copy link
Copy Markdown
Contributor

As a big proponent of meson-python IMO it's a great choice for this.
All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
merwok
merwok reviewed Dec 13, 2025
View reviewed changes
Comment thread Doc/extending/first-extension-module.rst Outdated
.. tip::

If you don't have ``pip`` installed, run ``python -m ensurepip``,
preferably in a :mod:`virtual environment <venv>`.

@merwok merwok Dec 13, 2025

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.

Do people actually need to run ensurepip if they have run python -m venv .venv ?

This tutorial could show the venv commands directly (and avoid ensurepip step) instead of referring to them.

Sorry, something went wrong.

Uh oh!

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

@encukou encukou Dec 16, 2025

Copy link
Copy Markdown
Member Author

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.

I added “You need to be able to install Python packages” to the intro, leaving exact steps for setting that up out of scope here.
Does that work?

Sorry, something went wrong.

Uh oh!

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

@merwok merwok Dec 19, 2025

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.

With a link to ensurepip docs, or Python setup and usage (if that includes notes about venv/pip)?

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
All reactions
merwok
merwok reviewed Dec 13, 2025
View reviewed changes
Comment thread Doc/extending/first-extension-module.rst Outdated
preferably in a :mod:`virtual environment <venv>`.
You can also use another tool that can build and install
``pyproject.toml``-based projects, like
`uv <https://docs.astral.sh/uv/>`_ (``uv pip install .``).

@merwok merwok Dec 13, 2025

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.

This note seems to contradict the intent of not providing options in a tutorial 🙂

Sorry, something went wrong.

Uh oh!

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

@encukou encukou Dec 16, 2025

Copy link
Copy Markdown
Member Author

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.

This is partly setup you're expected to have before starting, and part troubleshooting advice.

I added it to the introduction, and made this note smaller. Does that work?

Sorry, something went wrong.

Uh oh!

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

@merwok merwok Dec 17, 2025

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.

Will check!

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
All reactions
ZeroIntensity
ZeroIntensity reviewed Dec 15, 2025
View reviewed changes

@ZeroIntensity ZeroIntensity 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.

Yay, thanks for doing this! I'm excited to finally see a better tutorial.

I tried to avoid being overly nitpicky in my review.

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
encukou reacted with heart emoji
All reactions
  • ❤️ 1 reaction
Comment thread Doc/extending/extending.rst Resolved

Uh oh!

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

Uh oh!

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

Uh oh!

There was an error while loading. Please reload this page.
Comment thread Doc/extending/first-extension-module.rst Resolved

Uh oh!

There was an error while loading. Please reload this page.
Comment thread Doc/extending/first-extension-module.rst Resolved

Uh oh!

There was an error while loading. Please reload this page.
Comment thread Doc/extending/first-extension-module.rst Resolved

Uh oh!

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

Uh oh!

There was an error while loading. Please reload this page.
Comment thread Doc/extending/first-extension-module.rst Resolved

Uh oh!

There was an error while loading. Please reload this page.
Comment thread Doc/extending/first-extension-module.rst Resolved

Uh oh!

There was an error while loading. Please reload this page.
Comment thread Doc/extending/first-extension-module.rst Resolved

Uh oh!

There was an error while loading. Please reload this page.
dnicolodi
dnicolodi reviewed Dec 16, 2025
View reviewed changes
Comment thread Doc/extending/first-extension-module.rst Resolved

Uh oh!

There was an error while loading. Please reload this page.
encukou and others added 4 commits December 16, 2025 14:18
@encukou @dnicolodi @ZeroIntensity
Apply suggestions from code review
a17458a 
Co-authored-by: Daniele Nicolodi <[email protected]>
Co-authored-by: Peter Bierma <[email protected]>
@encukou
Address more review
638d2a0
@encukou
Use :c:func:system, not system
2fc1511
@encukou
Expand the explanation of Py_RETURN_NONE
24c6eaa
ngoldbaum
ngoldbaum reviewed Dec 16, 2025
View reviewed changes
Comment thread Doc/includes/capi-extension/spammodule-01.c Resolved

Uh oh!

There was an error while loading. Please reload this page.
encukou added 2 commits December 17, 2025 11:37
@encukou
Merge in the main branch
8e622ac
@encukou
Add a comment for <stdlib.h>
772152c
ZeroIntensity
ZeroIntensity reviewed Dec 17, 2025
View reviewed changes

@ZeroIntensity ZeroIntensity 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.

Mostly just typos left. I left a few minor wording suggestions, so feel free to reject those if you want to.

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
All reactions
Comment thread Doc/extending/first-extension-module.rst Resolved

Uh oh!

There was an error while loading. Please reload this page.
Comment thread Doc/extending/first-extension-module.rst Resolved

Uh oh!

There was an error while loading. Please reload this page.
Comment thread Doc/extending/first-extension-module.rst Resolved

Uh oh!

There was an error while loading. Please reload this page.
Comment thread Doc/extending/first-extension-module.rst Resolved

Uh oh!

There was an error while loading. Please reload this page.
Comment thread Doc/extending/first-extension-module.rst
Comment on lines +187 to +188
extension.
Unlike Python, C has an explicit compilation step.

@ZeroIntensity ZeroIntensity Dec 17, 2025

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.

These two sentences feel very related.

Suggested change
extension.
Unlike Python, C has an explicit compilation step.
extension, because unlike Python, C has an explicit compilation step.

Sorry, something went wrong.

Uh oh!

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

@merwok merwok Dec 17, 2025

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.

Juxtaposition is a valid construct! 🙂

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
encukou reacted with thumbs up emoji
All reactions
  • 👍 1 reaction
Comment thread Doc/extending/first-extension-module.rst Resolved

Uh oh!

There was an error while loading. Please reload this page.
Comment thread Doc/extending/first-extension-module.rst Resolved

Uh oh!

There was an error while loading. Please reload this page.
Comment thread Doc/extending/first-extension-module.rst Resolved

Uh oh!

There was an error while loading. Please reload this page.
Comment thread Doc/extending/first-extension-module.rst Resolved

Uh oh!

There was an error while loading. Please reload this page.
Comment thread Doc/extending/first-extension-module.rst Resolved

Uh oh!

There was an error while loading. Please reload this page.
@encukou @ZeroIntensity
Apply suggestions from code review
72fd39f 
Co-authored-by: Peter Bierma <[email protected]>
@encukou

encukou commented Dec 19, 2025

Copy link
Copy Markdown
Member Author

Thank you for those! I must admit I'm blind to typos at this point...

I'll merge soon, but I'm happy to take more suggestions. Docs are never done :)
All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
ZeroIntensity
ZeroIntensity approved these changes Dec 19, 2025
View reviewed changes

@ZeroIntensity ZeroIntensity 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.

I don't have any more complaints, LGTM!

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
All reactions
@bedevere-app bedevere-app Bot added awaiting merge and removed awaiting core review labels Dec 19, 2025
@encukou
encukou merged commit 049c252 into python:main Dec 19, 2025
32 checks passed

Uh oh!

There was an error while loading. Please reload this page.
@github-project-automation github-project-automation Bot moved this from Todo to Done in Docs PRs Dec 19, 2025
@bedevere-app bedevere-app Bot removed the awaiting merge label Dec 19, 2025
@encukou
encukou deleted the modexport-tutorial branch December 19, 2025 16:48
@encukou encukou mentioned this pull request Dec 19, 2025
Implement PEP 793 – PyModExport #140550
Open
19 of 25 tasks
cocolato pushed a commit to cocolato/cpython that referenced this pull request Dec 22, 2025
@encukou @StanFromIreland
@merwok @dnicolodi @ZeroIntensity @cocolato
pythongh-134160: Start "Extending and embedding" with a Diataxis-styl…
ca1dc21 
…e tutorial (pythonGH-142314)

Co-authored-by: Stan Ulbrych <[email protected]>
Co-authored-by: Éric <[email protected]>
Co-authored-by: Daniele Nicolodi <[email protected]>
Co-authored-by: Peter Bierma <[email protected]>
@rgommers rgommers mentioned this pull request Nov 10, 2026
Expand documentation on building for the Limited API pypa/packaging.python.org#1376
Open
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@merwok merwok merwok left review comments
@ngoldbaum ngoldbaum ngoldbaum left review comments
@StanFromIreland StanFromIreland StanFromIreland left review comments
@ZeroIntensity ZeroIntensity ZeroIntensity approved these changes
+1 more reviewer
@dnicolodi dnicolodi dnicolodi left review comments
Reviewers whose approvals may not affect merge requirements

Uh oh!

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

Assignees

No one assigned

Labels

docs Documentation in the Doc dir skip news

Projects

Docs PRs
Status: Done

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.

6 participants

@encukou @ngoldbaum @merwok @dnicolodi @ZeroIntensity @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.