Merge branch 'main' into pythongh-103492

.gitattributes

@@ -32,6 +32,9 @@ Lib/test/test_importlib/resources/data01/*           noeol
 Lib/test/test_importlib/resources/namespacedata01/*  noeol
 Lib/test/xmltestdata/*                     noeol
 
+# Shell scripts should have LF even on Windows because of Cygwin
+Lib/venv/scripts/common/activate text eol=lf
+
 # CRLF files
 [attr]dos text eol=crlf
 

.github/CODEOWNERS

@@ -61,11 +61,7 @@ Python/traceback.c            @iritkatriel
 /Tools/build/parse_html5_entities.py   @ezio-melotti
 
 # Import (including importlib).
-# Ignoring importlib.h so as to not get flagged on
-# all pull requests that change the emitted
-# bytecode.
-**/*import*.c                 @brettcannon @encukou @ericsnowcurrently @ncoghlan @warsaw
-**/*import*.py                @brettcannon @encukou @ericsnowcurrently @ncoghlan @warsaw
+**/*import*                   @brettcannon @encukou @ericsnowcurrently @ncoghlan @warsaw
 **/*importlib/resources/*      @jaraco @warsaw @FFY00
 **/importlib/metadata/*       @jaraco @warsaw
 

Doc/conf.py

@@ -68,8 +68,10 @@
 # Minimum version of sphinx required
 needs_sphinx = '3.2'
 
+# Ignore any .rst files in the includes/ directory;
+# they're embedded in pages but not rendered individually.
 # Ignore any .rst files in the venv/ directory.
-exclude_patterns = ['venv/*', 'README.rst']
+exclude_patterns = ['includes/*.rst', 'venv/*', 'README.rst']
 venvdir = os.getenv('VENVDIR')
 if venvdir is not None:
     exclude_patterns.append(venvdir + '/*')

Doc/glossary.rst

@@ -214,7 +214,7 @@ Glossary
       A callable is an object that can be called, possibly with a set
       of arguments (see :term:`argument`), with the following syntax::
 
-         callable(argument1, argument2, ...)
+         callable(argument1, argument2, argumentN)
 
       A :term:`function`, and by extension a :term:`method`, is a callable.
       An instance of a class that implements the :meth:`~object.__call__`

Doc/library/csv.rst

@@ -327,7 +327,7 @@ The :mod:`csv` module defines the following constants:
 
    Instructs :class:`writer` objects to quote all non-numeric fields.
 
-   Instructs the reader to convert all non-quoted fields to type *float*.
+   Instructs :class:`reader` objects to convert all non-quoted fields to type *float*.
 
 
 .. data:: QUOTE_NONE
@@ -337,7 +337,25 @@ The :mod:`csv` module defines the following constants:
    character.  If *escapechar* is not set, the writer will raise :exc:`Error` if
    any characters that require escaping are encountered.
 
-   Instructs :class:`reader` to perform no special processing of quote characters.
+   Instructs :class:`reader` objects to perform no special processing of quote characters.
+
+.. data:: QUOTE_NOTNULL
+
+   Instructs :class:`writer` objects to quote all fields which are not
+   ``None``.  This is similar to :data:`QUOTE_ALL`, except that if a
+   field value is ``None`` an empty (unquoted) string is written.
+
+   Instructs :class:`reader` objects to interpret an empty (unquoted) field as None and
+   to otherwise behave as :data:`QUOTE_ALL`.
+
+.. data:: QUOTE_STRINGS
+
+   Instructs :class:`writer` objects to always place quotes around fields
+   which are strings.  This is similar to :data:`QUOTE_NONNUMERIC`, except that if a
+   field value is ``None`` an empty (unquoted) string is written.
+
+   Instructs :class:`reader` objects to interpret an empty (unquoted) string as ``None`` and
+   to otherwise behave as :data:`QUOTE_NONNUMERIC`.
 
 The :mod:`csv` module defines the following exception:
 

Doc/library/functions.rst

@@ -1681,7 +1681,7 @@ are always available.  They are listed here in alphabetical order.
 
       class C:
           @staticmethod
-          def f(arg1, arg2, ...): ...
+          def f(arg1, arg2, argN): ...
 
    The ``@staticmethod`` form is a function :term:`decorator` -- see
    :ref:`function` for details.

Doc/library/logging.config.rst

@@ -253,6 +253,7 @@ otherwise, the context is used to determine what to instantiate.
    * ``datefmt``
    * ``style``
    * ``validate`` (since version >=3.8)
+   * ``defaults`` (since version >=3.12)
 
   An optional ``class`` key indicates the name of the formatter's
   class (as a dotted module and class name).  The instantiation
@@ -953,16 +954,22 @@ Sections which specify formatter configuration are typified by the following.
 .. code-block:: ini
 
    [formatter_form01]
-   format=F1 %(asctime)s %(levelname)s %(message)s
+   format=F1 %(asctime)s %(levelname)s %(message)s %(customfield)s
    datefmt=
    style=%
    validate=True
+   defaults={'customfield': 'defaultvalue'}
    class=logging.Formatter
 
 The arguments for the formatter configuration are the same as the keys
 in the dictionary schema :ref:`formatters section
 <logging-config-dictschema-formatters>`.
 
+The ``defaults`` entry, when :ref:`evaluated <func-eval>` in the context of
+the ``logging`` package's namespace, is a dictionary of default values for
+custom formatting fields. If not provided, it defaults to ``None``.
+
+
 .. note::
 
    Due to the use of :func:`eval` as described above, there are

Doc/library/multiprocessing.rst

@@ -452,7 +452,9 @@ process which created it.
    importable by the children. This is covered in :ref:`multiprocessing-programming`
    however it is worth pointing out here. This means that some examples, such
    as the :class:`multiprocessing.pool.Pool` examples will not work in the
-   interactive interpreter. For example::
+   interactive interpreter. For example:
+
+   .. code-block:: text
 
       >>> from multiprocessing import Pool
       >>> p = Pool(5)

Doc/library/pdb.rst

@@ -36,73 +36,91 @@ extension interface uses the modules :mod:`bdb` and :mod:`cmd`.
    Module :mod:`traceback`
       Standard interface to extract, format and print stack traces of Python programs.
 
-The debugger's prompt is ``(Pdb)``. Typical usage to run a program under control
-of the debugger is::
+The typical usage to break into the debugger is to insert::
 
-   >>> import pdb
-   >>> import mymodule
-   >>> pdb.run('mymodule.test()')
-   > <string>(0)?()
-   (Pdb) continue
-   > <string>(1)?()
+   import pdb; pdb.set_trace()
+
+Or::
+
+   breakpoint()
+
+at the location you want to break into the debugger, and then run the program.
+You can then step through the code following this statement, and continue
+running without the debugger using the :pdbcmd:`continue` command.
+
+.. versionadded:: 3.7
+   The built-in :func:`breakpoint()`, when called with defaults, can be used
+   instead of ``import pdb; pdb.set_trace()``.
+
+::
+
+   def double(x):
+      breakpoint()
+      return x * 2
+   val = 3
+   print(f"{val} * 2 is {double(val)}")
+
+The debugger's prompt is ``(Pdb)``, which is the indicator that you are in debug mode::
+
+   > ...(3)double()
+   -> return x * 2
+   (Pdb) p x
+   3
    (Pdb) continue
-   NameError: 'spam'
-   > <string>(1)?()
-   (Pdb)
+   3 * 2 is 6
 
 .. versionchanged:: 3.3
    Tab-completion via the :mod:`readline` module is available for commands and
    command arguments, e.g. the current global and local names are offered as
    arguments of the ``p`` command.
 
-:file:`pdb.py` can also be invoked as a script to debug other scripts.  For
+
+You can also invoke :mod:`pdb` from the command line to debug other scripts.  For
 example::
 
    python -m pdb myscript.py
 
-When invoked as a script, pdb will automatically enter post-mortem debugging if
+When invoked as a module, pdb will automatically enter post-mortem debugging if
 the program being debugged exits abnormally.  After post-mortem debugging (or
 after normal exit of the program), pdb will restart the program.  Automatic
 restarting preserves pdb's state (such as breakpoints) and in most cases is more
 useful than quitting the debugger upon program's exit.
 
 .. versionadded:: 3.2
-   :file:`pdb.py` now accepts a ``-c`` option that executes commands as if given
+   ``-c`` option is introduced to execute commands as if given
    in a :file:`.pdbrc` file, see :ref:`debugger-commands`.
 
 .. versionadded:: 3.7
-   :file:`pdb.py` now accepts a ``-m`` option that execute modules similar to the way
+   ``-m`` option is introduced to execute modules similar to the way
    ``python -m`` does. As with a script, the debugger will pause execution just
    before the first line of the module.
 
+Typical usage to execute a statement under control of the debugger is::
 
-The typical usage to break into the debugger is to insert::
-
-   import pdb; pdb.set_trace()
-
-at the location you want to break into the debugger, and then run the program.
-You can then step through the code following this statement, and continue
-running without the debugger using the :pdbcmd:`continue` command.
-
-.. versionadded:: 3.7
-   The built-in :func:`breakpoint()`, when called with defaults, can be used
-   instead of ``import pdb; pdb.set_trace()``.
+   >>> import pdb
+   >>> def f(x):
+   ...     print(1 / x)
+   >>> pdb.run("f(2)")
+   > <string>(1)<module>()
+   (Pdb) continue
+   0.5
+   >>>
 
 The typical usage to inspect a crashed program is::
 
    >>> import pdb
-   >>> import mymodule
-   >>> mymodule.test()
+   >>> def f(x):
+   ...     print(1 / x)
+   ...
+   >>> f(0)
    Traceback (most recent call last):
      File "<stdin>", line 1, in <module>
-     File "./mymodule.py", line 4, in test
-       test2()
-     File "./mymodule.py", line 3, in test2
-       print(spam)
-   NameError: spam
+     File "<stdin>", line 2, in f
+   ZeroDivisionError: division by zero
    >>> pdb.pm()
-   > ./mymodule.py(3)test2()
-   -> print(spam)
+   > <stdin>(2)f()
+   (Pdb) p x
+   0
    (Pdb)
 
 
@@ -275,7 +293,7 @@ can be overridden by the local file.
 
 .. pdbcommand:: w(here)
 
-   Print a stack trace, with the most recent frame at the bottom.  An arrow
+   Print a stack trace, with the most recent frame at the bottom.  An arrow (``>``)
    indicates the current frame, which determines the context of most commands.
 
 .. pdbcommand:: d(own) [count]
@@ -315,14 +333,14 @@ can be overridden by the local file.
    With a space separated list of breakpoint numbers, clear those breakpoints.
    Without argument, clear all breaks (but first ask confirmation).
 
-.. pdbcommand:: disable [bpnumber ...]
+.. pdbcommand:: disable bpnumber [bpnumber ...]
 
    Disable the breakpoints given as a space separated list of breakpoint
    numbers.  Disabling a breakpoint means it cannot cause the program to stop
    execution, but unlike clearing a breakpoint, it remains in the list of
    breakpoints and can be (re-)enabled.
 
-.. pdbcommand:: enable [bpnumber ...]
+.. pdbcommand:: enable bpnumber [bpnumber ...]
 
    Enable the breakpoints specified.
 
@@ -442,7 +460,7 @@ can be overridden by the local file.
 
 .. pdbcommand:: a(rgs)
 
-   Print the argument list of the current function.
+   Print the arguments of the current function and their current values.
 
 .. pdbcommand:: p expression
 
@@ -476,6 +494,50 @@ can be overridden by the local file.
 
    Without *expression*, list all display expressions for the current frame.
 
+   .. note::
+
+      Display evaluates *expression* and compares to the result of the previous
+      evaluation of *expression*, so when the result is mutable, display may not
+      be able to pick up the changes.
+
+   Example::
+
+      lst = []
+      breakpoint()
+      pass
+      lst.append(1)
+      print(lst)
+
+   Display won't realize ``lst`` has been changed because the result of evaluation
+   is modified in place by ``lst.append(1)`` before being compared::
+
+      > example.py(3)<module>()
+      -> pass
+      (Pdb) display lst
+      display lst: []
+      (Pdb) n
+      > example.py(4)<module>()
+      -> lst.append(1)
+      (Pdb) n
+      > example.py(5)<module>()
+      -> print(lst)
+      (Pdb)
+
+   You can do some tricks with copy mechanism to make it work::
+
+      > example.py(3)<module>()
+      -> pass
+      (Pdb) display lst[:]
+      display lst[:]: []
+      (Pdb) n
+      > example.py(4)<module>()
+      -> lst.append(1)
+      (Pdb) n
+      > example.py(5)<module>()
+      -> print(lst)
+      display lst[:]: [1]  [old: []]
+      (Pdb)
+
    .. versionadded:: 3.2
 
 .. pdbcommand:: undisplay [expression]
@@ -552,7 +614,7 @@ can be overridden by the local file.
 
 .. pdbcommand:: retval
 
-   Print the return value for the last return of a function.
+   Print the return value for the last return of the current function.
 
 .. rubric:: Footnotes
 

Doc/library/sched.rst

@@ -36,7 +36,7 @@ scheduler:
 Example::
 
    >>> import sched, time
-   >>> s = sched.scheduler(time.time, time.sleep)
+   >>> s = sched.scheduler(time.monotonic, time.sleep)
    >>> def print_time(a='default'):
    ...     print("From print_time", time.time(), a)
    ...

Doc/library/sys.rst

@@ -220,6 +220,10 @@ always available.
 
    .. audit-event:: sys._current_exceptions "" sys._current_exceptions
 
+   .. versionchanged:: 3.12
+      Each value in the dictionary is now a single exception instance, rather
+      than a 3-tuple as returned from ``sys.exc_info()``.
+
 .. function:: breakpointhook()
 
    This hook function is called by built-in :func:`breakpoint`.  By default,

Doc/library/types.rst

@@ -75,9 +75,9 @@ Dynamic Type Creation
 
    This function looks for items in *bases* that are not instances of
    :class:`type`, and returns a tuple where each such object that has
-   an ``__mro_entries__`` method is replaced with an unpacked result of
+   an :meth:`~object.__mro_entries__` method is replaced with an unpacked result of
    calling this method.  If a *bases* item is an instance of :class:`type`,
-   or it doesn't have an ``__mro_entries__`` method, then it is included in
+   or it doesn't have an :meth:`!__mro_entries__` method, then it is included in
    the return tuple unchanged.
 
    .. versionadded:: 3.7