gh-134160: Start "Extending and embedding" with a Diataxis-style tutorial #142314
Conversation
| first-extension-module.rst | ||
| extending.rst | ||
| newtypes_tutorial.rst | ||
| newtypes.rst | ||
| building.rst | ||
| windows.rst | ||
| embedding.rst |
There was a problem hiding this comment.
| 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 |
There was a problem hiding this comment.
Why change this? All of CPython's toctrees have the .rst suffixes.
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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.
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 |
|
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. |
|
As a big proponent of meson-python IMO it's a great choice for this. |
| .. tip:: | ||
|
|
||
| If you don't have ``pip`` installed, run ``python -m ensurepip``, | ||
| preferably in a :mod:`virtual environment <venv>`. |
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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?
There was a problem hiding this comment.
With a link to ensurepip docs, or Python setup and usage (if that includes notes about venv/pip)?
| 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 .``). |
There was a problem hiding this comment.
This note seems to contradict the intent of not providing options in a tutorial 🙂
There was a problem hiding this comment.
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?
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.
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.
| extension. | ||
| Unlike Python, C has an explicit compilation step. |
There was a problem hiding this comment.
These two sentences feel very related.
| extension. | |
| Unlike Python, C has an explicit compilation step. | |
| extension, because unlike Python, C has an explicit compilation step. |
There was a problem hiding this comment.
Juxtaposition is a valid construct! 🙂
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 :) |
ZeroIntensity
left a comment
ZeroIntensity
left a comment
There was a problem hiding this comment.
I don't have any more complaints, LGTM!
…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>
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/