Deploying to gh-pages from @ 5c9e7b5 🚀

Author: mattwang44

.buildinfo

@@ -1,4 +1,4 @@
 # Sphinx build info version 1
 # This file records the configuration used when building these files. When it is not found, a full rebuild will be done.
-config: d6751eade72bed0b8f7a3e9e8373c012
+config: 429e5f11a7c447b979c1ef472ceffa09
 tags: b5e2c454ba7771976391ed0cecdde553

_sources/c-api/bytearray.rst.txt

@@ -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)
 

_sources/c-api/bytes.rst.txt

@@ -123,6 +123,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)
 
@@ -181,13 +185,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)
 
@@ -206,6 +217,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)
 

_sources/c-api/file.rst.txt

@@ -123,9 +123,12 @@ the :mod:`io` APIs instead.
 
    Write object *obj* to file object *p*.  The only supported flag for *flags* is
    :c:macro:`Py_PRINT_RAW`; if given, the :func:`str` of the object is written
-   instead of the :func:`repr`.  Return ``0`` on success or ``-1`` on failure; the
-   appropriate exception will be set.
+   instead of the :func:`repr`.
+
+   If *obj* is ``NULL``, write the string ``"<NULL>"``.
 
+   Return ``0`` on success or ``-1`` on failure; the
+   appropriate exception will be set.
 
 .. c:function:: int PyFile_WriteString(const char *s, PyObject *p)
 

_sources/c-api/float.rst.txt

@@ -194,8 +194,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
@@ -209,7 +209,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.

_sources/c-api/list.rst.txt

@@ -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)
 

_sources/c-api/object.rst.txt

@@ -319,6 +319,8 @@ Object Protocol
    representation on success, ``NULL`` on failure.  This is the equivalent of the
    Python expression ``repr(o)``.  Called by the :func:`repr` built-in function.
 
+   If argument is ``NULL``, return the string ``'<NULL>'``.
+
    .. versionchanged:: 3.4
       This function now includes a debug assertion to help ensure that it
       does not silently discard an active exception.
@@ -333,6 +335,8 @@ Object Protocol
    a string similar to that returned by :c:func:`PyObject_Repr` in Python 2.
    Called by the :func:`ascii` built-in function.
 
+   If argument is ``NULL``, return the string ``'<NULL>'``.
+
    .. index:: string; PyObject_Str (C function)
 
 
@@ -343,6 +347,8 @@ Object Protocol
    Python expression ``str(o)``.  Called by the :func:`str` built-in function
    and, therefore, by the :func:`print` function.
 
+   If argument is ``NULL``, return the string ``'<NULL>'``.
+
    .. versionchanged:: 3.4
       This function now includes a debug assertion to help ensure that it
       does not silently discard an active exception.
@@ -358,6 +364,8 @@ Object Protocol
    a TypeError is raised when *o* is an integer instead of a zero-initialized
    bytes object.
 
+   If argument is ``NULL``, return the :class:`bytes` object ``b'<NULL>'``.
+
 
 .. c:function:: int PyObject_IsSubclass(PyObject *derived, PyObject *cls)
 

_sources/c-api/typeobj.rst.txt

@@ -3055,6 +3055,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:
 
@@ -3100,6 +3118,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

_sources/c-api/unicode.rst.txt

@@ -1842,8 +1842,6 @@ object.
    On success, return ``0``.
    On error, set an exception, leave the writer unchanged, and return ``-1``.
 
-   .. versionadded:: 3.14
-
 .. c:function:: int PyUnicodeWriter_WriteWideChar(PyUnicodeWriter *writer, const wchar_t *str, Py_ssize_t size)
 
    Write the wide string *str* into *writer*.
@@ -1874,9 +1872,15 @@ object.
 
    Call :c:func:`PyObject_Repr` on *obj* and write the output into *writer*.
 
+   If *obj* is ``NULL``, write the string ``"<NULL>"`` into *writer*.
+
    On success, return ``0``.
    On error, set an exception, leave the writer unchanged, and return ``-1``.
 
+   .. versionchanged:: 3.14.4
+
+      Added support for ``NULL``.
+
 .. c:function:: int PyUnicodeWriter_WriteSubstring(PyUnicodeWriter *writer, PyObject *str, Py_ssize_t start, Py_ssize_t end)
 
    Write the substring ``str[start:end]`` into *writer*.