gh-134160: Start "Extending and embedding" with a Diataxis-style tutorial#142314
gh-134160: Start "Extending and embedding" with a Diataxis-style tutorial#142314encukou merged 25 commits into
Conversation
Sorry, something went wrong.
Co-authored-by: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com> Co-authored-by: Éric <merwok@netwok.org>
|
I've changed things so the first compilation is after adding |
Sorry, something went wrong.
|
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: I put notes on using other tools in an appendix. |
Sorry, something went wrong.
|
As a big proponent of meson-python IMO it's a great choice for this. |
Sorry, something went wrong.
ZeroIntensity
left a comment
ZeroIntensity
left a comment
There was a problem hiding this comment.
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.
Co-authored-by: Daniele Nicolodi <daniele@grinta.net> Co-authored-by: Peter Bierma <zintensitydev@gmail.com>
ZeroIntensity
left a comment
ZeroIntensity
left a comment
There was a problem hiding this comment.
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.
Co-authored-by: Peter Bierma <zintensitydev@gmail.com>
|
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 :) |
Sorry, something went wrong.
ZeroIntensity
left a comment
ZeroIntensity
left a comment
There was a problem hiding this comment.
I don't have any more complaints, LGTM!
Sorry, something went wrong.
encukou
merged commit 049c252
into
python:main
Dec 19, 2025
…e tutorial (pythonGH-142314) Co-authored-by: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com> Co-authored-by: Éric <merwok@netwok.org> Co-authored-by: Daniele Nicolodi <daniele@grinta.net> Co-authored-by: Peter Bierma <zintensitydev@gmail.com>
Reviewers
+1 more reviewer
6 participants
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).
📚 Documentation preview 📚: https://cpython-previews--142314.org.readthedocs.build/