Merge branch 'main' into func-watchers

Author: mpage

.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

@@ -87,6 +87,8 @@ See also :ref:`Reflection <reflection>`.
    * 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
 
 

Doc/c-api/init_config.rst

@@ -254,7 +254,7 @@ PyPreConfig
 
    .. c:member:: int configure_locale
 
-      Set the LC_CTYPE locale to the user preferred locale?
+      Set the LC_CTYPE locale to the user preferred locale.
 
       If equals to ``0``, set :c:member:`~PyPreConfig.coerce_c_locale` and
       :c:member:`~PyPreConfig.coerce_c_locale_warn` members to ``0``.

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

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;
     }

Doc/includes/custom4.c

@@ -67,14 +67,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;
@@ -89,8 +87,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
@@ -114,8 +111,7 @@ Custom_setfirst(CustomObject *self, PyObject *value, void *closure)
 static PyObject *
 Custom_getlast(CustomObject *self, void *closure)
 {
-    Py_INCREF(self->last);
-    return self->last;
+    return Py_NewRef(self->last);
 }
 
 static int
@@ -192,9 +188,7 @@ PyInit_custom4(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/library/_thread.rst

@@ -57,6 +57,8 @@ This module defines the following constants and functions:
    When the function raises a :exc:`SystemExit` exception, it is silently
    ignored.
 
+   .. audit-event:: _thread.start_new_thread function,args,kwargs start_new_thread
+
    .. versionchanged:: 3.8
       :func:`sys.unraisablehook` is now used to handle unhandled exceptions.
 

Doc/library/asyncio-policy.rst

@@ -222,6 +222,9 @@ implementation used by the asyncio event loop:
       This method has to be called to ensure that underlying
       resources are cleaned-up.
 
+   .. deprecated:: 3.12
+
+
 .. class:: ThreadedChildWatcher
 
    This implementation starts a new waiting thread for every subprocess spawn.

Doc/library/asyncio-runner.rst

@@ -22,7 +22,7 @@ to simplify async code usage for common wide-spread scenarios.
 Running an asyncio Program
 ==========================
 
-.. function:: run(coro, *, debug=None)
+.. function:: run(coro, *, debug=None, loop_factory=None)
 
    Execute the :term:`coroutine` *coro* and return the result.
 
@@ -37,9 +37,11 @@ Running an asyncio Program
    debug mode explicitly. ``None`` is used to respect the global
    :ref:`asyncio-debug-mode` settings.
 
-   This function always creates a new event loop and closes it at
-   the end.  It should be used as a main entry point for asyncio
-   programs, and should ideally only be called once.
+   If *loop_factory* is not ``None``, it is used to create a new event loop;
+   otherwise :func:`asyncio.new_event_loop` is used. The loop is closed at the end.
+   This function should be used as a main entry point for asyncio programs,
+   and should ideally only be called once. It is recommended to use
+   *loop_factory* to configure the event loop instead of policies.
 
    The executor is given a timeout duration of 5 minutes to shutdown.
    If the executor hasn't finished within that duration, a warning is
@@ -62,6 +64,10 @@ Running an asyncio Program
 
       *debug* is ``None`` by default to respect the global debug mode settings.
 
+   .. versionchanged:: 3.12
+
+      Added *loop_factory* parameter.
+
 
 Runner context manager
 ======================

Doc/library/asyncio-task.rst

@@ -18,6 +18,10 @@ and Tasks.
 Coroutines
 ==========
 
+**Source code:** :source:`Lib/asyncio/coroutines.py`
+
+----------------------------------------------------
+
 :term:`Coroutines <coroutine>` declared with the async/await syntax is the
 preferred way of writing asyncio applications.  For example, the following
 snippet of code prints "hello", waits 1 second,
@@ -230,6 +234,10 @@ is :meth:`loop.run_in_executor`.
 Creating Tasks
 ==============
 
+**Source code:** :source:`Lib/asyncio/tasks.py`
+
+-----------------------------------------------
+
 .. function:: create_task(coro, *, name=None, context=None)
 
    Wrap the *coro* :ref:`coroutine <coroutine>` into a :class:`Task`