gh-134160: Start "Extending and embedding" with a Diataxis-style tutorial #142314
Conversation
|
|
||
| .. note:: | ||
|
|
||
| This tutorial uses API that was added in CPython 3.15. |
| If you don't want to use a tool, you can try to run your compiler directly. | ||
| The following command should work for many flavors of Linux, and generate | ||
| a ``spam.so`` file that you need to put in a directory | ||
| in :py:attr:`sys.path`: |
| Be sure to put this, and any other standard library includes, *after* | ||
| :file:`Python.h`. | ||
| On some systems, Python may define some pre-processor definitions | ||
| that affect the standard headers. |
There was a problem hiding this comment.
This is a useful note, but not sure about the tip just below.
It’s giving details that are not needed for this tuto, about something that people shouldn’t do, and already documented in c-api/intro
| } | ||
| Compile and load the module again. | ||
| You should get a different error this time. |
There was a problem hiding this comment.
Should this say to restart the Python interpreter?
(I don’t know if the previous non-loading module will be cached in sys.modules)
| >>> import spam | ||
| >>> print(spam.system) | ||
| <built-in function system> | ||
| >>> print(spam.system('whoami')) |
There was a problem hiding this comment.
Doesn’t this still print the output of whoami, then the return value?
(confusing IMHO – but the example should match what people will see)
| 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 |
|
|
||
| To call it, replace the ``Py_RETURN_NONE`` with the following 3 lines: | ||
|
|
||
| .. this could be a one-liner, but we want to how the data types here. |
There was a problem hiding this comment.
| .. this could be a one-liner, but we want to how the data types here. | |
| .. this could be a one-liner, but we want to show the data types here |
| In order to use the information in it, we will need | ||
| to convert it to a C value --- in this case, a C string (``const char *``). | ||
|
|
||
| There's a slight type mismatch here: Python's :c:type:`str` objects store |
There was a problem hiding this comment.
| There's a slight type mismatch here: Python's :c:type:`str` objects store | |
| There's a slight type mismatch here: Python's :type:`str` objects store |
There was a problem hiding this comment.
Will that work? It should be :class:`str` , no?
| There's a slight type mismatch here: Python's :c:type:`str` objects store | |
| There's a slight type mismatch here: Python's :class:`str` objects store |
There was a problem hiding this comment.
Probably! (I remembered the python domain defines class, func, meth, data so it makes sense type is not also there, as it was synonym with class before we got static typing)
|
|
||
| .. note:: | ||
|
|
||
| Using a third-party build tool is heavily recommended, as in will take |
There was a problem hiding this comment.
| Using a third-party build tool is heavily recommended, as in will take | |
| Using a third-party build tool is heavily recommended, as it will take |
3 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/