gh-133678: Document C API third party tools (#134526)

Co-authored-by: Petr Viktorin <encukou@gmail.com>
Co-authored-by: Steve Dower <steve.dower@python.org>
This commit is contained in:
Victor Stinner 2025-05-27 17:38:30 +02:00 committed by GitHub
parent f6f4e8a662
commit c3c88064f5
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
4 changed files with 46 additions and 35 deletions

View file

@ -838,3 +838,41 @@ after every statement run by the interpreter.)
Please refer to :file:`Misc/SpecialBuilds.txt` in the Python source distribution
for more detailed information.
.. _c-api-tools:
Recommended third party tools
=============================
The following third party tools offer both simpler and more sophisticated
approaches to creating C, C++ and Rust extensions for Python:
* `Cython <https://cython.org/>`_
* `cffi <https://cffi.readthedocs.io>`_
* `HPy <https://hpyproject.org/>`_
* `nanobind <https://github.com/wjakob/nanobind>`_ (C++)
* `Numba <https://numba.pydata.org/>`_
* `pybind11 <https://pybind11.readthedocs.io/>`_ (C++)
* `PyO3 <https://pyo3.rs/>`_ (Rust)
* `SWIG <https://www.swig.org>`_
Using tools such as these can help avoid writing code that is tightly bound to
a particular version of CPython, avoid reference counting errors, and focus
more on your own code than on using the CPython API. In general, new versions
of Python can be supported by updating the tool, and your code will often use
newer and more efficient APIs automatically. Some tools also support compiling
for other implementations of Python from a single set of sources.
These projects are not supported by the same people who maintain Python, and
issues need to be raised with the projects directly. Remember to check that the
project is still maintained and supported, as the list above may become
outdated.
.. seealso::
`Python Packaging User Guide: Binary Extensions <https://packaging.python.org/guides/packaging-binary-extensions/>`_
The Python Packaging User Guide not only covers several available
tools that simplify the creation of binary extensions, but also
discusses the various reasons why creating an extension module may be
desirable in the first place.

View file

@ -26,19 +26,9 @@ Recommended third party tools
=============================
This guide only covers the basic tools for creating extensions provided
as part of this version of CPython. Third party tools like
`Cython <https://cython.org/>`_, `cffi <https://cffi.readthedocs.io>`_,
`SWIG <https://www.swig.org>`_ and `Numba <https://numba.pydata.org/>`_
offer both simpler and more sophisticated approaches to creating C and C++
extensions for Python.
.. seealso::
`Python Packaging User Guide: Binary Extensions <https://packaging.python.org/guides/packaging-binary-extensions/>`_
The Python Packaging User Guide not only covers several available
tools that simplify the creation of binary extensions, but also
discusses the various reasons why creating an extension module may be
desirable in the first place.
as part of this version of CPython. Some :ref:`third party tools
<c-api-tools>` offer both simpler and more sophisticated approaches to creating
C and C++ extensions for Python.
Creating extensions without third party tools

View file

@ -37,24 +37,9 @@ Writing C is hard; are there any alternatives?
----------------------------------------------
There are a number of alternatives to writing your own C extensions, depending
on what you're trying to do.
.. XXX make sure these all work
`Cython <https://cython.org>`_ and its relative `Pyrex
<https://www.csse.canterbury.ac.nz/greg.ewing/python/Pyrex/>`_ are compilers
that accept a slightly modified form of Python and generate the corresponding
C code. Cython and Pyrex make it possible to write an extension without having
to learn Python's C API.
If you need to interface to some C or C++ library for which no Python extension
currently exists, you can try wrapping the library's data types and functions
with a tool such as `SWIG <https://www.swig.org>`_. `SIP
<https://github.com/Python-SIP/sip>`__, `CXX
<https://cxx.sourceforge.net/>`_ `Boost
<https://www.boost.org/libs/python/doc/index.html>`_, or `Weave
<https://github.com/scipy/weave>`_ are also
alternatives for wrapping C++ libraries.
on what you're trying to do. :ref:`Recommended third party tools <c-api-tools>`
offer both simpler and more sophisticated approaches to creating C and C++
extensions for Python.
How can I execute arbitrary Python statements from C?

View file

@ -14,13 +14,11 @@ We recommend the following resources for porting extension modules to Python 3:
module.
* The `Porting guide`_ from the *py3c* project provides opinionated
suggestions with supporting code.
* The `Cython`_ and `CFFI`_ libraries offer abstractions over
Python's C API.
* :ref:`Recommended third party tools <c-api-tools>` offer abstractions over
the Python's C API.
Extensions generally need to be re-written to use one of them,
but the library then handles differences between various Python
versions and implementations.
.. _Migrating C extensions: http://python3porting.com/cextensions.html
.. _Porting guide: https://py3c.readthedocs.io/en/latest/guide.html
.. _Cython: https://cython.org/
.. _CFFI: https://cffi.readthedocs.io/en/latest/