From 45b3c5f3fc9c13cb237c9e20a1649cb6f4bccb4c Mon Sep 17 00:00:00 2001 From: Victor Stinner Date: Thu, 22 May 2025 18:41:06 +0200 Subject: [PATCH 1/4] gh-133678: Document C API third party tools --- Doc/c-api/intro.rst | 41 +++++++++++++++++++++++++++++++++++++++++ Doc/extending/index.rst | 16 +++------------- Doc/faq/extending.rst | 21 +++------------------ Doc/howto/cporting.rst | 6 ++---- 4 files changed, 49 insertions(+), 35 deletions(-) diff --git a/Doc/c-api/intro.rst b/Doc/c-api/intro.rst index 0c20ad17194eb6..20a7d8664a33fc 100644 --- a/Doc/c-api/intro.rst +++ b/Doc/c-api/intro.rst @@ -838,3 +838,44 @@ 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 and C++ extensions for Python: + +* `Cython `_ +* `cffi `_ +* `HPy `_ +* `nanobind `_ (C++) +* `Numba `_ +* `pybind11 `_ (C++) +* `PyO3 `_ (Rust) +* `SWIG `_ + +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. + +Directly coding against the CPython C API should, in most cases, be your last +resort rather than the first. + +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 `_ + 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. diff --git a/Doc/extending/index.rst b/Doc/extending/index.rst index 01b4df6d44acff..378cae646d58ed 100644 --- a/Doc/extending/index.rst +++ b/Doc/extending/index.rst @@ -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 `_, `cffi `_, -`SWIG `_ and `Numba `_ -offer both simpler and more sophisticated approaches to creating C and C++ -extensions for Python. - -.. seealso:: - - `Python Packaging User Guide: 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. :ref:`Recommended third party tools +` offer both simpler and more sophisticated approaches to creating +C and C++ extensions for Python. Creating extensions without third party tools diff --git a/Doc/faq/extending.rst b/Doc/faq/extending.rst index 3147fda7c37124..1d5abed2317b0c 100644 --- a/Doc/faq/extending.rst +++ b/Doc/faq/extending.rst @@ -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 `_ and its relative `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 `_. `SIP -`__, `CXX -`_ `Boost -`_, or `Weave -`_ are also -alternatives for wrapping C++ libraries. +on what you're trying to do. :ref:`Recommended third party 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? diff --git a/Doc/howto/cporting.rst b/Doc/howto/cporting.rst index 7773620b40b973..cf857aed0425ec 100644 --- a/Doc/howto/cporting.rst +++ b/Doc/howto/cporting.rst @@ -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 ` 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/ From a1b5be2ce60caf33a159630a08992d6c8fe66d2e Mon Sep 17 00:00:00 2001 From: Victor Stinner Date: Fri, 23 May 2025 11:53:36 +0200 Subject: [PATCH 2/4] Update Doc/extending/index.rst Co-authored-by: Petr Viktorin --- Doc/extending/index.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/extending/index.rst b/Doc/extending/index.rst index 378cae646d58ed..2229501aaadc07 100644 --- a/Doc/extending/index.rst +++ b/Doc/extending/index.rst @@ -26,7 +26,7 @@ Recommended third party tools ============================= This guide only covers the basic tools for creating extensions provided -as part of this version of CPython. :ref:`Recommended third party tools +as part of this version of CPython. Some :ref:`third party tools ` offer both simpler and more sophisticated approaches to creating C and C++ extensions for Python. From 6e09d8fa7e33e1af85ccf0d5dc7e1c4755be55dc Mon Sep 17 00:00:00 2001 From: Victor Stinner Date: Fri, 23 May 2025 11:53:49 +0200 Subject: [PATCH 3/4] Update Doc/c-api/intro.rst Co-authored-by: Petr Viktorin --- Doc/c-api/intro.rst | 3 --- 1 file changed, 3 deletions(-) diff --git a/Doc/c-api/intro.rst b/Doc/c-api/intro.rst index 20a7d8664a33fc..0fbd0b6bc28f12 100644 --- a/Doc/c-api/intro.rst +++ b/Doc/c-api/intro.rst @@ -864,9 +864,6 @@ 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. -Directly coding against the CPython C API should, in most cases, be your last -resort rather than the first. - 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 From 1b574edda18599150816941ff26379f200341578 Mon Sep 17 00:00:00 2001 From: Victor Stinner Date: Mon, 26 May 2025 16:01:19 +0200 Subject: [PATCH 4/4] Add Rust --- Doc/c-api/intro.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/c-api/intro.rst b/Doc/c-api/intro.rst index 0fbd0b6bc28f12..5dcfb4bc778b0e 100644 --- a/Doc/c-api/intro.rst +++ b/Doc/c-api/intro.rst @@ -846,7 +846,7 @@ Recommended third party tools ============================= The following third party tools offer both simpler and more sophisticated -approaches to creating C and C++ extensions for Python: +approaches to creating C, C++ and Rust extensions for Python: * `Cython `_ * `cffi `_