Merge branch 'main' into feature/filecmp-coverage

Author: Bolotnyj

.gitignore

@@ -180,6 +180,7 @@ Python/frozen_modules/MANIFEST
 
 # Local AI agent scratch state (per-PR and per-branch notebooks, sandbox
 # experiments) and personal agent overrides, none of which are committed.
+/do-not-commit/
 /.claude/pr-*
 /.claude/branch-*
 /.claude/sandbox/

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/descriptor.rst

@@ -72,38 +72,34 @@ found in the dictionary of type objects.
    methods on a type, and correspond to :class:`types.MethodDescriptorType`
    objects in Python.
 
+.. c:var:: PyTypeObject PyWrapperDescr_Type
 
-.. c:struct:: wrapperbase
+   The type object for wrapper descriptor objects created by
+   :c:func:`PyDescr_NewWrapper` and :c:func:`PyWrapper_New`.
 
-   Describes a slot wrapper used by :c:func:`PyDescr_NewWrapper`.
+   Wrapper descriptors are used internally to expose special methods
+   such as ``__repr__`` or ``__add__``, which are implemented by type slots.
+   The type is exposed in Python as  :class:`types.WrapperDescriptorType`.
 
-   Each ``wrapperbase`` record stores the Python-visible name and metadata for a
-   special method implemented by a type slot, together with the wrapper
-   function used to adapt that slot to Python's calling convention.
 
-.. c:function:: PyObject* PyDescr_NewWrapper(PyTypeObject *type, struct wrapperbase *base, void *wrapped)
+.. `wrapperbase` & `PyWrapperFlag_KEYWORDS` show up in search and index,
+   and link here, but are only referenced in prose:
 
-   Create a new wrapper descriptor for extension type *type* from the
-   :c:struct:`wrapperbase` structure *base* and the wrapped slot function
-   pointer
-   *wrapped*.
+.. c:struct:: wrapperbase
+   :no-typesetting:
 
-   Wrapper descriptors expose special methods implemented by type slots. This
-   is the same kind of descriptor that CPython creates for slot-based special
-   methods such as ``__repr__`` or ``__add__``, and it appears in Python as a
-   :class:`types.WrapperDescriptorType` object.
+.. c:macro:: PyWrapperFlag_KEYWORDS
+   :no-typesetting:
 
-   On success, return a :term:`strong reference` to the descriptor. Return
-   ``NULL`` with an exception set on failure.
+.. c:function:: PyObject* PyDescr_NewWrapper(PyTypeObject *type, struct wrapperbase *base, void *wrapped)
 
-.. c:var:: PyTypeObject PyWrapperDescr_Type
+   Create a new wrapper descriptor of type :c:var:`PyWrapperDescr_Type`.
 
-   The type object for wrapper descriptor objects created by
-   :c:func:`PyDescr_NewWrapper` and :c:func:`PyWrapper_New`. Wrapper
-   descriptors are used internally to expose special methods implemented
-   via wrapper structures, and appear in Python as
-   :class:`types.WrapperDescriptorType` objects.
+   This function is meant for internal use only; it and
+   related API (``struct wrapperbase`` and the ``PyWrapperFlag_KEYWORDS``
+   flag) are exposed publicly for backwards compatibility reasons.
 
+   See :c:func:`PyCMethod_New` for wrapping a C function.
 
 .. c:function:: PyObject* PyDescr_NewClassMethod(PyTypeObject *type, PyMethodDef *method)
 
@@ -138,6 +134,30 @@ found in the dictionary of type objects.
    On success, return a :term:`strong reference` to the wrapper object. Return
    ``NULL`` with an exception set on failure.
 
+.. c:macro:: PyDescr_TYPE(descr)
+
+   Return a :term:`borrowed reference` to the type that the descriptor
+   *descr* belongs to. This is accessible as :attr:`~object.__objclass__`
+   in Python.
+
+   *descr* must be a descriptor object created by one of the
+   ``PyDescr_New*`` functions (an instance of
+   :c:var:`PyMethodDescr_Type`, :c:var:`PyClassMethodDescr_Type`,
+   :c:var:`PyMemberDescr_Type`, :c:var:`PyGetSetDescr_Type`, or
+   :c:var:`PyWrapperDescr_Type`). If the passed descriptor is not
+   an instance of one of these types, the behavior is undefined.
+
+
+.. c:macro:: PyDescr_NAME(descr)
+
+   Return the name of the descriptor *descr* as a :term:`borrowed reference`
+   to a :class:`str` object. This is available as :attr:`~definition.__name__`
+   in Python.
+
+   *descr* must be a descriptor object created by one of the ``PyDescr_New*``
+   functions. If not, the behavior is undefined.
+
+
 .. c:macro:: PyDescr_COMMON
 
    This is a macro including the common fields for a

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.