python · vstinner · May 8, 2025 · May 8, 2025 · May 8, 2025 · May 9, 2025
diff --git a/Doc/c-api/abstract.rst b/Doc/c-api/abstract.rst
@@ -6,6 +6,8 @@
 Abstract Objects Layer
 **********************
 
+.. c-api-tools-banner::
+
 The functions in this chapter interact with Python objects regardless of their
 type, or with wide classes of object types (e.g. all numerical types, or all
 sequence types).  When used on object types for which they do not apply, they

diff --git a/Doc/c-api/allocation.rst b/Doc/c-api/allocation.rst
@@ -5,6 +5,8 @@
 Allocating Objects on the Heap
 ==============================
 
+.. c-api-tools-banner::
+
 
 .. c:function:: PyObject* _PyObject_New(PyTypeObject *type)
 

diff --git a/Doc/c-api/apiabiversion.rst b/Doc/c-api/apiabiversion.rst
@@ -6,6 +6,7 @@
 API and ABI Versioning
 ***********************
 
+.. c-api-tools-banner::
 
 Build-time version constants
 ----------------------------

diff --git a/Doc/c-api/arg.rst b/Doc/c-api/arg.rst
@@ -5,6 +5,8 @@
 Parsing arguments and building values
 =====================================
 
+.. c-api-tools-banner::
+
 These functions are useful when creating your own extension functions and
 methods.  Additional information and examples are available in
 :ref:`extending-index`.

diff --git a/Doc/c-api/bool.rst b/Doc/c-api/bool.rst
@@ -5,6 +5,8 @@
 Boolean Objects
 ---------------
 
+.. c-api-tools-banner::
+
 Booleans in Python are implemented as a subclass of integers.  There are only
 two booleans, :c:data:`Py_False` and :c:data:`Py_True`.  As such, the normal
 creation and deletion functions don't apply to booleans.  The following macros

diff --git a/Doc/c-api/buffer.rst b/Doc/c-api/buffer.rst
@@ -14,6 +14,8 @@ Buffer Protocol
 .. sectionauthor:: Benjamin Peterson
 .. sectionauthor:: Stefan Krah
 
+.. c-api-tools-banner::
+
 
 Certain objects available in Python wrap access to an underlying memory
 array or *buffer*.  Such objects include the built-in :class:`bytes` and

diff --git a/Doc/c-api/bytearray.rst b/Doc/c-api/bytearray.rst
@@ -7,6 +7,8 @@ Byte Array Objects
 
 .. index:: pair: object; bytearray
 
+.. c-api-tools-banner::
+
 
 .. c:type:: PyByteArrayObject
 

diff --git a/Doc/c-api/bytes.rst b/Doc/c-api/bytes.rst
@@ -5,6 +5,8 @@
 Bytes Objects
 -------------
 
+.. c-api-tools-banner::
+
 These functions raise :exc:`TypeError` when expecting a bytes parameter and
 called with a non-bytes parameter.
 

diff --git a/Doc/c-api/call.rst b/Doc/c-api/call.rst
@@ -5,6 +5,8 @@
 Call Protocol
 =============
 
+.. c-api-tools-banner::
+
 CPython supports two different calling protocols:
 *tp_call* and vectorcall.
 

diff --git a/Doc/c-api/capsule.rst b/Doc/c-api/capsule.rst
@@ -7,6 +7,8 @@ Capsules
 
 .. index:: pair: object; Capsule
 
+.. c-api-tools-banner::
+
 Refer to :ref:`using-capsules` for more information on using these objects.
 
 .. versionadded:: 3.1

diff --git a/Doc/c-api/cell.rst b/Doc/c-api/cell.rst
@@ -5,6 +5,8 @@
 Cell Objects
 ------------
 
+.. c-api-tools-banner::
+
 "Cell" objects are used to implement variables referenced by multiple scopes.
 For each such variable, a cell object is created to store the value; the local
 variables of each stack frame that references the value contains a reference to

diff --git a/Doc/c-api/code.rst b/Doc/c-api/code.rst
@@ -9,6 +9,8 @@ Code Objects
 
 .. sectionauthor:: Jeffrey Yasskin <jyasskin@gmail.com>
 
+.. c-api-tools-banner::
+
 Code objects are a low-level detail of the CPython implementation.
 Each one represents a chunk of executable code that hasn't yet been
 bound into a function.

diff --git a/Doc/c-api/codec.rst b/Doc/c-api/codec.rst
@@ -3,6 +3,8 @@
 Codec registry and support functions
 ====================================
 
+.. c-api-tools-banner::
+
 .. c:function:: int PyCodec_Register(PyObject *search_function)
 
    Register a new codec search function.

diff --git a/Doc/c-api/complex.rst b/Doc/c-api/complex.rst
@@ -7,6 +7,8 @@ Complex Number Objects
 
 .. index:: pair: object; complex number
 
+.. c-api-tools-banner::
+
 Python's complex number objects are implemented as two distinct types when
 viewed from the C API:  one is the Python object exposed to Python programs, and
 the other is a C structure which represents the actual complex number value.

diff --git a/Doc/c-api/concrete.rst b/Doc/c-api/concrete.rst
@@ -7,6 +7,8 @@
 Concrete Objects Layer
 **********************
 
+.. c-api-tools-banner::
+
 The functions in this chapter are specific to certain Python object types.
 Passing them an object of the wrong type is not a good idea; if you receive an
 object from a Python program and you are not sure that it has the right type,

@@ -5,6 +5,8 @@
 Context Variables Objects
 -------------------------
 
+.. c-api-tools-banner::
+
 .. _contextvarsobjects_pointertype_change:
 .. versionadded:: 3.7
 

diff --git a/Doc/c-api/conversion.rst b/Doc/c-api/conversion.rst
@@ -5,6 +5,8 @@
 String conversion and formatting
 ================================
 
+.. c-api-tools-banner::
+
 Functions for number conversion and formatted string output.
 
 

diff --git a/Doc/c-api/coro.rst b/Doc/c-api/coro.rst
@@ -5,6 +5,8 @@
 Coroutine Objects
 -----------------
 
+.. c-api-tools-banner::
+
 .. versionadded:: 3.5
 
 Coroutine objects are what functions declared with an ``async`` keyword

@@ -5,6 +5,8 @@
 DateTime Objects
 ----------------
 
+.. c-api-tools-banner::
+
 Various date and time objects are supplied by the :mod:`datetime` module.
 Before using any of these functions, the header file :file:`datetime.h` must be
 included in your source (note that this is not included by :file:`Python.h`),

diff --git a/Doc/c-api/descriptor.rst b/Doc/c-api/descriptor.rst
@@ -5,6 +5,8 @@
 Descriptor Objects
 ------------------
 
+.. c-api-tools-banner::
+
 "Descriptors" are objects that describe some attribute of an object. They are
 found in the dictionary of type objects.
 

diff --git a/Doc/c-api/dict.rst b/Doc/c-api/dict.rst
@@ -7,6 +7,8 @@ Dictionary Objects
 
 .. index:: pair: object; dictionary
 
+.. c-api-tools-banner::
+
 
 .. c:type:: PyDictObject
 

diff --git a/Doc/c-api/exceptions.rst b/Doc/c-api/exceptions.rst
@@ -7,6 +7,8 @@
 Exception Handling
 ******************
 
+.. c-api-tools-banner::
+
 The functions described in this chapter will let you handle and raise Python
 exceptions.  It is important to understand some of the basics of Python
 exception handling.  It works somewhat like the POSIX :c:data:`errno` variable:

diff --git a/Doc/c-api/file.rst b/Doc/c-api/file.rst
@@ -7,6 +7,8 @@ File Objects
 
 .. index:: pair: object; file
 
+.. c-api-tools-banner::
+
 These APIs are a minimal emulation of the Python 2 C API for built-in file
 objects, which used to rely on the buffered I/O (:c:expr:`FILE*`) support
 from the C standard library.  In Python 3, files and streams use the new

diff --git a/Doc/c-api/float.rst b/Doc/c-api/float.rst
@@ -7,6 +7,8 @@ Floating-Point Objects
 
 .. index:: pair: object; floating-point
 
+.. c-api-tools-banner::
+
 
 .. c:type:: PyFloatObject
 

diff --git a/Doc/c-api/frame.rst b/Doc/c-api/frame.rst
@@ -3,6 +3,8 @@
 Frame Objects
 -------------
 
+.. c-api-tools-banner::
+
 .. c:type:: PyFrameObject
 
    The C structure of the objects used to describe frame objects.

diff --git a/Doc/c-api/function.rst b/Doc/c-api/function.rst
@@ -7,6 +7,8 @@ Function Objects
 
 .. index:: pair: object; function
 
+.. c-api-tools-banner::
+
 There are a few functions specific to Python functions.
 
 

diff --git a/Doc/c-api/gcsupport.rst b/Doc/c-api/gcsupport.rst
@@ -5,6 +5,8 @@
 Supporting Cyclic Garbage Collection
 ====================================
 
+.. c-api-tools-banner::
+
 Python's support for detecting and collecting garbage which involves circular
 references requires support from object types which are "containers" for other
 objects which may also be containers.  Types which do not store references to

diff --git a/Doc/c-api/gen.rst b/Doc/c-api/gen.rst
@@ -5,6 +5,8 @@
 Generator Objects
 -----------------
 
+.. c-api-tools-banner::
+
 Generator objects are what Python uses to implement generator iterators. They
 are normally created by iterating over a function that yields values, rather
 than explicitly calling :c:func:`PyGen_New` or :c:func:`PyGen_NewWithQualName`.

diff --git a/Doc/c-api/hash.rst b/Doc/c-api/hash.rst
@@ -3,6 +3,8 @@
 PyHash API
 ----------
 
+.. c-api-tools-banner::
+
 See also the :c:member:`PyTypeObject.tp_hash` member and :ref:`numeric-hash`.
 
 .. c:type:: Py_hash_t

@@ -5,6 +5,8 @@
 Importing Modules
 =================
 
+.. c-api-tools-banner::
+
 
 .. c:function:: PyObject* PyImport_ImportModule(const char *name)
 

diff --git a/Doc/c-api/index.rst b/Doc/c-api/index.rst
@@ -4,6 +4,8 @@
   Python/C API Reference Manual
 ##################################
 
+.. c-api-tools-banner::
+
 This manual documents the API used by C and C++ programmers who want to write
 extension modules or embed Python.  It is a companion to :ref:`extending-index`,
 which describes the general principles of extension writing but does not

diff --git a/Doc/c-api/init.rst b/Doc/c-api/init.rst
@@ -7,6 +7,8 @@
 Initialization, Finalization, and Threads
 *****************************************
 
+.. c-api-tools-banner::
+
 See :ref:`Python Initialization Configuration <init-config>` for details
 on how to configure the interpreter prior to initialization.
 

@@ -6,6 +6,8 @@
 Python Initialization Configuration
 ***********************************
 
+.. c-api-tools-banner::
+
 
 .. _pyinitconfig_api:
 

diff --git a/Doc/c-api/intro.rst b/Doc/c-api/intro.rst
@@ -7,6 +7,8 @@
 Introduction
 ************
 
+.. c-api-tools-banner::
+
 The Application Programmer's Interface to Python gives C and C++ programmers
 access to the Python interpreter at a variety of levels.  The API is equally
 usable from C++, but for brevity it is generally referred to as the Python/C
@@ -844,3 +846,36 @@ 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 <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.
+
+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.
diff --git a/Doc/c-api/iter.rst b/Doc/c-api/iter.rst
@@ -5,6 +5,8 @@
 Iterator Protocol
 =================
 
+.. c-api-tools-banner::
+
 There are two functions specifically for working with iterators.
 
 .. c:function:: int PyIter_Check(PyObject *o)

diff --git a/Doc/c-api/iterator.rst b/Doc/c-api/iterator.rst
@@ -5,6 +5,8 @@
 Iterator Objects
 ----------------
 
+.. c-api-tools-banner::
+
 Python provides two general-purpose iterator objects.  The first, a sequence
 iterator, works with an arbitrary sequence supporting the :meth:`~object.__getitem__`
 method.  The second works with a callable object and a sentinel value, calling

diff --git a/Doc/c-api/list.rst b/Doc/c-api/list.rst
@@ -7,6 +7,8 @@ List Objects
 
 .. index:: pair: object; list
 
+.. c-api-tools-banner::
+
 
 .. c:type:: PyListObject
 

diff --git a/Doc/c-api/long.rst b/Doc/c-api/long.rst
@@ -8,6 +8,8 @@ Integer Objects
 .. index:: pair: object; long integer
            pair: object; integer
 
+.. c-api-tools-banner::
+
 All integers are implemented as "long" integer objects of arbitrary size.
 
 On error, most ``PyLong_As*`` APIs return ``(return type)-1`` which cannot be

diff --git a/Doc/c-api/mapping.rst b/Doc/c-api/mapping.rst
@@ -5,6 +5,8 @@
 Mapping Protocol
 ================
 
+.. c-api-tools-banner::
+
 See also :c:func:`PyObject_GetItem`, :c:func:`PyObject_SetItem` and
 :c:func:`PyObject_DelItem`.
 

diff --git a/Doc/c-api/marshal.rst b/Doc/c-api/marshal.rst
@@ -5,6 +5,8 @@
 Data marshalling support
 ========================
 
+.. c-api-tools-banner::
+
 These routines allow C code to work with serialized objects using the same
 data format as the :mod:`marshal` module.  There are functions to write data
 into the serialization format, and additional functions that can be used to
Original file line number	Diff line number	Diff line change
Expand Up		@@ -7,6 +7,8 @@ Byte Array Objects

		.. index:: pair: object; bytearray

		.. c-api-tools-banner::


		.. c:type:: PyByteArrayObject

Expand Down
Original file line number	Diff line number	Diff line change
Expand Up		@@ -7,6 +7,8 @@ Dictionary Objects

		.. index:: pair: object; dictionary

		.. c-api-tools-banner::


		.. c:type:: PyDictObject

Expand Down
Original file line number	Diff line number	Diff line change
Expand Up		@@ -7,6 +7,8 @@ Floating-Point Objects

		.. index:: pair: object; floating-point

		.. c-api-tools-banner::


		.. c:type:: PyFloatObject

Expand Down
Original file line number	Diff line number	Diff line change
Expand Up		@@ -7,6 +7,8 @@ Function Objects

		.. index:: pair: object; function

		.. c-api-tools-banner::

		There are a few functions specific to Python functions.


Expand Down
Original file line number	Diff line number	Diff line change
Expand Up		@@ -7,6 +7,8 @@ List Objects

		.. index:: pair: object; list

		.. c-api-tools-banner::


		.. c:type:: PyListObject

Expand Down