Merge branch 'main' into special_for_iter2

Author: sweeneyde

Doc/c-api/frame.rst

@@ -27,8 +27,6 @@ See also :ref:`Reflection <reflection>`.
    Return a :term:`strong reference`, or ``NULL`` if *frame* has no outer
    frame.
 
-   *frame* must not be ``NULL``.
-
    .. versionadded:: 3.9
 
 
@@ -38,8 +36,6 @@ See also :ref:`Reflection <reflection>`.
 
    Return a :term:`strong reference`. The result cannot be ``NULL``.
 
-   *frame* must not be ``NULL``.
-
    .. versionadded:: 3.11
 
 
@@ -49,7 +45,7 @@ See also :ref:`Reflection <reflection>`.
 
    Return a :term:`strong reference`.
 
-   *frame* must not be ``NULL``. The result (frame code) cannot be ``NULL``.
+   The result (frame code) cannot be ``NULL``.
 
    .. versionadded:: 3.9
 
@@ -62,8 +58,6 @@ See also :ref:`Reflection <reflection>`.
 
    Return a :term:`strong reference`, or ``NULL``.
 
-   *frame* must not be ``NULL``.
-
    .. versionadded:: 3.11
 
 
@@ -73,19 +67,15 @@ See also :ref:`Reflection <reflection>`.
 
    Return a :term:`strong reference`. The result cannot be ``NULL``.
 
-   *frame* must not be ``NULL``.
-
    .. versionadded:: 3.11
 
 
 .. c:function:: int PyFrame_GetLasti(PyFrameObject *frame)
 
-   Get the *frame*'s ``f_lasti`` attribute (:class:`dict`).
+   Get the *frame*'s ``f_lasti`` attribute.
 
    Returns -1 if ``frame.f_lasti`` is ``None``.
 
-   *frame* must not be ``NULL``.
-
    .. versionadded:: 3.11
 
 
@@ -95,13 +85,9 @@ See also :ref:`Reflection <reflection>`.
 
    Return a :term:`strong reference`.
 
-   *frame* must not be ``NULL``.
-
    .. versionadded:: 3.11
 
 
 .. c:function:: int PyFrame_GetLineNumber(PyFrameObject *frame)
 
    Return the line number that *frame* is currently executing.
-
-   *frame* must not be ``NULL``.

Doc/library/argparse.rst

@@ -26,6 +26,75 @@ module also automatically generates help and usage messages and issues errors
 when users give the program invalid arguments.
 
 
+Summary
+-------
+
+Core Functionality
+^^^^^^^^^^^^^^^^^^
+
+The :mod:`argparse` module's support for command-line interfaces is built
+from the following:
+
+The :class:`argparse.ArgumentParser` creates a new :class:`ArgumentParser`
+object. Commonly used arguments include prog_, description_, and
+formatter_class_. For example, the user can create an instance of
+:class:`ArgumentParser` through the following::
+
+   >>> parser = argparse.ArgumentParser(prog='PROG', description='DESC',
+   ...                                  formatter_class=argparse.RawDescriptionHelpFormatter)
+
+The :func:`ArgumentParser.add_argument` is a function that is used
+to define how a single command-line argument should be parsed. Commonly used
+arguments include `name or flags`_, action_, default_, type_, required_,
+and help_. An example of the function :func:`ArgumentParser.add_argument`
+is as follows::
+
+   >>> parser.add_argument('-v', '--verbose', action='store_true',
+   ...                     help='Show various debugging information')
+
+
+Basic Usage of :func:`add_argument`
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+
+**Name or Flags Type**
+
+====================== ===========================
+Type                   Example
+====================== ===========================
+Positional             ``'foo'``
+Optional               ``'-v'``, ``'--verbose'``
+====================== ===========================
+
+
+**Basic Arguments:**
+
+====================== =========================================================== =========================================================================================================================
+Name                   Description                                                 Keywords
+====================== =========================================================== =========================================================================================================================
+action_                Specifies how an argument should be handled                 ``'store'``, ``'store_const'``, ``'store_true'``, ``'append'``, ``'append_const'``, ``'count'``, ``'help'``, ``'version'``
+default_               Default value used when an argument is not provided
+type_                  Automatically converts an argument to the given type        :class:`int`, :class:`float`, :class:`bool`, ``argparse.FileType('w')``, ``callable function``
+help_                  Help message of an argument
+====================== =========================================================== =========================================================================================================================
+
+
+
+**Advanced Arguments:**
+
+====================== =========================================================== =======================================================================================================================
+Name                   Description                                                 Keywords
+====================== =========================================================== =======================================================================================================================
+nargs_                 Associates a single action with the number of arguments     ``N`` (:class:`int`), ``'?'``, ``'*'``, ``'+'``, ``argparse.REMAINDER``
+const_                 Stores constant values of names or flags
+choices_               A container that lists the possible values                  ``['foo', 'bar']``, ``range(1, 10)``, Any object that supports ``in`` operator
+required_              Indicates if an optional argument is required or not        ``True``, ``False``
+metavar_               An alternative display name for the argument
+dest_                  Specifies name of attribute to be used in ``parse_args()``
+====================== =========================================================== =======================================================================================================================
+
+
+
 Example
 -------
 
@@ -196,6 +265,8 @@ ArgumentParser objects
 The following sections describe how each of these are used.
 
 
+.. _prog:
+
 prog
 ^^^^
 
@@ -293,6 +364,8 @@ The ``%(prog)s`` format specifier is available to fill in the program name in
 your usage messages.
 
 
+.. _description:
+
 description
 ^^^^^^^^^^^
 
@@ -373,6 +446,8 @@ and one in the child) and raise an error.
    not be reflected in the child.
 
 
+.. _formatter_class:
+
 formatter_class
 ^^^^^^^^^^^^^^^
 
@@ -716,6 +791,8 @@ The add_argument() method
 The following sections describe how each of these are used.
 
 
+.. _name_or_flags:
+
 name or flags
 ^^^^^^^^^^^^^
 
@@ -749,6 +826,8 @@ be positional::
    PROG: error: the following arguments are required: bar
 
 
+.. _action:
+
 action
 ^^^^^^
 
@@ -884,6 +963,9 @@ An example of a custom action::
 
 For more details, see :class:`Action`.
 
+
+.. _nargs:
+
 nargs
 ^^^^^
 
@@ -971,6 +1053,8 @@ is determined by the action_.  Generally this means a single command-line argume
 will be consumed and a single item (not a list) will be produced.
 
 
+.. _const:
+
 const
 ^^^^^
 
@@ -997,6 +1081,8 @@ the various :class:`ArgumentParser` actions.  The two most common uses of it are
    ``const=None`` by default, including when ``action='append_const'`` or
    ``action='store_const'``.
 
+.. _default:
+
 default
 ^^^^^^^
 
@@ -1055,6 +1141,8 @@ command-line argument was not present::
    Namespace(foo='1')
 
 
+.. _type:
+
 type
 ^^^^
 
@@ -1124,6 +1212,8 @@ For type checkers that simply check against a fixed set of values, consider
 using the choices_ keyword instead.
 
 
+.. _choices:
+
 choices
 ^^^^^^^
 
@@ -1166,6 +1256,8 @@ from *dest*.  This is usually what you want because the user never sees the
 many choices), just specify an explicit metavar_.
 
 
+.. _required:
+
 required
 ^^^^^^^^
 
@@ -1192,6 +1284,8 @@ present at the command line.
     *options* to be *optional*, and thus they should be avoided when possible.
 
 
+.. _help:
+
 help
 ^^^^
 
@@ -1247,6 +1341,8 @@ setting the ``help`` value to ``argparse.SUPPRESS``::
      -h, --help  show this help message and exit
 
 
+.. _metavar:
+
 metavar
 ^^^^^^^
 
@@ -1311,6 +1407,8 @@ arguments::
     --foo bar baz
 
 
+.. _dest:
+
 dest
 ^^^^
 

Doc/library/codecs.rst

@@ -1426,7 +1426,7 @@ Internationalized Domain Names (IDN)). It builds upon the ``punycode`` encoding
 and :mod:`stringprep`.
 
 If you need the IDNA 2008 standard from :rfc:`5891` and :rfc:`5895`, use the
-third-party `idna module <https://pypi.org/project/idna/>_`.
+third-party `idna module <https://pypi.org/project/idna/>`_.
 
 These RFCs together define a protocol to support non-ASCII characters in domain
 names. A domain name containing non-ASCII characters (such as

Doc/library/functools.rst

@@ -436,6 +436,23 @@ The :mod:`functools` module defines the following functions:
      ...     for i, elem in enumerate(arg):
      ...         print(i, elem)
 
+   :data:`types.UnionType` and :data:`typing.Union` can also be used::
+
+    >>> @fun.register
+    ... def _(arg: int | float, verbose=False):
+    ...     if verbose:
+    ...         print("Strength in numbers, eh?", end=" ")
+    ...     print(arg)
+    ...
+    >>> from typing import Union
+    >>> @fun.register
+    ... def _(arg: Union[list, set], verbose=False):
+    ...     if verbose:
+    ...         print("Enumerate this:")
+    ...     for i, elem in enumerate(arg):
+    ...         print(i, elem)
+    ...
+
    For code which doesn't use type annotations, the appropriate type
    argument can be passed explicitly to the decorator itself::
 
@@ -535,6 +552,10 @@ The :mod:`functools` module defines the following functions:
    .. versionchanged:: 3.7
       The :func:`register` attribute now supports using type annotations.
 
+   .. versionchanged:: 3.11
+      The :func:`register` attribute now supports :data:`types.UnionType`
+      and :data:`typing.Union` as type annotations.
+
 
 .. class:: singledispatchmethod(func)
 

Doc/library/multiprocessing.rst

@@ -1676,7 +1676,7 @@ Manager processes will be shutdown as soon as they are garbage collected or
 their parent process exits.  The manager classes are defined in the
 :mod:`multiprocessing.managers` module:
 
-.. class:: BaseManager([address[, authkey]])
+.. class:: BaseManager(address=None, authkey=None, serializer='pickle', ctx=None, *, shutdown_timeout=1.0)
 
    Create a BaseManager object.
 
@@ -1691,6 +1691,20 @@ their parent process exits.  The manager classes are defined in the
    *authkey* is ``None`` then ``current_process().authkey`` is used.
    Otherwise *authkey* is used and it must be a byte string.
 
+   *serializer* must be ``'pickle'`` (use :mod:`pickle` serialization) or
+   ``'xmlrpclib'`` (use :mod:`xmlrpc.client` serialization).
+
+   *ctx* is a context object, or ``None`` (use the current context). See the
+   :func:`get_context` function.
+
+   *shutdown_timeout* is a timeout in seconds used to wait until the process
+   used by the manager completes in the :meth:`shutdown` method. If the
+   shutdown times out, the process is terminated. If terminating the process
+   also times out, the process is killed.
+
+   .. versionchanged: 3.11
+      Added the *shutdown_timeout* parameter.
+
    .. method:: start([initializer[, initargs]])
 
       Start a subprocess to start the manager.  If *initializer* is not ``None``

Doc/library/socket.rst

@@ -660,7 +660,7 @@ The following functions all create :ref:`socket objects <socket-objects>`.
       Windows support added.
 
 
-.. function:: create_connection(address[, timeout[, source_address]])
+.. function:: create_connection(address[, timeout[, source_address[, all_errors]]])
 
    Connect to a TCP service listening on the internet *address* (a 2-tuple
    ``(host, port)``), and return the socket object.  This is a higher-level
@@ -679,9 +679,18 @@ The following functions all create :ref:`socket objects <socket-objects>`.
    socket to bind to as its source address before connecting.  If host or port
    are '' or 0 respectively the OS default behavior will be used.
 
+   When a connection cannot be created, an exception is raised. By default,
+   it is the exception from the last address in the list. If *all_errors*
+   is ``True``, it is an :exc:`ExceptionGroup` containing the errors of all
+   attempts.
+
    .. versionchanged:: 3.2
       *source_address* was added.
 
+   .. versionchanged:: 3.11
+      *all_errors* was added.
+
+
 .. function:: create_server(address, *, family=AF_INET, backlog=None, reuse_port=False, dualstack_ipv6=False)
 
    Convenience function which creates a TCP socket bound to *address* (a 2-tuple