Upload 280 files

python-3.12.6-docs-text/python-3.12.6-docs-text/about.txt

@@ -0,0 +1,33 @@
+About these documents
+*********************
+
+These documents are generated from reStructuredText sources by Sphinx,
+a document processor specifically written for the Python
+documentation.
+
+Development of the documentation and its toolchain is an entirely
+volunteer effort, just like Python itself.  If you want to contribute,
+please take a look at the Dealing with Bugs page for information on
+how to do so.  New volunteers are always welcome!
+
+Many thanks go to:
+
+* Fred L. Drake, Jr., the creator of the original Python documentation
+  toolset and writer of much of the content;
+
+* the Docutils project for creating reStructuredText and the Docutils
+  suite;
+
+* Fredrik Lundh for his Alternative Python Reference project from
+  which Sphinx got many good ideas.
+
+
+Contributors to the Python Documentation
+========================================
+
+Many people have contributed to the Python language, the Python
+standard library, and the Python documentation.  See Misc/ACKS in the
+Python source distribution for a partial list of contributors.
+
+It is only with the input and contributions of the Python community
+that Python has such wonderful documentation -- Thank You!

python-3.12.6-docs-text/python-3.12.6-docs-text/bugs.txt

@@ -0,0 +1,111 @@
+Dealing with Bugs
+*****************
+
+Python is a mature programming language which has established a
+reputation for stability.  In order to maintain this reputation, the
+developers would like to know of any deficiencies you find in Python.
+
+It can be sometimes faster to fix bugs yourself and contribute patches
+to Python as it streamlines the process and involves less people.
+Learn how to contribute.
+
+
+Documentation bugs
+==================
+
+If you find a bug in this documentation or would like to propose an
+improvement, please submit a bug report on the tracker.  If you have a
+suggestion on how to fix it, include that as well.
+
+You can also open a discussion item on our Documentation Discourse
+forum.
+
+If you find a bug in the theme (HTML / CSS / JavaScript) of the
+documentation, please submit a bug report on the python-doc-theme bug
+tracker.
+
+If you're short on time, you can also email documentation bug reports
+to [email protected] (behavioral bugs can be sent to python-
+[email protected]). 'docs@' is a mailing list run by volunteers; your
+request will be noticed, though it may take a while to be processed.
+
+See also:
+
+  Documentation bugs
+     A list of documentation bugs that have been submitted to the
+     Python issue tracker.
+
+  Issue Tracking
+     Overview of the process involved in reporting an improvement on
+     the tracker.
+
+  Helping with Documentation
+     Comprehensive guide for individuals that are interested in
+     contributing to Python documentation.
+
+  Documentation Translations
+     A list of GitHub pages for documentation translation and their
+     primary contacts.
+
+
+Using the Python issue tracker
+==============================
+
+Issue reports for Python itself should be submitted via the GitHub
+issues tracker (https://github.com/python/cpython/issues). The GitHub
+issues tracker offers a web form which allows pertinent information to
+be entered and submitted to the developers.
+
+The first step in filing a report is to determine whether the problem
+has already been reported.  The advantage in doing so, aside from
+saving the developers' time, is that you learn what has been done to
+fix it; it may be that the problem has already been fixed for the next
+release, or additional information is needed (in which case you are
+welcome to provide it if you can!). To do this, search the tracker
+using the search box at the top of the page.
+
+If the problem you're reporting is not already in the list, log in to
+GitHub. If you don't already have a GitHub account, create a new
+account using the "Sign up" link. It is not possible to submit a bug
+report anonymously.
+
+Being now logged in, you can submit an issue. Click on the "New issue"
+button in the top bar to report a new issue.
+
+The submission form has two fields, "Title" and "Comment".
+
+For the "Title" field, enter a *very* short description of the
+problem; fewer than ten words is good.
+
+In the "Comment" field, describe the problem in detail, including what
+you expected to happen and what did happen.  Be sure to include
+whether any extension modules were involved, and what hardware and
+software platform you were using (including version information as
+appropriate).
+
+Each issue report will be reviewed by a developer who will determine
+what needs to be done to correct the problem. You will receive an
+update each time an action is taken on the issue.
+
+See also:
+
+  How to Report Bugs Effectively
+     Article which goes into some detail about how to create a useful
+     bug report. This describes what kind of information is useful and
+     why it is useful.
+
+  Bug Writing Guidelines
+     Information about writing a good bug report.  Some of this is
+     specific to the Mozilla project, but describes general good
+     practices.
+
+
+Getting started contributing to Python yourself
+===============================================
+
+Beyond just reporting bugs that you find, you are also welcome to
+submit patches to fix them.  You can find more information on how to
+get started patching Python in the Python Developer's Guide.  If you
+have questions, the core-mentorship mailing list is a friendly place
+to get answers to any and all questions pertaining to the process of
+fixing issues in Python.

python-3.12.6-docs-text/python-3.12.6-docs-text/c-api/abstract.txt

@@ -0,0 +1,62 @@
+Abstract Objects Layer
+**********************
+
+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 will raise a Python exception.
+
+It is not possible to use these functions on objects that are not
+properly initialized, such as a list object that has been created by
+"PyList_New()", but whose items have not been set to some non-"NULL"
+value yet.
+
+* Object Protocol
+
+* Call Protocol
+
+  * The *tp_call* Protocol
+
+  * The Vectorcall Protocol
+
+    * Recursion Control
+
+    * Vectorcall Support API
+
+  * Object Calling API
+
+  * Call Support API
+
+* Number Protocol
+
+* Sequence Protocol
+
+* Mapping Protocol
+
+* Iterator Protocol
+
+* Buffer Protocol
+
+  * Buffer structure
+
+  * Buffer request types
+
+    * request-independent fields
+
+    * readonly, format
+
+    * shape, strides, suboffsets
+
+    * contiguity requests
+
+    * compound requests
+
+  * Complex arrays
+
+    * NumPy-style: shape and strides
+
+    * PIL-style: shape, strides and suboffsets
+
+  * Buffer-related functions
+
+* Old Buffer Protocol

python-3.12.6-docs-text/python-3.12.6-docs-text/c-api/allocation.txt

@@ -0,0 +1,64 @@
+Allocating Objects on the Heap
+******************************
+
+PyObject *_PyObject_New(PyTypeObject *type)
+    *Return value: New reference.*
+
+PyVarObject *_PyObject_NewVar(PyTypeObject *type, Py_ssize_t size)
+    *Return value: New reference.*
+
+PyObject *PyObject_Init(PyObject *op, PyTypeObject *type)
+    *Return value: Borrowed reference.** Part of the Stable ABI.*
+
+   Initialize a newly allocated object *op* with its type and initial
+   reference.  Returns the initialized object.  If *type* indicates
+   that the object participates in the cyclic garbage detector, it is
+   added to the detector's set of observed objects. Other fields of
+   the object are not affected.
+
+PyVarObject *PyObject_InitVar(PyVarObject *op, PyTypeObject *type, Py_ssize_t size)
+    *Return value: Borrowed reference.** Part of the Stable ABI.*
+
+   This does everything "PyObject_Init()" does, and also initializes
+   the length information for a variable-size object.
+
+PyObject_New(TYPE, typeobj)
+
+   Allocate a new Python object using the C structure type *TYPE* and
+   the Python type object *typeobj* ("PyTypeObject*"). Fields not
+   defined by the Python object header are not initialized. The caller
+   will own the only reference to the object (i.e. its reference count
+   will be one). The size of the memory allocation is determined from
+   the "tp_basicsize" field of the type object.
+
+PyObject_NewVar(TYPE, typeobj, size)
+
+   Allocate a new Python object using the C structure type *TYPE* and
+   the Python type object *typeobj* ("PyTypeObject*"). Fields not
+   defined by the Python object header are not initialized.  The
+   allocated memory allows for the *TYPE* structure plus *size*
+   ("Py_ssize_t") fields of the size given by the "tp_itemsize" field
+   of *typeobj*.  This is useful for implementing objects like tuples,
+   which are able to determine their size at construction time.
+   Embedding the array of fields into the same allocation decreases
+   the number of allocations, improving the memory management
+   efficiency.
+
+void PyObject_Del(void *op)
+
+   Releases memory allocated to an object using "PyObject_New" or
+   "PyObject_NewVar".  This is normally called from the "tp_dealloc"
+   handler specified in the object's type.  The fields of the object
+   should not be accessed after this call as the memory is no longer a
+   valid Python object.
+
+PyObject _Py_NoneStruct
+
+   Object which is visible in Python as "None".  This should only be
+   accessed using the "Py_None" macro, which evaluates to a pointer to
+   this object.
+
+See also:
+
+  "PyModule_Create()"
+     To allocate and create extension modules.

python-3.12.6-docs-text/python-3.12.6-docs-text/c-api/apiabiversion.txt

@@ -0,0 +1,69 @@
+API and ABI Versioning
+**********************
+
+CPython exposes its version number in the following macros. Note that
+these correspond to the version code is **built** with, not
+necessarily the version used at **run time**.
+
+See C API Stability for a discussion of API and ABI stability across
+versions.
+
+PY_MAJOR_VERSION
+
+   The "3" in "3.4.1a2".
+
+PY_MINOR_VERSION
+
+   The "4" in "3.4.1a2".
+
+PY_MICRO_VERSION
+
+   The "1" in "3.4.1a2".
+
+PY_RELEASE_LEVEL
+
+   The "a" in "3.4.1a2". This can be "0xA" for alpha, "0xB" for beta,
+   "0xC" for release candidate or "0xF" for final.
+
+PY_RELEASE_SERIAL
+
+   The "2" in "3.4.1a2". Zero for final releases.
+
+PY_VERSION_HEX
+
+   The Python version number encoded in a single integer.
+
+   The underlying version information can be found by treating it as a
+   32 bit number in the following manner:
+
+   +---------+---------------------------+---------------------------+----------------------------+
+   | Bytes   | Bits (big endian order)   | Meaning                   | Value for "3.4.1a2"        |
+   |=========|===========================|===========================|============================|
+   | 1       | 1-8                       | "PY_MAJOR_VERSION"        | "0x03"                     |
+   +---------+---------------------------+---------------------------+----------------------------+
+   | 2       | 9-16                      | "PY_MINOR_VERSION"        | "0x04"                     |
+   +---------+---------------------------+---------------------------+----------------------------+
+   | 3       | 17-24                     | "PY_MICRO_VERSION"        | "0x01"                     |
+   +---------+---------------------------+---------------------------+----------------------------+
+   | 4       | 25-28                     | "PY_RELEASE_LEVEL"        | "0xA"                      |
+   |         +---------------------------+---------------------------+----------------------------+
+   |         | 29-32                     | "PY_RELEASE_SERIAL"       | "0x2"                      |
+   +---------+---------------------------+---------------------------+----------------------------+
+
+   Thus "3.4.1a2" is hexversion "0x030401a2" and "3.10.0" is
+   hexversion "0x030a00f0".
+
+   Use this for numeric comparisons, e.g. "#if PY_VERSION_HEX >= ...".
+
+   This version is also available via the symbol "Py_Version".
+
+const unsigned long Py_Version
+    * Part of the Stable ABI since version 3.11.*
+
+   The Python runtime version number encoded in a single constant
+   integer, with the same format as the "PY_VERSION_HEX" macro. This
+   contains the Python version used at run time.
+
+   Added in version 3.11.
+
+All the given macros are defined in Include/patchlevel.h.

python-3.12.6-docs-text/python-3.12.6-docs-text/c-api/arg.txt

@@ -0,0 +1,672 @@
+Parsing arguments and building values
+*************************************
+
+These functions are useful when creating your own extensions functions
+and methods.  Additional information and examples are available in
+Extending and Embedding the Python Interpreter.
+
+The first three of these functions described, "PyArg_ParseTuple()",
+"PyArg_ParseTupleAndKeywords()", and "PyArg_Parse()", all use *format
+strings* which are used to tell the function about the expected
+arguments.  The format strings use the same syntax for each of these
+functions.
+
+
+Parsing arguments
+=================
+
+A format string consists of zero or more "format units."  A format
+unit describes one Python object; it is usually a single character or
+a parenthesized sequence of format units.  With a few exceptions, a
+format unit that is not a parenthesized sequence normally corresponds
+to a single address argument to these functions.  In the following
+description, the quoted form is the format unit; the entry in (round)
+parentheses is the Python object type that matches the format unit;
+and the entry in [square] brackets is the type of the C variable(s)
+whose address should be passed.
+
+
+Strings and buffers
+-------------------
+
+These formats allow accessing an object as a contiguous chunk of
+memory. You don't have to provide raw storage for the returned unicode
+or bytes area.
+
+Unless otherwise stated, buffers are not NUL-terminated.
+
+There are three ways strings and buffers can be converted to C:
+
+* Formats such as "y*" and "s*" fill a "Py_buffer" structure. This
+  locks the underlying buffer so that the caller can subsequently use
+  the buffer even inside a "Py_BEGIN_ALLOW_THREADS" block without the
+  risk of mutable data being resized or destroyed. As a result, **you
+  have to call** "PyBuffer_Release()" after you have finished
+  processing the data (or in any early abort case).
+
+* The "es", "es#", "et" and "et#" formats allocate the result buffer.
+  **You have to call** "PyMem_Free()" after you have finished
+  processing the data (or in any early abort case).
+
+* Other formats take a "str" or a read-only *bytes-like object*, such
+  as "bytes", and provide a "const char *" pointer to its buffer. In
+  this case the buffer is "borrowed": it is managed by the
+  corresponding Python object, and shares the lifetime of this object.
+  You won't have to release any memory yourself.
+
+  To ensure that the underlying buffer may be safely borrowed, the
+  object's "PyBufferProcs.bf_releasebuffer" field must be "NULL". This
+  disallows common mutable objects such as "bytearray", but also some
+  read-only objects such as "memoryview" of "bytes".
+
+  Besides this "bf_releasebuffer" requirement, there is no check to
+  verify whether the input object is immutable (e.g. whether it would
+  honor a request for a writable buffer, or whether another thread can
+  mutate the data).
+
+Note:
+
+  For all "#" variants of formats ("s#", "y#", etc.), the macro
+  "PY_SSIZE_T_CLEAN" must be defined before including "Python.h". On
+  Python 3.9 and older, the type of the length argument is
+  "Py_ssize_t" if the "PY_SSIZE_T_CLEAN" macro is defined, or int
+  otherwise.
+
+"s" ("str") [const char *]
+   Convert a Unicode object to a C pointer to a character string. A
+   pointer to an existing string is stored in the character pointer
+   variable whose address you pass.  The C string is NUL-terminated.
+   The Python string must not contain embedded null code points; if it
+   does, a "ValueError" exception is raised. Unicode objects are
+   converted to C strings using "'utf-8'" encoding. If this conversion
+   fails, a "UnicodeError" is raised.
+
+   Note:
+
+     This format does not accept *bytes-like objects*.  If you want to
+     accept filesystem paths and convert them to C character strings,
+     it is preferable to use the "O&" format with
+     "PyUnicode_FSConverter()" as *converter*.
+
+   Changed in version 3.5: Previously, "TypeError" was raised when
+   embedded null code points were encountered in the Python string.
+
+"s*" ("str" or *bytes-like object*) [Py_buffer]
+   This format accepts Unicode objects as well as bytes-like objects.
+   It fills a "Py_buffer" structure provided by the caller. In this
+   case the resulting C string may contain embedded NUL bytes. Unicode
+   objects are converted to C strings using "'utf-8'" encoding.
+
+"s#" ("str", read-only *bytes-like object*) [const char *,
+"Py_ssize_t"]
+   Like "s*", except that it provides a borrowed buffer. The result is
+   stored into two C variables, the first one a pointer to a C string,
+   the second one its length. The string may contain embedded null
+   bytes. Unicode objects are converted to C strings using "'utf-8'"
+   encoding.
+
+"z" ("str" or "None") [const char *]
+   Like "s", but the Python object may also be "None", in which case
+   the C pointer is set to "NULL".
+
+"z*" ("str", *bytes-like object* or "None") [Py_buffer]
+   Like "s*", but the Python object may also be "None", in which case
+   the "buf" member of the "Py_buffer" structure is set to "NULL".
+
+"z#" ("str", read-only *bytes-like object* or "None") [const char *,
+"Py_ssize_t"]
+   Like "s#", but the Python object may also be "None", in which case
+   the C pointer is set to "NULL".
+
+"y" (read-only *bytes-like object*) [const char *]
+   This format converts a bytes-like object to a C pointer to a
+   borrowed character string; it does not accept Unicode objects.  The
+   bytes buffer must not contain embedded null bytes; if it does, a
+   "ValueError" exception is raised.
+
+   Changed in version 3.5: Previously, "TypeError" was raised when
+   embedded null bytes were encountered in the bytes buffer.
+
+"y*" (*bytes-like object*) [Py_buffer]
+   This variant on "s*" doesn't accept Unicode objects, only bytes-
+   like objects.  **This is the recommended way to accept binary
+   data.**
+
+"y#" (read-only *bytes-like object*) [const char *, "Py_ssize_t"]
+   This variant on "s#" doesn't accept Unicode objects, only bytes-
+   like objects.
+
+"S" ("bytes") [PyBytesObject *]
+   Requires that the Python object is a "bytes" object, without
+   attempting any conversion.  Raises "TypeError" if the object is not
+   a bytes object.  The C variable may also be declared as PyObject*.
+
+"Y" ("bytearray") [PyByteArrayObject *]
+   Requires that the Python object is a "bytearray" object, without
+   attempting any conversion.  Raises "TypeError" if the object is not
+   a "bytearray" object. The C variable may also be declared as
+   PyObject*.
+
+"U" ("str") [PyObject *]
+   Requires that the Python object is a Unicode object, without
+   attempting any conversion.  Raises "TypeError" if the object is not
+   a Unicode object.  The C variable may also be declared as
+   PyObject*.
+
+"w*" (read-write *bytes-like object*) [Py_buffer]
+   This format accepts any object which implements the read-write
+   buffer interface. It fills a "Py_buffer" structure provided by the
+   caller. The buffer may contain embedded null bytes. The caller have
+   to call "PyBuffer_Release()" when it is done with the buffer.
+
+"es" ("str") [const char *encoding, char **buffer]
+   This variant on "s" is used for encoding Unicode into a character
+   buffer. It only works for encoded data without embedded NUL bytes.
+
+   This format requires two arguments.  The first is only used as
+   input, and must be a const char* which points to the name of an
+   encoding as a NUL-terminated string, or "NULL", in which case
+   "'utf-8'" encoding is used. An exception is raised if the named
+   encoding is not known to Python.  The second argument must be a
+   char**; the value of the pointer it references will be set to a
+   buffer with the contents of the argument text. The text will be
+   encoded in the encoding specified by the first argument.
+
+   "PyArg_ParseTuple()" will allocate a buffer of the needed size,
+   copy the encoded data into this buffer and adjust **buffer* to
+   reference the newly allocated storage.  The caller is responsible
+   for calling "PyMem_Free()" to free the allocated buffer after use.
+
+"et" ("str", "bytes" or "bytearray") [const char *encoding, char
+**buffer]
+   Same as "es" except that byte string objects are passed through
+   without recoding them.  Instead, the implementation assumes that
+   the byte string object uses the encoding passed in as parameter.
+
+"es#" ("str") [const char *encoding, char **buffer, "Py_ssize_t"
+*buffer_length]
+   This variant on "s#" is used for encoding Unicode into a character
+   buffer. Unlike the "es" format, this variant allows input data
+   which contains NUL characters.
+
+   It requires three arguments.  The first is only used as input, and
+   must be a const char* which points to the name of an encoding as a
+   NUL-terminated string, or "NULL", in which case "'utf-8'" encoding
+   is used. An exception is raised if the named encoding is not known
+   to Python.  The second argument must be a char**; the value of the
+   pointer it references will be set to a buffer with the contents of
+   the argument text. The text will be encoded in the encoding
+   specified by the first argument. The third argument must be a
+   pointer to an integer; the referenced integer will be set to the
+   number of bytes in the output buffer.
+
+   There are two modes of operation:
+
+   If **buffer* points a "NULL" pointer, the function will allocate a
+   buffer of the needed size, copy the encoded data into this buffer
+   and set **buffer* to reference the newly allocated storage.  The
+   caller is responsible for calling "PyMem_Free()" to free the
+   allocated buffer after usage.
+
+   If **buffer* points to a non-"NULL" pointer (an already allocated
+   buffer), "PyArg_ParseTuple()" will use this location as the buffer
+   and interpret the initial value of **buffer_length* as the buffer
+   size.  It will then copy the encoded data into the buffer and NUL-
+   terminate it.  If the buffer is not large enough, a "ValueError"
+   will be set.
+
+   In both cases, **buffer_length* is set to the length of the encoded
+   data without the trailing NUL byte.
+
+"et#" ("str", "bytes" or "bytearray") [const char *encoding, char
+**buffer, "Py_ssize_t" *buffer_length]
+   Same as "es#" except that byte string objects are passed through
+   without recoding them. Instead, the implementation assumes that the
+   byte string object uses the encoding passed in as parameter.
+
+Changed in version 3.12: "u", "u#", "Z", and "Z#" are removed because
+they used a legacy "Py_UNICODE*" representation.
+
+
+Numbers
+-------
+
+"b" ("int") [unsigned char]
+   Convert a nonnegative Python integer to an unsigned tiny int,
+   stored in a C unsigned char.
+
+"B" ("int") [unsigned char]
+   Convert a Python integer to a tiny int without overflow checking,
+   stored in a C unsigned char.
+
+"h" ("int") [short int]
+   Convert a Python integer to a C short int.
+
+"H" ("int") [unsigned short int]
+   Convert a Python integer to a C unsigned short int, without
+   overflow checking.
+
+"i" ("int") [int]
+   Convert a Python integer to a plain C int.
+
+"I" ("int") [unsigned int]
+   Convert a Python integer to a C unsigned int, without overflow
+   checking.
+
+"l" ("int") [long int]
+   Convert a Python integer to a C long int.
+
+"k" ("int") [unsigned long]
+   Convert a Python integer to a C unsigned long without overflow
+   checking.
+
+"L" ("int") [long long]
+   Convert a Python integer to a C long long.
+
+"K" ("int") [unsigned long long]
+   Convert a Python integer to a C unsigned long long without overflow
+   checking.
+
+"n" ("int") ["Py_ssize_t"]
+   Convert a Python integer to a C "Py_ssize_t".
+
+"c" ("bytes" or "bytearray" of length 1) [char]
+   Convert a Python byte, represented as a "bytes" or "bytearray"
+   object of length 1, to a C char.
+
+   Changed in version 3.3: Allow "bytearray" objects.
+
+"C" ("str" of length 1) [int]
+   Convert a Python character, represented as a "str" object of length
+   1, to a C int.
+
+"f" ("float") [float]
+   Convert a Python floating-point number to a C float.
+
+"d" ("float") [double]
+   Convert a Python floating-point number to a C double.
+
+"D" ("complex") [Py_complex]
+   Convert a Python complex number to a C "Py_complex" structure.
+
+
+Other objects
+-------------
+
+"O" (object) [PyObject *]
+   Store a Python object (without any conversion) in a C object
+   pointer.  The C program thus receives the actual object that was
+   passed.  A new *strong reference* to the object is not created
+   (i.e. its reference count is not increased). The pointer stored is
+   not "NULL".
+
+"O!" (object) [*typeobject*, PyObject *]
+   Store a Python object in a C object pointer.  This is similar to
+   "O", but takes two C arguments: the first is the address of a
+   Python type object, the second is the address of the C variable (of
+   type PyObject*) into which the object pointer is stored.  If the
+   Python object does not have the required type, "TypeError" is
+   raised.
+
+"O&" (object) [*converter*, *anything*]
+   Convert a Python object to a C variable through a *converter*
+   function.  This takes two arguments: the first is a function, the
+   second is the address of a C variable (of arbitrary type),
+   converted to void*.  The *converter* function in turn is called as
+   follows:
+
+      status = converter(object, address);
+
+   where *object* is the Python object to be converted and *address*
+   is the void* argument that was passed to the "PyArg_Parse*"
+   function. The returned *status* should be "1" for a successful
+   conversion and "0" if the conversion has failed.  When the
+   conversion fails, the *converter* function should raise an
+   exception and leave the content of *address* unmodified.
+
+   If the *converter* returns "Py_CLEANUP_SUPPORTED", it may get
+   called a second time if the argument parsing eventually fails,
+   giving the converter a chance to release any memory that it had
+   already allocated. In this second call, the *object* parameter will
+   be "NULL"; *address* will have the same value as in the original
+   call.
+
+   Changed in version 3.1: "Py_CLEANUP_SUPPORTED" was added.
+
+"p" ("bool") [int]
+   Tests the value passed in for truth (a boolean **p**redicate) and
+   converts the result to its equivalent C true/false integer value.
+   Sets the int to "1" if the expression was true and "0" if it was
+   false. This accepts any valid Python value.  See Truth Value
+   Testing for more information about how Python tests values for
+   truth.
+
+   Added in version 3.3.
+
+"(items)" ("tuple") [*matching-items*]
+   The object must be a Python sequence whose length is the number of
+   format units in *items*.  The C arguments must correspond to the
+   individual format units in *items*.  Format units for sequences may
+   be nested.
+
+It is possible to pass "long" integers (integers whose value exceeds
+the platform's "LONG_MAX") however no proper range checking is done
+--- the most significant bits are silently truncated when the
+receiving field is too small to receive the value (actually, the
+semantics are inherited from downcasts in C --- your mileage may
+vary).
+
+A few other characters have a meaning in a format string.  These may
+not occur inside nested parentheses.  They are:
+
+"|"
+   Indicates that the remaining arguments in the Python argument list
+   are optional. The C variables corresponding to optional arguments
+   should be initialized to their default value --- when an optional
+   argument is not specified, "PyArg_ParseTuple()" does not touch the
+   contents of the corresponding C variable(s).
+
+"$"
+   "PyArg_ParseTupleAndKeywords()" only: Indicates that the remaining
+   arguments in the Python argument list are keyword-only.  Currently,
+   all keyword-only arguments must also be optional arguments, so "|"
+   must always be specified before "$" in the format string.
+
+   Added in version 3.3.
+
+":"
+   The list of format units ends here; the string after the colon is
+   used as the function name in error messages (the "associated value"
+   of the exception that "PyArg_ParseTuple()" raises).
+
+";"
+   The list of format units ends here; the string after the semicolon
+   is used as the error message *instead* of the default error
+   message.  ":" and ";" mutually exclude each other.
+
+Note that any Python object references which are provided to the
+caller are *borrowed* references; do not release them (i.e. do not
+decrement their reference count)!
+
+Additional arguments passed to these functions must be addresses of
+variables whose type is determined by the format string; these are
+used to store values from the input tuple.  There are a few cases, as
+described in the list of format units above, where these parameters
+are used as input values; they should match what is specified for the
+corresponding format unit in that case.
+
+For the conversion to succeed, the *arg* object must match the format
+and the format must be exhausted.  On success, the "PyArg_Parse*"
+functions return true, otherwise they return false and raise an
+appropriate exception. When the "PyArg_Parse*" functions fail due to
+conversion failure in one of the format units, the variables at the
+addresses corresponding to that and the following format units are
+left untouched.
+
+
+API Functions
+-------------
+
+int PyArg_ParseTuple(PyObject *args, const char *format, ...)
+    * Part of the Stable ABI.*
+
+   Parse the parameters of a function that takes only positional
+   parameters into local variables.  Returns true on success; on
+   failure, it returns false and raises the appropriate exception.
+
+int PyArg_VaParse(PyObject *args, const char *format, va_list vargs)
+    * Part of the Stable ABI.*
+
+   Identical to "PyArg_ParseTuple()", except that it accepts a va_list
+   rather than a variable number of arguments.
+
+int PyArg_ParseTupleAndKeywords(PyObject *args, PyObject *kw, const char *format, char *keywords[], ...)
+    * Part of the Stable ABI.*
+
+   Parse the parameters of a function that takes both positional and
+   keyword parameters into local variables.  The *keywords* argument
+   is a "NULL"-terminated array of keyword parameter names.  Empty
+   names denote positional-only parameters. Returns true on success;
+   on failure, it returns false and raises the appropriate exception.
+
+   Changed in version 3.6: Added support for positional-only
+   parameters.
+
+int PyArg_VaParseTupleAndKeywords(PyObject *args, PyObject *kw, const char *format, char *keywords[], va_list vargs)
+    * Part of the Stable ABI.*
+
+   Identical to "PyArg_ParseTupleAndKeywords()", except that it
+   accepts a va_list rather than a variable number of arguments.
+
+int PyArg_ValidateKeywordArguments(PyObject*)
+    * Part of the Stable ABI.*
+
+   Ensure that the keys in the keywords argument dictionary are
+   strings.  This is only needed if "PyArg_ParseTupleAndKeywords()" is
+   not used, since the latter already does this check.
+
+   Added in version 3.2.
+
+int PyArg_Parse(PyObject *args, const char *format, ...)
+    * Part of the Stable ABI.*
+
+   Function used to deconstruct the argument lists of "old-style"
+   functions --- these are functions which use the "METH_OLDARGS"
+   parameter parsing method, which has been removed in Python 3.  This
+   is not recommended for use in parameter parsing in new code, and
+   most code in the standard interpreter has been modified to no
+   longer use this for that purpose.  It does remain a convenient way
+   to decompose other tuples, however, and may continue to be used for
+   that purpose.
+
+int PyArg_UnpackTuple(PyObject *args, const char *name, Py_ssize_t min, Py_ssize_t max, ...)
+    * Part of the Stable ABI.*
+
+   A simpler form of parameter retrieval which does not use a format
+   string to specify the types of the arguments.  Functions which use
+   this method to retrieve their parameters should be declared as
+   "METH_VARARGS" in function or method tables.  The tuple containing
+   the actual parameters should be passed as *args*; it must actually
+   be a tuple.  The length of the tuple must be at least *min* and no
+   more than *max*; *min* and *max* may be equal.  Additional
+   arguments must be passed to the function, each of which should be a
+   pointer to a PyObject* variable; these will be filled in with the
+   values from *args*; they will contain *borrowed references*. The
+   variables which correspond to optional parameters not given by
+   *args* will not be filled in; these should be initialized by the
+   caller. This function returns true on success and false if *args*
+   is not a tuple or contains the wrong number of elements; an
+   exception will be set if there was a failure.
+
+   This is an example of the use of this function, taken from the
+   sources for the "_weakref" helper module for weak references:
+
+      static PyObject *
+      weakref_ref(PyObject *self, PyObject *args)
+      {
+          PyObject *object;
+          PyObject *callback = NULL;
+          PyObject *result = NULL;
+
+          if (PyArg_UnpackTuple(args, "ref", 1, 2, &object, &callback)) {
+              result = PyWeakref_NewRef(object, callback);
+          }
+          return result;
+      }
+
+   The call to "PyArg_UnpackTuple()" in this example is entirely
+   equivalent to this call to "PyArg_ParseTuple()":
+
+      PyArg_ParseTuple(args, "O|O:ref", &object, &callback)
+
+
+Building values
+===============
+
+PyObject *Py_BuildValue(const char *format, ...)
+    *Return value: New reference.** Part of the Stable ABI.*
+
+   Create a new value based on a format string similar to those
+   accepted by the "PyArg_Parse*" family of functions and a sequence
+   of values.  Returns the value or "NULL" in the case of an error; an
+   exception will be raised if "NULL" is returned.
+
+   "Py_BuildValue()" does not always build a tuple.  It builds a tuple
+   only if its format string contains two or more format units.  If
+   the format string is empty, it returns "None"; if it contains
+   exactly one format unit, it returns whatever object is described by
+   that format unit.  To force it to return a tuple of size 0 or one,
+   parenthesize the format string.
+
+   When memory buffers are passed as parameters to supply data to
+   build objects, as for the "s" and "s#" formats, the required data
+   is copied.  Buffers provided by the caller are never referenced by
+   the objects created by "Py_BuildValue()".  In other words, if your
+   code invokes "malloc()" and passes the allocated memory to
+   "Py_BuildValue()", your code is responsible for calling "free()"
+   for that memory once "Py_BuildValue()" returns.
+
+   In the following description, the quoted form is the format unit;
+   the entry in (round) parentheses is the Python object type that the
+   format unit will return; and the entry in [square] brackets is the
+   type of the C value(s) to be passed.
+
+   The characters space, tab, colon and comma are ignored in format
+   strings (but not within format units such as "s#").  This can be
+   used to make long format strings a tad more readable.
+
+   "s" ("str" or "None") [const char *]
+      Convert a null-terminated C string to a Python "str" object
+      using "'utf-8'" encoding. If the C string pointer is "NULL",
+      "None" is used.
+
+   "s#" ("str" or "None") [const char *, "Py_ssize_t"]
+      Convert a C string and its length to a Python "str" object using
+      "'utf-8'" encoding. If the C string pointer is "NULL", the
+      length is ignored and "None" is returned.
+
+   "y" ("bytes") [const char *]
+      This converts a C string to a Python "bytes" object.  If the C
+      string pointer is "NULL", "None" is returned.
+
+   "y#" ("bytes") [const char *, "Py_ssize_t"]
+      This converts a C string and its lengths to a Python object.  If
+      the C string pointer is "NULL", "None" is returned.
+
+   "z" ("str" or "None") [const char *]
+      Same as "s".
+
+   "z#" ("str" or "None") [const char *, "Py_ssize_t"]
+      Same as "s#".
+
+   "u" ("str") [const wchar_t *]
+      Convert a null-terminated "wchar_t" buffer of Unicode (UTF-16 or
+      UCS-4) data to a Python Unicode object.  If the Unicode buffer
+      pointer is "NULL", "None" is returned.
+
+   "u#" ("str") [const wchar_t *, "Py_ssize_t"]
+      Convert a Unicode (UTF-16 or UCS-4) data buffer and its length
+      to a Python Unicode object.   If the Unicode buffer pointer is
+      "NULL", the length is ignored and "None" is returned.
+
+   "U" ("str" or "None") [const char *]
+      Same as "s".
+
+   "U#" ("str" or "None") [const char *, "Py_ssize_t"]
+      Same as "s#".
+
+   "i" ("int") [int]
+      Convert a plain C int to a Python integer object.
+
+   "b" ("int") [char]
+      Convert a plain C char to a Python integer object.
+
+   "h" ("int") [short int]
+      Convert a plain C short int to a Python integer object.
+
+   "l" ("int") [long int]
+      Convert a C long int to a Python integer object.
+
+   "B" ("int") [unsigned char]
+      Convert a C unsigned char to a Python integer object.
+
+   "H" ("int") [unsigned short int]
+      Convert a C unsigned short int to a Python integer object.
+
+   "I" ("int") [unsigned int]
+      Convert a C unsigned int to a Python integer object.
+
+   "k" ("int") [unsigned long]
+      Convert a C unsigned long to a Python integer object.
+
+   "L" ("int") [long long]
+      Convert a C long long to a Python integer object.
+
+   "K" ("int") [unsigned long long]
+      Convert a C unsigned long long to a Python integer object.
+
+   "n" ("int") ["Py_ssize_t"]
+      Convert a C "Py_ssize_t" to a Python integer.
+
+   "c" ("bytes" of length 1) [char]
+      Convert a C int representing a byte to a Python "bytes" object
+      of length 1.
+
+   "C" ("str" of length 1) [int]
+      Convert a C int representing a character to Python "str" object
+      of length 1.
+
+   "d" ("float") [double]
+      Convert a C double to a Python floating-point number.
+
+   "f" ("float") [float]
+      Convert a C float to a Python floating-point number.
+
+   "D" ("complex") [Py_complex *]
+      Convert a C "Py_complex" structure to a Python complex number.
+
+   "O" (object) [PyObject *]
+      Pass a Python object untouched but create a new *strong
+      reference* to it (i.e. its reference count is incremented by
+      one). If the object passed in is a "NULL" pointer, it is assumed
+      that this was caused because the call producing the argument
+      found an error and set an exception. Therefore,
+      "Py_BuildValue()" will return "NULL" but won't raise an
+      exception.  If no exception has been raised yet, "SystemError"
+      is set.
+
+   "S" (object) [PyObject *]
+      Same as "O".
+
+   "N" (object) [PyObject *]
+      Same as "O", except it doesn't create a new *strong reference*.
+      Useful when the object is created by a call to an object
+      constructor in the argument list.
+
+   "O&" (object) [*converter*, *anything*]
+      Convert *anything* to a Python object through a *converter*
+      function.  The function is called with *anything* (which should
+      be compatible with void*) as its argument and should return a
+      "new" Python object, or "NULL" if an error occurred.
+
+   "(items)" ("tuple") [*matching-items*]
+      Convert a sequence of C values to a Python tuple with the same
+      number of items.
+
+   "[items]" ("list") [*matching-items*]
+      Convert a sequence of C values to a Python list with the same
+      number of items.
+
+   "{items}" ("dict") [*matching-items*]
+      Convert a sequence of C values to a Python dictionary.  Each
+      pair of consecutive C values adds one item to the dictionary,
+      serving as key and value, respectively.
+
+   If there is an error in the format string, the "SystemError"
+   exception is set and "NULL" returned.
+
+PyObject *Py_VaBuildValue(const char *format, va_list vargs)
+    *Return value: New reference.** Part of the Stable ABI.*
+
+   Identical to "Py_BuildValue()", except that it accepts a va_list
+   rather than a variable number of arguments.

python-3.12.6-docs-text/python-3.12.6-docs-text/c-api/bool.txt

@@ -0,0 +1,46 @@
+Boolean Objects
+***************
+
+Booleans in Python are implemented as a subclass of integers.  There
+are only two booleans, "Py_False" and "Py_True".  As such, the normal
+creation and deletion functions don't apply to booleans.  The
+following macros are available, however.
+
+PyTypeObject PyBool_Type
+    * Part of the Stable ABI.*
+
+   This instance of "PyTypeObject" represents the Python boolean type;
+   it is the same object as "bool" in the Python layer.
+
+int PyBool_Check(PyObject *o)
+
+   Return true if *o* is of type "PyBool_Type".  This function always
+   succeeds.
+
+PyObject *Py_False
+
+   The Python "False" object.  This object has no methods and is
+   immortal.
+
+Changed in version 3.12: "Py_False" is immortal.
+
+PyObject *Py_True
+
+   The Python "True" object.  This object has no methods and is
+   immortal.
+
+Changed in version 3.12: "Py_True" is immortal.
+
+Py_RETURN_FALSE
+
+   Return "Py_False" from a function.
+
+Py_RETURN_TRUE
+
+   Return "Py_True" from a function.
+
+PyObject *PyBool_FromLong(long v)
+    *Return value: New reference.** Part of the Stable ABI.*
+
+   Return "Py_True" or "Py_False", depending on the truth value of
+   *v*.

python-3.12.6-docs-text/python-3.12.6-docs-text/c-api/buffer.txt

@@ -0,0 +1,520 @@
+Buffer Protocol
+***************
+
+Certain objects available in Python wrap access to an underlying
+memory array or *buffer*.  Such objects include the built-in "bytes"
+and "bytearray", and some extension types like "array.array". Third-
+party libraries may define their own types for special purposes, such
+as image processing or numeric analysis.
+
+While each of these types have their own semantics, they share the
+common characteristic of being backed by a possibly large memory
+buffer.  It is then desirable, in some situations, to access that
+buffer directly and without intermediate copying.
+
+Python provides such a facility at the C level in the form of the
+buffer protocol.  This protocol has two sides:
+
+* on the producer side, a type can export a "buffer interface" which
+  allows objects of that type to expose information about their
+  underlying buffer. This interface is described in the section Buffer
+  Object Structures;
+
+* on the consumer side, several means are available to obtain a
+  pointer to the raw underlying data of an object (for example a
+  method parameter).
+
+Simple objects such as "bytes" and "bytearray" expose their underlying
+buffer in byte-oriented form.  Other forms are possible; for example,
+the elements exposed by an "array.array" can be multi-byte values.
+
+An example consumer of the buffer interface is the "write()" method of
+file objects: any object that can export a series of bytes through the
+buffer interface can be written to a file.  While "write()" only needs
+read-only access to the internal contents of the object passed to it,
+other methods such as "readinto()" need write access to the contents
+of their argument.  The buffer interface allows objects to selectively
+allow or reject exporting of read-write and read-only buffers.
+
+There are two ways for a consumer of the buffer interface to acquire a
+buffer over a target object:
+
+* call "PyObject_GetBuffer()" with the right parameters;
+
+* call "PyArg_ParseTuple()" (or one of its siblings) with one of the
+  "y*", "w*" or "s*" format codes.
+
+In both cases, "PyBuffer_Release()" must be called when the buffer
+isn't needed anymore.  Failure to do so could lead to various issues
+such as resource leaks.
+
+
+Buffer structure
+================
+
+Buffer structures (or simply "buffers") are useful as a way to expose
+the binary data from another object to the Python programmer.  They
+can also be used as a zero-copy slicing mechanism.  Using their
+ability to reference a block of memory, it is possible to expose any
+data to the Python programmer quite easily.  The memory could be a
+large, constant array in a C extension, it could be a raw block of
+memory for manipulation before passing to an operating system library,
+or it could be used to pass around structured data in its native, in-
+memory format.
+
+Contrary to most data types exposed by the Python interpreter, buffers
+are not "PyObject" pointers but rather simple C structures.  This
+allows them to be created and copied very simply.  When a generic
+wrapper around a buffer is needed, a memoryview object can be created.
+
+For short instructions how to write an exporting object, see Buffer
+Object Structures. For obtaining a buffer, see "PyObject_GetBuffer()".
+
+type Py_buffer
+    * Part of the Stable ABI (including all members) since version
+   3.11.*
+
+   void *buf
+
+      A pointer to the start of the logical structure described by the
+      buffer fields. This can be any location within the underlying
+      physical memory block of the exporter. For example, with
+      negative "strides" the value may point to the end of the memory
+      block.
+
+      For *contiguous* arrays, the value points to the beginning of
+      the memory block.
+
+   PyObject *obj
+
+      A new reference to the exporting object. The reference is owned
+      by the consumer and automatically released (i.e. reference count
+      decremented) and set to "NULL" by "PyBuffer_Release()". The
+      field is the equivalent of the return value of any standard
+      C-API function.
+
+      As a special case, for *temporary* buffers that are wrapped by
+      "PyMemoryView_FromBuffer()" or "PyBuffer_FillInfo()" this field
+      is "NULL". In general, exporting objects MUST NOT use this
+      scheme.
+
+   Py_ssize_t len
+
+      "product(shape) * itemsize". For contiguous arrays, this is the
+      length of the underlying memory block. For non-contiguous
+      arrays, it is the length that the logical structure would have
+      if it were copied to a contiguous representation.
+
+      Accessing "((char *)buf)[0] up to ((char *)buf)[len-1]" is only
+      valid if the buffer has been obtained by a request that
+      guarantees contiguity. In most cases such a request will be
+      "PyBUF_SIMPLE" or "PyBUF_WRITABLE".
+
+   int readonly
+
+      An indicator of whether the buffer is read-only. This field is
+      controlled by the "PyBUF_WRITABLE" flag.
+
+   Py_ssize_t itemsize
+
+      Item size in bytes of a single element. Same as the value of
+      "struct.calcsize()" called on non-"NULL" "format" values.
+
+      Important exception: If a consumer requests a buffer without the
+      "PyBUF_FORMAT" flag, "format" will be set to  "NULL",  but
+      "itemsize" still has the value for the original format.
+
+      If "shape" is present, the equality "product(shape) * itemsize
+      == len" still holds and the consumer can use "itemsize" to
+      navigate the buffer.
+
+      If "shape" is "NULL" as a result of a "PyBUF_SIMPLE" or a
+      "PyBUF_WRITABLE" request, the consumer must disregard "itemsize"
+      and assume "itemsize == 1".
+
+   char *format
+
+      A *NULL* terminated string in "struct" module style syntax
+      describing the contents of a single item. If this is "NULL",
+      ""B"" (unsigned bytes) is assumed.
+
+      This field is controlled by the "PyBUF_FORMAT" flag.
+
+   int ndim
+
+      The number of dimensions the memory represents as an
+      n-dimensional array. If it is "0", "buf" points to a single item
+      representing a scalar. In this case, "shape", "strides" and
+      "suboffsets" MUST be "NULL". The maximum number of dimensions is
+      given by "PyBUF_MAX_NDIM".
+
+   Py_ssize_t *shape
+
+      An array of "Py_ssize_t" of length "ndim" indicating the shape
+      of the memory as an n-dimensional array. Note that "shape[0] *
+      ... * shape[ndim-1] * itemsize" MUST be equal to "len".
+
+      Shape values are restricted to "shape[n] >= 0". The case
+      "shape[n] == 0" requires special attention. See complex arrays
+      for further information.
+
+      The shape array is read-only for the consumer.
+
+   Py_ssize_t *strides
+
+      An array of "Py_ssize_t" of length "ndim" giving the number of
+      bytes to skip to get to a new element in each dimension.
+
+      Stride values can be any integer. For regular arrays, strides
+      are usually positive, but a consumer MUST be able to handle the
+      case "strides[n] <= 0". See complex arrays for further
+      information.
+
+      The strides array is read-only for the consumer.
+
+   Py_ssize_t *suboffsets
+
+      An array of "Py_ssize_t" of length "ndim". If "suboffsets[n] >=
+      0", the values stored along the nth dimension are pointers and
+      the suboffset value dictates how many bytes to add to each
+      pointer after de-referencing. A suboffset value that is negative
+      indicates that no de-referencing should occur (striding in a
+      contiguous memory block).
+
+      If all suboffsets are negative (i.e. no de-referencing is
+      needed), then this field must be "NULL" (the default value).
+
+      This type of array representation is used by the Python Imaging
+      Library (PIL). See complex arrays for further information how to
+      access elements of such an array.
+
+      The suboffsets array is read-only for the consumer.
+
+   void *internal
+
+      This is for use internally by the exporting object. For example,
+      this might be re-cast as an integer by the exporter and used to
+      store flags about whether or not the shape, strides, and
+      suboffsets arrays must be freed when the buffer is released. The
+      consumer MUST NOT alter this value.
+
+Constants:
+
+PyBUF_MAX_NDIM
+
+   The maximum number of dimensions the memory represents. Exporters
+   MUST respect this limit, consumers of multi-dimensional buffers
+   SHOULD be able to handle up to "PyBUF_MAX_NDIM" dimensions.
+   Currently set to 64.
+
+
+Buffer request types
+====================
+
+Buffers are usually obtained by sending a buffer request to an
+exporting object via "PyObject_GetBuffer()". Since the complexity of
+the logical structure of the memory can vary drastically, the consumer
+uses the *flags* argument to specify the exact buffer type it can
+handle.
+
+All "Py_buffer" fields are unambiguously defined by the request type.
+
+
+request-independent fields
+--------------------------
+
+The following fields are not influenced by *flags* and must always be
+filled in with the correct values: "obj", "buf", "len", "itemsize",
+"ndim".
+
+
+readonly, format
+----------------
+
+   PyBUF_WRITABLE
+
+      Controls the "readonly" field. If set, the exporter MUST provide
+      a writable buffer or else report failure. Otherwise, the
+      exporter MAY provide either a read-only or writable buffer, but
+      the choice MUST be consistent for all consumers.
+
+   PyBUF_FORMAT
+
+      Controls the "format" field. If set, this field MUST be filled
+      in correctly. Otherwise, this field MUST be "NULL".
+
+"PyBUF_WRITABLE" can be |'d to any of the flags in the next section.
+Since "PyBUF_SIMPLE" is defined as 0, "PyBUF_WRITABLE" can be used as
+a stand-alone flag to request a simple writable buffer.
+
+"PyBUF_FORMAT" can be |'d to any of the flags except "PyBUF_SIMPLE".
+The latter already implies format "B" (unsigned bytes).
+
+
+shape, strides, suboffsets
+--------------------------
+
+The flags that control the logical structure of the memory are listed
+in decreasing order of complexity. Note that each flag contains all
+bits of the flags below it.
+
++-------------------------------+---------+-----------+--------------+
+| Request                       | shape   | strides   | suboffsets   |
+|===============================|=========|===========|==============|
+| PyBUF_INDIRECT                | yes     | yes       | if needed    |
++-------------------------------+---------+-----------+--------------+
+| PyBUF_STRIDES                 | yes     | yes       | NULL         |
++-------------------------------+---------+-----------+--------------+
+| PyBUF_ND                      | yes     | NULL      | NULL         |
++-------------------------------+---------+-----------+--------------+
+| PyBUF_SIMPLE                  | NULL    | NULL      | NULL         |
++-------------------------------+---------+-----------+--------------+
+
+
+contiguity requests
+-------------------
+
+C or Fortran *contiguity* can be explicitly requested, with and
+without stride information. Without stride information, the buffer
+must be C-contiguous.
+
++-------------------------------------+---------+-----------+--------------+----------+
+| Request                             | shape   | strides   | suboffsets   | contig   |
+|=====================================|=========|===========|==============|==========|
+| PyBUF_C_CONTIGUOUS                  | yes     | yes       | NULL         | C        |
++-------------------------------------+---------+-----------+--------------+----------+
+| PyBUF_F_CONTIGUOUS                  | yes     | yes       | NULL         | F        |
++-------------------------------------+---------+-----------+--------------+----------+
+| PyBUF_ANY_CONTIGUOUS                | yes     | yes       | NULL         | C or F   |
++-------------------------------------+---------+-----------+--------------+----------+
+| "PyBUF_ND"                          | yes     | NULL      | NULL         | C        |
++-------------------------------------+---------+-----------+--------------+----------+
+
+
+compound requests
+-----------------
+
+All possible requests are fully defined by some combination of the
+flags in the previous section. For convenience, the buffer protocol
+provides frequently used combinations as single flags.
+
+In the following table *U* stands for undefined contiguity. The
+consumer would have to call "PyBuffer_IsContiguous()" to determine
+contiguity.
+
++---------------------------------+---------+-----------+--------------+----------+------------+----------+
+| Request                         | shape   | strides   | suboffsets   | contig   | readonly   | format   |
+|=================================|=========|===========|==============|==========|============|==========|
+| PyBUF_FULL                      | yes     | yes       | if needed    | U        | 0          | yes      |
++---------------------------------+---------+-----------+--------------+----------+------------+----------+
+| PyBUF_FULL_RO                   | yes     | yes       | if needed    | U        | 1 or 0     | yes      |
++---------------------------------+---------+-----------+--------------+----------+------------+----------+
+| PyBUF_RECORDS                   | yes     | yes       | NULL         | U        | 0          | yes      |
++---------------------------------+---------+-----------+--------------+----------+------------+----------+
+| PyBUF_RECORDS_RO                | yes     | yes       | NULL         | U        | 1 or 0     | yes      |
++---------------------------------+---------+-----------+--------------+----------+------------+----------+
+| PyBUF_STRIDED                   | yes     | yes       | NULL         | U        | 0          | NULL     |
++---------------------------------+---------+-----------+--------------+----------+------------+----------+
+| PyBUF_STRIDED_RO                | yes     | yes       | NULL         | U        | 1 or 0     | NULL     |
++---------------------------------+---------+-----------+--------------+----------+------------+----------+
+| PyBUF_CONTIG                    | yes     | NULL      | NULL         | C        | 0          | NULL     |
++---------------------------------+---------+-----------+--------------+----------+------------+----------+
+| PyBUF_CONTIG_RO                 | yes     | NULL      | NULL         | C        | 1 or 0     | NULL     |
++---------------------------------+---------+-----------+--------------+----------+------------+----------+
+
+
+Complex arrays
+==============
+
+
+NumPy-style: shape and strides
+------------------------------
+
+The logical structure of NumPy-style arrays is defined by "itemsize",
+"ndim", "shape" and "strides".
+
+If "ndim == 0", the memory location pointed to by "buf" is interpreted
+as a scalar of size "itemsize". In that case, both "shape" and
+"strides" are "NULL".
+
+If "strides" is "NULL", the array is interpreted as a standard
+n-dimensional C-array. Otherwise, the consumer must access an
+n-dimensional array as follows:
+
+   ptr = (char *)buf + indices[0] * strides[0] + ... + indices[n-1] * strides[n-1];
+   item = *((typeof(item) *)ptr);
+
+As noted above, "buf" can point to any location within the actual
+memory block. An exporter can check the validity of a buffer with this
+function:
+
+   def verify_structure(memlen, itemsize, ndim, shape, strides, offset):
+       """Verify that the parameters represent a valid array within
+          the bounds of the allocated memory:
+              char *mem: start of the physical memory block
+              memlen: length of the physical memory block
+              offset: (char *)buf - mem
+       """
+       if offset % itemsize:
+           return False
+       if offset < 0 or offset+itemsize > memlen:
+           return False
+       if any(v % itemsize for v in strides):
+           return False
+
+       if ndim <= 0:
+           return ndim == 0 and not shape and not strides
+       if 0 in shape:
+           return True
+
+       imin = sum(strides[j]*(shape[j]-1) for j in range(ndim)
+                  if strides[j] <= 0)
+       imax = sum(strides[j]*(shape[j]-1) for j in range(ndim)
+                  if strides[j] > 0)
+
+       return 0 <= offset+imin and offset+imax+itemsize <= memlen
+
+
+PIL-style: shape, strides and suboffsets
+----------------------------------------
+
+In addition to the regular items, PIL-style arrays can contain
+pointers that must be followed in order to get to the next element in
+a dimension. For example, the regular three-dimensional C-array "char
+v[2][2][3]" can also be viewed as an array of 2 pointers to 2 two-
+dimensional arrays: "char (*v[2])[2][3]". In suboffsets
+representation, those two pointers can be embedded at the start of
+"buf", pointing to two "char x[2][3]" arrays that can be located
+anywhere in memory.
+
+Here is a function that returns a pointer to the element in an N-D
+array pointed to by an N-dimensional index when there are both
+non-"NULL" strides and suboffsets:
+
+   void *get_item_pointer(int ndim, void *buf, Py_ssize_t *strides,
+                          Py_ssize_t *suboffsets, Py_ssize_t *indices) {
+       char *pointer = (char*)buf;
+       int i;
+       for (i = 0; i < ndim; i++) {
+           pointer += strides[i] * indices[i];
+           if (suboffsets[i] >=0 ) {
+               pointer = *((char**)pointer) + suboffsets[i];
+           }
+       }
+       return (void*)pointer;
+   }
+
+
+Buffer-related functions
+========================
+
+int PyObject_CheckBuffer(PyObject *obj)
+    * Part of the Stable ABI since version 3.11.*
+
+   Return "1" if *obj* supports the buffer interface otherwise "0".
+   When "1" is returned, it doesn't guarantee that
+   "PyObject_GetBuffer()" will succeed.  This function always
+   succeeds.
+
+int PyObject_GetBuffer(PyObject *exporter, Py_buffer *view, int flags)
+    * Part of the Stable ABI since version 3.11.*
+
+   Send a request to *exporter* to fill in *view* as specified by
+   *flags*. If the exporter cannot provide a buffer of the exact type,
+   it MUST raise "BufferError", set "view->obj" to "NULL" and return
+   "-1".
+
+   On success, fill in *view*, set "view->obj" to a new reference to
+   *exporter* and return 0. In the case of chained buffer providers
+   that redirect requests to a single object, "view->obj" MAY refer to
+   this object instead of *exporter* (See Buffer Object Structures).
+
+   Successful calls to "PyObject_GetBuffer()" must be paired with
+   calls to "PyBuffer_Release()", similar to "malloc()" and "free()".
+   Thus, after the consumer is done with the buffer,
+   "PyBuffer_Release()" must be called exactly once.
+
+void PyBuffer_Release(Py_buffer *view)
+    * Part of the Stable ABI since version 3.11.*
+
+   Release the buffer *view* and release the *strong reference* (i.e.
+   decrement the reference count) to the view's supporting object,
+   "view->obj". This function MUST be called when the buffer is no
+   longer being used, otherwise reference leaks may occur.
+
+   It is an error to call this function on a buffer that was not
+   obtained via "PyObject_GetBuffer()".
+
+Py_ssize_t PyBuffer_SizeFromFormat(const char *format)
+    * Part of the Stable ABI since version 3.11.*
+
+   Return the implied "itemsize" from "format". On error, raise an
+   exception and return -1.
+
+   Added in version 3.9.
+
+int PyBuffer_IsContiguous(const Py_buffer *view, char order)
+    * Part of the Stable ABI since version 3.11.*
+
+   Return "1" if the memory defined by the *view* is C-style (*order*
+   is "'C'") or Fortran-style (*order* is "'F'") *contiguous* or
+   either one (*order* is "'A'").  Return "0" otherwise.  This
+   function always succeeds.
+
+void *PyBuffer_GetPointer(const Py_buffer *view, const Py_ssize_t *indices)
+    * Part of the Stable ABI since version 3.11.*
+
+   Get the memory area pointed to by the *indices* inside the given
+   *view*. *indices* must point to an array of "view->ndim" indices.
+
+int PyBuffer_FromContiguous(const Py_buffer *view, const void *buf, Py_ssize_t len, char fort)
+    * Part of the Stable ABI since version 3.11.*
+
+   Copy contiguous *len* bytes from *buf* to *view*. *fort* can be
+   "'C'" or "'F'" (for C-style or Fortran-style ordering). "0" is
+   returned on success, "-1" on error.
+
+int PyBuffer_ToContiguous(void *buf, const Py_buffer *src, Py_ssize_t len, char order)
+    * Part of the Stable ABI since version 3.11.*
+
+   Copy *len* bytes from *src* to its contiguous representation in
+   *buf*. *order* can be "'C'" or "'F'" or "'A'" (for C-style or
+   Fortran-style ordering or either one). "0" is returned on success,
+   "-1" on error.
+
+   This function fails if *len* != *src->len*.
+
+int PyObject_CopyData(PyObject *dest, PyObject *src)
+    * Part of the Stable ABI since version 3.11.*
+
+   Copy data from *src* to *dest* buffer. Can convert between C-style
+   and or Fortran-style buffers.
+
+   "0" is returned on success, "-1" on error.
+
+void PyBuffer_FillContiguousStrides(int ndims, Py_ssize_t *shape, Py_ssize_t *strides, int itemsize, char order)
+    * Part of the Stable ABI since version 3.11.*
+
+   Fill the *strides* array with byte-strides of a *contiguous*
+   (C-style if *order* is "'C'" or Fortran-style if *order* is "'F'")
+   array of the given shape with the given number of bytes per
+   element.
+
+int PyBuffer_FillInfo(Py_buffer *view, PyObject *exporter, void *buf, Py_ssize_t len, int readonly, int flags)
+    * Part of the Stable ABI since version 3.11.*
+
+   Handle buffer requests for an exporter that wants to expose *buf*
+   of size *len* with writability set according to *readonly*. *buf*
+   is interpreted as a sequence of unsigned bytes.
+
+   The *flags* argument indicates the request type. This function
+   always fills in *view* as specified by flags, unless *buf* has been
+   designated as read-only and "PyBUF_WRITABLE" is set in *flags*.
+
+   On success, set "view->obj" to a new reference to *exporter* and
+   return 0. Otherwise, raise "BufferError", set "view->obj" to "NULL"
+   and return "-1";
+
+   If this function is used as part of a getbufferproc, *exporter*
+   MUST be set to the exporting object and *flags* must be passed
+   unmodified. Otherwise, *exporter* MUST be "NULL".

python-3.12.6-docs-text/python-3.12.6-docs-text/c-api/bytearray.txt

@@ -0,0 +1,85 @@
+Byte Array Objects
+******************
+
+type PyByteArrayObject
+
+   This subtype of "PyObject" represents a Python bytearray object.
+
+PyTypeObject PyByteArray_Type
+    * Part of the Stable ABI.*
+
+   This instance of "PyTypeObject" represents the Python bytearray
+   type; it is the same object as "bytearray" in the Python layer.
+
+
+Type check macros
+=================
+
+int PyByteArray_Check(PyObject *o)
+
+   Return true if the object *o* is a bytearray object or an instance
+   of a subtype of the bytearray type.  This function always succeeds.
+
+int PyByteArray_CheckExact(PyObject *o)
+
+   Return true if the object *o* is a bytearray object, but not an
+   instance of a subtype of the bytearray type.  This function always
+   succeeds.
+
+
+Direct API functions
+====================
+
+PyObject *PyByteArray_FromObject(PyObject *o)
+    *Return value: New reference.** Part of the Stable ABI.*
+
+   Return a new bytearray object from any object, *o*, that implements
+   the buffer protocol.
+
+   On failure, return "NULL" with an exception set.
+
+PyObject *PyByteArray_FromStringAndSize(const char *string, Py_ssize_t len)
+    *Return value: New reference.** Part of the Stable ABI.*
+
+   Create a new bytearray object from *string* and its length, *len*.
+
+   On failure, return "NULL" with an exception set.
+
+PyObject *PyByteArray_Concat(PyObject *a, PyObject *b)
+    *Return value: New reference.** Part of the Stable ABI.*
+
+   Concat bytearrays *a* and *b* and return a new bytearray with the
+   result.
+
+   On failure, return "NULL" with an exception set.
+
+Py_ssize_t PyByteArray_Size(PyObject *bytearray)
+    * Part of the Stable ABI.*
+
+   Return the size of *bytearray* after checking for a "NULL" pointer.
+
+char *PyByteArray_AsString(PyObject *bytearray)
+    * Part of the Stable ABI.*
+
+   Return the contents of *bytearray* as a char array after checking
+   for a "NULL" pointer.  The returned array always has an extra null
+   byte appended.
+
+int PyByteArray_Resize(PyObject *bytearray, Py_ssize_t len)
+    * Part of the Stable ABI.*
+
+   Resize the internal buffer of *bytearray* to *len*.
+
+
+Macros
+======
+
+These macros trade safety for speed and they don't check pointers.
+
+char *PyByteArray_AS_STRING(PyObject *bytearray)
+
+   Similar to "PyByteArray_AsString()", but without error checking.
+
+Py_ssize_t PyByteArray_GET_SIZE(PyObject *bytearray)
+
+   Similar to "PyByteArray_Size()", but without error checking.

python-3.12.6-docs-text/python-3.12.6-docs-text/c-api/bytes.txt

@@ -0,0 +1,188 @@
+Bytes Objects
+*************
+
+These functions raise "TypeError" when expecting a bytes parameter and
+called with a non-bytes parameter.
+
+type PyBytesObject
+
+   This subtype of "PyObject" represents a Python bytes object.
+
+PyTypeObject PyBytes_Type
+    * Part of the Stable ABI.*
+
+   This instance of "PyTypeObject" represents the Python bytes type;
+   it is the same object as "bytes" in the Python layer.
+
+int PyBytes_Check(PyObject *o)
+
+   Return true if the object *o* is a bytes object or an instance of a
+   subtype of the bytes type.  This function always succeeds.
+
+int PyBytes_CheckExact(PyObject *o)
+
+   Return true if the object *o* is a bytes object, but not an
+   instance of a subtype of the bytes type.  This function always
+   succeeds.
+
+PyObject *PyBytes_FromString(const char *v)
+    *Return value: New reference.** Part of the Stable ABI.*
+
+   Return a new bytes object with a copy of the string *v* as value on
+   success, and "NULL" on failure.  The parameter *v* must not be
+   "NULL"; it will not be checked.
+
+PyObject *PyBytes_FromStringAndSize(const char *v, Py_ssize_t len)
+    *Return value: New reference.** Part of the Stable ABI.*
+
+   Return a new bytes object with a copy of the string *v* as value
+   and length *len* on success, and "NULL" on failure.  If *v* is
+   "NULL", the contents of the bytes object are uninitialized.
+
+PyObject *PyBytes_FromFormat(const char *format, ...)
+    *Return value: New reference.** Part of the Stable ABI.*
+
+   Take a C "printf()"-style *format* string and a variable number of
+   arguments, calculate the size of the resulting Python bytes object
+   and return a bytes object with the values formatted into it.  The
+   variable arguments must be C types and must correspond exactly to
+   the format characters in the *format* string.  The following format
+   characters are allowed:
+
+   +---------------------+-----------------+----------------------------------+
+   | Format Characters   | Type            | Comment                          |
+   |=====================|=================|==================================|
+   | "%%"                | *n/a*           | The literal % character.         |
+   +---------------------+-----------------+----------------------------------+
+   | "%c"                | int             | A single byte, represented as a  |
+   |                     |                 | C int.                           |
+   +---------------------+-----------------+----------------------------------+
+   | "%d"                | int             | Equivalent to "printf("%d")".    |
+   |                     |                 | [1]                              |
+   +---------------------+-----------------+----------------------------------+
+   | "%u"                | unsigned int    | Equivalent to "printf("%u")".    |
+   |                     |                 | [1]                              |
+   +---------------------+-----------------+----------------------------------+
+   | "%ld"               | long            | Equivalent to "printf("%ld")".   |
+   |                     |                 | [1]                              |
+   +---------------------+-----------------+----------------------------------+
+   | "%lu"               | unsigned long   | Equivalent to "printf("%lu")".   |
+   |                     |                 | [1]                              |
+   +---------------------+-----------------+----------------------------------+
+   | "%zd"               | "Py_ssize_t"    | Equivalent to "printf("%zd")".   |
+   |                     |                 | [1]                              |
+   +---------------------+-----------------+----------------------------------+
+   | "%zu"               | size_t          | Equivalent to "printf("%zu")".   |
+   |                     |                 | [1]                              |
+   +---------------------+-----------------+----------------------------------+
+   | "%i"                | int             | Equivalent to "printf("%i")".    |
+   |                     |                 | [1]                              |
+   +---------------------+-----------------+----------------------------------+
+   | "%x"                | int             | Equivalent to "printf("%x")".    |
+   |                     |                 | [1]                              |
+   +---------------------+-----------------+----------------------------------+
+   | "%s"                | const char*     | A null-terminated C character    |
+   |                     |                 | array.                           |
+   +---------------------+-----------------+----------------------------------+
+   | "%p"                | const void*     | The hex representation of a C    |
+   |                     |                 | pointer. Mostly equivalent to    |
+   |                     |                 | "printf("%p")" except that it is |
+   |                     |                 | guaranteed to start with the     |
+   |                     |                 | literal "0x" regardless of what  |
+   |                     |                 | the platform's "printf" yields.  |
+   +---------------------+-----------------+----------------------------------+
+
+   An unrecognized format character causes all the rest of the format
+   string to be copied as-is to the result object, and any extra
+   arguments discarded.
+
+   [1] For integer specifiers (d, u, ld, lu, zd, zu, i, x): the
+       0-conversion flag has effect even when a precision is given.
+
+PyObject *PyBytes_FromFormatV(const char *format, va_list vargs)
+    *Return value: New reference.** Part of the Stable ABI.*
+
+   Identical to "PyBytes_FromFormat()" except that it takes exactly
+   two arguments.
+
+PyObject *PyBytes_FromObject(PyObject *o)
+    *Return value: New reference.** Part of the Stable ABI.*
+
+   Return the bytes representation of object *o* that implements the
+   buffer protocol.
+
+Py_ssize_t PyBytes_Size(PyObject *o)
+    * Part of the Stable ABI.*
+
+   Return the length of the bytes in bytes object *o*.
+
+Py_ssize_t PyBytes_GET_SIZE(PyObject *o)
+
+   Similar to "PyBytes_Size()", but without error checking.
+
+char *PyBytes_AsString(PyObject *o)
+    * Part of the Stable ABI.*
+
+   Return a pointer to the contents of *o*.  The pointer refers to the
+   internal buffer of *o*, which consists of "len(o) + 1" bytes.  The
+   last byte in the buffer is always null, regardless of whether there
+   are any other null bytes.  The data must not be modified in any
+   way, unless the object was just created using
+   "PyBytes_FromStringAndSize(NULL, size)". It must not be
+   deallocated.  If *o* is not a bytes object at all,
+   "PyBytes_AsString()" returns "NULL" and raises "TypeError".
+
+char *PyBytes_AS_STRING(PyObject *string)
+
+   Similar to "PyBytes_AsString()", but without error checking.
+
+int PyBytes_AsStringAndSize(PyObject *obj, char **buffer, Py_ssize_t *length)
+    * Part of the Stable ABI.*
+
+   Return the null-terminated contents of the object *obj* through the
+   output variables *buffer* and *length*. Returns "0" on success.
+
+   If *length* is "NULL", the bytes object may not contain embedded
+   null bytes; if it does, the function returns "-1" and a
+   "ValueError" is raised.
+
+   The buffer refers to an internal buffer of *obj*, which includes an
+   additional null byte at the end (not counted in *length*).  The
+   data must not be modified in any way, unless the object was just
+   created using "PyBytes_FromStringAndSize(NULL, size)".  It must not
+   be deallocated.  If *obj* is not a bytes object at all,
+   "PyBytes_AsStringAndSize()" returns "-1" and raises "TypeError".
+
+   Changed in version 3.5: Previously, "TypeError" was raised when
+   embedded null bytes were encountered in the bytes object.
+
+void PyBytes_Concat(PyObject **bytes, PyObject *newpart)
+    * Part of the Stable ABI.*
+
+   Create a new bytes object in **bytes* containing the contents of
+   *newpart* appended to *bytes*; the caller will own the new
+   reference.  The reference to the old value of *bytes* will be
+   stolen.  If the new object cannot be created, the old reference to
+   *bytes* will still be discarded and the value of **bytes* will be
+   set to "NULL"; the appropriate exception will be set.
+
+void PyBytes_ConcatAndDel(PyObject **bytes, PyObject *newpart)
+    * Part of the Stable ABI.*
+
+   Create a new bytes object in **bytes* containing the contents of
+   *newpart* appended to *bytes*.  This version releases the *strong
+   reference* to *newpart* (i.e. decrements its reference count).
+
+int _PyBytes_Resize(PyObject **bytes, Py_ssize_t newsize)
+
+   A way to resize a bytes object even though it is "immutable". Only
+   use this to build up a brand new bytes object; don't use this if
+   the bytes may already be known in other parts of the code.  It is
+   an error to call this function if the refcount on the input bytes
+   object is not one. Pass the address of an existing bytes object as
+   an lvalue (it may be written into), and the new size desired.  On
+   success, **bytes* holds the resized bytes object and "0" is
+   returned; the address in **bytes* may differ from its input value.
+   If the reallocation fails, the original bytes object at **bytes* is
+   deallocated, **bytes* is set to "NULL", "MemoryError" is set, and
+   "-1" is returned.

python-3.12.6-docs-text/python-3.12.6-docs-text/c-api/call.txt

@@ -0,0 +1,416 @@
+Call Protocol
+*************
+
+CPython supports two different calling protocols: *tp_call* and
+vectorcall.
+
+
+The *tp_call* Protocol
+======================
+
+Instances of classes that set "tp_call" are callable. The signature of
+the slot is:
+
+   PyObject *tp_call(PyObject *callable, PyObject *args, PyObject *kwargs);
+
+A call is made using a tuple for the positional arguments and a dict
+for the keyword arguments, similarly to "callable(*args, **kwargs)" in
+Python code. *args* must be non-NULL (use an empty tuple if there are
+no arguments) but *kwargs* may be *NULL* if there are no keyword
+arguments.
+
+This convention is not only used by *tp_call*: "tp_new" and "tp_init"
+also pass arguments this way.
+
+To call an object, use "PyObject_Call()" or another call API.
+
+
+The Vectorcall Protocol
+=======================
+
+Added in version 3.9.
+
+The vectorcall protocol was introduced in **PEP 590** as an additional
+protocol for making calls more efficient.
+
+As rule of thumb, CPython will prefer the vectorcall for internal
+calls if the callable supports it. However, this is not a hard rule.
+Additionally, some third-party extensions use *tp_call* directly
+(rather than using "PyObject_Call()"). Therefore, a class supporting
+vectorcall must also implement "tp_call". Moreover, the callable must
+behave the same regardless of which protocol is used. The recommended
+way to achieve this is by setting "tp_call" to "PyVectorcall_Call()".
+This bears repeating:
+
+Warning:
+
+  A class supporting vectorcall **must** also implement "tp_call" with
+  the same semantics.
+
+Changed in version 3.12: The "Py_TPFLAGS_HAVE_VECTORCALL" flag is now
+removed from a class when the class's "__call__()" method is
+reassigned. (This internally sets "tp_call" only, and thus may make it
+behave differently than the vectorcall function.) In earlier Python
+versions, vectorcall should only be used with "immutable" or static
+types.
+
+A class should not implement vectorcall if that would be slower than
+*tp_call*. For example, if the callee needs to convert the arguments
+to an args tuple and kwargs dict anyway, then there is no point in
+implementing vectorcall.
+
+Classes can implement the vectorcall protocol by enabling the
+"Py_TPFLAGS_HAVE_VECTORCALL" flag and setting "tp_vectorcall_offset"
+to the offset inside the object structure where a *vectorcallfunc*
+appears. This is a pointer to a function with the following signature:
+
+typedef PyObject *(*vectorcallfunc)(PyObject *callable, PyObject *const *args, size_t nargsf, PyObject *kwnames)
+    * Part of the Stable ABI since version 3.12.*
+
+* *callable* is the object being called.
+
+* *args* is a C array consisting of the positional arguments followed
+  by the
+     values of the keyword arguments. This can be *NULL* if there are
+     no arguments.
+
+* *nargsf* is the number of positional arguments plus possibly the
+     "PY_VECTORCALL_ARGUMENTS_OFFSET" flag. To get the actual number
+     of positional arguments from *nargsf*, use
+     "PyVectorcall_NARGS()".
+
+* *kwnames* is a tuple containing the names of the keyword arguments;
+     in other words, the keys of the kwargs dict. These names must be
+     strings (instances of "str" or a subclass) and they must be
+     unique. If there are no keyword arguments, then *kwnames* can
+     instead be *NULL*.
+
+PY_VECTORCALL_ARGUMENTS_OFFSET
+    * Part of the Stable ABI since version 3.12.*
+
+   If this flag is set in a vectorcall *nargsf* argument, the callee
+   is allowed to temporarily change "args[-1]". In other words, *args*
+   points to argument 1 (not 0) in the allocated vector. The callee
+   must restore the value of "args[-1]" before returning.
+
+   For "PyObject_VectorcallMethod()", this flag means instead that
+   "args[0]" may be changed.
+
+   Whenever they can do so cheaply (without additional allocation),
+   callers are encouraged to use "PY_VECTORCALL_ARGUMENTS_OFFSET".
+   Doing so will allow callables such as bound methods to make their
+   onward calls (which include a prepended *self* argument) very
+   efficiently.
+
+   Added in version 3.8.
+
+To call an object that implements vectorcall, use a call API function
+as with any other callable. "PyObject_Vectorcall()" will usually be
+most efficient.
+
+Note:
+
+  In CPython 3.8, the vectorcall API and related functions were
+  available provisionally under names with a leading underscore:
+  "_PyObject_Vectorcall", "_Py_TPFLAGS_HAVE_VECTORCALL",
+  "_PyObject_VectorcallMethod", "_PyVectorcall_Function",
+  "_PyObject_CallOneArg", "_PyObject_CallMethodNoArgs",
+  "_PyObject_CallMethodOneArg". Additionally,
+  "PyObject_VectorcallDict" was available as "_PyObject_FastCallDict".
+  The old names are still defined as aliases of the new, non-
+  underscored names.
+
+
+Recursion Control
+-----------------
+
+When using *tp_call*, callees do not need to worry about recursion:
+CPython uses "Py_EnterRecursiveCall()" and "Py_LeaveRecursiveCall()"
+for calls made using *tp_call*.
+
+For efficiency, this is not the case for calls done using vectorcall:
+the callee should use *Py_EnterRecursiveCall* and
+*Py_LeaveRecursiveCall* if needed.
+
+
+Vectorcall Support API
+----------------------
+
+Py_ssize_t PyVectorcall_NARGS(size_t nargsf)
+    * Part of the Stable ABI since version 3.12.*
+
+   Given a vectorcall *nargsf* argument, return the actual number of
+   arguments. Currently equivalent to:
+
+      (Py_ssize_t)(nargsf & ~PY_VECTORCALL_ARGUMENTS_OFFSET)
+
+   However, the function "PyVectorcall_NARGS" should be used to allow
+   for future extensions.
+
+   Added in version 3.8.
+
+vectorcallfunc PyVectorcall_Function(PyObject *op)
+
+   If *op* does not support the vectorcall protocol (either because
+   the type does not or because the specific instance does not),
+   return *NULL*. Otherwise, return the vectorcall function pointer
+   stored in *op*. This function never raises an exception.
+
+   This is mostly useful to check whether or not *op* supports
+   vectorcall, which can be done by checking
+   "PyVectorcall_Function(op) != NULL".
+
+   Added in version 3.9.
+
+PyObject *PyVectorcall_Call(PyObject *callable, PyObject *tuple, PyObject *dict)
+    * Part of the Stable ABI since version 3.12.*
+
+   Call *callable*'s "vectorcallfunc" with positional and keyword
+   arguments given in a tuple and dict, respectively.
+
+   This is a specialized function, intended to be put in the "tp_call"
+   slot or be used in an implementation of "tp_call". It does not
+   check the "Py_TPFLAGS_HAVE_VECTORCALL" flag and it does not fall
+   back to "tp_call".
+
+   Added in version 3.8.
+
+
+Object Calling API
+==================
+
+Various functions are available for calling a Python object. Each
+converts its arguments to a convention supported by the called object
+– either *tp_call* or vectorcall. In order to do as little conversion
+as possible, pick one that best fits the format of data you have
+available.
+
+The following table summarizes the available functions; please see
+individual documentation for details.
+
++--------------------------------------------+--------------------+----------------------+-----------------+
+| Function                                   | callable           | args                 | kwargs          |
+|============================================|====================|======================|=================|
+| "PyObject_Call()"                          | "PyObject *"       | tuple                | dict/"NULL"     |
++--------------------------------------------+--------------------+----------------------+-----------------+
+| "PyObject_CallNoArgs()"                    | "PyObject *"       | ---                  | ---             |
++--------------------------------------------+--------------------+----------------------+-----------------+
+| "PyObject_CallOneArg()"                    | "PyObject *"       | 1 object             | ---             |
++--------------------------------------------+--------------------+----------------------+-----------------+
+| "PyObject_CallObject()"                    | "PyObject *"       | tuple/"NULL"         | ---             |
++--------------------------------------------+--------------------+----------------------+-----------------+
+| "PyObject_CallFunction()"                  | "PyObject *"       | format               | ---             |
++--------------------------------------------+--------------------+----------------------+-----------------+
+| "PyObject_CallMethod()"                    | obj + "char*"      | format               | ---             |
++--------------------------------------------+--------------------+----------------------+-----------------+
+| "PyObject_CallFunctionObjArgs()"           | "PyObject *"       | variadic             | ---             |
++--------------------------------------------+--------------------+----------------------+-----------------+
+| "PyObject_CallMethodObjArgs()"             | obj + name         | variadic             | ---             |
++--------------------------------------------+--------------------+----------------------+-----------------+
+| "PyObject_CallMethodNoArgs()"              | obj + name         | ---                  | ---             |
++--------------------------------------------+--------------------+----------------------+-----------------+
+| "PyObject_CallMethodOneArg()"              | obj + name         | 1 object             | ---             |
++--------------------------------------------+--------------------+----------------------+-----------------+
+| "PyObject_Vectorcall()"                    | "PyObject *"       | vectorcall           | vectorcall      |
++--------------------------------------------+--------------------+----------------------+-----------------+
+| "PyObject_VectorcallDict()"                | "PyObject *"       | vectorcall           | dict/"NULL"     |
++--------------------------------------------+--------------------+----------------------+-----------------+
+| "PyObject_VectorcallMethod()"              | arg + name         | vectorcall           | vectorcall      |
++--------------------------------------------+--------------------+----------------------+-----------------+
+
+PyObject *PyObject_Call(PyObject *callable, PyObject *args, PyObject *kwargs)
+    *Return value: New reference.** Part of the Stable ABI.*
+
+   Call a callable Python object *callable*, with arguments given by
+   the tuple *args*, and named arguments given by the dictionary
+   *kwargs*.
+
+   *args* must not be *NULL*; use an empty tuple if no arguments are
+   needed. If no named arguments are needed, *kwargs* can be *NULL*.
+
+   Return the result of the call on success, or raise an exception and
+   return *NULL* on failure.
+
+   This is the equivalent of the Python expression: "callable(*args,
+   **kwargs)".
+
+PyObject *PyObject_CallNoArgs(PyObject *callable)
+    *Return value: New reference.** Part of the Stable ABI since
+   version 3.10.*
+
+   Call a callable Python object *callable* without any arguments. It
+   is the most efficient way to call a callable Python object without
+   any argument.
+
+   Return the result of the call on success, or raise an exception and
+   return *NULL* on failure.
+
+   Added in version 3.9.
+
+PyObject *PyObject_CallOneArg(PyObject *callable, PyObject *arg)
+    *Return value: New reference.*
+
+   Call a callable Python object *callable* with exactly 1 positional
+   argument *arg* and no keyword arguments.
+
+   Return the result of the call on success, or raise an exception and
+   return *NULL* on failure.
+
+   Added in version 3.9.
+
+PyObject *PyObject_CallObject(PyObject *callable, PyObject *args)
+    *Return value: New reference.** Part of the Stable ABI.*
+
+   Call a callable Python object *callable*, with arguments given by
+   the tuple *args*.  If no arguments are needed, then *args* can be
+   *NULL*.
+
+   Return the result of the call on success, or raise an exception and
+   return *NULL* on failure.
+
+   This is the equivalent of the Python expression: "callable(*args)".
+
+PyObject *PyObject_CallFunction(PyObject *callable, const char *format, ...)
+    *Return value: New reference.** Part of the Stable ABI.*
+
+   Call a callable Python object *callable*, with a variable number of
+   C arguments. The C arguments are described using a
+   "Py_BuildValue()" style format string.  The format can be *NULL*,
+   indicating that no arguments are provided.
+
+   Return the result of the call on success, or raise an exception and
+   return *NULL* on failure.
+
+   This is the equivalent of the Python expression: "callable(*args)".
+
+   Note that if you only pass PyObject* args,
+   "PyObject_CallFunctionObjArgs()" is a faster alternative.
+
+   Changed in version 3.4: The type of *format* was changed from "char
+   *".
+
+PyObject *PyObject_CallMethod(PyObject *obj, const char *name, const char *format, ...)
+    *Return value: New reference.** Part of the Stable ABI.*
+
+   Call the method named *name* of object *obj* with a variable number
+   of C arguments.  The C arguments are described by a
+   "Py_BuildValue()" format string that should produce a tuple.
+
+   The format can be *NULL*, indicating that no arguments are
+   provided.
+
+   Return the result of the call on success, or raise an exception and
+   return *NULL* on failure.
+
+   This is the equivalent of the Python expression: "obj.name(arg1,
+   arg2, ...)".
+
+   Note that if you only pass PyObject* args,
+   "PyObject_CallMethodObjArgs()" is a faster alternative.
+
+   Changed in version 3.4: The types of *name* and *format* were
+   changed from "char *".
+
+PyObject *PyObject_CallFunctionObjArgs(PyObject *callable, ...)
+    *Return value: New reference.** Part of the Stable ABI.*
+
+   Call a callable Python object *callable*, with a variable number of
+   PyObject* arguments.  The arguments are provided as a variable
+   number of parameters followed by *NULL*.
+
+   Return the result of the call on success, or raise an exception and
+   return *NULL* on failure.
+
+   This is the equivalent of the Python expression: "callable(arg1,
+   arg2, ...)".
+
+PyObject *PyObject_CallMethodObjArgs(PyObject *obj, PyObject *name, ...)
+    *Return value: New reference.** Part of the Stable ABI.*
+
+   Call a method of the Python object *obj*, where the name of the
+   method is given as a Python string object in *name*.  It is called
+   with a variable number of PyObject* arguments.  The arguments are
+   provided as a variable number of parameters followed by *NULL*.
+
+   Return the result of the call on success, or raise an exception and
+   return *NULL* on failure.
+
+PyObject *PyObject_CallMethodNoArgs(PyObject *obj, PyObject *name)
+
+   Call a method of the Python object *obj* without arguments, where
+   the name of the method is given as a Python string object in
+   *name*.
+
+   Return the result of the call on success, or raise an exception and
+   return *NULL* on failure.
+
+   Added in version 3.9.
+
+PyObject *PyObject_CallMethodOneArg(PyObject *obj, PyObject *name, PyObject *arg)
+
+   Call a method of the Python object *obj* with a single positional
+   argument *arg*, where the name of the method is given as a Python
+   string object in *name*.
+
+   Return the result of the call on success, or raise an exception and
+   return *NULL* on failure.
+
+   Added in version 3.9.
+
+PyObject *PyObject_Vectorcall(PyObject *callable, PyObject *const *args, size_t nargsf, PyObject *kwnames)
+    * Part of the Stable ABI since version 3.12.*
+
+   Call a callable Python object *callable*. The arguments are the
+   same as for "vectorcallfunc". If *callable* supports vectorcall,
+   this directly calls the vectorcall function stored in *callable*.
+
+   Return the result of the call on success, or raise an exception and
+   return *NULL* on failure.
+
+   Added in version 3.9.
+
+PyObject *PyObject_VectorcallDict(PyObject *callable, PyObject *const *args, size_t nargsf, PyObject *kwdict)
+
+   Call *callable* with positional arguments passed exactly as in the
+   vectorcall protocol, but with keyword arguments passed as a
+   dictionary *kwdict*. The *args* array contains only the positional
+   arguments.
+
+   Regardless of which protocol is used internally, a conversion of
+   arguments needs to be done. Therefore, this function should only be
+   used if the caller already has a dictionary ready to use for the
+   keyword arguments, but not a tuple for the positional arguments.
+
+   Added in version 3.9.
+
+PyObject *PyObject_VectorcallMethod(PyObject *name, PyObject *const *args, size_t nargsf, PyObject *kwnames)
+    * Part of the Stable ABI since version 3.12.*
+
+   Call a method using the vectorcall calling convention. The name of
+   the method is given as a Python string *name*. The object whose
+   method is called is *args[0]*, and the *args* array starting at
+   *args[1]* represents the arguments of the call. There must be at
+   least one positional argument. *nargsf* is the number of positional
+   arguments including *args[0]*, plus
+   "PY_VECTORCALL_ARGUMENTS_OFFSET" if the value of "args[0]" may
+   temporarily be changed. Keyword arguments can be passed just like
+   in "PyObject_Vectorcall()".
+
+   If the object has the "Py_TPFLAGS_METHOD_DESCRIPTOR" feature, this
+   will call the unbound method object with the full *args* vector as
+   arguments.
+
+   Return the result of the call on success, or raise an exception and
+   return *NULL* on failure.
+
+   Added in version 3.9.
+
+
+Call Support API
+================
+
+int PyCallable_Check(PyObject *o)
+    * Part of the Stable ABI.*
+
+   Determine if the object *o* is callable.  Return "1" if the object
+   is callable and "0" otherwise.  This function always succeeds.

python-3.12.6-docs-text/python-3.12.6-docs-text/c-api/capsule.txt

@@ -0,0 +1,156 @@
+Capsules
+********
+
+Refer to Providing a C API for an Extension Module for more
+information on using these objects.
+
+Added in version 3.1.
+
+type PyCapsule
+
+   This subtype of "PyObject" represents an opaque value, useful for C
+   extension modules who need to pass an opaque value (as a void*
+   pointer) through Python code to other C code.  It is often used to
+   make a C function pointer defined in one module available to other
+   modules, so the regular import mechanism can be used to access C
+   APIs defined in dynamically loaded modules.
+
+type PyCapsule_Destructor
+    * Part of the Stable ABI.*
+
+   The type of a destructor callback for a capsule.  Defined as:
+
+      typedef void (*PyCapsule_Destructor)(PyObject *);
+
+   See "PyCapsule_New()" for the semantics of PyCapsule_Destructor
+   callbacks.
+
+int PyCapsule_CheckExact(PyObject *p)
+
+   Return true if its argument is a "PyCapsule".  This function always
+   succeeds.
+
+PyObject *PyCapsule_New(void *pointer, const char *name, PyCapsule_Destructor destructor)
+    *Return value: New reference.** Part of the Stable ABI.*
+
+   Create a "PyCapsule" encapsulating the *pointer*.  The *pointer*
+   argument may not be "NULL".
+
+   On failure, set an exception and return "NULL".
+
+   The *name* string may either be "NULL" or a pointer to a valid C
+   string.  If non-"NULL", this string must outlive the capsule.
+   (Though it is permitted to free it inside the *destructor*.)
+
+   If the *destructor* argument is not "NULL", it will be called with
+   the capsule as its argument when it is destroyed.
+
+   If this capsule will be stored as an attribute of a module, the
+   *name* should be specified as "modulename.attributename".  This
+   will enable other modules to import the capsule using
+   "PyCapsule_Import()".
+
+void *PyCapsule_GetPointer(PyObject *capsule, const char *name)
+    * Part of the Stable ABI.*
+
+   Retrieve the *pointer* stored in the capsule.  On failure, set an
+   exception and return "NULL".
+
+   The *name* parameter must compare exactly to the name stored in the
+   capsule. If the name stored in the capsule is "NULL", the *name*
+   passed in must also be "NULL".  Python uses the C function
+   "strcmp()" to compare capsule names.
+
+PyCapsule_Destructor PyCapsule_GetDestructor(PyObject *capsule)
+    * Part of the Stable ABI.*
+
+   Return the current destructor stored in the capsule.  On failure,
+   set an exception and return "NULL".
+
+   It is legal for a capsule to have a "NULL" destructor.  This makes
+   a "NULL" return code somewhat ambiguous; use "PyCapsule_IsValid()"
+   or "PyErr_Occurred()" to disambiguate.
+
+void *PyCapsule_GetContext(PyObject *capsule)
+    * Part of the Stable ABI.*
+
+   Return the current context stored in the capsule.  On failure, set
+   an exception and return "NULL".
+
+   It is legal for a capsule to have a "NULL" context.  This makes a
+   "NULL" return code somewhat ambiguous; use "PyCapsule_IsValid()" or
+   "PyErr_Occurred()" to disambiguate.
+
+const char *PyCapsule_GetName(PyObject *capsule)
+    * Part of the Stable ABI.*
+
+   Return the current name stored in the capsule.  On failure, set an
+   exception and return "NULL".
+
+   It is legal for a capsule to have a "NULL" name.  This makes a
+   "NULL" return code somewhat ambiguous; use "PyCapsule_IsValid()" or
+   "PyErr_Occurred()" to disambiguate.
+
+void *PyCapsule_Import(const char *name, int no_block)
+    * Part of the Stable ABI.*
+
+   Import a pointer to a C object from a capsule attribute in a
+   module.  The *name* parameter should specify the full name to the
+   attribute, as in "module.attribute".  The *name* stored in the
+   capsule must match this string exactly.
+
+   Return the capsule's internal *pointer* on success.  On failure,
+   set an exception and return "NULL".
+
+   Changed in version 3.3: *no_block* has no effect anymore.
+
+int PyCapsule_IsValid(PyObject *capsule, const char *name)
+    * Part of the Stable ABI.*
+
+   Determines whether or not *capsule* is a valid capsule.  A valid
+   capsule is non-"NULL", passes "PyCapsule_CheckExact()", has a
+   non-"NULL" pointer stored in it, and its internal name matches the
+   *name* parameter.  (See "PyCapsule_GetPointer()" for information on
+   how capsule names are compared.)
+
+   In other words, if "PyCapsule_IsValid()" returns a true value,
+   calls to any of the accessors (any function starting with
+   "PyCapsule_Get") are guaranteed to succeed.
+
+   Return a nonzero value if the object is valid and matches the name
+   passed in. Return "0" otherwise.  This function will not fail.
+
+int PyCapsule_SetContext(PyObject *capsule, void *context)
+    * Part of the Stable ABI.*
+
+   Set the context pointer inside *capsule* to *context*.
+
+   Return "0" on success.  Return nonzero and set an exception on
+   failure.
+
+int PyCapsule_SetDestructor(PyObject *capsule, PyCapsule_Destructor destructor)
+    * Part of the Stable ABI.*
+
+   Set the destructor inside *capsule* to *destructor*.
+
+   Return "0" on success.  Return nonzero and set an exception on
+   failure.
+
+int PyCapsule_SetName(PyObject *capsule, const char *name)
+    * Part of the Stable ABI.*
+
+   Set the name inside *capsule* to *name*.  If non-"NULL", the name
+   must outlive the capsule.  If the previous *name* stored in the
+   capsule was not "NULL", no attempt is made to free it.
+
+   Return "0" on success.  Return nonzero and set an exception on
+   failure.
+
+int PyCapsule_SetPointer(PyObject *capsule, void *pointer)
+    * Part of the Stable ABI.*
+
+   Set the void pointer inside *capsule* to *pointer*.  The pointer
+   may not be "NULL".
+
+   Return "0" on success.  Return nonzero and set an exception on
+   failure.

python-3.12.6-docs-text/python-3.12.6-docs-text/c-api/cell.txt

@@ -0,0 +1,58 @@
+Cell Objects
+************
+
+"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 the cells from outer scopes which also
+use that variable.  When the value is accessed, the value contained in
+the cell is used instead of the cell object itself.  This de-
+referencing of the cell object requires support from the generated
+byte-code; these are not automatically de-referenced when accessed.
+Cell objects are not likely to be useful elsewhere.
+
+type PyCellObject
+
+   The C structure used for cell objects.
+
+PyTypeObject PyCell_Type
+
+   The type object corresponding to cell objects.
+
+int PyCell_Check(PyObject *ob)
+
+   Return true if *ob* is a cell object; *ob* must not be "NULL".
+   This function always succeeds.
+
+PyObject *PyCell_New(PyObject *ob)
+    *Return value: New reference.*
+
+   Create and return a new cell object containing the value *ob*. The
+   parameter may be "NULL".
+
+PyObject *PyCell_Get(PyObject *cell)
+    *Return value: New reference.*
+
+   Return the contents of the cell *cell*, which can be "NULL". If
+   *cell* is not a cell object, returns "NULL" with an exception set.
+
+PyObject *PyCell_GET(PyObject *cell)
+    *Return value: Borrowed reference.*
+
+   Return the contents of the cell *cell*, but without checking that
+   *cell* is non-"NULL" and a cell object.
+
+int PyCell_Set(PyObject *cell, PyObject *value)
+
+   Set the contents of the cell object *cell* to *value*.  This
+   releases the reference to any current content of the cell. *value*
+   may be "NULL".  *cell* must be non-"NULL".
+
+   On success, return "0". If *cell* is not a cell object, set an
+   exception and return "-1".
+
+void PyCell_SET(PyObject *cell, PyObject *value)
+
+   Sets the value of the cell object *cell* to *value*.  No reference
+   counts are adjusted, and no checks are made for safety; *cell* must
+   be non-"NULL" and must be a cell object.

python-3.12.6-docs-text/python-3.12.6-docs-text/c-api/code.txt

@@ -0,0 +1,263 @@
+Code Objects
+************
+
+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.
+
+type PyCodeObject
+
+   The C structure of the objects used to describe code objects.  The
+   fields of this type are subject to change at any time.
+
+PyTypeObject PyCode_Type
+
+   This is an instance of "PyTypeObject" representing the Python code
+   object.
+
+int PyCode_Check(PyObject *co)
+
+   Return true if *co* is a code object. This function always
+   succeeds.
+
+Py_ssize_t PyCode_GetNumFree(PyCodeObject *co)
+
+   Return the number of free variables in a code object.
+
+int PyCode_GetFirstFree(PyCodeObject *co)
+
+   Return the position of the first free variable in a code object.
+
+PyCodeObject *PyUnstable_Code_New(int argcount, int kwonlyargcount, int nlocals, int stacksize, int flags, PyObject *code, PyObject *consts, PyObject *names, PyObject *varnames, PyObject *freevars, PyObject *cellvars, PyObject *filename, PyObject *name, PyObject *qualname, int firstlineno, PyObject *linetable, PyObject *exceptiontable)
+
+   *This is Unstable API. It may change without warning in minor
+   releases.*
+
+   Return a new code object.  If you need a dummy code object to
+   create a frame, use "PyCode_NewEmpty()" instead.
+
+   Since the definition of the bytecode changes often, calling
+   "PyUnstable_Code_New()" directly can bind you to a precise Python
+   version.
+
+   The many arguments of this function are inter-dependent in complex
+   ways, meaning that subtle changes to values are likely to result in
+   incorrect execution or VM crashes. Use this function only with
+   extreme care.
+
+   Changed in version 3.11: Added "qualname" and "exceptiontable"
+   parameters.
+
+   Changed in version 3.12: Renamed from "PyCode_New" as part of
+   Unstable C API. The old name is deprecated, but will remain
+   available until the signature changes again.
+
+PyCodeObject *PyUnstable_Code_NewWithPosOnlyArgs(int argcount, int posonlyargcount, int kwonlyargcount, int nlocals, int stacksize, int flags, PyObject *code, PyObject *consts, PyObject *names, PyObject *varnames, PyObject *freevars, PyObject *cellvars, PyObject *filename, PyObject *name, PyObject *qualname, int firstlineno, PyObject *linetable, PyObject *exceptiontable)
+
+   *This is Unstable API. It may change without warning in minor
+   releases.*
+
+   Similar to "PyUnstable_Code_New()", but with an extra
+   "posonlyargcount" for positional-only arguments. The same caveats
+   that apply to "PyUnstable_Code_New" also apply to this function.
+
+   Added in version 3.8: as "PyCode_NewWithPosOnlyArgs"
+
+   Changed in version 3.11: Added "qualname" and  "exceptiontable"
+   parameters.
+
+   Changed in version 3.12: Renamed to
+   "PyUnstable_Code_NewWithPosOnlyArgs". The old name is deprecated,
+   but will remain available until the signature changes again.
+
+PyCodeObject *PyCode_NewEmpty(const char *filename, const char *funcname, int firstlineno)
+    *Return value: New reference.*
+
+   Return a new empty code object with the specified filename,
+   function name, and first line number. The resulting code object
+   will raise an "Exception" if executed.
+
+int PyCode_Addr2Line(PyCodeObject *co, int byte_offset)
+
+   Return the line number of the instruction that occurs on or before
+   "byte_offset" and ends after it. If you just need the line number
+   of a frame, use "PyFrame_GetLineNumber()" instead.
+
+   For efficiently iterating over the line numbers in a code object,
+   use the API described in PEP 626.
+
+int PyCode_Addr2Location(PyObject *co, int byte_offset, int *start_line, int *start_column, int *end_line, int *end_column)
+
+   Sets the passed "int" pointers to the source code line and column
+   numbers for the instruction at "byte_offset". Sets the value to "0"
+   when information is not available for any particular element.
+
+   Returns "1" if the function succeeds and 0 otherwise.
+
+   Added in version 3.11.
+
+PyObject *PyCode_GetCode(PyCodeObject *co)
+
+   Equivalent to the Python code "getattr(co, 'co_code')". Returns a
+   strong reference to a "PyBytesObject" representing the bytecode in
+   a code object. On error, "NULL" is returned and an exception is
+   raised.
+
+   This "PyBytesObject" may be created on-demand by the interpreter
+   and does not necessarily represent the bytecode actually executed
+   by CPython. The primary use case for this function is debuggers and
+   profilers.
+
+   Added in version 3.11.
+
+PyObject *PyCode_GetVarnames(PyCodeObject *co)
+
+   Equivalent to the Python code "getattr(co, 'co_varnames')". Returns
+   a new reference to a "PyTupleObject" containing the names of the
+   local variables. On error, "NULL" is returned and an exception is
+   raised.
+
+   Added in version 3.11.
+
+PyObject *PyCode_GetCellvars(PyCodeObject *co)
+
+   Equivalent to the Python code "getattr(co, 'co_cellvars')". Returns
+   a new reference to a "PyTupleObject" containing the names of the
+   local variables that are referenced by nested functions. On error,
+   "NULL" is returned and an exception is raised.
+
+   Added in version 3.11.
+
+PyObject *PyCode_GetFreevars(PyCodeObject *co)
+
+   Equivalent to the Python code "getattr(co, 'co_freevars')". Returns
+   a new reference to a "PyTupleObject" containing the names of the
+   free variables. On error, "NULL" is returned and an exception is
+   raised.
+
+   Added in version 3.11.
+
+int PyCode_AddWatcher(PyCode_WatchCallback callback)
+
+   Register *callback* as a code object watcher for the current
+   interpreter. Return an ID which may be passed to
+   "PyCode_ClearWatcher()". In case of error (e.g. no more watcher IDs
+   available), return "-1" and set an exception.
+
+   Added in version 3.12.
+
+int PyCode_ClearWatcher(int watcher_id)
+
+   Clear watcher identified by *watcher_id* previously returned from
+   "PyCode_AddWatcher()" for the current interpreter. Return "0" on
+   success, or "-1" and set an exception on error (e.g. if the given
+   *watcher_id* was never registered.)
+
+   Added in version 3.12.
+
+type PyCodeEvent
+
+   Enumeration of possible code object watcher events: -
+   "PY_CODE_EVENT_CREATE" - "PY_CODE_EVENT_DESTROY"
+
+   Added in version 3.12.
+
+typedef int (*PyCode_WatchCallback)(PyCodeEvent event, PyCodeObject *co)
+
+   Type of a code object watcher callback function.
+
+   If *event* is "PY_CODE_EVENT_CREATE", then the callback is invoked
+   after *co* has been fully initialized. Otherwise, the callback is
+   invoked before the destruction of *co* takes place, so the prior
+   state of *co* can be inspected.
+
+   If *event* is "PY_CODE_EVENT_DESTROY", taking a reference in the
+   callback to the about-to-be-destroyed code object will resurrect it
+   and prevent it from being freed at this time. When the resurrected
+   object is destroyed later, any watcher callbacks active at that
+   time will be called again.
+
+   Users of this API should not rely on internal runtime
+   implementation details. Such details may include, but are not
+   limited to, the exact order and timing of creation and destruction
+   of code objects. While changes in these details may result in
+   differences observable by watchers (including whether a callback is
+   invoked or not), it does not change the semantics of the Python
+   code being executed.
+
+   If the callback sets an exception, it must return "-1"; this
+   exception will be printed as an unraisable exception using
+   "PyErr_WriteUnraisable()". Otherwise it should return "0".
+
+   There may already be a pending exception set on entry to the
+   callback. In this case, the callback should return "0" with the
+   same exception still set. This means the callback may not call any
+   other API that can set an exception unless it saves and clears the
+   exception state first, and restores it before returning.
+
+   Added in version 3.12.
+
+
+Extra information
+*****************
+
+To support low-level extensions to frame evaluation, such as external
+just-in-time compilers, it is possible to attach arbitrary extra data
+to code objects.
+
+These functions are part of the unstable C API tier: this
+functionality is a CPython implementation detail, and the API may
+change without deprecation warnings.
+
+Py_ssize_t PyUnstable_Eval_RequestCodeExtraIndex(freefunc free)
+
+   *This is Unstable API. It may change without warning in minor
+   releases.*
+
+   Return a new an opaque index value used to adding data to code
+   objects.
+
+   You generally call this function once (per interpreter) and use the
+   result with "PyCode_GetExtra" and "PyCode_SetExtra" to manipulate
+   data on individual code objects.
+
+   If *free* is not "NULL": when a code object is deallocated, *free*
+   will be called on non-"NULL" data stored under the new index. Use
+   "Py_DecRef()" when storing "PyObject".
+
+   Added in version 3.6: as "_PyEval_RequestCodeExtraIndex"
+
+   Changed in version 3.12: Renamed to
+   "PyUnstable_Eval_RequestCodeExtraIndex". The old private name is
+   deprecated, but will be available until the API changes.
+
+int PyUnstable_Code_GetExtra(PyObject *code, Py_ssize_t index, void **extra)
+
+   *This is Unstable API. It may change without warning in minor
+   releases.*
+
+   Set *extra* to the extra data stored under the given index. Return
+   0 on success. Set an exception and return -1 on failure.
+
+   If no data was set under the index, set *extra* to "NULL" and
+   return 0 without setting an exception.
+
+   Added in version 3.6: as "_PyCode_GetExtra"
+
+   Changed in version 3.12: Renamed to "PyUnstable_Code_GetExtra". The
+   old private name is deprecated, but will be available until the API
+   changes.
+
+int PyUnstable_Code_SetExtra(PyObject *code, Py_ssize_t index, void *extra)
+
+   *This is Unstable API. It may change without warning in minor
+   releases.*
+
+   Set the extra data stored under the given index to *extra*. Return
+   0 on success. Set an exception and return -1 on failure.
+
+   Added in version 3.6: as "_PyCode_SetExtra"
+
+   Changed in version 3.12: Renamed to "PyUnstable_Code_SetExtra". The
+   old private name is deprecated, but will be available until the API
+   changes.

python-3.12.6-docs-text/python-3.12.6-docs-text/c-api/codec.txt

@@ -0,0 +1,152 @@
+Codec registry and support functions
+************************************
+
+int PyCodec_Register(PyObject *search_function)
+    * Part of the Stable ABI.*
+
+   Register a new codec search function.
+
+   As side effect, this tries to load the "encodings" package, if not
+   yet done, to make sure that it is always first in the list of
+   search functions.
+
+int PyCodec_Unregister(PyObject *search_function)
+    * Part of the Stable ABI since version 3.10.*
+
+   Unregister a codec search function and clear the registry's cache.
+   If the search function is not registered, do nothing. Return 0 on
+   success. Raise an exception and return -1 on error.
+
+   Added in version 3.10.
+
+int PyCodec_KnownEncoding(const char *encoding)
+    * Part of the Stable ABI.*
+
+   Return "1" or "0" depending on whether there is a registered codec
+   for the given *encoding*.  This function always succeeds.
+
+PyObject *PyCodec_Encode(PyObject *object, const char *encoding, const char *errors)
+    *Return value: New reference.** Part of the Stable ABI.*
+
+   Generic codec based encoding API.
+
+   *object* is passed through the encoder function found for the given
+   *encoding* using the error handling method defined by *errors*.
+   *errors* may be "NULL" to use the default method defined for the
+   codec.  Raises a "LookupError" if no encoder can be found.
+
+PyObject *PyCodec_Decode(PyObject *object, const char *encoding, const char *errors)
+    *Return value: New reference.** Part of the Stable ABI.*
+
+   Generic codec based decoding API.
+
+   *object* is passed through the decoder function found for the given
+   *encoding* using the error handling method defined by *errors*.
+   *errors* may be "NULL" to use the default method defined for the
+   codec.  Raises a "LookupError" if no encoder can be found.
+
+
+Codec lookup API
+================
+
+In the following functions, the *encoding* string is looked up
+converted to all lower-case characters, which makes encodings looked
+up through this mechanism effectively case-insensitive.  If no codec
+is found, a "KeyError" is set and "NULL" returned.
+
+PyObject *PyCodec_Encoder(const char *encoding)
+    *Return value: New reference.** Part of the Stable ABI.*
+
+   Get an encoder function for the given *encoding*.
+
+PyObject *PyCodec_Decoder(const char *encoding)
+    *Return value: New reference.** Part of the Stable ABI.*
+
+   Get a decoder function for the given *encoding*.
+
+PyObject *PyCodec_IncrementalEncoder(const char *encoding, const char *errors)
+    *Return value: New reference.** Part of the Stable ABI.*
+
+   Get an "IncrementalEncoder" object for the given *encoding*.
+
+PyObject *PyCodec_IncrementalDecoder(const char *encoding, const char *errors)
+    *Return value: New reference.** Part of the Stable ABI.*
+
+   Get an "IncrementalDecoder" object for the given *encoding*.
+
+PyObject *PyCodec_StreamReader(const char *encoding, PyObject *stream, const char *errors)
+    *Return value: New reference.** Part of the Stable ABI.*
+
+   Get a "StreamReader" factory function for the given *encoding*.
+
+PyObject *PyCodec_StreamWriter(const char *encoding, PyObject *stream, const char *errors)
+    *Return value: New reference.** Part of the Stable ABI.*
+
+   Get a "StreamWriter" factory function for the given *encoding*.
+
+
+Registry API for Unicode encoding error handlers
+================================================
+
+int PyCodec_RegisterError(const char *name, PyObject *error)
+    * Part of the Stable ABI.*
+
+   Register the error handling callback function *error* under the
+   given *name*. This callback function will be called by a codec when
+   it encounters unencodable characters/undecodable bytes and *name*
+   is specified as the error parameter in the call to the
+   encode/decode function.
+
+   The callback gets a single argument, an instance of
+   "UnicodeEncodeError", "UnicodeDecodeError" or
+   "UnicodeTranslateError" that holds information about the
+   problematic sequence of characters or bytes and their offset in the
+   original string (see Unicode Exception Objects for functions to
+   extract this information).  The callback must either raise the
+   given exception, or return a two-item tuple containing the
+   replacement for the problematic sequence, and an integer giving the
+   offset in the original string at which encoding/decoding should be
+   resumed.
+
+   Return "0" on success, "-1" on error.
+
+PyObject *PyCodec_LookupError(const char *name)
+    *Return value: New reference.** Part of the Stable ABI.*
+
+   Lookup the error handling callback function registered under
+   *name*.  As a special case "NULL" can be passed, in which case the
+   error handling callback for "strict" will be returned.
+
+PyObject *PyCodec_StrictErrors(PyObject *exc)
+    *Return value: Always NULL.** Part of the Stable ABI.*
+
+   Raise *exc* as an exception.
+
+PyObject *PyCodec_IgnoreErrors(PyObject *exc)
+    *Return value: New reference.** Part of the Stable ABI.*
+
+   Ignore the unicode error, skipping the faulty input.
+
+PyObject *PyCodec_ReplaceErrors(PyObject *exc)
+    *Return value: New reference.** Part of the Stable ABI.*
+
+   Replace the unicode encode error with "?" or "U+FFFD".
+
+PyObject *PyCodec_XMLCharRefReplaceErrors(PyObject *exc)
+    *Return value: New reference.** Part of the Stable ABI.*
+
+   Replace the unicode encode error with XML character references.
+
+PyObject *PyCodec_BackslashReplaceErrors(PyObject *exc)
+    *Return value: New reference.** Part of the Stable ABI.*
+
+   Replace the unicode encode error with backslash escapes ("\x", "\u"
+   and "\U").
+
+PyObject *PyCodec_NameReplaceErrors(PyObject *exc)
+    *Return value: New reference.** Part of the Stable ABI since
+   version 3.7.*
+
+   Replace the unicode encode error with "\N{...}" escapes.
+
+   Added in version 3.5.

python-3.12.6-docs-text/python-3.12.6-docs-text/c-api/complex.txt

@@ -0,0 +1,136 @@
+Complex Number Objects
+**********************
+
+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. The API provides functions for working
+with both.
+
+
+Complex Numbers as C Structures
+===============================
+
+Note that the functions which accept these structures as parameters
+and return them as results do so *by value* rather than dereferencing
+them through pointers.  This is consistent throughout the API.
+
+type Py_complex
+
+   The C structure which corresponds to the value portion of a Python
+   complex number object.  Most of the functions for dealing with
+   complex number objects use structures of this type as input or
+   output values, as appropriate.
+
+   double real
+   double imag
+
+   The structure is defined as:
+
+      typedef struct {
+          double real;
+          double imag;
+      } Py_complex;
+
+Py_complex _Py_c_sum(Py_complex left, Py_complex right)
+
+   Return the sum of two complex numbers, using the C "Py_complex"
+   representation.
+
+Py_complex _Py_c_diff(Py_complex left, Py_complex right)
+
+   Return the difference between two complex numbers, using the C
+   "Py_complex" representation.
+
+Py_complex _Py_c_neg(Py_complex num)
+
+   Return the negation of the complex number *num*, using the C
+   "Py_complex" representation.
+
+Py_complex _Py_c_prod(Py_complex left, Py_complex right)
+
+   Return the product of two complex numbers, using the C "Py_complex"
+   representation.
+
+Py_complex _Py_c_quot(Py_complex dividend, Py_complex divisor)
+
+   Return the quotient of two complex numbers, using the C
+   "Py_complex" representation.
+
+   If *divisor* is null, this method returns zero and sets "errno" to
+   "EDOM".
+
+Py_complex _Py_c_pow(Py_complex num, Py_complex exp)
+
+   Return the exponentiation of *num* by *exp*, using the C
+   "Py_complex" representation.
+
+   If *num* is null and *exp* is not a positive real number, this
+   method returns zero and sets "errno" to "EDOM".
+
+
+Complex Numbers as Python Objects
+=================================
+
+type PyComplexObject
+
+   This subtype of "PyObject" represents a Python complex number
+   object.
+
+PyTypeObject PyComplex_Type
+    * Part of the Stable ABI.*
+
+   This instance of "PyTypeObject" represents the Python complex
+   number type. It is the same object as "complex" in the Python
+   layer.
+
+int PyComplex_Check(PyObject *p)
+
+   Return true if its argument is a "PyComplexObject" or a subtype of
+   "PyComplexObject".  This function always succeeds.
+
+int PyComplex_CheckExact(PyObject *p)
+
+   Return true if its argument is a "PyComplexObject", but not a
+   subtype of "PyComplexObject".  This function always succeeds.
+
+PyObject *PyComplex_FromCComplex(Py_complex v)
+    *Return value: New reference.*
+
+   Create a new Python complex number object from a C "Py_complex"
+   value. Return "NULL" with an exception set on error.
+
+PyObject *PyComplex_FromDoubles(double real, double imag)
+    *Return value: New reference.** Part of the Stable ABI.*
+
+   Return a new "PyComplexObject" object from *real* and *imag*.
+   Return "NULL" with an exception set on error.
+
+double PyComplex_RealAsDouble(PyObject *op)
+    * Part of the Stable ABI.*
+
+   Return the real part of *op* as a C double.
+
+   Upon failure, this method returns "-1.0" with an exception set, so
+   one should call "PyErr_Occurred()" to check for errors.
+
+double PyComplex_ImagAsDouble(PyObject *op)
+    * Part of the Stable ABI.*
+
+   Return the imaginary part of *op* as a C double.
+
+Py_complex PyComplex_AsCComplex(PyObject *op)
+
+   Return the "Py_complex" value of the complex number *op*.
+
+   If *op* is not a Python complex number object but has a
+   "__complex__()" method, this method will first be called to convert
+   *op* to a Python complex number object.  If "__complex__()" is not
+   defined then it falls back to "__float__()".  If "__float__()" is
+   not defined then it falls back to "__index__()".
+
+   Upon failure, this method returns "Py_complex" with "real" set to
+   "-1.0" and with an exception set, so one should call
+   "PyErr_Occurred()" to check for errors.
+
+   Changed in version 3.8: Use "__index__()" if available.

python-3.12.6-docs-text/python-3.12.6-docs-text/c-api/concrete.txt

@@ -0,0 +1,193 @@
+Concrete Objects Layer
+**********************
+
+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, you must perform a type check first; for
+example, to check that an object is a dictionary, use
+"PyDict_Check()".  The chapter is structured like the "family tree" of
+Python object types.
+
+Warning:
+
+  While the functions described in this chapter carefully check the
+  type of the objects which are passed in, many of them do not check
+  for "NULL" being passed instead of a valid object.  Allowing "NULL"
+  to be passed in can cause memory access violations and immediate
+  termination of the interpreter.
+
+
+Fundamental Objects
+===================
+
+This section describes Python type objects and the singleton object
+"None".
+
+* Type Objects
+
+  * Creating Heap-Allocated Types
+
+* The "None" Object
+
+
+Numeric Objects
+===============
+
+* Integer Objects
+
+* Boolean Objects
+
+* Floating-Point Objects
+
+  * Pack and Unpack functions
+
+    * Pack functions
+
+    * Unpack functions
+
+* Complex Number Objects
+
+  * Complex Numbers as C Structures
+
+  * Complex Numbers as Python Objects
+
+
+Sequence Objects
+================
+
+Generic operations on sequence objects were discussed in the previous
+chapter; this section deals with the specific kinds of sequence
+objects that are intrinsic to the Python language.
+
+* Bytes Objects
+
+* Byte Array Objects
+
+  * Type check macros
+
+  * Direct API functions
+
+  * Macros
+
+* Unicode Objects and Codecs
+
+  * Unicode Objects
+
+    * Unicode Type
+
+    * Unicode Character Properties
+
+    * Creating and accessing Unicode strings
+
+    * Locale Encoding
+
+    * File System Encoding
+
+    * wchar_t Support
+
+  * Built-in Codecs
+
+    * Generic Codecs
+
+    * UTF-8 Codecs
+
+    * UTF-32 Codecs
+
+    * UTF-16 Codecs
+
+    * UTF-7 Codecs
+
+    * Unicode-Escape Codecs
+
+    * Raw-Unicode-Escape Codecs
+
+    * Latin-1 Codecs
+
+    * ASCII Codecs
+
+    * Character Map Codecs
+
+    * MBCS codecs for Windows
+
+    * Methods & Slots
+
+  * Methods and Slot Functions
+
+* Tuple Objects
+
+* Struct Sequence Objects
+
+* List Objects
+
+
+Container Objects
+=================
+
+* Dictionary Objects
+
+* Set Objects
+
+
+Function Objects
+================
+
+* Function Objects
+
+* Instance Method Objects
+
+* Method Objects
+
+* Cell Objects
+
+* Code Objects
+
+* Extra information
+
+
+Other Objects
+=============
+
+* File Objects
+
+* Module Objects
+
+  * Initializing C modules
+
+    * Single-phase initialization
+
+    * Multi-phase initialization
+
+    * Low-level module creation functions
+
+    * Support functions
+
+  * Module lookup
+
+* Iterator Objects
+
+* Descriptor Objects
+
+* Slice Objects
+
+  * Ellipsis Object
+
+* MemoryView objects
+
+* Weak Reference Objects
+
+* Capsules
+
+* Frame Objects
+
+  * Internal Frames
+
+* Generator Objects
+
+* Coroutine Objects
+
+* Context Variables Objects
+
+* DateTime Objects
+
+* Objects for Type Hinting

python-3.12.6-docs-text/python-3.12.6-docs-text/c-api/contextvars.txt

@@ -0,0 +1,135 @@
+Context Variables Objects
+*************************
+
+Added in version 3.7.
+
+Changed in version 3.7.1:
+
+Note:
+
+  In Python 3.7.1 the signatures of all context variables C APIs were
+  **changed** to use "PyObject" pointers instead of "PyContext",
+  "PyContextVar", and "PyContextToken", e.g.:
+
+     // in 3.7.0:
+     PyContext *PyContext_New(void);
+
+     // in 3.7.1+:
+     PyObject *PyContext_New(void);
+
+  See bpo-34762 for more details.
+
+This section details the public C API for the "contextvars" module.
+
+type PyContext
+
+   The C structure used to represent a "contextvars.Context" object.
+
+type PyContextVar
+
+   The C structure used to represent a "contextvars.ContextVar"
+   object.
+
+type PyContextToken
+
+   The C structure used to represent a "contextvars.Token" object.
+
+PyTypeObject PyContext_Type
+
+   The type object representing the *context* type.
+
+PyTypeObject PyContextVar_Type
+
+   The type object representing the *context variable* type.
+
+PyTypeObject PyContextToken_Type
+
+   The type object representing the *context variable token* type.
+
+Type-check macros:
+
+int PyContext_CheckExact(PyObject *o)
+
+   Return true if *o* is of type "PyContext_Type". *o* must not be
+   "NULL".  This function always succeeds.
+
+int PyContextVar_CheckExact(PyObject *o)
+
+   Return true if *o* is of type "PyContextVar_Type". *o* must not be
+   "NULL".  This function always succeeds.
+
+int PyContextToken_CheckExact(PyObject *o)
+
+   Return true if *o* is of type "PyContextToken_Type". *o* must not
+   be "NULL".  This function always succeeds.
+
+Context object management functions:
+
+PyObject *PyContext_New(void)
+    *Return value: New reference.*
+
+   Create a new empty context object.  Returns "NULL" if an error has
+   occurred.
+
+PyObject *PyContext_Copy(PyObject *ctx)
+    *Return value: New reference.*
+
+   Create a shallow copy of the passed *ctx* context object. Returns
+   "NULL" if an error has occurred.
+
+PyObject *PyContext_CopyCurrent(void)
+    *Return value: New reference.*
+
+   Create a shallow copy of the current thread context. Returns "NULL"
+   if an error has occurred.
+
+int PyContext_Enter(PyObject *ctx)
+
+   Set *ctx* as the current context for the current thread. Returns
+   "0" on success, and "-1" on error.
+
+int PyContext_Exit(PyObject *ctx)
+
+   Deactivate the *ctx* context and restore the previous context as
+   the current context for the current thread.  Returns "0" on
+   success, and "-1" on error.
+
+Context variable functions:
+
+PyObject *PyContextVar_New(const char *name, PyObject *def)
+    *Return value: New reference.*
+
+   Create a new "ContextVar" object.  The *name* parameter is used for
+   introspection and debug purposes.  The *def* parameter specifies a
+   default value for the context variable, or "NULL" for no default.
+   If an error has occurred, this function returns "NULL".
+
+int PyContextVar_Get(PyObject *var, PyObject *default_value, PyObject **value)
+
+   Get the value of a context variable.  Returns "-1" if an error has
+   occurred during lookup, and "0" if no error occurred, whether or
+   not a value was found.
+
+   If the context variable was found, *value* will be a pointer to it.
+   If the context variable was *not* found, *value* will point to:
+
+   * *default_value*, if not "NULL";
+
+   * the default value of *var*, if not "NULL";
+
+   * "NULL"
+
+   Except for "NULL", the function returns a new reference.
+
+PyObject *PyContextVar_Set(PyObject *var, PyObject *value)
+    *Return value: New reference.*
+
+   Set the value of *var* to *value* in the current context.  Returns
+   a new token object for this change, or "NULL" if an error has
+   occurred.
+
+int PyContextVar_Reset(PyObject *var, PyObject *token)
+
+   Reset the state of the *var* context variable to that it was in
+   before "PyContextVar_Set()" that returned the *token* was called.
+   This function returns "0" on success and "-1" on error.

python-3.12.6-docs-text/python-3.12.6-docs-text/c-api/conversion.txt

@@ -0,0 +1,162 @@
+String conversion and formatting
+********************************
+
+Functions for number conversion and formatted string output.
+
+int PyOS_snprintf(char *str, size_t size, const char *format, ...)
+    * Part of the Stable ABI.*
+
+   Output not more than *size* bytes to *str* according to the format
+   string *format* and the extra arguments. See the Unix man page
+   *snprintf(3)*.
+
+int PyOS_vsnprintf(char *str, size_t size, const char *format, va_list va)
+    * Part of the Stable ABI.*
+
+   Output not more than *size* bytes to *str* according to the format
+   string *format* and the variable argument list *va*. Unix man page
+   *vsnprintf(3)*.
+
+"PyOS_snprintf()" and "PyOS_vsnprintf()" wrap the Standard C library
+functions "snprintf()" and "vsnprintf()". Their purpose is to
+guarantee consistent behavior in corner cases, which the Standard C
+functions do not.
+
+The wrappers ensure that "str[size-1]" is always "'\0'" upon return.
+They never write more than *size* bytes (including the trailing
+"'\0'") into str. Both functions require that "str != NULL", "size >
+0", "format != NULL" and "size < INT_MAX". Note that this means there
+is no equivalent to the C99 "n = snprintf(NULL, 0, ...)" which would
+determine the necessary buffer size.
+
+The return value (*rv*) for these functions should be interpreted as
+follows:
+
+* When "0 <= rv < size", the output conversion was successful and *rv*
+  characters were written to *str* (excluding the trailing "'\0'" byte
+  at "str[rv]").
+
+* When "rv >= size", the output conversion was truncated and a buffer
+  with "rv + 1" bytes would have been needed to succeed. "str[size-1]"
+  is "'\0'" in this case.
+
+* When "rv < 0", "something bad happened." "str[size-1]" is "'\0'" in
+  this case too, but the rest of *str* is undefined. The exact cause
+  of the error depends on the underlying platform.
+
+The following functions provide locale-independent string to number
+conversions.
+
+unsigned long PyOS_strtoul(const char *str, char **ptr, int base)
+    * Part of the Stable ABI.*
+
+   Convert the initial part of the string in "str" to an unsigned long
+   value according to the given "base", which must be between "2" and
+   "36" inclusive, or be the special value "0".
+
+   Leading white space and case of characters are ignored.  If "base"
+   is zero it looks for a leading "0b", "0o" or "0x" to tell which
+   base.  If these are absent it defaults to "10".  Base must be 0 or
+   between 2 and 36 (inclusive).  If "ptr" is non-"NULL" it will
+   contain a pointer to the end of the scan.
+
+   If the converted value falls out of range of corresponding return
+   type, range error occurs ("errno" is set to "ERANGE") and
+   "ULONG_MAX" is returned.  If no conversion can be performed, "0" is
+   returned.
+
+   See also the Unix man page *strtoul(3)*.
+
+   Added in version 3.2.
+
+long PyOS_strtol(const char *str, char **ptr, int base)
+    * Part of the Stable ABI.*
+
+   Convert the initial part of the string in "str" to an long value
+   according to the given "base", which must be between "2" and "36"
+   inclusive, or be the special value "0".
+
+   Same as "PyOS_strtoul()", but return a long value instead and
+   "LONG_MAX" on overflows.
+
+   See also the Unix man page *strtol(3)*.
+
+   Added in version 3.2.
+
+double PyOS_string_to_double(const char *s, char **endptr, PyObject *overflow_exception)
+    * Part of the Stable ABI.*
+
+   Convert a string "s" to a double, raising a Python exception on
+   failure.  The set of accepted strings corresponds to the set of
+   strings accepted by Python's "float()" constructor, except that "s"
+   must not have leading or trailing whitespace. The conversion is
+   independent of the current locale.
+
+   If "endptr" is "NULL", convert the whole string.  Raise
+   "ValueError" and return "-1.0" if the string is not a valid
+   representation of a floating-point number.
+
+   If endptr is not "NULL", convert as much of the string as possible
+   and set "*endptr" to point to the first unconverted character.  If
+   no initial segment of the string is the valid representation of a
+   floating-point number, set "*endptr" to point to the beginning of
+   the string, raise ValueError, and return "-1.0".
+
+   If "s" represents a value that is too large to store in a float
+   (for example, ""1e500"" is such a string on many platforms) then if
+   "overflow_exception" is "NULL" return "Py_HUGE_VAL" (with an
+   appropriate sign) and don't set any exception.  Otherwise,
+   "overflow_exception" must point to a Python exception object; raise
+   that exception and return "-1.0".  In both cases, set "*endptr" to
+   point to the first character after the converted value.
+
+   If any other error occurs during the conversion (for example an
+   out-of-memory error), set the appropriate Python exception and
+   return "-1.0".
+
+   Added in version 3.1.
+
+char *PyOS_double_to_string(double val, char format_code, int precision, int flags, int *ptype)
+    * Part of the Stable ABI.*
+
+   Convert a double *val* to a string using supplied *format_code*,
+   *precision*, and *flags*.
+
+   *format_code* must be one of "'e'", "'E'", "'f'", "'F'", "'g'",
+   "'G'" or "'r'".  For "'r'", the supplied *precision* must be 0 and
+   is ignored.  The "'r'" format code specifies the standard "repr()"
+   format.
+
+   *flags* can be zero or more of the values "Py_DTSF_SIGN",
+   "Py_DTSF_ADD_DOT_0", or "Py_DTSF_ALT", or-ed together:
+
+   * "Py_DTSF_SIGN" means to always precede the returned string with a
+     sign character, even if *val* is non-negative.
+
+   * "Py_DTSF_ADD_DOT_0" means to ensure that the returned string will
+     not look like an integer.
+
+   * "Py_DTSF_ALT" means to apply "alternate" formatting rules.  See
+     the documentation for the "PyOS_snprintf()" "'#'" specifier for
+     details.
+
+   If *ptype* is non-"NULL", then the value it points to will be set
+   to one of "Py_DTST_FINITE", "Py_DTST_INFINITE", or "Py_DTST_NAN",
+   signifying that *val* is a finite number, an infinite number, or
+   not a number, respectively.
+
+   The return value is a pointer to *buffer* with the converted string
+   or "NULL" if the conversion failed. The caller is responsible for
+   freeing the returned string by calling "PyMem_Free()".
+
+   Added in version 3.1.
+
+int PyOS_stricmp(const char *s1, const char *s2)
+
+   Case insensitive comparison of strings. The function works almost
+   identically to "strcmp()" except that it ignores the case.
+
+int PyOS_strnicmp(const char *s1, const char *s2, Py_ssize_t size)
+
+   Case insensitive comparison of strings. The function works almost
+   identically to "strncmp()" except that it ignores the case.

python-3.12.6-docs-text/python-3.12.6-docs-text/c-api/coro.txt

@@ -0,0 +1,28 @@
+Coroutine Objects
+*****************
+
+Added in version 3.5.
+
+Coroutine objects are what functions declared with an "async" keyword
+return.
+
+type PyCoroObject
+
+   The C structure used for coroutine objects.
+
+PyTypeObject PyCoro_Type
+
+   The type object corresponding to coroutine objects.
+
+int PyCoro_CheckExact(PyObject *ob)
+
+   Return true if *ob*'s type is "PyCoro_Type"; *ob* must not be
+   "NULL". This function always succeeds.
+
+PyObject *PyCoro_New(PyFrameObject *frame, PyObject *name, PyObject *qualname)
+    *Return value: New reference.*
+
+   Create and return a new coroutine object based on the *frame*
+   object, with "__name__" and "__qualname__" set to *name* and
+   *qualname*. A reference to *frame* is stolen by this function.  The
+   *frame* argument must not be "NULL".

python-3.12.6-docs-text/python-3.12.6-docs-text/c-api/datetime.txt

@@ -0,0 +1,299 @@
+DateTime Objects
+****************
+
+Various date and time objects are supplied by the "datetime" module.
+Before using any of these functions, the header file "datetime.h" must
+be included in your source (note that this is not included by
+"Python.h"), and the macro "PyDateTime_IMPORT" must be invoked,
+usually as part of the module initialisation function.  The macro puts
+a pointer to a C structure into a static variable, "PyDateTimeAPI",
+that is used by the following macros.
+
+type PyDateTime_Date
+
+   This subtype of "PyObject" represents a Python date object.
+
+type PyDateTime_DateTime
+
+   This subtype of "PyObject" represents a Python datetime object.
+
+type PyDateTime_Time
+
+   This subtype of "PyObject" represents a Python time object.
+
+type PyDateTime_Delta
+
+   This subtype of "PyObject" represents the difference between two
+   datetime values.
+
+PyTypeObject PyDateTime_DateType
+
+   This instance of "PyTypeObject" represents the Python date type; it
+   is the same object as "datetime.date" in the Python layer.
+
+PyTypeObject PyDateTime_DateTimeType
+
+   This instance of "PyTypeObject" represents the Python datetime
+   type; it is the same object as "datetime.datetime" in the Python
+   layer.
+
+PyTypeObject PyDateTime_TimeType
+
+   This instance of "PyTypeObject" represents the Python time type; it
+   is the same object as "datetime.time" in the Python layer.
+
+PyTypeObject PyDateTime_DeltaType
+
+   This instance of "PyTypeObject" represents Python type for the
+   difference between two datetime values; it is the same object as
+   "datetime.timedelta" in the Python layer.
+
+PyTypeObject PyDateTime_TZInfoType
+
+   This instance of "PyTypeObject" represents the Python time zone
+   info type; it is the same object as "datetime.tzinfo" in the Python
+   layer.
+
+Macro for access to the UTC singleton:
+
+PyObject *PyDateTime_TimeZone_UTC
+
+   Returns the time zone singleton representing UTC, the same object
+   as "datetime.timezone.utc".
+
+   Added in version 3.7.
+
+Type-check macros:
+
+int PyDate_Check(PyObject *ob)
+
+   Return true if *ob* is of type "PyDateTime_DateType" or a subtype
+   of "PyDateTime_DateType".  *ob* must not be "NULL".  This function
+   always succeeds.
+
+int PyDate_CheckExact(PyObject *ob)
+
+   Return true if *ob* is of type "PyDateTime_DateType". *ob* must not
+   be "NULL".  This function always succeeds.
+
+int PyDateTime_Check(PyObject *ob)
+
+   Return true if *ob* is of type "PyDateTime_DateTimeType" or a
+   subtype of "PyDateTime_DateTimeType".  *ob* must not be "NULL".
+   This function always succeeds.
+
+int PyDateTime_CheckExact(PyObject *ob)
+
+   Return true if *ob* is of type "PyDateTime_DateTimeType". *ob* must
+   not be "NULL".  This function always succeeds.
+
+int PyTime_Check(PyObject *ob)
+
+   Return true if *ob* is of type "PyDateTime_TimeType" or a subtype
+   of "PyDateTime_TimeType".  *ob* must not be "NULL".  This function
+   always succeeds.
+
+int PyTime_CheckExact(PyObject *ob)
+
+   Return true if *ob* is of type "PyDateTime_TimeType". *ob* must not
+   be "NULL".  This function always succeeds.
+
+int PyDelta_Check(PyObject *ob)
+
+   Return true if *ob* is of type "PyDateTime_DeltaType" or a subtype
+   of "PyDateTime_DeltaType".  *ob* must not be "NULL".  This function
+   always succeeds.
+
+int PyDelta_CheckExact(PyObject *ob)
+
+   Return true if *ob* is of type "PyDateTime_DeltaType". *ob* must
+   not be "NULL".  This function always succeeds.
+
+int PyTZInfo_Check(PyObject *ob)
+
+   Return true if *ob* is of type "PyDateTime_TZInfoType" or a subtype
+   of "PyDateTime_TZInfoType".  *ob* must not be "NULL".  This
+   function always succeeds.
+
+int PyTZInfo_CheckExact(PyObject *ob)
+
+   Return true if *ob* is of type "PyDateTime_TZInfoType". *ob* must
+   not be "NULL".  This function always succeeds.
+
+Macros to create objects:
+
+PyObject *PyDate_FromDate(int year, int month, int day)
+    *Return value: New reference.*
+
+   Return a "datetime.date" object with the specified year, month and
+   day.
+
+PyObject *PyDateTime_FromDateAndTime(int year, int month, int day, int hour, int minute, int second, int usecond)
+    *Return value: New reference.*
+
+   Return a "datetime.datetime" object with the specified year, month,
+   day, hour, minute, second and microsecond.
+
+PyObject *PyDateTime_FromDateAndTimeAndFold(int year, int month, int day, int hour, int minute, int second, int usecond, int fold)
+    *Return value: New reference.*
+
+   Return a "datetime.datetime" object with the specified year, month,
+   day, hour, minute, second, microsecond and fold.
+
+   Added in version 3.6.
+
+PyObject *PyTime_FromTime(int hour, int minute, int second, int usecond)
+    *Return value: New reference.*
+
+   Return a "datetime.time" object with the specified hour, minute,
+   second and microsecond.
+
+PyObject *PyTime_FromTimeAndFold(int hour, int minute, int second, int usecond, int fold)
+    *Return value: New reference.*
+
+   Return a "datetime.time" object with the specified hour, minute,
+   second, microsecond and fold.
+
+   Added in version 3.6.
+
+PyObject *PyDelta_FromDSU(int days, int seconds, int useconds)
+    *Return value: New reference.*
+
+   Return a "datetime.timedelta" object representing the given number
+   of days, seconds and microseconds.  Normalization is performed so
+   that the resulting number of microseconds and seconds lie in the
+   ranges documented for "datetime.timedelta" objects.
+
+PyObject *PyTimeZone_FromOffset(PyObject *offset)
+    *Return value: New reference.*
+
+   Return a "datetime.timezone" object with an unnamed fixed offset
+   represented by the *offset* argument.
+
+   Added in version 3.7.
+
+PyObject *PyTimeZone_FromOffsetAndName(PyObject *offset, PyObject *name)
+    *Return value: New reference.*
+
+   Return a "datetime.timezone" object with a fixed offset represented
+   by the *offset* argument and with tzname *name*.
+
+   Added in version 3.7.
+
+Macros to extract fields from date objects.  The argument must be an
+instance of "PyDateTime_Date", including subclasses (such as
+"PyDateTime_DateTime").  The argument must not be "NULL", and the type
+is not checked:
+
+int PyDateTime_GET_YEAR(PyDateTime_Date *o)
+
+   Return the year, as a positive int.
+
+int PyDateTime_GET_MONTH(PyDateTime_Date *o)
+
+   Return the month, as an int from 1 through 12.
+
+int PyDateTime_GET_DAY(PyDateTime_Date *o)
+
+   Return the day, as an int from 1 through 31.
+
+Macros to extract fields from datetime objects.  The argument must be
+an instance of "PyDateTime_DateTime", including subclasses. The
+argument must not be "NULL", and the type is not checked:
+
+int PyDateTime_DATE_GET_HOUR(PyDateTime_DateTime *o)
+
+   Return the hour, as an int from 0 through 23.
+
+int PyDateTime_DATE_GET_MINUTE(PyDateTime_DateTime *o)
+
+   Return the minute, as an int from 0 through 59.
+
+int PyDateTime_DATE_GET_SECOND(PyDateTime_DateTime *o)
+
+   Return the second, as an int from 0 through 59.
+
+int PyDateTime_DATE_GET_MICROSECOND(PyDateTime_DateTime *o)
+
+   Return the microsecond, as an int from 0 through 999999.
+
+int PyDateTime_DATE_GET_FOLD(PyDateTime_DateTime *o)
+
+   Return the fold, as an int from 0 through 1.
+
+   Added in version 3.6.
+
+PyObject *PyDateTime_DATE_GET_TZINFO(PyDateTime_DateTime *o)
+
+   Return the tzinfo (which may be "None").
+
+   Added in version 3.10.
+
+Macros to extract fields from time objects.  The argument must be an
+instance of "PyDateTime_Time", including subclasses. The argument must
+not be "NULL", and the type is not checked:
+
+int PyDateTime_TIME_GET_HOUR(PyDateTime_Time *o)
+
+   Return the hour, as an int from 0 through 23.
+
+int PyDateTime_TIME_GET_MINUTE(PyDateTime_Time *o)
+
+   Return the minute, as an int from 0 through 59.
+
+int PyDateTime_TIME_GET_SECOND(PyDateTime_Time *o)
+
+   Return the second, as an int from 0 through 59.
+
+int PyDateTime_TIME_GET_MICROSECOND(PyDateTime_Time *o)
+
+   Return the microsecond, as an int from 0 through 999999.
+
+int PyDateTime_TIME_GET_FOLD(PyDateTime_Time *o)
+
+   Return the fold, as an int from 0 through 1.
+
+   Added in version 3.6.
+
+PyObject *PyDateTime_TIME_GET_TZINFO(PyDateTime_Time *o)
+
+   Return the tzinfo (which may be "None").
+
+   Added in version 3.10.
+
+Macros to extract fields from time delta objects.  The argument must
+be an instance of "PyDateTime_Delta", including subclasses. The
+argument must not be "NULL", and the type is not checked:
+
+int PyDateTime_DELTA_GET_DAYS(PyDateTime_Delta *o)
+
+   Return the number of days, as an int from -999999999 to 999999999.
+
+   Added in version 3.3.
+
+int PyDateTime_DELTA_GET_SECONDS(PyDateTime_Delta *o)
+
+   Return the number of seconds, as an int from 0 through 86399.
+
+   Added in version 3.3.
+
+int PyDateTime_DELTA_GET_MICROSECONDS(PyDateTime_Delta *o)
+
+   Return the number of microseconds, as an int from 0 through 999999.
+
+   Added in version 3.3.
+
+Macros for the convenience of modules implementing the DB API:
+
+PyObject *PyDateTime_FromTimestamp(PyObject *args)
+    *Return value: New reference.*
+
+   Create and return a new "datetime.datetime" object given an
+   argument tuple suitable for passing to
+   "datetime.datetime.fromtimestamp()".
+
+PyObject *PyDate_FromTimestamp(PyObject *args)
+    *Return value: New reference.*
+
+   Create and return a new "datetime.date" object given an argument
+   tuple suitable for passing to "datetime.date.fromtimestamp()".

python-3.12.6-docs-text/python-3.12.6-docs-text/c-api/descriptor.txt

@@ -0,0 +1,34 @@
+Descriptor Objects
+******************
+
+"Descriptors" are objects that describe some attribute of an object.
+They are found in the dictionary of type objects.
+
+PyTypeObject PyProperty_Type
+    * Part of the Stable ABI.*
+
+   The type object for the built-in descriptor types.
+
+PyObject *PyDescr_NewGetSet(PyTypeObject *type, struct PyGetSetDef *getset)
+    *Return value: New reference.** Part of the Stable ABI.*
+
+PyObject *PyDescr_NewMember(PyTypeObject *type, struct PyMemberDef *meth)
+    *Return value: New reference.** Part of the Stable ABI.*
+
+PyObject *PyDescr_NewMethod(PyTypeObject *type, struct PyMethodDef *meth)
+    *Return value: New reference.** Part of the Stable ABI.*
+
+PyObject *PyDescr_NewWrapper(PyTypeObject *type, struct wrapperbase *wrapper, void *wrapped)
+    *Return value: New reference.*
+
+PyObject *PyDescr_NewClassMethod(PyTypeObject *type, PyMethodDef *method)
+    *Return value: New reference.** Part of the Stable ABI.*
+
+int PyDescr_IsData(PyObject *descr)
+
+   Return non-zero if the descriptor objects *descr* describes a data
+   attribute, or "0" if it describes a method.  *descr* must be a
+   descriptor object; there is no error checking.
+
+PyObject *PyWrapper_New(PyObject*, PyObject*)
+    *Return value: New reference.** Part of the Stable ABI.*

python-3.12.6-docs-text/python-3.12.6-docs-text/c-api/dict.txt

@@ -0,0 +1,325 @@
+Dictionary Objects
+******************
+
+type PyDictObject
+
+   This subtype of "PyObject" represents a Python dictionary object.
+
+PyTypeObject PyDict_Type
+    * Part of the Stable ABI.*
+
+   This instance of "PyTypeObject" represents the Python dictionary
+   type.  This is the same object as "dict" in the Python layer.
+
+int PyDict_Check(PyObject *p)
+
+   Return true if *p* is a dict object or an instance of a subtype of
+   the dict type.  This function always succeeds.
+
+int PyDict_CheckExact(PyObject *p)
+
+   Return true if *p* is a dict object, but not an instance of a
+   subtype of the dict type.  This function always succeeds.
+
+PyObject *PyDict_New()
+    *Return value: New reference.** Part of the Stable ABI.*
+
+   Return a new empty dictionary, or "NULL" on failure.
+
+PyObject *PyDictProxy_New(PyObject *mapping)
+    *Return value: New reference.** Part of the Stable ABI.*
+
+   Return a "types.MappingProxyType" object for a mapping which
+   enforces read-only behavior.  This is normally used to create a
+   view to prevent modification of the dictionary for non-dynamic
+   class types.
+
+void PyDict_Clear(PyObject *p)
+    * Part of the Stable ABI.*
+
+   Empty an existing dictionary of all key-value pairs.
+
+int PyDict_Contains(PyObject *p, PyObject *key)
+    * Part of the Stable ABI.*
+
+   Determine if dictionary *p* contains *key*.  If an item in *p* is
+   matches *key*, return "1", otherwise return "0".  On error, return
+   "-1". This is equivalent to the Python expression "key in p".
+
+PyObject *PyDict_Copy(PyObject *p)
+    *Return value: New reference.** Part of the Stable ABI.*
+
+   Return a new dictionary that contains the same key-value pairs as
+   *p*.
+
+int PyDict_SetItem(PyObject *p, PyObject *key, PyObject *val)
+    * Part of the Stable ABI.*
+
+   Insert *val* into the dictionary *p* with a key of *key*.  *key*
+   must be *hashable*; if it isn't, "TypeError" will be raised. Return
+   "0" on success or "-1" on failure.  This function *does not* steal
+   a reference to *val*.
+
+int PyDict_SetItemString(PyObject *p, const char *key, PyObject *val)
+    * Part of the Stable ABI.*
+
+   This is the same as "PyDict_SetItem()", but *key* is specified as a
+   const char* UTF-8 encoded bytes string, rather than a PyObject*.
+
+int PyDict_DelItem(PyObject *p, PyObject *key)
+    * Part of the Stable ABI.*
+
+   Remove the entry in dictionary *p* with key *key*. *key* must be
+   *hashable*; if it isn't, "TypeError" is raised. If *key* is not in
+   the dictionary, "KeyError" is raised. Return "0" on success or "-1"
+   on failure.
+
+int PyDict_DelItemString(PyObject *p, const char *key)
+    * Part of the Stable ABI.*
+
+   This is the same as "PyDict_DelItem()", but *key* is specified as a
+   const char* UTF-8 encoded bytes string, rather than a PyObject*.
+
+PyObject *PyDict_GetItem(PyObject *p, PyObject *key)
+    *Return value: Borrowed reference.** Part of the Stable ABI.*
+
+   Return the object from dictionary *p* which has a key *key*.
+   Return "NULL" if the key *key* is not present, but *without*
+   setting an exception.
+
+   Note:
+
+     Exceptions that occur while this calls "__hash__()" and
+     "__eq__()" methods are silently ignored. Prefer the
+     "PyDict_GetItemWithError()" function instead.
+
+   Changed in version 3.10: Calling this API without *GIL* held had
+   been allowed for historical reason. It is no longer allowed.
+
+PyObject *PyDict_GetItemWithError(PyObject *p, PyObject *key)
+    *Return value: Borrowed reference.** Part of the Stable ABI.*
+
+   Variant of "PyDict_GetItem()" that does not suppress exceptions.
+   Return "NULL" **with** an exception set if an exception occurred.
+   Return "NULL" **without** an exception set if the key wasn't
+   present.
+
+PyObject *PyDict_GetItemString(PyObject *p, const char *key)
+    *Return value: Borrowed reference.** Part of the Stable ABI.*
+
+   This is the same as "PyDict_GetItem()", but *key* is specified as a
+   const char* UTF-8 encoded bytes string, rather than a PyObject*.
+
+   Note:
+
+     Exceptions that occur while this calls "__hash__()" and
+     "__eq__()" methods or while creating the temporary "str" object
+     are silently ignored. Prefer using the
+     "PyDict_GetItemWithError()" function with your own
+     "PyUnicode_FromString()" *key* instead.
+
+PyObject *PyDict_SetDefault(PyObject *p, PyObject *key, PyObject *defaultobj)
+    *Return value: Borrowed reference.*
+
+   This is the same as the Python-level "dict.setdefault()".  If
+   present, it returns the value corresponding to *key* from the
+   dictionary *p*.  If the key is not in the dict, it is inserted with
+   value *defaultobj* and *defaultobj* is returned.  This function
+   evaluates the hash function of *key* only once, instead of
+   evaluating it independently for the lookup and the insertion.
+
+   Added in version 3.4.
+
+PyObject *PyDict_Items(PyObject *p)
+    *Return value: New reference.** Part of the Stable ABI.*
+
+   Return a "PyListObject" containing all the items from the
+   dictionary.
+
+PyObject *PyDict_Keys(PyObject *p)
+    *Return value: New reference.** Part of the Stable ABI.*
+
+   Return a "PyListObject" containing all the keys from the
+   dictionary.
+
+PyObject *PyDict_Values(PyObject *p)
+    *Return value: New reference.** Part of the Stable ABI.*
+
+   Return a "PyListObject" containing all the values from the
+   dictionary *p*.
+
+Py_ssize_t PyDict_Size(PyObject *p)
+    * Part of the Stable ABI.*
+
+   Return the number of items in the dictionary.  This is equivalent
+   to "len(p)" on a dictionary.
+
+int PyDict_Next(PyObject *p, Py_ssize_t *ppos, PyObject **pkey, PyObject **pvalue)
+    * Part of the Stable ABI.*
+
+   Iterate over all key-value pairs in the dictionary *p*.  The
+   "Py_ssize_t" referred to by *ppos* must be initialized to "0" prior
+   to the first call to this function to start the iteration; the
+   function returns true for each pair in the dictionary, and false
+   once all pairs have been reported.  The parameters *pkey* and
+   *pvalue* should either point to PyObject* variables that will be
+   filled in with each key and value, respectively, or may be "NULL".
+   Any references returned through them are borrowed.  *ppos* should
+   not be altered during iteration. Its value represents offsets
+   within the internal dictionary structure, and since the structure
+   is sparse, the offsets are not consecutive.
+
+   For example:
+
+      PyObject *key, *value;
+      Py_ssize_t pos = 0;
+
+      while (PyDict_Next(self->dict, &pos, &key, &value)) {
+          /* do something interesting with the values... */
+          ...
+      }
+
+   The dictionary *p* should not be mutated during iteration.  It is
+   safe to modify the values of the keys as you iterate over the
+   dictionary, but only so long as the set of keys does not change.
+   For example:
+
+      PyObject *key, *value;
+      Py_ssize_t pos = 0;
+
+      while (PyDict_Next(self->dict, &pos, &key, &value)) {
+          long i = PyLong_AsLong(value);
+          if (i == -1 && PyErr_Occurred()) {
+              return -1;
+          }
+          PyObject *o = PyLong_FromLong(i + 1);
+          if (o == NULL)
+              return -1;
+          if (PyDict_SetItem(self->dict, key, o) < 0) {
+              Py_DECREF(o);
+              return -1;
+          }
+          Py_DECREF(o);
+      }
+
+int PyDict_Merge(PyObject *a, PyObject *b, int override)
+    * Part of the Stable ABI.*
+
+   Iterate over mapping object *b* adding key-value pairs to
+   dictionary *a*. *b* may be a dictionary, or any object supporting
+   "PyMapping_Keys()" and "PyObject_GetItem()". If *override* is true,
+   existing pairs in *a* will be replaced if a matching key is found
+   in *b*, otherwise pairs will only be added if there is not a
+   matching key in *a*. Return "0" on success or "-1" if an exception
+   was raised.
+
+int PyDict_Update(PyObject *a, PyObject *b)
+    * Part of the Stable ABI.*
+
+   This is the same as "PyDict_Merge(a, b, 1)" in C, and is similar to
+   "a.update(b)" in Python except that "PyDict_Update()" doesn't fall
+   back to the iterating over a sequence of key value pairs if the
+   second argument has no "keys" attribute.  Return "0" on success or
+   "-1" if an exception was raised.
+
+int PyDict_MergeFromSeq2(PyObject *a, PyObject *seq2, int override)
+    * Part of the Stable ABI.*
+
+   Update or merge into dictionary *a*, from the key-value pairs in
+   *seq2*. *seq2* must be an iterable object producing iterable
+   objects of length 2, viewed as key-value pairs.  In case of
+   duplicate keys, the last wins if *override* is true, else the first
+   wins. Return "0" on success or "-1" if an exception was raised.
+   Equivalent Python (except for the return value):
+
+      def PyDict_MergeFromSeq2(a, seq2, override):
+          for key, value in seq2:
+              if override or key not in a:
+                  a[key] = value
+
+int PyDict_AddWatcher(PyDict_WatchCallback callback)
+
+   Register *callback* as a dictionary watcher. Return a non-negative
+   integer id which must be passed to future calls to
+   "PyDict_Watch()". In case of error (e.g. no more watcher IDs
+   available), return "-1" and set an exception.
+
+   Added in version 3.12.
+
+int PyDict_ClearWatcher(int watcher_id)
+
+   Clear watcher identified by *watcher_id* previously returned from
+   "PyDict_AddWatcher()". Return "0" on success, "-1" on error (e.g.
+   if the given *watcher_id* was never registered.)
+
+   Added in version 3.12.
+
+int PyDict_Watch(int watcher_id, PyObject *dict)
+
+   Mark dictionary *dict* as watched. The callback granted
+   *watcher_id* by "PyDict_AddWatcher()" will be called when *dict* is
+   modified or deallocated. Return "0" on success or "-1" on error.
+
+   Added in version 3.12.
+
+int PyDict_Unwatch(int watcher_id, PyObject *dict)
+
+   Mark dictionary *dict* as no longer watched. The callback granted
+   *watcher_id* by "PyDict_AddWatcher()" will no longer be called when
+   *dict* is modified or deallocated. The dict must previously have
+   been watched by this watcher. Return "0" on success or "-1" on
+   error.
+
+   Added in version 3.12.
+
+type PyDict_WatchEvent
+
+   Enumeration of possible dictionary watcher events:
+   "PyDict_EVENT_ADDED", "PyDict_EVENT_MODIFIED",
+   "PyDict_EVENT_DELETED", "PyDict_EVENT_CLONED",
+   "PyDict_EVENT_CLEARED", or "PyDict_EVENT_DEALLOCATED".
+
+   Added in version 3.12.
+
+typedef int (*PyDict_WatchCallback)(PyDict_WatchEvent event, PyObject *dict, PyObject *key, PyObject *new_value)
+
+   Type of a dict watcher callback function.
+
+   If *event* is "PyDict_EVENT_CLEARED" or "PyDict_EVENT_DEALLOCATED",
+   both *key* and *new_value* will be "NULL". If *event* is
+   "PyDict_EVENT_ADDED" or "PyDict_EVENT_MODIFIED", *new_value* will
+   be the new value for *key*. If *event* is "PyDict_EVENT_DELETED",
+   *key* is being deleted from the dictionary and *new_value* will be
+   "NULL".
+
+   "PyDict_EVENT_CLONED" occurs when *dict* was previously empty and
+   another dict is merged into it. To maintain efficiency of this
+   operation, per-key "PyDict_EVENT_ADDED" events are not issued in
+   this case; instead a single "PyDict_EVENT_CLONED" is issued, and
+   *key* will be the source dictionary.
+
+   The callback may inspect but must not modify *dict*; doing so could
+   have unpredictable effects, including infinite recursion. Do not
+   trigger Python code execution in the callback, as it could modify
+   the dict as a side effect.
+
+   If *event* is "PyDict_EVENT_DEALLOCATED", taking a new reference in
+   the callback to the about-to-be-destroyed dictionary will resurrect
+   it and prevent it from being freed at this time. When the
+   resurrected object is destroyed later, any watcher callbacks active
+   at that time will be called again.
+
+   Callbacks occur before the notified modification to *dict* takes
+   place, so the prior state of *dict* can be inspected.
+
+   If the callback sets an exception, it must return "-1"; this
+   exception will be printed as an unraisable exception using
+   "PyErr_WriteUnraisable()". Otherwise it should return "0".
+
+   There may already be a pending exception set on entry to the
+   callback. In this case, the callback should return "0" with the
+   same exception still set. This means the callback may not call any
+   other API that can set an exception unless it saves and clears the
+   exception state first, and restores it before returning.
+
+   Added in version 3.12.

python-3.12.6-docs-text/python-3.12.6-docs-text/c-api/exceptions.txt

@@ -0,0 +1,1173 @@
+Exception Handling
+******************
+
+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
+"errno" variable: there is a global indicator (per thread) of the last
+error that occurred.  Most C API functions don't clear this on
+success, but will set it to indicate the cause of the error on
+failure.  Most C API functions also return an error indicator, usually
+"NULL" if they are supposed to return a pointer, or "-1" if they
+return an integer (exception: the "PyArg_*" functions return "1" for
+success and "0" for failure).
+
+Concretely, the error indicator consists of three object pointers: the
+exception's type, the exception's value, and the traceback object.
+Any of those pointers can be "NULL" if non-set (although some
+combinations are forbidden, for example you can't have a non-"NULL"
+traceback if the exception type is "NULL").
+
+When a function must fail because some function it called failed, it
+generally doesn't set the error indicator; the function it called
+already set it.  It is responsible for either handling the error and
+clearing the exception or returning after cleaning up any resources it
+holds (such as object references or memory allocations); it should
+*not* continue normally if it is not prepared to handle the error.  If
+returning due to an error, it is important to indicate to the caller
+that an error has been set.  If the error is not handled or carefully
+propagated, additional calls into the Python/C API may not behave as
+intended and may fail in mysterious ways.
+
+Note:
+
+  The error indicator is **not** the result of "sys.exc_info()". The
+  former corresponds to an exception that is not yet caught (and is
+  therefore still propagating), while the latter returns an exception
+  after it is caught (and has therefore stopped propagating).
+
+
+Printing and clearing
+=====================
+
+void PyErr_Clear()
+    * Part of the Stable ABI.*
+
+   Clear the error indicator.  If the error indicator is not set,
+   there is no effect.
+
+void PyErr_PrintEx(int set_sys_last_vars)
+    * Part of the Stable ABI.*
+
+   Print a standard traceback to "sys.stderr" and clear the error
+   indicator. **Unless** the error is a "SystemExit", in that case no
+   traceback is printed and the Python process will exit with the
+   error code specified by the "SystemExit" instance.
+
+   Call this function **only** when the error indicator is set.
+   Otherwise it will cause a fatal error!
+
+   If *set_sys_last_vars* is nonzero, the variable "sys.last_exc" is
+   set to the printed exception. For backwards compatibility, the
+   deprecated variables "sys.last_type", "sys.last_value" and
+   "sys.last_traceback" are also set to the type, value and traceback
+   of this exception, respectively.
+
+   Changed in version 3.12: The setting of "sys.last_exc" was added.
+
+void PyErr_Print()
+    * Part of the Stable ABI.*
+
+   Alias for "PyErr_PrintEx(1)".
+
+void PyErr_WriteUnraisable(PyObject *obj)
+    * Part of the Stable ABI.*
+
+   Call "sys.unraisablehook()" using the current exception and *obj*
+   argument.
+
+   This utility function prints a warning message to "sys.stderr" when
+   an exception has been set but it is impossible for the interpreter
+   to actually raise the exception.  It is used, for example, when an
+   exception occurs in an "__del__()" method.
+
+   The function is called with a single argument *obj* that identifies
+   the context in which the unraisable exception occurred. If
+   possible, the repr of *obj* will be printed in the warning message.
+   If *obj* is "NULL", only the traceback is printed.
+
+   An exception must be set when calling this function.
+
+   Changed in version 3.4: Print a traceback. Print only traceback if
+   *obj* is "NULL".
+
+   Changed in version 3.8: Use "sys.unraisablehook()".
+
+void PyErr_DisplayException(PyObject *exc)
+    * Part of the Stable ABI since version 3.12.*
+
+   Print the standard traceback display of "exc" to "sys.stderr",
+   including chained exceptions and notes.
+
+   Added in version 3.12.
+
+
+Raising exceptions
+==================
+
+These functions help you set the current thread's error indicator. For
+convenience, some of these functions will always return a "NULL"
+pointer for use in a "return" statement.
+
+void PyErr_SetString(PyObject *type, const char *message)
+    * Part of the Stable ABI.*
+
+   This is the most common way to set the error indicator.  The first
+   argument specifies the exception type; it is normally one of the
+   standard exceptions, e.g. "PyExc_RuntimeError".  You need not
+   create a new *strong reference* to it (e.g. with "Py_INCREF()").
+   The second argument is an error message; it is decoded from
+   "'utf-8'".
+
+void PyErr_SetObject(PyObject *type, PyObject *value)
+    * Part of the Stable ABI.*
+
+   This function is similar to "PyErr_SetString()" but lets you
+   specify an arbitrary Python object for the "value" of the
+   exception.
+
+PyObject *PyErr_Format(PyObject *exception, const char *format, ...)
+    *Return value: Always NULL.** Part of the Stable ABI.*
+
+   This function sets the error indicator and returns "NULL".
+   *exception* should be a Python exception class.  The *format* and
+   subsequent parameters help format the error message; they have the
+   same meaning and values as in "PyUnicode_FromFormat()". *format* is
+   an ASCII-encoded string.
+
+PyObject *PyErr_FormatV(PyObject *exception, const char *format, va_list vargs)
+    *Return value: Always NULL.** Part of the Stable ABI since version
+   3.5.*
+
+   Same as "PyErr_Format()", but taking a "va_list" argument rather
+   than a variable number of arguments.
+
+   Added in version 3.5.
+
+void PyErr_SetNone(PyObject *type)
+    * Part of the Stable ABI.*
+
+   This is a shorthand for "PyErr_SetObject(type, Py_None)".
+
+int PyErr_BadArgument()
+    * Part of the Stable ABI.*
+
+   This is a shorthand for "PyErr_SetString(PyExc_TypeError,
+   message)", where *message* indicates that a built-in operation was
+   invoked with an illegal argument.  It is mostly for internal use.
+
+PyObject *PyErr_NoMemory()
+    *Return value: Always NULL.** Part of the Stable ABI.*
+
+   This is a shorthand for "PyErr_SetNone(PyExc_MemoryError)"; it
+   returns "NULL" so an object allocation function can write "return
+   PyErr_NoMemory();" when it runs out of memory.
+
+PyObject *PyErr_SetFromErrno(PyObject *type)
+    *Return value: Always NULL.** Part of the Stable ABI.*
+
+   This is a convenience function to raise an exception when a C
+   library function has returned an error and set the C variable
+   "errno".  It constructs a tuple object whose first item is the
+   integer "errno" value and whose second item is the corresponding
+   error message (gotten from "strerror()"), and then calls
+   "PyErr_SetObject(type, object)".  On Unix, when the "errno" value
+   is "EINTR", indicating an interrupted system call, this calls
+   "PyErr_CheckSignals()", and if that set the error indicator, leaves
+   it set to that.  The function always returns "NULL", so a wrapper
+   function around a system call can write "return
+   PyErr_SetFromErrno(type);" when the system call returns an error.
+
+PyObject *PyErr_SetFromErrnoWithFilenameObject(PyObject *type, PyObject *filenameObject)
+    *Return value: Always NULL.** Part of the Stable ABI.*
+
+   Similar to "PyErr_SetFromErrno()", with the additional behavior
+   that if *filenameObject* is not "NULL", it is passed to the
+   constructor of *type* as a third parameter.  In the case of
+   "OSError" exception, this is used to define the "filename"
+   attribute of the exception instance.
+
+PyObject *PyErr_SetFromErrnoWithFilenameObjects(PyObject *type, PyObject *filenameObject, PyObject *filenameObject2)
+    *Return value: Always NULL.** Part of the Stable ABI since version
+   3.7.*
+
+   Similar to "PyErr_SetFromErrnoWithFilenameObject()", but takes a
+   second filename object, for raising errors when a function that
+   takes two filenames fails.
+
+   Added in version 3.4.
+
+PyObject *PyErr_SetFromErrnoWithFilename(PyObject *type, const char *filename)
+    *Return value: Always NULL.** Part of the Stable ABI.*
+
+   Similar to "PyErr_SetFromErrnoWithFilenameObject()", but the
+   filename is given as a C string.  *filename* is decoded from the
+   *filesystem encoding and error handler*.
+
+PyObject *PyErr_SetFromWindowsErr(int ierr)
+    *Return value: Always NULL.** Part of the Stable ABI on Windows
+   since version 3.7.*
+
+   This is a convenience function to raise "OSError". If called with
+   *ierr* of "0", the error code returned by a call to
+   "GetLastError()" is used instead.  It calls the Win32 function
+   "FormatMessage()" to retrieve the Windows description of error code
+   given by *ierr* or "GetLastError()", then it constructs a "OSError"
+   object with the "winerror" attribute set to the error code, the
+   "strerror" attribute set to the corresponding error message (gotten
+   from "FormatMessage()"), and then calls
+   "PyErr_SetObject(PyExc_OSError, object)". This function always
+   returns "NULL".
+
+   Availability: Windows.
+
+PyObject *PyErr_SetExcFromWindowsErr(PyObject *type, int ierr)
+    *Return value: Always NULL.** Part of the Stable ABI on Windows
+   since version 3.7.*
+
+   Similar to "PyErr_SetFromWindowsErr()", with an additional
+   parameter specifying the exception type to be raised.
+
+   Availability: Windows.
+
+PyObject *PyErr_SetFromWindowsErrWithFilename(int ierr, const char *filename)
+    *Return value: Always NULL.** Part of the Stable ABI on Windows
+   since version 3.7.*
+
+   Similar to "PyErr_SetFromWindowsErr()", with the additional
+   behavior that if *filename* is not "NULL", it is decoded from the
+   filesystem encoding ("os.fsdecode()") and passed to the constructor
+   of "OSError" as a third parameter to be used to define the
+   "filename" attribute of the exception instance.
+
+   Availability: Windows.
+
+PyObject *PyErr_SetExcFromWindowsErrWithFilenameObject(PyObject *type, int ierr, PyObject *filename)
+    *Return value: Always NULL.** Part of the Stable ABI on Windows
+   since version 3.7.*
+
+   Similar to "PyErr_SetExcFromWindowsErr()", with the additional
+   behavior that if *filename* is not "NULL", it is passed to the
+   constructor of "OSError" as a third parameter to be used to define
+   the "filename" attribute of the exception instance.
+
+   Availability: Windows.
+
+PyObject *PyErr_SetExcFromWindowsErrWithFilenameObjects(PyObject *type, int ierr, PyObject *filename, PyObject *filename2)
+    *Return value: Always NULL.** Part of the Stable ABI on Windows
+   since version 3.7.*
+
+   Similar to "PyErr_SetExcFromWindowsErrWithFilenameObject()", but
+   accepts a second filename object.
+
+   Availability: Windows.
+
+   Added in version 3.4.
+
+PyObject *PyErr_SetExcFromWindowsErrWithFilename(PyObject *type, int ierr, const char *filename)
+    *Return value: Always NULL.** Part of the Stable ABI on Windows
+   since version 3.7.*
+
+   Similar to "PyErr_SetFromWindowsErrWithFilename()", with an
+   additional parameter specifying the exception type to be raised.
+
+   Availability: Windows.
+
+PyObject *PyErr_SetImportError(PyObject *msg, PyObject *name, PyObject *path)
+    *Return value: Always NULL.** Part of the Stable ABI since version
+   3.7.*
+
+   This is a convenience function to raise "ImportError". *msg* will
+   be set as the exception's message string. *name* and *path*, both
+   of which can be "NULL", will be set as the "ImportError"'s
+   respective "name" and "path" attributes.
+
+   Added in version 3.3.
+
+PyObject *PyErr_SetImportErrorSubclass(PyObject *exception, PyObject *msg, PyObject *name, PyObject *path)
+    *Return value: Always NULL.** Part of the Stable ABI since version
+   3.6.*
+
+   Much like "PyErr_SetImportError()" but this function allows for
+   specifying a subclass of "ImportError" to raise.
+
+   Added in version 3.6.
+
+void PyErr_SyntaxLocationObject(PyObject *filename, int lineno, int col_offset)
+
+   Set file, line, and offset information for the current exception.
+   If the current exception is not a "SyntaxError", then it sets
+   additional attributes, which make the exception printing subsystem
+   think the exception is a "SyntaxError".
+
+   Added in version 3.4.
+
+void PyErr_SyntaxLocationEx(const char *filename, int lineno, int col_offset)
+    * Part of the Stable ABI since version 3.7.*
+
+   Like "PyErr_SyntaxLocationObject()", but *filename* is a byte
+   string decoded from the *filesystem encoding and error handler*.
+
+   Added in version 3.2.
+
+void PyErr_SyntaxLocation(const char *filename, int lineno)
+    * Part of the Stable ABI.*
+
+   Like "PyErr_SyntaxLocationEx()", but the *col_offset* parameter is
+   omitted.
+
+void PyErr_BadInternalCall()
+    * Part of the Stable ABI.*
+
+   This is a shorthand for "PyErr_SetString(PyExc_SystemError,
+   message)", where *message* indicates that an internal operation
+   (e.g. a Python/C API function) was invoked with an illegal
+   argument.  It is mostly for internal use.
+
+
+Issuing warnings
+================
+
+Use these functions to issue warnings from C code.  They mirror
+similar functions exported by the Python "warnings" module.  They
+normally print a warning message to *sys.stderr*; however, it is also
+possible that the user has specified that warnings are to be turned
+into errors, and in that case they will raise an exception.  It is
+also possible that the functions raise an exception because of a
+problem with the warning machinery. The return value is "0" if no
+exception is raised, or "-1" if an exception is raised.  (It is not
+possible to determine whether a warning message is actually printed,
+nor what the reason is for the exception; this is intentional.)  If an
+exception is raised, the caller should do its normal exception
+handling (for example, "Py_DECREF()" owned references and return an
+error value).
+
+int PyErr_WarnEx(PyObject *category, const char *message, Py_ssize_t stack_level)
+    * Part of the Stable ABI.*
+
+   Issue a warning message.  The *category* argument is a warning
+   category (see below) or "NULL"; the *message* argument is a UTF-8
+   encoded string.  *stack_level* is a positive number giving a number
+   of stack frames; the warning will be issued from the  currently
+   executing line of code in that stack frame.  A *stack_level* of 1
+   is the function calling "PyErr_WarnEx()", 2 is  the function above
+   that, and so forth.
+
+   Warning categories must be subclasses of "PyExc_Warning";
+   "PyExc_Warning" is a subclass of "PyExc_Exception"; the default
+   warning category is "PyExc_RuntimeWarning". The standard Python
+   warning categories are available as global variables whose names
+   are enumerated at Standard Warning Categories.
+
+   For information about warning control, see the documentation for
+   the "warnings" module and the "-W" option in the command line
+   documentation.  There is no C API for warning control.
+
+int PyErr_WarnExplicitObject(PyObject *category, PyObject *message, PyObject *filename, int lineno, PyObject *module, PyObject *registry)
+
+   Issue a warning message with explicit control over all warning
+   attributes.  This is a straightforward wrapper around the Python
+   function "warnings.warn_explicit()"; see there for more
+   information.  The *module* and *registry* arguments may be set to
+   "NULL" to get the default effect described there.
+
+   Added in version 3.4.
+
+int PyErr_WarnExplicit(PyObject *category, const char *message, const char *filename, int lineno, const char *module, PyObject *registry)
+    * Part of the Stable ABI.*
+
+   Similar to "PyErr_WarnExplicitObject()" except that *message* and
+   *module* are UTF-8 encoded strings, and *filename* is decoded from
+   the *filesystem encoding and error handler*.
+
+int PyErr_WarnFormat(PyObject *category, Py_ssize_t stack_level, const char *format, ...)
+    * Part of the Stable ABI.*
+
+   Function similar to "PyErr_WarnEx()", but use
+   "PyUnicode_FromFormat()" to format the warning message.  *format*
+   is an ASCII-encoded string.
+
+   Added in version 3.2.
+
+int PyErr_ResourceWarning(PyObject *source, Py_ssize_t stack_level, const char *format, ...)
+    * Part of the Stable ABI since version 3.6.*
+
+   Function similar to "PyErr_WarnFormat()", but *category* is
+   "ResourceWarning" and it passes *source* to
+   "warnings.WarningMessage".
+
+   Added in version 3.6.
+
+
+Querying the error indicator
+============================
+
+PyObject *PyErr_Occurred()
+    *Return value: Borrowed reference.** Part of the Stable ABI.*
+
+   Test whether the error indicator is set.  If set, return the
+   exception *type* (the first argument to the last call to one of the
+   "PyErr_Set*" functions or to "PyErr_Restore()").  If not set,
+   return "NULL".  You do not own a reference to the return value, so
+   you do not need to "Py_DECREF()" it.
+
+   The caller must hold the GIL.
+
+   Note:
+
+     Do not compare the return value to a specific exception; use
+     "PyErr_ExceptionMatches()" instead, shown below.  (The comparison
+     could easily fail since the exception may be an instance instead
+     of a class, in the case of a class exception, or it may be a
+     subclass of the expected exception.)
+
+int PyErr_ExceptionMatches(PyObject *exc)
+    * Part of the Stable ABI.*
+
+   Equivalent to "PyErr_GivenExceptionMatches(PyErr_Occurred(), exc)".
+   This should only be called when an exception is actually set; a
+   memory access violation will occur if no exception has been raised.
+
+int PyErr_GivenExceptionMatches(PyObject *given, PyObject *exc)
+    * Part of the Stable ABI.*
+
+   Return true if the *given* exception matches the exception type in
+   *exc*.  If *exc* is a class object, this also returns true when
+   *given* is an instance of a subclass.  If *exc* is a tuple, all
+   exception types in the tuple (and recursively in subtuples) are
+   searched for a match.
+
+PyObject *PyErr_GetRaisedException(void)
+    *Return value: New reference.** Part of the Stable ABI since
+   version 3.12.*
+
+   Return the exception currently being raised, clearing the error
+   indicator at the same time. Return "NULL" if the error indicator is
+   not set.
+
+   This function is used by code that needs to catch exceptions, or
+   code that needs to save and restore the error indicator
+   temporarily.
+
+   For example:
+
+      {
+         PyObject *exc = PyErr_GetRaisedException();
+
+         /* ... code that might produce other errors ... */
+
+         PyErr_SetRaisedException(exc);
+      }
+
+   See also:
+
+     "PyErr_GetHandledException()", to save the exception currently
+     being handled.
+
+   Added in version 3.12.
+
+void PyErr_SetRaisedException(PyObject *exc)
+    * Part of the Stable ABI since version 3.12.*
+
+   Set *exc* as the exception currently being raised, clearing the
+   existing exception if one is set.
+
+   Warning:
+
+     This call steals a reference to *exc*, which must be a valid
+     exception.
+
+   Added in version 3.12.
+
+void PyErr_Fetch(PyObject **ptype, PyObject **pvalue, PyObject **ptraceback)
+    * Part of the Stable ABI.*
+
+   Deprecated since version 3.12: Use "PyErr_GetRaisedException()"
+   instead.
+
+   Retrieve the error indicator into three variables whose addresses
+   are passed. If the error indicator is not set, set all three
+   variables to "NULL".  If it is set, it will be cleared and you own
+   a reference to each object retrieved.  The value and traceback
+   object may be "NULL" even when the type object is not.
+
+   Note:
+
+     This function is normally only used by legacy code that needs to
+     catch exceptions or save and restore the error indicator
+     temporarily.For example:
+
+        {
+           PyObject *type, *value, *traceback;
+           PyErr_Fetch(&type, &value, &traceback);
+
+           /* ... code that might produce other errors ... */
+
+           PyErr_Restore(type, value, traceback);
+        }
+
+void PyErr_Restore(PyObject *type, PyObject *value, PyObject *traceback)
+    * Part of the Stable ABI.*
+
+   Deprecated since version 3.12: Use "PyErr_SetRaisedException()"
+   instead.
+
+   Set the error indicator from the three objects, *type*, *value*,
+   and *traceback*, clearing the existing exception if one is set. If
+   the objects are "NULL", the error indicator is cleared.  Do not
+   pass a "NULL" type and non-"NULL" value or traceback.  The
+   exception type should be a class.  Do not pass an invalid exception
+   type or value. (Violating these rules will cause subtle problems
+   later.)  This call takes away a reference to each object: you must
+   own a reference to each object before the call and after the call
+   you no longer own these references.  (If you don't understand this,
+   don't use this function.  I warned you.)
+
+   Note:
+
+     This function is normally only used by legacy code that needs to
+     save and restore the error indicator temporarily. Use
+     "PyErr_Fetch()" to save the current error indicator.
+
+void PyErr_NormalizeException(PyObject **exc, PyObject **val, PyObject **tb)
+    * Part of the Stable ABI.*
+
+   Deprecated since version 3.12: Use "PyErr_GetRaisedException()"
+   instead, to avoid any possible de-normalization.
+
+   Under certain circumstances, the values returned by "PyErr_Fetch()"
+   below can be "unnormalized", meaning that "*exc" is a class object
+   but "*val" is not an instance of the  same class.  This function
+   can be used to instantiate the class in that case.  If the values
+   are already normalized, nothing happens. The delayed normalization
+   is implemented to improve performance.
+
+   Note:
+
+     This function *does not* implicitly set the "__traceback__"
+     attribute on the exception value. If setting the traceback
+     appropriately is desired, the following additional snippet is
+     needed:
+
+        if (tb != NULL) {
+          PyException_SetTraceback(val, tb);
+        }
+
+PyObject *PyErr_GetHandledException(void)
+    * Part of the Stable ABI since version 3.11.*
+
+   Retrieve the active exception instance, as would be returned by
+   "sys.exception()". This refers to an exception that was *already
+   caught*, not to an exception that was freshly raised. Returns a new
+   reference to the exception or "NULL". Does not modify the
+   interpreter's exception state.
+
+   Note:
+
+     This function is not normally used by code that wants to handle
+     exceptions. Rather, it can be used when code needs to save and
+     restore the exception state temporarily.  Use
+     "PyErr_SetHandledException()" to restore or clear the exception
+     state.
+
+   Added in version 3.11.
+
+void PyErr_SetHandledException(PyObject *exc)
+    * Part of the Stable ABI since version 3.11.*
+
+   Set the active exception, as known from "sys.exception()".  This
+   refers to an exception that was *already caught*, not to an
+   exception that was freshly raised. To clear the exception state,
+   pass "NULL".
+
+   Note:
+
+     This function is not normally used by code that wants to handle
+     exceptions. Rather, it can be used when code needs to save and
+     restore the exception state temporarily.  Use
+     "PyErr_GetHandledException()" to get the exception state.
+
+   Added in version 3.11.
+
+void PyErr_GetExcInfo(PyObject **ptype, PyObject **pvalue, PyObject **ptraceback)
+    * Part of the Stable ABI since version 3.7.*
+
+   Retrieve the old-style representation of the exception info, as
+   known from "sys.exc_info()".  This refers to an exception that was
+   *already caught*, not to an exception that was freshly raised.
+   Returns new references for the three objects, any of which may be
+   "NULL".  Does not modify the exception info state.  This function
+   is kept for backwards compatibility. Prefer using
+   "PyErr_GetHandledException()".
+
+   Note:
+
+     This function is not normally used by code that wants to handle
+     exceptions. Rather, it can be used when code needs to save and
+     restore the exception state temporarily.  Use
+     "PyErr_SetExcInfo()" to restore or clear the exception state.
+
+   Added in version 3.3.
+
+void PyErr_SetExcInfo(PyObject *type, PyObject *value, PyObject *traceback)
+    * Part of the Stable ABI since version 3.7.*
+
+   Set the exception info, as known from "sys.exc_info()".  This
+   refers to an exception that was *already caught*, not to an
+   exception that was freshly raised.  This function steals the
+   references of the arguments. To clear the exception state, pass
+   "NULL" for all three arguments. This function is kept for backwards
+   compatibility. Prefer using "PyErr_SetHandledException()".
+
+   Note:
+
+     This function is not normally used by code that wants to handle
+     exceptions. Rather, it can be used when code needs to save and
+     restore the exception state temporarily.  Use
+     "PyErr_GetExcInfo()" to read the exception state.
+
+   Added in version 3.3.
+
+   Changed in version 3.11: The "type" and "traceback" arguments are
+   no longer used and can be NULL. The interpreter now derives them
+   from the exception instance (the "value" argument). The function
+   still steals references of all three arguments.
+
+
+Signal Handling
+===============
+
+int PyErr_CheckSignals()
+    * Part of the Stable ABI.*
+
+   This function interacts with Python's signal handling.
+
+   If the function is called from the main thread and under the main
+   Python interpreter, it checks whether a signal has been sent to the
+   processes and if so, invokes the corresponding signal handler.  If
+   the "signal" module is supported, this can invoke a signal handler
+   written in Python.
+
+   The function attempts to handle all pending signals, and then
+   returns "0". However, if a Python signal handler raises an
+   exception, the error indicator is set and the function returns "-1"
+   immediately (such that other pending signals may not have been
+   handled yet: they will be on the next "PyErr_CheckSignals()"
+   invocation).
+
+   If the function is called from a non-main thread, or under a non-
+   main Python interpreter, it does nothing and returns "0".
+
+   This function can be called by long-running C code that wants to be
+   interruptible by user requests (such as by pressing Ctrl-C).
+
+   Note:
+
+     The default Python signal handler for "SIGINT" raises the
+     "KeyboardInterrupt" exception.
+
+void PyErr_SetInterrupt()
+    * Part of the Stable ABI.*
+
+   Simulate the effect of a "SIGINT" signal arriving. This is
+   equivalent to "PyErr_SetInterruptEx(SIGINT)".
+
+   Note:
+
+     This function is async-signal-safe.  It can be called without the
+     *GIL* and from a C signal handler.
+
+int PyErr_SetInterruptEx(int signum)
+    * Part of the Stable ABI since version 3.10.*
+
+   Simulate the effect of a signal arriving. The next time
+   "PyErr_CheckSignals()" is called,  the Python signal handler for
+   the given signal number will be called.
+
+   This function can be called by C code that sets up its own signal
+   handling and wants Python signal handlers to be invoked as expected
+   when an interruption is requested (for example when the user
+   presses Ctrl-C to interrupt an operation).
+
+   If the given signal isn't handled by Python (it was set to
+   "signal.SIG_DFL" or "signal.SIG_IGN"), it will be ignored.
+
+   If *signum* is outside of the allowed range of signal numbers, "-1"
+   is returned.  Otherwise, "0" is returned.  The error indicator is
+   never changed by this function.
+
+   Note:
+
+     This function is async-signal-safe.  It can be called without the
+     *GIL* and from a C signal handler.
+
+   Added in version 3.10.
+
+int PySignal_SetWakeupFd(int fd)
+
+   This utility function specifies a file descriptor to which the
+   signal number is written as a single byte whenever a signal is
+   received. *fd* must be non-blocking. It returns the previous such
+   file descriptor.
+
+   The value "-1" disables the feature; this is the initial state.
+   This is equivalent to "signal.set_wakeup_fd()" in Python, but
+   without any error checking.  *fd* should be a valid file
+   descriptor.  The function should only be called from the main
+   thread.
+
+   Changed in version 3.5: On Windows, the function now also supports
+   socket handles.
+
+
+Exception Classes
+=================
+
+PyObject *PyErr_NewException(const char *name, PyObject *base, PyObject *dict)
+    *Return value: New reference.** Part of the Stable ABI.*
+
+   This utility function creates and returns a new exception class.
+   The *name* argument must be the name of the new exception, a C
+   string of the form "module.classname".  The *base* and *dict*
+   arguments are normally "NULL". This creates a class object derived
+   from "Exception" (accessible in C as "PyExc_Exception").
+
+   The "__module__" attribute of the new class is set to the first
+   part (up to the last dot) of the *name* argument, and the class
+   name is set to the last part (after the last dot).  The *base*
+   argument can be used to specify alternate base classes; it can
+   either be only one class or a tuple of classes. The *dict* argument
+   can be used to specify a dictionary of class variables and methods.
+
+PyObject *PyErr_NewExceptionWithDoc(const char *name, const char *doc, PyObject *base, PyObject *dict)
+    *Return value: New reference.** Part of the Stable ABI.*
+
+   Same as "PyErr_NewException()", except that the new exception class
+   can easily be given a docstring: If *doc* is non-"NULL", it will be
+   used as the docstring for the exception class.
+
+   Added in version 3.2.
+
+
+Exception Objects
+=================
+
+PyObject *PyException_GetTraceback(PyObject *ex)
+    *Return value: New reference.** Part of the Stable ABI.*
+
+   Return the traceback associated with the exception as a new
+   reference, as accessible from Python through the "__traceback__"
+   attribute. If there is no traceback associated, this returns
+   "NULL".
+
+int PyException_SetTraceback(PyObject *ex, PyObject *tb)
+    * Part of the Stable ABI.*
+
+   Set the traceback associated with the exception to *tb*.  Use
+   "Py_None" to clear it.
+
+PyObject *PyException_GetContext(PyObject *ex)
+    *Return value: New reference.** Part of the Stable ABI.*
+
+   Return the context (another exception instance during whose
+   handling *ex* was raised) associated with the exception as a new
+   reference, as accessible from Python through the "__context__"
+   attribute. If there is no context associated, this returns "NULL".
+
+void PyException_SetContext(PyObject *ex, PyObject *ctx)
+    * Part of the Stable ABI.*
+
+   Set the context associated with the exception to *ctx*.  Use "NULL"
+   to clear it.  There is no type check to make sure that *ctx* is an
+   exception instance. This steals a reference to *ctx*.
+
+PyObject *PyException_GetCause(PyObject *ex)
+    *Return value: New reference.** Part of the Stable ABI.*
+
+   Return the cause (either an exception instance, or "None", set by
+   "raise ... from ...") associated with the exception as a new
+   reference, as accessible from Python through the "__cause__"
+   attribute.
+
+void PyException_SetCause(PyObject *ex, PyObject *cause)
+    * Part of the Stable ABI.*
+
+   Set the cause associated with the exception to *cause*.  Use "NULL"
+   to clear it.  There is no type check to make sure that *cause* is
+   either an exception instance or "None".  This steals a reference to
+   *cause*.
+
+   The "__suppress_context__" attribute is implicitly set to "True" by
+   this function.
+
+PyObject *PyException_GetArgs(PyObject *ex)
+    *Return value: New reference.** Part of the Stable ABI since
+   version 3.12.*
+
+   Return "args" of exception *ex*.
+
+void PyException_SetArgs(PyObject *ex, PyObject *args)
+    * Part of the Stable ABI since version 3.12.*
+
+   Set "args" of exception *ex* to *args*.
+
+PyObject *PyUnstable_Exc_PrepReraiseStar(PyObject *orig, PyObject *excs)
+
+   *This is Unstable API. It may change without warning in minor
+   releases.*
+
+   Implement part of the interpreter's implementation of "except*".
+   *orig* is the original exception that was caught, and *excs* is the
+   list of the exceptions that need to be raised. This list contains
+   the unhandled part of *orig*, if any, as well as the exceptions
+   that were raised from the "except*" clauses (so they have a
+   different traceback from *orig*) and those that were reraised (and
+   have the same traceback as *orig*). Return the "ExceptionGroup"
+   that needs to be reraised in the end, or "None" if there is nothing
+   to reraise.
+
+   Added in version 3.12.
+
+
+Unicode Exception Objects
+=========================
+
+The following functions are used to create and modify Unicode
+exceptions from C.
+
+PyObject *PyUnicodeDecodeError_Create(const char *encoding, const char *object, Py_ssize_t length, Py_ssize_t start, Py_ssize_t end, const char *reason)
+    *Return value: New reference.** Part of the Stable ABI.*
+
+   Create a "UnicodeDecodeError" object with the attributes
+   *encoding*, *object*, *length*, *start*, *end* and *reason*.
+   *encoding* and *reason* are UTF-8 encoded strings.
+
+PyObject *PyUnicodeDecodeError_GetEncoding(PyObject *exc)
+PyObject *PyUnicodeEncodeError_GetEncoding(PyObject *exc)
+    *Return value: New reference.** Part of the Stable ABI.*
+
+   Return the *encoding* attribute of the given exception object.
+
+PyObject *PyUnicodeDecodeError_GetObject(PyObject *exc)
+PyObject *PyUnicodeEncodeError_GetObject(PyObject *exc)
+PyObject *PyUnicodeTranslateError_GetObject(PyObject *exc)
+    *Return value: New reference.** Part of the Stable ABI.*
+
+   Return the *object* attribute of the given exception object.
+
+int PyUnicodeDecodeError_GetStart(PyObject *exc, Py_ssize_t *start)
+int PyUnicodeEncodeError_GetStart(PyObject *exc, Py_ssize_t *start)
+int PyUnicodeTranslateError_GetStart(PyObject *exc, Py_ssize_t *start)
+    * Part of the Stable ABI.*
+
+   Get the *start* attribute of the given exception object and place
+   it into **start*.  *start* must not be "NULL".  Return "0" on
+   success, "-1" on failure.
+
+int PyUnicodeDecodeError_SetStart(PyObject *exc, Py_ssize_t start)
+int PyUnicodeEncodeError_SetStart(PyObject *exc, Py_ssize_t start)
+int PyUnicodeTranslateError_SetStart(PyObject *exc, Py_ssize_t start)
+    * Part of the Stable ABI.*
+
+   Set the *start* attribute of the given exception object to *start*.
+   Return "0" on success, "-1" on failure.
+
+int PyUnicodeDecodeError_GetEnd(PyObject *exc, Py_ssize_t *end)
+int PyUnicodeEncodeError_GetEnd(PyObject *exc, Py_ssize_t *end)
+int PyUnicodeTranslateError_GetEnd(PyObject *exc, Py_ssize_t *end)
+    * Part of the Stable ABI.*
+
+   Get the *end* attribute of the given exception object and place it
+   into **end*.  *end* must not be "NULL".  Return "0" on success,
+   "-1" on failure.
+
+int PyUnicodeDecodeError_SetEnd(PyObject *exc, Py_ssize_t end)
+int PyUnicodeEncodeError_SetEnd(PyObject *exc, Py_ssize_t end)
+int PyUnicodeTranslateError_SetEnd(PyObject *exc, Py_ssize_t end)
+    * Part of the Stable ABI.*
+
+   Set the *end* attribute of the given exception object to *end*.
+   Return "0" on success, "-1" on failure.
+
+PyObject *PyUnicodeDecodeError_GetReason(PyObject *exc)
+PyObject *PyUnicodeEncodeError_GetReason(PyObject *exc)
+PyObject *PyUnicodeTranslateError_GetReason(PyObject *exc)
+    *Return value: New reference.** Part of the Stable ABI.*
+
+   Return the *reason* attribute of the given exception object.
+
+int PyUnicodeDecodeError_SetReason(PyObject *exc, const char *reason)
+int PyUnicodeEncodeError_SetReason(PyObject *exc, const char *reason)
+int PyUnicodeTranslateError_SetReason(PyObject *exc, const char *reason)
+    * Part of the Stable ABI.*
+
+   Set the *reason* attribute of the given exception object to
+   *reason*.  Return "0" on success, "-1" on failure.
+
+
+Recursion Control
+=================
+
+These two functions provide a way to perform safe recursive calls at
+the C level, both in the core and in extension modules.  They are
+needed if the recursive code does not necessarily invoke Python code
+(which tracks its recursion depth automatically). They are also not
+needed for *tp_call* implementations because the call protocol takes
+care of recursion handling.
+
+int Py_EnterRecursiveCall(const char *where)
+    * Part of the Stable ABI since version 3.9.*
+
+   Marks a point where a recursive C-level call is about to be
+   performed.
+
+   If "USE_STACKCHECK" is defined, this function checks if the OS
+   stack overflowed using "PyOS_CheckStack()".  If this is the case,
+   it sets a "MemoryError" and returns a nonzero value.
+
+   The function then checks if the recursion limit is reached.  If
+   this is the case, a "RecursionError" is set and a nonzero value is
+   returned. Otherwise, zero is returned.
+
+   *where* should be a UTF-8 encoded string such as "" in instance
+   check"" to be concatenated to the "RecursionError" message caused
+   by the recursion depth limit.
+
+   Changed in version 3.9: This function is now also available in the
+   limited API.
+
+void Py_LeaveRecursiveCall(void)
+    * Part of the Stable ABI since version 3.9.*
+
+   Ends a "Py_EnterRecursiveCall()".  Must be called once for each
+   *successful* invocation of "Py_EnterRecursiveCall()".
+
+   Changed in version 3.9: This function is now also available in the
+   limited API.
+
+Properly implementing "tp_repr" for container types requires special
+recursion handling.  In addition to protecting the stack, "tp_repr"
+also needs to track objects to prevent cycles.  The following two
+functions facilitate this functionality.  Effectively, these are the C
+equivalent to "reprlib.recursive_repr()".
+
+int Py_ReprEnter(PyObject *object)
+    * Part of the Stable ABI.*
+
+   Called at the beginning of the "tp_repr" implementation to detect
+   cycles.
+
+   If the object has already been processed, the function returns a
+   positive integer.  In that case the "tp_repr" implementation should
+   return a string object indicating a cycle.  As examples, "dict"
+   objects return "{...}" and "list" objects return "[...]".
+
+   The function will return a negative integer if the recursion limit
+   is reached.  In that case the "tp_repr" implementation should
+   typically return "NULL".
+
+   Otherwise, the function returns zero and the "tp_repr"
+   implementation can continue normally.
+
+void Py_ReprLeave(PyObject *object)
+    * Part of the Stable ABI.*
+
+   Ends a "Py_ReprEnter()".  Must be called once for each invocation
+   of "Py_ReprEnter()" that returns zero.
+
+
+Standard Exceptions
+===================
+
+All standard Python exceptions are available as global variables whose
+names are "PyExc_" followed by the Python exception name.  These have
+the type PyObject*; they are all class objects.  For completeness,
+here are all the variables:
+
++-------------------------------------------+-----------------------------------+------------+
+| C Name                                    | Python Name                       | Notes      |
+|===========================================|===================================|============|
+| "PyExc_BaseException"                     | "BaseException"                   | [1]        |
++-------------------------------------------+-----------------------------------+------------+
+| "PyExc_Exception"                         | "Exception"                       | [1]        |
++-------------------------------------------+-----------------------------------+------------+
+| "PyExc_ArithmeticError"                   | "ArithmeticError"                 | [1]        |
++-------------------------------------------+-----------------------------------+------------+
+| "PyExc_AssertionError"                    | "AssertionError"                  |            |
++-------------------------------------------+-----------------------------------+------------+
+| "PyExc_AttributeError"                    | "AttributeError"                  |            |
++-------------------------------------------+-----------------------------------+------------+
+| "PyExc_BlockingIOError"                   | "BlockingIOError"                 |            |
++-------------------------------------------+-----------------------------------+------------+
+| "PyExc_BrokenPipeError"                   | "BrokenPipeError"                 |            |
++-------------------------------------------+-----------------------------------+------------+
+| "PyExc_BufferError"                       | "BufferError"                     |            |
++-------------------------------------------+-----------------------------------+------------+
+| "PyExc_ChildProcessError"                 | "ChildProcessError"               |            |
++-------------------------------------------+-----------------------------------+------------+
+| "PyExc_ConnectionAbortedError"            | "ConnectionAbortedError"          |            |
++-------------------------------------------+-----------------------------------+------------+
+| "PyExc_ConnectionError"                   | "ConnectionError"                 |            |
++-------------------------------------------+-----------------------------------+------------+
+| "PyExc_ConnectionRefusedError"            | "ConnectionRefusedError"          |            |
++-------------------------------------------+-----------------------------------+------------+
+| "PyExc_ConnectionResetError"              | "ConnectionResetError"            |            |
++-------------------------------------------+-----------------------------------+------------+
+| "PyExc_EOFError"                          | "EOFError"                        |            |
++-------------------------------------------+-----------------------------------+------------+
+| "PyExc_FileExistsError"                   | "FileExistsError"                 |            |
++-------------------------------------------+-----------------------------------+------------+
+| "PyExc_FileNotFoundError"                 | "FileNotFoundError"               |            |
++-------------------------------------------+-----------------------------------+------------+
+| "PyExc_FloatingPointError"                | "FloatingPointError"              |            |
++-------------------------------------------+-----------------------------------+------------+
+| "PyExc_GeneratorExit"                     | "GeneratorExit"                   |            |
++-------------------------------------------+-----------------------------------+------------+
+| "PyExc_ImportError"                       | "ImportError"                     |            |
++-------------------------------------------+-----------------------------------+------------+
+| "PyExc_IndentationError"                  | "IndentationError"                |            |
++-------------------------------------------+-----------------------------------+------------+
+| "PyExc_IndexError"                        | "IndexError"                      |            |
++-------------------------------------------+-----------------------------------+------------+
+| "PyExc_InterruptedError"                  | "InterruptedError"                |            |
++-------------------------------------------+-----------------------------------+------------+
+| "PyExc_IsADirectoryError"                 | "IsADirectoryError"               |            |
++-------------------------------------------+-----------------------------------+------------+
+| "PyExc_KeyError"                          | "KeyError"                        |            |
++-------------------------------------------+-----------------------------------+------------+
+| "PyExc_KeyboardInterrupt"                 | "KeyboardInterrupt"               |            |
++-------------------------------------------+-----------------------------------+------------+
+| "PyExc_LookupError"                       | "LookupError"                     | [1]        |
++-------------------------------------------+-----------------------------------+------------+
+| "PyExc_MemoryError"                       | "MemoryError"                     |            |
++-------------------------------------------+-----------------------------------+------------+
+| "PyExc_ModuleNotFoundError"               | "ModuleNotFoundError"             |            |
++-------------------------------------------+-----------------------------------+------------+
+| "PyExc_NameError"                         | "NameError"                       |            |
++-------------------------------------------+-----------------------------------+------------+
+| "PyExc_NotADirectoryError"                | "NotADirectoryError"              |            |
++-------------------------------------------+-----------------------------------+------------+
+| "PyExc_NotImplementedError"               | "NotImplementedError"             |            |
++-------------------------------------------+-----------------------------------+------------+
+| "PyExc_OSError"                           | "OSError"                         | [1]        |
++-------------------------------------------+-----------------------------------+------------+
+| "PyExc_OverflowError"                     | "OverflowError"                   |            |
++-------------------------------------------+-----------------------------------+------------+
+| "PyExc_PermissionError"                   | "PermissionError"                 |            |
++-------------------------------------------+-----------------------------------+------------+
+| "PyExc_ProcessLookupError"                | "ProcessLookupError"              |            |
++-------------------------------------------+-----------------------------------+------------+
+| "PyExc_RecursionError"                    | "RecursionError"                  |            |
++-------------------------------------------+-----------------------------------+------------+
+| "PyExc_ReferenceError"                    | "ReferenceError"                  |            |
++-------------------------------------------+-----------------------------------+------------+
+| "PyExc_RuntimeError"                      | "RuntimeError"                    |            |
++-------------------------------------------+-----------------------------------+------------+
+| "PyExc_StopAsyncIteration"                | "StopAsyncIteration"              |            |
++-------------------------------------------+-----------------------------------+------------+
+| "PyExc_StopIteration"                     | "StopIteration"                   |            |
++-------------------------------------------+-----------------------------------+------------+
+| "PyExc_SyntaxError"                       | "SyntaxError"                     |            |
++-------------------------------------------+-----------------------------------+------------+
+| "PyExc_SystemError"                       | "SystemError"                     |            |
++-------------------------------------------+-----------------------------------+------------+
+| "PyExc_SystemExit"                        | "SystemExit"                      |            |
++-------------------------------------------+-----------------------------------+------------+
+| "PyExc_TabError"                          | "TabError"                        |            |
++-------------------------------------------+-----------------------------------+------------+
+| "PyExc_TimeoutError"                      | "TimeoutError"                    |            |
++-------------------------------------------+-----------------------------------+------------+
+| "PyExc_TypeError"                         | "TypeError"                       |            |
++-------------------------------------------+-----------------------------------+------------+
+| "PyExc_UnboundLocalError"                 | "UnboundLocalError"               |            |
++-------------------------------------------+-----------------------------------+------------+
+| "PyExc_UnicodeDecodeError"                | "UnicodeDecodeError"              |            |
++-------------------------------------------+-----------------------------------+------------+
+| "PyExc_UnicodeEncodeError"                | "UnicodeEncodeError"              |            |
++-------------------------------------------+-----------------------------------+------------+
+| "PyExc_UnicodeError"                      | "UnicodeError"                    |            |
++-------------------------------------------+-----------------------------------+------------+
+| "PyExc_UnicodeTranslateError"             | "UnicodeTranslateError"           |            |
++-------------------------------------------+-----------------------------------+------------+
+| "PyExc_ValueError"                        | "ValueError"                      |            |
++-------------------------------------------+-----------------------------------+------------+
+| "PyExc_ZeroDivisionError"                 | "ZeroDivisionError"               |            |
++-------------------------------------------+-----------------------------------+------------+
+
+Added in version 3.3: "PyExc_BlockingIOError",
+"PyExc_BrokenPipeError", "PyExc_ChildProcessError",
+"PyExc_ConnectionError", "PyExc_ConnectionAbortedError",
+"PyExc_ConnectionRefusedError", "PyExc_ConnectionResetError",
+"PyExc_FileExistsError", "PyExc_FileNotFoundError",
+"PyExc_InterruptedError", "PyExc_IsADirectoryError",
+"PyExc_NotADirectoryError", "PyExc_PermissionError",
+"PyExc_ProcessLookupError" and "PyExc_TimeoutError" were introduced
+following **PEP 3151**.
+
+Added in version 3.5: "PyExc_StopAsyncIteration" and
+"PyExc_RecursionError".
+
+Added in version 3.6: "PyExc_ModuleNotFoundError".
+
+These are compatibility aliases to "PyExc_OSError":
+
++---------------------------------------+------------+
+| C Name                                | Notes      |
+|=======================================|============|
+| "PyExc_EnvironmentError"              |            |
++---------------------------------------+------------+
+| "PyExc_IOError"                       |            |
++---------------------------------------+------------+
+| "PyExc_WindowsError"                  | [2]        |
++---------------------------------------+------------+
+
+Changed in version 3.3: These aliases used to be separate exception
+types.
+
+Notes:
+
+[1] This is a base class for other standard exceptions.
+
+[2] Only defined on Windows; protect code that uses this by testing
+    that the preprocessor macro "MS_WINDOWS" is defined.
+
+
+Standard Warning Categories
+===========================
+
+All standard Python warning categories are available as global
+variables whose names are "PyExc_" followed by the Python exception
+name. These have the type PyObject*; they are all class objects. For
+completeness, here are all the variables:
+
++--------------------------------------------+-----------------------------------+------------+
+| C Name                                     | Python Name                       | Notes      |
+|============================================|===================================|============|
+| "PyExc_Warning"                            | "Warning"                         | [3]        |
++--------------------------------------------+-----------------------------------+------------+
+| "PyExc_BytesWarning"                       | "BytesWarning"                    |            |
++--------------------------------------------+-----------------------------------+------------+
+| "PyExc_DeprecationWarning"                 | "DeprecationWarning"              |            |
++--------------------------------------------+-----------------------------------+------------+
+| "PyExc_FutureWarning"                      | "FutureWarning"                   |            |
++--------------------------------------------+-----------------------------------+------------+
+| "PyExc_ImportWarning"                      | "ImportWarning"                   |            |
++--------------------------------------------+-----------------------------------+------------+
+| "PyExc_PendingDeprecationWarning"          | "PendingDeprecationWarning"       |            |
++--------------------------------------------+-----------------------------------+------------+
+| "PyExc_ResourceWarning"                    | "ResourceWarning"                 |            |
++--------------------------------------------+-----------------------------------+------------+
+| "PyExc_RuntimeWarning"                     | "RuntimeWarning"                  |            |
++--------------------------------------------+-----------------------------------+------------+
+| "PyExc_SyntaxWarning"                      | "SyntaxWarning"                   |            |
++--------------------------------------------+-----------------------------------+------------+
+| "PyExc_UnicodeWarning"                     | "UnicodeWarning"                  |            |
++--------------------------------------------+-----------------------------------+------------+
+| "PyExc_UserWarning"                        | "UserWarning"                     |            |
++--------------------------------------------+-----------------------------------+------------+
+
+Added in version 3.2: "PyExc_ResourceWarning".
+
+Notes:
+
+[3] This is a base class for other standard warning categories.

python-3.12.6-docs-text/python-3.12.6-docs-text/c-api/file.txt

@@ -0,0 +1,97 @@
+File Objects
+************
+
+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 (FILE*) support
+from the C standard library.  In Python 3, files and streams use the
+new "io" module, which defines several layers over the low-level
+unbuffered I/O of the operating system.  The functions described below
+are convenience C wrappers over these new APIs, and meant mostly for
+internal error reporting in the interpreter; third-party code is
+advised to access the "io" APIs instead.
+
+PyObject *PyFile_FromFd(int fd, const char *name, const char *mode, int buffering, const char *encoding, const char *errors, const char *newline, int closefd)
+    *Return value: New reference.** Part of the Stable ABI.*
+
+   Create a Python file object from the file descriptor of an already
+   opened file *fd*.  The arguments *name*, *encoding*, *errors* and
+   *newline* can be "NULL" to use the defaults; *buffering* can be
+   *-1* to use the default. *name* is ignored and kept for backward
+   compatibility. Return "NULL" on failure. For a more comprehensive
+   description of the arguments, please refer to the "io.open()"
+   function documentation.
+
+   Warning:
+
+     Since Python streams have their own buffering layer, mixing them
+     with OS-level file descriptors can produce various issues (such
+     as unexpected ordering of data).
+
+   Changed in version 3.2: Ignore *name* attribute.
+
+int PyObject_AsFileDescriptor(PyObject *p)
+    * Part of the Stable ABI.*
+
+   Return the file descriptor associated with *p* as an int.  If the
+   object is an integer, its value is returned.  If not, the object's
+   "fileno()" method is called if it exists; the method must return an
+   integer, which is returned as the file descriptor value.  Sets an
+   exception and returns "-1" on failure.
+
+PyObject *PyFile_GetLine(PyObject *p, int n)
+    *Return value: New reference.** Part of the Stable ABI.*
+
+   Equivalent to "p.readline([n])", this function reads one line from
+   the object *p*.  *p* may be a file object or any object with a
+   "readline()" method.  If *n* is "0", exactly one line is read,
+   regardless of the length of the line.  If *n* is greater than "0",
+   no more than *n* bytes will be read from the file; a partial line
+   can be returned.  In both cases, an empty string is returned if the
+   end of the file is reached immediately.  If *n* is less than "0",
+   however, one line is read regardless of length, but "EOFError" is
+   raised if the end of the file is reached immediately.
+
+int PyFile_SetOpenCodeHook(Py_OpenCodeHookFunction handler)
+
+   Overrides the normal behavior of "io.open_code()" to pass its
+   parameter through the provided handler.
+
+   The handler is a function of type:
+
+   type Py_OpenCodeHookFunction
+
+      Equivalent of PyObject *(*)(PyObject *path, void *userData),
+      where *path* is guaranteed to be "PyUnicodeObject".
+
+   The *userData* pointer is passed into the hook function. Since hook
+   functions may be called from different runtimes, this pointer
+   should not refer directly to Python state.
+
+   As this hook is intentionally used during import, avoid importing
+   new modules during its execution unless they are known to be frozen
+   or available in "sys.modules".
+
+   Once a hook has been set, it cannot be removed or replaced, and
+   later calls to "PyFile_SetOpenCodeHook()" will fail. On failure,
+   the function returns -1 and sets an exception if the interpreter
+   has been initialized.
+
+   This function is safe to call before "Py_Initialize()".
+
+   Raises an auditing event "setopencodehook" with no arguments.
+
+   Added in version 3.8.
+
+int PyFile_WriteObject(PyObject *obj, PyObject *p, int flags)
+    * Part of the Stable ABI.*
+
+   Write object *obj* to file object *p*.  The only supported flag for
+   *flags* is "Py_PRINT_RAW"; if given, the "str()" of the object is
+   written instead of the "repr()".  Return "0" on success or "-1" on
+   failure; the appropriate exception will be set.
+
+int PyFile_WriteString(const char *s, PyObject *p)
+    * Part of the Stable ABI.*
+
+   Write string *s* to file object *p*.  Return "0" on success or "-1"
+   on failure; the appropriate exception will be set.

python-3.12.6-docs-text/python-3.12.6-docs-text/c-api/float.txt

@@ -0,0 +1,160 @@
+Floating-Point Objects
+**********************
+
+type PyFloatObject
+
+   This subtype of "PyObject" represents a Python floating-point
+   object.
+
+PyTypeObject PyFloat_Type
+    * Part of the Stable ABI.*
+
+   This instance of "PyTypeObject" represents the Python floating-
+   point type.  This is the same object as "float" in the Python
+   layer.
+
+int PyFloat_Check(PyObject *p)
+
+   Return true if its argument is a "PyFloatObject" or a subtype of
+   "PyFloatObject".  This function always succeeds.
+
+int PyFloat_CheckExact(PyObject *p)
+
+   Return true if its argument is a "PyFloatObject", but not a subtype
+   of "PyFloatObject".  This function always succeeds.
+
+PyObject *PyFloat_FromString(PyObject *str)
+    *Return value: New reference.** Part of the Stable ABI.*
+
+   Create a "PyFloatObject" object based on the string value in *str*,
+   or "NULL" on failure.
+
+PyObject *PyFloat_FromDouble(double v)
+    *Return value: New reference.** Part of the Stable ABI.*
+
+   Create a "PyFloatObject" object from *v*, or "NULL" on failure.
+
+double PyFloat_AsDouble(PyObject *pyfloat)
+    * Part of the Stable ABI.*
+
+   Return a C double representation of the contents of *pyfloat*.  If
+   *pyfloat* is not a Python floating-point object but has a
+   "__float__()" method, this method will first be called to convert
+   *pyfloat* into a float. If "__float__()" is not defined then it
+   falls back to "__index__()". This method returns "-1.0" upon
+   failure, so one should call "PyErr_Occurred()" to check for errors.
+
+   Changed in version 3.8: Use "__index__()" if available.
+
+double PyFloat_AS_DOUBLE(PyObject *pyfloat)
+
+   Return a C double representation of the contents of *pyfloat*, but
+   without error checking.
+
+PyObject *PyFloat_GetInfo(void)
+    *Return value: New reference.** Part of the Stable ABI.*
+
+   Return a structseq instance which contains information about the
+   precision, minimum and maximum values of a float. It's a thin
+   wrapper around the header file "float.h".
+
+double PyFloat_GetMax()
+    * Part of the Stable ABI.*
+
+   Return the maximum representable finite float *DBL_MAX* as C
+   double.
+
+double PyFloat_GetMin()
+    * Part of the Stable ABI.*
+
+   Return the minimum normalized positive float *DBL_MIN* as C double.
+
+
+Pack and Unpack functions
+=========================
+
+The pack and unpack functions provide an efficient platform-
+independent way to store floating-point values as byte strings. The
+Pack routines produce a bytes string from a C double, and the Unpack
+routines produce a C double from such a bytes string. The suffix (2, 4
+or 8) specifies the number of bytes in the bytes string.
+
+On platforms that appear to use IEEE 754 formats these functions work
+by copying bits. On other platforms, the 2-byte format is identical to
+the IEEE 754 binary16 half-precision format, the 4-byte format
+(32-bit) is identical to the IEEE 754 binary32 single precision
+format, and the 8-byte format to the IEEE 754 binary64 double
+precision format, although the packing of INFs and NaNs (if such
+things exist on the platform) isn't handled correctly, and attempting
+to unpack a bytes string containing an IEEE INF or NaN will raise an
+exception.
+
+On non-IEEE platforms with more precision, or larger dynamic range,
+than IEEE 754 supports, not all values can be packed; on non-IEEE
+platforms with less precision, or smaller dynamic range, not all
+values can be unpacked. What happens in such cases is partly
+accidental (alas).
+
+Added in version 3.11.
+
+
+Pack functions
+--------------
+
+The pack routines write 2, 4 or 8 bytes, starting at *p*. *le* is an
+int argument, non-zero if you want the bytes string in little-endian
+format (exponent last, at "p+1", "p+3", or "p+6" "p+7"), zero if you
+want big-endian format (exponent first, at *p*). The "PY_BIG_ENDIAN"
+constant can be used to use the native endian: it is equal to "1" on
+big endian processor, or "0" on little endian processor.
+
+Return value: "0" if all is OK, "-1" if error (and an exception is
+set, most likely "OverflowError").
+
+There are two problems on non-IEEE platforms:
+
+* What this does is undefined if *x* is a NaN or infinity.
+
+* "-0.0" and "+0.0" produce the same bytes string.
+
+int PyFloat_Pack2(double x, unsigned char *p, int le)
+
+   Pack a C double as the IEEE 754 binary16 half-precision format.
+
+int PyFloat_Pack4(double x, unsigned char *p, int le)
+
+   Pack a C double as the IEEE 754 binary32 single precision format.
+
+int PyFloat_Pack8(double x, unsigned char *p, int le)
+
+   Pack a C double as the IEEE 754 binary64 double precision format.
+
+
+Unpack functions
+----------------
+
+The unpack routines read 2, 4 or 8 bytes, starting at *p*.  *le* is an
+int argument, non-zero if the bytes string is in little-endian format
+(exponent last, at "p+1", "p+3" or "p+6" and "p+7"), zero if big-
+endian (exponent first, at *p*). The "PY_BIG_ENDIAN" constant can be
+used to use the native endian: it is equal to "1" on big endian
+processor, or "0" on little endian processor.
+
+Return value: The unpacked double.  On error, this is "-1.0" and
+"PyErr_Occurred()" is true (and an exception is set, most likely
+"OverflowError").
+
+Note that on a non-IEEE platform this will refuse to unpack a bytes
+string that represents a NaN or infinity.
+
+double PyFloat_Unpack2(const unsigned char *p, int le)
+
+   Unpack the IEEE 754 binary16 half-precision format as a C double.
+
+double PyFloat_Unpack4(const unsigned char *p, int le)
+
+   Unpack the IEEE 754 binary32 single precision format as a C double.
+
+double PyFloat_Unpack8(const unsigned char *p, int le)
+
+   Unpack the IEEE 754 binary64 double precision format as a C double.

python-3.12.6-docs-text/python-3.12.6-docs-text/c-api/frame.txt

@@ -0,0 +1,161 @@
+Frame Objects
+*************
+
+type PyFrameObject
+    * Part of the Limited API (as an opaque struct).*
+
+   The C structure of the objects used to describe frame objects.
+
+   There are no public members in this structure.
+
+   Changed in version 3.11: The members of this structure were removed
+   from the public C API. Refer to the What's New entry for details.
+
+The "PyEval_GetFrame()" and "PyThreadState_GetFrame()" functions can
+be used to get a frame object.
+
+See also Reflection.
+
+PyTypeObject PyFrame_Type
+
+   The type of frame objects. It is the same object as
+   "types.FrameType" in the Python layer.
+
+   Changed in version 3.11: Previously, this type was only available
+   after including "<frameobject.h>".
+
+int PyFrame_Check(PyObject *obj)
+
+   Return non-zero if *obj* is a frame object.
+
+   Changed in version 3.11: Previously, this function was only
+   available after including "<frameobject.h>".
+
+PyFrameObject *PyFrame_GetBack(PyFrameObject *frame)
+
+   Get the *frame* next outer frame.
+
+   Return a *strong reference*, or "NULL" if *frame* has no outer
+   frame.
+
+   Added in version 3.9.
+
+PyObject *PyFrame_GetBuiltins(PyFrameObject *frame)
+
+   Get the *frame*'s "f_builtins" attribute.
+
+   Return a *strong reference*. The result cannot be "NULL".
+
+   Added in version 3.11.
+
+PyCodeObject *PyFrame_GetCode(PyFrameObject *frame)
+    * Part of the Stable ABI since version 3.10.*
+
+   Get the *frame* code.
+
+   Return a *strong reference*.
+
+   The result (frame code) cannot be "NULL".
+
+   Added in version 3.9.
+
+PyObject *PyFrame_GetGenerator(PyFrameObject *frame)
+
+   Get the generator, coroutine, or async generator that owns this
+   frame, or "NULL" if this frame is not owned by a generator. Does
+   not raise an exception, even if the return value is "NULL".
+
+   Return a *strong reference*, or "NULL".
+
+   Added in version 3.11.
+
+PyObject *PyFrame_GetGlobals(PyFrameObject *frame)
+
+   Get the *frame*'s "f_globals" attribute.
+
+   Return a *strong reference*. The result cannot be "NULL".
+
+   Added in version 3.11.
+
+int PyFrame_GetLasti(PyFrameObject *frame)
+
+   Get the *frame*'s "f_lasti" attribute.
+
+   Returns -1 if "frame.f_lasti" is "None".
+
+   Added in version 3.11.
+
+PyObject *PyFrame_GetVar(PyFrameObject *frame, PyObject *name)
+
+   Get the variable *name* of *frame*.
+
+   * Return a *strong reference* to the variable value on success.
+
+   * Raise "NameError" and return "NULL" if the variable does not
+     exist.
+
+   * Raise an exception and return "NULL" on error.
+
+   *name* type must be a "str".
+
+   Added in version 3.12.
+
+PyObject *PyFrame_GetVarString(PyFrameObject *frame, const char *name)
+
+   Similar to "PyFrame_GetVar()", but the variable name is a C string
+   encoded in UTF-8.
+
+   Added in version 3.12.
+
+PyObject *PyFrame_GetLocals(PyFrameObject *frame)
+
+   Get the *frame*'s "f_locals" attribute ("dict").
+
+   Return a *strong reference*.
+
+   Added in version 3.11.
+
+int PyFrame_GetLineNumber(PyFrameObject *frame)
+    * Part of the Stable ABI since version 3.10.*
+
+   Return the line number that *frame* is currently executing.
+
+
+Internal Frames
+===============
+
+Unless using **PEP 523**, you will not need this.
+
+struct _PyInterpreterFrame
+
+   The interpreter's internal frame representation.
+
+   Added in version 3.11.
+
+PyObject *PyUnstable_InterpreterFrame_GetCode(struct _PyInterpreterFrame *frame);
+
+   *This is Unstable API. It may change without warning in minor
+   releases.*
+
+      Return a *strong reference* to the code object for the frame.
+
+   Added in version 3.12.
+
+int PyUnstable_InterpreterFrame_GetLasti(struct _PyInterpreterFrame *frame);
+
+   *This is Unstable API. It may change without warning in minor
+   releases.*
+
+   Return the byte offset into the last executed instruction.
+
+   Added in version 3.12.
+
+int PyUnstable_InterpreterFrame_GetLine(struct _PyInterpreterFrame *frame);
+
+   *This is Unstable API. It may change without warning in minor
+   releases.*
+
+   Return the currently executing line number, or -1 if there is no
+   line number.
+
+   Added in version 3.12.

python-3.12.6-docs-text/python-3.12.6-docs-text/c-api/function.txt

@@ -0,0 +1,178 @@
+Function Objects
+****************
+
+There are a few functions specific to Python functions.
+
+type PyFunctionObject
+
+   The C structure used for functions.
+
+PyTypeObject PyFunction_Type
+
+   This is an instance of "PyTypeObject" and represents the Python
+   function type.  It is exposed to Python programmers as
+   "types.FunctionType".
+
+int PyFunction_Check(PyObject *o)
+
+   Return true if *o* is a function object (has type
+   "PyFunction_Type"). The parameter must not be "NULL".  This
+   function always succeeds.
+
+PyObject *PyFunction_New(PyObject *code, PyObject *globals)
+    *Return value: New reference.*
+
+   Return a new function object associated with the code object
+   *code*. *globals* must be a dictionary with the global variables
+   accessible to the function.
+
+   The function's docstring and name are retrieved from the code
+   object. "__module__" is retrieved from *globals*. The argument
+   defaults, annotations and closure are set to "NULL". "__qualname__"
+   is set to the same value as the code object's "co_qualname" field.
+
+PyObject *PyFunction_NewWithQualName(PyObject *code, PyObject *globals, PyObject *qualname)
+    *Return value: New reference.*
+
+   As "PyFunction_New()", but also allows setting the function
+   object's "__qualname__" attribute. *qualname* should be a unicode
+   object or "NULL"; if "NULL", the "__qualname__" attribute is set to
+   the same value as the code object's "co_qualname" field.
+
+   Added in version 3.3.
+
+PyObject *PyFunction_GetCode(PyObject *op)
+    *Return value: Borrowed reference.*
+
+   Return the code object associated with the function object *op*.
+
+PyObject *PyFunction_GetGlobals(PyObject *op)
+    *Return value: Borrowed reference.*
+
+   Return the globals dictionary associated with the function object
+   *op*.
+
+PyObject *PyFunction_GetModule(PyObject *op)
+    *Return value: Borrowed reference.*
+
+   Return a *borrowed reference* to the "__module__" attribute of the
+   function object *op*. It can be *NULL*.
+
+   This is normally a "string" containing the module name, but can be
+   set to any other object by Python code.
+
+PyObject *PyFunction_GetDefaults(PyObject *op)
+    *Return value: Borrowed reference.*
+
+   Return the argument default values of the function object *op*.
+   This can be a tuple of arguments or "NULL".
+
+int PyFunction_SetDefaults(PyObject *op, PyObject *defaults)
+
+   Set the argument default values for the function object *op*.
+   *defaults* must be "Py_None" or a tuple.
+
+   Raises "SystemError" and returns "-1" on failure.
+
+void PyFunction_SetVectorcall(PyFunctionObject *func, vectorcallfunc vectorcall)
+
+   Set the vectorcall field of a given function object *func*.
+
+   Warning: extensions using this API must preserve the behavior of
+   the unaltered (default) vectorcall function!
+
+   Added in version 3.12.
+
+PyObject *PyFunction_GetClosure(PyObject *op)
+    *Return value: Borrowed reference.*
+
+   Return the closure associated with the function object *op*. This
+   can be "NULL" or a tuple of cell objects.
+
+int PyFunction_SetClosure(PyObject *op, PyObject *closure)
+
+   Set the closure associated with the function object *op*. *closure*
+   must be "Py_None" or a tuple of cell objects.
+
+   Raises "SystemError" and returns "-1" on failure.
+
+PyObject *PyFunction_GetAnnotations(PyObject *op)
+    *Return value: Borrowed reference.*
+
+   Return the annotations of the function object *op*. This can be a
+   mutable dictionary or "NULL".
+
+int PyFunction_SetAnnotations(PyObject *op, PyObject *annotations)
+
+   Set the annotations for the function object *op*. *annotations*
+   must be a dictionary or "Py_None".
+
+   Raises "SystemError" and returns "-1" on failure.
+
+int PyFunction_AddWatcher(PyFunction_WatchCallback callback)
+
+   Register *callback* as a function watcher for the current
+   interpreter. Return an ID which may be passed to
+   "PyFunction_ClearWatcher()". In case of error (e.g. no more watcher
+   IDs available), return "-1" and set an exception.
+
+   Added in version 3.12.
+
+int PyFunction_ClearWatcher(int watcher_id)
+
+   Clear watcher identified by *watcher_id* previously returned from
+   "PyFunction_AddWatcher()" for the current interpreter. Return "0"
+   on success, or "-1" and set an exception on error (e.g.  if the
+   given *watcher_id* was never registered.)
+
+   Added in version 3.12.
+
+type PyFunction_WatchEvent
+
+   Enumeration of possible function watcher events: -
+   "PyFunction_EVENT_CREATE" - "PyFunction_EVENT_DESTROY" -
+   "PyFunction_EVENT_MODIFY_CODE" - "PyFunction_EVENT_MODIFY_DEFAULTS"
+   - "PyFunction_EVENT_MODIFY_KWDEFAULTS"
+
+   Added in version 3.12.
+
+typedef int (*PyFunction_WatchCallback)(PyFunction_WatchEvent event, PyFunctionObject *func, PyObject *new_value)
+
+   Type of a function watcher callback function.
+
+   If *event* is "PyFunction_EVENT_CREATE" or
+   "PyFunction_EVENT_DESTROY" then *new_value* will be "NULL".
+   Otherwise, *new_value* will hold a *borrowed reference* to the new
+   value that is about to be stored in *func* for the attribute that
+   is being modified.
+
+   The callback may inspect but must not modify *func*; doing so could
+   have unpredictable effects, including infinite recursion.
+
+   If *event* is "PyFunction_EVENT_CREATE", then the callback is
+   invoked after *func* has been fully initialized. Otherwise, the
+   callback is invoked before the modification to *func* takes place,
+   so the prior state of *func* can be inspected. The runtime is
+   permitted to optimize away the creation of function objects when
+   possible. In such cases no event will be emitted. Although this
+   creates the possibility of an observable difference of runtime
+   behavior depending on optimization decisions, it does not change
+   the semantics of the Python code being executed.
+
+   If *event* is "PyFunction_EVENT_DESTROY",  Taking a reference in
+   the callback to the about-to-be-destroyed function will resurrect
+   it, preventing it from being freed at this time. When the
+   resurrected object is destroyed later, any watcher callbacks active
+   at that time will be called again.
+
+   If the callback sets an exception, it must return "-1"; this
+   exception will be printed as an unraisable exception using
+   "PyErr_WriteUnraisable()". Otherwise it should return "0".
+
+   There may already be a pending exception set on entry to the
+   callback. In this case, the callback should return "0" with the
+   same exception still set. This means the callback may not call any
+   other API that can set an exception unless it saves and clears the
+   exception state first, and restores it before returning.
+
+   Added in version 3.12.

python-3.12.6-docs-text/python-3.12.6-docs-text/c-api/gcsupport.txt

@@ -0,0 +1,282 @@
+Supporting Cyclic Garbage Collection
+************************************
+
+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 other objects, or which only store
+references to atomic types (such as numbers or strings), do not need
+to provide any explicit support for garbage collection.
+
+To create a container type, the "tp_flags" field of the type object
+must include the "Py_TPFLAGS_HAVE_GC" and provide an implementation of
+the "tp_traverse" handler.  If instances of the type are mutable, a
+"tp_clear" implementation must also be provided.
+
+"Py_TPFLAGS_HAVE_GC"
+   Objects with a type with this flag set must conform with the rules
+   documented here.  For convenience these objects will be referred to
+   as container objects.
+
+Constructors for container types must conform to two rules:
+
+1. The memory for the object must be allocated using "PyObject_GC_New"
+   or "PyObject_GC_NewVar".
+
+2. Once all the fields which may contain references to other
+   containers are initialized, it must call "PyObject_GC_Track()".
+
+Similarly, the deallocator for the object must conform to a similar
+pair of rules:
+
+1. Before fields which refer to other containers are invalidated,
+   "PyObject_GC_UnTrack()" must be called.
+
+2. The object's memory must be deallocated using "PyObject_GC_Del()".
+
+   Warning:
+
+     If a type adds the Py_TPFLAGS_HAVE_GC, then it *must* implement
+     at least a "tp_traverse" handler or explicitly use one from its
+     subclass or subclasses.When calling "PyType_Ready()" or some of
+     the APIs that indirectly call it like
+     "PyType_FromSpecWithBases()" or "PyType_FromSpec()" the
+     interpreter will automatically populate the "tp_flags",
+     "tp_traverse" and "tp_clear" fields if the type inherits from a
+     class that implements the garbage collector protocol and the
+     child class does *not* include the "Py_TPFLAGS_HAVE_GC" flag.
+
+PyObject_GC_New(TYPE, typeobj)
+
+   Analogous to "PyObject_New" but for container objects with the
+   "Py_TPFLAGS_HAVE_GC" flag set.
+
+PyObject_GC_NewVar(TYPE, typeobj, size)
+
+   Analogous to "PyObject_NewVar" but for container objects with the
+   "Py_TPFLAGS_HAVE_GC" flag set.
+
+PyObject *PyUnstable_Object_GC_NewWithExtraData(PyTypeObject *type, size_t extra_size)
+
+   *This is Unstable API. It may change without warning in minor
+   releases.*
+
+   Analogous to "PyObject_GC_New" but allocates *extra_size* bytes at
+   the end of the object (at offset "tp_basicsize"). The allocated
+   memory is initialized to zeros, except for the "Python object
+   header".
+
+   The extra data will be deallocated with the object, but otherwise
+   it is not managed by Python.
+
+   Warning:
+
+     The function is marked as unstable because the final mechanism
+     for reserving extra data after an instance is not yet decided.
+     For allocating a variable number of fields, prefer using
+     "PyVarObject" and "tp_itemsize" instead.
+
+   Added in version 3.12.
+
+PyObject_GC_Resize(TYPE, op, newsize)
+
+   Resize an object allocated by "PyObject_NewVar". Returns the
+   resized object of type "TYPE*" (refers to any C type) or "NULL" on
+   failure.
+
+   *op* must be of type PyVarObject* and must not be tracked by the
+   collector yet. *newsize* must be of type "Py_ssize_t".
+
+void PyObject_GC_Track(PyObject *op)
+    * Part of the Stable ABI.*
+
+   Adds the object *op* to the set of container objects tracked by the
+   collector.  The collector can run at unexpected times so objects
+   must be valid while being tracked.  This should be called once all
+   the fields followed by the "tp_traverse" handler become valid,
+   usually near the end of the constructor.
+
+int PyObject_IS_GC(PyObject *obj)
+
+   Returns non-zero if the object implements the garbage collector
+   protocol, otherwise returns 0.
+
+   The object cannot be tracked by the garbage collector if this
+   function returns 0.
+
+int PyObject_GC_IsTracked(PyObject *op)
+    * Part of the Stable ABI since version 3.9.*
+
+   Returns 1 if the object type of *op* implements the GC protocol and
+   *op* is being currently tracked by the garbage collector and 0
+   otherwise.
+
+   This is analogous to the Python function "gc.is_tracked()".
+
+   Added in version 3.9.
+
+int PyObject_GC_IsFinalized(PyObject *op)
+    * Part of the Stable ABI since version 3.9.*
+
+   Returns 1 if the object type of *op* implements the GC protocol and
+   *op* has been already finalized by the garbage collector and 0
+   otherwise.
+
+   This is analogous to the Python function "gc.is_finalized()".
+
+   Added in version 3.9.
+
+void PyObject_GC_Del(void *op)
+    * Part of the Stable ABI.*
+
+   Releases memory allocated to an object using "PyObject_GC_New" or
+   "PyObject_GC_NewVar".
+
+void PyObject_GC_UnTrack(void *op)
+    * Part of the Stable ABI.*
+
+   Remove the object *op* from the set of container objects tracked by
+   the collector.  Note that "PyObject_GC_Track()" can be called again
+   on this object to add it back to the set of tracked objects.  The
+   deallocator ("tp_dealloc" handler) should call this for the object
+   before any of the fields used by the "tp_traverse" handler become
+   invalid.
+
+Changed in version 3.8: The "_PyObject_GC_TRACK()" and
+"_PyObject_GC_UNTRACK()" macros have been removed from the public C
+API.
+
+The "tp_traverse" handler accepts a function parameter of this type:
+
+typedef int (*visitproc)(PyObject *object, void *arg)
+    * Part of the Stable ABI.*
+
+   Type of the visitor function passed to the "tp_traverse" handler.
+   The function should be called with an object to traverse as
+   *object* and the third parameter to the "tp_traverse" handler as
+   *arg*.  The Python core uses several visitor functions to implement
+   cyclic garbage detection; it's not expected that users will need to
+   write their own visitor functions.
+
+The "tp_traverse" handler must have the following type:
+
+typedef int (*traverseproc)(PyObject *self, visitproc visit, void *arg)
+    * Part of the Stable ABI.*
+
+   Traversal function for a container object.  Implementations must
+   call the *visit* function for each object directly contained by
+   *self*, with the parameters to *visit* being the contained object
+   and the *arg* value passed to the handler.  The *visit* function
+   must not be called with a "NULL" object argument.  If *visit*
+   returns a non-zero value that value should be returned immediately.
+
+To simplify writing "tp_traverse" handlers, a "Py_VISIT()" macro is
+provided.  In order to use this macro, the "tp_traverse"
+implementation must name its arguments exactly *visit* and *arg*:
+
+void Py_VISIT(PyObject *o)
+
+   If *o* is not "NULL", call the *visit* callback, with arguments *o*
+   and *arg*.  If *visit* returns a non-zero value, then return it.
+   Using this macro, "tp_traverse" handlers look like:
+
+      static int
+      my_traverse(Noddy *self, visitproc visit, void *arg)
+      {
+          Py_VISIT(self->foo);
+          Py_VISIT(self->bar);
+          return 0;
+      }
+
+The "tp_clear" handler must be of the "inquiry" type, or "NULL" if the
+object is immutable.
+
+typedef int (*inquiry)(PyObject *self)
+    * Part of the Stable ABI.*
+
+   Drop references that may have created reference cycles.  Immutable
+   objects do not have to define this method since they can never
+   directly create reference cycles.  Note that the object must still
+   be valid after calling this method (don't just call "Py_DECREF()"
+   on a reference).  The collector will call this method if it detects
+   that this object is involved in a reference cycle.
+
+
+Controlling the Garbage Collector State
+=======================================
+
+The C-API provides the following functions for controlling garbage
+collection runs.
+
+Py_ssize_t PyGC_Collect(void)
+    * Part of the Stable ABI.*
+
+   Perform a full garbage collection, if the garbage collector is
+   enabled. (Note that "gc.collect()" runs it unconditionally.)
+
+   Returns the number of collected + unreachable objects which cannot
+   be collected. If the garbage collector is disabled or already
+   collecting, returns "0" immediately. Errors during garbage
+   collection are passed to "sys.unraisablehook". This function does
+   not raise exceptions.
+
+int PyGC_Enable(void)
+    * Part of the Stable ABI since version 3.10.*
+
+   Enable the garbage collector: similar to "gc.enable()". Returns the
+   previous state, 0 for disabled and 1 for enabled.
+
+   Added in version 3.10.
+
+int PyGC_Disable(void)
+    * Part of the Stable ABI since version 3.10.*
+
+   Disable the garbage collector: similar to "gc.disable()". Returns
+   the previous state, 0 for disabled and 1 for enabled.
+
+   Added in version 3.10.
+
+int PyGC_IsEnabled(void)
+    * Part of the Stable ABI since version 3.10.*
+
+   Query the state of the garbage collector: similar to
+   "gc.isenabled()". Returns the current state, 0 for disabled and 1
+   for enabled.
+
+   Added in version 3.10.
+
+
+Querying Garbage Collector State
+================================
+
+The C-API provides the following interface for querying information
+about the garbage collector.
+
+void PyUnstable_GC_VisitObjects(gcvisitobjects_t callback, void *arg)
+
+   *This is Unstable API. It may change without warning in minor
+   releases.*
+
+   Run supplied *callback* on all live GC-capable objects. *arg* is
+   passed through to all invocations of *callback*.
+
+   Warning:
+
+     If new objects are (de)allocated by the callback it is undefined
+     if they will be visited.Garbage collection is disabled during
+     operation. Explicitly running a collection in the callback may
+     lead to undefined behaviour e.g. visiting the same objects
+     multiple times or not at all.
+
+   Added in version 3.12.
+
+typedef int (*gcvisitobjects_t)(PyObject *object, void *arg)
+
+   Type of the visitor function to be passed to
+   "PyUnstable_GC_VisitObjects()". *arg* is the same as the *arg*
+   passed to "PyUnstable_GC_VisitObjects". Return "0" to continue
+   iteration, return "1" to stop iteration. Other return values are
+   reserved for now so behavior on returning anything else is
+   undefined.
+
+   Added in version 3.12.

python-3.12.6-docs-text/python-3.12.6-docs-text/c-api/gen.txt

@@ -0,0 +1,40 @@
+Generator Objects
+*****************
+
+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 "PyGen_New()" or
+"PyGen_NewWithQualName()".
+
+type PyGenObject
+
+   The C structure used for generator objects.
+
+PyTypeObject PyGen_Type
+
+   The type object corresponding to generator objects.
+
+int PyGen_Check(PyObject *ob)
+
+   Return true if *ob* is a generator object; *ob* must not be "NULL".
+   This function always succeeds.
+
+int PyGen_CheckExact(PyObject *ob)
+
+   Return true if *ob*'s type is "PyGen_Type"; *ob* must not be
+   "NULL".  This function always succeeds.
+
+PyObject *PyGen_New(PyFrameObject *frame)
+    *Return value: New reference.*
+
+   Create and return a new generator object based on the *frame*
+   object. A reference to *frame* is stolen by this function. The
+   argument must not be "NULL".
+
+PyObject *PyGen_NewWithQualName(PyFrameObject *frame, PyObject *name, PyObject *qualname)
+    *Return value: New reference.*
+
+   Create and return a new generator object based on the *frame*
+   object, with "__name__" and "__qualname__" set to *name* and
+   *qualname*. A reference to *frame* is stolen by this function.  The
+   *frame* argument must not be "NULL".

python-3.12.6-docs-text/python-3.12.6-docs-text/c-api/hash.txt

@@ -0,0 +1,42 @@
+PyHash API
+**********
+
+See also the "PyTypeObject.tp_hash" member.
+
+type Py_hash_t
+
+   Hash value type: signed integer.
+
+   Added in version 3.2.
+
+type Py_uhash_t
+
+   Hash value type: unsigned integer.
+
+   Added in version 3.2.
+
+type PyHash_FuncDef
+
+   Hash function definition used by "PyHash_GetFuncDef()".
+
+   const char *name
+
+      Hash function name (UTF-8 encoded string).
+
+   const int hash_bits
+
+      Internal size of the hash value in bits.
+
+   const int seed_bits
+
+      Size of seed input in bits.
+
+   Added in version 3.4.
+
+PyHash_FuncDef *PyHash_GetFuncDef(void)
+
+   Get the hash function definition.
+
+   See also: **PEP 456** "Secure and interchangeable hash algorithm".
+
+   Added in version 3.4.

python-3.12.6-docs-text/python-3.12.6-docs-text/c-api/import.txt

@@ -0,0 +1,311 @@
+Importing Modules
+*****************
+
+PyObject *PyImport_ImportModule(const char *name)
+    *Return value: New reference.** Part of the Stable ABI.*
+
+   This is a wrapper around "PyImport_Import()" which takes a const
+   char* as an argument instead of a PyObject*.
+
+PyObject *PyImport_ImportModuleNoBlock(const char *name)
+    *Return value: New reference.** Part of the Stable ABI.*
+
+   This function is a deprecated alias of "PyImport_ImportModule()".
+
+   Changed in version 3.3: This function used to fail immediately when
+   the import lock was held by another thread.  In Python 3.3 though,
+   the locking scheme switched to per-module locks for most purposes,
+   so this function's special behaviour isn't needed anymore.
+
+PyObject *PyImport_ImportModuleEx(const char *name, PyObject *globals, PyObject *locals, PyObject *fromlist)
+    *Return value: New reference.*
+
+   Import a module.  This is best described by referring to the built-
+   in Python function "__import__()".
+
+   The return value is a new reference to the imported module or top-
+   level package, or "NULL" with an exception set on failure.  Like
+   for "__import__()", the return value when a submodule of a package
+   was requested is normally the top-level package, unless a non-empty
+   *fromlist* was given.
+
+   Failing imports remove incomplete module objects, like with
+   "PyImport_ImportModule()".
+
+PyObject *PyImport_ImportModuleLevelObject(PyObject *name, PyObject *globals, PyObject *locals, PyObject *fromlist, int level)
+    *Return value: New reference.** Part of the Stable ABI since
+   version 3.7.*
+
+   Import a module.  This is best described by referring to the built-
+   in Python function "__import__()", as the standard "__import__()"
+   function calls this function directly.
+
+   The return value is a new reference to the imported module or top-
+   level package, or "NULL" with an exception set on failure.  Like
+   for "__import__()", the return value when a submodule of a package
+   was requested is normally the top-level package, unless a non-empty
+   *fromlist* was given.
+
+   Added in version 3.3.
+
+PyObject *PyImport_ImportModuleLevel(const char *name, PyObject *globals, PyObject *locals, PyObject *fromlist, int level)
+    *Return value: New reference.** Part of the Stable ABI.*
+
+   Similar to "PyImport_ImportModuleLevelObject()", but the name is a
+   UTF-8 encoded string instead of a Unicode object.
+
+   Changed in version 3.3: Negative values for *level* are no longer
+   accepted.
+
+PyObject *PyImport_Import(PyObject *name)
+    *Return value: New reference.** Part of the Stable ABI.*
+
+   This is a higher-level interface that calls the current "import
+   hook function" (with an explicit *level* of 0, meaning absolute
+   import).  It invokes the "__import__()" function from the
+   "__builtins__" of the current globals.  This means that the import
+   is done using whatever import hooks are installed in the current
+   environment.
+
+   This function always uses absolute imports.
+
+PyObject *PyImport_ReloadModule(PyObject *m)
+    *Return value: New reference.** Part of the Stable ABI.*
+
+   Reload a module.  Return a new reference to the reloaded module, or
+   "NULL" with an exception set on failure (the module still exists in
+   this case).
+
+PyObject *PyImport_AddModuleObject(PyObject *name)
+    *Return value: Borrowed reference.** Part of the Stable ABI since
+   version 3.7.*
+
+   Return the module object corresponding to a module name.  The
+   *name* argument may be of the form "package.module". First check
+   the modules dictionary if there's one there, and if not, create a
+   new one and insert it in the modules dictionary. Return "NULL" with
+   an exception set on failure.
+
+   Note:
+
+     This function does not load or import the module; if the module
+     wasn't already loaded, you will get an empty module object. Use
+     "PyImport_ImportModule()" or one of its variants to import a
+     module.  Package structures implied by a dotted name for *name*
+     are not created if not already present.
+
+   Added in version 3.3.
+
+PyObject *PyImport_AddModule(const char *name)
+    *Return value: Borrowed reference.** Part of the Stable ABI.*
+
+   Similar to "PyImport_AddModuleObject()", but the name is a UTF-8
+   encoded string instead of a Unicode object.
+
+PyObject *PyImport_ExecCodeModule(const char *name, PyObject *co)
+    *Return value: New reference.** Part of the Stable ABI.*
+
+   Given a module name (possibly of the form "package.module") and a
+   code object read from a Python bytecode file or obtained from the
+   built-in function "compile()", load the module.  Return a new
+   reference to the module object, or "NULL" with an exception set if
+   an error occurred.  *name* is removed from "sys.modules" in error
+   cases, even if *name* was already in "sys.modules" on entry to
+   "PyImport_ExecCodeModule()".  Leaving incompletely initialized
+   modules in "sys.modules" is dangerous, as imports of such modules
+   have no way to know that the module object is an unknown (and
+   probably damaged with respect to the module author's intents)
+   state.
+
+   The module's "__spec__" and "__loader__" will be set, if not set
+   already, with the appropriate values.  The spec's loader will be
+   set to the module's "__loader__" (if set) and to an instance of
+   "SourceFileLoader" otherwise.
+
+   The module's "__file__" attribute will be set to the code object's
+   "co_filename".  If applicable, "__cached__" will also be set.
+
+   This function will reload the module if it was already imported.
+   See "PyImport_ReloadModule()" for the intended way to reload a
+   module.
+
+   If *name* points to a dotted name of the form "package.module", any
+   package structures not already created will still not be created.
+
+   See also "PyImport_ExecCodeModuleEx()" and
+   "PyImport_ExecCodeModuleWithPathnames()".
+
+   Changed in version 3.12: The setting of "__cached__" and
+   "__loader__" is deprecated. See "ModuleSpec" for alternatives.
+
+PyObject *PyImport_ExecCodeModuleEx(const char *name, PyObject *co, const char *pathname)
+    *Return value: New reference.** Part of the Stable ABI.*
+
+   Like "PyImport_ExecCodeModule()", but the "__file__" attribute of
+   the module object is set to *pathname* if it is non-"NULL".
+
+   See also "PyImport_ExecCodeModuleWithPathnames()".
+
+PyObject *PyImport_ExecCodeModuleObject(PyObject *name, PyObject *co, PyObject *pathname, PyObject *cpathname)
+    *Return value: New reference.** Part of the Stable ABI since
+   version 3.7.*
+
+   Like "PyImport_ExecCodeModuleEx()", but the "__cached__" attribute
+   of the module object is set to *cpathname* if it is non-"NULL".  Of
+   the three functions, this is the preferred one to use.
+
+   Added in version 3.3.
+
+   Changed in version 3.12: Setting "__cached__" is deprecated. See
+   "ModuleSpec" for alternatives.
+
+PyObject *PyImport_ExecCodeModuleWithPathnames(const char *name, PyObject *co, const char *pathname, const char *cpathname)
+    *Return value: New reference.** Part of the Stable ABI.*
+
+   Like "PyImport_ExecCodeModuleObject()", but *name*, *pathname* and
+   *cpathname* are UTF-8 encoded strings. Attempts are also made to
+   figure out what the value for *pathname* should be from *cpathname*
+   if the former is set to "NULL".
+
+   Added in version 3.2.
+
+   Changed in version 3.3: Uses "imp.source_from_cache()" in
+   calculating the source path if only the bytecode path is provided.
+
+   Changed in version 3.12: No longer uses the removed "imp" module.
+
+long PyImport_GetMagicNumber()
+    * Part of the Stable ABI.*
+
+   Return the magic number for Python bytecode files (a.k.a. ".pyc"
+   file). The magic number should be present in the first four bytes
+   of the bytecode file, in little-endian byte order. Returns "-1" on
+   error.
+
+   Changed in version 3.3: Return value of "-1" upon failure.
+
+const char *PyImport_GetMagicTag()
+    * Part of the Stable ABI.*
+
+   Return the magic tag string for **PEP 3147** format Python bytecode
+   file names.  Keep in mind that the value at
+   "sys.implementation.cache_tag" is authoritative and should be used
+   instead of this function.
+
+   Added in version 3.2.
+
+PyObject *PyImport_GetModuleDict()
+    *Return value: Borrowed reference.** Part of the Stable ABI.*
+
+   Return the dictionary used for the module administration (a.k.a.
+   "sys.modules").  Note that this is a per-interpreter variable.
+
+PyObject *PyImport_GetModule(PyObject *name)
+    *Return value: New reference.** Part of the Stable ABI since
+   version 3.8.*
+
+   Return the already imported module with the given name.  If the
+   module has not been imported yet then returns "NULL" but does not
+   set an error.  Returns "NULL" and sets an error if the lookup
+   failed.
+
+   Added in version 3.7.
+
+PyObject *PyImport_GetImporter(PyObject *path)
+    *Return value: New reference.** Part of the Stable ABI.*
+
+   Return a finder object for a "sys.path"/"pkg.__path__" item *path*,
+   possibly by fetching it from the "sys.path_importer_cache" dict.
+   If it wasn't yet cached, traverse "sys.path_hooks" until a hook is
+   found that can handle the path item.  Return "None" if no hook
+   could; this tells our caller that the *path based finder* could not
+   find a finder for this path item. Cache the result in
+   "sys.path_importer_cache". Return a new reference to the finder
+   object.
+
+int PyImport_ImportFrozenModuleObject(PyObject *name)
+    * Part of the Stable ABI since version 3.7.*
+
+   Load a frozen module named *name*.  Return "1" for success, "0" if
+   the module is not found, and "-1" with an exception set if the
+   initialization failed.  To access the imported module on a
+   successful load, use "PyImport_ImportModule()".  (Note the misnomer
+   --- this function would reload the module if it was already
+   imported.)
+
+   Added in version 3.3.
+
+   Changed in version 3.4: The "__file__" attribute is no longer set
+   on the module.
+
+int PyImport_ImportFrozenModule(const char *name)
+    * Part of the Stable ABI.*
+
+   Similar to "PyImport_ImportFrozenModuleObject()", but the name is a
+   UTF-8 encoded string instead of a Unicode object.
+
+struct _frozen
+
+   This is the structure type definition for frozen module
+   descriptors, as generated by the **freeze** utility (see
+   "Tools/freeze/" in the Python source distribution).  Its
+   definition, found in "Include/import.h", is:
+
+      struct _frozen {
+          const char *name;
+          const unsigned char *code;
+          int size;
+          bool is_package;
+      };
+
+   Changed in version 3.11: The new "is_package" field indicates
+   whether the module is a package or not. This replaces setting the
+   "size" field to a negative value.
+
+const struct _frozen *PyImport_FrozenModules
+
+   This pointer is initialized to point to an array of "_frozen"
+   records, terminated by one whose members are all "NULL" or zero.
+   When a frozen module is imported, it is searched in this table.
+   Third-party code could play tricks with this to provide a
+   dynamically created collection of frozen modules.
+
+int PyImport_AppendInittab(const char *name, PyObject *(*initfunc)(void))
+    * Part of the Stable ABI.*
+
+   Add a single module to the existing table of built-in modules.
+   This is a convenience wrapper around "PyImport_ExtendInittab()",
+   returning "-1" if the table could not be extended.  The new module
+   can be imported by the name *name*, and uses the function
+   *initfunc* as the initialization function called on the first
+   attempted import.  This should be called before "Py_Initialize()".
+
+struct _inittab
+
+   Structure describing a single entry in the list of built-in
+   modules. Programs which embed Python may use an array of these
+   structures in conjunction with "PyImport_ExtendInittab()" to
+   provide additional built-in modules. The structure consists of two
+   members:
+
+   const char *name
+
+      The module name, as an ASCII encoded string.
+
+   PyObject *(*initfunc)(void)
+
+      Initialization function for a module built into the interpreter.
+
+int PyImport_ExtendInittab(struct _inittab *newtab)
+
+   Add a collection of modules to the table of built-in modules.  The
+   *newtab* array must end with a sentinel entry which contains "NULL"
+   for the "name" field; failure to provide the sentinel value can
+   result in a memory fault. Returns "0" on success or "-1" if
+   insufficient memory could be allocated to extend the internal
+   table.  In the event of failure, no modules are added to the
+   internal table.  This must be called before "Py_Initialize()".
+
+   If Python is initialized multiple times, "PyImport_AppendInittab()"
+   or "PyImport_ExtendInittab()" must be called before each Python
+   initialization.

python-3.12.6-docs-text/python-3.12.6-docs-text/c-api/index.txt

@@ -0,0 +1,218 @@
+Python/C API Reference Manual
+*****************************
+
+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
+Extending and Embedding the Python Interpreter, which describes the
+general principles of extension writing but does not document the API
+functions in detail.
+
+* Introduction
+
+  * Coding standards
+
+  * Include Files
+
+  * Useful macros
+
+  * Objects, Types and Reference Counts
+
+  * Exceptions
+
+  * Embedding Python
+
+  * Debugging Builds
+
+* C API Stability
+
+  * Unstable C API
+
+  * Stable Application Binary Interface
+
+  * Platform Considerations
+
+  * Contents of Limited API
+
+* The Very High Level Layer
+
+* Reference Counting
+
+* Exception Handling
+
+  * Printing and clearing
+
+  * Raising exceptions
+
+  * Issuing warnings
+
+  * Querying the error indicator
+
+  * Signal Handling
+
+  * Exception Classes
+
+  * Exception Objects
+
+  * Unicode Exception Objects
+
+  * Recursion Control
+
+  * Standard Exceptions
+
+  * Standard Warning Categories
+
+* Utilities
+
+  * Operating System Utilities
+
+  * System Functions
+
+  * Process Control
+
+  * Importing Modules
+
+  * Data marshalling support
+
+  * Parsing arguments and building values
+
+  * String conversion and formatting
+
+  * PyHash API
+
+  * Reflection
+
+  * Codec registry and support functions
+
+  * Support for Perf Maps
+
+* Abstract Objects Layer
+
+  * Object Protocol
+
+  * Call Protocol
+
+  * Number Protocol
+
+  * Sequence Protocol
+
+  * Mapping Protocol
+
+  * Iterator Protocol
+
+  * Buffer Protocol
+
+  * Old Buffer Protocol
+
+* Concrete Objects Layer
+
+  * Fundamental Objects
+
+  * Numeric Objects
+
+  * Sequence Objects
+
+  * Container Objects
+
+  * Function Objects
+
+  * Other Objects
+
+* Initialization, Finalization, and Threads
+
+  * Before Python Initialization
+
+  * Global configuration variables
+
+  * Initializing and finalizing the interpreter
+
+  * Process-wide parameters
+
+  * Thread State and the Global Interpreter Lock
+
+  * Sub-interpreter support
+
+  * Asynchronous Notifications
+
+  * Profiling and Tracing
+
+  * Advanced Debugger Support
+
+  * Thread Local Storage Support
+
+* Python Initialization Configuration
+
+  * Example
+
+  * PyWideStringList
+
+  * PyStatus
+
+  * PyPreConfig
+
+  * Preinitialize Python with PyPreConfig
+
+  * PyConfig
+
+  * Initialization with PyConfig
+
+  * Isolated Configuration
+
+  * Python Configuration
+
+  * Python Path Configuration
+
+  * Py_RunMain()
+
+  * Py_GetArgcArgv()
+
+  * Multi-Phase Initialization Private Provisional API
+
+* Memory Management
+
+  * Overview
+
+  * Allocator Domains
+
+  * Raw Memory Interface
+
+  * Memory Interface
+
+  * Object allocators
+
+  * Default Memory Allocators
+
+  * Customize Memory Allocators
+
+  * Debug hooks on the Python memory allocators
+
+  * The pymalloc allocator
+
+  * tracemalloc C API
+
+  * Examples
+
+* Object Implementation Support
+
+  * Allocating Objects on the Heap
+
+  * Common Object Structures
+
+  * Type Objects
+
+  * Number Object Structures
+
+  * Mapping Object Structures
+
+  * Sequence Object Structures
+
+  * Buffer Object Structures
+
+  * Async Object Structures
+
+  * Slot Type typedefs
+
+  * Examples
+
+  * Supporting Cyclic Garbage Collection
+
+* API and ABI Versioning

python-3.12.6-docs-text/python-3.12.6-docs-text/c-api/init.txt

@@ -0,0 +1,2115 @@
+Initialization, Finalization, and Threads
+*****************************************
+
+See also Python Initialization Configuration.
+
+
+Before Python Initialization
+============================
+
+In an application embedding  Python, the "Py_Initialize()" function
+must be called before using any other Python/C API functions; with the
+exception of a few functions and the global configuration variables.
+
+The following functions can be safely called before Python is
+initialized:
+
+* Configuration functions:
+
+  * "PyImport_AppendInittab()"
+
+  * "PyImport_ExtendInittab()"
+
+  * "PyInitFrozenExtensions()"
+
+  * "PyMem_SetAllocator()"
+
+  * "PyMem_SetupDebugHooks()"
+
+  * "PyObject_SetArenaAllocator()"
+
+  * "Py_SetPath()"
+
+  * "Py_SetProgramName()"
+
+  * "Py_SetPythonHome()"
+
+  * "Py_SetStandardStreamEncoding()"
+
+  * "PySys_AddWarnOption()"
+
+  * "PySys_AddXOption()"
+
+  * "PySys_ResetWarnOptions()"
+
+* Informative functions:
+
+  * "Py_IsInitialized()"
+
+  * "PyMem_GetAllocator()"
+
+  * "PyObject_GetArenaAllocator()"
+
+  * "Py_GetBuildInfo()"
+
+  * "Py_GetCompiler()"
+
+  * "Py_GetCopyright()"
+
+  * "Py_GetPlatform()"
+
+  * "Py_GetVersion()"
+
+* Utilities:
+
+  * "Py_DecodeLocale()"
+
+* Memory allocators:
+
+  * "PyMem_RawMalloc()"
+
+  * "PyMem_RawRealloc()"
+
+  * "PyMem_RawCalloc()"
+
+  * "PyMem_RawFree()"
+
+Note:
+
+  The following functions **should not be called** before
+  "Py_Initialize()": "Py_EncodeLocale()", "Py_GetPath()",
+  "Py_GetPrefix()", "Py_GetExecPrefix()", "Py_GetProgramFullPath()",
+  "Py_GetPythonHome()", "Py_GetProgramName()" and
+  "PyEval_InitThreads()".
+
+
+Global configuration variables
+==============================
+
+Python has variables for the global configuration to control different
+features and options. By default, these flags are controlled by
+command line options.
+
+When a flag is set by an option, the value of the flag is the number
+of times that the option was set. For example, "-b" sets
+"Py_BytesWarningFlag" to 1 and "-bb" sets "Py_BytesWarningFlag" to 2.
+
+int Py_BytesWarningFlag
+
+   This API is kept for backward compatibility: setting
+   "PyConfig.bytes_warning" should be used instead, see Python
+   Initialization Configuration.
+
+   Issue a warning when comparing "bytes" or "bytearray" with "str" or
+   "bytes" with "int".  Issue an error if greater or equal to "2".
+
+   Set by the "-b" option.
+
+   Deprecated since version 3.12.
+
+int Py_DebugFlag
+
+   This API is kept for backward compatibility: setting
+   "PyConfig.parser_debug" should be used instead, see Python
+   Initialization Configuration.
+
+   Turn on parser debugging output (for expert only, depending on
+   compilation options).
+
+   Set by the "-d" option and the "PYTHONDEBUG" environment variable.
+
+   Deprecated since version 3.12.
+
+int Py_DontWriteBytecodeFlag
+
+   This API is kept for backward compatibility: setting
+   "PyConfig.write_bytecode" should be used instead, see Python
+   Initialization Configuration.
+
+   If set to non-zero, Python won't try to write ".pyc" files on the
+   import of source modules.
+
+   Set by the "-B" option and the "PYTHONDONTWRITEBYTECODE"
+   environment variable.
+
+   Deprecated since version 3.12.
+
+int Py_FrozenFlag
+
+   This API is kept for backward compatibility: setting
+   "PyConfig.pathconfig_warnings" should be used instead, see Python
+   Initialization Configuration.
+
+   Suppress error messages when calculating the module search path in
+   "Py_GetPath()".
+
+   Private flag used by "_freeze_module" and "frozenmain" programs.
+
+   Deprecated since version 3.12.
+
+int Py_HashRandomizationFlag
+
+   This API is kept for backward compatibility: setting
+   "PyConfig.hash_seed" and "PyConfig.use_hash_seed" should be used
+   instead, see Python Initialization Configuration.
+
+   Set to "1" if the "PYTHONHASHSEED" environment variable is set to a
+   non-empty string.
+
+   If the flag is non-zero, read the "PYTHONHASHSEED" environment
+   variable to initialize the secret hash seed.
+
+   Deprecated since version 3.12.
+
+int Py_IgnoreEnvironmentFlag
+
+   This API is kept for backward compatibility: setting
+   "PyConfig.use_environment" should be used instead, see Python
+   Initialization Configuration.
+
+   Ignore all "PYTHON*" environment variables, e.g. "PYTHONPATH" and
+   "PYTHONHOME", that might be set.
+
+   Set by the "-E" and "-I" options.
+
+   Deprecated since version 3.12.
+
+int Py_InspectFlag
+
+   This API is kept for backward compatibility: setting
+   "PyConfig.inspect" should be used instead, see Python
+   Initialization Configuration.
+
+   When a script is passed as first argument or the "-c" option is
+   used, enter interactive mode after executing the script or the
+   command, even when "sys.stdin" does not appear to be a terminal.
+
+   Set by the "-i" option and the "PYTHONINSPECT" environment
+   variable.
+
+   Deprecated since version 3.12.
+
+int Py_InteractiveFlag
+
+   This API is kept for backward compatibility: setting
+   "PyConfig.interactive" should be used instead, see Python
+   Initialization Configuration.
+
+   Set by the "-i" option.
+
+   Deprecated since version 3.12.
+
+int Py_IsolatedFlag
+
+   This API is kept for backward compatibility: setting
+   "PyConfig.isolated" should be used instead, see Python
+   Initialization Configuration.
+
+   Run Python in isolated mode. In isolated mode "sys.path" contains
+   neither the script's directory nor the user's site-packages
+   directory.
+
+   Set by the "-I" option.
+
+   Added in version 3.4.
+
+   Deprecated since version 3.12.
+
+int Py_LegacyWindowsFSEncodingFlag
+
+   This API is kept for backward compatibility: setting
+   "PyPreConfig.legacy_windows_fs_encoding" should be used instead,
+   see Python Initialization Configuration.
+
+   If the flag is non-zero, use the "mbcs" encoding with "replace"
+   error handler, instead of the UTF-8 encoding with "surrogatepass"
+   error handler, for the *filesystem encoding and error handler*.
+
+   Set to "1" if the "PYTHONLEGACYWINDOWSFSENCODING" environment
+   variable is set to a non-empty string.
+
+   See **PEP 529** for more details.
+
+   Availability: Windows.
+
+   Deprecated since version 3.12.
+
+int Py_LegacyWindowsStdioFlag
+
+   This API is kept for backward compatibility: setting
+   "PyConfig.legacy_windows_stdio" should be used instead, see Python
+   Initialization Configuration.
+
+   If the flag is non-zero, use "io.FileIO" instead of
+   "io._WindowsConsoleIO" for "sys" standard streams.
+
+   Set to "1" if the "PYTHONLEGACYWINDOWSSTDIO" environment variable
+   is set to a non-empty string.
+
+   See **PEP 528** for more details.
+
+   Availability: Windows.
+
+   Deprecated since version 3.12.
+
+int Py_NoSiteFlag
+
+   This API is kept for backward compatibility: setting
+   "PyConfig.site_import" should be used instead, see Python
+   Initialization Configuration.
+
+   Disable the import of the module "site" and the site-dependent
+   manipulations of "sys.path" that it entails.  Also disable these
+   manipulations if "site" is explicitly imported later (call
+   "site.main()" if you want them to be triggered).
+
+   Set by the "-S" option.
+
+   Deprecated since version 3.12.
+
+int Py_NoUserSiteDirectory
+
+   This API is kept for backward compatibility: setting
+   "PyConfig.user_site_directory" should be used instead, see Python
+   Initialization Configuration.
+
+   Don't add the "user site-packages directory" to "sys.path".
+
+   Set by the "-s" and "-I" options, and the "PYTHONNOUSERSITE"
+   environment variable.
+
+   Deprecated since version 3.12.
+
+int Py_OptimizeFlag
+
+   This API is kept for backward compatibility: setting
+   "PyConfig.optimization_level" should be used instead, see Python
+   Initialization Configuration.
+
+   Set by the "-O" option and the "PYTHONOPTIMIZE" environment
+   variable.
+
+   Deprecated since version 3.12.
+
+int Py_QuietFlag
+
+   This API is kept for backward compatibility: setting
+   "PyConfig.quiet" should be used instead, see Python Initialization
+   Configuration.
+
+   Don't display the copyright and version messages even in
+   interactive mode.
+
+   Set by the "-q" option.
+
+   Added in version 3.2.
+
+   Deprecated since version 3.12.
+
+int Py_UnbufferedStdioFlag
+
+   This API is kept for backward compatibility: setting
+   "PyConfig.buffered_stdio" should be used instead, see Python
+   Initialization Configuration.
+
+   Force the stdout and stderr streams to be unbuffered.
+
+   Set by the "-u" option and the "PYTHONUNBUFFERED" environment
+   variable.
+
+   Deprecated since version 3.12.
+
+int Py_VerboseFlag
+
+   This API is kept for backward compatibility: setting
+   "PyConfig.verbose" should be used instead, see Python
+   Initialization Configuration.
+
+   Print a message each time a module is initialized, showing the
+   place (filename or built-in module) from which it is loaded.  If
+   greater or equal to "2", print a message for each file that is
+   checked for when searching for a module. Also provides information
+   on module cleanup at exit.
+
+   Set by the "-v" option and the "PYTHONVERBOSE" environment
+   variable.
+
+   Deprecated since version 3.12.
+
+
+Initializing and finalizing the interpreter
+===========================================
+
+void Py_Initialize()
+    * Part of the Stable ABI.*
+
+   Initialize the Python interpreter.  In an application embedding
+   Python, this should be called before using any other Python/C API
+   functions; see Before Python Initialization for the few exceptions.
+
+   This initializes the table of loaded modules ("sys.modules"), and
+   creates the fundamental modules "builtins", "__main__" and "sys".
+   It also initializes the module search path ("sys.path"). It does
+   not set "sys.argv"; use "PySys_SetArgvEx()" for that.  This is a
+   no-op when called for a second time (without calling
+   "Py_FinalizeEx()" first).  There is no return value; it is a fatal
+   error if the initialization fails.
+
+   Use the "Py_InitializeFromConfig()" function to customize the
+   Python Initialization Configuration.
+
+   Note:
+
+     On Windows, changes the console mode from "O_TEXT" to "O_BINARY",
+     which will also affect non-Python uses of the console using the C
+     Runtime.
+
+void Py_InitializeEx(int initsigs)
+    * Part of the Stable ABI.*
+
+   This function works like "Py_Initialize()" if *initsigs* is "1". If
+   *initsigs* is "0", it skips initialization registration of signal
+   handlers, which might be useful when Python is embedded.
+
+   Use the "Py_InitializeFromConfig()" function to customize the
+   Python Initialization Configuration.
+
+int Py_IsInitialized()
+    * Part of the Stable ABI.*
+
+   Return true (nonzero) when the Python interpreter has been
+   initialized, false (zero) if not.  After "Py_FinalizeEx()" is
+   called, this returns false until "Py_Initialize()" is called again.
+
+int Py_FinalizeEx()
+    * Part of the Stable ABI since version 3.6.*
+
+   Undo all initializations made by "Py_Initialize()" and subsequent
+   use of Python/C API functions, and destroy all sub-interpreters
+   (see "Py_NewInterpreter()" below) that were created and not yet
+   destroyed since the last call to "Py_Initialize()".  Ideally, this
+   frees all memory allocated by the Python interpreter.  This is a
+   no-op when called for a second time (without calling
+   "Py_Initialize()" again first).
+
+   Since this is the reverse of "Py_Initialize()", it should be called
+   in the same thread with the same interpreter active.  That means
+   the main thread and the main interpreter. This should never be
+   called while "Py_RunMain()" is running.
+
+   Normally the return value is "0". If there were errors during
+   finalization (flushing buffered data), "-1" is returned.
+
+   This function is provided for a number of reasons.  An embedding
+   application might want to restart Python without having to restart
+   the application itself. An application that has loaded the Python
+   interpreter from a dynamically loadable library (or DLL) might want
+   to free all memory allocated by Python before unloading the DLL.
+   During a hunt for memory leaks in an application a developer might
+   want to free all memory allocated by Python before exiting from the
+   application.
+
+   **Bugs and caveats:** The destruction of modules and objects in
+   modules is done in random order; this may cause destructors
+   ("__del__()" methods) to fail when they depend on other objects
+   (even functions) or modules.  Dynamically loaded extension modules
+   loaded by Python are not unloaded.  Small amounts of memory
+   allocated by the Python interpreter may not be freed (if you find a
+   leak, please report it).  Memory tied up in circular references
+   between objects is not freed.  Some memory allocated by extension
+   modules may not be freed.  Some extensions may not work properly if
+   their initialization routine is called more than once; this can
+   happen if an application calls "Py_Initialize()" and
+   "Py_FinalizeEx()" more than once.
+
+   Raises an auditing event "cpython._PySys_ClearAuditHooks" with no
+   arguments.
+
+   Added in version 3.6.
+
+void Py_Finalize()
+    * Part of the Stable ABI.*
+
+   This is a backwards-compatible version of "Py_FinalizeEx()" that
+   disregards the return value.
+
+
+Process-wide parameters
+=======================
+
+int Py_SetStandardStreamEncoding(const char *encoding, const char *errors)
+
+   This API is kept for backward compatibility: setting
+   "PyConfig.stdio_encoding" and "PyConfig.stdio_errors" should be
+   used instead, see Python Initialization Configuration.
+
+   This function should be called before "Py_Initialize()", if it is
+   called at all. It specifies which encoding and error handling to
+   use with standard IO, with the same meanings as in "str.encode()".
+
+   It overrides "PYTHONIOENCODING" values, and allows embedding code
+   to control IO encoding when the environment variable does not work.
+
+   *encoding* and/or *errors* may be "NULL" to use "PYTHONIOENCODING"
+   and/or default values (depending on other settings).
+
+   Note that "sys.stderr" always uses the "backslashreplace" error
+   handler, regardless of this (or any other) setting.
+
+   If "Py_FinalizeEx()" is called, this function will need to be
+   called again in order to affect subsequent calls to
+   "Py_Initialize()".
+
+   Returns "0" if successful, a nonzero value on error (e.g. calling
+   after the interpreter has already been initialized).
+
+   Added in version 3.4.
+
+   Deprecated since version 3.11.
+
+void Py_SetProgramName(const wchar_t *name)
+    * Part of the Stable ABI.*
+
+   This API is kept for backward compatibility: setting
+   "PyConfig.program_name" should be used instead, see Python
+   Initialization Configuration.
+
+   This function should be called before "Py_Initialize()" is called
+   for the first time, if it is called at all.  It tells the
+   interpreter the value of the "argv[0]" argument to the "main()"
+   function of the program (converted to wide characters). This is
+   used by "Py_GetPath()" and some other functions below to find the
+   Python run-time libraries relative to the interpreter executable.
+   The default value is "'python'".  The argument should point to a
+   zero-terminated wide character string in static storage whose
+   contents will not change for the duration of the program's
+   execution.  No code in the Python interpreter will change the
+   contents of this storage.
+
+   Use "Py_DecodeLocale()" to decode a bytes string to get a wchar_t*
+   string.
+
+   Deprecated since version 3.11.
+
+wchar_t *Py_GetProgramName()
+    * Part of the Stable ABI.*
+
+   Return the program name set with "Py_SetProgramName()", or the
+   default. The returned string points into static storage; the caller
+   should not modify its value.
+
+   This function should not be called before "Py_Initialize()",
+   otherwise it returns "NULL".
+
+   Changed in version 3.10: It now returns "NULL" if called before
+   "Py_Initialize()".
+
+wchar_t *Py_GetPrefix()
+    * Part of the Stable ABI.*
+
+   Return the *prefix* for installed platform-independent files. This
+   is derived through a number of complicated rules from the program
+   name set with "Py_SetProgramName()" and some environment variables;
+   for example, if the program name is "'/usr/local/bin/python'", the
+   prefix is "'/usr/local'". The returned string points into static
+   storage; the caller should not modify its value.  This corresponds
+   to the **prefix** variable in the top-level "Makefile" and the "--
+   prefix" argument to the **configure** script at build time.  The
+   value is available to Python code as "sys.prefix". It is only
+   useful on Unix.  See also the next function.
+
+   This function should not be called before "Py_Initialize()",
+   otherwise it returns "NULL".
+
+   Changed in version 3.10: It now returns "NULL" if called before
+   "Py_Initialize()".
+
+wchar_t *Py_GetExecPrefix()
+    * Part of the Stable ABI.*
+
+   Return the *exec-prefix* for installed platform-*dependent* files.
+   This is derived through a number of complicated rules from the
+   program name set with "Py_SetProgramName()" and some environment
+   variables; for example, if the program name is
+   "'/usr/local/bin/python'", the exec-prefix is "'/usr/local'".  The
+   returned string points into static storage; the caller should not
+   modify its value.  This corresponds to the **exec_prefix** variable
+   in the top-level "Makefile" and the "--exec-prefix" argument to the
+   **configure** script at build  time.  The value is available to
+   Python code as "sys.exec_prefix".  It is only useful on Unix.
+
+   Background: The exec-prefix differs from the prefix when platform
+   dependent files (such as executables and shared libraries) are
+   installed in a different directory tree.  In a typical
+   installation, platform dependent files may be installed in the
+   "/usr/local/plat" subtree while platform independent may be
+   installed in "/usr/local".
+
+   Generally speaking, a platform is a combination of hardware and
+   software families, e.g.  Sparc machines running the Solaris 2.x
+   operating system are considered the same platform, but Intel
+   machines running Solaris 2.x are another platform, and Intel
+   machines running Linux are yet another platform.  Different major
+   revisions of the same operating system generally also form
+   different platforms.  Non-Unix operating systems are a different
+   story; the installation strategies on those systems are so
+   different that the prefix and exec-prefix are meaningless, and set
+   to the empty string. Note that compiled Python bytecode files are
+   platform independent (but not independent from the Python version
+   by which they were compiled!).
+
+   System administrators will know how to configure the **mount** or
+   **automount** programs to share "/usr/local" between platforms
+   while having "/usr/local/plat" be a different filesystem for each
+   platform.
+
+   This function should not be called before "Py_Initialize()",
+   otherwise it returns "NULL".
+
+   Changed in version 3.10: It now returns "NULL" if called before
+   "Py_Initialize()".
+
+wchar_t *Py_GetProgramFullPath()
+    * Part of the Stable ABI.*
+
+   Return the full program name of the Python executable; this is
+   computed as a side-effect of deriving the default module search
+   path  from the program name (set by "Py_SetProgramName()" above).
+   The returned string points into static storage; the caller should
+   not modify its value.  The value is available to Python code as
+   "sys.executable".
+
+   This function should not be called before "Py_Initialize()",
+   otherwise it returns "NULL".
+
+   Changed in version 3.10: It now returns "NULL" if called before
+   "Py_Initialize()".
+
+wchar_t *Py_GetPath()
+    * Part of the Stable ABI.*
+
+   Return the default module search path; this is computed from the
+   program name (set by "Py_SetProgramName()" above) and some
+   environment variables. The returned string consists of a series of
+   directory names separated by a platform dependent delimiter
+   character.  The delimiter character is "':'" on Unix and macOS,
+   "';'" on Windows.  The returned string points into static storage;
+   the caller should not modify its value.  The list "sys.path" is
+   initialized with this value on interpreter startup; it can be (and
+   usually is) modified later to change the search path for loading
+   modules.
+
+   This function should not be called before "Py_Initialize()",
+   otherwise it returns "NULL".
+
+   Changed in version 3.10: It now returns "NULL" if called before
+   "Py_Initialize()".
+
+void Py_SetPath(const wchar_t*)
+    * Part of the Stable ABI since version 3.7.*
+
+   This API is kept for backward compatibility: setting
+   "PyConfig.module_search_paths" and
+   "PyConfig.module_search_paths_set" should be used instead, see
+   Python Initialization Configuration.
+
+   Set the default module search path.  If this function is called
+   before "Py_Initialize()", then "Py_GetPath()" won't attempt to
+   compute a default search path but uses the one provided instead.
+   This is useful if Python is embedded by an application that has
+   full knowledge of the location of all modules.  The path components
+   should be separated by the platform dependent delimiter character,
+   which is "':'" on Unix and macOS, "';'" on Windows.
+
+   This also causes "sys.executable" to be set to the program full
+   path (see "Py_GetProgramFullPath()") and for "sys.prefix" and
+   "sys.exec_prefix" to be empty.  It is up to the caller to modify
+   these if required after calling "Py_Initialize()".
+
+   Use "Py_DecodeLocale()" to decode a bytes string to get a wchar_*
+   string.
+
+   The path argument is copied internally, so the caller may free it
+   after the call completes.
+
+   Changed in version 3.8: The program full path is now used for
+   "sys.executable", instead of the program name.
+
+   Deprecated since version 3.11.
+
+const char *Py_GetVersion()
+    * Part of the Stable ABI.*
+
+   Return the version of this Python interpreter.  This is a string
+   that looks something like
+
+      "3.0a5+ (py3k:63103M, May 12 2008, 00:53:55) \n[GCC 4.2.3]"
+
+   The first word (up to the first space character) is the current
+   Python version; the first characters are the major and minor
+   version separated by a period.  The returned string points into
+   static storage; the caller should not modify its value.  The value
+   is available to Python code as "sys.version".
+
+   See also the "Py_Version" constant.
+
+const char *Py_GetPlatform()
+    * Part of the Stable ABI.*
+
+   Return the platform identifier for the current platform.  On Unix,
+   this is formed from the "official" name of the operating system,
+   converted to lower case, followed by the major revision number;
+   e.g., for Solaris 2.x, which is also known as SunOS 5.x, the value
+   is "'sunos5'".  On macOS, it is "'darwin'".  On Windows, it is
+   "'win'".  The returned string points into static storage; the
+   caller should not modify its value.  The value is available to
+   Python code as "sys.platform".
+
+const char *Py_GetCopyright()
+    * Part of the Stable ABI.*
+
+   Return the official copyright string for the current Python
+   version, for example
+
+   "'Copyright 1991-1995 Stichting Mathematisch Centrum, Amsterdam'"
+
+   The returned string points into static storage; the caller should
+   not modify its value.  The value is available to Python code as
+   "sys.copyright".
+
+const char *Py_GetCompiler()
+    * Part of the Stable ABI.*
+
+   Return an indication of the compiler used to build the current
+   Python version, in square brackets, for example:
+
+      "[GCC 2.7.2.2]"
+
+   The returned string points into static storage; the caller should
+   not modify its value.  The value is available to Python code as
+   part of the variable "sys.version".
+
+const char *Py_GetBuildInfo()
+    * Part of the Stable ABI.*
+
+   Return information about the sequence number and build date and
+   time  of the current Python interpreter instance, for example
+
+      "#67, Aug  1 1997, 22:34:28"
+
+   The returned string points into static storage; the caller should
+   not modify its value.  The value is available to Python code as
+   part of the variable "sys.version".
+
+void PySys_SetArgvEx(int argc, wchar_t **argv, int updatepath)
+    * Part of the Stable ABI.*
+
+   This API is kept for backward compatibility: setting
+   "PyConfig.argv", "PyConfig.parse_argv" and "PyConfig.safe_path"
+   should be used instead, see Python Initialization Configuration.
+
+   Set "sys.argv" based on *argc* and *argv*.  These parameters are
+   similar to those passed to the program's "main()" function with the
+   difference that the first entry should refer to the script file to
+   be executed rather than the executable hosting the Python
+   interpreter.  If there isn't a script that will be run, the first
+   entry in *argv* can be an empty string.  If this function fails to
+   initialize "sys.argv", a fatal condition is signalled using
+   "Py_FatalError()".
+
+   If *updatepath* is zero, this is all the function does.  If
+   *updatepath* is non-zero, the function also modifies "sys.path"
+   according to the following algorithm:
+
+   * If the name of an existing script is passed in "argv[0]", the
+     absolute path of the directory where the script is located is
+     prepended to "sys.path".
+
+   * Otherwise (that is, if *argc* is "0" or "argv[0]" doesn't point
+     to an existing file name), an empty string is prepended to
+     "sys.path", which is the same as prepending the current working
+     directory (""."").
+
+   Use "Py_DecodeLocale()" to decode a bytes string to get a wchar_*
+   string.
+
+   See also "PyConfig.orig_argv" and "PyConfig.argv" members of the
+   Python Initialization Configuration.
+
+   Note:
+
+     It is recommended that applications embedding the Python
+     interpreter for purposes other than executing a single script
+     pass "0" as *updatepath*, and update "sys.path" themselves if
+     desired. See CVE-2008-5983.On versions before 3.1.3, you can
+     achieve the same effect by manually popping the first "sys.path"
+     element after having called "PySys_SetArgv()", for example using:
+
+        PyRun_SimpleString("import sys; sys.path.pop(0)\n");
+
+   Added in version 3.1.3.
+
+   Deprecated since version 3.11.
+
+void PySys_SetArgv(int argc, wchar_t **argv)
+    * Part of the Stable ABI.*
+
+   This API is kept for backward compatibility: setting
+   "PyConfig.argv" and "PyConfig.parse_argv" should be used instead,
+   see Python Initialization Configuration.
+
+   This function works like "PySys_SetArgvEx()" with *updatepath* set
+   to "1" unless the **python** interpreter was started with the "-I".
+
+   Use "Py_DecodeLocale()" to decode a bytes string to get a wchar_*
+   string.
+
+   See also "PyConfig.orig_argv" and "PyConfig.argv" members of the
+   Python Initialization Configuration.
+
+   Changed in version 3.4: The *updatepath* value depends on "-I".
+
+   Deprecated since version 3.11.
+
+void Py_SetPythonHome(const wchar_t *home)
+    * Part of the Stable ABI.*
+
+   This API is kept for backward compatibility: setting
+   "PyConfig.home" should be used instead, see Python Initialization
+   Configuration.
+
+   Set the default "home" directory, that is, the location of the
+   standard Python libraries.  See "PYTHONHOME" for the meaning of the
+   argument string.
+
+   The argument should point to a zero-terminated character string in
+   static storage whose contents will not change for the duration of
+   the program's execution.  No code in the Python interpreter will
+   change the contents of this storage.
+
+   Use "Py_DecodeLocale()" to decode a bytes string to get a wchar_*
+   string.
+
+   Deprecated since version 3.11.
+
+wchar_t *Py_GetPythonHome()
+    * Part of the Stable ABI.*
+
+   Return the default "home", that is, the value set by a previous
+   call to "Py_SetPythonHome()", or the value of the "PYTHONHOME"
+   environment variable if it is set.
+
+   This function should not be called before "Py_Initialize()",
+   otherwise it returns "NULL".
+
+   Changed in version 3.10: It now returns "NULL" if called before
+   "Py_Initialize()".
+
+
+Thread State and the Global Interpreter Lock
+============================================
+
+The Python interpreter is not fully thread-safe.  In order to support
+multi-threaded Python programs, there's a global lock, called the
+*global interpreter lock* or *GIL*, that must be held by the current
+thread before it can safely access Python objects. Without the lock,
+even the simplest operations could cause problems in a multi-threaded
+program: for example, when two threads simultaneously increment the
+reference count of the same object, the reference count could end up
+being incremented only once instead of twice.
+
+Therefore, the rule exists that only the thread that has acquired the
+*GIL* may operate on Python objects or call Python/C API functions. In
+order to emulate concurrency of execution, the interpreter regularly
+tries to switch threads (see "sys.setswitchinterval()").  The lock is
+also released around potentially blocking I/O operations like reading
+or writing a file, so that other Python threads can run in the
+meantime.
+
+The Python interpreter keeps some thread-specific bookkeeping
+information inside a data structure called "PyThreadState".  There's
+also one global variable pointing to the current "PyThreadState": it
+can be retrieved using "PyThreadState_Get()".
+
+
+Releasing the GIL from extension code
+-------------------------------------
+
+Most extension code manipulating the *GIL* has the following simple
+structure:
+
+   Save the thread state in a local variable.
+   Release the global interpreter lock.
+   ... Do some blocking I/O operation ...
+   Reacquire the global interpreter lock.
+   Restore the thread state from the local variable.
+
+This is so common that a pair of macros exists to simplify it:
+
+   Py_BEGIN_ALLOW_THREADS
+   ... Do some blocking I/O operation ...
+   Py_END_ALLOW_THREADS
+
+The "Py_BEGIN_ALLOW_THREADS" macro opens a new block and declares a
+hidden local variable; the "Py_END_ALLOW_THREADS" macro closes the
+block.
+
+The block above expands to the following code:
+
+   PyThreadState *_save;
+
+   _save = PyEval_SaveThread();
+   ... Do some blocking I/O operation ...
+   PyEval_RestoreThread(_save);
+
+Here is how these functions work: the global interpreter lock is used
+to protect the pointer to the current thread state.  When releasing
+the lock and saving the thread state, the current thread state pointer
+must be retrieved before the lock is released (since another thread
+could immediately acquire the lock and store its own thread state in
+the global variable). Conversely, when acquiring the lock and
+restoring the thread state, the lock must be acquired before storing
+the thread state pointer.
+
+Note:
+
+  Calling system I/O functions is the most common use case for
+  releasing the GIL, but it can also be useful before calling long-
+  running computations which don't need access to Python objects, such
+  as compression or cryptographic functions operating over memory
+  buffers.  For example, the standard "zlib" and "hashlib" modules
+  release the GIL when compressing or hashing data.
+
+
+Non-Python created threads
+--------------------------
+
+When threads are created using the dedicated Python APIs (such as the
+"threading" module), a thread state is automatically associated to
+them and the code showed above is therefore correct.  However, when
+threads are created from C (for example by a third-party library with
+its own thread management), they don't hold the GIL, nor is there a
+thread state structure for them.
+
+If you need to call Python code from these threads (often this will be
+part of a callback API provided by the aforementioned third-party
+library), you must first register these threads with the interpreter
+by creating a thread state data structure, then acquiring the GIL, and
+finally storing their thread state pointer, before you can start using
+the Python/C API.  When you are done, you should reset the thread
+state pointer, release the GIL, and finally free the thread state data
+structure.
+
+The "PyGILState_Ensure()" and "PyGILState_Release()" functions do all
+of the above automatically.  The typical idiom for calling into Python
+from a C thread is:
+
+   PyGILState_STATE gstate;
+   gstate = PyGILState_Ensure();
+
+   /* Perform Python actions here. */
+   result = CallSomeFunction();
+   /* evaluate result or handle exception */
+
+   /* Release the thread. No Python API allowed beyond this point. */
+   PyGILState_Release(gstate);
+
+Note that the "PyGILState_*" functions assume there is only one global
+interpreter (created automatically by "Py_Initialize()").  Python
+supports the creation of additional interpreters (using
+"Py_NewInterpreter()"), but mixing multiple interpreters and the
+"PyGILState_*" API is unsupported.
+
+
+Cautions about fork()
+---------------------
+
+Another important thing to note about threads is their behaviour in
+the face of the C "fork()" call. On most systems with "fork()", after
+a process forks only the thread that issued the fork will exist.  This
+has a concrete impact both on how locks must be handled and on all
+stored state in CPython's runtime.
+
+The fact that only the "current" thread remains means any locks held
+by other threads will never be released. Python solves this for
+"os.fork()" by acquiring the locks it uses internally before the fork,
+and releasing them afterwards. In addition, it resets any Lock Objects
+in the child. When extending or embedding Python, there is no way to
+inform Python of additional (non-Python) locks that need to be
+acquired before or reset after a fork. OS facilities such as
+"pthread_atfork()" would need to be used to accomplish the same thing.
+Additionally, when extending or embedding Python, calling "fork()"
+directly rather than through "os.fork()" (and returning to or calling
+into Python) may result in a deadlock by one of Python's internal
+locks being held by a thread that is defunct after the fork.
+"PyOS_AfterFork_Child()" tries to reset the necessary locks, but is
+not always able to.
+
+The fact that all other threads go away also means that CPython's
+runtime state there must be cleaned up properly, which "os.fork()"
+does.  This means finalizing all other "PyThreadState" objects
+belonging to the current interpreter and all other
+"PyInterpreterState" objects.  Due to this and the special nature of
+the "main" interpreter, "fork()" should only be called in that
+interpreter's "main" thread, where the CPython global runtime was
+originally initialized. The only exception is if "exec()" will be
+called immediately after.
+
+
+High-level API
+--------------
+
+These are the most commonly used types and functions when writing C
+extension code, or when embedding the Python interpreter:
+
+type PyInterpreterState
+    * Part of the Limited API (as an opaque struct).*
+
+   This data structure represents the state shared by a number of
+   cooperating threads.  Threads belonging to the same interpreter
+   share their module administration and a few other internal items.
+   There are no public members in this structure.
+
+   Threads belonging to different interpreters initially share
+   nothing, except process state like available memory, open file
+   descriptors and such.  The global interpreter lock is also shared
+   by all threads, regardless of to which interpreter they belong.
+
+type PyThreadState
+    * Part of the Limited API (as an opaque struct).*
+
+   This data structure represents the state of a single thread.  The
+   only public data member is:
+
+   PyInterpreterState *interp
+
+      This thread's interpreter state.
+
+void PyEval_InitThreads()
+    * Part of the Stable ABI.*
+
+   Deprecated function which does nothing.
+
+   In Python 3.6 and older, this function created the GIL if it didn't
+   exist.
+
+   Changed in version 3.9: The function now does nothing.
+
+   Changed in version 3.7: This function is now called by
+   "Py_Initialize()", so you don't have to call it yourself anymore.
+
+   Changed in version 3.2: This function cannot be called before
+   "Py_Initialize()" anymore.
+
+   Deprecated since version 3.9.
+
+int PyEval_ThreadsInitialized()
+    * Part of the Stable ABI.*
+
+   Returns a non-zero value if "PyEval_InitThreads()" has been called.
+   This function can be called without holding the GIL, and therefore
+   can be used to avoid calls to the locking API when running single-
+   threaded.
+
+   Changed in version 3.7: The *GIL* is now initialized by
+   "Py_Initialize()".
+
+   Deprecated since version 3.9.
+
+PyThreadState *PyEval_SaveThread()
+    * Part of the Stable ABI.*
+
+   Release the global interpreter lock (if it has been created) and
+   reset the thread state to "NULL", returning the previous thread
+   state (which is not "NULL").  If the lock has been created, the
+   current thread must have acquired it.
+
+void PyEval_RestoreThread(PyThreadState *tstate)
+    * Part of the Stable ABI.*
+
+   Acquire the global interpreter lock (if it has been created) and
+   set the thread state to *tstate*, which must not be "NULL".  If the
+   lock has been created, the current thread must not have acquired
+   it, otherwise deadlock ensues.
+
+   Note:
+
+     Calling this function from a thread when the runtime is
+     finalizing will terminate the thread, even if the thread was not
+     created by Python. You can use "_Py_IsFinalizing()" or
+     "sys.is_finalizing()" to check if the interpreter is in process
+     of being finalized before calling this function to avoid unwanted
+     termination.
+
+PyThreadState *PyThreadState_Get()
+    * Part of the Stable ABI.*
+
+   Return the current thread state.  The global interpreter lock must
+   be held. When the current thread state is "NULL", this issues a
+   fatal error (so that the caller needn't check for "NULL").
+
+PyThreadState *PyThreadState_Swap(PyThreadState *tstate)
+    * Part of the Stable ABI.*
+
+   Swap the current thread state with the thread state given by the
+   argument *tstate*, which may be "NULL".  The global interpreter
+   lock must be held and is not released.
+
+The following functions use thread-local storage, and are not
+compatible with sub-interpreters:
+
+PyGILState_STATE PyGILState_Ensure()
+    * Part of the Stable ABI.*
+
+   Ensure that the current thread is ready to call the Python C API
+   regardless of the current state of Python, or of the global
+   interpreter lock. This may be called as many times as desired by a
+   thread as long as each call is matched with a call to
+   "PyGILState_Release()". In general, other thread-related APIs may
+   be used between "PyGILState_Ensure()" and "PyGILState_Release()"
+   calls as long as the thread state is restored to its previous state
+   before the Release().  For example, normal usage of the
+   "Py_BEGIN_ALLOW_THREADS" and "Py_END_ALLOW_THREADS" macros is
+   acceptable.
+
+   The return value is an opaque "handle" to the thread state when
+   "PyGILState_Ensure()" was called, and must be passed to
+   "PyGILState_Release()" to ensure Python is left in the same state.
+   Even though recursive calls are allowed, these handles *cannot* be
+   shared - each unique call to "PyGILState_Ensure()" must save the
+   handle for its call to "PyGILState_Release()".
+
+   When the function returns, the current thread will hold the GIL and
+   be able to call arbitrary Python code.  Failure is a fatal error.
+
+   Note:
+
+     Calling this function from a thread when the runtime is
+     finalizing will terminate the thread, even if the thread was not
+     created by Python. You can use "_Py_IsFinalizing()" or
+     "sys.is_finalizing()" to check if the interpreter is in process
+     of being finalized before calling this function to avoid unwanted
+     termination.
+
+void PyGILState_Release(PyGILState_STATE)
+    * Part of the Stable ABI.*
+
+   Release any resources previously acquired.  After this call,
+   Python's state will be the same as it was prior to the
+   corresponding "PyGILState_Ensure()" call (but generally this state
+   will be unknown to the caller, hence the use of the GILState API).
+
+   Every call to "PyGILState_Ensure()" must be matched by a call to
+   "PyGILState_Release()" on the same thread.
+
+PyThreadState *PyGILState_GetThisThreadState()
+    * Part of the Stable ABI.*
+
+   Get the current thread state for this thread.  May return "NULL" if
+   no GILState API has been used on the current thread.  Note that the
+   main thread always has such a thread-state, even if no auto-thread-
+   state call has been made on the main thread.  This is mainly a
+   helper/diagnostic function.
+
+int PyGILState_Check()
+
+   Return "1" if the current thread is holding the GIL and "0"
+   otherwise. This function can be called from any thread at any time.
+   Only if it has had its Python thread state initialized and
+   currently is holding the GIL will it return "1". This is mainly a
+   helper/diagnostic function.  It can be useful for example in
+   callback contexts or memory allocation functions when knowing that
+   the GIL is locked can allow the caller to perform sensitive actions
+   or otherwise behave differently.
+
+   Added in version 3.4.
+
+The following macros are normally used without a trailing semicolon;
+look for example usage in the Python source distribution.
+
+Py_BEGIN_ALLOW_THREADS
+    * Part of the Stable ABI.*
+
+   This macro expands to "{ PyThreadState *_save; _save =
+   PyEval_SaveThread();". Note that it contains an opening brace; it
+   must be matched with a following "Py_END_ALLOW_THREADS" macro.  See
+   above for further discussion of this macro.
+
+Py_END_ALLOW_THREADS
+    * Part of the Stable ABI.*
+
+   This macro expands to "PyEval_RestoreThread(_save); }". Note that
+   it contains a closing brace; it must be matched with an earlier
+   "Py_BEGIN_ALLOW_THREADS" macro.  See above for further discussion
+   of this macro.
+
+Py_BLOCK_THREADS
+    * Part of the Stable ABI.*
+
+   This macro expands to "PyEval_RestoreThread(_save);": it is
+   equivalent to "Py_END_ALLOW_THREADS" without the closing brace.
+
+Py_UNBLOCK_THREADS
+    * Part of the Stable ABI.*
+
+   This macro expands to "_save = PyEval_SaveThread();": it is
+   equivalent to "Py_BEGIN_ALLOW_THREADS" without the opening brace
+   and variable declaration.
+
+
+Low-level API
+-------------
+
+All of the following functions must be called after "Py_Initialize()".
+
+Changed in version 3.7: "Py_Initialize()" now initializes the *GIL*.
+
+PyInterpreterState *PyInterpreterState_New()
+    * Part of the Stable ABI.*
+
+   Create a new interpreter state object.  The global interpreter lock
+   need not be held, but may be held if it is necessary to serialize
+   calls to this function.
+
+   Raises an auditing event "cpython.PyInterpreterState_New" with no
+   arguments.
+
+void PyInterpreterState_Clear(PyInterpreterState *interp)
+    * Part of the Stable ABI.*
+
+   Reset all information in an interpreter state object.  The global
+   interpreter lock must be held.
+
+   Raises an auditing event "cpython.PyInterpreterState_Clear" with no
+   arguments.
+
+void PyInterpreterState_Delete(PyInterpreterState *interp)
+    * Part of the Stable ABI.*
+
+   Destroy an interpreter state object.  The global interpreter lock
+   need not be held.  The interpreter state must have been reset with
+   a previous call to "PyInterpreterState_Clear()".
+
+PyThreadState *PyThreadState_New(PyInterpreterState *interp)
+    * Part of the Stable ABI.*
+
+   Create a new thread state object belonging to the given interpreter
+   object. The global interpreter lock need not be held, but may be
+   held if it is necessary to serialize calls to this function.
+
+void PyThreadState_Clear(PyThreadState *tstate)
+    * Part of the Stable ABI.*
+
+   Reset all information in a thread state object.  The global
+   interpreter lock must be held.
+
+   Changed in version 3.9: This function now calls the
+   "PyThreadState.on_delete" callback. Previously, that happened in
+   "PyThreadState_Delete()".
+
+void PyThreadState_Delete(PyThreadState *tstate)
+    * Part of the Stable ABI.*
+
+   Destroy a thread state object.  The global interpreter lock need
+   not be held. The thread state must have been reset with a previous
+   call to "PyThreadState_Clear()".
+
+void PyThreadState_DeleteCurrent(void)
+
+   Destroy the current thread state and release the global interpreter
+   lock. Like "PyThreadState_Delete()", the global interpreter lock
+   need not be held. The thread state must have been reset with a
+   previous call to "PyThreadState_Clear()".
+
+PyFrameObject *PyThreadState_GetFrame(PyThreadState *tstate)
+    * Part of the Stable ABI since version 3.10.*
+
+   Get the current frame of the Python thread state *tstate*.
+
+   Return a *strong reference*. Return "NULL" if no frame is currently
+   executing.
+
+   See also "PyEval_GetFrame()".
+
+   *tstate* must not be "NULL".
+
+   Added in version 3.9.
+
+uint64_t PyThreadState_GetID(PyThreadState *tstate)
+    * Part of the Stable ABI since version 3.10.*
+
+   Get the unique thread state identifier of the Python thread state
+   *tstate*.
+
+   *tstate* must not be "NULL".
+
+   Added in version 3.9.
+
+PyInterpreterState *PyThreadState_GetInterpreter(PyThreadState *tstate)
+    * Part of the Stable ABI since version 3.10.*
+
+   Get the interpreter of the Python thread state *tstate*.
+
+   *tstate* must not be "NULL".
+
+   Added in version 3.9.
+
+void PyThreadState_EnterTracing(PyThreadState *tstate)
+
+   Suspend tracing and profiling in the Python thread state *tstate*.
+
+   Resume them using the "PyThreadState_LeaveTracing()" function.
+
+   Added in version 3.11.
+
+void PyThreadState_LeaveTracing(PyThreadState *tstate)
+
+   Resume tracing and profiling in the Python thread state *tstate*
+   suspended by the "PyThreadState_EnterTracing()" function.
+
+   See also "PyEval_SetTrace()" and "PyEval_SetProfile()" functions.
+
+   Added in version 3.11.
+
+PyInterpreterState *PyInterpreterState_Get(void)
+    * Part of the Stable ABI since version 3.9.*
+
+   Get the current interpreter.
+
+   Issue a fatal error if there no current Python thread state or no
+   current interpreter. It cannot return NULL.
+
+   The caller must hold the GIL.
+
+   Added in version 3.9.
+
+int64_t PyInterpreterState_GetID(PyInterpreterState *interp)
+    * Part of the Stable ABI since version 3.7.*
+
+   Return the interpreter's unique ID.  If there was any error in
+   doing so then "-1" is returned and an error is set.
+
+   The caller must hold the GIL.
+
+   Added in version 3.7.
+
+PyObject *PyInterpreterState_GetDict(PyInterpreterState *interp)
+    * Part of the Stable ABI since version 3.8.*
+
+   Return a dictionary in which interpreter-specific data may be
+   stored. If this function returns "NULL" then no exception has been
+   raised and the caller should assume no interpreter-specific dict is
+   available.
+
+   This is not a replacement for "PyModule_GetState()", which
+   extensions should use to store interpreter-specific state
+   information.
+
+   Added in version 3.8.
+
+typedef PyObject *(*_PyFrameEvalFunction)(PyThreadState *tstate, _PyInterpreterFrame *frame, int throwflag)
+
+   Type of a frame evaluation function.
+
+   The *throwflag* parameter is used by the "throw()" method of
+   generators: if non-zero, handle the current exception.
+
+   Changed in version 3.9: The function now takes a *tstate*
+   parameter.
+
+   Changed in version 3.11: The *frame* parameter changed from
+   "PyFrameObject*" to "_PyInterpreterFrame*".
+
+_PyFrameEvalFunction _PyInterpreterState_GetEvalFrameFunc(PyInterpreterState *interp)
+
+   Get the frame evaluation function.
+
+   See the **PEP 523** "Adding a frame evaluation API to CPython".
+
+   Added in version 3.9.
+
+void _PyInterpreterState_SetEvalFrameFunc(PyInterpreterState *interp, _PyFrameEvalFunction eval_frame)
+
+   Set the frame evaluation function.
+
+   See the **PEP 523** "Adding a frame evaluation API to CPython".
+
+   Added in version 3.9.
+
+PyObject *PyThreadState_GetDict()
+    *Return value: Borrowed reference.** Part of the Stable ABI.*
+
+   Return a dictionary in which extensions can store thread-specific
+   state information.  Each extension should use a unique key to use
+   to store state in the dictionary.  It is okay to call this function
+   when no current thread state is available. If this function returns
+   "NULL", no exception has been raised and the caller should assume
+   no current thread state is available.
+
+int PyThreadState_SetAsyncExc(unsigned long id, PyObject *exc)
+    * Part of the Stable ABI.*
+
+   Asynchronously raise an exception in a thread. The *id* argument is
+   the thread id of the target thread; *exc* is the exception object
+   to be raised. This function does not steal any references to *exc*.
+   To prevent naive misuse, you must write your own C extension to
+   call this.  Must be called with the GIL held. Returns the number of
+   thread states modified; this is normally one, but will be zero if
+   the thread id isn't found.  If *exc* is "NULL", the pending
+   exception (if any) for the thread is cleared. This raises no
+   exceptions.
+
+   Changed in version 3.7: The type of the *id* parameter changed from
+   long to unsigned long.
+
+void PyEval_AcquireThread(PyThreadState *tstate)
+    * Part of the Stable ABI.*
+
+   Acquire the global interpreter lock and set the current thread
+   state to *tstate*, which must not be "NULL".  The lock must have
+   been created earlier. If this thread already has the lock, deadlock
+   ensues.
+
+   Note:
+
+     Calling this function from a thread when the runtime is
+     finalizing will terminate the thread, even if the thread was not
+     created by Python. You can use "_Py_IsFinalizing()" or
+     "sys.is_finalizing()" to check if the interpreter is in process
+     of being finalized before calling this function to avoid unwanted
+     termination.
+
+   Changed in version 3.8: Updated to be consistent with
+   "PyEval_RestoreThread()", "Py_END_ALLOW_THREADS()", and
+   "PyGILState_Ensure()", and terminate the current thread if called
+   while the interpreter is finalizing.
+
+   "PyEval_RestoreThread()" is a higher-level function which is always
+   available (even when threads have not been initialized).
+
+void PyEval_ReleaseThread(PyThreadState *tstate)
+    * Part of the Stable ABI.*
+
+   Reset the current thread state to "NULL" and release the global
+   interpreter lock.  The lock must have been created earlier and must
+   be held by the current thread.  The *tstate* argument, which must
+   not be "NULL", is only used to check that it represents the current
+   thread state --- if it isn't, a fatal error is reported.
+
+   "PyEval_SaveThread()" is a higher-level function which is always
+   available (even when threads have not been initialized).
+
+void PyEval_AcquireLock()
+    * Part of the Stable ABI.*
+
+   Acquire the global interpreter lock.  The lock must have been
+   created earlier. If this thread already has the lock, a deadlock
+   ensues.
+
+   Deprecated since version 3.2: This function does not update the
+   current thread state.  Please use "PyEval_RestoreThread()" or
+   "PyEval_AcquireThread()" instead.
+
+   Note:
+
+     Calling this function from a thread when the runtime is
+     finalizing will terminate the thread, even if the thread was not
+     created by Python. You can use "_Py_IsFinalizing()" or
+     "sys.is_finalizing()" to check if the interpreter is in process
+     of being finalized before calling this function to avoid unwanted
+     termination.
+
+   Changed in version 3.8: Updated to be consistent with
+   "PyEval_RestoreThread()", "Py_END_ALLOW_THREADS()", and
+   "PyGILState_Ensure()", and terminate the current thread if called
+   while the interpreter is finalizing.
+
+void PyEval_ReleaseLock()
+    * Part of the Stable ABI.*
+
+   Release the global interpreter lock.  The lock must have been
+   created earlier.
+
+   Deprecated since version 3.2: This function does not update the
+   current thread state.  Please use "PyEval_SaveThread()" or
+   "PyEval_ReleaseThread()" instead.
+
+
+Sub-interpreter support
+=======================
+
+While in most uses, you will only embed a single Python interpreter,
+there are cases where you need to create several independent
+interpreters in the same process and perhaps even in the same thread.
+Sub-interpreters allow you to do that.
+
+The "main" interpreter is the first one created when the runtime
+initializes. It is usually the only Python interpreter in a process.
+Unlike sub-interpreters, the main interpreter has unique process-
+global responsibilities like signal handling.  It is also responsible
+for execution during runtime initialization and is usually the active
+interpreter during runtime finalization.  The
+"PyInterpreterState_Main()" function returns a pointer to its state.
+
+You can switch between sub-interpreters using the
+"PyThreadState_Swap()" function. You can create and destroy them using
+the following functions:
+
+type PyInterpreterConfig
+
+   Structure containing most parameters to configure a sub-
+   interpreter. Its values are used only in
+   "Py_NewInterpreterFromConfig()" and never modified by the runtime.
+
+   Added in version 3.12.
+
+   Structure fields:
+
+   int use_main_obmalloc
+
+      If this is "0" then the sub-interpreter will use its own
+      "object" allocator state. Otherwise it will use (share) the main
+      interpreter's.
+
+      If this is "0" then "check_multi_interp_extensions" must be "1"
+      (non-zero). If this is "1" then "gil" must not be
+      "PyInterpreterConfig_OWN_GIL".
+
+   int allow_fork
+
+      If this is "0" then the runtime will not support forking the
+      process in any thread where the sub-interpreter is currently
+      active. Otherwise fork is unrestricted.
+
+      Note that the "subprocess" module still works when fork is
+      disallowed.
+
+   int allow_exec
+
+      If this is "0" then the runtime will not support replacing the
+      current process via exec (e.g. "os.execv()") in any thread where
+      the sub-interpreter is currently active. Otherwise exec is
+      unrestricted.
+
+      Note that the "subprocess" module still works when exec is
+      disallowed.
+
+   int allow_threads
+
+      If this is "0" then the sub-interpreter's "threading" module
+      won't create threads. Otherwise threads are allowed.
+
+   int allow_daemon_threads
+
+      If this is "0" then the sub-interpreter's "threading" module
+      won't create daemon threads. Otherwise daemon threads are
+      allowed (as long as "allow_threads" is non-zero).
+
+   int check_multi_interp_extensions
+
+      If this is "0" then all extension modules may be imported,
+      including legacy (single-phase init) modules, in any thread
+      where the sub-interpreter is currently active. Otherwise only
+      multi-phase init extension modules (see **PEP 489**) may be
+      imported. (Also see "Py_mod_multiple_interpreters".)
+
+      This must be "1" (non-zero) if "use_main_obmalloc" is "0".
+
+   int gil
+
+      This determines the operation of the GIL for the sub-
+      interpreter. It may be one of the following:
+
+      PyInterpreterConfig_DEFAULT_GIL
+
+         Use the default selection ("PyInterpreterConfig_SHARED_GIL").
+
+      PyInterpreterConfig_SHARED_GIL
+
+         Use (share) the main interpreter's GIL.
+
+      PyInterpreterConfig_OWN_GIL
+
+         Use the sub-interpreter's own GIL.
+
+      If this is "PyInterpreterConfig_OWN_GIL" then
+      "PyInterpreterConfig.use_main_obmalloc" must be "0".
+
+PyStatus Py_NewInterpreterFromConfig(PyThreadState **tstate_p, const PyInterpreterConfig *config)
+
+   Create a new sub-interpreter.  This is an (almost) totally separate
+   environment for the execution of Python code.  In particular, the
+   new interpreter has separate, independent versions of all imported
+   modules, including the fundamental modules "builtins", "__main__"
+   and "sys".  The table of loaded modules ("sys.modules") and the
+   module search path ("sys.path") are also separate.  The new
+   environment has no "sys.argv" variable.  It has new standard I/O
+   stream file objects "sys.stdin", "sys.stdout" and "sys.stderr"
+   (however these refer to the same underlying file descriptors).
+
+   The given *config* controls the options with which the interpreter
+   is initialized.
+
+   Upon success, *tstate_p* will be set to the first thread state
+   created in the new sub-interpreter.  This thread state is made in
+   the current thread state. Note that no actual thread is created;
+   see the discussion of thread states below.  If creation of the new
+   interpreter is unsuccessful, *tstate_p* is set to "NULL"; no
+   exception is set since the exception state is stored in the current
+   thread state and there may not be a current thread state.
+
+   Like all other Python/C API functions, the global interpreter lock
+   must be held before calling this function and is still held when it
+   returns.  Likewise a current thread state must be set on entry.  On
+   success, the returned thread state will be set as current.  If the
+   sub-interpreter is created with its own GIL then the GIL of the
+   calling interpreter will be released.  When the function returns,
+   the new interpreter's GIL will be held by the current thread and
+   the previously interpreter's GIL will remain released here.
+
+   Added in version 3.12.
+
+   Sub-interpreters are most effective when isolated from each other,
+   with certain functionality restricted:
+
+      PyInterpreterConfig config = {
+          .use_main_obmalloc = 0,
+          .allow_fork = 0,
+          .allow_exec = 0,
+          .allow_threads = 1,
+          .allow_daemon_threads = 0,
+          .check_multi_interp_extensions = 1,
+          .gil = PyInterpreterConfig_OWN_GIL,
+      };
+      PyThreadState *tstate = Py_NewInterpreterFromConfig(&config);
+
+   Note that the config is used only briefly and does not get
+   modified. During initialization the config's values are converted
+   into various "PyInterpreterState" values.  A read-only copy of the
+   config may be stored internally on the "PyInterpreterState".
+
+   Extension modules are shared between (sub-)interpreters as follows:
+
+   * For modules using multi-phase initialization, e.g.
+     "PyModule_FromDefAndSpec()", a separate module object is created
+     and initialized for each interpreter. Only C-level static and
+     global variables are shared between these module objects.
+
+   * For modules using single-phase initialization, e.g.
+     "PyModule_Create()", the first time a particular extension is
+     imported, it is initialized normally, and a (shallow) copy of its
+     module's dictionary is squirreled away. When the same extension
+     is imported by another (sub-)interpreter, a new module is
+     initialized and filled with the contents of this copy; the
+     extension's "init" function is not called. Objects in the
+     module's dictionary thus end up shared across (sub-)interpreters,
+     which might cause unwanted behavior (see Bugs and caveats below).
+
+     Note that this is different from what happens when an extension
+     is imported after the interpreter has been completely re-
+     initialized by calling "Py_FinalizeEx()" and "Py_Initialize()";
+     in that case, the extension's "initmodule" function *is* called
+     again. As with multi-phase initialization, this means that only
+     C-level static and global variables are shared between these
+     modules.
+
+PyThreadState *Py_NewInterpreter(void)
+    * Part of the Stable ABI.*
+
+   Create a new sub-interpreter.  This is essentially just a wrapper
+   around "Py_NewInterpreterFromConfig()" with a config that preserves
+   the existing behavior.  The result is an unisolated sub-interpreter
+   that shares the main interpreter's GIL, allows fork/exec, allows
+   daemon threads, and allows single-phase init modules.
+
+void Py_EndInterpreter(PyThreadState *tstate)
+    * Part of the Stable ABI.*
+
+   Destroy the (sub-)interpreter represented by the given thread
+   state. The given thread state must be the current thread state.
+   See the discussion of thread states below.  When the call returns,
+   the current thread state is "NULL".  All thread states associated
+   with this interpreter are destroyed.  The global interpreter lock
+   used by the target interpreter must be held before calling this
+   function.  No GIL is held when it returns.
+
+   "Py_FinalizeEx()" will destroy all sub-interpreters that haven't
+   been explicitly destroyed at that point.
+
+
+A Per-Interpreter GIL
+---------------------
+
+Using "Py_NewInterpreterFromConfig()" you can create a sub-interpreter
+that is completely isolated from other interpreters, including having
+its own GIL.  The most important benefit of this isolation is that
+such an interpreter can execute Python code without being blocked by
+other interpreters or blocking any others.  Thus a single Python
+process can truly take advantage of multiple CPU cores when running
+Python code.  The isolation also encourages a different approach to
+concurrency than that of just using threads. (See **PEP 554**.)
+
+Using an isolated interpreter requires vigilance in preserving that
+isolation.  That especially means not sharing any objects or mutable
+state without guarantees about thread-safety.  Even objects that are
+otherwise immutable (e.g. "None", "(1, 5)") can't normally be shared
+because of the refcount.  One simple but less-efficient approach
+around this is to use a global lock around all use of some state (or
+object). Alternately, effectively immutable objects (like integers or
+strings) can be made safe in spite of their refcounts by making them
+"immortal". In fact, this has been done for the builtin singletons,
+small integers, and a number of other builtin objects.
+
+If you preserve isolation then you will have access to proper multi-
+core computing without the complications that come with free-
+threading. Failure to preserve isolation will expose you to the full
+consequences of free-threading, including races and hard-to-debug
+crashes.
+
+Aside from that, one of the main challenges of using multiple isolated
+interpreters is how to communicate between them safely (not break
+isolation) and efficiently.  The runtime and stdlib do not provide any
+standard approach to this yet.  A future stdlib module would help
+mitigate the effort of preserving isolation and expose effective tools
+for communicating (and sharing) data between interpreters.
+
+Added in version 3.12.
+
+
+Bugs and caveats
+----------------
+
+Because sub-interpreters (and the main interpreter) are part of the
+same process, the insulation between them isn't perfect --- for
+example, using low-level file operations like  "os.close()" they can
+(accidentally or maliciously) affect each other's open files.  Because
+of the way extensions are shared between (sub-)interpreters, some
+extensions may not work properly; this is especially likely when using
+single-phase initialization or (static) global variables. It is
+possible to insert objects created in one sub-interpreter into a
+namespace of another (sub-)interpreter; this should be avoided if
+possible.
+
+Special care should be taken to avoid sharing user-defined functions,
+methods, instances or classes between sub-interpreters, since import
+operations executed by such objects may affect the wrong
+(sub-)interpreter's dictionary of loaded modules. It is equally
+important to avoid sharing objects from which the above are reachable.
+
+Also note that combining this functionality with "PyGILState_*" APIs
+is delicate, because these APIs assume a bijection between Python
+thread states and OS-level threads, an assumption broken by the
+presence of sub-interpreters. It is highly recommended that you don't
+switch sub-interpreters between a pair of matching
+"PyGILState_Ensure()" and "PyGILState_Release()" calls. Furthermore,
+extensions (such as "ctypes") using these APIs to allow calling of
+Python code from non-Python created threads will probably be broken
+when using sub-interpreters.
+
+
+Asynchronous Notifications
+==========================
+
+A mechanism is provided to make asynchronous notifications to the main
+interpreter thread.  These notifications take the form of a function
+pointer and a void pointer argument.
+
+int Py_AddPendingCall(int (*func)(void*), void *arg)
+    * Part of the Stable ABI.*
+
+   Schedule a function to be called from the main interpreter thread.
+   On success, "0" is returned and *func* is queued for being called
+   in the main thread.  On failure, "-1" is returned without setting
+   any exception.
+
+   When successfully queued, *func* will be *eventually* called from
+   the main interpreter thread with the argument *arg*.  It will be
+   called asynchronously with respect to normally running Python code,
+   but with both these conditions met:
+
+   * on a *bytecode* boundary;
+
+   * with the main thread holding the *global interpreter lock*
+     (*func* can therefore use the full C API).
+
+   *func* must return "0" on success, or "-1" on failure with an
+   exception set.  *func* won't be interrupted to perform another
+   asynchronous notification recursively, but it can still be
+   interrupted to switch threads if the global interpreter lock is
+   released.
+
+   This function doesn't need a current thread state to run, and it
+   doesn't need the global interpreter lock.
+
+   To call this function in a subinterpreter, the caller must hold the
+   GIL. Otherwise, the function *func* can be scheduled to be called
+   from the wrong interpreter.
+
+   Warning:
+
+     This is a low-level function, only useful for very special cases.
+     There is no guarantee that *func* will be called as quick as
+     possible.  If the main thread is busy executing a system call,
+     *func* won't be called before the system call returns.  This
+     function is generally **not** suitable for calling Python code
+     from arbitrary C threads.  Instead, use the PyGILState API.
+
+   Added in version 3.1.
+
+   Changed in version 3.9: If this function is called in a
+   subinterpreter, the function *func* is now scheduled to be called
+   from the subinterpreter, rather than being called from the main
+   interpreter. Each subinterpreter now has its own list of scheduled
+   calls.
+
+
+Profiling and Tracing
+=====================
+
+The Python interpreter provides some low-level support for attaching
+profiling and execution tracing facilities.  These are used for
+profiling, debugging, and coverage analysis tools.
+
+This C interface allows the profiling or tracing code to avoid the
+overhead of calling through Python-level callable objects, making a
+direct C function call instead.  The essential attributes of the
+facility have not changed; the interface allows trace functions to be
+installed per-thread, and the basic events reported to the trace
+function are the same as had been reported to the Python-level trace
+functions in previous versions.
+
+typedef int (*Py_tracefunc)(PyObject *obj, PyFrameObject *frame, int what, PyObject *arg)
+
+   The type of the trace function registered using
+   "PyEval_SetProfile()" and "PyEval_SetTrace()". The first parameter
+   is the object passed to the registration function as *obj*, *frame*
+   is the frame object to which the event pertains, *what* is one of
+   the constants "PyTrace_CALL", "PyTrace_EXCEPTION", "PyTrace_LINE",
+   "PyTrace_RETURN", "PyTrace_C_CALL", "PyTrace_C_EXCEPTION",
+   "PyTrace_C_RETURN", or "PyTrace_OPCODE", and *arg* depends on the
+   value of *what*:
+
+   +---------------------------------+------------------------------------------+
+   | Value of *what*                 | Meaning of *arg*                         |
+   |=================================|==========================================|
+   | "PyTrace_CALL"                  | Always "Py_None".                        |
+   +---------------------------------+------------------------------------------+
+   | "PyTrace_EXCEPTION"             | Exception information as returned by     |
+   |                                 | "sys.exc_info()".                        |
+   +---------------------------------+------------------------------------------+
+   | "PyTrace_LINE"                  | Always "Py_None".                        |
+   +---------------------------------+------------------------------------------+
+   | "PyTrace_RETURN"                | Value being returned to the caller, or   |
+   |                                 | "NULL" if caused by an exception.        |
+   +---------------------------------+------------------------------------------+
+   | "PyTrace_C_CALL"                | Function object being called.            |
+   +---------------------------------+------------------------------------------+
+   | "PyTrace_C_EXCEPTION"           | Function object being called.            |
+   +---------------------------------+------------------------------------------+
+   | "PyTrace_C_RETURN"              | Function object being called.            |
+   +---------------------------------+------------------------------------------+
+   | "PyTrace_OPCODE"                | Always "Py_None".                        |
+   +---------------------------------+------------------------------------------+
+
+int PyTrace_CALL
+
+   The value of the *what* parameter to a "Py_tracefunc" function when
+   a new call to a function or method is being reported, or a new
+   entry into a generator. Note that the creation of the iterator for
+   a generator function is not reported as there is no control
+   transfer to the Python bytecode in the corresponding frame.
+
+int PyTrace_EXCEPTION
+
+   The value of the *what* parameter to a "Py_tracefunc" function when
+   an exception has been raised.  The callback function is called with
+   this value for *what* when after any bytecode is processed after
+   which the exception becomes set within the frame being executed.
+   The effect of this is that as exception propagation causes the
+   Python stack to unwind, the callback is called upon return to each
+   frame as the exception propagates.  Only trace functions receives
+   these events; they are not needed by the profiler.
+
+int PyTrace_LINE
+
+   The value passed as the *what* parameter to a "Py_tracefunc"
+   function (but not a profiling function) when a line-number event is
+   being reported. It may be disabled for a frame by setting
+   "f_trace_lines" to *0* on that frame.
+
+int PyTrace_RETURN
+
+   The value for the *what* parameter to "Py_tracefunc" functions when
+   a call is about to return.
+
+int PyTrace_C_CALL
+
+   The value for the *what* parameter to "Py_tracefunc" functions when
+   a C function is about to be called.
+
+int PyTrace_C_EXCEPTION
+
+   The value for the *what* parameter to "Py_tracefunc" functions when
+   a C function has raised an exception.
+
+int PyTrace_C_RETURN
+
+   The value for the *what* parameter to "Py_tracefunc" functions when
+   a C function has returned.
+
+int PyTrace_OPCODE
+
+   The value for the *what* parameter to "Py_tracefunc" functions (but
+   not profiling functions) when a new opcode is about to be executed.
+   This event is not emitted by default: it must be explicitly
+   requested by setting "f_trace_opcodes" to *1* on the frame.
+
+void PyEval_SetProfile(Py_tracefunc func, PyObject *obj)
+
+   Set the profiler function to *func*.  The *obj* parameter is passed
+   to the function as its first parameter, and may be any Python
+   object, or "NULL".  If the profile function needs to maintain
+   state, using a different value for *obj* for each thread provides a
+   convenient and thread-safe place to store it.  The profile function
+   is called for all monitored events except "PyTrace_LINE"
+   "PyTrace_OPCODE" and "PyTrace_EXCEPTION".
+
+   See also the "sys.setprofile()" function.
+
+   The caller must hold the *GIL*.
+
+void PyEval_SetProfileAllThreads(Py_tracefunc func, PyObject *obj)
+
+   Like "PyEval_SetProfile()" but sets the profile function in all
+   running threads belonging to the current interpreter instead of the
+   setting it only on the current thread.
+
+   The caller must hold the *GIL*.
+
+   As "PyEval_SetProfile()", this function ignores any exceptions
+   raised while setting the profile functions in all threads.
+
+Added in version 3.12.
+
+void PyEval_SetTrace(Py_tracefunc func, PyObject *obj)
+
+   Set the tracing function to *func*.  This is similar to
+   "PyEval_SetProfile()", except the tracing function does receive
+   line-number events and per-opcode events, but does not receive any
+   event related to C function objects being called.  Any trace
+   function registered using "PyEval_SetTrace()" will not receive
+   "PyTrace_C_CALL", "PyTrace_C_EXCEPTION" or "PyTrace_C_RETURN" as a
+   value for the *what* parameter.
+
+   See also the "sys.settrace()" function.
+
+   The caller must hold the *GIL*.
+
+void PyEval_SetTraceAllThreads(Py_tracefunc func, PyObject *obj)
+
+   Like "PyEval_SetTrace()" but sets the tracing function in all
+   running threads belonging to the current interpreter instead of the
+   setting it only on the current thread.
+
+   The caller must hold the *GIL*.
+
+   As "PyEval_SetTrace()", this function ignores any exceptions raised
+   while setting the trace functions in all threads.
+
+Added in version 3.12.
+
+
+Advanced Debugger Support
+=========================
+
+These functions are only intended to be used by advanced debugging
+tools.
+
+PyInterpreterState *PyInterpreterState_Head()
+
+   Return the interpreter state object at the head of the list of all
+   such objects.
+
+PyInterpreterState *PyInterpreterState_Main()
+
+   Return the main interpreter state object.
+
+PyInterpreterState *PyInterpreterState_Next(PyInterpreterState *interp)
+
+   Return the next interpreter state object after *interp* from the
+   list of all such objects.
+
+PyThreadState *PyInterpreterState_ThreadHead(PyInterpreterState *interp)
+
+   Return the pointer to the first "PyThreadState" object in the list
+   of threads associated with the interpreter *interp*.
+
+PyThreadState *PyThreadState_Next(PyThreadState *tstate)
+
+   Return the next thread state object after *tstate* from the list of
+   all such objects belonging to the same "PyInterpreterState" object.
+
+
+Thread Local Storage Support
+============================
+
+The Python interpreter provides low-level support for thread-local
+storage (TLS) which wraps the underlying native TLS implementation to
+support the Python-level thread local storage API ("threading.local").
+The CPython C level APIs are similar to those offered by pthreads and
+Windows: use a thread key and functions to associate a void* value per
+thread.
+
+The GIL does *not* need to be held when calling these functions; they
+supply their own locking.
+
+Note that "Python.h" does not include the declaration of the TLS APIs,
+you need to include "pythread.h" to use thread-local storage.
+
+Note:
+
+  None of these API functions handle memory management on behalf of
+  the void* values.  You need to allocate and deallocate them
+  yourself. If the void* values happen to be PyObject*, these
+  functions don't do refcount operations on them either.
+
+
+Thread Specific Storage (TSS) API
+---------------------------------
+
+TSS API is introduced to supersede the use of the existing TLS API
+within the CPython interpreter.  This API uses a new type "Py_tss_t"
+instead of int to represent thread keys.
+
+Added in version 3.7.
+
+See also:
+
+  "A New C-API for Thread-Local Storage in CPython" (**PEP 539**)
+
+type Py_tss_t
+
+   This data structure represents the state of a thread key, the
+   definition of which may depend on the underlying TLS
+   implementation, and it has an internal field representing the key's
+   initialization state.  There are no public members in this
+   structure.
+
+   When Py_LIMITED_API is not defined, static allocation of this type
+   by "Py_tss_NEEDS_INIT" is allowed.
+
+Py_tss_NEEDS_INIT
+
+   This macro expands to the initializer for "Py_tss_t" variables.
+   Note that this macro won't be defined with Py_LIMITED_API.
+
+
+Dynamic Allocation
+~~~~~~~~~~~~~~~~~~
+
+Dynamic allocation of the "Py_tss_t", required in extension modules
+built with Py_LIMITED_API, where static allocation of this type is not
+possible due to its implementation being opaque at build time.
+
+Py_tss_t *PyThread_tss_alloc()
+    * Part of the Stable ABI since version 3.7.*
+
+   Return a value which is the same state as a value initialized with
+   "Py_tss_NEEDS_INIT", or "NULL" in the case of dynamic allocation
+   failure.
+
+void PyThread_tss_free(Py_tss_t *key)
+    * Part of the Stable ABI since version 3.7.*
+
+   Free the given *key* allocated by "PyThread_tss_alloc()", after
+   first calling "PyThread_tss_delete()" to ensure any associated
+   thread locals have been unassigned. This is a no-op if the *key*
+   argument is "NULL".
+
+   Note:
+
+     A freed key becomes a dangling pointer. You should reset the key
+     to "NULL".
+
+
+Methods
+~~~~~~~
+
+The parameter *key* of these functions must not be "NULL".  Moreover,
+the behaviors of "PyThread_tss_set()" and "PyThread_tss_get()" are
+undefined if the given "Py_tss_t" has not been initialized by
+"PyThread_tss_create()".
+
+int PyThread_tss_is_created(Py_tss_t *key)
+    * Part of the Stable ABI since version 3.7.*
+
+   Return a non-zero value if the given "Py_tss_t" has been
+   initialized by "PyThread_tss_create()".
+
+int PyThread_tss_create(Py_tss_t *key)
+    * Part of the Stable ABI since version 3.7.*
+
+   Return a zero value on successful initialization of a TSS key.  The
+   behavior is undefined if the value pointed to by the *key* argument
+   is not initialized by "Py_tss_NEEDS_INIT".  This function can be
+   called repeatedly on the same key -- calling it on an already
+   initialized key is a no-op and immediately returns success.
+
+void PyThread_tss_delete(Py_tss_t *key)
+    * Part of the Stable ABI since version 3.7.*
+
+   Destroy a TSS key to forget the values associated with the key
+   across all threads, and change the key's initialization state to
+   uninitialized.  A destroyed key is able to be initialized again by
+   "PyThread_tss_create()". This function can be called repeatedly on
+   the same key -- calling it on an already destroyed key is a no-op.
+
+int PyThread_tss_set(Py_tss_t *key, void *value)
+    * Part of the Stable ABI since version 3.7.*
+
+   Return a zero value to indicate successfully associating a void*
+   value with a TSS key in the current thread.  Each thread has a
+   distinct mapping of the key to a void* value.
+
+void *PyThread_tss_get(Py_tss_t *key)
+    * Part of the Stable ABI since version 3.7.*
+
+   Return the void* value associated with a TSS key in the current
+   thread.  This returns "NULL" if no value is associated with the key
+   in the current thread.
+
+
+Thread Local Storage (TLS) API
+------------------------------
+
+Deprecated since version 3.7: This API is superseded by Thread
+Specific Storage (TSS) API.
+
+Note:
+
+  This version of the API does not support platforms where the native
+  TLS key is defined in a way that cannot be safely cast to "int".  On
+  such platforms, "PyThread_create_key()" will return immediately with
+  a failure status, and the other TLS functions will all be no-ops on
+  such platforms.
+
+Due to the compatibility problem noted above, this version of the API
+should not be used in new code.
+
+int PyThread_create_key()
+    * Part of the Stable ABI.*
+
+void PyThread_delete_key(int key)
+    * Part of the Stable ABI.*
+
+int PyThread_set_key_value(int key, void *value)
+    * Part of the Stable ABI.*
+
+void *PyThread_get_key_value(int key)
+    * Part of the Stable ABI.*
+
+void PyThread_delete_key_value(int key)
+    * Part of the Stable ABI.*
+
+void PyThread_ReInitTLS()
+    * Part of the Stable ABI.*

python-3.12.6-docs-text/python-3.12.6-docs-text/c-api/init_config.txt

@@ -0,0 +1,1652 @@
+Python Initialization Configuration
+***********************************
+
+Added in version 3.8.
+
+Python can be initialized with "Py_InitializeFromConfig()" and the
+"PyConfig" structure. It can be preinitialized with
+"Py_PreInitialize()" and the "PyPreConfig" structure.
+
+There are two kinds of configuration:
+
+* The Python Configuration can be used to build a customized Python
+  which behaves as the regular Python. For example, environment
+  variables and command line arguments are used to configure Python.
+
+* The Isolated Configuration can be used to embed Python into an
+  application. It isolates Python from the system. For example,
+  environment variables are ignored, the LC_CTYPE locale is left
+  unchanged and no signal handler is registered.
+
+The "Py_RunMain()" function can be used to write a customized Python
+program.
+
+See also Initialization, Finalization, and Threads.
+
+See also: **PEP 587** "Python Initialization Configuration".
+
+
+Example
+=======
+
+Example of customized Python always running in isolated mode:
+
+   int main(int argc, char **argv)
+   {
+       PyStatus status;
+
+       PyConfig config;
+       PyConfig_InitPythonConfig(&config);
+       config.isolated = 1;
+
+       /* Decode command line arguments.
+          Implicitly preinitialize Python (in isolated mode). */
+       status = PyConfig_SetBytesArgv(&config, argc, argv);
+       if (PyStatus_Exception(status)) {
+           goto exception;
+       }
+
+       status = Py_InitializeFromConfig(&config);
+       if (PyStatus_Exception(status)) {
+           goto exception;
+       }
+       PyConfig_Clear(&config);
+
+       return Py_RunMain();
+
+   exception:
+       PyConfig_Clear(&config);
+       if (PyStatus_IsExit(status)) {
+           return status.exitcode;
+       }
+       /* Display the error message and exit the process with
+          non-zero exit code */
+       Py_ExitStatusException(status);
+   }
+
+
+PyWideStringList
+================
+
+type PyWideStringList
+
+   List of "wchar_t*" strings.
+
+   If *length* is non-zero, *items* must be non-"NULL" and all strings
+   must be non-"NULL".
+
+   Methods:
+
+   PyStatus PyWideStringList_Append(PyWideStringList *list, const wchar_t *item)
+
+      Append *item* to *list*.
+
+      Python must be preinitialized to call this function.
+
+   PyStatus PyWideStringList_Insert(PyWideStringList *list, Py_ssize_t index, const wchar_t *item)
+
+      Insert *item* into *list* at *index*.
+
+      If *index* is greater than or equal to *list* length, append
+      *item* to *list*.
+
+      *index* must be greater than or equal to "0".
+
+      Python must be preinitialized to call this function.
+
+   Structure fields:
+
+   Py_ssize_t length
+
+      List length.
+
+   wchar_t **items
+
+      List items.
+
+
+PyStatus
+========
+
+type PyStatus
+
+   Structure to store an initialization function status: success,
+   error or exit.
+
+   For an error, it can store the C function name which created the
+   error.
+
+   Structure fields:
+
+   int exitcode
+
+      Exit code. Argument passed to "exit()".
+
+   const char *err_msg
+
+      Error message.
+
+   const char *func
+
+      Name of the function which created an error, can be "NULL".
+
+   Functions to create a status:
+
+   PyStatus PyStatus_Ok(void)
+
+      Success.
+
+   PyStatus PyStatus_Error(const char *err_msg)
+
+      Initialization error with a message.
+
+      *err_msg* must not be "NULL".
+
+   PyStatus PyStatus_NoMemory(void)
+
+      Memory allocation failure (out of memory).
+
+   PyStatus PyStatus_Exit(int exitcode)
+
+      Exit Python with the specified exit code.
+
+   Functions to handle a status:
+
+   int PyStatus_Exception(PyStatus status)
+
+      Is the status an error or an exit? If true, the exception must
+      be handled; by calling "Py_ExitStatusException()" for example.
+
+   int PyStatus_IsError(PyStatus status)
+
+      Is the result an error?
+
+   int PyStatus_IsExit(PyStatus status)
+
+      Is the result an exit?
+
+   void Py_ExitStatusException(PyStatus status)
+
+      Call "exit(exitcode)" if *status* is an exit. Print the error
+      message and exit with a non-zero exit code if *status* is an
+      error.  Must only be called if "PyStatus_Exception(status)" is
+      non-zero.
+
+Note:
+
+  Internally, Python uses macros which set "PyStatus.func", whereas
+  functions to create a status set "func" to "NULL".
+
+Example:
+
+   PyStatus alloc(void **ptr, size_t size)
+   {
+       *ptr = PyMem_RawMalloc(size);
+       if (*ptr == NULL) {
+           return PyStatus_NoMemory();
+       }
+       return PyStatus_Ok();
+   }
+
+   int main(int argc, char **argv)
+   {
+       void *ptr;
+       PyStatus status = alloc(&ptr, 16);
+       if (PyStatus_Exception(status)) {
+           Py_ExitStatusException(status);
+       }
+       PyMem_Free(ptr);
+       return 0;
+   }
+
+
+PyPreConfig
+===========
+
+type PyPreConfig
+
+   Structure used to preinitialize Python.
+
+   Function to initialize a preconfiguration:
+
+   void PyPreConfig_InitPythonConfig(PyPreConfig *preconfig)
+
+      Initialize the preconfiguration with Python Configuration.
+
+   void PyPreConfig_InitIsolatedConfig(PyPreConfig *preconfig)
+
+      Initialize the preconfiguration with Isolated Configuration.
+
+   Structure fields:
+
+   int allocator
+
+      Name of the Python memory allocators:
+
+      * "PYMEM_ALLOCATOR_NOT_SET" ("0"): don't change memory
+        allocators (use defaults).
+
+      * "PYMEM_ALLOCATOR_DEFAULT" ("1"): default memory allocators.
+
+      * "PYMEM_ALLOCATOR_DEBUG" ("2"): default memory allocators with
+        debug hooks.
+
+      * "PYMEM_ALLOCATOR_MALLOC" ("3"): use "malloc()" of the C
+        library.
+
+      * "PYMEM_ALLOCATOR_MALLOC_DEBUG" ("4"): force usage of
+        "malloc()" with debug hooks.
+
+      * "PYMEM_ALLOCATOR_PYMALLOC" ("5"): Python pymalloc memory
+        allocator.
+
+      * "PYMEM_ALLOCATOR_PYMALLOC_DEBUG" ("6"): Python pymalloc memory
+        allocator with debug hooks.
+
+      "PYMEM_ALLOCATOR_PYMALLOC" and "PYMEM_ALLOCATOR_PYMALLOC_DEBUG"
+      are not supported if Python is "configured using --without-
+      pymalloc".
+
+      See Memory Management.
+
+      Default: "PYMEM_ALLOCATOR_NOT_SET".
+
+   int configure_locale
+
+      Set the LC_CTYPE locale to the user preferred locale.
+
+      If equals to "0", set "coerce_c_locale" and
+      "coerce_c_locale_warn" members to "0".
+
+      See the *locale encoding*.
+
+      Default: "1" in Python config, "0" in isolated config.
+
+   int coerce_c_locale
+
+      If equals to "2", coerce the C locale.
+
+      If equals to "1", read the LC_CTYPE locale to decide if it
+      should be coerced.
+
+      See the *locale encoding*.
+
+      Default: "-1" in Python config, "0" in isolated config.
+
+   int coerce_c_locale_warn
+
+      If non-zero, emit a warning if the C locale is coerced.
+
+      Default: "-1" in Python config, "0" in isolated config.
+
+   int dev_mode
+
+      Python Development Mode: see "PyConfig.dev_mode".
+
+      Default: "-1" in Python mode, "0" in isolated mode.
+
+   int isolated
+
+      Isolated mode: see "PyConfig.isolated".
+
+      Default: "0" in Python mode, "1" in isolated mode.
+
+   int legacy_windows_fs_encoding
+
+      If non-zero:
+
+      * Set "PyPreConfig.utf8_mode" to "0",
+
+      * Set "PyConfig.filesystem_encoding" to ""mbcs"",
+
+      * Set "PyConfig.filesystem_errors" to ""replace"".
+
+      Initialized from the "PYTHONLEGACYWINDOWSFSENCODING" environment
+      variable value.
+
+      Only available on Windows. "#ifdef MS_WINDOWS" macro can be used
+      for Windows specific code.
+
+      Default: "0".
+
+   int parse_argv
+
+      If non-zero, "Py_PreInitializeFromArgs()" and
+      "Py_PreInitializeFromBytesArgs()" parse their "argv" argument
+      the same way the regular Python parses command line arguments:
+      see Command Line Arguments.
+
+      Default: "1" in Python config, "0" in isolated config.
+
+   int use_environment
+
+      Use environment variables? See "PyConfig.use_environment".
+
+      Default: "1" in Python config and "0" in isolated config.
+
+   int utf8_mode
+
+      If non-zero, enable the Python UTF-8 Mode.
+
+      Set to "0" or "1" by the "-X utf8" command line option and the
+      "PYTHONUTF8" environment variable.
+
+      Also set to "1" if the "LC_CTYPE" locale is "C" or "POSIX".
+
+      Default: "-1" in Python config and "0" in isolated config.
+
+
+Preinitialize Python with PyPreConfig
+=====================================
+
+The preinitialization of Python:
+
+* Set the Python memory allocators ("PyPreConfig.allocator")
+
+* Configure the LC_CTYPE locale (*locale encoding*)
+
+* Set the Python UTF-8 Mode ("PyPreConfig.utf8_mode")
+
+The current preconfiguration ("PyPreConfig" type) is stored in
+"_PyRuntime.preconfig".
+
+Functions to preinitialize Python:
+
+PyStatus Py_PreInitialize(const PyPreConfig *preconfig)
+
+   Preinitialize Python from *preconfig* preconfiguration.
+
+   *preconfig* must not be "NULL".
+
+PyStatus Py_PreInitializeFromBytesArgs(const PyPreConfig *preconfig, int argc, char *const *argv)
+
+   Preinitialize Python from *preconfig* preconfiguration.
+
+   Parse *argv* command line arguments (bytes strings) if "parse_argv"
+   of *preconfig* is non-zero.
+
+   *preconfig* must not be "NULL".
+
+PyStatus Py_PreInitializeFromArgs(const PyPreConfig *preconfig, int argc, wchar_t *const *argv)
+
+   Preinitialize Python from *preconfig* preconfiguration.
+
+   Parse *argv* command line arguments (wide strings) if "parse_argv"
+   of *preconfig* is non-zero.
+
+   *preconfig* must not be "NULL".
+
+The caller is responsible to handle exceptions (error or exit) using
+"PyStatus_Exception()" and "Py_ExitStatusException()".
+
+For Python Configuration ("PyPreConfig_InitPythonConfig()"), if Python
+is initialized with command line arguments, the command line arguments
+must also be passed to preinitialize Python, since they have an effect
+on the pre-configuration like encodings. For example, the "-X utf8"
+command line option enables the Python UTF-8 Mode.
+
+"PyMem_SetAllocator()" can be called after "Py_PreInitialize()" and
+before "Py_InitializeFromConfig()" to install a custom memory
+allocator. It can be called before "Py_PreInitialize()" if
+"PyPreConfig.allocator" is set to "PYMEM_ALLOCATOR_NOT_SET".
+
+Python memory allocation functions like "PyMem_RawMalloc()" must not
+be used before the Python preinitialization, whereas calling directly
+"malloc()" and "free()" is always safe. "Py_DecodeLocale()" must not
+be called before the Python preinitialization.
+
+Example using the preinitialization to enable the Python UTF-8 Mode:
+
+   PyStatus status;
+   PyPreConfig preconfig;
+   PyPreConfig_InitPythonConfig(&preconfig);
+
+   preconfig.utf8_mode = 1;
+
+   status = Py_PreInitialize(&preconfig);
+   if (PyStatus_Exception(status)) {
+       Py_ExitStatusException(status);
+   }
+
+   /* at this point, Python speaks UTF-8 */
+
+   Py_Initialize();
+   /* ... use Python API here ... */
+   Py_Finalize();
+
+
+PyConfig
+========
+
+type PyConfig
+
+   Structure containing most parameters to configure Python.
+
+   When done, the "PyConfig_Clear()" function must be used to release
+   the configuration memory.
+
+   Structure methods:
+
+   void PyConfig_InitPythonConfig(PyConfig *config)
+
+      Initialize configuration with the Python Configuration.
+
+   void PyConfig_InitIsolatedConfig(PyConfig *config)
+
+      Initialize configuration with the Isolated Configuration.
+
+   PyStatus PyConfig_SetString(PyConfig *config, wchar_t *const *config_str, const wchar_t *str)
+
+      Copy the wide character string *str* into "*config_str".
+
+      Preinitialize Python if needed.
+
+   PyStatus PyConfig_SetBytesString(PyConfig *config, wchar_t *const *config_str, const char *str)
+
+      Decode *str* using "Py_DecodeLocale()" and set the result into
+      "*config_str".
+
+      Preinitialize Python if needed.
+
+   PyStatus PyConfig_SetArgv(PyConfig *config, int argc, wchar_t *const *argv)
+
+      Set command line arguments ("argv" member of *config*) from the
+      *argv* list of wide character strings.
+
+      Preinitialize Python if needed.
+
+   PyStatus PyConfig_SetBytesArgv(PyConfig *config, int argc, char *const *argv)
+
+      Set command line arguments ("argv" member of *config*) from the
+      *argv* list of bytes strings. Decode bytes using
+      "Py_DecodeLocale()".
+
+      Preinitialize Python if needed.
+
+   PyStatus PyConfig_SetWideStringList(PyConfig *config, PyWideStringList *list, Py_ssize_t length, wchar_t **items)
+
+      Set the list of wide strings *list* to *length* and *items*.
+
+      Preinitialize Python if needed.
+
+   PyStatus PyConfig_Read(PyConfig *config)
+
+      Read all Python configuration.
+
+      Fields which are already initialized are left unchanged.
+
+      Fields for path configuration are no longer calculated or
+      modified when calling this function, as of Python 3.11.
+
+      The "PyConfig_Read()" function only parses "PyConfig.argv"
+      arguments once: "PyConfig.parse_argv" is set to "2" after
+      arguments are parsed. Since Python arguments are stripped from
+      "PyConfig.argv", parsing arguments twice would parse the
+      application options as Python options.
+
+      Preinitialize Python if needed.
+
+      Changed in version 3.10: The "PyConfig.argv" arguments are now
+      only parsed once, "PyConfig.parse_argv" is set to "2" after
+      arguments are parsed, and arguments are only parsed if
+      "PyConfig.parse_argv" equals "1".
+
+      Changed in version 3.11: "PyConfig_Read()" no longer calculates
+      all paths, and so fields listed under Python Path Configuration
+      may no longer be updated until "Py_InitializeFromConfig()" is
+      called.
+
+   void PyConfig_Clear(PyConfig *config)
+
+      Release configuration memory.
+
+   Most "PyConfig" methods preinitialize Python if needed. In that
+   case, the Python preinitialization configuration ("PyPreConfig") in
+   based on the "PyConfig". If configuration fields which are in
+   common with "PyPreConfig" are tuned, they must be set before
+   calling a "PyConfig" method:
+
+   * "PyConfig.dev_mode"
+
+   * "PyConfig.isolated"
+
+   * "PyConfig.parse_argv"
+
+   * "PyConfig.use_environment"
+
+   Moreover, if "PyConfig_SetArgv()" or "PyConfig_SetBytesArgv()" is
+   used, this method must be called before other methods, since the
+   preinitialization configuration depends on command line arguments
+   (if "parse_argv" is non-zero).
+
+   The caller of these methods is responsible to handle exceptions
+   (error or exit) using "PyStatus_Exception()" and
+   "Py_ExitStatusException()".
+
+   Structure fields:
+
+   PyWideStringList argv
+
+      Command line arguments: "sys.argv".
+
+      Set "parse_argv" to "1" to parse "argv" the same way the regular
+      Python parses Python command line arguments and then to strip
+      Python arguments from "argv".
+
+      If "argv" is empty, an empty string is added to ensure that
+      "sys.argv" always exists and is never empty.
+
+      Default: "NULL".
+
+      See also the "orig_argv" member.
+
+   int safe_path
+
+      If equals to zero, "Py_RunMain()" prepends a potentially unsafe
+      path to "sys.path" at startup:
+
+      * If "argv[0]" is equal to "L"-m"" ("python -m module"), prepend
+        the current working directory.
+
+      * If running a script ("python script.py"), prepend the script's
+        directory.  If it's a symbolic link, resolve symbolic links.
+
+      * Otherwise ("python -c code" and "python"), prepend an empty
+        string, which means the current working directory.
+
+      Set to "1" by the "-P" command line option and the
+      "PYTHONSAFEPATH" environment variable.
+
+      Default: "0" in Python config, "1" in isolated config.
+
+      Added in version 3.11.
+
+   wchar_t *base_exec_prefix
+
+      "sys.base_exec_prefix".
+
+      Default: "NULL".
+
+      Part of the Python Path Configuration output.
+
+   wchar_t *base_executable
+
+      Python base executable: "sys._base_executable".
+
+      Set by the "__PYVENV_LAUNCHER__" environment variable.
+
+      Set from "PyConfig.executable" if "NULL".
+
+      Default: "NULL".
+
+      Part of the Python Path Configuration output.
+
+   wchar_t *base_prefix
+
+      "sys.base_prefix".
+
+      Default: "NULL".
+
+      Part of the Python Path Configuration output.
+
+   int buffered_stdio
+
+      If equals to "0" and "configure_c_stdio" is non-zero, disable
+      buffering on the C streams stdout and stderr.
+
+      Set to "0" by the "-u" command line option and the
+      "PYTHONUNBUFFERED" environment variable.
+
+      stdin is always opened in buffered mode.
+
+      Default: "1".
+
+   int bytes_warning
+
+      If equals to "1", issue a warning when comparing "bytes" or
+      "bytearray" with "str", or comparing "bytes" with "int".
+
+      If equal or greater to "2", raise a "BytesWarning" exception in
+      these cases.
+
+      Incremented by the "-b" command line option.
+
+      Default: "0".
+
+   int warn_default_encoding
+
+      If non-zero, emit a "EncodingWarning" warning when
+      "io.TextIOWrapper" uses its default encoding. See Opt-in
+      EncodingWarning for details.
+
+      Default: "0".
+
+      Added in version 3.10.
+
+   int code_debug_ranges
+
+      If equals to "0", disables the inclusion of the end line and
+      column mappings in code objects. Also disables traceback
+      printing carets to specific error locations.
+
+      Set to "0" by the "PYTHONNODEBUGRANGES" environment variable and
+      by the "-X no_debug_ranges" command line option.
+
+      Default: "1".
+
+      Added in version 3.11.
+
+   wchar_t *check_hash_pycs_mode
+
+      Control the validation behavior of hash-based ".pyc" files:
+      value of the "--check-hash-based-pycs" command line option.
+
+      Valid values:
+
+      * "L"always"": Hash the source file for invalidation regardless
+        of value of the 'check_source' flag.
+
+      * "L"never"": Assume that hash-based pycs always are valid.
+
+      * "L"default"": The 'check_source' flag in hash-based pycs
+        determines invalidation.
+
+      Default: "L"default"".
+
+      See also **PEP 552** "Deterministic pycs".
+
+   int configure_c_stdio
+
+      If non-zero, configure C standard streams:
+
+      * On Windows, set the binary mode ("O_BINARY") on stdin, stdout
+        and stderr.
+
+      * If "buffered_stdio" equals zero, disable buffering of stdin,
+        stdout and stderr streams.
+
+      * If "interactive" is non-zero, enable stream buffering on stdin
+        and stdout (only stdout on Windows).
+
+      Default: "1" in Python config, "0" in isolated config.
+
+   int dev_mode
+
+      If non-zero, enable the Python Development Mode.
+
+      Set to "1" by the "-X dev" option and the "PYTHONDEVMODE"
+      environment variable.
+
+      Default: "-1" in Python mode, "0" in isolated mode.
+
+   int dump_refs
+
+      Dump Python references?
+
+      If non-zero, dump all objects which are still alive at exit.
+
+      Set to "1" by the "PYTHONDUMPREFS" environment variable.
+
+      Need a special build of Python with the "Py_TRACE_REFS" macro
+      defined: see the "configure --with-trace-refs option".
+
+      Default: "0".
+
+   wchar_t *exec_prefix
+
+      The site-specific directory prefix where the platform-dependent
+      Python files are installed: "sys.exec_prefix".
+
+      Default: "NULL".
+
+      Part of the Python Path Configuration output.
+
+   wchar_t *executable
+
+      The absolute path of the executable binary for the Python
+      interpreter: "sys.executable".
+
+      Default: "NULL".
+
+      Part of the Python Path Configuration output.
+
+   int faulthandler
+
+      Enable faulthandler?
+
+      If non-zero, call "faulthandler.enable()" at startup.
+
+      Set to "1" by "-X faulthandler" and the "PYTHONFAULTHANDLER"
+      environment variable.
+
+      Default: "-1" in Python mode, "0" in isolated mode.
+
+   wchar_t *filesystem_encoding
+
+      *Filesystem encoding*: "sys.getfilesystemencoding()".
+
+      On macOS, Android and VxWorks: use ""utf-8"" by default.
+
+      On Windows: use ""utf-8"" by default, or ""mbcs"" if
+      "legacy_windows_fs_encoding" of "PyPreConfig" is non-zero.
+
+      Default encoding on other platforms:
+
+      * ""utf-8"" if "PyPreConfig.utf8_mode" is non-zero.
+
+      * ""ascii"" if Python detects that "nl_langinfo(CODESET)"
+        announces the ASCII encoding, whereas the "mbstowcs()"
+        function decodes from a different encoding (usually Latin1).
+
+      * ""utf-8"" if "nl_langinfo(CODESET)" returns an empty string.
+
+      * Otherwise, use the *locale encoding*: "nl_langinfo(CODESET)"
+        result.
+
+      At Python startup, the encoding name is normalized to the Python
+      codec name. For example, ""ANSI_X3.4-1968"" is replaced with
+      ""ascii"".
+
+      See also the "filesystem_errors" member.
+
+   wchar_t *filesystem_errors
+
+      *Filesystem error handler*: "sys.getfilesystemencodeerrors()".
+
+      On Windows: use ""surrogatepass"" by default, or ""replace""  if
+      "legacy_windows_fs_encoding" of "PyPreConfig" is non-zero.
+
+      On other platforms: use ""surrogateescape"" by default.
+
+      Supported error handlers:
+
+      * ""strict""
+
+      * ""surrogateescape""
+
+      * ""surrogatepass"" (only supported with the UTF-8 encoding)
+
+      See also the "filesystem_encoding" member.
+
+   unsigned long hash_seed
+
+   int use_hash_seed
+
+      Randomized hash function seed.
+
+      If "use_hash_seed" is zero, a seed is chosen randomly at Python
+      startup, and "hash_seed" is ignored.
+
+      Set by the "PYTHONHASHSEED" environment variable.
+
+      Default *use_hash_seed* value: "-1" in Python mode, "0" in
+      isolated mode.
+
+   wchar_t *home
+
+      Python home directory.
+
+      If "Py_SetPythonHome()" has been called, use its argument if it
+      is not "NULL".
+
+      Set by the "PYTHONHOME" environment variable.
+
+      Default: "NULL".
+
+      Part of the Python Path Configuration input.
+
+   int import_time
+
+      If non-zero, profile import time.
+
+      Set the "1" by the "-X importtime" option and the
+      "PYTHONPROFILEIMPORTTIME" environment variable.
+
+      Default: "0".
+
+   int inspect
+
+      Enter interactive mode after executing a script or a command.
+
+      If greater than "0", enable inspect: when a script is passed as
+      first argument or the -c option is used, enter interactive mode
+      after executing the script or the command, even when "sys.stdin"
+      does not appear to be a terminal.
+
+      Incremented by the "-i" command line option. Set to "1" if the
+      "PYTHONINSPECT" environment variable is non-empty.
+
+      Default: "0".
+
+   int install_signal_handlers
+
+      Install Python signal handlers?
+
+      Default: "1" in Python mode, "0" in isolated mode.
+
+   int interactive
+
+      If greater than "0", enable the interactive mode (REPL).
+
+      Incremented by the "-i" command line option.
+
+      Default: "0".
+
+   int int_max_str_digits
+
+      Configures the integer string conversion length limitation.  An
+      initial value of "-1" means the value will be taken from the
+      command line or environment or otherwise default to 4300
+      ("sys.int_info.default_max_str_digits").  A value of "0"
+      disables the limitation.  Values greater than zero but less than
+      640 ("sys.int_info.str_digits_check_threshold") are unsupported
+      and will produce an error.
+
+      Configured by the "-X int_max_str_digits" command line flag or
+      the "PYTHONINTMAXSTRDIGITS" environment variable.
+
+      Default: "-1" in Python mode.  4300
+      ("sys.int_info.default_max_str_digits") in isolated mode.
+
+      Added in version 3.12.
+
+   int isolated
+
+      If greater than "0", enable isolated mode:
+
+      * Set "safe_path" to "1": don't prepend a potentially unsafe
+        path to "sys.path" at Python startup, such as the current
+        directory, the script's directory or an empty string.
+
+      * Set "use_environment" to "0": ignore "PYTHON" environment
+        variables.
+
+      * Set "user_site_directory" to "0": don't add the user site
+        directory to "sys.path".
+
+      * Python REPL doesn't import "readline" nor enable default
+        readline configuration on interactive prompts.
+
+      Set to "1" by the "-I" command line option.
+
+      Default: "0" in Python mode, "1" in isolated mode.
+
+      See also the Isolated Configuration and "PyPreConfig.isolated".
+
+   int legacy_windows_stdio
+
+      If non-zero, use "io.FileIO" instead of "io._WindowsConsoleIO"
+      for "sys.stdin", "sys.stdout" and "sys.stderr".
+
+      Set to "1" if the "PYTHONLEGACYWINDOWSSTDIO" environment
+      variable is set to a non-empty string.
+
+      Only available on Windows. "#ifdef MS_WINDOWS" macro can be used
+      for Windows specific code.
+
+      Default: "0".
+
+      See also the **PEP 528** (Change Windows console encoding to
+      UTF-8).
+
+   int malloc_stats
+
+      If non-zero, dump statistics on Python pymalloc memory allocator
+      at exit.
+
+      Set to "1" by the "PYTHONMALLOCSTATS" environment variable.
+
+      The option is ignored if Python is "configured using the
+      --without-pymalloc option".
+
+      Default: "0".
+
+   wchar_t *platlibdir
+
+      Platform library directory name: "sys.platlibdir".
+
+      Set by the "PYTHONPLATLIBDIR" environment variable.
+
+      Default: value of the "PLATLIBDIR" macro which is set by the
+      "configure --with-platlibdir option" (default: ""lib"", or
+      ""DLLs"" on Windows).
+
+      Part of the Python Path Configuration input.
+
+      Added in version 3.9.
+
+      Changed in version 3.11: This macro is now used on Windows to
+      locate the standard library extension modules, typically under
+      "DLLs". However, for compatibility, note that this value is
+      ignored for any non-standard layouts, including in-tree builds
+      and virtual environments.
+
+   wchar_t *pythonpath_env
+
+      Module search paths ("sys.path") as a string separated by
+      "DELIM" ("os.pathsep").
+
+      Set by the "PYTHONPATH" environment variable.
+
+      Default: "NULL".
+
+      Part of the Python Path Configuration input.
+
+   PyWideStringList module_search_paths
+
+   int module_search_paths_set
+
+      Module search paths: "sys.path".
+
+      If "module_search_paths_set" is equal to "0",
+      "Py_InitializeFromConfig()" will replace "module_search_paths"
+      and sets "module_search_paths_set" to "1".
+
+      Default: empty list ("module_search_paths") and "0"
+      ("module_search_paths_set").
+
+      Part of the Python Path Configuration output.
+
+   int optimization_level
+
+      Compilation optimization level:
+
+      * "0": Peephole optimizer, set "__debug__" to "True".
+
+      * "1": Level 0, remove assertions, set "__debug__" to "False".
+
+      * "2": Level 1, strip docstrings.
+
+      Incremented by the "-O" command line option. Set to the
+      "PYTHONOPTIMIZE" environment variable value.
+
+      Default: "0".
+
+   PyWideStringList orig_argv
+
+      The list of the original command line arguments passed to the
+      Python executable: "sys.orig_argv".
+
+      If "orig_argv" list is empty and "argv" is not a list only
+      containing an empty string, "PyConfig_Read()" copies "argv" into
+      "orig_argv" before modifying "argv" (if "parse_argv" is non-
+      zero).
+
+      See also the "argv" member and the "Py_GetArgcArgv()" function.
+
+      Default: empty list.
+
+      Added in version 3.10.
+
+   int parse_argv
+
+      Parse command line arguments?
+
+      If equals to "1", parse "argv" the same way the regular Python
+      parses command line arguments, and strip Python arguments from
+      "argv".
+
+      The "PyConfig_Read()" function only parses "PyConfig.argv"
+      arguments once: "PyConfig.parse_argv" is set to "2" after
+      arguments are parsed. Since Python arguments are stripped from
+      "PyConfig.argv", parsing arguments twice would parse the
+      application options as Python options.
+
+      Default: "1" in Python mode, "0" in isolated mode.
+
+      Changed in version 3.10: The "PyConfig.argv" arguments are now
+      only parsed if "PyConfig.parse_argv" equals to "1".
+
+   int parser_debug
+
+      Parser debug mode. If greater than "0", turn on parser debugging
+      output (for expert only, depending on compilation options).
+
+      Incremented by the "-d" command line option. Set to the
+      "PYTHONDEBUG" environment variable value.
+
+      Need a debug build of Python (the "Py_DEBUG" macro must be
+      defined).
+
+      Default: "0".
+
+   int pathconfig_warnings
+
+      If non-zero, calculation of path configuration is allowed to log
+      warnings into "stderr". If equals to "0", suppress these
+      warnings.
+
+      Default: "1" in Python mode, "0" in isolated mode.
+
+      Part of the Python Path Configuration input.
+
+      Changed in version 3.11: Now also applies on Windows.
+
+   wchar_t *prefix
+
+      The site-specific directory prefix where the platform
+      independent Python files are installed: "sys.prefix".
+
+      Default: "NULL".
+
+      Part of the Python Path Configuration output.
+
+   wchar_t *program_name
+
+      Program name used to initialize "executable" and in early error
+      messages during Python initialization.
+
+      * If "Py_SetProgramName()" has been called, use its argument.
+
+      * On macOS, use "PYTHONEXECUTABLE" environment variable if set.
+
+      * If the "WITH_NEXT_FRAMEWORK" macro is defined, use
+        "__PYVENV_LAUNCHER__" environment variable if set.
+
+      * Use "argv[0]" of "argv" if available and non-empty.
+
+      * Otherwise, use "L"python"" on Windows, or "L"python3"" on
+        other platforms.
+
+      Default: "NULL".
+
+      Part of the Python Path Configuration input.
+
+   wchar_t *pycache_prefix
+
+      Directory where cached ".pyc" files are written:
+      "sys.pycache_prefix".
+
+      Set by the "-X pycache_prefix=PATH" command line option and the
+      "PYTHONPYCACHEPREFIX" environment variable.
+
+      If "NULL", "sys.pycache_prefix" is set to "None".
+
+      Default: "NULL".
+
+   int quiet
+
+      Quiet mode. If greater than "0", don't display the copyright and
+      version at Python startup in interactive mode.
+
+      Incremented by the "-q" command line option.
+
+      Default: "0".
+
+   wchar_t *run_command
+
+      Value of the "-c" command line option.
+
+      Used by "Py_RunMain()".
+
+      Default: "NULL".
+
+   wchar_t *run_filename
+
+      Filename passed on the command line: trailing command line
+      argument without "-c" or "-m". It is used by the "Py_RunMain()"
+      function.
+
+      For example, it is set to "script.py" by the "python3 script.py
+      arg" command line.
+
+      See also the "PyConfig.skip_source_first_line" option.
+
+      Default: "NULL".
+
+   wchar_t *run_module
+
+      Value of the "-m" command line option.
+
+      Used by "Py_RunMain()".
+
+      Default: "NULL".
+
+   int show_ref_count
+
+      Show total reference count at exit (excluding immortal objects)?
+
+      Set to "1" by "-X showrefcount" command line option.
+
+      Need a debug build of Python (the "Py_REF_DEBUG" macro must be
+      defined).
+
+      Default: "0".
+
+   int site_import
+
+      Import the "site" module at startup?
+
+      If equal to zero, disable the import of the module site and the
+      site-dependent manipulations of "sys.path" that it entails.
+
+      Also disable these manipulations if the "site" module is
+      explicitly imported later (call "site.main()" if you want them
+      to be triggered).
+
+      Set to "0" by the "-S" command line option.
+
+      "sys.flags.no_site" is set to the inverted value of
+      "site_import".
+
+      Default: "1".
+
+   int skip_source_first_line
+
+      If non-zero, skip the first line of the "PyConfig.run_filename"
+      source.
+
+      It allows the usage of non-Unix forms of "#!cmd". This is
+      intended for a DOS specific hack only.
+
+      Set to "1" by the "-x" command line option.
+
+      Default: "0".
+
+   wchar_t *stdio_encoding
+
+   wchar_t *stdio_errors
+
+      Encoding and encoding errors of "sys.stdin", "sys.stdout" and
+      "sys.stderr" (but "sys.stderr" always uses ""backslashreplace""
+      error handler).
+
+      If "Py_SetStandardStreamEncoding()" has been called, use its
+      *error* and *errors* arguments if they are not "NULL".
+
+      Use the "PYTHONIOENCODING" environment variable if it is non-
+      empty.
+
+      Default encoding:
+
+      * ""UTF-8"" if "PyPreConfig.utf8_mode" is non-zero.
+
+      * Otherwise, use the *locale encoding*.
+
+      Default error handler:
+
+      * On Windows: use ""surrogateescape"".
+
+      * ""surrogateescape"" if "PyPreConfig.utf8_mode" is non-zero, or
+        if the LC_CTYPE locale is "C" or "POSIX".
+
+      * ""strict"" otherwise.
+
+   int tracemalloc
+
+      Enable tracemalloc?
+
+      If non-zero, call "tracemalloc.start()" at startup.
+
+      Set by "-X tracemalloc=N" command line option and by the
+      "PYTHONTRACEMALLOC" environment variable.
+
+      Default: "-1" in Python mode, "0" in isolated mode.
+
+   int perf_profiling
+
+      Enable compatibility mode with the perf profiler?
+
+      If non-zero, initialize the perf trampoline. See Python support
+      for the Linux perf profiler for more information.
+
+      Set by "-X perf" command line option and by the
+      "PYTHONPERFSUPPORT" environment variable.
+
+      Default: "-1".
+
+      Added in version 3.12.
+
+   int use_environment
+
+      Use environment variables?
+
+      If equals to zero, ignore the environment variables.
+
+      Set to "0" by the "-E" environment variable.
+
+      Default: "1" in Python config and "0" in isolated config.
+
+   int user_site_directory
+
+      If non-zero, add the user site directory to "sys.path".
+
+      Set to "0" by the "-s" and "-I" command line options.
+
+      Set to "0" by the "PYTHONNOUSERSITE" environment variable.
+
+      Default: "1" in Python mode, "0" in isolated mode.
+
+   int verbose
+
+      Verbose mode. If greater than "0", print a message each time a
+      module is imported, showing the place (filename or built-in
+      module) from which it is loaded.
+
+      If greater than or equal to "2", print a message for each file
+      that is checked for when searching for a module. Also provides
+      information on module cleanup at exit.
+
+      Incremented by the "-v" command line option.
+
+      Set by the "PYTHONVERBOSE" environment variable value.
+
+      Default: "0".
+
+   PyWideStringList warnoptions
+
+      Options of the "warnings" module to build warnings filters,
+      lowest to highest priority: "sys.warnoptions".
+
+      The "warnings" module adds "sys.warnoptions" in the reverse
+      order: the last "PyConfig.warnoptions" item becomes the first
+      item of "warnings.filters" which is checked first (highest
+      priority).
+
+      The "-W" command line options adds its value to "warnoptions",
+      it can be used multiple times.
+
+      The "PYTHONWARNINGS" environment variable can also be used to
+      add warning options. Multiple options can be specified,
+      separated by commas (",").
+
+      Default: empty list.
+
+   int write_bytecode
+
+      If equal to "0", Python won't try to write ".pyc" files on the
+      import of source modules.
+
+      Set to "0" by the "-B" command line option and the
+      "PYTHONDONTWRITEBYTECODE" environment variable.
+
+      "sys.dont_write_bytecode" is initialized to the inverted value
+      of "write_bytecode".
+
+      Default: "1".
+
+   PyWideStringList xoptions
+
+      Values of the "-X" command line options: "sys._xoptions".
+
+      Default: empty list.
+
+If "parse_argv" is non-zero, "argv" arguments are parsed the same way
+the regular Python parses command line arguments, and Python arguments
+are stripped from "argv".
+
+The "xoptions" options are parsed to set other options: see the "-X"
+command line option.
+
+Changed in version 3.9: The "show_alloc_count" field has been removed.
+
+
+Initialization with PyConfig
+============================
+
+Function to initialize Python:
+
+PyStatus Py_InitializeFromConfig(const PyConfig *config)
+
+   Initialize Python from *config* configuration.
+
+The caller is responsible to handle exceptions (error or exit) using
+"PyStatus_Exception()" and "Py_ExitStatusException()".
+
+If "PyImport_FrozenModules()", "PyImport_AppendInittab()" or
+"PyImport_ExtendInittab()" are used, they must be set or called after
+Python preinitialization and before the Python initialization. If
+Python is initialized multiple times, "PyImport_AppendInittab()" or
+"PyImport_ExtendInittab()" must be called before each Python
+initialization.
+
+The current configuration ("PyConfig" type) is stored in
+"PyInterpreterState.config".
+
+Example setting the program name:
+
+   void init_python(void)
+   {
+       PyStatus status;
+
+       PyConfig config;
+       PyConfig_InitPythonConfig(&config);
+
+       /* Set the program name. Implicitly preinitialize Python. */
+       status = PyConfig_SetString(&config, &config.program_name,
+                                   L"/path/to/my_program");
+       if (PyStatus_Exception(status)) {
+           goto exception;
+       }
+
+       status = Py_InitializeFromConfig(&config);
+       if (PyStatus_Exception(status)) {
+           goto exception;
+       }
+       PyConfig_Clear(&config);
+       return;
+
+   exception:
+       PyConfig_Clear(&config);
+       Py_ExitStatusException(status);
+   }
+
+More complete example modifying the default configuration, read the
+configuration, and then override some parameters. Note that since
+3.11, many parameters are not calculated until initialization, and so
+values cannot be read from the configuration structure. Any values set
+before initialize is called will be left unchanged by initialization:
+
+   PyStatus init_python(const char *program_name)
+   {
+       PyStatus status;
+
+       PyConfig config;
+       PyConfig_InitPythonConfig(&config);
+
+       /* Set the program name before reading the configuration
+          (decode byte string from the locale encoding).
+
+          Implicitly preinitialize Python. */
+       status = PyConfig_SetBytesString(&config, &config.program_name,
+                                        program_name);
+       if (PyStatus_Exception(status)) {
+           goto done;
+       }
+
+       /* Read all configuration at once */
+       status = PyConfig_Read(&config);
+       if (PyStatus_Exception(status)) {
+           goto done;
+       }
+
+       /* Specify sys.path explicitly */
+       /* If you want to modify the default set of paths, finish
+          initialization first and then use PySys_GetObject("path") */
+       config.module_search_paths_set = 1;
+       status = PyWideStringList_Append(&config.module_search_paths,
+                                        L"/path/to/stdlib");
+       if (PyStatus_Exception(status)) {
+           goto done;
+       }
+       status = PyWideStringList_Append(&config.module_search_paths,
+                                        L"/path/to/more/modules");
+       if (PyStatus_Exception(status)) {
+           goto done;
+       }
+
+       /* Override executable computed by PyConfig_Read() */
+       status = PyConfig_SetString(&config, &config.executable,
+                                   L"/path/to/my_executable");
+       if (PyStatus_Exception(status)) {
+           goto done;
+       }
+
+       status = Py_InitializeFromConfig(&config);
+
+   done:
+       PyConfig_Clear(&config);
+       return status;
+   }
+
+
+Isolated Configuration
+======================
+
+"PyPreConfig_InitIsolatedConfig()" and "PyConfig_InitIsolatedConfig()"
+functions create a configuration to isolate Python from the system.
+For example, to embed Python into an application.
+
+This configuration ignores global configuration variables, environment
+variables, command line arguments ("PyConfig.argv" is not parsed) and
+user site directory. The C standard streams (ex: "stdout") and the
+LC_CTYPE locale are left unchanged. Signal handlers are not installed.
+
+Configuration files are still used with this configuration to
+determine paths that are unspecified. Ensure "PyConfig.home" is
+specified to avoid computing the default path configuration.
+
+
+Python Configuration
+====================
+
+"PyPreConfig_InitPythonConfig()" and "PyConfig_InitPythonConfig()"
+functions create a configuration to build a customized Python which
+behaves as the regular Python.
+
+Environments variables and command line arguments are used to
+configure Python, whereas global configuration variables are ignored.
+
+This function enables C locale coercion (**PEP 538**) and Python UTF-8
+Mode (**PEP 540**) depending on the LC_CTYPE locale, "PYTHONUTF8" and
+"PYTHONCOERCECLOCALE" environment variables.
+
+
+Python Path Configuration
+=========================
+
+"PyConfig" contains multiple fields for the path configuration:
+
+* Path configuration inputs:
+
+  * "PyConfig.home"
+
+  * "PyConfig.platlibdir"
+
+  * "PyConfig.pathconfig_warnings"
+
+  * "PyConfig.program_name"
+
+  * "PyConfig.pythonpath_env"
+
+  * current working directory: to get absolute paths
+
+  * "PATH" environment variable to get the program full path (from
+    "PyConfig.program_name")
+
+  * "__PYVENV_LAUNCHER__" environment variable
+
+  * (Windows only) Application paths in the registry under
+    "SoftwarePythonPythonCoreX.YPythonPath" of HKEY_CURRENT_USER and
+    HKEY_LOCAL_MACHINE (where X.Y is the Python version).
+
+* Path configuration output fields:
+
+  * "PyConfig.base_exec_prefix"
+
+  * "PyConfig.base_executable"
+
+  * "PyConfig.base_prefix"
+
+  * "PyConfig.exec_prefix"
+
+  * "PyConfig.executable"
+
+  * "PyConfig.module_search_paths_set", "PyConfig.module_search_paths"
+
+  * "PyConfig.prefix"
+
+If at least one "output field" is not set, Python calculates the path
+configuration to fill unset fields. If "module_search_paths_set" is
+equal to "0", "module_search_paths" is overridden and
+"module_search_paths_set" is set to "1".
+
+It is possible to completely ignore the function calculating the
+default path configuration by setting explicitly all path
+configuration output fields listed above. A string is considered as
+set even if it is non-empty. "module_search_paths" is considered as
+set if "module_search_paths_set" is set to "1". In this case,
+"module_search_paths" will be used without modification.
+
+Set "pathconfig_warnings" to "0" to suppress warnings when calculating
+the path configuration (Unix only, Windows does not log any warning).
+
+If "base_prefix" or "base_exec_prefix" fields are not set, they
+inherit their value from "prefix" and "exec_prefix" respectively.
+
+"Py_RunMain()" and "Py_Main()" modify "sys.path":
+
+* If "run_filename" is set and is a directory which contains a
+  "__main__.py" script, prepend "run_filename" to "sys.path".
+
+* If "isolated" is zero:
+
+  * If "run_module" is set, prepend the current directory to
+    "sys.path". Do nothing if the current directory cannot be read.
+
+  * If "run_filename" is set, prepend the directory of the filename to
+    "sys.path".
+
+  * Otherwise, prepend an empty string to "sys.path".
+
+If "site_import" is non-zero, "sys.path" can be modified by the "site"
+module. If "user_site_directory" is non-zero and the user's site-
+package directory exists, the "site" module appends the user's site-
+package directory to "sys.path".
+
+The following configuration files are used by the path configuration:
+
+* "pyvenv.cfg"
+
+* "._pth" file (ex: "python._pth")
+
+* "pybuilddir.txt" (Unix only)
+
+If a "._pth" file is present:
+
+* Set "isolated" to "1".
+
+* Set "use_environment" to "0".
+
+* Set "site_import" to "0".
+
+* Set "safe_path" to "1".
+
+The "__PYVENV_LAUNCHER__" environment variable is used to set
+"PyConfig.base_executable"
+
+
+Py_RunMain()
+============
+
+int Py_RunMain(void)
+
+   Execute the command ("PyConfig.run_command"), the script
+   ("PyConfig.run_filename") or the module ("PyConfig.run_module")
+   specified on the command line or in the configuration.
+
+   By default and when if "-i" option is used, run the REPL.
+
+   Finally, finalizes Python and returns an exit status that can be
+   passed to the "exit()" function.
+
+See Python Configuration for an example of customized Python always
+running in isolated mode using "Py_RunMain()".
+
+
+Py_GetArgcArgv()
+================
+
+void Py_GetArgcArgv(int *argc, wchar_t ***argv)
+
+   Get the original command line arguments, before Python modified
+   them.
+
+   See also "PyConfig.orig_argv" member.
+
+
+Multi-Phase Initialization Private Provisional API
+==================================================
+
+This section is a private provisional API introducing multi-phase
+initialization, the core feature of **PEP 432**:
+
+* "Core" initialization phase, "bare minimum Python":
+
+  * Builtin types;
+
+  * Builtin exceptions;
+
+  * Builtin and frozen modules;
+
+  * The "sys" module is only partially initialized (ex: "sys.path"
+    doesn't exist yet).
+
+* "Main" initialization phase, Python is fully initialized:
+
+  * Install and configure "importlib";
+
+  * Apply the Path Configuration;
+
+  * Install signal handlers;
+
+  * Finish "sys" module initialization (ex: create "sys.stdout" and
+    "sys.path");
+
+  * Enable optional features like "faulthandler" and "tracemalloc";
+
+  * Import the "site" module;
+
+  * etc.
+
+Private provisional API:
+
+* "PyConfig._init_main": if set to "0", "Py_InitializeFromConfig()"
+  stops at the "Core" initialization phase.
+
+PyStatus _Py_InitializeMain(void)
+
+   Move to the "Main" initialization phase, finish the Python
+   initialization.
+
+No module is imported during the "Core" phase and the "importlib"
+module is not configured: the Path Configuration is only applied
+during the "Main" phase. It may allow to customize Python in Python to
+override or tune the Path Configuration, maybe install a custom
+"sys.meta_path" importer or an import hook, etc.
+
+It may become possible to calculate the Path Configuration in Python,
+after the Core phase and before the Main phase, which is one of the
+**PEP 432** motivation.
+
+The "Core" phase is not properly defined: what should be and what
+should not be available at this phase is not specified yet. The API is
+marked as private and provisional: the API can be modified or even be
+removed anytime until a proper public API is designed.
+
+Example running Python code between "Core" and "Main" initialization
+phases:
+
+   void init_python(void)
+   {
+       PyStatus status;
+
+       PyConfig config;
+       PyConfig_InitPythonConfig(&config);
+       config._init_main = 0;
+
+       /* ... customize 'config' configuration ... */
+
+       status = Py_InitializeFromConfig(&config);
+       PyConfig_Clear(&config);
+       if (PyStatus_Exception(status)) {
+           Py_ExitStatusException(status);
+       }
+
+       /* Use sys.stderr because sys.stdout is only created
+          by _Py_InitializeMain() */
+       int res = PyRun_SimpleString(
+           "import sys; "
+           "print('Run Python code before _Py_InitializeMain', "
+                  "file=sys.stderr)");
+       if (res < 0) {
+           exit(1);
+       }
+
+       /* ... put more configuration code here ... */
+
+       status = _Py_InitializeMain();
+       if (PyStatus_Exception(status)) {
+           Py_ExitStatusException(status);
+       }
+   }

python-3.12.6-docs-text/python-3.12.6-docs-text/c-api/intro.txt

@@ -0,0 +1,784 @@
+Introduction
+************
+
+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 API.  There are two fundamentally
+different reasons for using the Python/C API. The first reason is to
+write *extension modules* for specific purposes; these are C modules
+that extend the Python interpreter.  This is probably the most common
+use.  The second reason is to use Python as a component in a larger
+application; this technique is generally referred to as *embedding*
+Python in an application.
+
+Writing an extension module is a relatively well-understood process,
+where a "cookbook" approach works well.  There are several tools that
+automate the process to some extent.  While people have embedded
+Python in other applications since its early existence, the process of
+embedding Python is less straightforward than writing an extension.
+
+Many API functions are useful independent of whether you're embedding
+or extending Python; moreover, most applications that embed Python
+will need to provide a custom extension as well, so it's probably a
+good idea to become familiar with writing an extension before
+attempting to embed Python in a real application.
+
+
+Coding standards
+================
+
+If you're writing C code for inclusion in CPython, you **must** follow
+the guidelines and standards defined in **PEP 7**.  These guidelines
+apply regardless of the version of Python you are contributing to.
+Following these conventions is not necessary for your own third party
+extension modules, unless you eventually expect to contribute them to
+Python.
+
+
+Include Files
+=============
+
+All function, type and macro definitions needed to use the Python/C
+API are included in your code by the following line:
+
+   #define PY_SSIZE_T_CLEAN
+   #include <Python.h>
+
+This implies inclusion of the following standard headers: "<stdio.h>",
+"<string.h>", "<errno.h>", "<limits.h>", "<assert.h>" and "<stdlib.h>"
+(if available).
+
+Note:
+
+  Since Python may define some pre-processor definitions which affect
+  the standard headers on some systems, you *must* include "Python.h"
+  before any standard headers are included.It is recommended to always
+  define "PY_SSIZE_T_CLEAN" before including "Python.h".  See Parsing
+  arguments and building values for a description of this macro.
+
+All user visible names defined by Python.h (except those defined by
+the included standard headers) have one of the prefixes "Py" or "_Py".
+Names beginning with "_Py" are for internal use by the Python
+implementation and should not be used by extension writers. Structure
+member names do not have a reserved prefix.
+
+Note:
+
+  User code should never define names that begin with "Py" or "_Py".
+  This confuses the reader, and jeopardizes the portability of the
+  user code to future Python versions, which may define additional
+  names beginning with one of these prefixes.
+
+The header files are typically installed with Python.  On Unix, these
+are located in the directories "*prefix*/include/pythonversion/" and
+"*exec_prefix*/include/pythonversion/", where "prefix" and
+"exec_prefix" are defined by the corresponding parameters to Python's
+**configure** script and *version* is "'%d.%d' %
+sys.version_info[:2]".  On Windows, the headers are installed in
+"*prefix*/include", where "prefix" is the installation directory
+specified to the installer.
+
+To include the headers, place both directories (if different) on your
+compiler's search path for includes.  Do *not* place the parent
+directories on the search path and then use "#include
+<pythonX.Y/Python.h>"; this will break on multi-platform builds since
+the platform independent headers under "prefix" include the platform
+specific headers from "exec_prefix".
+
+C++ users should note that although the API is defined entirely using
+C, the header files properly declare the entry points to be "extern
+"C"". As a result, there is no need to do anything special to use the
+API from C++.
+
+
+Useful macros
+=============
+
+Several useful macros are defined in the Python header files.  Many
+are defined closer to where they are useful (e.g. "Py_RETURN_NONE").
+Others of a more general utility are defined here.  This is not
+necessarily a complete listing.
+
+PyMODINIT_FUNC
+
+   Declare an extension module "PyInit" initialization function. The
+   function return type is PyObject*. The macro declares any special
+   linkage declarations required by the platform, and for C++ declares
+   the function as "extern "C"".
+
+   The initialization function must be named "PyInit_*name*", where
+   *name* is the name of the module, and should be the only
+   non-"static" item defined in the module file. Example:
+
+      static struct PyModuleDef spam_module = {
+          PyModuleDef_HEAD_INIT,
+          .m_name = "spam",
+          ...
+      };
+
+      PyMODINIT_FUNC
+      PyInit_spam(void)
+      {
+          return PyModule_Create(&spam_module);
+      }
+
+Py_ABS(x)
+
+   Return the absolute value of "x".
+
+   Added in version 3.3.
+
+Py_ALWAYS_INLINE
+
+   Ask the compiler to always inline a static inline function. The
+   compiler can ignore it and decides to not inline the function.
+
+   It can be used to inline performance critical static inline
+   functions when building Python in debug mode with function inlining
+   disabled. For example, MSC disables function inlining when building
+   in debug mode.
+
+   Marking blindly a static inline function with Py_ALWAYS_INLINE can
+   result in worse performances (due to increased code size for
+   example). The compiler is usually smarter than the developer for
+   the cost/benefit analysis.
+
+   If Python is built in debug mode (if the "Py_DEBUG" macro is
+   defined), the "Py_ALWAYS_INLINE" macro does nothing.
+
+   It must be specified before the function return type. Usage:
+
+      static inline Py_ALWAYS_INLINE int random(void) { return 4; }
+
+   Added in version 3.11.
+
+Py_CHARMASK(c)
+
+   Argument must be a character or an integer in the range [-128, 127]
+   or [0, 255].  This macro returns "c" cast to an "unsigned char".
+
+Py_DEPRECATED(version)
+
+   Use this for deprecated declarations.  The macro must be placed
+   before the symbol name.
+
+   Example:
+
+      Py_DEPRECATED(3.8) PyAPI_FUNC(int) Py_OldFunction(void);
+
+   Changed in version 3.8: MSVC support was added.
+
+Py_GETENV(s)
+
+   Like "getenv(s)", but returns "NULL" if "-E" was passed on the
+   command line (see "PyConfig.use_environment").
+
+Py_MAX(x, y)
+
+   Return the maximum value between "x" and "y".
+
+   Added in version 3.3.
+
+Py_MEMBER_SIZE(type, member)
+
+   Return the size of a structure ("type") "member" in bytes.
+
+   Added in version 3.6.
+
+Py_MIN(x, y)
+
+   Return the minimum value between "x" and "y".
+
+   Added in version 3.3.
+
+Py_NO_INLINE
+
+   Disable inlining on a function. For example, it reduces the C stack
+   consumption: useful on LTO+PGO builds which heavily inline code
+   (see bpo-33720).
+
+   Usage:
+
+      Py_NO_INLINE static int random(void) { return 4; }
+
+   Added in version 3.11.
+
+Py_STRINGIFY(x)
+
+   Convert "x" to a C string.  E.g. "Py_STRINGIFY(123)" returns
+   ""123"".
+
+   Added in version 3.4.
+
+Py_UNREACHABLE()
+
+   Use this when you have a code path that cannot be reached by
+   design. For example, in the "default:" clause in a "switch"
+   statement for which all possible values are covered in "case"
+   statements.  Use this in places where you might be tempted to put
+   an "assert(0)" or "abort()" call.
+
+   In release mode, the macro helps the compiler to optimize the code,
+   and avoids a warning about unreachable code.  For example, the
+   macro is implemented with "__builtin_unreachable()" on GCC in
+   release mode.
+
+   A use for "Py_UNREACHABLE()" is following a call a function that
+   never returns but that is not declared "_Py_NO_RETURN".
+
+   If a code path is very unlikely code but can be reached under
+   exceptional case, this macro must not be used.  For example, under
+   low memory condition or if a system call returns a value out of the
+   expected range.  In this case, it's better to report the error to
+   the caller.  If the error cannot be reported to caller,
+   "Py_FatalError()" can be used.
+
+   Added in version 3.7.
+
+Py_UNUSED(arg)
+
+   Use this for unused arguments in a function definition to silence
+   compiler warnings. Example: "int func(int a, int Py_UNUSED(b)) {
+   return a; }".
+
+   Added in version 3.4.
+
+PyDoc_STRVAR(name, str)
+
+   Creates a variable with name "name" that can be used in docstrings.
+   If Python is built without docstrings, the value will be empty.
+
+   Use "PyDoc_STRVAR" for docstrings to support building Python
+   without docstrings, as specified in **PEP 7**.
+
+   Example:
+
+      PyDoc_STRVAR(pop_doc, "Remove and return the rightmost element.");
+
+      static PyMethodDef deque_methods[] = {
+          // ...
+          {"pop", (PyCFunction)deque_pop, METH_NOARGS, pop_doc},
+          // ...
+      }
+
+PyDoc_STR(str)
+
+   Creates a docstring for the given input string or an empty string
+   if docstrings are disabled.
+
+   Use "PyDoc_STR" in specifying docstrings to support building Python
+   without docstrings, as specified in **PEP 7**.
+
+   Example:
+
+      static PyMethodDef pysqlite_row_methods[] = {
+          {"keys", (PyCFunction)pysqlite_row_keys, METH_NOARGS,
+              PyDoc_STR("Returns the keys of the row.")},
+          {NULL, NULL}
+      };
+
+
+Objects, Types and Reference Counts
+===================================
+
+Most Python/C API functions have one or more arguments as well as a
+return value of type PyObject*.  This type is a pointer to an opaque
+data type representing an arbitrary Python object.  Since all Python
+object types are treated the same way by the Python language in most
+situations (e.g., assignments, scope rules, and argument passing), it
+is only fitting that they should be represented by a single C type.
+Almost all Python objects live on the heap: you never declare an
+automatic or static variable of type "PyObject", only pointer
+variables of type PyObject* can  be declared.  The sole exception are
+the type objects; since these must never be deallocated, they are
+typically static "PyTypeObject" objects.
+
+All Python objects (even Python integers) have a *type* and a
+*reference count*.  An object's type determines what kind of object it
+is (e.g., an integer, a list, or a user-defined function; there are
+many more as explained in The standard type hierarchy).  For each of
+the well-known types there is a macro to check whether an object is of
+that type; for instance, "PyList_Check(a)" is true if (and only if)
+the object pointed to by *a* is a Python list.
+
+
+Reference Counts
+----------------
+
+The reference count is important because today's computers have a
+finite (and often severely limited) memory size; it counts how many
+different places there are that have a *strong reference* to an
+object. Such a place could be another object, or a global (or static)
+C variable, or a local variable in some C function. When the last
+*strong reference* to an object is released (i.e. its reference count
+becomes zero), the object is deallocated. If it contains references to
+other objects, those references are released. Those other objects may
+be deallocated in turn, if there are no more references to them, and
+so on.  (There's an obvious problem  with objects that reference each
+other here; for now, the solution is "don't do that.")
+
+Reference counts are always manipulated explicitly.  The normal way is
+to use the macro "Py_INCREF()" to take a new reference to an object
+(i.e. increment its reference count by one), and "Py_DECREF()" to
+release that reference (i.e. decrement the reference count by one).
+The "Py_DECREF()" macro is considerably more complex than the incref
+one, since it must check whether the reference count becomes zero and
+then cause the object's deallocator to be called.  The deallocator is
+a function pointer contained in the object's type structure.  The
+type-specific deallocator takes care of releasing references for other
+objects contained in the object if this is a compound object type,
+such as a list, as well as performing any additional finalization
+that's needed.  There's no chance that the reference count can
+overflow; at least as many bits are used to hold the reference count
+as there are distinct memory locations in virtual memory (assuming
+"sizeof(Py_ssize_t) >= sizeof(void*)"). Thus, the reference count
+increment is a simple operation.
+
+It is not necessary to hold a *strong reference* (i.e. increment the
+reference count) for every local variable that contains a pointer to
+an object.  In theory, the  object's reference count goes up by one
+when the variable is made to  point to it and it goes down by one when
+the variable goes out of  scope.  However, these two cancel each other
+out, so at the end the  reference count hasn't changed.  The only real
+reason to use the  reference count is to prevent the object from being
+deallocated as  long as our variable is pointing to it.  If we know
+that there is at  least one other reference to the object that lives
+at least as long as our variable, there is no need to take a new
+*strong reference* (i.e. increment the reference count) temporarily.
+An important situation where this arises is in objects  that are
+passed as arguments to C functions in an extension module  that are
+called from Python; the call mechanism guarantees to hold a  reference
+to every argument for the duration of the call.
+
+However, a common pitfall is to extract an object from a list and hold
+on to it for a while without taking a new reference.  Some other
+operation might conceivably remove the object from the list, releasing
+that reference, and possibly deallocating it. The real danger is that
+innocent-looking operations may invoke arbitrary Python code which
+could do this; there is a code path which allows control to flow back
+to the user from a "Py_DECREF()", so almost any operation is
+potentially dangerous.
+
+A safe approach is to always use the generic operations (functions
+whose name begins with "PyObject_", "PyNumber_", "PySequence_" or
+"PyMapping_"). These operations always create a new *strong reference*
+(i.e. increment the reference count) of the object they return. This
+leaves the caller with the responsibility to call "Py_DECREF()" when
+they are done with the result; this soon becomes second nature.
+
+
+Reference Count Details
+~~~~~~~~~~~~~~~~~~~~~~~
+
+The reference count behavior of functions in the Python/C API is best
+explained in terms of *ownership of references*.  Ownership pertains
+to references, never to objects (objects are not owned: they are
+always shared).  "Owning a reference" means being responsible for
+calling Py_DECREF on it when the reference is no longer needed.
+Ownership can also be transferred, meaning that the code that receives
+ownership of the reference then becomes responsible for eventually
+releasing it by calling "Py_DECREF()" or "Py_XDECREF()" when it's no
+longer needed---or passing on this responsibility (usually to its
+caller). When a function passes ownership of a reference on to its
+caller, the caller is said to receive a *new* reference.  When no
+ownership is transferred, the caller is said to *borrow* the
+reference. Nothing needs to be done for a *borrowed reference*.
+
+Conversely, when a calling function passes in a reference to an
+object, there are two possibilities: the function *steals* a
+reference to the object, or it does not.  *Stealing a reference* means
+that when you pass a reference to a function, that function assumes
+that it now owns that reference, and you are not responsible for it
+any longer.
+
+Few functions steal references; the two notable exceptions are
+"PyList_SetItem()" and "PyTuple_SetItem()", which  steal a reference
+to the item (but not to the tuple or list into which the item is
+put!).  These functions were designed to steal a reference because of
+a common idiom for populating a tuple or list with newly created
+objects; for example, the code to create the tuple "(1, 2, "three")"
+could look like this (forgetting about error handling for the moment;
+a better way to code this is shown below):
+
+   PyObject *t;
+
+   t = PyTuple_New(3);
+   PyTuple_SetItem(t, 0, PyLong_FromLong(1L));
+   PyTuple_SetItem(t, 1, PyLong_FromLong(2L));
+   PyTuple_SetItem(t, 2, PyUnicode_FromString("three"));
+
+Here, "PyLong_FromLong()" returns a new reference which is immediately
+stolen by "PyTuple_SetItem()".  When you want to keep using an object
+although the reference to it will be stolen, use "Py_INCREF()" to grab
+another reference before calling the reference-stealing function.
+
+Incidentally, "PyTuple_SetItem()" is the *only* way to set tuple
+items; "PySequence_SetItem()" and "PyObject_SetItem()" refuse to do
+this since tuples are an immutable data type.  You should only use
+"PyTuple_SetItem()" for tuples that you are creating yourself.
+
+Equivalent code for populating a list can be written using
+"PyList_New()" and "PyList_SetItem()".
+
+However, in practice, you will rarely use these ways of creating and
+populating a tuple or list.  There's a generic function,
+"Py_BuildValue()", that can create most common objects from C values,
+directed by a *format string*. For example, the above two blocks of
+code could be replaced by the following (which also takes care of the
+error checking):
+
+   PyObject *tuple, *list;
+
+   tuple = Py_BuildValue("(iis)", 1, 2, "three");
+   list = Py_BuildValue("[iis]", 1, 2, "three");
+
+It is much more common to use "PyObject_SetItem()" and friends with
+items whose references you are only borrowing, like arguments that
+were passed in to the function you are writing.  In that case, their
+behaviour regarding references is much saner, since you don't have to
+take a new reference just so you can give that reference away ("have
+it be stolen").  For example, this function sets all items of a list
+(actually, any mutable sequence) to a given item:
+
+   int
+   set_all(PyObject *target, PyObject *item)
+   {
+       Py_ssize_t i, n;
+
+       n = PyObject_Length(target);
+       if (n < 0)
+           return -1;
+       for (i = 0; i < n; i++) {
+           PyObject *index = PyLong_FromSsize_t(i);
+           if (!index)
+               return -1;
+           if (PyObject_SetItem(target, index, item) < 0) {
+               Py_DECREF(index);
+               return -1;
+           }
+           Py_DECREF(index);
+       }
+       return 0;
+   }
+
+The situation is slightly different for function return values.
+While passing a reference to most functions does not change your
+ownership responsibilities for that reference, many functions that
+return a reference to an object give you ownership of the reference.
+The reason is simple: in many cases, the returned object is created
+on the fly, and the reference you get is the only reference to the
+object.  Therefore, the generic functions that return object
+references, like "PyObject_GetItem()" and  "PySequence_GetItem()",
+always return a new reference (the caller becomes the owner of the
+reference).
+
+It is important to realize that whether you own a reference returned
+by a function depends on which function you call only --- *the
+plumage* (the type of the object passed as an argument to the
+function) *doesn't enter into it!* Thus, if you  extract an item from
+a list using "PyList_GetItem()", you don't own the reference --- but
+if you obtain the same item from the same list using
+"PySequence_GetItem()" (which happens to take exactly the same
+arguments), you do own a reference to the returned object.
+
+Here is an example of how you could write a function that computes the
+sum of the items in a list of integers; once using
+"PyList_GetItem()", and once using "PySequence_GetItem()".
+
+   long
+   sum_list(PyObject *list)
+   {
+       Py_ssize_t i, n;
+       long total = 0, value;
+       PyObject *item;
+
+       n = PyList_Size(list);
+       if (n < 0)
+           return -1; /* Not a list */
+       for (i = 0; i < n; i++) {
+           item = PyList_GetItem(list, i); /* Can't fail */
+           if (!PyLong_Check(item)) continue; /* Skip non-integers */
+           value = PyLong_AsLong(item);
+           if (value == -1 && PyErr_Occurred())
+               /* Integer too big to fit in a C long, bail out */
+               return -1;
+           total += value;
+       }
+       return total;
+   }
+
+   long
+   sum_sequence(PyObject *sequence)
+   {
+       Py_ssize_t i, n;
+       long total = 0, value;
+       PyObject *item;
+       n = PySequence_Length(sequence);
+       if (n < 0)
+           return -1; /* Has no length */
+       for (i = 0; i < n; i++) {
+           item = PySequence_GetItem(sequence, i);
+           if (item == NULL)
+               return -1; /* Not a sequence, or other failure */
+           if (PyLong_Check(item)) {
+               value = PyLong_AsLong(item);
+               Py_DECREF(item);
+               if (value == -1 && PyErr_Occurred())
+                   /* Integer too big to fit in a C long, bail out */
+                   return -1;
+               total += value;
+           }
+           else {
+               Py_DECREF(item); /* Discard reference ownership */
+           }
+       }
+       return total;
+   }
+
+
+Types
+-----
+
+There are few other data types that play a significant role in  the
+Python/C API; most are simple C types such as int,  long, double and
+char*.  A few structure types  are used to describe static tables used
+to list the functions exported  by a module or the data attributes of
+a new object type, and another is used to describe the value of a
+complex number.  These will  be discussed together with the functions
+that use them.
+
+type Py_ssize_t
+    * Part of the Stable ABI.*
+
+   A signed integral type such that "sizeof(Py_ssize_t) ==
+   sizeof(size_t)". C99 doesn't define such a thing directly (size_t
+   is an unsigned integral type). See **PEP 353** for details.
+   "PY_SSIZE_T_MAX" is the largest positive value of type
+   "Py_ssize_t".
+
+
+Exceptions
+==========
+
+The Python programmer only needs to deal with exceptions if specific
+error handling is required; unhandled exceptions are automatically
+propagated to the caller, then to the caller's caller, and so on,
+until they reach the top-level interpreter, where they are reported to
+the  user accompanied by a stack traceback.
+
+For C programmers, however, error checking always has to be explicit.
+All functions in the Python/C API can raise exceptions, unless an
+explicit claim is made otherwise in a function's documentation.  In
+general, when a function encounters an error, it sets an exception,
+discards any object references that it owns, and returns an error
+indicator.  If not documented otherwise, this indicator is either
+"NULL" or "-1", depending on the function's return type. A few
+functions return a Boolean true/false result, with false indicating an
+error.  Very few functions return no explicit error indicator or have
+an ambiguous return value, and require explicit testing for errors
+with "PyErr_Occurred()".  These exceptions are always explicitly
+documented.
+
+Exception state is maintained in per-thread storage (this is
+equivalent to using global storage in an unthreaded application).  A
+thread can be in one of two states: an exception has occurred, or not.
+The function "PyErr_Occurred()" can be used to check for this: it
+returns a borrowed reference to the exception type object when an
+exception has occurred, and "NULL" otherwise.  There are a number of
+functions to set the exception state: "PyErr_SetString()" is the most
+common (though not the most general) function to set the exception
+state, and "PyErr_Clear()" clears the exception state.
+
+The full exception state consists of three objects (all of which can
+be "NULL"): the exception type, the corresponding exception  value,
+and the traceback.  These have the same meanings as the Python result
+of "sys.exc_info()"; however, they are not the same: the Python
+objects represent the last exception being handled by a Python  "try"
+... "except" statement, while the C level exception state only exists
+while an exception is being passed on between C functions until it
+reaches the Python bytecode interpreter's  main loop, which takes care
+of transferring it to "sys.exc_info()" and friends.
+
+Note that starting with Python 1.5, the preferred, thread-safe way to
+access the exception state from Python code is to call the function
+"sys.exc_info()", which returns the per-thread exception state for
+Python code.  Also, the semantics of both ways to access the exception
+state have changed so that a function which catches an exception will
+save and restore its thread's exception state so as to preserve the
+exception state of its caller.  This prevents common bugs in exception
+handling code caused by an innocent-looking function overwriting the
+exception being handled; it also reduces the often unwanted lifetime
+extension for objects that are referenced by the stack frames in the
+traceback.
+
+As a general principle, a function that calls another function to
+perform some task should check whether the called function raised an
+exception, and if so, pass the exception state on to its caller.  It
+should discard any object references that it owns, and return an
+error indicator, but it should *not* set another exception --- that
+would overwrite the exception that was just raised, and lose important
+information about the exact cause of the error.
+
+A simple example of detecting exceptions and passing them on is shown
+in the "sum_sequence()" example above.  It so happens that this
+example doesn't need to clean up any owned references when it detects
+an error.  The following example function shows some error cleanup.
+First, to remind you why you like Python, we show the equivalent
+Python code:
+
+   def incr_item(dict, key):
+       try:
+           item = dict[key]
+       except KeyError:
+           item = 0
+       dict[key] = item + 1
+
+Here is the corresponding C code, in all its glory:
+
+   int
+   incr_item(PyObject *dict, PyObject *key)
+   {
+       /* Objects all initialized to NULL for Py_XDECREF */
+       PyObject *item = NULL, *const_one = NULL, *incremented_item = NULL;
+       int rv = -1; /* Return value initialized to -1 (failure) */
+
+       item = PyObject_GetItem(dict, key);
+       if (item == NULL) {
+           /* Handle KeyError only: */
+           if (!PyErr_ExceptionMatches(PyExc_KeyError))
+               goto error;
+
+           /* Clear the error and use zero: */
+           PyErr_Clear();
+           item = PyLong_FromLong(0L);
+           if (item == NULL)
+               goto error;
+       }
+       const_one = PyLong_FromLong(1L);
+       if (const_one == NULL)
+           goto error;
+
+       incremented_item = PyNumber_Add(item, const_one);
+       if (incremented_item == NULL)
+           goto error;
+
+       if (PyObject_SetItem(dict, key, incremented_item) < 0)
+           goto error;
+       rv = 0; /* Success */
+       /* Continue with cleanup code */
+
+    error:
+       /* Cleanup code, shared by success and failure path */
+
+       /* Use Py_XDECREF() to ignore NULL references */
+       Py_XDECREF(item);
+       Py_XDECREF(const_one);
+       Py_XDECREF(incremented_item);
+
+       return rv; /* -1 for error, 0 for success */
+   }
+
+This example represents an endorsed use of the "goto" statement  in C!
+It illustrates the use of "PyErr_ExceptionMatches()" and
+"PyErr_Clear()" to handle specific exceptions, and the use of
+"Py_XDECREF()" to dispose of owned references that may be "NULL" (note
+the "'X'" in the name; "Py_DECREF()" would crash when confronted with
+a "NULL" reference).  It is important that the variables used to hold
+owned references are initialized to "NULL" for this to work; likewise,
+the proposed return value is initialized to "-1" (failure) and only
+set to success after the final call made is successful.
+
+
+Embedding Python
+================
+
+The one important task that only embedders (as opposed to extension
+writers) of the Python interpreter have to worry about is the
+initialization, and possibly the finalization, of the Python
+interpreter.  Most functionality of the interpreter can only be used
+after the interpreter has been initialized.
+
+The basic initialization function is "Py_Initialize()". This
+initializes the table of loaded modules, and creates the fundamental
+modules "builtins", "__main__", and "sys".  It also initializes the
+module search path ("sys.path").
+
+"Py_Initialize()" does not set the "script argument list"
+("sys.argv"). If this variable is needed by Python code that will be
+executed later, setting "PyConfig.argv" and "PyConfig.parse_argv" must
+be set: see Python Initialization Configuration.
+
+On most systems (in particular, on Unix and Windows, although the
+details are slightly different), "Py_Initialize()" calculates the
+module search path based upon its best guess for the location of the
+standard Python interpreter executable, assuming that the Python
+library is found in a fixed location relative to the Python
+interpreter executable.  In particular, it looks for a directory named
+"lib/python*X.Y*" relative to the parent directory where the
+executable named "python" is found on the shell command search path
+(the environment variable "PATH").
+
+For instance, if the Python executable is found in
+"/usr/local/bin/python", it will assume that the libraries are in
+"/usr/local/lib/python*X.Y*".  (In fact, this particular path is also
+the "fallback" location, used when no executable file named "python"
+is found along "PATH".)  The user can override this behavior by
+setting the environment variable "PYTHONHOME", or insert additional
+directories in front of the standard path by setting "PYTHONPATH".
+
+The embedding application can steer the search by calling
+"Py_SetProgramName(file)" *before* calling  "Py_Initialize()".  Note
+that "PYTHONHOME" still overrides this and "PYTHONPATH" is still
+inserted in front of the standard path.  An application that requires
+total control has to provide its own implementation of "Py_GetPath()",
+"Py_GetPrefix()", "Py_GetExecPrefix()", and "Py_GetProgramFullPath()"
+(all defined in "Modules/getpath.c").
+
+Sometimes, it is desirable to "uninitialize" Python.  For instance,
+the application may want to start over (make another call to
+"Py_Initialize()") or the application is simply done with its  use of
+Python and wants to free memory allocated by Python.  This can be
+accomplished by calling "Py_FinalizeEx()".  The function
+"Py_IsInitialized()" returns true if Python is currently in the
+initialized state.  More information about these functions is given in
+a later chapter. Notice that "Py_FinalizeEx()" does *not* free all
+memory allocated by the Python interpreter, e.g. memory allocated by
+extension modules currently cannot be released.
+
+
+Debugging Builds
+================
+
+Python can be built with several macros to enable extra checks of the
+interpreter and extension modules.  These checks tend to add a large
+amount of overhead to the runtime so they are not enabled by default.
+
+A full list of the various types of debugging builds is in the file
+"Misc/SpecialBuilds.txt" in the Python source distribution. Builds are
+available that support tracing of reference counts, debugging the
+memory allocator, or low-level profiling of the main interpreter loop.
+Only the most frequently used builds will be described in the
+remainder of this section.
+
+Py_DEBUG
+
+Compiling the interpreter with the "Py_DEBUG" macro defined produces
+what is generally meant by a debug build of Python. "Py_DEBUG" is
+enabled in the Unix build by adding "--with-pydebug" to the
+"./configure" command. It is also implied by the presence of the not-
+Python-specific "_DEBUG" macro.  When "Py_DEBUG" is enabled in the
+Unix build, compiler optimization is disabled.
+
+In addition to the reference count debugging described below, extra
+checks are performed, see Python Debug Build.
+
+Defining "Py_TRACE_REFS" enables reference tracing (see the "configure
+--with-trace-refs option"). When defined, a circular doubly linked
+list of active objects is maintained by adding two extra fields to
+every "PyObject".  Total allocations are tracked as well.  Upon exit,
+all existing references are printed.  (In interactive mode this
+happens after every statement run by the interpreter.)
+
+Please refer to "Misc/SpecialBuilds.txt" in the Python source
+distribution for more detailed information.

python-3.12.6-docs-text/python-3.12.6-docs-text/c-api/iter.txt

@@ -0,0 +1,76 @@
+Iterator Protocol
+*****************
+
+There are two functions specifically for working with iterators.
+
+int PyIter_Check(PyObject *o)
+    * Part of the Stable ABI since version 3.8.*
+
+   Return non-zero if the object *o* can be safely passed to
+   "PyIter_Next()", and "0" otherwise.  This function always succeeds.
+
+int PyAIter_Check(PyObject *o)
+    * Part of the Stable ABI since version 3.10.*
+
+   Return non-zero if the object *o* provides the "AsyncIterator"
+   protocol, and "0" otherwise.  This function always succeeds.
+
+   Added in version 3.10.
+
+PyObject *PyIter_Next(PyObject *o)
+    *Return value: New reference.** Part of the Stable ABI.*
+
+   Return the next value from the iterator *o*.  The object must be an
+   iterator according to "PyIter_Check()" (it is up to the caller to
+   check this). If there are no remaining values, returns "NULL" with
+   no exception set. If an error occurs while retrieving the item,
+   returns "NULL" and passes along the exception.
+
+To write a loop which iterates over an iterator, the C code should
+look something like this:
+
+   PyObject *iterator = PyObject_GetIter(obj);
+   PyObject *item;
+
+   if (iterator == NULL) {
+       /* propagate error */
+   }
+
+   while ((item = PyIter_Next(iterator))) {
+       /* do something with item */
+       ...
+       /* release reference when done */
+       Py_DECREF(item);
+   }
+
+   Py_DECREF(iterator);
+
+   if (PyErr_Occurred()) {
+       /* propagate error */
+   }
+   else {
+       /* continue doing useful work */
+   }
+
+type PySendResult
+
+   The enum value used to represent different results of
+   "PyIter_Send()".
+
+   Added in version 3.10.
+
+PySendResult PyIter_Send(PyObject *iter, PyObject *arg, PyObject **presult)
+    * Part of the Stable ABI since version 3.10.*
+
+   Sends the *arg* value into the iterator *iter*. Returns:
+
+   * "PYGEN_RETURN" if iterator returns. Return value is returned via
+     *presult*.
+
+   * "PYGEN_NEXT" if iterator yields. Yielded value is returned via
+     *presult*.
+
+   * "PYGEN_ERROR" if iterator has raised and exception. *presult* is
+     set to "NULL".
+
+   Added in version 3.10.

python-3.12.6-docs-text/python-3.12.6-docs-text/c-api/iterator.txt

@@ -0,0 +1,47 @@
+Iterator Objects
+****************
+
+Python provides two general-purpose iterator objects.  The first, a
+sequence iterator, works with an arbitrary sequence supporting the
+"__getitem__()" method.  The second works with a callable object and a
+sentinel value, calling the callable for each item in the sequence,
+and ending the iteration when the sentinel value is returned.
+
+PyTypeObject PySeqIter_Type
+    * Part of the Stable ABI.*
+
+   Type object for iterator objects returned by "PySeqIter_New()" and
+   the one-argument form of the "iter()" built-in function for built-
+   in sequence types.
+
+int PySeqIter_Check(PyObject *op)
+
+   Return true if the type of *op* is "PySeqIter_Type".  This function
+   always succeeds.
+
+PyObject *PySeqIter_New(PyObject *seq)
+    *Return value: New reference.** Part of the Stable ABI.*
+
+   Return an iterator that works with a general sequence object,
+   *seq*.  The iteration ends when the sequence raises "IndexError"
+   for the subscripting operation.
+
+PyTypeObject PyCallIter_Type
+    * Part of the Stable ABI.*
+
+   Type object for iterator objects returned by "PyCallIter_New()" and
+   the two-argument form of the "iter()" built-in function.
+
+int PyCallIter_Check(PyObject *op)
+
+   Return true if the type of *op* is "PyCallIter_Type".  This
+   function always succeeds.
+
+PyObject *PyCallIter_New(PyObject *callable, PyObject *sentinel)
+    *Return value: New reference.** Part of the Stable ABI.*
+
+   Return a new iterator.  The first parameter, *callable*, can be any
+   Python callable object that can be called with no parameters; each
+   call to it should return the next item in the iteration.  When
+   *callable* returns a value equal to *sentinel*, the iteration will
+   be terminated.

python-3.12.6-docs-text/python-3.12.6-docs-text/c-api/list.txt

@@ -0,0 +1,133 @@
+List Objects
+************
+
+type PyListObject
+
+   This subtype of "PyObject" represents a Python list object.
+
+PyTypeObject PyList_Type
+    * Part of the Stable ABI.*
+
+   This instance of "PyTypeObject" represents the Python list type.
+   This is the same object as "list" in the Python layer.
+
+int PyList_Check(PyObject *p)
+
+   Return true if *p* is a list object or an instance of a subtype of
+   the list type.  This function always succeeds.
+
+int PyList_CheckExact(PyObject *p)
+
+   Return true if *p* is a list object, but not an instance of a
+   subtype of the list type.  This function always succeeds.
+
+PyObject *PyList_New(Py_ssize_t len)
+    *Return value: New reference.** Part of the Stable ABI.*
+
+   Return a new list of length *len* on success, or "NULL" on failure.
+
+   Note:
+
+     If *len* is greater than zero, the returned list object's items
+     are set to "NULL".  Thus you cannot use abstract API functions
+     such as "PySequence_SetItem()"  or expose the object to Python
+     code before setting all items to a real object with
+     "PyList_SetItem()".
+
+Py_ssize_t PyList_Size(PyObject *list)
+    * Part of the Stable ABI.*
+
+   Return the length of the list object in *list*; this is equivalent
+   to "len(list)" on a list object.
+
+Py_ssize_t PyList_GET_SIZE(PyObject *list)
+
+   Similar to "PyList_Size()", but without error checking.
+
+PyObject *PyList_GetItem(PyObject *list, Py_ssize_t index)
+    *Return value: Borrowed reference.** Part of the Stable ABI.*
+
+   Return the object at position *index* in the list pointed to by
+   *list*.  The position must be non-negative; indexing from the end
+   of the list is not supported.  If *index* is out of bounds (<0 or
+   >=len(list)), return "NULL" and set an "IndexError" exception.
+
+PyObject *PyList_GET_ITEM(PyObject *list, Py_ssize_t i)
+    *Return value: Borrowed reference.*
+
+   Similar to "PyList_GetItem()", but without error checking.
+
+int PyList_SetItem(PyObject *list, Py_ssize_t index, PyObject *item)
+    * Part of the Stable ABI.*
+
+   Set the item at index *index* in list to *item*.  Return "0" on
+   success. If *index* is out of bounds, return "-1" and set an
+   "IndexError" exception.
+
+   Note:
+
+     This function "steals" a reference to *item* and discards a
+     reference to an item already in the list at the affected
+     position.
+
+void PyList_SET_ITEM(PyObject *list, Py_ssize_t i, PyObject *o)
+
+   Macro form of "PyList_SetItem()" without error checking. This is
+   normally only used to fill in new lists where there is no previous
+   content.
+
+   Note:
+
+     This macro "steals" a reference to *item*, and, unlike
+     "PyList_SetItem()", does *not* discard a reference to any item
+     that is being replaced; any reference in *list* at position *i*
+     will be leaked.
+
+int PyList_Insert(PyObject *list, Py_ssize_t index, PyObject *item)
+    * Part of the Stable ABI.*
+
+   Insert the item *item* into list *list* in front of index *index*.
+   Return "0" if successful; return "-1" and set an exception if
+   unsuccessful. Analogous to "list.insert(index, item)".
+
+int PyList_Append(PyObject *list, PyObject *item)
+    * Part of the Stable ABI.*
+
+   Append the object *item* at the end of list *list*. Return "0" if
+   successful; return "-1" and set an exception if unsuccessful.
+   Analogous to "list.append(item)".
+
+PyObject *PyList_GetSlice(PyObject *list, Py_ssize_t low, Py_ssize_t high)
+    *Return value: New reference.** Part of the Stable ABI.*
+
+   Return a list of the objects in *list* containing the objects
+   *between* *low* and *high*.  Return "NULL" and set an exception if
+   unsuccessful.  Analogous to "list[low:high]".  Indexing from the
+   end of the list is not supported.
+
+int PyList_SetSlice(PyObject *list, Py_ssize_t low, Py_ssize_t high, PyObject *itemlist)
+    * Part of the Stable ABI.*
+
+   Set the slice of *list* between *low* and *high* to the contents of
+   *itemlist*.  Analogous to "list[low:high] = itemlist". The
+   *itemlist* may be "NULL", indicating the assignment of an empty
+   list (slice deletion). Return "0" on success, "-1" on failure.
+   Indexing from the end of the list is not supported.
+
+int PyList_Sort(PyObject *list)
+    * Part of the Stable ABI.*
+
+   Sort the items of *list* in place.  Return "0" on success, "-1" on
+   failure.  This is equivalent to "list.sort()".
+
+int PyList_Reverse(PyObject *list)
+    * Part of the Stable ABI.*
+
+   Reverse the items of *list* in place.  Return "0" on success, "-1"
+   on failure.  This is the equivalent of "list.reverse()".
+
+PyObject *PyList_AsTuple(PyObject *list)
+    *Return value: New reference.** Part of the Stable ABI.*
+
+   Return a new tuple object containing the contents of *list*;
+   equivalent to "tuple(list)".

python-3.12.6-docs-text/python-3.12.6-docs-text/c-api/long.txt

@@ -0,0 +1,331 @@
+Integer Objects
+***************
+
+All integers are implemented as "long" integer objects of arbitrary
+size.
+
+On error, most "PyLong_As*" APIs return "(return type)-1" which cannot
+be distinguished from a number.  Use "PyErr_Occurred()" to
+disambiguate.
+
+type PyLongObject
+    * Part of the Limited API (as an opaque struct).*
+
+   This subtype of "PyObject" represents a Python integer object.
+
+PyTypeObject PyLong_Type
+    * Part of the Stable ABI.*
+
+   This instance of "PyTypeObject" represents the Python integer type.
+   This is the same object as "int" in the Python layer.
+
+int PyLong_Check(PyObject *p)
+
+   Return true if its argument is a "PyLongObject" or a subtype of
+   "PyLongObject".  This function always succeeds.
+
+int PyLong_CheckExact(PyObject *p)
+
+   Return true if its argument is a "PyLongObject", but not a subtype
+   of "PyLongObject".  This function always succeeds.
+
+PyObject *PyLong_FromLong(long v)
+    *Return value: New reference.** Part of the Stable ABI.*
+
+   Return a new "PyLongObject" object from *v*, or "NULL" on failure.
+
+   The current implementation keeps an array of integer objects for
+   all integers between "-5" and "256". When you create an int in that
+   range you actually just get back a reference to the existing
+   object.
+
+PyObject *PyLong_FromUnsignedLong(unsigned long v)
+    *Return value: New reference.** Part of the Stable ABI.*
+
+   Return a new "PyLongObject" object from a C unsigned long, or
+   "NULL" on failure.
+
+PyObject *PyLong_FromSsize_t(Py_ssize_t v)
+    *Return value: New reference.** Part of the Stable ABI.*
+
+   Return a new "PyLongObject" object from a C "Py_ssize_t", or "NULL"
+   on failure.
+
+PyObject *PyLong_FromSize_t(size_t v)
+    *Return value: New reference.** Part of the Stable ABI.*
+
+   Return a new "PyLongObject" object from a C "size_t", or "NULL" on
+   failure.
+
+PyObject *PyLong_FromLongLong(long long v)
+    *Return value: New reference.** Part of the Stable ABI.*
+
+   Return a new "PyLongObject" object from a C long long, or "NULL" on
+   failure.
+
+PyObject *PyLong_FromUnsignedLongLong(unsigned long long v)
+    *Return value: New reference.** Part of the Stable ABI.*
+
+   Return a new "PyLongObject" object from a C unsigned long long, or
+   "NULL" on failure.
+
+PyObject *PyLong_FromDouble(double v)
+    *Return value: New reference.** Part of the Stable ABI.*
+
+   Return a new "PyLongObject" object from the integer part of *v*, or
+   "NULL" on failure.
+
+PyObject *PyLong_FromString(const char *str, char **pend, int base)
+    *Return value: New reference.** Part of the Stable ABI.*
+
+   Return a new "PyLongObject" based on the string value in *str*,
+   which is interpreted according to the radix in *base*, or "NULL" on
+   failure.  If *pend* is non-"NULL", **pend* will point to the end of
+   *str* on success or to the first character that could not be
+   processed on error.  If *base* is "0", *str* is interpreted using
+   the Integer literals definition; in this case, leading zeros in a
+   non-zero decimal number raises a "ValueError".  If *base* is not
+   "0", it must be between "2" and "36", inclusive.  Leading and
+   trailing whitespace and single underscores after a base specifier
+   and between digits are ignored.  If there are no digits or *str* is
+   not NULL-terminated following the digits and trailing whitespace,
+   "ValueError" will be raised.
+
+   See also:
+
+     Python methods "int.to_bytes()" and "int.from_bytes()" to convert
+     a "PyLongObject" to/from an array of bytes in base "256". You can
+     call those from C using "PyObject_CallMethod()".
+
+PyObject *PyLong_FromUnicodeObject(PyObject *u, int base)
+    *Return value: New reference.*
+
+   Convert a sequence of Unicode digits in the string *u* to a Python
+   integer value.
+
+   Added in version 3.3.
+
+PyObject *PyLong_FromVoidPtr(void *p)
+    *Return value: New reference.** Part of the Stable ABI.*
+
+   Create a Python integer from the pointer *p*. The pointer value can
+   be retrieved from the resulting value using "PyLong_AsVoidPtr()".
+
+long PyLong_AsLong(PyObject *obj)
+    * Part of the Stable ABI.*
+
+   Return a C long representation of *obj*.  If *obj* is not an
+   instance of "PyLongObject", first call its "__index__()" method (if
+   present) to convert it to a "PyLongObject".
+
+   Raise "OverflowError" if the value of *obj* is out of range for a
+   long.
+
+   Returns "-1" on error.  Use "PyErr_Occurred()" to disambiguate.
+
+   Changed in version 3.8: Use "__index__()" if available.
+
+   Changed in version 3.10: This function will no longer use
+   "__int__()".
+
+long PyLong_AsLongAndOverflow(PyObject *obj, int *overflow)
+    * Part of the Stable ABI.*
+
+   Return a C long representation of *obj*.  If *obj* is not an
+   instance of "PyLongObject", first call its "__index__()" method (if
+   present) to convert it to a "PyLongObject".
+
+   If the value of *obj* is greater than "LONG_MAX" or less than
+   "LONG_MIN", set **overflow* to "1" or "-1", respectively, and
+   return "-1"; otherwise, set **overflow* to "0".  If any other
+   exception occurs set **overflow* to "0" and return "-1" as usual.
+
+   Returns "-1" on error.  Use "PyErr_Occurred()" to disambiguate.
+
+   Changed in version 3.8: Use "__index__()" if available.
+
+   Changed in version 3.10: This function will no longer use
+   "__int__()".
+
+long long PyLong_AsLongLong(PyObject *obj)
+    * Part of the Stable ABI.*
+
+   Return a C long long representation of *obj*.  If *obj* is not an
+   instance of "PyLongObject", first call its "__index__()" method (if
+   present) to convert it to a "PyLongObject".
+
+   Raise "OverflowError" if the value of *obj* is out of range for a
+   long long.
+
+   Returns "-1" on error.  Use "PyErr_Occurred()" to disambiguate.
+
+   Changed in version 3.8: Use "__index__()" if available.
+
+   Changed in version 3.10: This function will no longer use
+   "__int__()".
+
+long long PyLong_AsLongLongAndOverflow(PyObject *obj, int *overflow)
+    * Part of the Stable ABI.*
+
+   Return a C long long representation of *obj*.  If *obj* is not an
+   instance of "PyLongObject", first call its "__index__()" method (if
+   present) to convert it to a "PyLongObject".
+
+   If the value of *obj* is greater than "LLONG_MAX" or less than
+   "LLONG_MIN", set **overflow* to "1" or "-1", respectively, and
+   return "-1"; otherwise, set **overflow* to "0".  If any other
+   exception occurs set **overflow* to "0" and return "-1" as usual.
+
+   Returns "-1" on error.  Use "PyErr_Occurred()" to disambiguate.
+
+   Added in version 3.2.
+
+   Changed in version 3.8: Use "__index__()" if available.
+
+   Changed in version 3.10: This function will no longer use
+   "__int__()".
+
+Py_ssize_t PyLong_AsSsize_t(PyObject *pylong)
+    * Part of the Stable ABI.*
+
+   Return a C "Py_ssize_t" representation of *pylong*.  *pylong* must
+   be an instance of "PyLongObject".
+
+   Raise "OverflowError" if the value of *pylong* is out of range for
+   a "Py_ssize_t".
+
+   Returns "-1" on error.  Use "PyErr_Occurred()" to disambiguate.
+
+unsigned long PyLong_AsUnsignedLong(PyObject *pylong)
+    * Part of the Stable ABI.*
+
+   Return a C unsigned long representation of *pylong*.  *pylong* must
+   be an instance of "PyLongObject".
+
+   Raise "OverflowError" if the value of *pylong* is out of range for
+   a unsigned long.
+
+   Returns "(unsigned long)-1" on error. Use "PyErr_Occurred()" to
+   disambiguate.
+
+size_t PyLong_AsSize_t(PyObject *pylong)
+    * Part of the Stable ABI.*
+
+   Return a C "size_t" representation of *pylong*.  *pylong* must be
+   an instance of "PyLongObject".
+
+   Raise "OverflowError" if the value of *pylong* is out of range for
+   a "size_t".
+
+   Returns "(size_t)-1" on error. Use "PyErr_Occurred()" to
+   disambiguate.
+
+unsigned long long PyLong_AsUnsignedLongLong(PyObject *pylong)
+    * Part of the Stable ABI.*
+
+   Return a C unsigned long long representation of *pylong*.  *pylong*
+   must be an instance of "PyLongObject".
+
+   Raise "OverflowError" if the value of *pylong* is out of range for
+   an unsigned long long.
+
+   Returns "(unsigned long long)-1" on error. Use "PyErr_Occurred()"
+   to disambiguate.
+
+   Changed in version 3.1: A negative *pylong* now raises
+   "OverflowError", not "TypeError".
+
+unsigned long PyLong_AsUnsignedLongMask(PyObject *obj)
+    * Part of the Stable ABI.*
+
+   Return a C unsigned long representation of *obj*.  If *obj* is not
+   an instance of "PyLongObject", first call its "__index__()" method
+   (if present) to convert it to a "PyLongObject".
+
+   If the value of *obj* is out of range for an unsigned long, return
+   the reduction of that value modulo "ULONG_MAX + 1".
+
+   Returns "(unsigned long)-1" on error.  Use "PyErr_Occurred()" to
+   disambiguate.
+
+   Changed in version 3.8: Use "__index__()" if available.
+
+   Changed in version 3.10: This function will no longer use
+   "__int__()".
+
+unsigned long long PyLong_AsUnsignedLongLongMask(PyObject *obj)
+    * Part of the Stable ABI.*
+
+   Return a C unsigned long long representation of *obj*.  If *obj* is
+   not an instance of "PyLongObject", first call its "__index__()"
+   method (if present) to convert it to a "PyLongObject".
+
+   If the value of *obj* is out of range for an unsigned long long,
+   return the reduction of that value modulo "ULLONG_MAX + 1".
+
+   Returns "(unsigned long long)-1" on error.  Use "PyErr_Occurred()"
+   to disambiguate.
+
+   Changed in version 3.8: Use "__index__()" if available.
+
+   Changed in version 3.10: This function will no longer use
+   "__int__()".
+
+double PyLong_AsDouble(PyObject *pylong)
+    * Part of the Stable ABI.*
+
+   Return a C double representation of *pylong*.  *pylong* must be an
+   instance of "PyLongObject".
+
+   Raise "OverflowError" if the value of *pylong* is out of range for
+   a double.
+
+   Returns "-1.0" on error.  Use "PyErr_Occurred()" to disambiguate.
+
+void *PyLong_AsVoidPtr(PyObject *pylong)
+    * Part of the Stable ABI.*
+
+   Convert a Python integer *pylong* to a C void pointer. If *pylong*
+   cannot be converted, an "OverflowError" will be raised.  This is
+   only assured to produce a usable void pointer for values created
+   with "PyLong_FromVoidPtr()".
+
+   Returns "NULL" on error.  Use "PyErr_Occurred()" to disambiguate.
+
+PyObject *PyLong_GetInfo(void)
+    * Part of the Stable ABI.*
+
+   On success, return a read only *named tuple*, that holds
+   information about Python's internal representation of integers. See
+   "sys.int_info" for description of individual fields.
+
+   On failure, return "NULL" with an exception set.
+
+   Added in version 3.1.
+
+int PyUnstable_Long_IsCompact(const PyLongObject *op)
+
+   *This is Unstable API. It may change without warning in minor
+   releases.*
+
+   Return 1 if *op* is compact, 0 otherwise.
+
+   This function makes it possible for performance-critical code to
+   implement a “fast path” for small integers. For compact values use
+   "PyUnstable_Long_CompactValue()"; for others fall back to a
+   "PyLong_As*" function or "calling" "int.to_bytes()".
+
+   The speedup is expected to be negligible for most users.
+
+   Exactly what values are considered compact is an implementation
+   detail and is subject to change.
+
+Py_ssize_t PyUnstable_Long_CompactValue(const PyLongObject *op)
+
+   *This is Unstable API. It may change without warning in minor
+   releases.*
+
+   If *op* is compact, as determined by "PyUnstable_Long_IsCompact()",
+   return its value.
+
+   Otherwise, the return value is undefined.

python-3.12.6-docs-text/python-3.12.6-docs-text/c-api/mapping.txt

@@ -0,0 +1,96 @@
+Mapping Protocol
+****************
+
+See also "PyObject_GetItem()", "PyObject_SetItem()" and
+"PyObject_DelItem()".
+
+int PyMapping_Check(PyObject *o)
+    * Part of the Stable ABI.*
+
+   Return "1" if the object provides the mapping protocol or supports
+   slicing, and "0" otherwise.  Note that it returns "1" for Python
+   classes with a "__getitem__()" method, since in general it is
+   impossible to determine what type of keys the class supports. This
+   function always succeeds.
+
+Py_ssize_t PyMapping_Size(PyObject *o)
+Py_ssize_t PyMapping_Length(PyObject *o)
+    * Part of the Stable ABI.*
+
+   Returns the number of keys in object *o* on success, and "-1" on
+   failure. This is equivalent to the Python expression "len(o)".
+
+PyObject *PyMapping_GetItemString(PyObject *o, const char *key)
+    *Return value: New reference.** Part of the Stable ABI.*
+
+   This is the same as "PyObject_GetItem()", but *key* is specified as
+   a const char* UTF-8 encoded bytes string, rather than a PyObject*.
+
+int PyMapping_SetItemString(PyObject *o, const char *key, PyObject *v)
+    * Part of the Stable ABI.*
+
+   This is the same as "PyObject_SetItem()", but *key* is specified as
+   a const char* UTF-8 encoded bytes string, rather than a PyObject*.
+
+int PyMapping_DelItem(PyObject *o, PyObject *key)
+
+   This is an alias of "PyObject_DelItem()".
+
+int PyMapping_DelItemString(PyObject *o, const char *key)
+
+   This is the same as "PyObject_DelItem()", but *key* is specified as
+   a const char* UTF-8 encoded bytes string, rather than a PyObject*.
+
+int PyMapping_HasKey(PyObject *o, PyObject *key)
+    * Part of the Stable ABI.*
+
+   Return "1" if the mapping object has the key *key* and "0"
+   otherwise. This is equivalent to the Python expression "key in o".
+   This function always succeeds.
+
+   Note:
+
+     Exceptions which occur when this calls "__getitem__()" method are
+     silently ignored. For proper error handling, use
+     "PyObject_GetItem()" instead.
+
+int PyMapping_HasKeyString(PyObject *o, const char *key)
+    * Part of the Stable ABI.*
+
+   This is the same as "PyMapping_HasKey()", but *key* is specified as
+   a const char* UTF-8 encoded bytes string, rather than a PyObject*.
+
+   Note:
+
+     Exceptions that occur when this calls "__getitem__()" method or
+     while creating the temporary "str" object are silently ignored.
+     For proper error handling, use "PyMapping_GetItemString()"
+     instead.
+
+PyObject *PyMapping_Keys(PyObject *o)
+    *Return value: New reference.** Part of the Stable ABI.*
+
+   On success, return a list of the keys in object *o*.  On failure,
+   return "NULL".
+
+   Changed in version 3.7: Previously, the function returned a list or
+   a tuple.
+
+PyObject *PyMapping_Values(PyObject *o)
+    *Return value: New reference.** Part of the Stable ABI.*
+
+   On success, return a list of the values in object *o*.  On failure,
+   return "NULL".
+
+   Changed in version 3.7: Previously, the function returned a list or
+   a tuple.
+
+PyObject *PyMapping_Items(PyObject *o)
+    *Return value: New reference.** Part of the Stable ABI.*
+
+   On success, return a list of the items in object *o*, where each
+   item is a tuple containing a key-value pair.  On failure, return
+   "NULL".
+
+   Changed in version 3.7: Previously, the function returned a list or
+   a tuple.

python-3.12.6-docs-text/python-3.12.6-docs-text/c-api/marshal.txt

@@ -0,0 +1,92 @@
+Data marshalling support
+************************
+
+These routines allow C code to work with serialized objects using the
+same data format as the "marshal" module.  There are functions to
+write data into the serialization format, and additional functions
+that can be used to read the data back.  Files used to store
+marshalled data must be opened in binary mode.
+
+Numeric values are stored with the least significant byte first.
+
+The module supports two versions of the data format: version 0 is the
+historical version, version 1 shares interned strings in the file, and
+upon unmarshalling.  Version 2 uses a binary format for floating-point
+numbers. "Py_MARSHAL_VERSION" indicates the current file format
+(currently 2).
+
+void PyMarshal_WriteLongToFile(long value, FILE *file, int version)
+
+   Marshal a long integer, *value*, to *file*.  This will only write
+   the least-significant 32 bits of *value*; regardless of the size of
+   the native long type.  *version* indicates the file format.
+
+   This function can fail, in which case it sets the error indicator.
+   Use "PyErr_Occurred()" to check for that.
+
+void PyMarshal_WriteObjectToFile(PyObject *value, FILE *file, int version)
+
+   Marshal a Python object, *value*, to *file*. *version* indicates
+   the file format.
+
+   This function can fail, in which case it sets the error indicator.
+   Use "PyErr_Occurred()" to check for that.
+
+PyObject *PyMarshal_WriteObjectToString(PyObject *value, int version)
+    *Return value: New reference.*
+
+   Return a bytes object containing the marshalled representation of
+   *value*. *version* indicates the file format.
+
+The following functions allow marshalled values to be read back in.
+
+long PyMarshal_ReadLongFromFile(FILE *file)
+
+   Return a C long from the data stream in a FILE* opened for reading.
+   Only a 32-bit value can be read in using this function, regardless
+   of the native size of long.
+
+   On error, sets the appropriate exception ("EOFError") and returns
+   "-1".
+
+int PyMarshal_ReadShortFromFile(FILE *file)
+
+   Return a C short from the data stream in a FILE* opened for
+   reading.  Only a 16-bit value can be read in using this function,
+   regardless of the native size of short.
+
+   On error, sets the appropriate exception ("EOFError") and returns
+   "-1".
+
+PyObject *PyMarshal_ReadObjectFromFile(FILE *file)
+    *Return value: New reference.*
+
+   Return a Python object from the data stream in a FILE* opened for
+   reading.
+
+   On error, sets the appropriate exception ("EOFError", "ValueError"
+   or "TypeError") and returns "NULL".
+
+PyObject *PyMarshal_ReadLastObjectFromFile(FILE *file)
+    *Return value: New reference.*
+
+   Return a Python object from the data stream in a FILE* opened for
+   reading.  Unlike "PyMarshal_ReadObjectFromFile()", this function
+   assumes that no further objects will be read from the file,
+   allowing it to aggressively load file data into memory so that the
+   de-serialization can operate from data in memory rather than
+   reading a byte at a time from the file.  Only use these variant if
+   you are certain that you won't be reading anything else from the
+   file.
+
+   On error, sets the appropriate exception ("EOFError", "ValueError"
+   or "TypeError") and returns "NULL".
+
+PyObject *PyMarshal_ReadObjectFromString(const char *data, Py_ssize_t len)
+    *Return value: New reference.*
+
+   Return a Python object from the data stream in a byte buffer
+   containing *len* bytes pointed to by *data*.
+
+   On error, sets the appropriate exception ("EOFError", "ValueError"
+   or "TypeError") and returns "NULL".

python-3.12.6-docs-text/python-3.12.6-docs-text/c-api/memory.txt

@@ -0,0 +1,752 @@
+Memory Management
+*****************
+
+
+Overview
+========
+
+Memory management in Python involves a private heap containing all
+Python objects and data structures. The management of this private
+heap is ensured internally by the *Python memory manager*.  The Python
+memory manager has different components which deal with various
+dynamic storage management aspects, like sharing, segmentation,
+preallocation or caching.
+
+At the lowest level, a raw memory allocator ensures that there is
+enough room in the private heap for storing all Python-related data by
+interacting with the memory manager of the operating system. On top of
+the raw memory allocator, several object-specific allocators operate
+on the same heap and implement distinct memory management policies
+adapted to the peculiarities of every object type. For example,
+integer objects are managed differently within the heap than strings,
+tuples or dictionaries because integers imply different storage
+requirements and speed/space tradeoffs. The Python memory manager thus
+delegates some of the work to the object-specific allocators, but
+ensures that the latter operate within the bounds of the private heap.
+
+It is important to understand that the management of the Python heap
+is performed by the interpreter itself and that the user has no
+control over it, even if they regularly manipulate object pointers to
+memory blocks inside that heap.  The allocation of heap space for
+Python objects and other internal buffers is performed on demand by
+the Python memory manager through the Python/C API functions listed in
+this document.
+
+To avoid memory corruption, extension writers should never try to
+operate on Python objects with the functions exported by the C
+library: "malloc()", "calloc()", "realloc()" and "free()".  This will
+result in  mixed calls between the C allocator and the Python memory
+manager with fatal consequences, because they implement different
+algorithms and operate on different heaps.  However, one may safely
+allocate and release memory blocks with the C library allocator for
+individual purposes, as shown in the following example:
+
+   PyObject *res;
+   char *buf = (char *) malloc(BUFSIZ); /* for I/O */
+
+   if (buf == NULL)
+       return PyErr_NoMemory();
+   ...Do some I/O operation involving buf...
+   res = PyBytes_FromString(buf);
+   free(buf); /* malloc'ed */
+   return res;
+
+In this example, the memory request for the I/O buffer is handled by
+the C library allocator. The Python memory manager is involved only in
+the allocation of the bytes object returned as a result.
+
+In most situations, however, it is recommended to allocate memory from
+the Python heap specifically because the latter is under control of
+the Python memory manager. For example, this is required when the
+interpreter is extended with new object types written in C. Another
+reason for using the Python heap is the desire to *inform* the Python
+memory manager about the memory needs of the extension module. Even
+when the requested memory is used exclusively for internal, highly
+specific purposes, delegating all memory requests to the Python memory
+manager causes the interpreter to have a more accurate image of its
+memory footprint as a whole. Consequently, under certain
+circumstances, the Python memory manager may or may not trigger
+appropriate actions, like garbage collection, memory compaction or
+other preventive procedures. Note that by using the C library
+allocator as shown in the previous example, the allocated memory for
+the I/O buffer escapes completely the Python memory manager.
+
+See also:
+
+  The "PYTHONMALLOC" environment variable can be used to configure the
+  memory allocators used by Python.
+
+  The "PYTHONMALLOCSTATS" environment variable can be used to print
+  statistics of the pymalloc memory allocator every time a new
+  pymalloc object arena is created, and on shutdown.
+
+
+Allocator Domains
+=================
+
+All allocating functions belong to one of three different "domains"
+(see also "PyMemAllocatorDomain"). These domains represent different
+allocation strategies and are optimized for different purposes. The
+specific details on how every domain allocates memory or what internal
+functions each domain calls is considered an implementation detail,
+but for debugging purposes a simplified table can be found at here.
+There is no hard requirement to use the memory returned by the
+allocation functions belonging to a given domain for only the purposes
+hinted by that domain (although this is the recommended practice). For
+example, one could use the memory returned by "PyMem_RawMalloc()" for
+allocating Python objects or the memory returned by
+"PyObject_Malloc()" for allocating memory for buffers.
+
+The three allocation domains are:
+
+* Raw domain: intended for allocating memory for general-purpose
+  memory buffers where the allocation *must* go to the system
+  allocator or where the allocator can operate without the *GIL*. The
+  memory is requested directly to the system.
+
+* "Mem" domain: intended for allocating memory for Python buffers and
+  general-purpose memory buffers where the allocation must be
+  performed with the *GIL* held. The memory is taken from the Python
+  private heap.
+
+* Object domain: intended for allocating memory belonging to Python
+  objects. The memory is taken from the Python private heap.
+
+When freeing memory previously allocated by the allocating functions
+belonging to a given domain,the matching specific deallocating
+functions must be used. For example, "PyMem_Free()" must be used to
+free memory allocated using "PyMem_Malloc()".
+
+
+Raw Memory Interface
+====================
+
+The following function sets are wrappers to the system allocator.
+These functions are thread-safe, the *GIL* does not need to be held.
+
+The default raw memory allocator uses the following functions:
+"malloc()", "calloc()", "realloc()" and "free()"; call "malloc(1)" (or
+"calloc(1, 1)") when requesting zero bytes.
+
+Added in version 3.4.
+
+void *PyMem_RawMalloc(size_t n)
+
+   Allocates *n* bytes and returns a pointer of type void* to the
+   allocated memory, or "NULL" if the request fails.
+
+   Requesting zero bytes returns a distinct non-"NULL" pointer if
+   possible, as if "PyMem_RawMalloc(1)" had been called instead. The
+   memory will not have been initialized in any way.
+
+void *PyMem_RawCalloc(size_t nelem, size_t elsize)
+
+   Allocates *nelem* elements each whose size in bytes is *elsize* and
+   returns a pointer of type void* to the allocated memory, or "NULL"
+   if the request fails. The memory is initialized to zeros.
+
+   Requesting zero elements or elements of size zero bytes returns a
+   distinct non-"NULL" pointer if possible, as if "PyMem_RawCalloc(1,
+   1)" had been called instead.
+
+   Added in version 3.5.
+
+void *PyMem_RawRealloc(void *p, size_t n)
+
+   Resizes the memory block pointed to by *p* to *n* bytes. The
+   contents will be unchanged to the minimum of the old and the new
+   sizes.
+
+   If *p* is "NULL", the call is equivalent to "PyMem_RawMalloc(n)";
+   else if *n* is equal to zero, the memory block is resized but is
+   not freed, and the returned pointer is non-"NULL".
+
+   Unless *p* is "NULL", it must have been returned by a previous call
+   to "PyMem_RawMalloc()", "PyMem_RawRealloc()" or
+   "PyMem_RawCalloc()".
+
+   If the request fails, "PyMem_RawRealloc()" returns "NULL" and *p*
+   remains a valid pointer to the previous memory area.
+
+void PyMem_RawFree(void *p)
+
+   Frees the memory block pointed to by *p*, which must have been
+   returned by a previous call to "PyMem_RawMalloc()",
+   "PyMem_RawRealloc()" or "PyMem_RawCalloc()".  Otherwise, or if
+   "PyMem_RawFree(p)" has been called before, undefined behavior
+   occurs.
+
+   If *p* is "NULL", no operation is performed.
+
+
+Memory Interface
+================
+
+The following function sets, modeled after the ANSI C standard, but
+specifying behavior when requesting zero bytes, are available for
+allocating and releasing memory from the Python heap.
+
+The default memory allocator uses the pymalloc memory allocator.
+
+Warning:
+
+  The *GIL* must be held when using these functions.
+
+Changed in version 3.6: The default allocator is now pymalloc instead
+of system "malloc()".
+
+void *PyMem_Malloc(size_t n)
+    * Part of the Stable ABI.*
+
+   Allocates *n* bytes and returns a pointer of type void* to the
+   allocated memory, or "NULL" if the request fails.
+
+   Requesting zero bytes returns a distinct non-"NULL" pointer if
+   possible, as if "PyMem_Malloc(1)" had been called instead. The
+   memory will not have been initialized in any way.
+
+void *PyMem_Calloc(size_t nelem, size_t elsize)
+    * Part of the Stable ABI since version 3.7.*
+
+   Allocates *nelem* elements each whose size in bytes is *elsize* and
+   returns a pointer of type void* to the allocated memory, or "NULL"
+   if the request fails. The memory is initialized to zeros.
+
+   Requesting zero elements or elements of size zero bytes returns a
+   distinct non-"NULL" pointer if possible, as if "PyMem_Calloc(1, 1)"
+   had been called instead.
+
+   Added in version 3.5.
+
+void *PyMem_Realloc(void *p, size_t n)
+    * Part of the Stable ABI.*
+
+   Resizes the memory block pointed to by *p* to *n* bytes. The
+   contents will be unchanged to the minimum of the old and the new
+   sizes.
+
+   If *p* is "NULL", the call is equivalent to "PyMem_Malloc(n)"; else
+   if *n* is equal to zero, the memory block is resized but is not
+   freed, and the returned pointer is non-"NULL".
+
+   Unless *p* is "NULL", it must have been returned by a previous call
+   to "PyMem_Malloc()", "PyMem_Realloc()" or "PyMem_Calloc()".
+
+   If the request fails, "PyMem_Realloc()" returns "NULL" and *p*
+   remains a valid pointer to the previous memory area.
+
+void PyMem_Free(void *p)
+    * Part of the Stable ABI.*
+
+   Frees the memory block pointed to by *p*, which must have been
+   returned by a previous call to "PyMem_Malloc()", "PyMem_Realloc()"
+   or "PyMem_Calloc()".  Otherwise, or if "PyMem_Free(p)" has been
+   called before, undefined behavior occurs.
+
+   If *p* is "NULL", no operation is performed.
+
+The following type-oriented macros are provided for convenience.  Note
+that *TYPE* refers to any C type.
+
+PyMem_New(TYPE, n)
+
+   Same as "PyMem_Malloc()", but allocates "(n * sizeof(TYPE))" bytes
+   of memory.  Returns a pointer cast to "TYPE*".  The memory will not
+   have been initialized in any way.
+
+PyMem_Resize(p, TYPE, n)
+
+   Same as "PyMem_Realloc()", but the memory block is resized to "(n *
+   sizeof(TYPE))" bytes.  Returns a pointer cast to "TYPE*". On
+   return, *p* will be a pointer to the new memory area, or "NULL" in
+   the event of failure.
+
+   This is a C preprocessor macro; *p* is always reassigned.  Save the
+   original value of *p* to avoid losing memory when handling errors.
+
+void PyMem_Del(void *p)
+
+   Same as "PyMem_Free()".
+
+In addition, the following macro sets are provided for calling the
+Python memory allocator directly, without involving the C API
+functions listed above. However, note that their use does not preserve
+binary compatibility across Python versions and is therefore
+deprecated in extension modules.
+
+* "PyMem_MALLOC(size)"
+
+* "PyMem_NEW(type, size)"
+
+* "PyMem_REALLOC(ptr, size)"
+
+* "PyMem_RESIZE(ptr, type, size)"
+
+* "PyMem_FREE(ptr)"
+
+* "PyMem_DEL(ptr)"
+
+
+Object allocators
+=================
+
+The following function sets, modeled after the ANSI C standard, but
+specifying behavior when requesting zero bytes, are available for
+allocating and releasing memory from the Python heap.
+
+Note:
+
+  There is no guarantee that the memory returned by these allocators
+  can be successfully cast to a Python object when intercepting the
+  allocating functions in this domain by the methods described in the
+  Customize Memory Allocators section.
+
+The default object allocator uses the pymalloc memory allocator.
+
+Warning:
+
+  The *GIL* must be held when using these functions.
+
+void *PyObject_Malloc(size_t n)
+    * Part of the Stable ABI.*
+
+   Allocates *n* bytes and returns a pointer of type void* to the
+   allocated memory, or "NULL" if the request fails.
+
+   Requesting zero bytes returns a distinct non-"NULL" pointer if
+   possible, as if "PyObject_Malloc(1)" had been called instead. The
+   memory will not have been initialized in any way.
+
+void *PyObject_Calloc(size_t nelem, size_t elsize)
+    * Part of the Stable ABI since version 3.7.*
+
+   Allocates *nelem* elements each whose size in bytes is *elsize* and
+   returns a pointer of type void* to the allocated memory, or "NULL"
+   if the request fails. The memory is initialized to zeros.
+
+   Requesting zero elements or elements of size zero bytes returns a
+   distinct non-"NULL" pointer if possible, as if "PyObject_Calloc(1,
+   1)" had been called instead.
+
+   Added in version 3.5.
+
+void *PyObject_Realloc(void *p, size_t n)
+    * Part of the Stable ABI.*
+
+   Resizes the memory block pointed to by *p* to *n* bytes. The
+   contents will be unchanged to the minimum of the old and the new
+   sizes.
+
+   If *p* is "NULL", the call is equivalent to "PyObject_Malloc(n)";
+   else if *n* is equal to zero, the memory block is resized but is
+   not freed, and the returned pointer is non-"NULL".
+
+   Unless *p* is "NULL", it must have been returned by a previous call
+   to "PyObject_Malloc()", "PyObject_Realloc()" or
+   "PyObject_Calloc()".
+
+   If the request fails, "PyObject_Realloc()" returns "NULL" and *p*
+   remains a valid pointer to the previous memory area.
+
+void PyObject_Free(void *p)
+    * Part of the Stable ABI.*
+
+   Frees the memory block pointed to by *p*, which must have been
+   returned by a previous call to "PyObject_Malloc()",
+   "PyObject_Realloc()" or "PyObject_Calloc()".  Otherwise, or if
+   "PyObject_Free(p)" has been called before, undefined behavior
+   occurs.
+
+   If *p* is "NULL", no operation is performed.
+
+
+Default Memory Allocators
+=========================
+
+Default memory allocators:
+
++---------------------------------+----------------------+--------------------+-----------------------+----------------------+
+| Configuration                   | Name                 | PyMem_RawMalloc    | PyMem_Malloc          | PyObject_Malloc      |
+|=================================|======================|====================|=======================|======================|
+| Release build                   | ""pymalloc""         | "malloc"           | "pymalloc"            | "pymalloc"           |
++---------------------------------+----------------------+--------------------+-----------------------+----------------------+
+| Debug build                     | ""pymalloc_debug""   | "malloc" + debug   | "pymalloc" + debug    | "pymalloc" + debug   |
++---------------------------------+----------------------+--------------------+-----------------------+----------------------+
+| Release build, without pymalloc | ""malloc""           | "malloc"           | "malloc"              | "malloc"             |
++---------------------------------+----------------------+--------------------+-----------------------+----------------------+
+| Debug build, without pymalloc   | ""malloc_debug""     | "malloc" + debug   | "malloc" + debug      | "malloc" + debug     |
++---------------------------------+----------------------+--------------------+-----------------------+----------------------+
+
+Legend:
+
+* Name: value for "PYTHONMALLOC" environment variable.
+
+* "malloc": system allocators from the standard C library, C
+  functions: "malloc()", "calloc()", "realloc()" and "free()".
+
+* "pymalloc": pymalloc memory allocator.
+
+* "+ debug": with debug hooks on the Python memory allocators.
+
+* "Debug build": Python build in debug mode.
+
+
+Customize Memory Allocators
+===========================
+
+Added in version 3.4.
+
+type PyMemAllocatorEx
+
+   Structure used to describe a memory block allocator. The structure
+   has the following fields:
+
+   +------------------------------------------------------------+-----------------------------------------+
+   | Field                                                      | Meaning                                 |
+   |============================================================|=========================================|
+   | "void *ctx"                                                | user context passed as first argument   |
+   +------------------------------------------------------------+-----------------------------------------+
+   | "void* malloc(void *ctx, size_t size)"                     | allocate a memory block                 |
+   +------------------------------------------------------------+-----------------------------------------+
+   | "void* calloc(void *ctx, size_t nelem, size_t elsize)"     | allocate a memory block initialized     |
+   |                                                            | with zeros                              |
+   +------------------------------------------------------------+-----------------------------------------+
+   | "void* realloc(void *ctx, void *ptr, size_t new_size)"     | allocate or resize a memory block       |
+   +------------------------------------------------------------+-----------------------------------------+
+   | "void free(void *ctx, void *ptr)"                          | free a memory block                     |
+   +------------------------------------------------------------+-----------------------------------------+
+
+   Changed in version 3.5: The "PyMemAllocator" structure was renamed
+   to "PyMemAllocatorEx" and a new "calloc" field was added.
+
+type PyMemAllocatorDomain
+
+   Enum used to identify an allocator domain. Domains:
+
+   PYMEM_DOMAIN_RAW
+
+      Functions:
+
+      * "PyMem_RawMalloc()"
+
+      * "PyMem_RawRealloc()"
+
+      * "PyMem_RawCalloc()"
+
+      * "PyMem_RawFree()"
+
+   PYMEM_DOMAIN_MEM
+
+      Functions:
+
+      * "PyMem_Malloc()",
+
+      * "PyMem_Realloc()"
+
+      * "PyMem_Calloc()"
+
+      * "PyMem_Free()"
+
+   PYMEM_DOMAIN_OBJ
+
+      Functions:
+
+      * "PyObject_Malloc()"
+
+      * "PyObject_Realloc()"
+
+      * "PyObject_Calloc()"
+
+      * "PyObject_Free()"
+
+void PyMem_GetAllocator(PyMemAllocatorDomain domain, PyMemAllocatorEx *allocator)
+
+   Get the memory block allocator of the specified domain.
+
+void PyMem_SetAllocator(PyMemAllocatorDomain domain, PyMemAllocatorEx *allocator)
+
+   Set the memory block allocator of the specified domain.
+
+   The new allocator must return a distinct non-"NULL" pointer when
+   requesting zero bytes.
+
+   For the "PYMEM_DOMAIN_RAW" domain, the allocator must be thread-
+   safe: the *GIL* is not held when the allocator is called.
+
+   For the remaining domains, the allocator must also be thread-safe:
+   the allocator may be called in different interpreters that do not
+   share a "GIL".
+
+   If the new allocator is not a hook (does not call the previous
+   allocator), the "PyMem_SetupDebugHooks()" function must be called
+   to reinstall the debug hooks on top on the new allocator.
+
+   See also "PyPreConfig.allocator" and Preinitialize Python with
+   PyPreConfig.
+
+   Warning:
+
+     "PyMem_SetAllocator()" does have the following contract:
+
+     * It can be called after "Py_PreInitialize()" and before
+       "Py_InitializeFromConfig()" to install a custom memory
+       allocator. There are no restrictions over the installed
+       allocator other than the ones imposed by the domain (for
+       instance, the Raw Domain allows the allocator to be called
+       without the GIL held). See the section on allocator domains for
+       more information.
+
+     * If called after Python has finish initializing (after
+       "Py_InitializeFromConfig()" has been called) the allocator
+       **must** wrap the existing allocator. Substituting the current
+       allocator for some other arbitrary one is **not supported**.
+
+   Changed in version 3.12: All allocators must be thread-safe.
+
+void PyMem_SetupDebugHooks(void)
+
+   Setup debug hooks in the Python memory allocators to detect memory
+   errors.
+
+
+Debug hooks on the Python memory allocators
+===========================================
+
+When Python is built in debug mode, the "PyMem_SetupDebugHooks()"
+function is called at the Python preinitialization to setup debug
+hooks on Python memory allocators to detect memory errors.
+
+The "PYTHONMALLOC" environment variable can be used to install debug
+hooks on a Python compiled in release mode (ex: "PYTHONMALLOC=debug").
+
+The "PyMem_SetupDebugHooks()" function can be used to set debug hooks
+after calling "PyMem_SetAllocator()".
+
+These debug hooks fill dynamically allocated memory blocks with
+special, recognizable bit patterns. Newly allocated memory is filled
+with the byte "0xCD" ("PYMEM_CLEANBYTE"), freed memory is filled with
+the byte "0xDD" ("PYMEM_DEADBYTE"). Memory blocks are surrounded by
+"forbidden bytes" filled with the byte "0xFD" ("PYMEM_FORBIDDENBYTE").
+Strings of these bytes are unlikely to be valid addresses, floats, or
+ASCII strings.
+
+Runtime checks:
+
+* Detect API violations. For example, detect if "PyObject_Free()" is
+  called on a memory block allocated by "PyMem_Malloc()".
+
+* Detect write before the start of the buffer (buffer underflow).
+
+* Detect write after the end of the buffer (buffer overflow).
+
+* Check that the *GIL* is held when allocator functions of
+  "PYMEM_DOMAIN_OBJ" (ex: "PyObject_Malloc()") and "PYMEM_DOMAIN_MEM"
+  (ex: "PyMem_Malloc()") domains are called.
+
+On error, the debug hooks use the "tracemalloc" module to get the
+traceback where a memory block was allocated. The traceback is only
+displayed if "tracemalloc" is tracing Python memory allocations and
+the memory block was traced.
+
+Let *S* = "sizeof(size_t)". "2*S" bytes are added at each end of each
+block of *N* bytes requested.  The memory layout is like so, where p
+represents the address returned by a malloc-like or realloc-like
+function ("p[i:j]" means the slice of bytes from "*(p+i)" inclusive up
+to "*(p+j)" exclusive; note that the treatment of negative indices
+differs from a Python slice):
+
+"p[-2*S:-S]"
+   Number of bytes originally asked for.  This is a size_t, big-endian
+   (easier to read in a memory dump).
+
+"p[-S]"
+   API identifier (ASCII character):
+
+   * "'r'" for "PYMEM_DOMAIN_RAW".
+
+   * "'m'" for "PYMEM_DOMAIN_MEM".
+
+   * "'o'" for "PYMEM_DOMAIN_OBJ".
+
+"p[-S+1:0]"
+   Copies of PYMEM_FORBIDDENBYTE.  Used to catch under- writes and
+   reads.
+
+"p[0:N]"
+   The requested memory, filled with copies of PYMEM_CLEANBYTE, used
+   to catch reference to uninitialized memory.  When a realloc-like
+   function is called requesting a larger memory block, the new excess
+   bytes are also filled with PYMEM_CLEANBYTE.  When a free-like
+   function is called, these are overwritten with PYMEM_DEADBYTE, to
+   catch reference to freed memory.  When a realloc- like function is
+   called requesting a smaller memory block, the excess old bytes are
+   also filled with PYMEM_DEADBYTE.
+
+"p[N:N+S]"
+   Copies of PYMEM_FORBIDDENBYTE.  Used to catch over- writes and
+   reads.
+
+"p[N+S:N+2*S]"
+   Only used if the "PYMEM_DEBUG_SERIALNO" macro is defined (not
+   defined by default).
+
+   A serial number, incremented by 1 on each call to a malloc-like or
+   realloc-like function.  Big-endian "size_t".  If "bad memory" is
+   detected later, the serial number gives an excellent way to set a
+   breakpoint on the next run, to capture the instant at which this
+   block was passed out.  The static function bumpserialno() in
+   obmalloc.c is the only place the serial number is incremented, and
+   exists so you can set such a breakpoint easily.
+
+A realloc-like or free-like function first checks that the
+PYMEM_FORBIDDENBYTE bytes at each end are intact.  If they've been
+altered, diagnostic output is written to stderr, and the program is
+aborted via Py_FatalError().  The other main failure mode is provoking
+a memory error when a program reads up one of the special bit patterns
+and tries to use it as an address.  If you get in a debugger then and
+look at the object, you're likely to see that it's entirely filled
+with PYMEM_DEADBYTE (meaning freed memory is getting used) or
+PYMEM_CLEANBYTE (meaning uninitialized memory is getting used).
+
+Changed in version 3.6: The "PyMem_SetupDebugHooks()" function now
+also works on Python compiled in release mode.  On error, the debug
+hooks now use "tracemalloc" to get the traceback where a memory block
+was allocated. The debug hooks now also check if the GIL is held when
+functions of "PYMEM_DOMAIN_OBJ" and "PYMEM_DOMAIN_MEM" domains are
+called.
+
+Changed in version 3.8: Byte patterns "0xCB" ("PYMEM_CLEANBYTE"),
+"0xDB" ("PYMEM_DEADBYTE") and "0xFB" ("PYMEM_FORBIDDENBYTE") have been
+replaced with "0xCD", "0xDD" and "0xFD" to use the same values than
+Windows CRT debug "malloc()" and "free()".
+
+
+The pymalloc allocator
+======================
+
+Python has a *pymalloc* allocator optimized for small objects (smaller
+or equal to 512 bytes) with a short lifetime. It uses memory mappings
+called "arenas" with a fixed size of either 256 KiB on 32-bit
+platforms or 1 MiB on 64-bit platforms. It falls back to
+"PyMem_RawMalloc()" and "PyMem_RawRealloc()" for allocations larger
+than 512 bytes.
+
+*pymalloc* is the default allocator of the "PYMEM_DOMAIN_MEM" (ex:
+"PyMem_Malloc()") and "PYMEM_DOMAIN_OBJ" (ex: "PyObject_Malloc()")
+domains.
+
+The arena allocator uses the following functions:
+
+* "VirtualAlloc()" and "VirtualFree()" on Windows,
+
+* "mmap()" and "munmap()" if available,
+
+* "malloc()" and "free()" otherwise.
+
+This allocator is disabled if Python is configured with the "--
+without-pymalloc" option. It can also be disabled at runtime using the
+"PYTHONMALLOC" environment variable (ex: "PYTHONMALLOC=malloc").
+
+
+Customize pymalloc Arena Allocator
+----------------------------------
+
+Added in version 3.4.
+
+type PyObjectArenaAllocator
+
+   Structure used to describe an arena allocator. The structure has
+   three fields:
+
+   +----------------------------------------------------+-----------------------------------------+
+   | Field                                              | Meaning                                 |
+   |====================================================|=========================================|
+   | "void *ctx"                                        | user context passed as first argument   |
+   +----------------------------------------------------+-----------------------------------------+
+   | "void* alloc(void *ctx, size_t size)"              | allocate an arena of size bytes         |
+   +----------------------------------------------------+-----------------------------------------+
+   | "void free(void *ctx, void *ptr, size_t size)"     | free an arena                           |
+   +----------------------------------------------------+-----------------------------------------+
+
+void PyObject_GetArenaAllocator(PyObjectArenaAllocator *allocator)
+
+   Get the arena allocator.
+
+void PyObject_SetArenaAllocator(PyObjectArenaAllocator *allocator)
+
+   Set the arena allocator.
+
+
+tracemalloc C API
+=================
+
+Added in version 3.7.
+
+int PyTraceMalloc_Track(unsigned int domain, uintptr_t ptr, size_t size)
+
+   Track an allocated memory block in the "tracemalloc" module.
+
+   Return "0" on success, return "-1" on error (failed to allocate
+   memory to store the trace). Return "-2" if tracemalloc is disabled.
+
+   If memory block is already tracked, update the existing trace.
+
+int PyTraceMalloc_Untrack(unsigned int domain, uintptr_t ptr)
+
+   Untrack an allocated memory block in the "tracemalloc" module. Do
+   nothing if the block was not tracked.
+
+   Return "-2" if tracemalloc is disabled, otherwise return "0".
+
+
+Examples
+========
+
+Here is the example from section Overview, rewritten so that the I/O
+buffer is allocated from the Python heap by using the first function
+set:
+
+   PyObject *res;
+   char *buf = (char *) PyMem_Malloc(BUFSIZ); /* for I/O */
+
+   if (buf == NULL)
+       return PyErr_NoMemory();
+   /* ...Do some I/O operation involving buf... */
+   res = PyBytes_FromString(buf);
+   PyMem_Free(buf); /* allocated with PyMem_Malloc */
+   return res;
+
+The same code using the type-oriented function set:
+
+   PyObject *res;
+   char *buf = PyMem_New(char, BUFSIZ); /* for I/O */
+
+   if (buf == NULL)
+       return PyErr_NoMemory();
+   /* ...Do some I/O operation involving buf... */
+   res = PyBytes_FromString(buf);
+   PyMem_Del(buf); /* allocated with PyMem_New */
+   return res;
+
+Note that in the two examples above, the buffer is always manipulated
+via functions belonging to the same set. Indeed, it is required to use
+the same memory API family for a given memory block, so that the risk
+of mixing different allocators is reduced to a minimum. The following
+code sequence contains two errors, one of which is labeled as *fatal*
+because it mixes two different allocators operating on different
+heaps.
+
+   char *buf1 = PyMem_New(char, BUFSIZ);
+   char *buf2 = (char *) malloc(BUFSIZ);
+   char *buf3 = (char *) PyMem_Malloc(BUFSIZ);
+   ...
+   PyMem_Del(buf3);  /* Wrong -- should be PyMem_Free() */
+   free(buf2);       /* Right -- allocated via malloc() */
+   free(buf1);       /* Fatal -- should be PyMem_Del()  */
+
+In addition to the functions aimed at handling raw memory blocks from
+the Python heap, objects in Python are allocated and released with
+"PyObject_New", "PyObject_NewVar" and "PyObject_Del()".
+
+These will be explained in the next chapter on defining and
+implementing new object types in C.

python-3.12.6-docs-text/python-3.12.6-docs-text/c-api/memoryview.txt

@@ -0,0 +1,70 @@
+MemoryView objects
+******************
+
+A "memoryview" object exposes the C level buffer interface as a Python
+object which can then be passed around like any other object.
+
+PyObject *PyMemoryView_FromObject(PyObject *obj)
+    *Return value: New reference.** Part of the Stable ABI.*
+
+   Create a memoryview object from an object that provides the buffer
+   interface. If *obj* supports writable buffer exports, the
+   memoryview object will be read/write, otherwise it may be either
+   read-only or read/write at the discretion of the exporter.
+
+PyBUF_READ
+
+   Flag to request a readonly buffer.
+
+PyBUF_WRITE
+
+   Flag to request a writable buffer.
+
+PyObject *PyMemoryView_FromMemory(char *mem, Py_ssize_t size, int flags)
+    *Return value: New reference.** Part of the Stable ABI since
+   version 3.7.*
+
+   Create a memoryview object using *mem* as the underlying buffer.
+   *flags* can be one of "PyBUF_READ" or "PyBUF_WRITE".
+
+   Added in version 3.3.
+
+PyObject *PyMemoryView_FromBuffer(const Py_buffer *view)
+    *Return value: New reference.** Part of the Stable ABI since
+   version 3.11.*
+
+   Create a memoryview object wrapping the given buffer structure
+   *view*. For simple byte buffers, "PyMemoryView_FromMemory()" is the
+   preferred function.
+
+PyObject *PyMemoryView_GetContiguous(PyObject *obj, int buffertype, char order)
+    *Return value: New reference.** Part of the Stable ABI.*
+
+   Create a memoryview object to a *contiguous* chunk of memory (in
+   either 'C' or 'F'ortran *order*) from an object that defines the
+   buffer interface. If memory is contiguous, the memoryview object
+   points to the original memory. Otherwise, a copy is made and the
+   memoryview points to a new bytes object.
+
+   *buffertype* can be one of "PyBUF_READ" or "PyBUF_WRITE".
+
+int PyMemoryView_Check(PyObject *obj)
+
+   Return true if the object *obj* is a memoryview object.  It is not
+   currently allowed to create subclasses of "memoryview".  This
+   function always succeeds.
+
+Py_buffer *PyMemoryView_GET_BUFFER(PyObject *mview)
+
+   Return a pointer to the memoryview's private copy of the exporter's
+   buffer. *mview* **must** be a memoryview instance; this macro
+   doesn't check its type, you must do it yourself or you will risk
+   crashes.
+
+PyObject *PyMemoryView_GET_BASE(PyObject *mview)
+
+   Return either a pointer to the exporting object that the memoryview
+   is based on or "NULL" if the memoryview has been created by one of
+   the functions "PyMemoryView_FromMemory()" or
+   "PyMemoryView_FromBuffer()". *mview* **must** be a memoryview
+   instance.

python-3.12.6-docs-text/python-3.12.6-docs-text/c-api/method.txt

@@ -0,0 +1,82 @@
+Instance Method Objects
+***********************
+
+An instance method is a wrapper for a "PyCFunction" and the new way to
+bind a "PyCFunction" to a class object. It replaces the former call
+"PyMethod_New(func, NULL, class)".
+
+PyTypeObject PyInstanceMethod_Type
+
+   This instance of "PyTypeObject" represents the Python instance
+   method type. It is not exposed to Python programs.
+
+int PyInstanceMethod_Check(PyObject *o)
+
+   Return true if *o* is an instance method object (has type
+   "PyInstanceMethod_Type").  The parameter must not be "NULL". This
+   function always succeeds.
+
+PyObject *PyInstanceMethod_New(PyObject *func)
+    *Return value: New reference.*
+
+   Return a new instance method object, with *func* being any callable
+   object. *func* is the function that will be called when the
+   instance method is called.
+
+PyObject *PyInstanceMethod_Function(PyObject *im)
+    *Return value: Borrowed reference.*
+
+   Return the function object associated with the instance method
+   *im*.
+
+PyObject *PyInstanceMethod_GET_FUNCTION(PyObject *im)
+    *Return value: Borrowed reference.*
+
+   Macro version of "PyInstanceMethod_Function()" which avoids error
+   checking.
+
+
+Method Objects
+**************
+
+Methods are bound function objects. Methods are always bound to an
+instance of a user-defined class. Unbound methods (methods bound to a
+class object) are no longer available.
+
+PyTypeObject PyMethod_Type
+
+   This instance of "PyTypeObject" represents the Python method type.
+   This is exposed to Python programs as "types.MethodType".
+
+int PyMethod_Check(PyObject *o)
+
+   Return true if *o* is a method object (has type "PyMethod_Type").
+   The parameter must not be "NULL".  This function always succeeds.
+
+PyObject *PyMethod_New(PyObject *func, PyObject *self)
+    *Return value: New reference.*
+
+   Return a new method object, with *func* being any callable object
+   and *self* the instance the method should be bound. *func* is the
+   function that will be called when the method is called. *self* must
+   not be "NULL".
+
+PyObject *PyMethod_Function(PyObject *meth)
+    *Return value: Borrowed reference.*
+
+   Return the function object associated with the method *meth*.
+
+PyObject *PyMethod_GET_FUNCTION(PyObject *meth)
+    *Return value: Borrowed reference.*
+
+   Macro version of "PyMethod_Function()" which avoids error checking.
+
+PyObject *PyMethod_Self(PyObject *meth)
+    *Return value: Borrowed reference.*
+
+   Return the instance associated with the method *meth*.
+
+PyObject *PyMethod_GET_SELF(PyObject *meth)
+    *Return value: Borrowed reference.*
+
+   Macro version of "PyMethod_Self()" which avoids error checking.

python-3.12.6-docs-text/python-3.12.6-docs-text/c-api/module.txt

@@ -0,0 +1,668 @@
+Module Objects
+**************
+
+PyTypeObject PyModule_Type
+    * Part of the Stable ABI.*
+
+   This instance of "PyTypeObject" represents the Python module type.
+   This is exposed to Python programs as "types.ModuleType".
+
+int PyModule_Check(PyObject *p)
+
+   Return true if *p* is a module object, or a subtype of a module
+   object. This function always succeeds.
+
+int PyModule_CheckExact(PyObject *p)
+
+   Return true if *p* is a module object, but not a subtype of
+   "PyModule_Type".  This function always succeeds.
+
+PyObject *PyModule_NewObject(PyObject *name)
+    *Return value: New reference.** Part of the Stable ABI since
+   version 3.7.*
+
+   Return a new module object with the "__name__" attribute set to
+   *name*. The module's "__name__", "__doc__", "__package__", and
+   "__loader__" attributes are filled in (all but "__name__" are set
+   to "None"); the caller is responsible for providing a "__file__"
+   attribute.
+
+   Return "NULL" with an exception set on error.
+
+   Added in version 3.3.
+
+   Changed in version 3.4: "__package__" and "__loader__" are set to
+   "None".
+
+PyObject *PyModule_New(const char *name)
+    *Return value: New reference.** Part of the Stable ABI.*
+
+   Similar to "PyModule_NewObject()", but the name is a UTF-8 encoded
+   string instead of a Unicode object.
+
+PyObject *PyModule_GetDict(PyObject *module)
+    *Return value: Borrowed reference.** Part of the Stable ABI.*
+
+   Return the dictionary object that implements *module*'s namespace;
+   this object is the same as the "__dict__" attribute of the module
+   object. If *module* is not a module object (or a subtype of a
+   module object), "SystemError" is raised and "NULL" is returned.
+
+   It is recommended extensions use other "PyModule_*" and
+   "PyObject_*" functions rather than directly manipulate a module's
+   "__dict__".
+
+PyObject *PyModule_GetNameObject(PyObject *module)
+    *Return value: New reference.** Part of the Stable ABI since
+   version 3.7.*
+
+   Return *module*'s "__name__" value.  If the module does not provide
+   one, or if it is not a string, "SystemError" is raised and "NULL"
+   is returned.
+
+   Added in version 3.3.
+
+const char *PyModule_GetName(PyObject *module)
+    * Part of the Stable ABI.*
+
+   Similar to "PyModule_GetNameObject()" but return the name encoded
+   to "'utf-8'".
+
+void *PyModule_GetState(PyObject *module)
+    * Part of the Stable ABI.*
+
+   Return the "state" of the module, that is, a pointer to the block
+   of memory allocated at module creation time, or "NULL".  See
+   "PyModuleDef.m_size".
+
+PyModuleDef *PyModule_GetDef(PyObject *module)
+    * Part of the Stable ABI.*
+
+   Return a pointer to the "PyModuleDef" struct from which the module
+   was created, or "NULL" if the module wasn't created from a
+   definition.
+
+PyObject *PyModule_GetFilenameObject(PyObject *module)
+    *Return value: New reference.** Part of the Stable ABI.*
+
+   Return the name of the file from which *module* was loaded using
+   *module*'s "__file__" attribute.  If this is not defined, or if it
+   is not a unicode string, raise "SystemError" and return "NULL";
+   otherwise return a reference to a Unicode object.
+
+   Added in version 3.2.
+
+const char *PyModule_GetFilename(PyObject *module)
+    * Part of the Stable ABI.*
+
+   Similar to "PyModule_GetFilenameObject()" but return the filename
+   encoded to 'utf-8'.
+
+   Deprecated since version 3.2: "PyModule_GetFilename()" raises
+   "UnicodeEncodeError" on unencodable filenames, use
+   "PyModule_GetFilenameObject()" instead.
+
+
+Initializing C modules
+======================
+
+Modules objects are usually created from extension modules (shared
+libraries which export an initialization function), or compiled-in
+modules (where the initialization function is added using
+"PyImport_AppendInittab()"). See Building C and C++ Extensions or
+Extending Embedded Python for details.
+
+The initialization function can either pass a module definition
+instance to "PyModule_Create()", and return the resulting module
+object, or request "multi-phase initialization" by returning the
+definition struct itself.
+
+type PyModuleDef
+    * Part of the Stable ABI (including all members).*
+
+   The module definition struct, which holds all information needed to
+   create a module object. There is usually only one statically
+   initialized variable of this type for each module.
+
+   PyModuleDef_Base m_base
+
+      Always initialize this member to "PyModuleDef_HEAD_INIT".
+
+   const char *m_name
+
+      Name for the new module.
+
+   const char *m_doc
+
+      Docstring for the module; usually a docstring variable created
+      with "PyDoc_STRVAR" is used.
+
+   Py_ssize_t m_size
+
+      Module state may be kept in a per-module memory area that can be
+      retrieved with "PyModule_GetState()", rather than in static
+      globals. This makes modules safe for use in multiple sub-
+      interpreters.
+
+      This memory area is allocated based on *m_size* on module
+      creation, and freed when the module object is deallocated, after
+      the "m_free" function has been called, if present.
+
+      Setting "m_size" to "-1" means that the module does not support
+      sub-interpreters, because it has global state.
+
+      Setting it to a non-negative value means that the module can be
+      re-initialized and specifies the additional amount of memory it
+      requires for its state. Non-negative "m_size" is required for
+      multi-phase initialization.
+
+      See **PEP 3121** for more details.
+
+   PyMethodDef *m_methods
+
+      A pointer to a table of module-level functions, described by
+      "PyMethodDef" values.  Can be "NULL" if no functions are
+      present.
+
+   PyModuleDef_Slot *m_slots
+
+      An array of slot definitions for multi-phase initialization,
+      terminated by a "{0, NULL}" entry. When using single-phase
+      initialization, *m_slots* must be "NULL".
+
+      Changed in version 3.5: Prior to version 3.5, this member was
+      always set to "NULL", and was defined as:
+
+         inquiry m_reload
+
+   traverseproc m_traverse
+
+      A traversal function to call during GC traversal of the module
+      object, or "NULL" if not needed.
+
+      This function is not called if the module state was requested
+      but is not allocated yet. This is the case immediately after the
+      module is created and before the module is executed
+      ("Py_mod_exec" function). More precisely, this function is not
+      called if "m_size" is greater than 0 and the module state (as
+      returned by "PyModule_GetState()") is "NULL".
+
+      Changed in version 3.9: No longer called before the module state
+      is allocated.
+
+   inquiry m_clear
+
+      A clear function to call during GC clearing of the module
+      object, or "NULL" if not needed.
+
+      This function is not called if the module state was requested
+      but is not allocated yet. This is the case immediately after the
+      module is created and before the module is executed
+      ("Py_mod_exec" function). More precisely, this function is not
+      called if "m_size" is greater than 0 and the module state (as
+      returned by "PyModule_GetState()") is "NULL".
+
+      Like "PyTypeObject.tp_clear", this function is not *always*
+      called before a module is deallocated. For example, when
+      reference counting is enough to determine that an object is no
+      longer used, the cyclic garbage collector is not involved and
+      "m_free" is called directly.
+
+      Changed in version 3.9: No longer called before the module state
+      is allocated.
+
+   freefunc m_free
+
+      A function to call during deallocation of the module object, or
+      "NULL" if not needed.
+
+      This function is not called if the module state was requested
+      but is not allocated yet. This is the case immediately after the
+      module is created and before the module is executed
+      ("Py_mod_exec" function). More precisely, this function is not
+      called if "m_size" is greater than 0 and the module state (as
+      returned by "PyModule_GetState()") is "NULL".
+
+      Changed in version 3.9: No longer called before the module state
+      is allocated.
+
+
+Single-phase initialization
+---------------------------
+
+The module initialization function may create and return the module
+object directly. This is referred to as "single-phase initialization",
+and uses one of the following two module creation functions:
+
+PyObject *PyModule_Create(PyModuleDef *def)
+    *Return value: New reference.*
+
+   Create a new module object, given the definition in *def*.  This
+   behaves like "PyModule_Create2()" with *module_api_version* set to
+   "PYTHON_API_VERSION".
+
+PyObject *PyModule_Create2(PyModuleDef *def, int module_api_version)
+    *Return value: New reference.** Part of the Stable ABI.*
+
+   Create a new module object, given the definition in *def*, assuming
+   the API version *module_api_version*.  If that version does not
+   match the version of the running interpreter, a "RuntimeWarning" is
+   emitted.
+
+   Return "NULL" with an exception set on error.
+
+   Note:
+
+     Most uses of this function should be using "PyModule_Create()"
+     instead; only use this if you are sure you need it.
+
+Before it is returned from in the initialization function, the
+resulting module object is typically populated using functions like
+"PyModule_AddObjectRef()".
+
+
+Multi-phase initialization
+--------------------------
+
+An alternate way to specify extensions is to request "multi-phase
+initialization". Extension modules created this way behave more like
+Python modules: the initialization is split between the *creation
+phase*, when the module object is created, and the *execution phase*,
+when it is populated. The distinction is similar to the "__new__()"
+and "__init__()" methods of classes.
+
+Unlike modules created using single-phase initialization, these
+modules are not singletons: if the *sys.modules* entry is removed and
+the module is re-imported, a new module object is created, and the old
+module is subject to normal garbage collection -- as with Python
+modules. By default, multiple modules created from the same definition
+should be independent: changes to one should not affect the others.
+This means that all state should be specific to the module object
+(using e.g. using "PyModule_GetState()"), or its contents (such as the
+module's "__dict__" or individual classes created with
+"PyType_FromSpec()").
+
+All modules created using multi-phase initialization are expected to
+support sub-interpreters. Making sure multiple modules are independent
+is typically enough to achieve this.
+
+To request multi-phase initialization, the initialization function
+(PyInit_modulename) returns a "PyModuleDef" instance with non-empty
+"m_slots". Before it is returned, the "PyModuleDef" instance must be
+initialized with the following function:
+
+PyObject *PyModuleDef_Init(PyModuleDef *def)
+    *Return value: Borrowed reference.** Part of the Stable ABI since
+   version 3.5.*
+
+   Ensures a module definition is a properly initialized Python object
+   that correctly reports its type and reference count.
+
+   Returns *def* cast to "PyObject*", or "NULL" if an error occurred.
+
+   Added in version 3.5.
+
+The *m_slots* member of the module definition must point to an array
+of "PyModuleDef_Slot" structures:
+
+type PyModuleDef_Slot
+
+   int slot
+
+      A slot ID, chosen from the available values explained below.
+
+   void *value
+
+      Value of the slot, whose meaning depends on the slot ID.
+
+   Added in version 3.5.
+
+The *m_slots* array must be terminated by a slot with id 0.
+
+The available slot types are:
+
+Py_mod_create
+
+   Specifies a function that is called to create the module object
+   itself. The *value* pointer of this slot must point to a function
+   of the signature:
+
+   PyObject *create_module(PyObject *spec, PyModuleDef *def)
+
+   The function receives a "ModuleSpec" instance, as defined in **PEP
+   451**, and the module definition. It should return a new module
+   object, or set an error and return "NULL".
+
+   This function should be kept minimal. In particular, it should not
+   call arbitrary Python code, as trying to import the same module
+   again may result in an infinite loop.
+
+   Multiple "Py_mod_create" slots may not be specified in one module
+   definition.
+
+   If "Py_mod_create" is not specified, the import machinery will
+   create a normal module object using "PyModule_New()". The name is
+   taken from *spec*, not the definition, to allow extension modules
+   to dynamically adjust to their place in the module hierarchy and be
+   imported under different names through symlinks, all while sharing
+   a single module definition.
+
+   There is no requirement for the returned object to be an instance
+   of "PyModule_Type". Any type can be used, as long as it supports
+   setting and getting import-related attributes. However, only
+   "PyModule_Type" instances may be returned if the "PyModuleDef" has
+   non-"NULL" "m_traverse", "m_clear", "m_free"; non-zero "m_size"; or
+   slots other than "Py_mod_create".
+
+Py_mod_exec
+
+   Specifies a function that is called to *execute* the module. This
+   is equivalent to executing the code of a Python module: typically,
+   this function adds classes and constants to the module. The
+   signature of the function is:
+
+   int exec_module(PyObject *module)
+
+   If multiple "Py_mod_exec" slots are specified, they are processed
+   in the order they appear in the *m_slots* array.
+
+Py_mod_multiple_interpreters
+
+   Specifies one of the following values:
+
+   Py_MOD_MULTIPLE_INTERPRETERS_NOT_SUPPORTED
+
+      The module does not support being imported in subinterpreters.
+
+   Py_MOD_MULTIPLE_INTERPRETERS_SUPPORTED
+
+      The module supports being imported in subinterpreters, but only
+      when they share the main interpreter's GIL. (See Isolating
+      Extension Modules.)
+
+   Py_MOD_PER_INTERPRETER_GIL_SUPPORTED
+
+      The module supports being imported in subinterpreters, even when
+      they have their own GIL. (See Isolating Extension Modules.)
+
+   This slot determines whether or not importing this module in a
+   subinterpreter will fail.
+
+   Multiple "Py_mod_multiple_interpreters" slots may not be specified
+   in one module definition.
+
+   If "Py_mod_multiple_interpreters" is not specified, the import
+   machinery defaults to "Py_MOD_MULTIPLE_INTERPRETERS_NOT_SUPPORTED".
+
+   Added in version 3.12.
+
+See **PEP 489** for more details on multi-phase initialization.
+
+
+Low-level module creation functions
+-----------------------------------
+
+The following functions are called under the hood when using multi-
+phase initialization. They can be used directly, for example when
+creating module objects dynamically. Note that both
+"PyModule_FromDefAndSpec" and "PyModule_ExecDef" must be called to
+fully initialize a module.
+
+PyObject *PyModule_FromDefAndSpec(PyModuleDef *def, PyObject *spec)
+    *Return value: New reference.*
+
+   Create a new module object, given the definition in *def* and the
+   ModuleSpec *spec*.  This behaves like "PyModule_FromDefAndSpec2()"
+   with *module_api_version* set to "PYTHON_API_VERSION".
+
+   Added in version 3.5.
+
+PyObject *PyModule_FromDefAndSpec2(PyModuleDef *def, PyObject *spec, int module_api_version)
+    *Return value: New reference.** Part of the Stable ABI since
+   version 3.7.*
+
+   Create a new module object, given the definition in *def* and the
+   ModuleSpec *spec*, assuming the API version *module_api_version*.
+   If that version does not match the version of the running
+   interpreter, a "RuntimeWarning" is emitted.
+
+   Return "NULL" with an exception set on error.
+
+   Note:
+
+     Most uses of this function should be using
+     "PyModule_FromDefAndSpec()" instead; only use this if you are
+     sure you need it.
+
+   Added in version 3.5.
+
+int PyModule_ExecDef(PyObject *module, PyModuleDef *def)
+    * Part of the Stable ABI since version 3.7.*
+
+   Process any execution slots ("Py_mod_exec") given in *def*.
+
+   Added in version 3.5.
+
+int PyModule_SetDocString(PyObject *module, const char *docstring)
+    * Part of the Stable ABI since version 3.7.*
+
+   Set the docstring for *module* to *docstring*. This function is
+   called automatically when creating a module from "PyModuleDef",
+   using either "PyModule_Create" or "PyModule_FromDefAndSpec".
+
+   Added in version 3.5.
+
+int PyModule_AddFunctions(PyObject *module, PyMethodDef *functions)
+    * Part of the Stable ABI since version 3.7.*
+
+   Add the functions from the "NULL" terminated *functions* array to
+   *module*. Refer to the "PyMethodDef" documentation for details on
+   individual entries (due to the lack of a shared module namespace,
+   module level "functions" implemented in C typically receive the
+   module as their first parameter, making them similar to instance
+   methods on Python classes). This function is called automatically
+   when creating a module from "PyModuleDef", using either
+   "PyModule_Create" or "PyModule_FromDefAndSpec".
+
+   Added in version 3.5.
+
+
+Support functions
+-----------------
+
+The module initialization function (if using single phase
+initialization) or a function called from a module execution slot (if
+using multi-phase initialization), can use the following functions to
+help initialize the module state:
+
+int PyModule_AddObjectRef(PyObject *module, const char *name, PyObject *value)
+    * Part of the Stable ABI since version 3.10.*
+
+   Add an object to *module* as *name*.  This is a convenience
+   function which can be used from the module's initialization
+   function.
+
+   On success, return "0". On error, raise an exception and return
+   "-1".
+
+   Return "-1" if *value* is "NULL". It must be called with an
+   exception raised in this case.
+
+   Example usage:
+
+      static int
+      add_spam(PyObject *module, int value)
+      {
+          PyObject *obj = PyLong_FromLong(value);
+          if (obj == NULL) {
+              return -1;
+          }
+          int res = PyModule_AddObjectRef(module, "spam", obj);
+          Py_DECREF(obj);
+          return res;
+       }
+
+   The example can also be written without checking explicitly if
+   *obj* is "NULL":
+
+      static int
+      add_spam(PyObject *module, int value)
+      {
+          PyObject *obj = PyLong_FromLong(value);
+          int res = PyModule_AddObjectRef(module, "spam", obj);
+          Py_XDECREF(obj);
+          return res;
+       }
+
+   Note that "Py_XDECREF()" should be used instead of "Py_DECREF()" in
+   this case, since *obj* can be "NULL".
+
+   Added in version 3.10.
+
+int PyModule_AddObject(PyObject *module, const char *name, PyObject *value)
+    * Part of the Stable ABI.*
+
+   Similar to "PyModule_AddObjectRef()", but steals a reference to
+   *value* on success (if it returns "0").
+
+   The new "PyModule_AddObjectRef()" function is recommended, since it
+   is easy to introduce reference leaks by misusing the
+   "PyModule_AddObject()" function.
+
+   Note:
+
+     Unlike other functions that steal references,
+     "PyModule_AddObject()" only releases the reference to *value*
+     **on success**.This means that its return value must be checked,
+     and calling code must "Py_DECREF()" *value* manually on error.
+
+   Example usage:
+
+      static int
+      add_spam(PyObject *module, int value)
+      {
+          PyObject *obj = PyLong_FromLong(value);
+          if (obj == NULL) {
+              return -1;
+          }
+          if (PyModule_AddObject(module, "spam", obj) < 0) {
+              Py_DECREF(obj);
+              return -1;
+          }
+          // PyModule_AddObject() stole a reference to obj:
+          // Py_DECREF(obj) is not needed here
+          return 0;
+      }
+
+   The example can also be written without checking explicitly if
+   *obj* is "NULL":
+
+      static int
+      add_spam(PyObject *module, int value)
+      {
+          PyObject *obj = PyLong_FromLong(value);
+          if (PyModule_AddObject(module, "spam", obj) < 0) {
+              Py_XDECREF(obj);
+              return -1;
+          }
+          // PyModule_AddObject() stole a reference to obj:
+          // Py_DECREF(obj) is not needed here
+          return 0;
+      }
+
+   Note that "Py_XDECREF()" should be used instead of "Py_DECREF()" in
+   this case, since *obj* can be "NULL".
+
+int PyModule_AddIntConstant(PyObject *module, const char *name, long value)
+    * Part of the Stable ABI.*
+
+   Add an integer constant to *module* as *name*.  This convenience
+   function can be used from the module's initialization function.
+   Return "-1" with an exception set on error, "0" on success.
+
+int PyModule_AddStringConstant(PyObject *module, const char *name, const char *value)
+    * Part of the Stable ABI.*
+
+   Add a string constant to *module* as *name*.  This convenience
+   function can be used from the module's initialization function.
+   The string *value* must be "NULL"-terminated. Return "-1" with an
+   exception set on error, "0" on success.
+
+PyModule_AddIntMacro(module, macro)
+
+   Add an int constant to *module*. The name and the value are taken
+   from *macro*. For example "PyModule_AddIntMacro(module, AF_INET)"
+   adds the int constant *AF_INET* with the value of *AF_INET* to
+   *module*. Return "-1" with an exception set on error, "0" on
+   success.
+
+PyModule_AddStringMacro(module, macro)
+
+   Add a string constant to *module*.
+
+int PyModule_AddType(PyObject *module, PyTypeObject *type)
+    * Part of the Stable ABI since version 3.10.*
+
+   Add a type object to *module*. The type object is finalized by
+   calling internally "PyType_Ready()". The name of the type object is
+   taken from the last component of "tp_name" after dot. Return "-1"
+   with an exception set on error, "0" on success.
+
+   Added in version 3.9.
+
+
+Module lookup
+=============
+
+Single-phase initialization creates singleton modules that can be
+looked up in the context of the current interpreter. This allows the
+module object to be retrieved later with only a reference to the
+module definition.
+
+These functions will not work on modules created using multi-phase
+initialization, since multiple such modules can be created from a
+single definition.
+
+PyObject *PyState_FindModule(PyModuleDef *def)
+    *Return value: Borrowed reference.** Part of the Stable ABI.*
+
+   Returns the module object that was created from *def* for the
+   current interpreter. This method requires that the module object
+   has been attached to the interpreter state with
+   "PyState_AddModule()" beforehand. In case the corresponding module
+   object is not found or has not been attached to the interpreter
+   state yet, it returns "NULL".
+
+int PyState_AddModule(PyObject *module, PyModuleDef *def)
+    * Part of the Stable ABI since version 3.3.*
+
+   Attaches the module object passed to the function to the
+   interpreter state. This allows the module object to be accessible
+   via "PyState_FindModule()".
+
+   Only effective on modules created using single-phase
+   initialization.
+
+   Python calls "PyState_AddModule" automatically after importing a
+   module, so it is unnecessary (but harmless) to call it from module
+   initialization code. An explicit call is needed only if the
+   module's own init code subsequently calls "PyState_FindModule". The
+   function is mainly intended for implementing alternative import
+   mechanisms (either by calling it directly, or by referring to its
+   implementation for details of the required state updates).
+
+   The caller must hold the GIL.
+
+   Return "-1" with an exception set on error, "0" on success.
+
+   Added in version 3.3.
+
+int PyState_RemoveModule(PyModuleDef *def)
+    * Part of the Stable ABI since version 3.3.*
+
+   Removes the module object created from *def* from the interpreter
+   state. Return "-1" with an exception set on error, "0" on success.
+
+   The caller must hold the GIL.
+
+   Added in version 3.3.

python-3.12.6-docs-text/python-3.12.6-docs-text/c-api/none.txt

@@ -0,0 +1,18 @@
+The "None" Object
+*****************
+
+Note that the "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 "PyNone_Check()"
+function for the same reason.
+
+PyObject *Py_None
+
+   The Python "None" object, denoting lack of value.  This object has
+   no methods and is immortal.
+
+Changed in version 3.12: "Py_None" is immortal.
+
+Py_RETURN_NONE
+
+   Return "Py_None" from a function.

python-3.12.6-docs-text/python-3.12.6-docs-text/c-api/number.txt

@@ -0,0 +1,297 @@
+Number Protocol
+***************
+
+int PyNumber_Check(PyObject *o)
+    * Part of the Stable ABI.*
+
+   Returns "1" if the object *o* provides numeric protocols, and false
+   otherwise. This function always succeeds.
+
+   Changed in version 3.8: Returns "1" if *o* is an index integer.
+
+PyObject *PyNumber_Add(PyObject *o1, PyObject *o2)
+    *Return value: New reference.** Part of the Stable ABI.*
+
+   Returns the result of adding *o1* and *o2*, or "NULL" on failure.
+   This is the equivalent of the Python expression "o1 + o2".
+
+PyObject *PyNumber_Subtract(PyObject *o1, PyObject *o2)
+    *Return value: New reference.** Part of the Stable ABI.*
+
+   Returns the result of subtracting *o2* from *o1*, or "NULL" on
+   failure.  This is the equivalent of the Python expression "o1 -
+   o2".
+
+PyObject *PyNumber_Multiply(PyObject *o1, PyObject *o2)
+    *Return value: New reference.** Part of the Stable ABI.*
+
+   Returns the result of multiplying *o1* and *o2*, or "NULL" on
+   failure.  This is the equivalent of the Python expression "o1 *
+   o2".
+
+PyObject *PyNumber_MatrixMultiply(PyObject *o1, PyObject *o2)
+    *Return value: New reference.** Part of the Stable ABI since
+   version 3.7.*
+
+   Returns the result of matrix multiplication on *o1* and *o2*, or
+   "NULL" on failure.  This is the equivalent of the Python expression
+   "o1 @ o2".
+
+   Added in version 3.5.
+
+PyObject *PyNumber_FloorDivide(PyObject *o1, PyObject *o2)
+    *Return value: New reference.** Part of the Stable ABI.*
+
+   Return the floor of *o1* divided by *o2*, or "NULL" on failure.
+   This is the equivalent of the Python expression "o1 // o2".
+
+PyObject *PyNumber_TrueDivide(PyObject *o1, PyObject *o2)
+    *Return value: New reference.** Part of the Stable ABI.*
+
+   Return a reasonable approximation for the mathematical value of
+   *o1* divided by *o2*, or "NULL" on failure.  The return value is
+   "approximate" because binary floating-point numbers are
+   approximate; it is not possible to represent all real numbers in
+   base two.  This function can return a floating-point value when
+   passed two integers.  This is the equivalent of the Python
+   expression "o1 / o2".
+
+PyObject *PyNumber_Remainder(PyObject *o1, PyObject *o2)
+    *Return value: New reference.** Part of the Stable ABI.*
+
+   Returns the remainder of dividing *o1* by *o2*, or "NULL" on
+   failure.  This is the equivalent of the Python expression "o1 %
+   o2".
+
+PyObject *PyNumber_Divmod(PyObject *o1, PyObject *o2)
+    *Return value: New reference.** Part of the Stable ABI.*
+
+   See the built-in function "divmod()". Returns "NULL" on failure.
+   This is the equivalent of the Python expression "divmod(o1, o2)".
+
+PyObject *PyNumber_Power(PyObject *o1, PyObject *o2, PyObject *o3)
+    *Return value: New reference.** Part of the Stable ABI.*
+
+   See the built-in function "pow()". Returns "NULL" on failure.  This
+   is the equivalent of the Python expression "pow(o1, o2, o3)", where
+   *o3* is optional. If *o3* is to be ignored, pass "Py_None" in its
+   place (passing "NULL" for *o3* would cause an illegal memory
+   access).
+
+PyObject *PyNumber_Negative(PyObject *o)
+    *Return value: New reference.** Part of the Stable ABI.*
+
+   Returns the negation of *o* on success, or "NULL" on failure. This
+   is the equivalent of the Python expression "-o".
+
+PyObject *PyNumber_Positive(PyObject *o)
+    *Return value: New reference.** Part of the Stable ABI.*
+
+   Returns *o* on success, or "NULL" on failure.  This is the
+   equivalent of the Python expression "+o".
+
+PyObject *PyNumber_Absolute(PyObject *o)
+    *Return value: New reference.** Part of the Stable ABI.*
+
+   Returns the absolute value of *o*, or "NULL" on failure.  This is
+   the equivalent of the Python expression "abs(o)".
+
+PyObject *PyNumber_Invert(PyObject *o)
+    *Return value: New reference.** Part of the Stable ABI.*
+
+   Returns the bitwise negation of *o* on success, or "NULL" on
+   failure.  This is the equivalent of the Python expression "~o".
+
+PyObject *PyNumber_Lshift(PyObject *o1, PyObject *o2)
+    *Return value: New reference.** Part of the Stable ABI.*
+
+   Returns the result of left shifting *o1* by *o2* on success, or
+   "NULL" on failure.  This is the equivalent of the Python expression
+   "o1 << o2".
+
+PyObject *PyNumber_Rshift(PyObject *o1, PyObject *o2)
+    *Return value: New reference.** Part of the Stable ABI.*
+
+   Returns the result of right shifting *o1* by *o2* on success, or
+   "NULL" on failure.  This is the equivalent of the Python expression
+   "o1 >> o2".
+
+PyObject *PyNumber_And(PyObject *o1, PyObject *o2)
+    *Return value: New reference.** Part of the Stable ABI.*
+
+   Returns the "bitwise and" of *o1* and *o2* on success and "NULL" on
+   failure. This is the equivalent of the Python expression "o1 & o2".
+
+PyObject *PyNumber_Xor(PyObject *o1, PyObject *o2)
+    *Return value: New reference.** Part of the Stable ABI.*
+
+   Returns the "bitwise exclusive or" of *o1* by *o2* on success, or
+   "NULL" on failure.  This is the equivalent of the Python expression
+   "o1 ^ o2".
+
+PyObject *PyNumber_Or(PyObject *o1, PyObject *o2)
+    *Return value: New reference.** Part of the Stable ABI.*
+
+   Returns the "bitwise or" of *o1* and *o2* on success, or "NULL" on
+   failure. This is the equivalent of the Python expression "o1 | o2".
+
+PyObject *PyNumber_InPlaceAdd(PyObject *o1, PyObject *o2)
+    *Return value: New reference.** Part of the Stable ABI.*
+
+   Returns the result of adding *o1* and *o2*, or "NULL" on failure.
+   The operation is done *in-place* when *o1* supports it.  This is
+   the equivalent of the Python statement "o1 += o2".
+
+PyObject *PyNumber_InPlaceSubtract(PyObject *o1, PyObject *o2)
+    *Return value: New reference.** Part of the Stable ABI.*
+
+   Returns the result of subtracting *o2* from *o1*, or "NULL" on
+   failure.  The operation is done *in-place* when *o1* supports it.
+   This is the equivalent of the Python statement "o1 -= o2".
+
+PyObject *PyNumber_InPlaceMultiply(PyObject *o1, PyObject *o2)
+    *Return value: New reference.** Part of the Stable ABI.*
+
+   Returns the result of multiplying *o1* and *o2*, or "NULL" on
+   failure.  The operation is done *in-place* when *o1* supports it.
+   This is the equivalent of the Python statement "o1 *= o2".
+
+PyObject *PyNumber_InPlaceMatrixMultiply(PyObject *o1, PyObject *o2)
+    *Return value: New reference.** Part of the Stable ABI since
+   version 3.7.*
+
+   Returns the result of matrix multiplication on *o1* and *o2*, or
+   "NULL" on failure.  The operation is done *in-place* when *o1*
+   supports it.  This is the equivalent of the Python statement "o1 @=
+   o2".
+
+   Added in version 3.5.
+
+PyObject *PyNumber_InPlaceFloorDivide(PyObject *o1, PyObject *o2)
+    *Return value: New reference.** Part of the Stable ABI.*
+
+   Returns the mathematical floor of dividing *o1* by *o2*, or "NULL"
+   on failure. The operation is done *in-place* when *o1* supports it.
+   This is the equivalent of the Python statement "o1 //= o2".
+
+PyObject *PyNumber_InPlaceTrueDivide(PyObject *o1, PyObject *o2)
+    *Return value: New reference.** Part of the Stable ABI.*
+
+   Return a reasonable approximation for the mathematical value of
+   *o1* divided by *o2*, or "NULL" on failure.  The return value is
+   "approximate" because binary floating-point numbers are
+   approximate; it is not possible to represent all real numbers in
+   base two.  This function can return a floating-point value when
+   passed two integers.  The operation is done *in-place* when *o1*
+   supports it. This is the equivalent of the Python statement "o1 /=
+   o2".
+
+PyObject *PyNumber_InPlaceRemainder(PyObject *o1, PyObject *o2)
+    *Return value: New reference.** Part of the Stable ABI.*
+
+   Returns the remainder of dividing *o1* by *o2*, or "NULL" on
+   failure.  The operation is done *in-place* when *o1* supports it.
+   This is the equivalent of the Python statement "o1 %= o2".
+
+PyObject *PyNumber_InPlacePower(PyObject *o1, PyObject *o2, PyObject *o3)
+    *Return value: New reference.** Part of the Stable ABI.*
+
+   See the built-in function "pow()". Returns "NULL" on failure.  The
+   operation is done *in-place* when *o1* supports it.  This is the
+   equivalent of the Python statement "o1 **= o2" when o3 is
+   "Py_None", or an in-place variant of "pow(o1, o2, o3)" otherwise.
+   If *o3* is to be ignored, pass "Py_None" in its place (passing
+   "NULL" for *o3* would cause an illegal memory access).
+
+PyObject *PyNumber_InPlaceLshift(PyObject *o1, PyObject *o2)
+    *Return value: New reference.** Part of the Stable ABI.*
+
+   Returns the result of left shifting *o1* by *o2* on success, or
+   "NULL" on failure.  The operation is done *in-place* when *o1*
+   supports it.  This is the equivalent of the Python statement "o1
+   <<= o2".
+
+PyObject *PyNumber_InPlaceRshift(PyObject *o1, PyObject *o2)
+    *Return value: New reference.** Part of the Stable ABI.*
+
+   Returns the result of right shifting *o1* by *o2* on success, or
+   "NULL" on failure.  The operation is done *in-place* when *o1*
+   supports it.  This is the equivalent of the Python statement "o1
+   >>= o2".
+
+PyObject *PyNumber_InPlaceAnd(PyObject *o1, PyObject *o2)
+    *Return value: New reference.** Part of the Stable ABI.*
+
+   Returns the "bitwise and" of *o1* and *o2* on success and "NULL" on
+   failure. The operation is done *in-place* when *o1* supports it.
+   This is the equivalent of the Python statement "o1 &= o2".
+
+PyObject *PyNumber_InPlaceXor(PyObject *o1, PyObject *o2)
+    *Return value: New reference.** Part of the Stable ABI.*
+
+   Returns the "bitwise exclusive or" of *o1* by *o2* on success, or
+   "NULL" on failure.  The operation is done *in-place* when *o1*
+   supports it.  This is the equivalent of the Python statement "o1 ^=
+   o2".
+
+PyObject *PyNumber_InPlaceOr(PyObject *o1, PyObject *o2)
+    *Return value: New reference.** Part of the Stable ABI.*
+
+   Returns the "bitwise or" of *o1* and *o2* on success, or "NULL" on
+   failure.  The operation is done *in-place* when *o1* supports it.
+   This is the equivalent of the Python statement "o1 |= o2".
+
+PyObject *PyNumber_Long(PyObject *o)
+    *Return value: New reference.** Part of the Stable ABI.*
+
+   Returns the *o* converted to an integer object on success, or
+   "NULL" on failure.  This is the equivalent of the Python expression
+   "int(o)".
+
+PyObject *PyNumber_Float(PyObject *o)
+    *Return value: New reference.** Part of the Stable ABI.*
+
+   Returns the *o* converted to a float object on success, or "NULL"
+   on failure. This is the equivalent of the Python expression
+   "float(o)".
+
+PyObject *PyNumber_Index(PyObject *o)
+    *Return value: New reference.** Part of the Stable ABI.*
+
+   Returns the *o* converted to a Python int on success or "NULL" with
+   a "TypeError" exception raised on failure.
+
+   Changed in version 3.10: The result always has exact type "int".
+   Previously, the result could have been an instance of a subclass of
+   "int".
+
+PyObject *PyNumber_ToBase(PyObject *n, int base)
+    *Return value: New reference.** Part of the Stable ABI.*
+
+   Returns the integer *n* converted to base *base* as a string.  The
+   *base* argument must be one of 2, 8, 10, or 16.  For base 2, 8, or
+   16, the returned string is prefixed with a base marker of "'0b'",
+   "'0o'", or "'0x'", respectively.  If *n* is not a Python int, it is
+   converted with "PyNumber_Index()" first.
+
+Py_ssize_t PyNumber_AsSsize_t(PyObject *o, PyObject *exc)
+    * Part of the Stable ABI.*
+
+   Returns *o* converted to a "Py_ssize_t" value if *o* can be
+   interpreted as an integer.  If the call fails, an exception is
+   raised and "-1" is returned.
+
+   If *o* can be converted to a Python int but the attempt to convert
+   to a "Py_ssize_t" value would raise an "OverflowError", then the
+   *exc* argument is the type of exception that will be raised
+   (usually "IndexError" or "OverflowError").  If *exc* is "NULL",
+   then the exception is cleared and the value is clipped to
+   "PY_SSIZE_T_MIN" for a negative integer or "PY_SSIZE_T_MAX" for a
+   positive integer.
+
+int PyIndex_Check(PyObject *o)
+    * Part of the Stable ABI since version 3.8.*
+
+   Returns "1" if *o* is an index integer (has the "nb_index" slot of
+   the "tp_as_number" structure filled in), and "0" otherwise. This
+   function always succeeds.

python-3.12.6-docs-text/python-3.12.6-docs-text/c-api/objbuffer.txt

@@ -0,0 +1,54 @@
+Old Buffer Protocol
+*******************
+
+Deprecated since version 3.0.
+
+These functions were part of the "old buffer protocol" API in Python
+2. In Python 3, this protocol doesn't exist anymore but the functions
+are still exposed to ease porting 2.x code.  They act as a
+compatibility wrapper around the new buffer protocol, but they don't
+give you control over the lifetime of the resources acquired when a
+buffer is exported.
+
+Therefore, it is recommended that you call "PyObject_GetBuffer()" (or
+the "y*" or "w*" format codes with the "PyArg_ParseTuple()" family of
+functions) to get a buffer view over an object, and
+"PyBuffer_Release()" when the buffer view can be released.
+
+int PyObject_AsCharBuffer(PyObject *obj, const char **buffer, Py_ssize_t *buffer_len)
+    * Part of the Stable ABI.*
+
+   Returns a pointer to a read-only memory location usable as
+   character-based input.  The *obj* argument must support the single-
+   segment character buffer interface.  On success, returns "0", sets
+   *buffer* to the memory location and *buffer_len* to the buffer
+   length.  Returns "-1" and sets a "TypeError" on error.
+
+int PyObject_AsReadBuffer(PyObject *obj, const void **buffer, Py_ssize_t *buffer_len)
+    * Part of the Stable ABI.*
+
+   Returns a pointer to a read-only memory location containing
+   arbitrary data. The *obj* argument must support the single-segment
+   readable buffer interface.  On success, returns "0", sets *buffer*
+   to the memory location and *buffer_len* to the buffer length.
+   Returns "-1" and sets a "TypeError" on error.
+
+int PyObject_CheckReadBuffer(PyObject *o)
+    * Part of the Stable ABI.*
+
+   Returns "1" if *o* supports the single-segment readable buffer
+   interface. Otherwise returns "0".  This function always succeeds.
+
+   Note that this function tries to get and release a buffer, and
+   exceptions which occur while calling corresponding functions will
+   get suppressed. To get error reporting use "PyObject_GetBuffer()"
+   instead.
+
+int PyObject_AsWriteBuffer(PyObject *obj, void **buffer, Py_ssize_t *buffer_len)
+    * Part of the Stable ABI.*
+
+   Returns a pointer to a writable memory location.  The *obj*
+   argument must support the single-segment, character buffer
+   interface.  On success, returns "0", sets *buffer* to the memory
+   location and *buffer_len* to the buffer length.  Returns "-1" and
+   sets a "TypeError" on error.

python-3.12.6-docs-text/python-3.12.6-docs-text/c-api/object.txt

@@ -0,0 +1,437 @@
+Object Protocol
+***************
+
+PyObject *Py_NotImplemented
+
+   The "NotImplemented" singleton, used to signal that an operation is
+   not implemented for the given type combination.
+
+Py_RETURN_NOTIMPLEMENTED
+
+   Properly handle returning "Py_NotImplemented" from within a C
+   function (that is, create a new *strong reference* to
+   "NotImplemented" and return it).
+
+Py_PRINT_RAW
+
+   Flag to be used with multiple functions that print the object (like
+   "PyObject_Print()" and "PyFile_WriteObject()"). If passed, these
+   function would use the "str()" of the object instead of the
+   "repr()".
+
+int PyObject_Print(PyObject *o, FILE *fp, int flags)
+
+   Print an object *o*, on file *fp*.  Returns "-1" on error.  The
+   flags argument is used to enable certain printing options.  The
+   only option currently supported is "Py_PRINT_RAW"; if given, the
+   "str()" of the object is written instead of the "repr()".
+
+int PyObject_HasAttr(PyObject *o, PyObject *attr_name)
+    * Part of the Stable ABI.*
+
+   Returns "1" if *o* has the attribute *attr_name*, and "0"
+   otherwise.  This is equivalent to the Python expression "hasattr(o,
+   attr_name)".  This function always succeeds.
+
+   Note:
+
+     Exceptions that occur when this calls "__getattr__()" and
+     "__getattribute__()" methods are silently ignored. For proper
+     error handling, use "PyObject_GetAttr()" instead.
+
+int PyObject_HasAttrString(PyObject *o, const char *attr_name)
+    * Part of the Stable ABI.*
+
+   This is the same as "PyObject_HasAttr()", but *attr_name* is
+   specified as a const char* UTF-8 encoded bytes string, rather than
+   a PyObject*.
+
+   Note:
+
+     Exceptions that occur when this calls "__getattr__()" and
+     "__getattribute__()" methods or while creating the temporary
+     "str" object are silently ignored. For proper error handling, use
+     "PyObject_GetAttrString()" instead.
+
+PyObject *PyObject_GetAttr(PyObject *o, PyObject *attr_name)
+    *Return value: New reference.** Part of the Stable ABI.*
+
+   Retrieve an attribute named *attr_name* from object *o*. Returns
+   the attribute value on success, or "NULL" on failure.  This is the
+   equivalent of the Python expression "o.attr_name".
+
+PyObject *PyObject_GetAttrString(PyObject *o, const char *attr_name)
+    *Return value: New reference.** Part of the Stable ABI.*
+
+   This is the same as "PyObject_GetAttr()", but *attr_name* is
+   specified as a const char* UTF-8 encoded bytes string, rather than
+   a PyObject*.
+
+PyObject *PyObject_GenericGetAttr(PyObject *o, PyObject *name)
+    *Return value: New reference.** Part of the Stable ABI.*
+
+   Generic attribute getter function that is meant to be put into a
+   type object's "tp_getattro" slot.  It looks for a descriptor in the
+   dictionary of classes in the object's MRO as well as an attribute
+   in the object's "__dict__" (if present).  As outlined in
+   Implementing Descriptors, data descriptors take preference over
+   instance attributes, while non-data descriptors don't.  Otherwise,
+   an "AttributeError" is raised.
+
+int PyObject_SetAttr(PyObject *o, PyObject *attr_name, PyObject *v)
+    * Part of the Stable ABI.*
+
+   Set the value of the attribute named *attr_name*, for object *o*,
+   to the value *v*. Raise an exception and return "-1" on failure;
+   return "0" on success.  This is the equivalent of the Python
+   statement "o.attr_name = v".
+
+   If *v* is "NULL", the attribute is deleted. This behaviour is
+   deprecated in favour of using "PyObject_DelAttr()", but there are
+   currently no plans to remove it.
+
+int PyObject_SetAttrString(PyObject *o, const char *attr_name, PyObject *v)
+    * Part of the Stable ABI.*
+
+   This is the same as "PyObject_SetAttr()", but *attr_name* is
+   specified as a const char* UTF-8 encoded bytes string, rather than
+   a PyObject*.
+
+   If *v* is "NULL", the attribute is deleted, but this feature is
+   deprecated in favour of using "PyObject_DelAttrString()".
+
+int PyObject_GenericSetAttr(PyObject *o, PyObject *name, PyObject *value)
+    * Part of the Stable ABI.*
+
+   Generic attribute setter and deleter function that is meant to be
+   put into a type object's "tp_setattro" slot.  It looks for a data
+   descriptor in the dictionary of classes in the object's MRO, and if
+   found it takes preference over setting or deleting the attribute in
+   the instance dictionary. Otherwise, the attribute is set or deleted
+   in the object's "__dict__" (if present). On success, "0" is
+   returned, otherwise an "AttributeError" is raised and "-1" is
+   returned.
+
+int PyObject_DelAttr(PyObject *o, PyObject *attr_name)
+
+   Delete attribute named *attr_name*, for object *o*. Returns "-1" on
+   failure. This is the equivalent of the Python statement "del
+   o.attr_name".
+
+int PyObject_DelAttrString(PyObject *o, const char *attr_name)
+
+   This is the same as "PyObject_DelAttr()", but *attr_name* is
+   specified as a const char* UTF-8 encoded bytes string, rather than
+   a PyObject*.
+
+PyObject *PyObject_GenericGetDict(PyObject *o, void *context)
+    *Return value: New reference.** Part of the Stable ABI since
+   version 3.10.*
+
+   A generic implementation for the getter of a "__dict__" descriptor.
+   It creates the dictionary if necessary.
+
+   This function may also be called to get the "__dict__" of the
+   object *o*. Pass "NULL" for *context* when calling it. Since this
+   function may need to allocate memory for the dictionary, it may be
+   more efficient to call "PyObject_GetAttr()" when accessing an
+   attribute on the object.
+
+   On failure, returns "NULL" with an exception set.
+
+   Added in version 3.3.
+
+int PyObject_GenericSetDict(PyObject *o, PyObject *value, void *context)
+    * Part of the Stable ABI since version 3.7.*
+
+   A generic implementation for the setter of a "__dict__" descriptor.
+   This implementation does not allow the dictionary to be deleted.
+
+   Added in version 3.3.
+
+PyObject **_PyObject_GetDictPtr(PyObject *obj)
+
+   Return a pointer to "__dict__" of the object *obj*. If there is no
+   "__dict__", return "NULL" without setting an exception.
+
+   This function may need to allocate memory for the dictionary, so it
+   may be more efficient to call "PyObject_GetAttr()" when accessing
+   an attribute on the object.
+
+PyObject *PyObject_RichCompare(PyObject *o1, PyObject *o2, int opid)
+    *Return value: New reference.** Part of the Stable ABI.*
+
+   Compare the values of *o1* and *o2* using the operation specified
+   by *opid*, which must be one of "Py_LT", "Py_LE", "Py_EQ", "Py_NE",
+   "Py_GT", or "Py_GE", corresponding to "<", "<=", "==", "!=", ">",
+   or ">=" respectively. This is the equivalent of the Python
+   expression "o1 op o2", where "op" is the operator corresponding to
+   *opid*. Returns the value of the comparison on success, or "NULL"
+   on failure.
+
+int PyObject_RichCompareBool(PyObject *o1, PyObject *o2, int opid)
+    * Part of the Stable ABI.*
+
+   Compare the values of *o1* and *o2* using the operation specified
+   by *opid*, like "PyObject_RichCompare()", but returns "-1" on
+   error, "0" if the result is false, "1" otherwise.
+
+Note:
+
+  If *o1* and *o2* are the same object, "PyObject_RichCompareBool()"
+  will always return "1" for "Py_EQ" and "0" for "Py_NE".
+
+PyObject *PyObject_Format(PyObject *obj, PyObject *format_spec)
+    * Part of the Stable ABI.*
+
+   Format *obj* using *format_spec*. This is equivalent to the Python
+   expression "format(obj, format_spec)".
+
+   *format_spec* may be "NULL". In this case the call is equivalent to
+   "format(obj)". Returns the formatted string on success, "NULL" on
+   failure.
+
+PyObject *PyObject_Repr(PyObject *o)
+    *Return value: New reference.** Part of the Stable ABI.*
+
+   Compute a string representation of object *o*.  Returns the string
+   representation on success, "NULL" on failure.  This is the
+   equivalent of the Python expression "repr(o)".  Called by the
+   "repr()" built-in function.
+
+   Changed in version 3.4: This function now includes a debug
+   assertion to help ensure that it does not silently discard an
+   active exception.
+
+PyObject *PyObject_ASCII(PyObject *o)
+    *Return value: New reference.** Part of the Stable ABI.*
+
+   As "PyObject_Repr()", compute a string representation of object
+   *o*, but escape the non-ASCII characters in the string returned by
+   "PyObject_Repr()" with "\x", "\u" or "\U" escapes.  This generates
+   a string similar to that returned by "PyObject_Repr()" in Python 2.
+   Called by the "ascii()" built-in function.
+
+PyObject *PyObject_Str(PyObject *o)
+    *Return value: New reference.** Part of the Stable ABI.*
+
+   Compute a string representation of object *o*.  Returns the string
+   representation on success, "NULL" on failure.  This is the
+   equivalent of the Python expression "str(o)".  Called by the
+   "str()" built-in function and, therefore, by the "print()"
+   function.
+
+   Changed in version 3.4: This function now includes a debug
+   assertion to help ensure that it does not silently discard an
+   active exception.
+
+PyObject *PyObject_Bytes(PyObject *o)
+    *Return value: New reference.** Part of the Stable ABI.*
+
+   Compute a bytes representation of object *o*.  "NULL" is returned
+   on failure and a bytes object on success.  This is equivalent to
+   the Python expression "bytes(o)", when *o* is not an integer.
+   Unlike "bytes(o)", a TypeError is raised when *o* is an integer
+   instead of a zero-initialized bytes object.
+
+int PyObject_IsSubclass(PyObject *derived, PyObject *cls)
+    * Part of the Stable ABI.*
+
+   Return "1" if the class *derived* is identical to or derived from
+   the class *cls*, otherwise return "0".  In case of an error, return
+   "-1".
+
+   If *cls* is a tuple, the check will be done against every entry in
+   *cls*. The result will be "1" when at least one of the checks
+   returns "1", otherwise it will be "0".
+
+   If *cls* has a "__subclasscheck__()" method, it will be called to
+   determine the subclass status as described in **PEP 3119**.
+   Otherwise, *derived* is a subclass of *cls* if it is a direct or
+   indirect subclass, i.e. contained in "cls.__mro__".
+
+   Normally only class objects, i.e. instances of "type" or a derived
+   class, are considered classes.  However, objects can override this
+   by having a "__bases__" attribute (which must be a tuple of base
+   classes).
+
+int PyObject_IsInstance(PyObject *inst, PyObject *cls)
+    * Part of the Stable ABI.*
+
+   Return "1" if *inst* is an instance of the class *cls* or a
+   subclass of *cls*, or "0" if not.  On error, returns "-1" and sets
+   an exception.
+
+   If *cls* is a tuple, the check will be done against every entry in
+   *cls*. The result will be "1" when at least one of the checks
+   returns "1", otherwise it will be "0".
+
+   If *cls* has a "__instancecheck__()" method, it will be called to
+   determine the subclass status as described in **PEP 3119**.
+   Otherwise, *inst* is an instance of *cls* if its class is a
+   subclass of *cls*.
+
+   An instance *inst* can override what is considered its class by
+   having a "__class__" attribute.
+
+   An object *cls* can override if it is considered a class, and what
+   its base classes are, by having a "__bases__" attribute (which must
+   be a tuple of base classes).
+
+Py_hash_t PyObject_Hash(PyObject *o)
+    * Part of the Stable ABI.*
+
+   Compute and return the hash value of an object *o*.  On failure,
+   return "-1". This is the equivalent of the Python expression
+   "hash(o)".
+
+   Changed in version 3.2: The return type is now Py_hash_t.  This is
+   a signed integer the same size as "Py_ssize_t".
+
+Py_hash_t PyObject_HashNotImplemented(PyObject *o)
+    * Part of the Stable ABI.*
+
+   Set a "TypeError" indicating that "type(o)" is not *hashable* and
+   return "-1". This function receives special treatment when stored
+   in a "tp_hash" slot, allowing a type to explicitly indicate to the
+   interpreter that it is not hashable.
+
+int PyObject_IsTrue(PyObject *o)
+    * Part of the Stable ABI.*
+
+   Returns "1" if the object *o* is considered to be true, and "0"
+   otherwise. This is equivalent to the Python expression "not not o".
+   On failure, return "-1".
+
+int PyObject_Not(PyObject *o)
+    * Part of the Stable ABI.*
+
+   Returns "0" if the object *o* is considered to be true, and "1"
+   otherwise. This is equivalent to the Python expression "not o".  On
+   failure, return "-1".
+
+PyObject *PyObject_Type(PyObject *o)
+    *Return value: New reference.** Part of the Stable ABI.*
+
+   When *o* is non-"NULL", returns a type object corresponding to the
+   object type of object *o*. On failure, raises "SystemError" and
+   returns "NULL".  This is equivalent to the Python expression
+   "type(o)". This function creates a new *strong reference* to the
+   return value. There's really no reason to use this function instead
+   of the "Py_TYPE()" function, which returns a pointer of type
+   PyTypeObject*, except when a new *strong reference* is needed.
+
+int PyObject_TypeCheck(PyObject *o, PyTypeObject *type)
+
+   Return non-zero if the object *o* is of type *type* or a subtype of
+   *type*, and "0" otherwise.  Both parameters must be non-"NULL".
+
+Py_ssize_t PyObject_Size(PyObject *o)
+Py_ssize_t PyObject_Length(PyObject *o)
+    * Part of the Stable ABI.*
+
+   Return the length of object *o*.  If the object *o* provides either
+   the sequence and mapping protocols, the sequence length is
+   returned.  On error, "-1" is returned.  This is the equivalent to
+   the Python expression "len(o)".
+
+Py_ssize_t PyObject_LengthHint(PyObject *o, Py_ssize_t defaultvalue)
+
+   Return an estimated length for the object *o*. First try to return
+   its actual length, then an estimate using "__length_hint__()", and
+   finally return the default value. On error return "-1". This is the
+   equivalent to the Python expression "operator.length_hint(o,
+   defaultvalue)".
+
+   Added in version 3.4.
+
+PyObject *PyObject_GetItem(PyObject *o, PyObject *key)
+    *Return value: New reference.** Part of the Stable ABI.*
+
+   Return element of *o* corresponding to the object *key* or "NULL"
+   on failure. This is the equivalent of the Python expression
+   "o[key]".
+
+int PyObject_SetItem(PyObject *o, PyObject *key, PyObject *v)
+    * Part of the Stable ABI.*
+
+   Map the object *key* to the value *v*.  Raise an exception and
+   return "-1" on failure; return "0" on success.  This is the
+   equivalent of the Python statement "o[key] = v".  This function
+   *does not* steal a reference to *v*.
+
+int PyObject_DelItem(PyObject *o, PyObject *key)
+    * Part of the Stable ABI.*
+
+   Remove the mapping for the object *key* from the object *o*.
+   Return "-1" on failure.  This is equivalent to the Python statement
+   "del o[key]".
+
+PyObject *PyObject_Dir(PyObject *o)
+    *Return value: New reference.** Part of the Stable ABI.*
+
+   This is equivalent to the Python expression "dir(o)", returning a
+   (possibly empty) list of strings appropriate for the object
+   argument, or "NULL" if there was an error.  If the argument is
+   "NULL", this is like the Python "dir()", returning the names of the
+   current locals; in this case, if no execution frame is active then
+   "NULL" is returned but "PyErr_Occurred()" will return false.
+
+PyObject *PyObject_GetIter(PyObject *o)
+    *Return value: New reference.** Part of the Stable ABI.*
+
+   This is equivalent to the Python expression "iter(o)". It returns a
+   new iterator for the object argument, or the object  itself if the
+   object is already an iterator.  Raises "TypeError" and returns
+   "NULL" if the object cannot be iterated.
+
+PyObject *PyObject_GetAIter(PyObject *o)
+    *Return value: New reference.** Part of the Stable ABI since
+   version 3.10.*
+
+   This is the equivalent to the Python expression "aiter(o)". Takes
+   an "AsyncIterable" object and returns an "AsyncIterator" for it.
+   This is typically a new iterator but if the argument is an
+   "AsyncIterator", this returns itself. Raises "TypeError" and
+   returns "NULL" if the object cannot be iterated.
+
+   Added in version 3.10.
+
+void *PyObject_GetTypeData(PyObject *o, PyTypeObject *cls)
+    * Part of the Stable ABI since version 3.12.*
+
+   Get a pointer to subclass-specific data reserved for *cls*.
+
+   The object *o* must be an instance of *cls*, and *cls* must have
+   been created using negative "PyType_Spec.basicsize". Python does
+   not check this.
+
+   On error, set an exception and return "NULL".
+
+   Added in version 3.12.
+
+Py_ssize_t PyType_GetTypeDataSize(PyTypeObject *cls)
+    * Part of the Stable ABI since version 3.12.*
+
+   Return the size of the instance memory space reserved for *cls*,
+   i.e. the size of the memory "PyObject_GetTypeData()" returns.
+
+   This may be larger than requested using "-PyType_Spec.basicsize";
+   it is safe to use this larger size (e.g. with "memset()").
+
+   The type *cls* **must** have been created using negative
+   "PyType_Spec.basicsize". Python does not check this.
+
+   On error, set an exception and return a negative value.
+
+   Added in version 3.12.
+
+void *PyObject_GetItemData(PyObject *o)
+
+   Get a pointer to per-item data for a class with
+   "Py_TPFLAGS_ITEMS_AT_END".
+
+   On error, set an exception and return "NULL". "TypeError" is raised
+   if *o* does not have "Py_TPFLAGS_ITEMS_AT_END" set.
+
+   Added in version 3.12.