Merge branch 'main' into fix-issue-146452

Author: overlorde

.github/workflows/build.yml

@@ -369,7 +369,7 @@ jobs:
           sudo xcode-select --switch /Applications/Xcode_15.4.app
 
       - name: Build and test
-        run: python3 Apple ci iOS --fast-ci --simulator 'iPhone SE (3rd generation),OS=17.5'
+        run: python3 Platforms/Apple ci iOS --fast-ci --simulator 'iPhone SE (3rd generation),OS=17.5'
 
   build-emscripten:
     name: 'Emscripten'

.pre-commit-config.yaml

@@ -3,9 +3,9 @@ repos:
     rev: a27a2e47c7751b639d2b5badf0ef6ff11fee893f  # frozen: v0.15.4
     hooks:
       - id: ruff-check
-        name: Run Ruff (lint) on Apple/
-        args: [--exit-non-zero-on-fix, --config=Apple/.ruff.toml]
-        files: ^Apple/
+        name: Run Ruff (lint) on Platforms/Apple/
+        args: [--exit-non-zero-on-fix, --config=Platforms/Apple/.ruff.toml]
+        files: ^Platforms/Apple/
       - id: ruff-check
         name: Run Ruff (lint) on Doc/
         args: [--exit-non-zero-on-fix]
@@ -39,9 +39,9 @@ repos:
         args: [--exit-non-zero-on-fix, --config=Tools/wasm/.ruff.toml]
         files: ^Tools/wasm/
       - id: ruff-format
-        name: Run Ruff (format) on Apple/
-        args: [--exit-non-zero-on-fix, --config=Apple/.ruff.toml]
-        files: ^Apple
+        name: Run Ruff (format) on Platforms/Apple/
+        args: [--exit-non-zero-on-fix, --config=Platforms/Apple/.ruff.toml]
+        files: ^Platforms/Apple/
       - id: ruff-format
         name: Run Ruff (format) on Doc/
         args: [--exit-non-zero-on-fix]

Doc/c-api/bytearray.rst

@@ -44,6 +44,10 @@ Direct API functions
 
    On failure, return ``NULL`` with an exception set.
 
+   .. note::
+      If the object implements the buffer protocol, then the buffer
+      must not be mutated while the bytearray object is being created.
+
 
 .. c:function:: PyObject* PyByteArray_FromStringAndSize(const char *string, Py_ssize_t len)
 
@@ -58,6 +62,10 @@ Direct API functions
 
    On failure, return ``NULL`` with an exception set.
 
+   .. note::
+      If the object implements the buffer protocol, then the buffer
+      must not be mutated while the bytearray object is being created.
+
 
 .. c:function:: Py_ssize_t PyByteArray_Size(PyObject *bytearray)
 
@@ -70,6 +78,9 @@ Direct API functions
    ``NULL`` pointer.  The returned array always has an extra
    null byte appended.
 
+   .. note::
+      It is not thread-safe to mutate the bytearray object while using the returned char array.
+
 
 .. c:function:: int PyByteArray_Resize(PyObject *bytearray, Py_ssize_t len)
 
@@ -89,6 +100,9 @@ These macros trade safety for speed and they don't check pointers.
 
    Similar to :c:func:`PyByteArray_AsString`, but without error checking.
 
+   .. note::
+      It is not thread-safe to mutate the bytearray object while using the returned char array.
+
 
 .. c:function:: Py_ssize_t PyByteArray_GET_SIZE(PyObject *bytearray)
 

Doc/c-api/bytes.rst

@@ -127,6 +127,10 @@ called with a non-bytes parameter.
    Return the bytes representation of object *o* that implements the buffer
    protocol.
 
+   .. note::
+      If the object implements the buffer protocol, then the buffer
+      must not be mutated while the bytes object is being created.
+
 
 .. c:function:: Py_ssize_t PyBytes_Size(PyObject *o)
 
@@ -185,13 +189,20 @@ called with a non-bytes parameter.
    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.
 
+   .. note::
+      If *newpart* implements the buffer protocol, then the buffer
+      must not be mutated while the new bytes object is being created.
 
 .. c:function:: void PyBytes_ConcatAndDel(PyObject **bytes, PyObject *newpart)
 
    Create a new bytes object in *\*bytes* containing the contents of *newpart*
    appended to *bytes*.  This version releases the :term:`strong reference`
    to *newpart* (i.e. decrements its reference count).
 
+   .. note::
+      If *newpart* implements the buffer protocol, then the buffer
+      must not be mutated while the new bytes object is being created.
+
 
 .. c:function:: PyObject* PyBytes_Join(PyObject *sep, PyObject *iterable)
 
@@ -210,6 +221,9 @@ called with a non-bytes parameter.
 
    .. versionadded:: 3.14
 
+   .. note::
+      If *iterable* objects implement the buffer protocol, then the buffers
+      must not be mutated while the new bytes object is being created.
 
 .. c:function:: int _PyBytes_Resize(PyObject **bytes, Py_ssize_t newsize)
 

Doc/conf.py

@@ -177,6 +177,7 @@
     ('c:type', '__int64'),
     ('c:type', 'unsigned __int64'),
     ('c:type', 'double'),
+    ('c:type', '_Float16'),
     # Standard C structures
     ('c:struct', 'in6_addr'),
     ('c:struct', 'in_addr'),

Doc/data/threadsafety.dat

@@ -66,10 +66,61 @@ PyList_Reverse:shared:
 # is a list
 PyList_SetSlice:shared:
 
-# Sort - per-object lock held; comparison callbacks may execute
-# arbitrary Python code
+# Sort - per-object lock held; the list is emptied before sorting
+# so other threads may observe an empty list, but they won't see the
+# intermediate states of the sort
 PyList_Sort:shared:
 
 # Extend - lock target list; also lock source when it is a
 # list, set, or dict
 PyList_Extend:shared:
+
+# Creation - pure allocation, no shared state
+PyBytes_FromString:atomic:
+PyBytes_FromStringAndSize:atomic:
+PyBytes_DecodeEscape:atomic:
+
+# Creation from formatting C primitives - pure allocation, no shared state
+PyBytes_FromFormat:atomic:
+PyBytes_FromFormatV:atomic:
+
+# Creation from object - uses buffer protocol so may call arbitrary code;
+# safe as long as the buffer is not mutated by another thread during the operation
+PyBytes_FromObject:shared:
+
+# Size - uses atomic load on free-threaded builds
+PyBytes_Size:atomic:
+PyBytes_GET_SIZE:atomic:
+
+# Raw data - no locking; mutating it is unsafe if the bytes object is shared between threads
+PyBytes_AsString:compatible:
+PyBytes_AS_STRING:compatible:
+PyBytes_AsStringAndSize:compatible:
+
+# Concatenation - uses buffer protocol; safe as long as buffer is not mutated by another thread during the operation
+PyBytes_Concat:shared:
+PyBytes_ConcatAndDel:shared:
+PyBytes_Join:shared:
+
+# Resizing - safe if the object is unique
+_PyBytes_Resize:distinct:
+
+# Repr - atomic as bytes are immutable
+PyBytes_Repr:atomic:
+
+# Creation from object - may call arbitrary code
+PyByteArray_FromObject:shared:
+
+# Creation - pure allocation, no shared state
+PyByteArray_FromStringAndSize:atomic:
+
+# Concatenation - uses buffer protocol; safe as long as buffer is not mutated by another thread during the operation
+PyByteArray_Concat:shared:
+
+# Size - uses atomic load on free-threaded builds
+PyByteArray_Size:atomic:
+PyByteArray_GET_SIZE:atomic:
+
+# Raw data - no locking; mutating it is unsafe if the bytearray object is shared between threads
+PyByteArray_AsString:compatible:
+PyByteArray_AS_STRING:compatible:

Doc/library/array.rst

@@ -9,7 +9,7 @@
 --------------
 
 This module defines an object type which can compactly represent an array of
-basic values: characters, integers, floating-point numbers.  Arrays are mutable :term:`sequence`
+basic values: characters, integers, floating-point numbers, complex numbers.  Arrays are mutable :term:`sequence`
 types and behave very much like lists, except that the type of objects stored in
 them is constrained.  The type is specified at object creation time by using a
 :dfn:`type code`, which is a single character.  The following type codes are
@@ -46,6 +46,11 @@ defined:
 +-----------+--------------------+-------------------+-----------------------+-------+
 | ``'d'``   | double             | float             | 8                     |       |
 +-----------+--------------------+-------------------+-----------------------+-------+
+| ``'F'``   | float complex      | complex           | 8                     | \(3)  |
++-----------+--------------------+-------------------+-----------------------+-------+
+| ``'D'``   | double complex     | complex           | 16                    | \(3)  |
++-----------+--------------------+-------------------+-----------------------+-------+
+
 
 Notes:
 
@@ -63,6 +68,15 @@ Notes:
 (2)
    .. versionadded:: 3.13
 
+(3)
+   Complex types (``F`` and ``D``) are available unconditionally,
+   regardless on support for complex types (the Annex G of the C11 standard)
+   by the C compiler.
+   As specified in the C11 standard, each complex type is represented by a
+   two-element C array containing, respectively, the real and imaginary parts.
+
+   .. versionadded:: 3.15
+
 .. seealso::
 
    The :ref:`ctypes <ctypes-fundamental-data-types>` and
@@ -119,9 +133,9 @@ The module defines the following type:
       The length in bytes of one array item in the internal representation.
 
 
-   .. method:: append(x)
+   .. method:: append(value, /)
 
-      Append a new item with value *x* to the end of the array.
+      Append a new item with the specified value to the end of the array.
 
 
    .. method:: buffer_info()
@@ -146,25 +160,26 @@ The module defines the following type:
    .. method:: byteswap()
 
       "Byteswap" all items of the array.  This is only supported for values which are
-      1, 2, 4, or 8 bytes in size; for other types of values, :exc:`RuntimeError` is
+      1, 2, 4, 8 or 16 bytes in size; for other types of values, :exc:`RuntimeError` is
       raised.  It is useful when reading data from a file written on a machine with a
-      different byte order.
+      different byte order.  Note, that for complex types the order of
+      components (the real part, followed by imaginary part) is preserved.
 
 
-   .. method:: count(x)
+   .. method:: count(value, /)
 
-      Return the number of occurrences of *x* in the array.
+      Return the number of occurrences of *value* in the array.
 
 
-   .. method:: extend(iterable)
+   .. method:: extend(iterable, /)
 
       Append items from *iterable* to the end of the array.  If *iterable* is another
       array, it must have *exactly* the same type code; if not, :exc:`TypeError` will
       be raised.  If *iterable* is not an array, it must be iterable and its elements
       must be the right type to be appended to the array.
 
 
-   .. method:: frombytes(buffer)
+   .. method:: frombytes(buffer, /)
 
       Appends items from the :term:`bytes-like object`, interpreting
       its content as an array of machine values (as if it had been read
@@ -174,55 +189,55 @@ The module defines the following type:
          :meth:`!fromstring` is renamed to :meth:`frombytes` for clarity.
 
 
-   .. method:: fromfile(f, n)
+   .. method:: fromfile(f, n, /)
 
       Read *n* items (as machine values) from the :term:`file object` *f* and append
       them to the end of the array.  If less than *n* items are available,
       :exc:`EOFError` is raised, but the items that were available are still
       inserted into the array.
 
 
-   .. method:: fromlist(list)
+   .. method:: fromlist(list, /)
 
       Append items from the list.  This is equivalent to ``for x in list:
       a.append(x)`` except that if there is a type error, the array is unchanged.
 
 
-   .. method:: fromunicode(s)
+   .. method:: fromunicode(ustr, /)
 
       Extends this array with data from the given Unicode string.
       The array must have type code ``'u'`` or ``'w'``; otherwise a :exc:`ValueError` is raised.
       Use ``array.frombytes(unicodestring.encode(enc))`` to append Unicode data to an
       array of some other type.
 
 
-   .. method:: index(x[, start[, stop]])
+   .. method:: index(value[, start[, stop]])
 
       Return the smallest *i* such that *i* is the index of the first occurrence of
-      *x* in the array.  The optional arguments *start* and *stop* can be
-      specified to search for *x* within a subsection of the array.  Raise
-      :exc:`ValueError` if *x* is not found.
+      *value* in the array.  The optional arguments *start* and *stop* can be
+      specified to search for *value* within a subsection of the array.  Raise
+      :exc:`ValueError` if *value* is not found.
 
       .. versionchanged:: 3.10
          Added optional *start* and *stop* parameters.
 
 
-   .. method:: insert(i, x)
+   .. method:: insert(index, value, /)
 
-      Insert a new item with value *x* in the array before position *i*. Negative
+      Insert a new item *value* in the array before position *index*. Negative
       values are treated as being relative to the end of the array.
 
 
-   .. method:: pop([i])
+   .. method:: pop(index=-1, /)
 
       Removes the item with the index *i* from the array and returns it. The optional
       argument defaults to ``-1``, so that by default the last item is removed and
       returned.
 
 
-   .. method:: remove(x)
+   .. method:: remove(value, /)
 
-      Remove the first occurrence of *x* from the array.
+      Remove the first occurrence of *value* from the array.
 
 
    .. method:: clear()
@@ -247,7 +262,7 @@ The module defines the following type:
          :meth:`!tostring` is renamed to :meth:`tobytes` for clarity.
 
 
-   .. method:: tofile(f)
+   .. method:: tofile(f, /)
 
       Write all items (as machine values) to the :term:`file object` *f*.