Merge branch 'main' into frozen-dict-partial

Author: brijkapadia

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

@@ -3057,6 +3057,24 @@ Buffer Object Structures
 
    (5) Return ``0``.
 
+   **Thread safety:**
+
+   In the :term:`free-threaded build`, implementations must ensure:
+
+   * The export counter increment in step (3) is atomic.
+
+   * The underlying buffer data remains valid and at a stable memory
+     location for the lifetime of all exports.
+
+   * For objects that support resizing or reallocation (such as
+     :class:`bytearray`), the export counter is checked atomically before
+     such operations, and :exc:`BufferError` is raised if exports exist.
+
+   * The function is safe to call concurrently from multiple threads.
+
+   See also :ref:`thread-safety-memoryview` for the Python-level
+   thread safety guarantees of :class:`memoryview` objects.
+
    If *exporter* is part of a chain or tree of buffer providers, two main
    schemes can be used:
 
@@ -3102,6 +3120,16 @@ Buffer Object Structures
 
    (2) If the counter is ``0``, free all memory associated with *view*.
 
+   **Thread safety:**
+
+   In the :term:`free-threaded build`:
+
+   * The export counter decrement in step (1) must be atomic.
+
+   * Resource cleanup when the counter reaches zero must be done atomically,
+     as the final release may race with concurrent releases from other
+     threads and dellocation must only happen once.
+
    The exporter MUST use the :c:member:`~Py_buffer.internal` field to keep
    track of buffer-specific resources. This field is guaranteed to remain
    constant, while a consumer MAY pass a copy of the original buffer as the

Doc/library/asyncio-task.rst

@@ -557,7 +557,7 @@ Running Tasks Concurrently
       provides stronger safety guarantees than *gather* for scheduling a nesting of subtasks:
       if a task (or a subtask, a task scheduled by a task)
       raises an exception, *TaskGroup* will, while *gather* will not,
-      cancel the remaining scheduled tasks).
+      cancel the remaining scheduled tasks.
 
    .. _asyncio_example_gather:
 

Doc/library/stdtypes.rst

@@ -3514,6 +3514,11 @@ The representation of bytearray objects uses the bytes literal format
 ``bytearray([46, 46, 46])``.  You can always convert a bytearray object into
 a list of integers using ``list(b)``.
 
+.. seealso::
+
+   For detailed information on thread-safety guarantees for :class:`bytearray`
+   objects, see :ref:`thread-safety-bytearray`.
+
 
 .. _bytes-methods:
 
@@ -5040,6 +5045,9 @@ copying.
 
       .. versionadded:: 3.3
 
+For information on the thread safety of :class:`memoryview` objects in
+the :term:`free-threaded build`, see :ref:`thread-safety-memoryview`.
+
 
 .. _types-set:
 

Doc/library/threadsafety.rst

@@ -447,3 +447,160 @@ atomic:
 
 Consider external synchronization when sharing :class:`set` instances
 across threads.  See :ref:`freethreading-python-howto` for more information.
+
+
+.. _thread-safety-bytearray:
+
+Thread safety for bytearray objects
+===================================
+
+   The :func:`len` function is lock-free and :term:`atomic <atomic operation>`.
+
+   Concatenation and comparisons use the buffer protocol, which prevents
+   resizing but does not hold the per-object lock. These operations may
+   observe intermediate states from concurrent modifications:
+
+   .. code-block::
+      :class: maybe
+
+      ba + other    # may observe concurrent writes
+      ba == other   # may observe concurrent writes
+      ba < other    # may observe concurrent writes
+
+   All other operations from here on hold the per-object lock.
+
+   Reading a single element or slice is safe to call from multiple threads:
+
+   .. code-block::
+      :class: good
+
+      ba[i]        # bytearray.__getitem__
+      ba[i:j]      # slice
+
+   The following operations are safe to call from multiple threads and will
+   not corrupt the bytearray:
+
+   .. code-block::
+      :class: good
+
+      ba[i] = x         # write single byte
+      ba[i:j] = values  # write slice
+      ba.append(x)      # append single byte
+      ba.extend(other)  # extend with iterable
+      ba.insert(i, x)   # insert single byte
+      ba.pop()          # remove and return last byte
+      ba.pop(i)         # remove and return byte at index
+      ba.remove(x)      # remove first occurrence
+      ba.reverse()      # reverse in place
+      ba.clear()        # remove all bytes
+
+   Slice assignment locks both objects when *values* is a :class:`bytearray`:
+
+   .. code-block::
+      :class: good
+
+      ba[i:j] = other_bytearray  # both locked
+
+   The following operations return new objects and hold the per-object lock
+   for the duration:
+
+   .. code-block::
+      :class: good
+
+      ba.copy()     # returns a shallow copy
+      ba * n        # repeat into new bytearray
+
+   The membership test holds the lock for its duration:
+
+   .. code-block::
+      :class: good
+
+      x in ba       # bytearray.__contains__
+
+   All other bytearray methods (such as :meth:`~bytearray.find`,
+   :meth:`~bytearray.replace`, :meth:`~bytearray.split`,
+   :meth:`~bytearray.decode`, etc.) hold the per-object lock for their
+   duration.
+
+   Operations that involve multiple accesses, as well as iteration, are never
+   atomic:
+
+   .. code-block::
+      :class: bad
+
+      # NOT atomic: check-then-act
+      if x in ba:
+          ba.remove(x)
+
+      # NOT thread-safe: iteration while modifying
+      for byte in ba:
+          process(byte)  # another thread may modify ba
+
+   To safely iterate over a bytearray that may be modified by another
+   thread, iterate over a copy:
+
+   .. code-block::
+      :class: good
+
+      # Make a copy to iterate safely
+      for byte in ba.copy():
+          process(byte)
+
+   Consider external synchronization when sharing :class:`bytearray` instances
+   across threads.  See :ref:`freethreading-python-howto` for more information.
+
+
+.. _thread-safety-memoryview:
+
+Thread safety for memoryview objects
+====================================
+
+:class:`memoryview` objects provide access to the internal data of an
+underlying object without copying. Thread safety depends on both the
+memoryview itself and the underlying buffer exporter.
+
+The memoryview implementation uses atomic operations to track its own
+exports in the :term:`free-threaded build`. Creating and
+releasing a memoryview are thread-safe. Attribute access (e.g.,
+:attr:`~memoryview.shape`, :attr:`~memoryview.format`) reads fields that
+are immutable for the lifetime of the memoryview, so concurrent reads
+are safe as long as the memoryview has not been released.
+
+However, the actual data accessed through the memoryview is owned by the
+underlying object. Concurrent access to this data is only safe if the
+underlying object supports it:
+
+* For immutable objects like :class:`bytes`, concurrent reads through
+  multiple memoryviews are safe.
+
+* For mutable objects like :class:`bytearray`, reading and writing the
+  same memory region from multiple threads without external
+  synchronization is not safe and may result in data corruption.
+  Note that even read-only memoryviews of mutable objects do not
+  prevent data races if the underlying object is modified from
+  another thread.
+
+.. code-block::
+   :class: bad
+
+   # NOT safe: concurrent writes to the same buffer
+   data = bytearray(1000)
+   view = memoryview(data)
+   # Thread 1: view[0:500] = b'x' * 500
+   # Thread 2: view[0:500] = b'y' * 500
+
+.. code-block::
+   :class: good
+
+   # Safe: use a lock for concurrent access
+   import threading
+   lock = threading.Lock()
+   data = bytearray(1000)
+   view = memoryview(data)
+
+   with lock:
+       view[0:500] = b'x' * 500
+
+Resizing or reallocating the underlying object (such as calling
+:meth:`bytearray.resize`) while a memoryview is exported raises
+:exc:`BufferError`. This is enforced regardless of threading.

Doc/library/wave.rst

@@ -9,14 +9,19 @@
 --------------
 
 The :mod:`!wave` module provides a convenient interface to the Waveform Audio
-"WAVE" (or "WAV") file format. Only uncompressed PCM encoded wave files are
-supported.
+"WAVE" (or "WAV") file format.
+
+The module supports uncompressed PCM and IEEE floating-point WAV formats.
 
 .. versionchanged:: 3.12
 
    Support for ``WAVE_FORMAT_EXTENSIBLE`` headers was added, provided that the
    extended format is ``KSDATAFORMAT_SUBTYPE_PCM``.
 
+.. versionchanged:: next
+
+   Support for reading and writing ``WAVE_FORMAT_IEEE_FLOAT`` files was added.
+
 The :mod:`!wave` module defines the following function and exception:
 
 
@@ -60,6 +65,21 @@ The :mod:`!wave` module defines the following function and exception:
    specification or hits an implementation deficiency.
 
 
+.. data:: WAVE_FORMAT_PCM
+
+   Format code for uncompressed PCM audio.
+
+
+.. data:: WAVE_FORMAT_IEEE_FLOAT
+
+   Format code for IEEE floating-point audio.
+
+
+.. data:: WAVE_FORMAT_EXTENSIBLE
+
+   Format code for WAVE extensible headers.
+
+
 .. _wave-read-objects:
 
 Wave_read Objects
@@ -98,6 +118,14 @@ Wave_read Objects
       Returns number of audio frames.
 
 
+   .. method:: getformat()
+
+      Returns the frame format code.
+
+      This is one of :data:`WAVE_FORMAT_PCM`,
+      :data:`WAVE_FORMAT_IEEE_FLOAT`, or :data:`WAVE_FORMAT_EXTENSIBLE`.
+
+
    .. method:: getcomptype()
 
       Returns compression type (``'NONE'`` is the only supported type).
@@ -112,8 +140,8 @@ Wave_read Objects
    .. method:: getparams()
 
       Returns a :func:`~collections.namedtuple` ``(nchannels, sampwidth,
-      framerate, nframes, comptype, compname)``, equivalent to output of the
-      ``get*()`` methods.
+      framerate, nframes, comptype, compname)``, equivalent to output
+      of the ``get*()`` methods.
 
 
    .. method:: readframes(n)
@@ -190,6 +218,9 @@ Wave_write Objects
 
       Set the sample width to *n* bytes.
 
+      For :data:`WAVE_FORMAT_IEEE_FLOAT`, only 4-byte (32-bit) and
+      8-byte (64-bit) sample widths are supported.
+
 
    .. method:: getsampwidth()
 
@@ -238,11 +269,32 @@ Wave_write Objects
       Return the human-readable compression type name.
 
 
+   .. method:: setformat(format)
+
+      Set the frame format code.
+
+      Supported values are :data:`WAVE_FORMAT_PCM` and
+      :data:`WAVE_FORMAT_IEEE_FLOAT`.
+
+      When setting :data:`WAVE_FORMAT_IEEE_FLOAT`, the sample width must be
+      4 or 8 bytes.
+
+
+   .. method:: getformat()
+
+      Return the current frame format code.
+
+
    .. method:: setparams(tuple)
 
-      The *tuple* should be ``(nchannels, sampwidth, framerate, nframes, comptype,
-      compname)``, with values valid for the ``set*()`` methods.  Sets all
-      parameters.
+      The *tuple* should be
+      ``(nchannels, sampwidth, framerate, nframes, comptype, compname, format)``,
+      with values valid for the ``set*()`` methods. Sets all parameters.
+
+      For backwards compatibility, a 6-item tuple without *format* is also
+      accepted and defaults to :data:`WAVE_FORMAT_PCM`.
+
+      For ``format=WAVE_FORMAT_IEEE_FLOAT``, *sampwidth* must be 4 or 8.
 
 
    .. method:: getparams()
@@ -279,3 +331,6 @@ Wave_write Objects
       Note that it is invalid to set any parameters after calling :meth:`writeframes`
       or :meth:`writeframesraw`, and any attempt to do so will raise
       :exc:`wave.Error`.
+
+      For :data:`WAVE_FORMAT_IEEE_FLOAT` output, a ``fact`` chunk is written as
+      required by the WAVE specification for non-PCM formats.