Merge branch 'main' into fix-issue-XXXXX

Author: carltongibson

.gitattributes

@@ -69,7 +69,7 @@ Doc/library/token-list.inc                          generated
 Include/internal/pycore_ast.h                       generated
 Include/internal/pycore_ast_state.h                 generated
 Include/internal/pycore_opcode.h                    generated
-Include/internal/pycore_runtime_init_generated.h    generated
+Include/internal/pycore_*_generated.h               generated
 Include/opcode.h                                    generated
 Include/token.h                                     generated
 Lib/keyword.py                                      generated

.github/CODEOWNERS

@@ -63,7 +63,7 @@ Python/traceback.c            @iritkatriel
 # bytecode.
 **/*import*.c                 @brettcannon @encukou @ericsnowcurrently @ncoghlan @warsaw
 **/*import*.py                @brettcannon @encukou @ericsnowcurrently @ncoghlan @warsaw
-**/*importlib/resources/*      @jaraco @warsaw @brettcannon
+**/*importlib/resources/*      @jaraco @warsaw @brettcannon @FFY00
 **/importlib/metadata/*       @jaraco @warsaw
 
 # Dates and times
@@ -137,8 +137,6 @@ Lib/ast.py                    @isidentical
 
 **/*typing*                   @gvanrossum @Fidget-Spinner @JelleZijlstra @AlexWaygood
 
-**/*asyncore                  @giampaolo
-**/*asynchat                  @giampaolo
 **/*ftplib                    @giampaolo
 **/*shutil                    @giampaolo
 
@@ -148,6 +146,8 @@ Lib/ast.py                    @isidentical
 
 **/*tomllib*                  @encukou
 
+**/*sysconfig*                @FFY00
+
 # macOS
 /Mac/                         @python/macos-team
 **/*osx_support*              @python/macos-team

.github/workflows/build.yml

@@ -176,7 +176,7 @@ jobs:
     needs: check_source
     if: needs.check_source.outputs.run_tests == 'true'
     env:
-      OPENSSL_VER: 1.1.1q
+      OPENSSL_VER: 1.1.1s
       PYTHONSTRICTEXTENSIONBUILD: 1
     steps:
     - uses: actions/checkout@v3
@@ -235,7 +235,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        openssl_ver: [1.1.1q, 3.0.5]
+        openssl_ver: [1.1.1s, 3.0.7]
     env:
       OPENSSL_VER: ${{ matrix.openssl_ver }}
       MULTISSL_DIR: ${{ github.workspace }}/multissl
@@ -282,7 +282,7 @@ jobs:
     needs: check_source
     if: needs.check_source.outputs.run_tests == 'true'
     env:
-      OPENSSL_VER: 1.1.1q
+      OPENSSL_VER: 1.1.1s
       PYTHONSTRICTEXTENSIONBUILD: 1
       ASAN_OPTIONS: detect_leaks=0:allocator_may_return_null=1:handle_segv=0
     steps:

Doc/c-api/frame.rst

@@ -79,6 +79,27 @@ See also :ref:`Reflection <reflection>`.
    .. versionadded:: 3.11
 
 
+.. c:function:: PyObject* PyFrame_GetVar(PyFrameObject *frame, PyObject *name)
+
+   Get the variable *name* of *frame*.
+
+   * Return a :term:`strong reference` to the variable value on success.
+   * Raise :exc:`NameError` and return ``NULL`` if the variable does not exist.
+   * Raise an exception and return ``NULL`` on error.
+
+   *name* type must be a :class:`str`.
+
+   .. versionadded:: 3.12
+
+
+.. c:function:: PyObject* PyFrame_GetVarString(PyFrameObject *frame, const char *name)
+
+   Similar to :c:func:`PyFrame_GetVar`, but the variable name is a C string
+   encoded in UTF-8.
+
+   .. versionadded:: 3.12
+
+
 .. c:function:: PyObject* PyFrame_GetLocals(PyFrameObject *frame)
 
    Get the *frame*'s ``f_locals`` attribute (:class:`dict`).

Doc/c-api/refcounting.rst

@@ -7,8 +7,8 @@
 Reference Counting
 ******************
 
-The macros in this section are used for managing reference counts of Python
-objects.
+The functions and macros in this section are used for managing reference counts
+of Python objects.
 
 
 .. c:function:: Py_ssize_t Py_REFCNT(PyObject *o)
@@ -129,6 +129,11 @@ objects.
    It is a good idea to use this macro whenever decrementing the reference
    count of an object that might be traversed during garbage collection.
 
+   .. versionchanged:: 3.12
+      The macro argument is now only evaluated once. If the argument has side
+      effects, these are no longer duplicated.
+
+
 .. c:function:: void Py_IncRef(PyObject *o)
 
    Increment the reference count for object *o*. A function version of :c:func:`Py_XINCREF`.
@@ -139,3 +144,40 @@ objects.
 
    Decrement the reference count for object *o*. A function version of :c:func:`Py_XDECREF`.
    It can be used for runtime dynamic embedding of Python.
+
+
+.. c:macro:: Py_SETREF(dst, src)
+
+   Macro safely decrementing the `dst` reference count and setting `dst` to
+   `src`.
+
+   As in case of :c:func:`Py_CLEAR`, "the obvious" code can be deadly::
+
+       Py_DECREF(dst);
+       dst = src;
+
+   The safe way is::
+
+        Py_SETREF(dst, src);
+
+   That arranges to set `dst` to `src` _before_ decrementing reference count of
+   *dst* old value, so that any code triggered as a side-effect of `dst`
+   getting torn down no longer believes `dst` points to a valid object.
+
+   .. versionadded:: 3.6
+
+   .. versionchanged:: 3.12
+      The macro arguments are now only evaluated once. If an argument has side
+      effects, these are no longer duplicated.
+
+
+.. c:macro:: Py_XSETREF(dst, src)
+
+   Variant of :c:macro:`Py_SETREF` macro that uses :c:func:`Py_XDECREF` instead
+   of :c:func:`Py_DECREF`.
+
+   .. versionadded:: 3.6
+
+   .. versionchanged:: 3.12
+      The macro arguments are now only evaluated once. If an argument has side
+      effects, these are no longer duplicated.

Doc/faq/programming.rst

@@ -1279,13 +1279,25 @@ Or, you can use an extension that provides a matrix datatype; `NumPy
 <https://numpy.org/>`_ is the best known.
 
 
-How do I apply a method to a sequence of objects?
--------------------------------------------------
+How do I apply a method or function to a sequence of objects?
+-------------------------------------------------------------
 
-Use a list comprehension::
+To call a method or function and accumulate the return values is a list,
+a :term:`list comprehension` is an elegant solution::
 
    result = [obj.method() for obj in mylist]
 
+   result = [function(obj) for obj in mylist]
+
+To just run the method or function without saving the return values,
+a plain :keyword:`for` loop will suffice::
+
+   for obj in mylist:
+       obj.method()
+
+   for obj in mylist:
+       function(obj)
+
 .. _faq-augmented-assignment-tuple-error:
 
 Why does a_tuple[i] += ['item'] raise an exception when the addition works?

Doc/howto/enum.rst

@@ -173,6 +173,7 @@ yourself some work and use :func:`auto()` for the values::
     ...     FRIDAY = auto()
     ...     SATURDAY = auto()
     ...     SUNDAY = auto()
+    ...     WEEKEND = SATURDAY | SUNDAY
 
 
 .. _enum-advanced-tutorial:
@@ -305,6 +306,10 @@ Iterating over the members of an enum does not provide the aliases::
 
     >>> list(Shape)
     [<Shape.SQUARE: 2>, <Shape.DIAMOND: 1>, <Shape.CIRCLE: 3>]
+    >>> list(Weekday)
+    [<Weekday.MONDAY: 1>, <Weekday.TUESDAY: 2>, <Weekday.WEDNESDAY: 4>, <Weekday.THURSDAY: 8>, <Weekday.FRIDAY: 16>, <Weekday.SATURDAY: 32>, <Weekday.SUNDAY: 64>]
+
+Note that the aliases ``Shape.ALIAS_FOR_SQUARE`` and ``Weekday.WEEKEND`` aren't shown.
 
 The special attribute ``__members__`` is a read-only ordered mapping of names
 to members.  It includes all names defined in the enumeration, including the
@@ -324,6 +329,11 @@ the enumeration members.  For example, finding all the aliases::
     >>> [name for name, member in Shape.__members__.items() if member.name != name]
     ['ALIAS_FOR_SQUARE']
 
+.. note::
+
+   Aliases for flags include values with multiple flags set, such as ``3``,
+   and no flags set, i.e. ``0``.
+
 
 Comparisons
 -----------
@@ -751,7 +761,7 @@ flags being set, the boolean evaluation is :data:`False`::
     False
 
 Individual flags should have values that are powers of two (1, 2, 4, 8, ...),
-while combinations of flags won't::
+while combinations of flags will not::
 
     >>> class Color(Flag):
     ...     RED = auto()
@@ -1096,8 +1106,8 @@ example of when ``KEEP`` is needed).
 
 .. _enum-class-differences:
 
-How are Enums different?
-------------------------
+How are Enums and Flags different?
+----------------------------------
 
 Enums have a custom metaclass that affects many aspects of both derived :class:`Enum`
 classes and their instances (members).
@@ -1114,6 +1124,13 @@ responsible for ensuring that various other methods on the final :class:`Enum`
 class are correct (such as :meth:`__new__`, :meth:`__getnewargs__`,
 :meth:`__str__` and :meth:`__repr__`).
 
+Flag Classes
+^^^^^^^^^^^^
+
+Flags have an expanded view of aliasing: to be canonical, the value of a flag
+needs to be a power-of-two value, and not a duplicate name.  So, in addition to the
+:class:`Enum` definition of alias, a flag with no value (a.k.a. ``0``) or with more than one
+power-of-two value (e.g. ``3``) is considered an alias.
 
 Enum Members (aka instances)
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -1123,9 +1140,35 @@ The most interesting thing about enum members is that they are singletons.
 and then puts a custom :meth:`__new__` in place to ensure that no new ones are
 ever instantiated by returning only the existing member instances.
 
+Flag Members
+^^^^^^^^^^^^
+
+Flag members can be iterated over just like the :class:`Flag` class, and only the
+canonical members will be returned.  For example::
+
+    >>> list(Color)
+    [<Color.RED: 1>, <Color.GREEN: 2>, <Color.BLUE: 4>]
+
+(Note that ``BLACK``, ``PURPLE``, and ``WHITE`` do not show up.)
+
+Inverting a flag member returns the corresponding positive value,
+rather than a negative value --- for example::
+
+    >>> ~Color.RED
+    <Color.GREEN|BLUE: 6>
+
+Flag members have a length corresponding to the number of power-of-two values
+they contain.  For example::
+
+    >>> len(Color.PURPLE)
+    2
+
 
 .. _enum-cookbook:
 
+Enum Cookbook
+-------------
+
 
 While :class:`Enum`, :class:`IntEnum`, :class:`StrEnum`, :class:`Flag`, and
 :class:`IntFlag` are expected to cover the majority of use-cases, they cannot
@@ -1299,7 +1342,7 @@ enumerations)::
 DuplicateFreeEnum
 ^^^^^^^^^^^^^^^^^
 
-Raises an error if a duplicate member name is found instead of creating an
+Raises an error if a duplicate member value is found instead of creating an
 alias::
 
     >>> class DuplicateFreeEnum(Enum):

Doc/includes/custom2.c

@@ -51,14 +51,12 @@ Custom_init(CustomObject *self, PyObject *args, PyObject *kwds)
 
     if (first) {
         tmp = self->first;
-        Py_INCREF(first);
-        self->first = first;
+        self->first = Py_NewRef(first);
         Py_XDECREF(tmp);
     }
     if (last) {
         tmp = self->last;
-        Py_INCREF(last);
-        self->last = last;
+        self->last = Py_NewRef(last);
         Py_XDECREF(tmp);
     }
     return 0;
@@ -127,9 +125,7 @@ PyInit_custom2(void)
     if (m == NULL)
         return NULL;
 
-    Py_INCREF(&CustomType);
-    if (PyModule_AddObject(m, "Custom", (PyObject *) &CustomType) < 0) {
-        Py_DECREF(&CustomType);
+    if (PyModule_AddObjectRef(m, "Custom", (PyObject *) &CustomType) < 0) {
         Py_DECREF(m);
         return NULL;
     }

Doc/includes/custom3.c

@@ -51,14 +51,12 @@ Custom_init(CustomObject *self, PyObject *args, PyObject *kwds)
 
     if (first) {
         tmp = self->first;
-        Py_INCREF(first);
-        self->first = first;
+        self->first = Py_NewRef(first);
         Py_DECREF(tmp);
     }
     if (last) {
         tmp = self->last;
-        Py_INCREF(last);
-        self->last = last;
+        self->last = Py_NewRef(last);
         Py_DECREF(tmp);
     }
     return 0;
@@ -73,8 +71,7 @@ static PyMemberDef Custom_members[] = {
 static PyObject *
 Custom_getfirst(CustomObject *self, void *closure)
 {
-    Py_INCREF(self->first);
-    return self->first;
+    return Py_NewRef(self->first);
 }
 
 static int
@@ -91,17 +88,15 @@ Custom_setfirst(CustomObject *self, PyObject *value, void *closure)
         return -1;
     }
     tmp = self->first;
-    Py_INCREF(value);
-    self->first = value;
+    self->first = Py_NewRef(value);
     Py_DECREF(tmp);
     return 0;
 }
 
 static PyObject *
 Custom_getlast(CustomObject *self, void *closure)
 {
-    Py_INCREF(self->last);
-    return self->last;
+    return Py_NewRef(self->last);
 }
 
 static int
@@ -118,8 +113,7 @@ Custom_setlast(CustomObject *self, PyObject *value, void *closure)
         return -1;
     }
     tmp = self->last;
-    Py_INCREF(value);
-    self->last = value;
+    self->last = Py_NewRef(value);
     Py_DECREF(tmp);
     return 0;
 }
@@ -178,9 +172,7 @@ PyInit_custom3(void)
     if (m == NULL)
         return NULL;
 
-    Py_INCREF(&CustomType);
-    if (PyModule_AddObject(m, "Custom", (PyObject *) &CustomType) < 0) {
-        Py_DECREF(&CustomType);
+    if (PyModule_AddObjectRef(m, "Custom", (PyObject *) &CustomType) < 0) {
         Py_DECREF(m);
         return NULL;
     }