mirror of
https://github.com/python/cpython.git
synced 2025-07-07 11:25:30 +00:00
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:
parent
f6f4e8a662
commit
c3c88064f5
4 changed files with 46 additions and 35 deletions
|
@ -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.
|
||||
|
|
|
@ -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
|
||||
|
|
|
@ -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?
|
||||
|
|
|
@ -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/
|
||||
|
|
Loading…
Add table
Add a link
Reference in a new issue