Deploy preview for PR 1208 🛫

Author: josix

pr-preview/pr-1208/_sources/c-api/dict.rst.txt

@@ -65,6 +65,11 @@ Dictionary Objects
    *key*, return ``1``, otherwise return ``0``.  On error, return ``-1``.
    This is equivalent to the Python expression ``key in p``.
 
+   .. note::
+
+      The operation is atomic on :term:`free threading <free-threaded build>`
+      when *key* is :class:`str`, :class:`int`, :class:`float`, :class:`bool` or :class:`bytes`.
+
 
 .. c:function:: int PyDict_ContainsString(PyObject *p, const char *key)
 
@@ -87,6 +92,11 @@ Dictionary Objects
    ``0`` on success or ``-1`` on failure.  This function *does not* steal a
    reference to *val*.
 
+   .. note::
+
+      The operation is atomic on :term:`free threading <free-threaded build>`
+      when *key* is :class:`str`, :class:`int`, :class:`float`, :class:`bool` or :class:`bytes`.
+
 
 .. c:function:: int PyDict_SetItemString(PyObject *p, const char *key, PyObject *val)
 
@@ -102,6 +112,11 @@ Dictionary Objects
    If *key* is not in the dictionary, :exc:`KeyError` is raised.
    Return ``0`` on success or ``-1`` on failure.
 
+   .. note::
+
+      The operation is atomic on :term:`free threading <free-threaded build>`
+      when *key* is :class:`str`, :class:`int`, :class:`float`, :class:`bool` or :class:`bytes`.
+
 
 .. c:function:: int PyDict_DelItemString(PyObject *p, const char *key)
 
@@ -120,6 +135,11 @@ Dictionary Objects
    * If the key is missing, set *\*result* to ``NULL`` and return ``0``.
    * On error, raise an exception and return ``-1``.
 
+   .. note::
+
+      The operation is atomic on :term:`free threading <free-threaded build>`
+      when *key* is :class:`str`, :class:`int`, :class:`float`, :class:`bool` or :class:`bytes`.
+
    .. versionadded:: 3.13
 
    See also the :c:func:`PyObject_GetItem` function.
@@ -137,6 +157,13 @@ Dictionary Objects
       :meth:`~object.__eq__` methods are silently ignored.
       Prefer the :c:func:`PyDict_GetItemWithError` function instead.
 
+   .. note::
+
+      In the :term:`free-threaded build`, the returned
+      :term:`borrowed reference` may become invalid if another thread modifies
+      the dictionary concurrently. Prefer :c:func:`PyDict_GetItemRef`, which
+      returns a :term:`strong reference`.
+
    .. versionchanged:: 3.10
       Calling this API without an :term:`attached thread state` had been allowed for historical
       reason. It is no longer allowed.
@@ -149,6 +176,13 @@ Dictionary Objects
    occurred.  Return ``NULL`` **without** an exception set if the key
    wasn't present.
 
+   .. note::
+
+      In the :term:`free-threaded build`, the returned
+      :term:`borrowed reference` may become invalid if another thread modifies
+      the dictionary concurrently. Prefer :c:func:`PyDict_GetItemRef`, which
+      returns a :term:`strong reference`.
+
 
 .. c:function:: PyObject* PyDict_GetItemString(PyObject *p, const char *key)
 
@@ -164,6 +198,13 @@ Dictionary Objects
       Prefer using the :c:func:`PyDict_GetItemWithError` function with your own
       :c:func:`PyUnicode_FromString` *key* instead.
 
+   .. note::
+
+      In the :term:`free-threaded build`, the returned
+      :term:`borrowed reference` may become invalid if another thread modifies
+      the dictionary concurrently. Prefer :c:func:`PyDict_GetItemStringRef`,
+      which returns a :term:`strong reference`.
+
 
 .. c:function:: int PyDict_GetItemStringRef(PyObject *p, const char *key, PyObject **result)
 
@@ -184,6 +225,14 @@ Dictionary Objects
 
    .. versionadded:: 3.4
 
+   .. note::
+
+      In the :term:`free-threaded build`, the returned
+      :term:`borrowed reference` may become invalid if another thread modifies
+      the dictionary concurrently. Prefer :c:func:`PyDict_SetDefaultRef`,
+      which returns a :term:`strong reference`.
+
+
 
 .. c:function:: int PyDict_SetDefaultRef(PyObject *p, PyObject *key, PyObject *default_value, PyObject **result)
 
@@ -203,6 +252,11 @@ Dictionary Objects
    These may refer to the same object: in that case you hold two separate
    references to it.
 
+   .. note::
+
+      The operation is atomic on :term:`free threading <free-threaded build>`
+      when *key* is :class:`str`, :class:`int`, :class:`float`, :class:`bool` or :class:`bytes`.
+
    .. versionadded:: 3.13
 
 
@@ -220,6 +274,11 @@ Dictionary Objects
    Similar to :meth:`dict.pop`, but without the default value and
    not raising :exc:`KeyError` if the key is missing.
 
+   .. note::
+
+      The operation is atomic on :term:`free threading <free-threaded build>`
+      when *key* is :class:`str`, :class:`int`, :class:`float`, :class:`bool` or :class:`bytes`.
+
    .. versionadded:: 3.13
 
 
@@ -336,6 +395,13 @@ Dictionary Objects
    only be added if there is not a matching key in *a*. Return ``0`` on
    success or ``-1`` if an exception was raised.
 
+   .. note::
+
+      In the :term:`free-threaded build`, when *b* is a
+      :class:`dict` (with the standard iterator), both *a* and *b* are locked
+      for the duration of the operation. When *b* is a non-dict mapping, only
+      *a* is locked; *b* may be concurrently modified by another thread.
+
 
 .. c:function:: int PyDict_Update(PyObject *a, PyObject *b)
 
@@ -345,6 +411,13 @@ Dictionary Objects
    argument has no "keys" attribute.  Return ``0`` on success or ``-1`` if an
    exception was raised.
 
+   .. note::
+
+      In the :term:`free-threaded build`, when *b* is a
+      :class:`dict` (with the standard iterator), both *a* and *b* are locked
+      for the duration of the operation. When *b* is a non-dict mapping, only
+      *a* is locked; *b* may be concurrently modified by another thread.
+
 
 .. c:function:: int PyDict_MergeFromSeq2(PyObject *a, PyObject *seq2, int override)
 
@@ -360,13 +433,27 @@ Dictionary Objects
               if override or key not in a:
                   a[key] = value
 
+   .. note::
+
+      In the :term:`free-threaded <free threading>` build, only *a* is locked.
+      The iteration over *seq2* is not synchronized; *seq2* may be concurrently
+      modified by another thread.
+
+
 .. c:function:: int PyDict_AddWatcher(PyDict_WatchCallback callback)
 
    Register *callback* as a dictionary watcher. Return a non-negative integer
    id which must be passed to future calls to :c:func:`PyDict_Watch`. In case
    of error (e.g. no more watcher IDs available), return ``-1`` and set an
    exception.
 
+   .. note::
+
+      This function is not internally synchronized. In the
+      :term:`free-threaded <free threading>` build, callers should ensure no
+      concurrent calls to :c:func:`PyDict_AddWatcher` or
+      :c:func:`PyDict_ClearWatcher` are in progress.
+
    .. versionadded:: 3.12
 
 .. c:function:: int PyDict_ClearWatcher(int watcher_id)
@@ -375,6 +462,13 @@ Dictionary Objects
    :c:func:`PyDict_AddWatcher`. Return ``0`` on success, ``-1`` on error (e.g.
    if the given *watcher_id* was never registered.)
 
+   .. note::
+
+      This function is not internally synchronized. In the
+      :term:`free-threaded <free threading>` build, callers should ensure no
+      concurrent calls to :c:func:`PyDict_AddWatcher` or
+      :c:func:`PyDict_ClearWatcher` are in progress.
+
    .. versionadded:: 3.12
 
 .. c:function:: int PyDict_Watch(int watcher_id, PyObject *dict)

pr-preview/pr-1208/_sources/c-api/set.rst.txt

@@ -92,6 +92,11 @@ the constructor functions work with any iterable Python object.
    actually iterable.  The constructor is also useful for copying a set
    (``c=set(s)``).
 
+   .. note::
+
+      The operation is atomic on :term:`free threading <free-threaded build>`
+      when *iterable* is a :class:`set`, :class:`frozenset` or :class:`dict`.
+
 
 .. c:function:: PyObject* PyFrozenSet_New(PyObject *iterable)
 
@@ -100,6 +105,11 @@ the constructor functions work with any iterable Python object.
    set on success or ``NULL`` on failure.  Raise :exc:`TypeError` if *iterable* is
    not actually iterable.
 
+   .. note::
+
+      The operation is atomic on :term:`free threading <free-threaded build>`
+      when *iterable* is a :class:`set`, :class:`frozenset` or :class:`dict`.
+
 
 The following functions and macros are available for instances of :class:`set`
 or :class:`frozenset` or instances of their subtypes.
@@ -127,6 +137,10 @@ or :class:`frozenset` or instances of their subtypes.
    the *key* is unhashable. Raise :exc:`SystemError` if *anyset* is not a
    :class:`set`, :class:`frozenset`, or an instance of a subtype.
 
+   .. note::
+
+      The operation is atomic on :term:`free threading <free-threaded build>`
+      when *key* is :class:`str`, :class:`int`, :class:`float`, :class:`bool` or :class:`bytes`.
 
 .. c:function:: int PySet_Add(PyObject *set, PyObject *key)
 
@@ -138,6 +152,12 @@ or :class:`frozenset` or instances of their subtypes.
    :exc:`SystemError` if *set* is not an instance of :class:`set` or its
    subtype.
 
+   .. note::
+
+      The operation is atomic on :term:`free threading <free-threaded build>`
+      when *key* is :class:`str`, :class:`int`, :class:`float`, :class:`bool` or :class:`bytes`.
+
+
 
 The following functions are available for instances of :class:`set` or its
 subtypes but not for instances of :class:`frozenset` or its subtypes.
@@ -152,6 +172,11 @@ subtypes but not for instances of :class:`frozenset` or its subtypes.
    temporary frozensets. Raise :exc:`SystemError` if *set* is not an
    instance of :class:`set` or its subtype.
 
+   .. note::
+
+      The operation is atomic on :term:`free threading <free-threaded build>`
+      when *key* is :class:`str`, :class:`int`, :class:`float`, :class:`bool` or :class:`bytes`.
+
 
 .. c:function:: PyObject* PySet_Pop(PyObject *set)
 
@@ -167,6 +192,12 @@ subtypes but not for instances of :class:`frozenset` or its subtypes.
    success. Return ``-1`` and raise :exc:`SystemError` if *set* is not an instance of
    :class:`set` or its subtype.
 
+   .. note::
+
+      In the :term:`free-threaded build`, the set is emptied before its entries
+      are cleared, so other threads will observe an empty set rather than
+      intermediate states.
+
 
 Deprecated API
 ^^^^^^^^^^^^^^

pr-preview/pr-1208/_sources/c-api/unicode.rst.txt

@@ -1868,6 +1868,10 @@ object.
    On success, return ``0``.
    On error, set an exception, leave the writer unchanged, and return ``-1``.
 
+   To write a :class:`str` subclass which overrides the :meth:`~object.__str__`
+   method, :c:func:`PyUnicode_FromObject` can be used to get the original
+   string.
+
 .. c:function:: int PyUnicodeWriter_WriteRepr(PyUnicodeWriter *writer, PyObject *obj)
 
    Call :c:func:`PyObject_Repr` on *obj* and write the output into *writer*.

pr-preview/pr-1208/_sources/library/asyncio-eventloop.rst.txt

@@ -2055,7 +2055,7 @@ Wait until a file descriptor received some data using the
 Set signal handlers for SIGINT and SIGTERM
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-(This ``signals`` example only works on Unix.)
+(This ``signal`` example only works on Unix.)
 
 Register handlers for signals :const:`~signal.SIGINT` and :const:`~signal.SIGTERM`
 using the :meth:`loop.add_signal_handler` method::

pr-preview/pr-1208/_sources/library/asyncio-future.rst.txt

@@ -196,6 +196,10 @@ Future Object
       Otherwise, change the Future's state to *cancelled*,
       schedule the callbacks, and return ``True``.
 
+      The optional string argument *msg* is passed as the argument to the
+      :exc:`CancelledError` exception raised when a cancelled Future
+      is awaited.
+
       .. versionchanged:: 3.9
          Added the *msg* parameter.
 

pr-preview/pr-1208/_sources/library/glob.rst.txt

@@ -83,6 +83,11 @@ The :mod:`!glob` module defines the following functions:
       This function may return duplicate path names if *pathname*
       contains multiple "``**``" patterns and *recursive* is true.
 
+   .. note::
+      Any :exc:`OSError` exceptions raised from scanning the filesystem are
+      suppressed. This includes :exc:`PermissionError` when accessing
+      directories without read permission.
+
    .. versionchanged:: 3.5
       Support for recursive globs using "``**``".
 
@@ -106,6 +111,11 @@ The :mod:`!glob` module defines the following functions:
       This function may return duplicate path names if *pathname*
       contains multiple "``**``" patterns and *recursive* is true.
 
+   .. note::
+      Any :exc:`OSError` exceptions raised from scanning the filesystem are
+      suppressed. This includes :exc:`PermissionError` when accessing
+      directories without read permission.
+
    .. versionchanged:: 3.5
       Support for recursive globs using "``**``".
 

pr-preview/pr-1208/_sources/library/importlib.resources.rst.txt

@@ -31,6 +31,12 @@ not** have to exist as physical files and directories on the file system:
 for example, a package and its resources can be imported from a zip file using
 :py:mod:`zipimport`.
 
+.. warning::
+
+   :mod:`importlib.resources` follows the same security model as the built-in
+   :func:`open` function. Passing untrusted inputs to the functions
+   in this module is unsafe.
+
 .. note::
 
    This module provides functionality similar to `pkg_resources

pr-preview/pr-1208/_sources/library/itertools.rst.txt

@@ -853,7 +853,7 @@ and :term:`generators <generator>` which incur interpreter overhead.
 
    def running_mean(iterable):
        "Yield the average of all values seen so far."
-       # running_mean([8.5, 9.5, 7.5, 6.5]) -> 8.5 9.0 8.5 8.0
+       # running_mean([8.5, 9.5, 7.5, 6.5]) → 8.5 9.0 8.5 8.0
        return map(truediv, accumulate(iterable), count(1))
 
    def repeatfunc(function, times=None, *args):
@@ -935,10 +935,10 @@ and :term:`generators <generator>` which incur interpreter overhead.
                    yield element
 
    def unique(iterable, key=None, reverse=False):
-      "Yield unique elements in sorted order. Supports unhashable inputs."
-      # unique([[1, 2], [3, 4], [1, 2]]) → [1, 2] [3, 4]
-      sequenced = sorted(iterable, key=key, reverse=reverse)
-      return unique_justseen(sequenced, key=key)
+       "Yield unique elements in sorted order. Supports unhashable inputs."
+       # unique([[1, 2], [3, 4], [1, 2]]) → [1, 2] [3, 4]
+       sequenced = sorted(iterable, key=key, reverse=reverse)
+       return unique_justseen(sequenced, key=key)
 
    def sliding_window(iterable, n):
        "Collect data into overlapping fixed-length chunks or blocks."

pr-preview/pr-1208/_sources/library/multiprocessing.rst.txt

@@ -932,7 +932,8 @@ For an example of the usage of queues for interprocess communication see
    standard library's :mod:`queue` module are raised to signal timeouts.
 
    :class:`Queue` implements all the methods of :class:`queue.Queue` except for
-   :meth:`~queue.Queue.task_done` and :meth:`~queue.Queue.join`.
+   :meth:`~queue.Queue.task_done`, :meth:`~queue.Queue.join`, and
+   :meth:`~queue.Queue.shutdown`.
 
    .. method:: qsize()
 

pr-preview/pr-1208/_sources/library/pathlib.rst.txt

@@ -1365,6 +1365,11 @@ Reading directories
    ``False``, this method follows symlinks except when expanding "``**``"
    wildcards. Set *recurse_symlinks* to ``True`` to always follow symlinks.
 
+   .. note::
+      Any :exc:`OSError` exceptions raised from scanning the filesystem are
+      suppressed. This includes :exc:`PermissionError` when accessing
+      directories without read permission.
+
    .. audit-event:: pathlib.Path.glob self,pattern pathlib.Path.glob
 
    .. versionchanged:: 3.12
@@ -1391,6 +1396,11 @@ Reading directories
       The paths are returned in no particular order.
       If you need a specific order, sort the results.
 
+   .. note::
+      Any :exc:`OSError` exceptions raised from scanning the filesystem are
+      suppressed. This includes :exc:`PermissionError` when accessing
+      directories without read permission.
+
    .. seealso::
       :ref:`pathlib-pattern-language` and :meth:`Path.glob` documentation.