Merge branch 'main' into buffer-protocol-thread-safety

Author: lysnikolaou

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)
 
@@ -122,8 +138,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.
 
 
@@ -133,6 +154,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
@@ -143,6 +166,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)
 
@@ -151,6 +177,9 @@ Dictionary objects
    occurred.  Return ``NULL`` **without** an exception set if the key
    wasn't present.
 
+   .. versionchanged:: next
+      Also accept :class:`frozendict`.
+
 
 .. c:function:: PyObject* PyDict_GetItemString(PyObject *p, const char *key)
 
@@ -166,6 +195,9 @@ Dictionary objects
       Prefer using the :c:func:`PyDict_GetItemWithError` function with your own
       :c:func:`PyUnicode_FromString` *key* instead.
 
+   .. versionchanged:: next
+      Also accept :class:`frozendict`.
+
 
 .. c:function:: int PyDict_GetItemStringRef(PyObject *p, const char *key, PyObject **result)
 
@@ -175,6 +207,9 @@ Dictionary objects
 
    .. versionadded:: 3.13
 
+   .. versionchanged:: next
+      Also accept :class:`frozendict`.
+
 
 .. c:function:: PyObject* PyDict_SetDefault(PyObject *p, PyObject *key, PyObject *defaultobj)
 
@@ -238,17 +273,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)
 
@@ -257,11 +307,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)
 
@@ -276,6 +334,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;
@@ -309,7 +369,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::
 
@@ -319,6 +379,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
@@ -329,6 +391,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/library/datetime.rst

@@ -2611,8 +2611,10 @@ requires, and these work on all supported platforms.
 |  ``%M``   | Minute as a zero-padded        | 00, 01, ..., 59        | \(9)  |
 |           | decimal number.                |                        |       |
 +-----------+--------------------------------+------------------------+-------+
-|  ``%n``   | The newline character          | ``\n``                 | \(0)  |
-|           | (``'\n'``).                    |                        |       |
+|  ``%n``   | The newline character          | ``\n``                 |       |
+|           | (``'\n'``). For                |                        |       |
+|           | :meth:`!strptime`, zero or     |                        |       |
+|           | more whitespace.               |                        |       |
 +-----------+--------------------------------+------------------------+-------+
 |  ``%p``   | Locale's equivalent of either  || AM, PM (en_US);       | \(1), |
 |           | AM or PM.                      || am, pm (de_DE)        | \(3)  |
@@ -2625,8 +2627,9 @@ requires, and these work on all supported platforms.
 |  ``%S``   | Second as a zero-padded        | 00, 01, ..., 59        | \(4), |
 |           | decimal number.                |                        | \(9)  |
 +-----------+--------------------------------+------------------------+-------+
-|  ``%t``   | The tab character              | ``\t``                 | \(0)  |
-|           | (``'\t'``).                    |                        |       |
+|  ``%t``   | The tab character (``'\t'``).  | ``\t``                 |       |
+|           | For :meth:`!strptime`,         |                        |       |
+|           | zero or more whitespace.       |                        |       |
 +-----------+--------------------------------+------------------------+-------+
 |  ``%T``   | ISO 8601 time format,          | 10:01:59               |       |
 |           | equivalent to ``%H:%M:%S``.    |                        |       |
@@ -2717,7 +2720,8 @@ differences between platforms in handling of unsupported format specifiers.
    ``%:z`` was added for :meth:`~.datetime.strftime`.
 
 .. versionadded:: 3.15
-   ``%:z``, ``%F``, and ``%D`` were added for :meth:`~.datetime.strptime`.
+   ``%D``, ``%F``, ``%n``, ``%t``, and ``%:z`` were added for
+   :meth:`~.datetime.strptime`.
 
 
 Technical detail

Doc/library/stdtypes.rst

@@ -5254,6 +5254,11 @@ Note, the *elem* argument to the :meth:`~object.__contains__`,
 :meth:`~set.discard` methods may be a set.  To support searching for an equivalent
 frozenset, a temporary one is created from *elem*.
 
+.. seealso::
+
+   For detailed information on thread-safety guarantees for :class:`set`
+   objects, see :ref:`thread-safety-set`.
+
 
 .. _typesmapping:
 

Doc/library/threadsafety.rst

@@ -344,6 +344,111 @@ Consider external synchronization when sharing :class:`dict` instances
 across threads.
 
 
+.. _thread-safety-set:
+
+Thread safety for set objects
+==============================
+
+The :func:`len` function is lock-free and :term:`atomic <atomic operation>`.
+
+The following read operation is lock-free. It does not block concurrent
+modifications and may observe intermediate states from operations that
+hold the per-object lock:
+
+.. code-block::
+   :class: good
+
+   elem in s    # set.__contains__
+
+This operation may compare elements using :meth:`~object.__eq__`, which can
+execute arbitrary Python code. During such comparisons, the set may be
+modified by another thread. For built-in types like :class:`str`,
+:class:`int`, and :class:`float`, :meth:`!__eq__` does not release the
+underlying lock during comparisons and this is not a concern.
+
+All other operations from here on hold the per-object lock.
+
+Adding or removing a single element is safe to call from multiple threads
+and will not corrupt the set:
+
+.. code-block::
+   :class: good
+
+   s.add(elem)      # add element
+   s.remove(elem)   # remove element, raise if missing
+   s.discard(elem)  # remove element if present
+   s.pop()          # remove and return arbitrary element
+
+These operations also compare elements, so the same :meth:`~object.__eq__`
+considerations as above apply.
+
+The :meth:`~set.copy` method returns a new object and holds the per-object lock
+for the duration so that it is always atomic.
+
+The :meth:`~set.clear` method holds the lock for its duration. Other
+threads cannot observe elements being removed.
+
+The following operations only accept :class:`set` or :class:`frozenset`
+as operands and always lock both objects:
+
+.. code-block::
+   :class: good
+
+   s |= other                   # other must be set/frozenset
+   s &= other                   # other must be set/frozenset
+   s -= other                   # other must be set/frozenset
+   s ^= other                   # other must be set/frozenset
+   s & other                    # other must be set/frozenset
+   s | other                    # other must be set/frozenset
+   s - other                    # other must be set/frozenset
+   s ^ other                    # other must be set/frozenset
+
+:meth:`set.update`, :meth:`set.union`, :meth:`set.intersection` and
+:meth:`set.difference` can take multiple iterables as arguments. They all
+iterate through all the passed iterables and do the following:
+
+   * :meth:`set.update` and :meth:`set.union` lock both objects only when
+      the other operand is a :class:`set`, :class:`frozenset`, or :class:`dict`.
+   * :meth:`set.intersection` and :meth:`set.difference` always try to lock
+      all objects.
+
+:meth:`set.symmetric_difference` tries to lock both objects.
+
+The update variants of the above methods also have some differences between
+them:
+
+   * :meth:`set.difference_update` and :meth:`set.intersection_update` try
+      to lock all objects one-by-one.
+   * :meth:`set.symmetric_difference_update` only locks the arguments if it is
+      of type :class:`set`, :class:`frozenset`, or :class:`dict`.
+
+The following methods always try to lock both objects:
+
+.. code-block::
+   :class: good
+
+   s.isdisjoint(other)          # both locked
+   s.issubset(other)            # both locked
+   s.issuperset(other)          # both locked
+
+Operations that involve multiple accesses, as well as iteration, are never
+atomic:
+
+.. code-block::
+   :class: bad
+
+   # NOT atomic: check-then-act
+   if elem in s:
+         s.remove(elem)
+
+   # NOT thread-safe: iteration while modifying
+   for elem in s:
+         process(elem)  # another thread may modify s
+
+Consider external synchronization when sharing :class:`set` instances
+across threads.  See :ref:`freethreading-python-howto` for more information.
+
+
 .. _thread-safety-memoryview:
 
 Thread safety for memoryview objects