Merge branch 'main' into gh-109461-update-logging-lock-acquisition

Author: AA-Turner

Doc/extending/windows.rst

@@ -132,4 +132,4 @@ modules (including Python) to be able to see your identifiers, you have to say
 Developer Studio will throw in a lot of import libraries that you do not really
 need, adding about 100K to your executable.  To get rid of them, use the Project
 Settings dialog, Link tab, to specify *ignore default libraries*.  Add the
-correct :file:`msvcrtxx.lib` to the list of libraries.
+correct :file:`msvcrt{xx}.lib` to the list of libraries.

Doc/howto/logging-cookbook.rst

@@ -1728,7 +1728,7 @@ when (and if) the logged message is actually about to be output to a log by a
 handler. So the only slightly unusual thing which might trip you up is that the
 parentheses go around the format string and the arguments, not just the format
 string. That's because the __ notation is just syntax sugar for a constructor
-call to one of the XXXMessage classes.
+call to one of the :samp:`{XXX}Message` classes.
 
 If you prefer, you can use a :class:`LoggerAdapter` to achieve a similar effect
 to the above, as in the following example::
@@ -2644,7 +2644,7 @@ when (and if) the logged message is actually about to be output to a log by a
 handler. So the only slightly unusual thing which might trip you up is that the
 parentheses go around the format string and the arguments, not just the format
 string. That’s because the __ notation is just syntax sugar for a constructor
-call to one of the ``XXXMessage`` classes shown above.
+call to one of the :samp:`{XXX}Message` classes shown above.
 
 
 .. _filters-dictconfig:

Doc/howto/logging.rst

@@ -979,7 +979,7 @@ provided:
 
 #. :class:`NullHandler` instances do nothing with error messages. They are used
    by library developers who want to use logging, but want to avoid the 'No
-   handlers could be found for logger XXX' message which can be displayed if
+   handlers could be found for logger *XXX*' message which can be displayed if
    the library user has not configured logging. See :ref:`library-config` for
    more information.
 

Doc/library/__future__.rst

@@ -22,42 +22,48 @@
   can be inspected programmatically via importing :mod:`__future__` and examining
   its contents.
 
-Each statement in :file:`__future__.py` is of the form::
+.. _future-classes:
 
-   FeatureName = _Feature(OptionalRelease, MandatoryRelease,
-                          CompilerFlag)
+.. class:: _Feature
 
+   Each statement in :file:`__future__.py` is of the form::
 
-where, normally, *OptionalRelease* is less than *MandatoryRelease*, and both are
-5-tuples of the same form as :data:`sys.version_info`::
+      FeatureName = _Feature(OptionalRelease, MandatoryRelease,
+                             CompilerFlag)
 
-   (PY_MAJOR_VERSION, # the 2 in 2.1.0a3; an int
-    PY_MINOR_VERSION, # the 1; an int
-    PY_MICRO_VERSION, # the 0; an int
-    PY_RELEASE_LEVEL, # "alpha", "beta", "candidate" or "final"; string
-    PY_RELEASE_SERIAL # the 3; an int
-   )
+   where, normally, *OptionalRelease* is less than *MandatoryRelease*, and both are
+   5-tuples of the same form as :data:`sys.version_info`::
 
-*OptionalRelease* records the first release in which the feature was accepted.
+      (PY_MAJOR_VERSION, # the 2 in 2.1.0a3; an int
+       PY_MINOR_VERSION, # the 1; an int
+       PY_MICRO_VERSION, # the 0; an int
+       PY_RELEASE_LEVEL, # "alpha", "beta", "candidate" or "final"; string
+       PY_RELEASE_SERIAL # the 3; an int
+      )
 
-In the case of a *MandatoryRelease* that has not yet occurred,
-*MandatoryRelease* predicts the release in which the feature will become part of
-the language.
+.. method:: _Feature.getOptionalRelease()
 
-Else *MandatoryRelease* records when the feature became part of the language; in
-releases at or after that, modules no longer need a future statement to use the
-feature in question, but may continue to use such imports.
+   *OptionalRelease* records the first release in which the feature was accepted.
 
-*MandatoryRelease* may also be ``None``, meaning that a planned feature got
-dropped.
+.. method:: _Feature.getMandatoryRelease()
 
-Instances of class :class:`_Feature` have two corresponding methods,
-:meth:`getOptionalRelease` and :meth:`getMandatoryRelease`.
+   In the case of a *MandatoryRelease* that has not yet occurred,
+   *MandatoryRelease* predicts the release in which the feature will become part of
+   the language.
 
-*CompilerFlag* is the (bitfield) flag that should be passed in the fourth
-argument to the built-in function :func:`compile` to enable the feature in
-dynamically compiled code.  This flag is stored in the :attr:`compiler_flag`
-attribute on :class:`_Feature` instances.
+   Else *MandatoryRelease* records when the feature became part of the language; in
+   releases at or after that, modules no longer need a future statement to use the
+   feature in question, but may continue to use such imports.
+
+   *MandatoryRelease* may also be ``None``, meaning that a planned feature got
+   dropped or that it is not yet decided.
+
+.. attribute:: _Feature.compiler_flag
+
+   *CompilerFlag* is the (bitfield) flag that should be passed in the fourth
+   argument to the built-in function :func:`compile` to enable the feature in
+   dynamically compiled code.  This flag is stored in the :attr:`_Feature.compiler_flag`
+   attribute on :class:`_Feature` instances.
 
 No feature description will ever be deleted from :mod:`__future__`. Since its
 introduction in Python 2.1 the following features have found their way into the

Doc/library/codecs.rst

@@ -345,9 +345,10 @@ The following error handlers can be used with all Python
 +-------------------------+-----------------------------------------------+
 | ``'backslashreplace'``  | Replace with backslashed escape sequences.    |
 |                         | On encoding, use hexadecimal form of Unicode  |
-|                         | code point with formats ``\xhh`` ``\uxxxx``   |
-|                         | ``\Uxxxxxxxx``. On decoding, use hexadecimal  |
-|                         | form of byte value with format ``\xhh``.      |
+|                         | code point with formats :samp:`\\x{hh}`       |
+|                         | :samp:`\\u{xxxx}` :samp:`\\U{xxxxxxxx}`.      |
+|                         | On decoding, use hexadecimal form of byte     |
+|                         | value with format :samp:`\\x{hh}`.            |
 |                         | Implemented in                                |
 |                         | :func:`backslashreplace_errors`.              |
 +-------------------------+-----------------------------------------------+
@@ -373,8 +374,9 @@ The following error handlers are only applicable to encoding (within
 +=========================+===============================================+
 | ``'xmlcharrefreplace'`` | Replace with XML/HTML numeric character       |
 |                         | reference, which is a decimal form of Unicode |
-|                         | code point with format ``&#num;`` Implemented |
-|                         | in :func:`xmlcharrefreplace_errors`.          |
+|                         | code point with format :samp:`&#{num};`.      |
+|                         | Implemented in                                |
+|                         | :func:`xmlcharrefreplace_errors`.             |
 +-------------------------+-----------------------------------------------+
 | ``'namereplace'``       | Replace with ``\N{...}`` escape sequences,    |
 |                         | what appears in the braces is the Name        |
@@ -478,8 +480,9 @@ functions:
 
    Malformed data is replaced by a backslashed escape sequence.
    On encoding, use the hexadecimal form of Unicode code point with formats
-   ``\xhh`` ``\uxxxx`` ``\Uxxxxxxxx``. On decoding, use the hexadecimal form of
-   byte value with format ``\xhh``.
+   :samp:`\\x{hh}` :samp:`\\u{xxxx}` :samp:`\\U{xxxxxxxx}`.
+   On decoding, use the hexadecimal form of
+   byte value with format :samp:`\\x{hh}`.
 
    .. versionchanged:: 3.5
       Works with decoding and translating.
@@ -492,7 +495,7 @@ functions:
 
    The unencodable character is replaced by an appropriate XML/HTML numeric
    character reference, which is a decimal form of Unicode code point with
-   format ``&#num;`` .
+   format :samp:`&#{num};` .
 
 
 .. function:: namereplace_errors(exception)
@@ -1346,9 +1349,10 @@ encodings.
 |                    |         | supported.                |
 +--------------------+---------+---------------------------+
 | raw_unicode_escape |         | Latin-1 encoding with     |
-|                    |         | ``\uXXXX`` and            |
-|                    |         | ``\UXXXXXXXX`` for other  |
-|                    |         | code points. Existing     |
+|                    |         | :samp:`\\u{XXXX}` and     |
+|                    |         | :samp:`\\U{XXXXXXXX}``    |
+|                    |         | for other code points.    |
+|                    |         | Existing                  |
 |                    |         | backslashes are not       |
 |                    |         | escaped in any way.       |
 |                    |         | It is used in the Python  |

Doc/library/compileall.rst

@@ -31,7 +31,7 @@ compile Python sources.
 
    Positional arguments are files to compile or directories that contain
    source files, traversed recursively.  If no argument is given, behave as if
-   the command line was ``-l <directories from sys.path>``.
+   the command line was :samp:`-l {<directories from sys.path>}`.
 
 .. cmdoption:: -l
 

Doc/library/concurrent.futures.rst

@@ -293,6 +293,14 @@ to a :class:`ProcessPoolExecutor` will result in deadlock.
       The *max_tasks_per_child* argument was added to allow users to
       control the lifetime of workers in the pool.
 
+   .. versionchanged:: 3.12
+      On POSIX systems, if your application has multiple threads and the
+      :mod:`multiprocessing` context uses the ``"fork"`` start method:
+      The :func:`os.fork` function called internally to spawn workers may raise a
+      :exc:`DeprecationWarning`. Pass a *mp_context* configured to use a
+      different start method. See the :func:`os.fork` documentation for
+      further explanation.
+
 .. _processpoolexecutor-example:
 
 ProcessPoolExecutor Example

Doc/library/ensurepip.rst

@@ -61,7 +61,7 @@ By default, ``pip`` is installed into the current virtual environment
 active virtual environment). The installation location can be controlled
 through two additional command line options:
 
-* ``--root <dir>``: Installs ``pip`` relative to the given root directory
+* :samp:`--root {dir}`: Installs ``pip`` relative to the given root directory
   rather than the root of the currently active virtual environment (if any)
   or the default root for the current Python installation.
 * ``--user``: Installs ``pip`` into the user site packages directory rather

Doc/library/functions.rst

@@ -1271,7 +1271,7 @@ are always available.  They are listed here in alphabetical order.
 
    * ``'xmlcharrefreplace'`` is only supported when writing to a file.
      Characters not supported by the encoding are replaced with the
-     appropriate XML character reference ``&#nnn;``.
+     appropriate XML character reference :samp:`&#{nnn};`.
 
    * ``'backslashreplace'`` replaces malformed data by Python's backslashed
      escape sequences.

Doc/library/html.parser.rst

@@ -173,7 +173,7 @@ implementations do nothing (except for :meth:`~HTMLParser.handle_startendtag`):
 .. method:: HTMLParser.handle_charref(name)
 
    This method is called to process decimal and hexadecimal numeric character
-   references of the form ``&#NNN;`` and ``&#xNNN;``.  For example, the decimal
+   references of the form :samp:`&#{NNN};` and :samp:`&#x{NNN};`.  For example, the decimal
    equivalent for ``>`` is ``>``, whereas the hexadecimal is ``>``;
    in this case the method will receive ``'62'`` or ``'x3E'``.  This method
    is never called if *convert_charrefs* is ``True``.