bpo-42353: Add prefixmatch APIs to the re module.

These alleviate common confusion around what "match" means as Python is
different than other popular languages in our use of the term as an API
name.  The original "match" names are NOT being deprecated.  Source
tooling like linters are expected to suggest using prefixmatch instead
of match to improve code health and reduce cognitive burden of
understanding the intent when reading code.

See the documentation changes within this PR for a better description.

Author: gpshead

Doc/library/re.rst

@@ -610,8 +610,8 @@ form.
 
    Compile a regular expression pattern into a :ref:`regular expression object
    <re-objects>`, which can be used for matching using its
-   :func:`~Pattern.match`, :func:`~Pattern.search` and other methods, described
-   below.
+   :func:`~Pattern.prefixmatch`, :func:`~Pattern.search` and other methods,
+   described below.
 
    The expression's behaviour can be modified by specifying a *flags* value.
    Values can be any of the following variables, combined using bitwise OR (the
@@ -620,11 +620,11 @@ form.
    The sequence ::
 
       prog = re.compile(pattern)
-      result = prog.match(string)
+      result = prog.search(string)
 
    is equivalent to ::
 
-      result = re.match(pattern, string)
+      result = re.search(pattern, string)
 
    but using :func:`re.compile` and saving the resulting regular expression
    object for reuse is more efficient when the expression will be used several
@@ -753,19 +753,36 @@ form.
    point in the string.
 
 
-.. function:: match(pattern, string, flags=0)
+.. function:: prefixmatch(pattern, string, flags=0)
 
    If zero or more characters at the beginning of *string* match the regular
    expression *pattern*, return a corresponding :ref:`match object
    <match-objects>`.  Return ``None`` if the string does not match the pattern;
    note that this is different from a zero-length match.
 
-   Note that even in :const:`MULTILINE` mode, :func:`re.match` will only match
-   at the beginning of the string and not at the beginning of each line.
+   Note that even in :const:`MULTILINE` mode, :func:`re.prefixmatch` will only
+   match at the beginning of the string and not at the beginning of each line.
 
    If you want to locate a match anywhere in *string*, use :func:`search`
    instead (see also :ref:`search-vs-match`).
 
+   Use :func:`~re.match` when your code needs to support older Python versions.
+
+   .. versionadded:: 3.11
+
+
+.. function:: match(pattern, string, flags=0)
+
+   The same as :func:`prefixmatch` documented above. Prefer using that more
+   explicit name when writing code intended only for Python versions 3.11
+   and up.
+
+   The new name was created in order to be explicit about its behavior
+   to reduce confusion vs the industry norm for regular expression APIs.
+   See :ref:`prefixmatch-vs-match`.
+
+   .. versionchanged:: 3.11
+
 
 .. function:: fullmatch(pattern, string, flags=0)
 
@@ -1041,7 +1058,7 @@ attributes:
       >>> pattern.search("dog", 1)  # No match; search doesn't include the "d"
 
 
-.. method:: Pattern.match(string[, pos[, endpos]])
+.. method:: Pattern.prefixmatch(string[, pos[, endpos]])
 
    If zero or more characters at the *beginning* of *string* match this regular
    expression, return a corresponding :ref:`match object <match-objects>`.
@@ -1059,6 +1076,23 @@ attributes:
    If you want to locate a match anywhere in *string*, use
    :meth:`~Pattern.search` instead (see also :ref:`search-vs-match`).
 
+   Use :meth:`~Pattern.match` when your code needs to support older Pythons.
+
+   .. versionadded:: 3.11
+
+
+.. method:: Pattern.match(string[, pos[, endpos]])
+
+   The same as :meth:`Pattern.prefixmatch` documented above. Prefer using that
+   more explicit name when writing code intended only for Python versions 3.11
+   and up.
+
+   The new name was created in order to be explicit about its behavior
+   to reduce confusion vs the industry norm for regular expression APIs.
+   See :ref:`prefixmatch-vs-match`.
+
+   .. versionchanged:: 3.11
+
 
 .. method:: Pattern.fullmatch(string[, pos[, endpos]])
 
@@ -1179,7 +1213,7 @@ Match objects support the following methods and attributes:
    If a group is contained in a part of the pattern that matched multiple times,
    the last match is returned. ::
 
-      >>> m = re.match(r"(\w+) (\w+)", "Isaac Newton, physicist")
+      >>> m = re.search(r"(\w+) (\w+)", "Isaac Newton, physicist")
       >>> m.group(0)       # The entire match
       'Isaac Newton'
       >>> m.group(1)       # The first parenthesized subgroup.
@@ -1196,7 +1230,7 @@ Match objects support the following methods and attributes:
 
    A moderately complicated example::
 
-      >>> m = re.match(r"(?P<first_name>\w+) (?P<last_name>\w+)", "Malcolm Reynolds")
+      >>> m = re.search(r"(?P<first_name>\w+) (?P<last_name>\w+)", "Malcolm Reynolds")
       >>> m.group('first_name')
       'Malcolm'
       >>> m.group('last_name')
@@ -1211,8 +1245,8 @@ Match objects support the following methods and attributes:
 
    If a group matches multiple times, only the last match is accessible::
 
-      >>> m = re.match(r"(..)+", "a1b2c3")  # Matches 3 times.
-      >>> m.group(1)                        # Returns only the last match.
+      >>> m = re.search(r"(..)+", "a1b2c3")  # Matches 3 times.
+      >>> m.group(1)                         # Returns only the last match.
       'c3'
 
 
@@ -1221,7 +1255,7 @@ Match objects support the following methods and attributes:
    This is identical to ``m.group(g)``.  This allows easier access to
    an individual group from a match::
 
-      >>> m = re.match(r"(\w+) (\w+)", "Isaac Newton, physicist")
+      >>> m = re.search(r"(\w+) (\w+)", "Isaac Newton, physicist")
       >>> m[0]       # The entire match
       'Isaac Newton'
       >>> m[1]       # The first parenthesized subgroup.
@@ -1240,15 +1274,15 @@ Match objects support the following methods and attributes:
 
    For example::
 
-      >>> m = re.match(r"(\d+)\.(\d+)", "24.1632")
+      >>> m = re.search(r"(\d+)\.(\d+)", "24.1632")
       >>> m.groups()
       ('24', '1632')
 
    If we make the decimal place and everything after it optional, not all groups
    might participate in the match.  These groups will default to ``None`` unless
    the *default* argument is given::
 
-      >>> m = re.match(r"(\d+)\.?(\d+)?", "24")
+      >>> m = re.search(r"(\d+)\.?(\d+)?", "24")
       >>> m.groups()      # Second group defaults to None.
       ('24', None)
       >>> m.groups('0')   # Now, the second group defaults to '0'.
@@ -1261,7 +1295,7 @@ Match objects support the following methods and attributes:
    the subgroup name.  The *default* argument is used for groups that did not
    participate in the match; it defaults to ``None``.  For example::
 
-      >>> m = re.match(r"(?P<first_name>\w+) (?P<last_name>\w+)", "Malcolm Reynolds")
+      >>> m = re.search(r"(?P<first_name>\w+) (?P<last_name>\w+)", "Malcolm Reynolds")
       >>> m.groupdict()
       {'first_name': 'Malcolm', 'last_name': 'Reynolds'}
 
@@ -1367,38 +1401,38 @@ representing the card with that value.
 To see if a given string is a valid hand, one could do the following::
 
    >>> valid = re.compile(r"^[a2-9tjqk]{5}$")
-   >>> displaymatch(valid.match("akt5q"))  # Valid.
+   >>> displaymatch(valid.search("akt5q"))  # Valid.
    "<Match: 'akt5q', groups=()>"
-   >>> displaymatch(valid.match("akt5e"))  # Invalid.
-   >>> displaymatch(valid.match("akt"))    # Invalid.
-   >>> displaymatch(valid.match("727ak"))  # Valid.
+   >>> displaymatch(valid.search("akt5e"))  # Invalid.
+   >>> displaymatch(valid.search("akt"))    # Invalid.
+   >>> displaymatch(valid.search("727ak"))  # Valid.
    "<Match: '727ak', groups=()>"
 
 That last hand, ``"727ak"``, contained a pair, or two of the same valued cards.
 To match this with a regular expression, one could use backreferences as such::
 
-   >>> pair = re.compile(r".*(.).*\1")
-   >>> displaymatch(pair.match("717ak"))     # Pair of 7s.
+   >>> pair = re.compile(r"^.*(.).*\1")
+   >>> displaymatch(pair.search("717ak"))     # Pair of 7s.
    "<Match: '717', groups=('7',)>"
-   >>> displaymatch(pair.match("718ak"))     # No pairs.
-   >>> displaymatch(pair.match("354aa"))     # Pair of aces.
+   >>> displaymatch(pair.search("718ak"))     # No pairs.
+   >>> displaymatch(pair.search("354aa"))     # Pair of aces.
    "<Match: '354aa', groups=('a',)>"
 
 To find out what card the pair consists of, one could use the
 :meth:`~Match.group` method of the match object in the following manner::
 
-   >>> pair = re.compile(r".*(.).*\1")
-   >>> pair.match("717ak").group(1)
+   >>> pair = re.compile(r"^.*(.).*\1")
+   >>> pair.search("717ak").group(1)
    '7'
 
    # Error because re.match() returns None, which doesn't have a group() method:
-   >>> pair.match("718ak").group(1)
+   >>> pair.search("718ak").group(1)
    Traceback (most recent call last):
      File "<pyshell#23>", line 1, in <module>
-       re.match(r".*(.).*\1", "718ak").group(1)
+       re.search(r".*(.).*\1", "718ak").group(1)
    AttributeError: 'NoneType' object has no attribute 'group'
 
-   >>> pair.match("354aa").group(1)
+   >>> pair.search("354aa").group(1)
    'a'
 
 
@@ -1456,32 +1490,54 @@ search() vs. match()
 .. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org>
 
 Python offers two different primitive operations based on regular expressions:
-:func:`re.match` checks for a match only at the beginning of the string, while
-:func:`re.search` checks for a match anywhere in the string (this is what Perl
-does by default).
+:func:`re.prefixmatch` and its older equivalent named :func:`re.match` checks
+for a match only at the beginning of the string, while :func:`re.search` checks
+for a match anywhere in the string (this is what Perl does by default).
 
 For example::
 
-   >>> re.match("c", "abcdef")    # No match
-   >>> re.search("c", "abcdef")   # Match
+   >>> re.match("c", "abcdef")        # No match
+   >>> re.prefixmatch("c", "abcdef")  # No match
+   >>> re.search("c", "abcdef")       # Match
    <re.Match object; span=(2, 3), match='c'>
 
 Regular expressions beginning with ``'^'`` can be used with :func:`search` to
 restrict the match at the beginning of the string::
 
-   >>> re.match("c", "abcdef")    # No match
-   >>> re.search("^c", "abcdef")  # No match
-   >>> re.search("^a", "abcdef")  # Match
+   >>> re.match("c", "abcdef")        # No match
+   >>> re.prefixmatch("c", "abcdef")  # No match
+   >>> re.search("^c", "abcdef")      # No match
+   >>> re.search("^a", "abcdef")      # Match
    <re.Match object; span=(0, 1), match='a'>
 
 Note however that in :const:`MULTILINE` mode :func:`match` only matches at the
 beginning of the string, whereas using :func:`search` with a regular expression
 beginning with ``'^'`` will match at the beginning of each line. ::
 
-   >>> re.match('X', 'A\nB\nX', re.MULTILINE)  # No match
-   >>> re.search('^X', 'A\nB\nX', re.MULTILINE)  # Match
+   >>> re.match('X', 'A\nB\nX', re.MULTILINE)        # No match
+   >>> re.prefixmatch('X', 'A\nB\nX', re.MULTILINE)  # No match
+   >>> re.search('^X', 'A\nB\nX', re.MULTILINE)      # Match
    <re.Match object; span=(4, 5), match='X'>
 
+.. _prefixmatch-vs-match:
+
+prefixmatch() vs. match()
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Why is the :func:`re.match` name being discouraged in favor of the longer
+:func:`re.prefixmatch` as of Python 3.11?
+
+Since regular expressions were introduced in Python, many other languages have
+been created and or gained regex support libraries. However in the most popular
+of those, they use the term "match" in their APIs to mean the unanchored
+behavior provided in Python by :func:`re.search`. Thus any use of the plain
+term "match" can be confusing to those reading or writing Python who are not
+familiar with it's divergence from the collective software 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 semantics intended. When reading :func:`re.match` there remains
+a seed of doubt about the author's actual intended behavior.
 
 Making a Phonebook
 ^^^^^^^^^^^^^^^^^^
@@ -1600,19 +1656,19 @@ every backslash (``'\'``) in a regular expression would have to be prefixed with
 another one to escape it.  For example, the two following lines of code are
 functionally identical::
 
-   >>> re.match(r"\W(.)\1\W", " ff ")
+   >>> re.search(r"\W(.)\1\W", " ff ")
    <re.Match object; span=(0, 4), match=' ff '>
-   >>> re.match("\\W(.)\\1\\W", " ff ")
+   >>> re.search("\\W(.)\\1\\W", " ff ")
    <re.Match object; span=(0, 4), match=' ff '>
 
 When one wants to match a literal backslash, it must be escaped in the regular
 expression.  With raw string notation, this means ``r"\\"``.  Without raw string
 notation, one must use ``"\\\\"``, making the following lines of code
 functionally identical::
 
-   >>> re.match(r"\\", r"\\")
+   >>> re.search(r"\\", r"\\")
    <re.Match object; span=(0, 1), match='\\'>
-   >>> re.match("\\\\", r"\\")
+   >>> re.search("\\\\", r"\\")
    <re.Match object; span=(0, 1), match='\\'>
 
 

Doc/whatsnew/3.11.rst

@@ -264,6 +264,17 @@ os
   (Contributed by Dong-hee Na in :issue:`44611`.)
 
 
+re
+--
+
+* :func:`re.prefixmatch` and a corresponding :meth:`re.Pattern.prefixmatch`
+  have been added as alternate names for the existing :func:`re.match` and
+  :meth:`re.Pattern.prefixmatch` APIs. These are intended to be used to
+  alleviate confusion around what "match" means by following *"Explicit is
+  better than implicit"*. Other popular language regular expression libraries
+  use an API named ``match`` to mean what Python has always called ``search``.
+
+
 socket
 ------