gh-141004: Document remaining parts of the public C API (GH-159892)

Co-authored-by: Petr Viktorin <encukou@gmail.com>

Author: ZeroIntensity

Doc/c-api/code.rst

@@ -176,6 +176,14 @@ bound into a function.
 
    .. versionadded:: 3.12
 
+.. c:macro:: PY_FOREACH_CODE_EVENT(V)
+
+   Apply the macro *V* to each suffix of :c:type:`PyCodeEvent`
+   constants.
+   Currently expands to ``V(CREATE) V(DESTROY)``.
+   The macro *V* must accept one event name and supply any punctuation
+   needed between expansions.
+
 .. c:type:: int (*PyCode_WatchCallback)(PyCodeEvent event, PyCodeObject* co)
 
    Type of a code object watcher callback function.

Doc/c-api/conversion.rst

@@ -258,3 +258,23 @@ The argument must be a signed or unsigned :c:expr:`char`.
 .. c:macro:: Py_TOUPPER(c)
 
    Return the uppercase equivalent of the character *c*.
+
+
+Bit masks
+---------
+
+The following constants are bit masks used by the character classification
+macros above:
+
+.. c:macro:: PY_CTF_ALNUM
+             PY_CTF_ALPHA
+             PY_CTF_DIGIT
+             PY_CTF_LOWER
+             PY_CTF_SPACE
+             PY_CTF_UPPER
+             PY_CTF_XDIGIT
+
+   Values used internally by the ``Py_IS*`` classification macros above.
+   Exposed for backwards compatibility only.
+
+   .. soft-deprecated:: next

Doc/c-api/dict.rst

@@ -563,6 +563,15 @@ Dictionary objects
 
    .. versionadded:: 3.12
 
+.. c:macro:: PY_FOREACH_DICT_EVENT(V)
+
+   Apply the macro *V* to each suffix of :c:type:`PyDict_WatchEvent`
+   constants.
+   Currently expands to ``V(ADDED) V(MODIFIED) V(DELETED) V(CLONED)
+   V(CLEARED) V(DEALLOCATED)``.
+   The macro *V* must accept one event name and supply any punctuation
+   needed between expansions.
+
 .. c:type:: int (*PyDict_WatchCallback)(PyDict_WatchEvent event, PyObject *dict, PyObject *key, PyObject *new_value)
 
    Type of a dict watcher callback function.

Doc/c-api/exceptions.rst

@@ -407,6 +407,11 @@ an error value).
    documentation.  There is no C API for warning control.
 
 
+.. c:function:: int PyErr_Warn(PyObject *category, const char *message)
+
+   Equivalent to :c:expr:`PyErr_WarnEx(category, message, 1)`.
+
+
 .. c:function:: 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

Doc/c-api/file.rst

@@ -162,18 +162,30 @@ the :mod:`io` APIs instead.
 Soft-deprecated API
 ^^^^^^^^^^^^^^^^^^^
 
-.. soft-deprecated:: 3.15
-
 These are APIs that were included in Python's C API
 by mistake. They are documented solely for completeness; use other
 ``PyFile*`` APIs instead.
 
+
 .. c:function:: PyObject *PyFile_NewStdPrinter(int fd)
 
    Use :c:func:`PyFile_FromFd` with defaults (``fd, NULL, "w", -1, NULL, NULL, NULL, 0``) instead.
 
+   .. soft-deprecated:: 3.15
+
+
 .. c:var:: PyTypeObject PyStdPrinter_Type
 
    Type of file-like objects used internally at Python startup when :py:mod:`io` is
    not yet available.
    Use Python :py:func:`open` or :c:func:`PyFile_FromFd` to create file objects instead.
+
+   .. soft-deprecated:: 3.15
+
+
+.. c:macro:: PY_STDIOTEXTMODE
+
+   The string literal ``"b"``, used to open files in binary mode.
+   Exposed for backwards compatibility only.
+
+   .. soft-deprecated:: next

Doc/c-api/function.rst

@@ -197,6 +197,15 @@ There are a few functions specific to Python functions.
 
    .. versionadded:: 3.15
 
+.. c:macro:: PY_FOREACH_FUNC_EVENT(V)
+
+   Apply the macro *V* to each suffix of :c:type:`PyFunction_WatchEvent`
+   constants.
+   Currently expands to ``V(CREATE) V(DESTROY) V(MODIFY_CODE)
+   V(MODIFY_DEFAULTS) V(MODIFY_KWDEFAULTS) V(MODIFY_QUALNAME)``.
+   The macro *V* must accept one event name and supply any punctuation
+   needed between expansions.
+
 .. c:type:: int (*PyFunction_WatchCallback)(PyFunction_WatchEvent event, PyFunctionObject *func, PyObject *new_value)
 
    Type of a function watcher callback function.

Doc/c-api/hash.rst

@@ -32,13 +32,19 @@ See also the :c:member:`PyTypeObject.tp_hash` member and :ref:`numeric-hash`.
 .. c:macro:: Py_HASH_FNV
              Py_HASH_SIPHASH24
              Py_HASH_SIPHASH13
+             Py_HASH_EXTERNAL
 
    Numerical values to compare to :c:macro:`Py_HASH_ALGORITHM` to determine
-   which algorithm is used for hashing. The hash algorithm can be configured
-   via the configure :option:`--with-hash-algorithm` option.
+   which algorithm is used for hashing. The built-in hash algorithm can be
+   configured via the configure :option:`--with-hash-algorithm` option.
+
+   :c:macro:`!Py_HASH_EXTERNAL` has value ``0`` and indicates a hash
+   implementation supplied by the application embedding Python; see
+   :c:var:`PyHash_Func`.
 
    .. versionadded:: 3.4
-      Add :c:macro:`!Py_HASH_FNV` and :c:macro:`!Py_HASH_SIPHASH24`.
+      Add :c:macro:`!Py_HASH_FNV`, :c:macro:`!Py_HASH_SIPHASH24`, and
+      :c:macro:`!Py_HASH_EXTERNAL`.
 
    .. versionadded:: 3.11
       Add :c:macro:`!Py_HASH_SIPHASH13`.
@@ -132,6 +138,19 @@ See also the :c:member:`PyTypeObject.tp_hash` member and :ref:`numeric-hash`.
    .. versionadded:: 3.4
 
 
+.. c:var:: PyHash_FuncDef PyHash_Func
+
+   When Python is built with :c:macro:`Py_HASH_ALGORITHM` set to
+   :c:macro:`Py_HASH_EXTERNAL`, the application embedding Python must define
+   this variable to supply a hash implementation instead of using one of
+   Python's built-in hash algorithms.
+
+   .. versionadded:: 3.4
+
+   .. deprecated-removed:: 3.15 3.19
+      Use one of the built-in hash algorithms instead.
+
+
 .. c:function:: PyHash_FuncDef* PyHash_GetFuncDef(void)
 
    Get the hash function definition.

Doc/c-api/intro.rst

@@ -924,13 +924,26 @@ use them.
    C99 doesn't define such a thing directly (size_t is an unsigned integral type).
    See :pep:`353` for details.
 
+
+.. c:macro:: Py_INVALID_SIZE
+
+   A constant of type :c:type:`Py_ssize_t` with value ``-1``, representing an
+   invalid size.
+
+
 .. c:macro:: PY_SSIZE_T_MAX
              PY_SSIZE_T_MIN
 
    The limit values (largest positive one and smallest negative one,
    respecitvely) of type :c:type:`Py_ssize_t`.
 
 
+.. c:macro:: PY_DWORD_MAX
+
+   The maximum value of the Windows ``DWORD`` type.
+   Expands to ``0xffffffff`` on all platforms.
+
+
 .. _api-exceptions:
 
 Exceptions

Doc/c-api/long.rst

@@ -680,6 +680,21 @@ distinguished from a number.  Use :c:func:`PyErr_Occurred` to disambiguate.
    .. versionadded:: 3.12
 
 
+Build configuration
+^^^^^^^^^^^^^^^^^^^
+
+.. c:macro:: PYLONG_BITS_IN_DIGIT
+
+   The number of bits in each digit of CPython's native representation of
+   integers.
+   The value can currently be either ``30`` (the default) or ``15``,
+   selected with :option:`--enable-big-digits` when building Python.
+
+   To access the native representation of integers, use
+   :c:func:`PyLong_GetNativeLayout` and its
+   :c:member:`~PyLongLayout.bits_per_digit` member instead.
+
+
 Export API
 ^^^^^^^^^^
 

Doc/c-api/monitoring.rst

@@ -170,28 +170,56 @@ would typically correspond to a Python function.
    .. The table is here to make the docs searchable, and to allow automatic
       links to the identifiers.
 
-   ================================================== =====================================
-   Macro                                              Event
-   ================================================== =====================================
-   .. c:macro:: PY_MONITORING_EVENT_BRANCH_LEFT       :monitoring-event:`BRANCH_LEFT`
-   .. c:macro:: PY_MONITORING_EVENT_BRANCH_RIGHT      :monitoring-event:`BRANCH_RIGHT`
-   .. c:macro:: PY_MONITORING_EVENT_CALL              :monitoring-event:`CALL`
-   .. c:macro:: PY_MONITORING_EVENT_C_RAISE           :monitoring-event:`C_RAISE`
-   .. c:macro:: PY_MONITORING_EVENT_C_RETURN          :monitoring-event:`C_RETURN`
-   .. c:macro:: PY_MONITORING_EVENT_EXCEPTION_HANDLED :monitoring-event:`EXCEPTION_HANDLED`
-   .. c:macro:: PY_MONITORING_EVENT_INSTRUCTION       :monitoring-event:`INSTRUCTION`
-   .. c:macro:: PY_MONITORING_EVENT_JUMP              :monitoring-event:`JUMP`
-   .. c:macro:: PY_MONITORING_EVENT_LINE              :monitoring-event:`LINE`
-   .. c:macro:: PY_MONITORING_EVENT_PY_RESUME         :monitoring-event:`PY_RESUME`
-   .. c:macro:: PY_MONITORING_EVENT_PY_RETURN         :monitoring-event:`PY_RETURN`
-   .. c:macro:: PY_MONITORING_EVENT_PY_START          :monitoring-event:`PY_START`
-   .. c:macro:: PY_MONITORING_EVENT_PY_THROW          :monitoring-event:`PY_THROW`
-   .. c:macro:: PY_MONITORING_EVENT_PY_UNWIND         :monitoring-event:`PY_UNWIND`
-   .. c:macro:: PY_MONITORING_EVENT_PY_YIELD          :monitoring-event:`PY_YIELD`
-   .. c:macro:: PY_MONITORING_EVENT_RAISE             :monitoring-event:`RAISE`
-   .. c:macro:: PY_MONITORING_EVENT_RERAISE           :monitoring-event:`RERAISE`
-   .. c:macro:: PY_MONITORING_EVENT_STOP_ITERATION    :monitoring-event:`STOP_ITERATION`
-   ================================================== =====================================
+   .. list-table::
+      :header-rows: 1
+      :widths: 50 37
+
+      * - Macro
+        - Event
+      * - .. c:macro:: PY_MONITORING_EVENT_BRANCH_LEFT
+        - :monitoring-event:`BRANCH_LEFT`
+      * - .. c:macro:: PY_MONITORING_EVENT_BRANCH_RIGHT
+        - :monitoring-event:`BRANCH_RIGHT`
+      * - .. c:macro:: PY_MONITORING_EVENT_CALL
+        - :monitoring-event:`CALL`
+      * - .. c:macro:: PY_MONITORING_EVENT_C_RAISE
+        - :monitoring-event:`C_RAISE`
+      * - .. c:macro:: PY_MONITORING_EVENT_C_RETURN
+        - :monitoring-event:`C_RETURN`
+      * - .. c:macro:: PY_MONITORING_EVENT_EXCEPTION_HANDLED
+        - :monitoring-event:`EXCEPTION_HANDLED`
+      * - .. c:macro:: PY_MONITORING_EVENT_INSTRUCTION
+        - :monitoring-event:`INSTRUCTION`
+      * - .. c:macro:: PY_MONITORING_EVENT_JUMP
+        - :monitoring-event:`JUMP`
+      * - .. c:macro:: PY_MONITORING_EVENT_LINE
+        - :monitoring-event:`LINE`
+      * - .. c:macro:: PY_MONITORING_EVENT_PY_RESUME
+        - :monitoring-event:`PY_RESUME`
+      * - .. c:macro:: PY_MONITORING_EVENT_PY_RETURN
+        - :monitoring-event:`PY_RETURN`
+      * - .. c:macro:: PY_MONITORING_EVENT_PY_START
+        - :monitoring-event:`PY_START`
+      * - .. c:macro:: PY_MONITORING_EVENT_PY_THROW
+        - :monitoring-event:`PY_THROW`
+      * - .. c:macro:: PY_MONITORING_EVENT_PY_UNWIND
+        - :monitoring-event:`PY_UNWIND`
+      * - .. c:macro:: PY_MONITORING_EVENT_PY_YIELD
+        - :monitoring-event:`PY_YIELD`
+      * - .. c:macro:: PY_MONITORING_EVENT_RAISE
+        - :monitoring-event:`RAISE`
+      * - .. c:macro:: PY_MONITORING_EVENT_RERAISE
+        - :monitoring-event:`RERAISE`
+      * - .. c:macro:: PY_MONITORING_EVENT_STOP_ITERATION
+        - :monitoring-event:`STOP_ITERATION`
+      * - .. c:macro:: PY_MONITORING_EVENT_BRANCH
+
+             .. deprecated:: 3.14
+                Use :c:macro:`PY_MONITORING_EVENT_BRANCH_LEFT`
+                and :c:macro:`PY_MONITORING_EVENT_BRANCH_RIGHT` instead.
+
+        - :monitoring-event:`BRANCH_LEFT` and :monitoring-event:`BRANCH_RIGHT`
+
 
 .. c:function:: int PyMonitoring_ExitScope(void)