Merge branch 'main' into compare_op

Author: Yhg1s

.github/workflows/reusable-macos.yml

@@ -45,6 +45,7 @@ jobs:
         brew link --overwrite tcl-tk@8
     - name: Configure CPython
       run: |
+        MACOSX_DEPLOYMENT_TARGET=10.15 \
         GDBM_CFLAGS="-I$(brew --prefix gdbm)/include" \
         GDBM_LIBS="-L$(brew --prefix gdbm)/lib -lgdbm" \
         ./configure \

Doc/c-api/monitoring.rst

@@ -75,9 +75,14 @@ See :mod:`sys.monitoring` for descriptions of the events.
    Fire a ``JUMP`` event.
 
 
-.. c:function:: int PyMonitoring_FireBranchEvent(PyMonitoringState *state, PyObject *codelike, int32_t offset, PyObject *target_offset)
+.. c:function:: int PyMonitoring_FireBranchLeftEvent(PyMonitoringState *state, PyObject *codelike, int32_t offset, PyObject *target_offset)
 
-   Fire a ``BRANCH`` event.
+   Fire a ``BRANCH_LEFT`` event.
+
+
+.. c:function:: int PyMonitoring_FireBranchRightEvent(PyMonitoringState *state, PyObject *codelike, int32_t offset, PyObject *target_offset)
+
+   Fire a ``BRANCH_RIGHT`` event.
 
 
 .. c:function:: int PyMonitoring_FireCReturnEvent(PyMonitoringState *state, PyObject *codelike, int32_t offset, PyObject *retval)
@@ -168,7 +173,8 @@ would typically correspond to a python function.
    ================================================== =====================================
    Macro                                              Event
    ================================================== =====================================
-   .. c:macro:: PY_MONITORING_EVENT_BRANCH            :monitoring-event:`BRANCH`
+   .. c:macro:: PY_MONITORING_EVENT_BRANCH_LEFT       :monitoring-event:`BRANCH_LEFT`
+   .. c:macro:: PY_MONITORING_EVENT_BRANCH_RIGHT      :monitoring-event:`BRANCH_RIGHT`
    .. c:macro:: PY_MONITORING_EVENT_CALL              :monitoring-event:`CALL`
    .. c:macro:: PY_MONITORING_EVENT_C_RAISE           :monitoring-event:`C_RAISE`
    .. c:macro:: PY_MONITORING_EVENT_C_RETURN          :monitoring-event:`C_RETURN`

Doc/c-api/weakref.rst

@@ -88,6 +88,15 @@ as much as it can.
       Use :c:func:`PyWeakref_GetRef` instead.
 
 
+.. c:function:: int PyWeakref_IsDead(PyObject *ref)
+
+   Test if the weak reference *ref* is dead. Returns 1 if the reference is
+   dead, 0 if it is alive, and -1 with an error set if *ref* is not a weak
+   reference object.
+
+   .. versionadded:: 3.14
+
+
 .. c:function:: void PyObject_ClearWeakRefs(PyObject *object)
 
    This function is called by the :c:member:`~PyTypeObject.tp_dealloc` handler

Doc/howto/argparse-optparse.rst

@@ -1,20 +1,14 @@
 .. currentmodule:: argparse
 
 .. _upgrading-optparse-code:
+.. _migrating-optparse-code:
 
-==========================
-Upgrading optparse code
-==========================
+============================================
+Migrating ``optparse`` code to ``argparse``
+============================================
 
-Originally, the :mod:`argparse` module had attempted to maintain compatibility
-with :mod:`optparse`.  However, :mod:`optparse` was difficult to extend
-transparently, particularly with the changes required to support
-``nargs=`` specifiers and better usage messages.  When most everything in
-:mod:`optparse` had either been copy-pasted over or monkey-patched, it no
-longer seemed practical to try to maintain the backwards compatibility.
-
-The :mod:`argparse` module improves on the :mod:`optparse`
-module in a number of ways including:
+The :mod:`argparse` module offers several higher level features not natively
+provided by the :mod:`optparse` module, including:
 
 * Handling positional arguments.
 * Supporting subcommands.
@@ -23,7 +17,23 @@ module in a number of ways including:
 * Producing more informative usage messages.
 * Providing a much simpler interface for custom ``type`` and ``action``.
 
-A partial upgrade path from :mod:`optparse` to :mod:`argparse`:
+Originally, the :mod:`argparse` module attempted to maintain compatibility
+with :mod:`optparse`.  However, the fundamental design differences between
+supporting declarative command line option processing (while leaving positional
+argument processing to application code), and supporting both named options
+and positional arguments in the declarative interface mean that the
+API has diverged from that of ``optparse`` over time.
+
+As described in :ref:`choosing-an-argument-parser`, applications that are
+currently using :mod:`optparse` and are happy with the way it works can
+just continue to use ``optparse``.
+
+Application developers that are considering migrating should also review
+the list of intrinsic behavioural differences described in that section
+before deciding whether or not migration is desirable.
+
+For applications that do choose to migrate from :mod:`optparse` to :mod:`argparse`,
+the following suggestions should be helpful:
 
 * Replace all :meth:`optparse.OptionParser.add_option` calls with
   :meth:`ArgumentParser.add_argument` calls.

Doc/howto/argparse.rst

@@ -13,11 +13,16 @@ recommended command-line parsing module in the Python standard library.
 
 .. note::
 
-   There are two other modules that fulfill the same task, namely
-   :mod:`getopt` (an equivalent for ``getopt()`` from the C
-   language) and the deprecated :mod:`optparse`.
-   Note also that :mod:`argparse` is based on :mod:`optparse`,
-   and therefore very similar in terms of usage.
+   The standard library includes two other libraries directly related
+   to command-line parameter processing: the lower level :mod:`optparse`
+   module (which may require more code to configure for a given application,
+   but also allows an application to request behaviors that ``argparse``
+   doesn't support), and the very low level :mod:`getopt` (which specifically
+   serves as an equivalent to the :c:func:`!getopt` family of functions
+   available to C programmers).
+   While neither of those modules is covered directly in this guide, many of
+   the core concepts in ``argparse`` first originated in ``optparse``, so
+   some aspects of this tutorial will also be relevant to ``optparse`` users.
 
 
 Concepts

Doc/library/allos.rst

@@ -15,14 +15,9 @@ but they are available on most other systems as well.  Here's an overview:
    os.rst
    io.rst
    time.rst
-   argparse.rst
    logging.rst
    logging.config.rst
    logging.handlers.rst
-   getpass.rst
-   curses.rst
-   curses.ascii.rst
-   curses.panel.rst
    platform.rst
    errno.rst
    ctypes.rst

Doc/library/argparse.rst

@@ -11,6 +11,18 @@
 
 **Source code:** :source:`Lib/argparse.py`
 
+.. note::
+
+   While :mod:`argparse` is the default recommended standard library module
+   for implementing basic command line applications, authors with more
+   exacting requirements for exactly how their command line applications
+   behave may find it doesn't provide the necessary level of control.
+   Refer to :ref:`choosing-an-argument-parser` for alternatives to
+   consider when ``argparse`` doesn't support behaviors that the application
+   requires (such as entirely disabling support for interspersed options and
+   positional arguments, or accepting option parameter values that start
+   with ``-`` even when they correspond to another defined option).
+
 --------------
 
 .. sidebar:: Tutorial

Doc/library/cmdlinelibs.rst

@@ -0,0 +1,21 @@
+.. _cmdlinelibs:
+
+********************************
+Command Line Interface Libraries
+********************************
+
+The modules described in this chapter assist with implementing
+command line and terminal interfaces for applications.
+
+Here's an overview:
+
+.. toctree::
+   :maxdepth: 1
+
+   argparse.rst
+   optparse.rst
+   getpass.rst
+   fileinput.rst
+   curses.rst
+   curses.ascii.rst
+   curses.panel.rst

Doc/library/enum.rst

@@ -110,6 +110,10 @@ Module Contents
       ``KEEP`` which allows for more fine-grained control over how invalid values
       are dealt with in an enumeration.
 
+   :class:`EnumDict`
+
+      A subclass of :class:`dict` for use when subclassing :class:`EnumType`.
+
    :class:`auto`
 
       Instances are replaced with an appropriate value for Enum members.
@@ -152,6 +156,7 @@ Module Contents
 
 .. versionadded:: 3.6  ``Flag``, ``IntFlag``, ``auto``
 .. versionadded:: 3.11  ``StrEnum``, ``EnumCheck``, ``ReprEnum``, ``FlagBoundary``, ``property``, ``member``, ``nonmember``, ``global_enum``, ``show_flag_values``
+.. versionadded:: 3.13  ``EnumDict``
 
 ---------------
 
@@ -821,7 +826,27 @@ Data Types
          >>> KeepFlag(2**2 + 2**4)
          <KeepFlag.BLUE|16: 20>
 
-.. versionadded:: 3.11
+   .. versionadded:: 3.11
+
+.. class:: EnumDict
+
+   *EnumDict* is a subclass of :class:`dict` that is used as the namespace
+   for defining enum classes (see :ref:`prepare`).
+   It is exposed to allow subclasses of :class:`EnumType` with advanced
+   behavior like having multiple values per member.
+   It should be called with the name of the enum class being created, otherwise
+   private names and internal classes will not be handled correctly.
+
+   Note that only the :class:`~collections.abc.MutableMapping` interface
+   (:meth:`~object.__setitem__` and :meth:`~dict.update`) is overridden.
+   It may be possible to bypass the checks using other :class:`!dict`
+   operations like :meth:`|= <object.__ior__>`.
+
+   .. attribute:: EnumDict.member_names
+
+      A list of member names.
+
+   .. versionadded:: 3.13
 
 ---------------
 

Doc/library/filesys.rst

@@ -14,7 +14,6 @@ in this chapter is:
 
    pathlib.rst
    os.path.rst
-   fileinput.rst
    stat.rst
    filecmp.rst
    tempfile.rst