diff --git a/Doc/c-api/abstract.rst b/Doc/c-api/abstract.rst index f5df09fa7fd7863..43fe8cbfb4b593c 100644 --- 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 index 7cbc99ad145ad46..758ce6c8ca86350 100644 --- 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 index 96050f59bd52508..2ff0ccd3a8e1352 100644 --- 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 index 3bbc990b6329c0d..e0b0aa78636a42a 100644 --- 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 index b4dc4849d044e1c..212e6b79c2aa545 100644 --- 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 index d3081894eadaf5e..55fce37b74f2614 100644 --- 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 index e2b22ec3c794ae4..714546c1a2e05ce 100644 --- 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 index d47beee68eaa338..9a4b7c517a1b70f 100644 --- 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 index 7198d6bc056eb43..5f3d673530aeccb 100644 --- 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 index cdb8aa33e9fd325..49b64164a760909 100644 --- 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 index 61eb994c3709460..d6f8d834a6d6d76 100644 --- 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 index 6eae24b38fae48a..70e9a325d3dc156 100644 --- a/Doc/c-api/code.rst +++ b/Doc/c-api/code.rst @@ -9,6 +9,8 @@ Code Objects .. sectionauthor:: Jeffrey Yasskin +.. 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 index 8ae5c4fecd6248f..6bed943a69ebc5a 100644 --- 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 index 16bd79475dc1e66..679caa8acffb4f7 100644 --- 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 index 880f7b15ce68e82..974cf01d5e290ee 100644 --- 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, diff --git a/Doc/c-api/contextvars.rst b/Doc/c-api/contextvars.rst index b7c6550ff34aac1..29aa712b855732e 100644 --- a/Doc/c-api/contextvars.rst +++ b/Doc/c-api/contextvars.rst @@ -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 index c92ef4c653a675f..3b3ec200acc2d7e 100644 --- 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 index caa855a10d20ca9..f8d3db311246ff9 100644 --- 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 diff --git a/Doc/c-api/datetime.rst b/Doc/c-api/datetime.rst index d2d4d5309c70984..dd5279cd71abbbf 100644 --- a/Doc/c-api/datetime.rst +++ b/Doc/c-api/datetime.rst @@ -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 index b32c113e5f04573..92e16b1653622a3 100644 --- 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 index e55c5c80cb83c0e..91b5a5ee19dc099 100644 --- 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 index c8e1b5c24617382..99cc30a3dea45b8 100644 --- 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 index e9019a0d500f7e5..2f8d70c30a4c3d0 100644 --- 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 index c5a7653efca26bc..4ea050c3e3afbc8 100644 --- 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 index 1a52e146a697510..52c8c3d00954d80 100644 --- 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 index 58792edeed25e3d..cc205915c67b3de 100644 --- 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 index d1f0982b8189311..585b0464e2aeb1d 100644 --- 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 index 0eb5922f6da75f2..26ed7021f64d701 100644 --- 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 index 00f8cb887dc7ebf..b1f4c2f2c30a23a 100644 --- 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 diff --git a/Doc/c-api/import.rst b/Doc/c-api/import.rst index 1cab3ce3061ec90..d0b0c20bc6caec3 100644 --- a/Doc/c-api/import.rst +++ b/Doc/c-api/import.rst @@ -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 index ba56b03c6ac8e7c..ec407c04d7f0e66 100644 --- 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 index 52f64a61006b74d..eaeeda7df643daa 100644 --- 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 ` for details on how to configure the interpreter prior to initialization. diff --git a/Doc/c-api/init_config.rst b/Doc/c-api/init_config.rst index e1931655618b1c9..c37a8a4b7387d39 100644 --- a/Doc/c-api/init_config.rst +++ b/Doc/c-api/init_config.rst @@ -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 index c8c60eb9f48f45a..5dd91478ffadb04 100644 --- 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 `_ +* `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. diff --git a/Doc/c-api/iter.rst b/Doc/c-api/iter.rst index bf9df62c6f17065..9e716796e6141e8 100644 --- 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 index 6b7ba8c99791634..8b0717904ce26d1 100644 --- 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 index 758415a76e5cb41..f286b7bd82e4f19 100644 --- 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 index 25d9e62e3872797..5eb02f795736b05 100644 --- 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 index 1f55c0aa955c75b..7f8b787480a47db 100644 --- 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 index 61218a1bf6f1716..51c3364dfc92600 100644 --- 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 diff --git a/Doc/c-api/memory.rst b/Doc/c-api/memory.rst index 64ae35daa703b88..11e790a8142eee1 100644 --- a/Doc/c-api/memory.rst +++ b/Doc/c-api/memory.rst @@ -9,6 +9,7 @@ Memory Management .. sectionauthor:: Vladimir Marangozov +.. c-api-tools-banner:: .. _memoryoverview: diff --git a/Doc/c-api/memoryview.rst b/Doc/c-api/memoryview.rst index f6038032805259f..558567d0bc0d100 100644 --- a/Doc/c-api/memoryview.rst +++ b/Doc/c-api/memoryview.rst @@ -8,6 +8,8 @@ MemoryView objects ------------------ +.. c-api-tools-banner:: + A :class:`memoryview` object exposes the C level :ref:`buffer interface ` as a Python object which can then be passed around like any other object. diff --git a/Doc/c-api/method.rst b/Doc/c-api/method.rst index 0d75ab8e1af1118..1384199da31d177 100644 --- a/Doc/c-api/method.rst +++ b/Doc/c-api/method.rst @@ -7,6 +7,8 @@ Instance Method Objects .. index:: pair: object; instancemethod +.. c-api-tools-banner:: + An instance method is a wrapper for a :c:type:`PyCFunction` and the new way to bind a :c:type:`PyCFunction` to a class object. It replaces the former call ``PyMethod_New(func, NULL, class)``. diff --git a/Doc/c-api/module.rst b/Doc/c-api/module.rst index f7f4d37d4c721fb..9b9167e20510146 100644 --- a/Doc/c-api/module.rst +++ b/Doc/c-api/module.rst @@ -7,6 +7,8 @@ Module Objects .. index:: pair: object; module +.. c-api-tools-banner:: + .. c:var:: PyTypeObject PyModule_Type diff --git a/Doc/c-api/monitoring.rst b/Doc/c-api/monitoring.rst index 7926148302af0b5..a9541d5d1d445c0 100644 --- a/Doc/c-api/monitoring.rst +++ b/Doc/c-api/monitoring.rst @@ -1,5 +1,7 @@ .. highlight:: c +.. c-api-tools-banner:: + .. _c-api-monitoring: Monitoring C API diff --git a/Doc/c-api/none.rst b/Doc/c-api/none.rst index f1941fc4bc4e850..db32d0c90bc0850 100644 --- a/Doc/c-api/none.rst +++ b/Doc/c-api/none.rst @@ -7,6 +7,8 @@ The ``None`` Object .. index:: pair: object; None +.. c-api-tools-banner:: + Note that the :c:type:`PyTypeObject` for ``None`` is not directly exposed in the Python/C API. Since ``None`` is a singleton, testing for object identity (using ``==`` in C) is sufficient. There is no :c:func:`!PyNone_Check` function for the diff --git a/Doc/c-api/number.rst b/Doc/c-api/number.rst index ad8b5935258fa7b..d048b356694eacf 100644 --- a/Doc/c-api/number.rst +++ b/Doc/c-api/number.rst @@ -5,6 +5,8 @@ Number Protocol =============== +.. c-api-tools-banner:: + .. c:function:: int PyNumber_Check(PyObject *o) diff --git a/Doc/c-api/object.rst b/Doc/c-api/object.rst index 0fd159f1eb87f80..d2aaadce990027d 100644 --- a/Doc/c-api/object.rst +++ b/Doc/c-api/object.rst @@ -5,6 +5,8 @@ Object Protocol =============== +.. c-api-tools-banner:: + .. c:function:: PyObject* Py_GetConstant(unsigned int constant_id) diff --git a/Doc/c-api/objimpl.rst b/Doc/c-api/objimpl.rst index 8bd8c107c98bdfc..0f6bc8d7ec9ff4d 100644 --- a/Doc/c-api/objimpl.rst +++ b/Doc/c-api/objimpl.rst @@ -6,6 +6,8 @@ Object Implementation Support ***************************** +.. c-api-tools-banner:: + This chapter describes the functions, types, and macros used when defining new object types. diff --git a/Doc/c-api/perfmaps.rst b/Doc/c-api/perfmaps.rst index 77b5e3c0876bbb7..ef9e488be98e9b8 100644 --- a/Doc/c-api/perfmaps.rst +++ b/Doc/c-api/perfmaps.rst @@ -5,6 +5,8 @@ Support for Perf Maps ---------------------- +.. c-api-tools-banner:: + On supported platforms (as of this writing, only Linux), the runtime can take advantage of *perf map files* to make Python functions visible to an external profiling tool (such as `perf `_). diff --git a/Doc/c-api/refcounting.rst b/Doc/c-api/refcounting.rst index b23f016f9b0a063..e33425f6e9524d2 100644 --- a/Doc/c-api/refcounting.rst +++ b/Doc/c-api/refcounting.rst @@ -7,6 +7,8 @@ Reference Counting ****************** +.. c-api-tools-banner:: + The functions and macros in this section are used for managing reference counts of Python objects. diff --git a/Doc/c-api/reflection.rst b/Doc/c-api/reflection.rst index 54fd5a064aa2ac2..622997e0a64401e 100644 --- a/Doc/c-api/reflection.rst +++ b/Doc/c-api/reflection.rst @@ -5,6 +5,8 @@ Reflection ========== +.. c-api-tools-banner:: + .. c:function:: PyObject* PyEval_GetBuiltins(void) .. deprecated:: 3.13 diff --git a/Doc/c-api/sequence.rst b/Doc/c-api/sequence.rst index df5bf6b64a93a00..ebaf0c721df6430 100644 --- a/Doc/c-api/sequence.rst +++ b/Doc/c-api/sequence.rst @@ -5,6 +5,8 @@ Sequence Protocol ================= +.. c-api-tools-banner:: + .. c:function:: int PySequence_Check(PyObject *o) diff --git a/Doc/c-api/set.rst b/Doc/c-api/set.rst index cba823aa027bd6d..85f07dc733ccfcb 100644 --- a/Doc/c-api/set.rst +++ b/Doc/c-api/set.rst @@ -7,6 +7,8 @@ Set Objects .. sectionauthor:: Raymond D. Hettinger +.. c-api-tools-banner:: + .. index:: pair: object; set diff --git a/Doc/c-api/slice.rst b/Doc/c-api/slice.rst index c6d761fe7fd1c96..79e87728e986d6e 100644 --- a/Doc/c-api/slice.rst +++ b/Doc/c-api/slice.rst @@ -5,6 +5,8 @@ Slice Objects ------------- +.. c-api-tools-banner:: + .. c:var:: PyTypeObject PySlice_Type diff --git a/Doc/c-api/stable.rst b/Doc/c-api/stable.rst index 124e58cf950b7a7..f186d035506e9ff 100644 --- a/Doc/c-api/stable.rst +++ b/Doc/c-api/stable.rst @@ -6,6 +6,8 @@ C API Stability *************** +.. c-api-tools-banner:: + Unless documented otherwise, Python's C API is covered by the Backwards Compatibility Policy, :pep:`387`. Most changes to it are source-compatible (typically by only adding new API). diff --git a/Doc/c-api/structures.rst b/Doc/c-api/structures.rst index 987bc167c68d6cd..edbcb4959c8c168 100644 --- a/Doc/c-api/structures.rst +++ b/Doc/c-api/structures.rst @@ -5,6 +5,8 @@ Common Object Structures ======================== +.. c-api-tools-banner:: + There are a large number of structures which are used in the definition of object types for Python. This section describes these structures and how they are used. diff --git a/Doc/c-api/sys.rst b/Doc/c-api/sys.rst index b3c89800e386ff1..690549bcd345066 100644 --- a/Doc/c-api/sys.rst +++ b/Doc/c-api/sys.rst @@ -5,6 +5,8 @@ Operating System Utilities ========================== +.. c-api-tools-banner:: + .. c:function:: PyObject* PyOS_FSPath(PyObject *path) diff --git a/Doc/c-api/time.rst b/Doc/c-api/time.rst index 31d6adbc225439e..0cc5ca521152f64 100644 --- a/Doc/c-api/time.rst +++ b/Doc/c-api/time.rst @@ -5,6 +5,8 @@ PyTime C API ============ +.. c-api-tools-banner:: + .. versionadded:: 3.13 The clock C API provides access to system clocks. diff --git a/Doc/c-api/tuple.rst b/Doc/c-api/tuple.rst index 815afddad19df1a..929c8b1dd6c2be9 100644 --- a/Doc/c-api/tuple.rst +++ b/Doc/c-api/tuple.rst @@ -7,6 +7,8 @@ Tuple Objects .. index:: pair: object; tuple +.. c-api-tools-banner:: + .. c:type:: PyTupleObject diff --git a/Doc/c-api/type.rst b/Doc/c-api/type.rst index ec2867b0ce09ba1..be4e1c0d06ea70d 100644 --- a/Doc/c-api/type.rst +++ b/Doc/c-api/type.rst @@ -7,6 +7,8 @@ Type Objects .. index:: pair: object; type +.. c-api-tools-banner:: + .. c:type:: PyTypeObject diff --git a/Doc/c-api/typehints.rst b/Doc/c-api/typehints.rst index 98fe68737deb81c..de22b5765eda2de 100644 --- a/Doc/c-api/typehints.rst +++ b/Doc/c-api/typehints.rst @@ -5,6 +5,8 @@ Objects for Type Hinting ------------------------ +.. c-api-tools-banner:: + Various built-in types for type hinting are provided. Currently, two types exist -- :ref:`GenericAlias ` and :ref:`Union `. Only ``GenericAlias`` is exposed to C. diff --git a/Doc/c-api/typeobj.rst b/Doc/c-api/typeobj.rst index 3b9f07778d5ace9..46dc24f3f4bac5f 100644 --- a/Doc/c-api/typeobj.rst +++ b/Doc/c-api/typeobj.rst @@ -5,6 +5,8 @@ Type Object Structures ====================== +.. c-api-tools-banner:: + Perhaps one of the most important structures of the Python object system is the structure that defines a new type: the :c:type:`PyTypeObject` structure. Type objects can be handled using any of the ``PyObject_*`` or diff --git a/Doc/c-api/unicode.rst b/Doc/c-api/unicode.rst index 95987e872ce639d..d5ba413d654e24a 100644 --- a/Doc/c-api/unicode.rst +++ b/Doc/c-api/unicode.rst @@ -8,6 +8,8 @@ Unicode Objects and Codecs .. sectionauthor:: Marc-André Lemburg .. sectionauthor:: Georg Brandl +.. c-api-tools-banner:: + Unicode Objects ^^^^^^^^^^^^^^^ diff --git a/Doc/c-api/utilities.rst b/Doc/c-api/utilities.rst index 9d0abf440f791d4..a45966ca358572f 100644 --- a/Doc/c-api/utilities.rst +++ b/Doc/c-api/utilities.rst @@ -6,6 +6,8 @@ Utilities ********* +.. c-api-tools-banner:: + The functions in this chapter perform various utility tasks, ranging from helping C code be more portable across platforms, using Python modules from C, and parsing function arguments and constructing Python values from C values. diff --git a/Doc/c-api/veryhigh.rst b/Doc/c-api/veryhigh.rst index 1ef4181d52eb101..5ccd007f77c73f4 100644 --- a/Doc/c-api/veryhigh.rst +++ b/Doc/c-api/veryhigh.rst @@ -7,6 +7,8 @@ The Very High Level Layer ************************* +.. c-api-tools-banner:: + The functions in this chapter will let you execute Python source code given in a file or a buffer, but they will not let you interact in a more detailed way with the interpreter. diff --git a/Doc/c-api/weakref.rst b/Doc/c-api/weakref.rst index c3c6cf413dcef58..efc210223bb5672 100644 --- a/Doc/c-api/weakref.rst +++ b/Doc/c-api/weakref.rst @@ -5,6 +5,8 @@ Weak Reference Objects ---------------------- +.. c-api-tools-banner:: + Python supports *weak references* as first-class objects. There are two specific object types which directly implement weak references. The first is a simple reference object, and the second acts as a proxy for the original object diff --git a/Doc/tools/extensions/c_annotations.py b/Doc/tools/extensions/c_annotations.py index 089614a1f6c421d..ad96da1cfa734fa 100644 --- a/Doc/tools/extensions/c_annotations.py +++ b/Doc/tools/extensions/c_annotations.py @@ -265,6 +265,38 @@ def run(self) -> list[nodes.Node]: return [node] +class CAPIToolsBanner(SphinxDirective): + """CAPI Tools banner.""" + + has_content = False + required_arguments = 0 + optional_arguments = 0 + final_argument_whitespace = True + + text = sphinx_gettext( + "The Python C API is a low level interface that allows language runtime " + "embedding and extension module development tools to integrate " + "with the running interpreter. It is generally recommended to use a " + "higher level :ref:`third party tool `, rather than using the " + "Python C API directly." + ) + + def run(self) -> list[nodes.admonition]: + text = self.text + + text_node = nodes.paragraph(text) + text_node.line = self.lineno + node, msg = self.state.inline_text(text, self.lineno) + text_node.extend(node + msg) + + source_lines = [text] + admonition_node = nodes.note( + "\n".join(source_lines), classes=["admonition note"] + ) + admonition_node.append(text_node) + return [admonition_node] + + def init_annotations(app: Sphinx) -> None: # Using domaindata is a bit hack-ish, # but allows storing state without a global variable or closure. @@ -281,6 +313,7 @@ def setup(app: Sphinx) -> ExtensionMetadata: app.add_config_value("refcount_file", "", "env", types={str}) app.add_config_value("stable_abi_file", "", "env", types={str}) app.add_directive("limited-api-list", LimitedAPIList) + app.add_directive("c-api-tools-banner", CAPIToolsBanner) app.connect("builder-inited", init_annotations) app.connect("doctree-read", add_annotations)