diff --git a/Doc/c-api/abstract.rst b/Doc/c-api/abstract.rst index f5df09fa7fd786..43fe8cbfb4b593 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 7cbc99ad145ad4..758ce6c8ca8635 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 96050f59bd5250..2ff0ccd3a8e135 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 3bbc990b6329c0..e0b0aa78636a42 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 b4dc4849d044e1..212e6b79c2aa54 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 d3081894eadaf5..55fce37b74f261 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 e2b22ec3c794ae..714546c1a2e05c 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 d47beee68eaa33..9a4b7c517a1b70 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 7198d6bc056eb4..5f3d673530aecc 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 cdb8aa33e9fd32..49b64164a76090 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 61eb994c370946..d6f8d834a6d6d7 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 6eae24b38fae48..70e9a325d3dc15 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 8ae5c4fecd6248..6bed943a69ebc5 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 16bd79475dc1e6..679caa8acffb4f 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 880f7b15ce68e8..974cf01d5e290e 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 b7c6550ff34aac..29aa712b855732 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 c92ef4c653a675..3b3ec200acc2d7 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 caa855a10d20ca..f8d3db311246ff 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 d2d4d5309c7098..dd5279cd71abbb 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 b32c113e5f0457..92e16b1653622a 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 e55c5c80cb83c0..91b5a5ee19dc09 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 c8e1b5c2461738..99cc30a3dea45b 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 e9019a0d500f7e..2f8d70c30a4c3d 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 c5a7653efca26b..4ea050c3e3afbc 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 1a52e146a69751..52c8c3d00954d8 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 58792edeed25e3..cc205915c67b3d 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 d1f0982b818931..585b0464e2aeb1 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 0eb5922f6da75f..26ed7021f64d70 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 00f8cb887dc7eb..b1f4c2f2c30a23 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 1cab3ce3061ec9..d0b0c20bc6caec 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 ba56b03c6ac8e7..ec407c04d7f0e6 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 52f64a61006b74..eaeeda7df643da 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 e1931655618b1c..c37a8a4b7387d3 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 c8c60eb9f48f45..5dd91478ffadb0 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 bf9df62c6f1706..9e716796e6141e 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 6b7ba8c9979163..8b0717904ce26d 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 758415a76e5cb4..f286b7bd82e4f1 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 25d9e62e387279..5eb02f795736b0 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 1f55c0aa955c75..7f8b787480a47d 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 61218a1bf6f171..51c3364dfc9260 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 64ae35daa703b8..11e790a8142eee 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 f6038032805259..558567d0bc0d10 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 0d75ab8e1af111..1384199da31d17 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 f7f4d37d4c721f..9b9167e2051014 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 7926148302af0b..a9541d5d1d445c 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 f1941fc4bc4e85..db32d0c90bc085 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 ad8b5935258fa7..d048b356694eac 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 0fd159f1eb87f8..d2aaadce990027 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 8bd8c107c98bdf..0f6bc8d7ec9ff4 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 77b5e3c0876bbb..ef9e488be98e9b 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 b23f016f9b0a06..e33425f6e9524d 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 54fd5a064aa2ac..622997e0a64401 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 df5bf6b64a93a0..ebaf0c721df643 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 cba823aa027bd6..85f07dc733ccfc 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 c6d761fe7fd1c9..79e87728e986d6 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 124e58cf950b7a..f186d035506e9f 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 987bc167c68d6c..edbcb4959c8c16 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 b3c89800e386ff..690549bcd34506 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 31d6adbc225439..0cc5ca521152f6 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 815afddad19df1..929c8b1dd6c2be 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 ec2867b0ce09ba..be4e1c0d06ea70 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 98fe68737deb81..de22b5765eda2d 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 3b9f07778d5ace..46dc24f3f4bac5 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 95987e872ce639..d5ba413d654e24 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 9d0abf440f791d..a45966ca358572 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 1ef4181d52eb10..5ccd007f77c73f 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 c3c6cf413dcef5..efc210223bb567 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 089614a1f6c421..ad96da1cfa734f 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)