Merge branch 'main' into specialize-iteration-with-jit

Author: markshannon

Doc/deprecations/index.rst

@@ -15,6 +15,8 @@ Deprecations
 
 .. include:: pending-removal-in-future.rst
 
+.. include:: soft-deprecations.rst
+
 C API deprecations
 ------------------
 

Doc/deprecations/soft-deprecations.rst

@@ -0,0 +1,21 @@
+Soft deprecations
+-----------------
+
+There are no plans to remove :term:`soft deprecated` APIs.
+
+* :func:`re.match` and :meth:`re.Pattern.match` are now
+  :term:`soft deprecated` in favor of the new :func:`re.prefixmatch` and
+  :meth:`re.Pattern.prefixmatch` APIs, which have been added as alternate,
+  more explicit names. These are intended to be used to alleviate confusion
+  around what *match* means by following the Zen of Python's *"Explicit is
+  better than implicit"* mantra. Most other language regular expression
+  libraries use an API named *match* to mean what Python has always called
+  *search*.
+
+  We **do not** plan to remove the older :func:`!match` name, as it has been
+  used in code for over 30 years. Code supporting older versions of Python
+  should continue to use :func:`!match`, while new code should prefer
+  :func:`!prefixmatch`. See :ref:`prefixmatch-vs-match`.
+
+  (Contributed by Gregory P. Smith in :gh:`86519` and
+  Hugo van Kemenade in :gh:`148100`.)

Doc/library/enum.rst

@@ -502,7 +502,7 @@ Data types
       Using :class:`auto` with :class:`Enum` results in integers of increasing value,
       starting with ``1``.
 
-   .. versionchanged:: 3.12 Added :ref:`enum-dataclass-support`
+   .. versionchanged:: 3.12 Added :ref:`enum-dataclass-support`.
 
    .. method:: Enum._add_alias_
 
@@ -977,9 +977,9 @@ Utilities and decorators
 
    *auto* can be used in place of a value.  If used, the *Enum* machinery will
    call an :class:`Enum`'s :meth:`~Enum._generate_next_value_` to get an appropriate value.
-   For :class:`Enum` and :class:`IntEnum` that appropriate value will be the last value plus
-   one; for :class:`Flag` and :class:`IntFlag` it will be the first power-of-two greater
-   than the highest value; for :class:`StrEnum` it will be the lower-cased version of
+   For :class:`Enum` and :class:`IntEnum` that appropriate value will be the highest value seen
+   plus one; for :class:`Flag` and :class:`IntFlag` it will be the first power-of-two greater
+   than the highest value seen; for :class:`StrEnum` it will be the lower-cased version of
    the member's name.  Care must be taken if mixing *auto()* with manually
    specified values.
 
@@ -989,8 +989,8 @@ Utilities and decorators
    * ``FIRST = auto()`` will work (auto() is replaced with ``1``);
    * ``SECOND = auto(), -2`` will work (auto is replaced with ``2``, so ``2, -2`` is
      used to create the ``SECOND`` enum member;
-   * ``THREE = [auto(), -3]`` will *not* work (``[<auto instance>, -3]`` is used to
-     create the ``THREE`` enum member)
+   * ``THIRD = [auto(), -3]`` will *not* work (``[<auto instance>, -3]`` is used to
+     create the ``THIRD`` enum member)
 
    .. versionchanged:: 3.11.1
 
@@ -1000,7 +1000,7 @@ Utilities and decorators
    ``_generate_next_value_`` can be overridden to customize the values used by
    *auto*.
 
-   .. note:: in 3.13 the default ``_generate_next_value_`` will always return
+   .. note:: In version 3.13 the default ``_generate_next_value_`` will always return
              the highest member value incremented by 1, and will fail if any
              member is an incompatible type.
 
@@ -1010,7 +1010,7 @@ Utilities and decorators
    enumerations.  It allows member attributes to have the same names as members
    themselves.
 
-   .. note:: the *property* and the member must be defined in separate classes;
+   .. note:: The *property* and the member must be defined in separate classes;
              for example, the *value* and *name* attributes are defined in the
              *Enum* class, and *Enum* subclasses can define members with the
              names ``value`` and ``name``.

Doc/library/http.server.rst

@@ -99,7 +99,7 @@ instantiation, of which this module provides three different variants:
 
    This class is used to handle the HTTP requests that arrive at the server.  By
    itself, it cannot respond to any actual HTTP requests; it must be subclassed
-   to handle each request method (e.g. GET or POST).
+   to handle each request method (for example, ``'GET'`` or ``'POST'``).
    :class:`BaseHTTPRequestHandler` provides a number of class and instance
    variables, and methods for use by subclasses.
 
@@ -241,7 +241,7 @@ instantiation, of which this module provides three different variants:
       request header it responds back with a ``100 Continue`` followed by ``200
       OK`` headers.
       This method can be overridden to raise an error if the server does not
-      want the client to continue.  For e.g. server can choose to send ``417
+      want the client to continue.  For example, the server can choose to send ``417
       Expectation Failed`` as a response header and ``return False``.
 
       .. versionadded:: 3.2
@@ -469,7 +469,9 @@ Command-line interface
 
 :mod:`!http.server` can also be invoked directly using the :option:`-m`
 switch of the interpreter.  The following example illustrates how to serve
-files relative to the current directory::
+files relative to the current directory:
+
+.. code-block:: bash
 
    python -m http.server [OPTIONS] [port]
 
@@ -480,7 +482,9 @@ The following options are accepted:
 .. option:: port
 
    The server listens to port 8000 by default. The default can be overridden
-   by passing the desired port number as an argument::
+   by passing the desired port number as an argument:
+
+   .. code-block:: bash
 
       python -m http.server 9000
 
@@ -489,7 +493,9 @@ The following options are accepted:
    Specifies a specific address to which it should bind. Both IPv4 and IPv6
    addresses are supported. By default, the server binds itself to all
    interfaces. For example, the following command causes the server to bind
-   to localhost only::
+   to localhost only:
+
+   .. code-block:: bash
 
       python -m http.server --bind 127.0.0.1
 
@@ -502,7 +508,9 @@ The following options are accepted:
 
    Specifies a directory to which it should serve the files. By default,
    the server uses the current directory. For example, the following command
-   uses a specific directory::
+   uses a specific directory:
+
+   .. code-block:: bash
 
       python -m http.server --directory /tmp/
 
@@ -512,15 +520,19 @@ The following options are accepted:
 
    Specifies the HTTP version to which the server is conformant. By default,
    the server is conformant to HTTP/1.0. For example, the following command
-   runs an HTTP/1.1 conformant server::
+   runs an HTTP/1.1 conformant server:
+
+   .. code-block:: bash
 
       python -m http.server --protocol HTTP/1.1
 
    .. versionadded:: 3.11
 
 .. option:: --tls-cert
 
-   Specifies a TLS certificate chain for HTTPS connections::
+   Specifies a TLS certificate chain for HTTPS connections:
+
+   .. code-block:: bash
 
       python -m http.server --tls-cert fullchain.pem
 
@@ -536,14 +548,16 @@ The following options are accepted:
 
 .. option:: --tls-password-file
 
-   Specifies the password file for password-protected private keys::
+   Specifies the password file for password-protected private keys:
+
+   .. code-block:: bash
 
       python -m http.server \
              --tls-cert cert.pem \
              --tls-key key.pem \
              --tls-password-file password.txt
 
-   This option requires `--tls-cert`` to be specified.
+   This option requires ``--tls-cert`` to be specified.
 
    .. versionadded:: 3.14
 
@@ -561,7 +575,7 @@ to be served.
 
 Methods :meth:`BaseHTTPRequestHandler.send_header` and
 :meth:`BaseHTTPRequestHandler.send_response_only` assume sanitized input
-and does not perform input validation such as checking for the presence of CRLF
+and do not perform input validation such as checking for the presence of CRLF
 sequences. Untrusted input may result in HTTP Header injection attacks.
 
 Earlier versions of Python did not scrub control characters from the

Doc/library/re.rst

@@ -52,7 +52,7 @@ fine-tuning parameters.
 
 .. _re-syntax:
 
-Regular Expression Syntax
+Regular expression syntax
 -------------------------
 
 A regular expression (or RE) specifies a set of strings that matches it; the
@@ -205,7 +205,7 @@ The special characters are:
    *without* establishing any backtracking points.
    This is the possessive version of the quantifier above.
    For example, on the 6-character string ``'aaaaaa'``, ``a{3,5}+aa``
-   attempt to match 5 ``'a'`` characters, then, requiring 2 more ``'a'``\ s,
+   attempts to match 5 ``'a'`` characters, then, requiring 2 more ``'a'``\ s,
    will need more characters than available and thus fail, while
    ``a{3,5}aa`` will match with ``a{3,5}`` capturing 5, then 4 ``'a'``\ s
    by backtracking and then the final 2 ``'a'``\ s are matched by the final
@@ -717,7 +717,7 @@ three digits in length.
 
 .. _contents-of-module-re:
 
-Module Contents
+Module contents
 ---------------
 
 The module defines several functions, constants, and an exception. Some of the
@@ -833,8 +833,8 @@ Flags
    will be conditionally ORed with other flags.  Example of use as a default
    value::
 
-      def myfunc(text, flag=re.NOFLAG):
-          return re.search(text, flag)
+      def myfunc(pattern, text, flag=re.NOFLAG):
+          return re.search(pattern, text, flag)
 
    .. versionadded:: 3.11
 
@@ -954,9 +954,10 @@ Functions
    :func:`~re.match`.  Use that name when you need to retain compatibility with
    older Python versions.
 
-   .. versionchanged:: 3.15
-      The alternate :func:`~re.prefixmatch` name of this API was added as a
-      more explicitly descriptive name than :func:`~re.match`. Use it to better
+   .. deprecated:: 3.15
+      :func:`~re.match` has been :term:`soft deprecated` in favor of
+      the alternate :func:`~re.prefixmatch` name of this API which is
+      more explicitly descriptive. Use it to better
       express intent. The norm in other languages and regular expression
       implementations is to use the term *match* to refer to the behavior of
       what Python has always called :func:`~re.search`.
@@ -1246,7 +1247,7 @@ Exceptions
 
 .. _re-objects:
 
-Regular Expression Objects
+Regular expression objects
 --------------------------
 
 .. class:: Pattern
@@ -1309,9 +1310,10 @@ Regular Expression Objects
    :meth:`~Pattern.match`.  Use that name when you need to retain compatibility
    with older Python versions.
 
-   .. versionchanged:: 3.15
-      The alternate :meth:`~Pattern.prefixmatch` name of this API was added as
-      a more explicitly descriptive name than :meth:`~Pattern.match`. Use it to
+   .. deprecated:: 3.15
+      :meth:`~Pattern.match` has been :term:`soft deprecated` in favor of
+      the alternate :meth:`~Pattern.prefixmatch` name of this API which is
+      more explicitly descriptive. Use it to
       better express intent. The norm in other languages and regular expression
       implementations is to use the term *match* to refer to the behavior of
       what Python has always called :meth:`~Pattern.search`.
@@ -1396,7 +1398,7 @@ Regular Expression Objects
 
 .. _match-objects:
 
-Match Objects
+Match objects
 -------------
 
 Match objects always have a boolean value of ``True``.
@@ -1615,11 +1617,11 @@ when there is no match, you can test whether there was a match with a simple
 
 .. _re-examples:
 
-Regular Expression Examples
+Regular expression examples
 ---------------------------
 
 
-Checking for a Pair
+Checking for a pair
 ^^^^^^^^^^^^^^^^^^^
 
 In this example, we'll use the following helper function to display match
@@ -1705,15 +1707,21 @@ expressions.
 | ``%x``, ``%X``                 | ``[-+]?(0[xX])?[\dA-Fa-f]+``                |
 +--------------------------------+---------------------------------------------+
 
-To extract the filename and numbers from a string like ::
+To extract the filename and numbers from a string like:
+
+.. code-block:: text
 
    /usr/sbin/sendmail - 0 errors, 4 warnings
 
-you would use a :c:func:`!scanf` format like ::
+you would use a :c:func:`!scanf` format like:
+
+.. code-block:: text
 
    %s - %d errors, %d warnings
 
-The equivalent regular expression would be ::
+The equivalent regular expression would be:
+
+.. code-block:: text
 
    (\S+) - (\d+) errors, (\d+) warnings
 
@@ -1772,18 +1780,24 @@ not familiar with the Python API's divergence from what otherwise become the
 industry norm.
 
 Quoting from the Zen Of Python (``python3 -m this``): *"Explicit is better than
-implicit"*. Anyone reading the name :func:`~re.prefixmatch` is likely to
-understand the intended semantics. When reading :func:`~re.match` there remains
+implicit"*. Anyone reading the name :func:`!prefixmatch` is likely to
+understand the intended semantics. When reading :func:`!match` there remains
 a seed of doubt about the intended behavior to anyone not already familiar with
 this old Python gotcha.
 
-We **do not** plan to deprecate and remove the older *match* name,
+We **do not** plan to remove the older :func:`!match` name,
 as it has been used in code for over 30 years.
-Code supporting older versions of Python should continue to use *match*.
+It has been :term:`soft deprecated`:
+code supporting older versions of Python should continue to use :func:`!match`,
+while new code should prefer :func:`!prefixmatch`.
 
 .. versionadded:: 3.15
+   :func:`!prefixmatch`
+
+.. deprecated:: 3.15
+   :func:`!match` is :term:`soft deprecated`
 
-Making a Phonebook
+Making a phonebook
 ^^^^^^^^^^^^^^^^^^
 
 :func:`split` splits a string into a list delimited by the passed pattern.  The
@@ -1844,7 +1858,7 @@ house number from the street name:
    ['Heather', 'Albrecht', '548.326.4584', '919', 'Park Place']]
 
 
-Text Munging
+Text munging
 ^^^^^^^^^^^^
 
 :func:`sub` replaces every occurrence of a pattern with a string or the
@@ -1864,7 +1878,7 @@ in each word of a sentence except for the first and last characters::
    'Pofsroser Aodlambelk, plasee reoprt yuor asnebces potlmrpy.'
 
 
-Finding all Adverbs
+Finding all adverbs
 ^^^^^^^^^^^^^^^^^^^
 
 :func:`findall` matches *all* occurrences of a pattern, not just the first
@@ -1877,7 +1891,7 @@ the following manner::
    ['carefully', 'quickly']
 
 
-Finding all Adverbs and their Positions
+Finding all adverbs and their positions
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 If one wants more information about all matches of a pattern than the matched
@@ -1893,7 +1907,7 @@ to find all of the adverbs *and their positions* in some text, they would use
    40-47: quickly
 
 
-Raw String Notation
+Raw string notation
 ^^^^^^^^^^^^^^^^^^^
 
 Raw string notation (``r"text"``) keeps regular expressions sane.  Without it,
@@ -1917,7 +1931,7 @@ functionally identical::
    <re.Match object; span=(0, 1), match='\\'>
 
 
-Writing a Tokenizer
+Writing a tokenizer
 ^^^^^^^^^^^^^^^^^^^
 
 A `tokenizer or scanner <https://en.wikipedia.org/wiki/Lexical_analysis>`_