Merge branch 'main' into annotate-pydict

Author: lysnikolaou

.github/dependabot.yml

@@ -12,6 +12,10 @@ updates:
         update-types:
           - "version-update:semver-minor"
           - "version-update:semver-patch"
+    groups:
+      actions:
+        patterns:
+          - "*"
     cooldown:
       # https://blog.yossarian.net/2025/11/21/We-should-all-be-using-dependency-cooldowns
       # Cooldowns protect against supply chain attacks by avoiding the

.github/workflows/build.yml

@@ -475,7 +475,7 @@ jobs:
           -x test_subprocess \
           -x test_signal \
           -x test_sysconfig
-    - uses: actions/upload-artifact@v6
+    - uses: actions/upload-artifact@v7
       if: always()
       with:
         name: hypothesis-example-db

.github/workflows/reusable-check-c-api-docs.yml

@@ -15,10 +15,10 @@ jobs:
     runs-on: ubuntu-latest
     timeout-minutes: 5
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
         with:
           persist-credentials: false
-      - uses: actions/setup-python@v5
+      - uses: actions/setup-python@v6
         with:
           python-version: '3.x'
       - name: Check for undocumented C APIs

.github/workflows/reusable-cifuzz.yml

@@ -34,7 +34,7 @@ jobs:
           sanitizer: ${{ inputs.sanitizer }}
       - name: Upload crash
         if: failure() && steps.build.outcome == 'success'
-        uses: actions/upload-artifact@v6
+        uses: actions/upload-artifact@v7
         with:
           name: ${{ inputs.sanitizer }}-artifacts
           path: ./out/artifacts

.github/workflows/reusable-san.yml

@@ -96,7 +96,7 @@ jobs:
       run: find "${GITHUB_WORKSPACE}" -name 'san_log.*' | xargs head -n 1000
     - name: Archive logs
       if: always()
-      uses: actions/upload-artifact@v6
+      uses: actions/upload-artifact@v7
       with:
         name: >-
           ${{ inputs.sanitizer }}-logs-${{

.github/workflows/stale.yml

@@ -14,7 +14,7 @@ jobs:
 
     steps:
     - name: "Check PRs"
-      uses: actions/stale@v9
+      uses: actions/stale@v10
       with:
         repo-token: ${{ secrets.GITHUB_TOKEN }}
         stale-pr-message: 'This PR is stale because it has been open for 30 days with no activity.'

Doc/c-api/bytes.rst

@@ -371,13 +371,17 @@ Getters
 
    Get the writer size.
 
+   The function cannot fail.
+
 .. c:function:: void* PyBytesWriter_GetData(PyBytesWriter *writer)
 
    Get the writer data: start of the internal buffer.
 
    The pointer is valid until :c:func:`PyBytesWriter_Finish` or
    :c:func:`PyBytesWriter_Discard` is called on *writer*.
 
+   The function cannot fail.
+
 
 Low-level API
 ^^^^^^^^^^^^^

Doc/c-api/dict.rst

@@ -42,6 +42,12 @@ Dictionary objects
    enforces read-only behavior.  This is normally used to create a view to
    prevent modification of the dictionary for non-dynamic class types.
 
+   The first argument can be a :class:`dict`, a :class:`frozendict`, or a
+   mapping.
+
+   .. versionchanged:: next
+      Also accept :class:`frozendict`.
+
 
 .. c:var:: PyTypeObject PyDictProxy_Type
 
@@ -68,15 +74,25 @@ Dictionary objects
    *key*, return ``1``, otherwise return ``0``.  On error, return ``-1``.
    This is equivalent to the Python expression ``key in p``.
 
+   The first argument can be a :class:`dict` or a :class:`frozendict`.
+
+   .. versionchanged:: next
+      Also accept :class:`frozendict`.
+
 
 .. c:function:: int PyDict_ContainsString(PyObject *p, const char *key)
 
    This is the same as :c:func:`PyDict_Contains`, but *key* is specified as a
    :c:expr:`const char*` UTF-8 encoded bytes string, rather than a
    :c:expr:`PyObject*`.
 
+   The first argument can be a :class:`dict` or a :class:`frozendict`.
+
    .. versionadded:: 3.13
 
+   .. versionchanged:: next
+      Also accept :class:`frozendict`.
+
 
 .. c:function:: PyObject* PyDict_Copy(PyObject *p)
 
@@ -158,8 +174,13 @@ Dictionary objects
    * If the key is missing, set *\*result* to ``NULL`` and return ``0``.
    * On error, raise an exception and return ``-1``.
 
+   The first argument can be a :class:`dict` or a :class:`frozendict`.
+
    .. versionadded:: 3.13
 
+   .. versionchanged:: next
+      Also accept :class:`frozendict`.
+
    See also the :c:func:`PyObject_GetItem` function.
 
 
@@ -169,6 +190,8 @@ Dictionary objects
    has a key *key*.  Return ``NULL`` if the key *key* is missing *without*
    setting an exception.
 
+   The first argument can be a :class:`dict` or a :class:`frozendict`.
+
    .. note::
 
       Exceptions that occur while this calls :meth:`~object.__hash__` and
@@ -186,6 +209,9 @@ Dictionary objects
       Calling this API without an :term:`attached thread state` had been allowed for historical
       reason. It is no longer allowed.
 
+   .. versionchanged:: next
+      Also accept :class:`frozendict`.
+
 
 .. c:function:: PyObject* PyDict_GetItemWithError(PyObject *p, PyObject *key)
 
@@ -201,6 +227,9 @@ Dictionary objects
       the dictionary concurrently. Prefer :c:func:`PyDict_GetItemRef`, which
       returns a :term:`strong reference`.
 
+   .. versionchanged:: next
+      Also accept :class:`frozendict`.
+
 
 .. c:function:: PyObject* PyDict_GetItemString(PyObject *p, const char *key)
 
@@ -223,6 +252,9 @@ Dictionary objects
       the dictionary concurrently. Prefer :c:func:`PyDict_GetItemStringRef`,
       which returns a :term:`strong reference`.
 
+   .. versionchanged:: next
+      Also accept :class:`frozendict`.
+
 
 .. c:function:: int PyDict_GetItemStringRef(PyObject *p, const char *key, PyObject **result)
 
@@ -232,6 +264,9 @@ Dictionary objects
 
    .. versionadded:: 3.13
 
+   .. versionchanged:: next
+      Also accept :class:`frozendict`.
+
 
 .. c:function:: PyObject* PyDict_SetDefault(PyObject *p, PyObject *key, PyObject *defaultobj)
 
@@ -321,17 +356,32 @@ Dictionary objects
 
    Return a :c:type:`PyListObject` containing all the items from the dictionary.
 
+   The first argument can be a :class:`dict` or a :class:`frozendict`.
+
+   .. versionchanged:: next
+      Also accept :class:`frozendict`.
+
 
 .. c:function:: PyObject* PyDict_Keys(PyObject *p)
 
    Return a :c:type:`PyListObject` containing all the keys from the dictionary.
 
+   The first argument can be a :class:`dict` or a :class:`frozendict`.
+
+   .. versionchanged:: next
+      Also accept :class:`frozendict`.
+
 
 .. c:function:: PyObject* PyDict_Values(PyObject *p)
 
    Return a :c:type:`PyListObject` containing all the values from the dictionary
    *p*.
 
+   The first argument can be a :class:`dict` or a :class:`frozendict`.
+
+   .. versionchanged:: next
+      Also accept :class:`frozendict`.
+
 
 .. c:function:: Py_ssize_t PyDict_Size(PyObject *p)
 
@@ -340,11 +390,19 @@ Dictionary objects
    Return the number of items in the dictionary.  This is equivalent to
    ``len(p)`` on a dictionary.
 
+   The argument can be a :class:`dict` or a :class:`frozendict`.
+
+   .. versionchanged:: next
+      Also accept :class:`frozendict`.
+
 
 .. c:function:: Py_ssize_t PyDict_GET_SIZE(PyObject *p)
 
    Similar to :c:func:`PyDict_Size`, but without error checking.
 
+   .. versionchanged:: next
+      Also accept :class:`frozendict`.
+
 
 .. c:function:: int PyDict_Next(PyObject *p, Py_ssize_t *ppos, PyObject **pkey, PyObject **pvalue)
 
@@ -359,6 +417,8 @@ Dictionary objects
    value represents offsets within the internal dictionary structure, and
    since the structure is sparse, the offsets are not consecutive.
 
+   The first argument can be a :class:`dict` or a :class:`frozendict`.
+
    For example::
 
       PyObject *key, *value;
@@ -392,7 +452,7 @@ Dictionary objects
       }
 
    The function is not thread-safe in the :term:`free-threaded <free threading>`
-   build without external synchronization.  You can use
+   build without external synchronization for a mutable :class:`dict`. You can use
    :c:macro:`Py_BEGIN_CRITICAL_SECTION` to lock the dictionary while iterating
    over it::
 
@@ -402,6 +462,8 @@ Dictionary objects
       }
       Py_END_CRITICAL_SECTION();
 
+   The function is thread-safe on a :class:`frozendict`.
+
    .. note::
 
       On the free-threaded build, this function can be used safely inside a
@@ -412,6 +474,9 @@ Dictionary objects
       :term:`strong reference <strong reference>` (for example, using
       :c:func:`Py_NewRef`).
 
+   .. versionchanged:: next
+      Also accept :class:`frozendict`.
+
 .. c:function:: int PyDict_Merge(PyObject *a, PyObject *b, int override)
 
    Iterate over mapping object *b* adding key-value pairs to dictionary *a*.

Doc/c-api/float.rst

@@ -201,8 +201,8 @@ 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.
 
-Note that NaNs type may not be preserved on IEEE platforms (signaling NaN become
-quiet NaN), for example on x86 systems in 32-bit mode.
+Note that NaN type may not be preserved on IEEE platforms (signaling NaNs become
+quiet NaNs), for example on x86 systems in 32-bit mode.
 
 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
@@ -216,7 +216,7 @@ Pack functions
 
 The pack routines write 2, 4 or 8 bytes, starting at *p*. *le* is an
 :c:expr:`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
+format (exponent last, at ``p+1``, ``p+3``, or ``p+6`` and ``p+7``), zero if you
 want big-endian format (exponent first, at *p*). The :c:macro:`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.

Doc/c-api/list.rst

@@ -74,11 +74,25 @@ List Objects
    Like :c:func:`PyList_GetItemRef`, but returns a
    :term:`borrowed reference` instead of a :term:`strong reference`.
 
+   .. note::
+
+      In the :term:`free-threaded build`, the returned
+      :term:`borrowed reference` may become invalid if another thread modifies
+      the list concurrently. Prefer :c:func:`PyList_GetItemRef`, which returns
+      a :term:`strong reference`.
+
 
 .. c:function:: PyObject* PyList_GET_ITEM(PyObject *list, Py_ssize_t i)
 
    Similar to :c:func:`PyList_GetItem`, but without error checking.
 
+   .. note::
+
+      In the :term:`free-threaded build`, the returned
+      :term:`borrowed reference` may become invalid if another thread modifies
+      the list concurrently. Prefer :c:func:`PyList_GetItemRef`, which returns
+      a :term:`strong reference`.
+
 
 .. c:function:: int PyList_SetItem(PyObject *list, Py_ssize_t index, PyObject *item)
 
@@ -108,6 +122,14 @@ List Objects
       is being replaced; any reference in *list* at position *i* will be
       leaked.
 
+   .. note::
+
+      In the :term:`free-threaded build`, this macro has no internal
+      synchronization. It is normally only used to fill in new lists where no
+      other thread has a reference to the list. If the list may be shared,
+      use :c:func:`PyList_SetItem` instead, which uses a :term:`per-object
+      lock`.
+
 
 .. c:function:: int PyList_Insert(PyObject *list, Py_ssize_t index, PyObject *item)
 
@@ -138,6 +160,12 @@ List Objects
    Return ``0`` on success, ``-1`` on failure.  Indexing from the end of the
    list is not supported.
 
+   .. note::
+
+      In the :term:`free-threaded build`, when *itemlist* is a :class:`list`,
+      both *list* and *itemlist* are locked for the duration of the operation.
+      For other iterables (or ``NULL``), only *list* is locked.
+
 
 .. c:function:: int PyList_Extend(PyObject *list, PyObject *iterable)
 
@@ -150,6 +178,14 @@ List Objects
 
    .. versionadded:: 3.13
 
+   .. note::
+
+      In the :term:`free-threaded build`, when *iterable* is a :class:`list`,
+      :class:`set`, :class:`dict`, or dict view, both *list* and *iterable*
+      (or its underlying dict) are locked for the duration of the operation.
+      For other iterables, only *list* is locked; *iterable* may be
+      concurrently modified by another thread.
+
 
 .. c:function:: int PyList_Clear(PyObject *list)
 
@@ -168,6 +204,14 @@ List Objects
    Sort the items of *list* in place.  Return ``0`` on success, ``-1`` on
    failure.  This is equivalent to ``list.sort()``.
 
+   .. note::
+
+      In the :term:`free-threaded build`, element comparison via
+      :meth:`~object.__lt__` can execute arbitrary Python code, during which
+      the :term:`per-object lock` may be temporarily released. For built-in
+      types (:class:`str`, :class:`int`, :class:`float`), the lock is not
+      released during comparison.
+
 
 .. c:function:: int PyList_Reverse(PyObject *list)