Merge remote-tracking branch 'upstream/main' into gh-138122

Author: pablogsal

.github/CODEOWNERS

@@ -2299,12 +2299,20 @@ per-object locks for :term:`free-threaded <free threading>` CPython.  They are
 intended to replace reliance on the :term:`global interpreter lock`, and are
 no-ops in versions of Python with the global interpreter lock.
 
+Critical sections are intended to be used for custom types implemented
+in C-API extensions. They should generally not be used with built-in types like
+:class:`list` and :class:`dict` because their public C-APIs
+already use critical sections internally, with the notable
+exception of :c:func:`PyDict_Next`, which requires critical section
+to be acquired externally.
+
 Critical sections avoid deadlocks by implicitly suspending active critical
-sections and releasing the locks during calls to :c:func:`PyEval_SaveThread`.
-When :c:func:`PyEval_RestoreThread` is called, the most recent critical section
-is resumed, and its locks reacquired.  This means the critical section API
-provides weaker guarantees than traditional locks -- they are useful because
-their behavior is similar to the :term:`GIL`.
+sections, hence, they do not provide exclusive access such as provided by
+traditional locks like :c:type:`PyMutex`.  When a critical section is started,
+the per-object lock for the object is acquired. If the code executed inside the
+critical section calls C-API functions then it can suspend the critical section thereby
+releasing the per-object lock, so other threads can acquire the per-object lock
+for the same object.
 
 Variants that accept :c:type:`PyMutex` pointers rather than Python objects are also
 available. Use these variants to start a critical section in a situation where

Doc/c-api/init.rst

@@ -107,7 +107,7 @@ Glossary
       statements.
 
    asynchronous generator iterator
-      An object created by a :term:`asynchronous generator` function.
+      An object created by an :term:`asynchronous generator` function.
 
       This is an :term:`asynchronous iterator` which when called using the
       :meth:`~object.__anext__` method returns an awaitable object which will execute

Doc/glossary.rst

@@ -1911,6 +1911,14 @@ expression support in the :mod:`re` module).
    Return the lowest index in the string where substring *sub* is found within
    the slice ``s[start:end]``.  Optional arguments *start* and *end* are
    interpreted as in slice notation.  Return ``-1`` if *sub* is not found.
+   For example::
+
+      >>> 'spam, spam, spam'.find('sp')
+      0
+      >>> 'spam, spam, spam'.find('sp', 5)
+      6
+
+   See also :meth:`rfind` and :meth:`index`.
 
    .. note::
 

Doc/library/stdtypes.rst

@@ -60,6 +60,15 @@
 #  endif
 #endif // Py_GIL_DISABLED
 
+#ifdef _MSC_VER
+// Ignore MSC warning C4201: "nonstandard extension used: nameless
+// struct/union".  (Only generated for C standard versions less than C11, which
+// we don't *officially* support.)
+__pragma(warning(push))
+__pragma(warning(disable: 4201))
+#endif
+
+
 // Include Python header files
 #include "pyport.h"
 #include "pymacro.h"
@@ -139,4 +148,8 @@
 #include "cpython/pyfpe.h"
 #include "cpython/tracemalloc.h"
 
+#ifdef _MSC_VER
+__pragma(warning(pop))  // warning(disable: 4201)
+#endif
+
 #endif /* !Py_PYTHON_H */

Include/Python.h

@@ -123,18 +123,7 @@ whose size is determined when the object is allocated.
   /* PyObject is opaque */
 #elif !defined(Py_GIL_DISABLED)
 struct _object {
-#if (defined(__GNUC__) || defined(__clang__)) \
-        && !(defined __STDC_VERSION__ && __STDC_VERSION__ >= 201112L)
-    // On C99 and older, anonymous union is a GCC and clang extension
-    __extension__
-#endif
-#ifdef _MSC_VER
-    // Ignore MSC warning C4201: "nonstandard extension used:
-    // nameless struct/union"
-    __pragma(warning(push))
-    __pragma(warning(disable: 4201))
-#endif
-    union {
+    _Py_ANONYMOUS union {
 #if SIZEOF_VOID_P > 4
         PY_INT64_T ob_refcnt_full; /* This field is needed for efficient initialization with Clang on ARM */
         struct {
@@ -153,9 +142,6 @@ struct _object {
 #endif
         _Py_ALIGNED_DEF(_PyObject_MIN_ALIGNMENT, char) _aligner;
     };
-#ifdef _MSC_VER
-    __pragma(warning(pop))
-#endif
 
     PyTypeObject *ob_type;
 };

Include/object.h

@@ -86,6 +86,28 @@
 #    endif
 #endif
 
+
+// _Py_ANONYMOUS: modifier for declaring an anonymous union.
+// Usage: _Py_ANONYMOUS union { ... };
+// Standards/compiler support:
+// - C++ allows anonymous unions, but not structs
+// - C11 and above allows anonymous unions and structs
+// - MSVC has warning(disable: 4201) "nonstandard extension used : nameless
+//   struct/union". This is specific enough that we disable it for all of
+//   Python.h.
+// - GCC & clang needs __extension__ before C11
+// To allow unsupported platforms which need other spellings, we use a
+// predefined value of _Py_ANONYMOUS if it exists.
+#ifndef _Py_ANONYMOUS
+#   if (defined(__GNUC__) || defined(__clang__)) \
+          && !(defined(__STDC_VERSION__) && __STDC_VERSION__ >= 201112L)
+#       define _Py_ANONYMOUS __extension__
+#   else
+#       define _Py_ANONYMOUS
+#   endif
+#endif
+
+
 /* Minimum value between x and y */
 #define Py_MIN(x, y) (((x) > (y)) ? (y) : (x))
 

Include/pymacro.h

@@ -36,21 +36,21 @@
                  efficiently compute the digests of data that share a common
                  initial substring.
 
-Assuming that Python has been built with MD5 support, the following computes
-the MD5 digest of the byte string b'Nobody inspects the spammish repetition':
+Assuming that Python has been built with SHA-2 support, the SHA-256 digest
+of the byte string b'Nobody inspects the spammish repetition' is computed
+as follows:
 
     >>> import hashlib
-    >>> m = hashlib.md5()
+    >>> m = hashlib.sha256()
     >>> m.update(b"Nobody inspects")
     >>> m.update(b" the spammish repetition")
-    >>> m.digest()
-    b'\xbbd\x9c\x83\xdd\x1e\xa5\xc9\xd9\xde\xc9\xa1\x8d\xf0\xff\xe9'
+    >>> m.digest()  # doctest: +ELLIPSIS
+    b'\x03\x1e\xdd}Ae\x15\x93\xc5\xfe\\\x00o\xa5u+7...'
 
 More condensed:
 
-    >>> hashlib.md5(b"Nobody inspects the spammish repetition").hexdigest()
-    'bb649c83dd1ea5c9d9dec9a18df0ffe9'
-
+    >>> hashlib.sha256(b"Nobody inspects the spammish repetition").hexdigest()
+    '031edd7d41651593c5fe5c006fa5752b37fddff7bc4e843aa6af0c950f4b9406'
 """
 
 # This tuple and __get_builtin_constructor() must be modified if a new