gh-118184: Support tuples for find, index, rfind & rindex

Doc/library/stdtypes.rst

@@ -1724,8 +1724,13 @@ expression support in the :mod:`re` module).
 .. method:: str.find(sub[, start[, end]])
 
    Return the lowest index in the string where substring *sub* is found within
-   the slice ``s[start:end]``.  Optional arguments *start* and *end* are
-   interpreted as in slice notation.  Return ``-1`` if *sub* is not found.
+   the slice ``s[start:end]``.  *sub* can also be a tuple of substrings to look
+   for.  In this case the returned index, if found, will be the index of the
+   first match.  Optional arguments *start* and *end* are interpreted as in
+   slice notation.  Return ``-1`` if *sub* is not found.
+
+   .. seealso::
+      The :mod:`re` module, which provides advanced pattern matching.
 
    .. note::
 
@@ -1736,6 +1741,9 @@ expression support in the :mod:`re` module).
          >>> 'Py' in 'Python'
          True
 
+   .. versionchanged:: 3.14
+      *sub* can now be a tuple of substrings.
+
 
 .. method:: str.format(*args, **kwargs)
 
@@ -1789,6 +1797,9 @@ expression support in the :mod:`re` module).
    Like :meth:`~str.find`, but raise :exc:`ValueError` when the substring is
    not found.
 
+   .. versionchanged:: 3.14
+      *sub* can now be a tuple of substrings.
+
 
 .. method:: str.isalnum()
 
@@ -2030,15 +2041,26 @@ expression support in the :mod:`re` module).
 .. method:: str.rfind(sub[, start[, end]])
 
    Return the highest index in the string where substring *sub* is found, such
-   that *sub* is contained within ``s[start:end]``.  Optional arguments *start*
-   and *end* are interpreted as in slice notation.  Return ``-1`` on failure.
+   that *sub* is contained within ``s[start:end]``.  *sub* can also be a tuple
+   of substrings to look for.  In this case the returned index, if found, will
+   be the index of the last match.  Optional arguments *start* and *end* are
+   interpreted as in slice notation.  Return ``-1`` on failure.
+
+   .. seealso::
+      The third-party :pypi:`regex` module, which provides advanced pattern matching.
+
+   .. versionchanged:: 3.14
+      *sub* can now be a tuple of substrings.
 
 
 .. method:: str.rindex(sub[, start[, end]])
 
    Like :meth:`rfind` but raises :exc:`ValueError` when the substring *sub* is not
    found.
 
+   .. versionchanged:: 3.14
+      *sub* can now be a tuple of substrings.
+
 
 .. method:: str.rjust(width[, fillchar])
 
@@ -2859,13 +2881,18 @@ arbitrary binary data.
             bytearray.find(sub[, start[, end]])
 
    Return the lowest index in the data where the subsequence *sub* is found,
-   such that *sub* is contained in the slice ``s[start:end]``.  Optional
-   arguments *start* and *end* are interpreted as in slice notation.  Return
-   ``-1`` if *sub* is not found.
+   such that *sub* is contained in the slice ``s[start:end]``.  *sub* can
+   also be a tuple of subsequences to look for.  In this case the returned
+   index, if found, will be the index of the first match.  Optional arguments
+   *start* and *end* are interpreted as in slice notation.  Return ``-1`` if
+   *sub* is not found.
 
    The subsequence to search for may be any :term:`bytes-like object` or an
    integer in the range 0 to 255.
 
+   .. seealso::
+      The :mod:`re` module, which provides advanced pattern matching.
+
    .. note::
 
       The :meth:`~bytes.find` method should be used only if you need to know the
@@ -2878,6 +2905,9 @@ arbitrary binary data.
    .. versionchanged:: 3.3
       Also accept an integer in the range 0 to 255 as the subsequence.
 
+   .. versionchanged:: 3.14
+      *sub* can now be a tuple of subsequences.
+
 
 .. method:: bytes.index(sub[, start[, end]])
             bytearray.index(sub[, start[, end]])
@@ -2891,6 +2921,9 @@ arbitrary binary data.
    .. versionchanged:: 3.3
       Also accept an integer in the range 0 to 255 as the subsequence.
 
+   .. versionchanged:: 3.14
+      *sub* can now be a tuple of subsequences.
+
 
 .. method:: bytes.join(iterable)
             bytearray.join(iterable)
@@ -2947,16 +2980,24 @@ arbitrary binary data.
             bytearray.rfind(sub[, start[, end]])
 
    Return the highest index in the sequence where the subsequence *sub* is
-   found, such that *sub* is contained within ``s[start:end]``.  Optional
-   arguments *start* and *end* are interpreted as in slice notation. Return
-   ``-1`` on failure.
+   found, such that *sub* is contained within ``s[start:end]``.  *sub* can
+   also be a tuple of subsequences to look for.  In this case the returned
+   index, if found, will be the index of the last match.  Optional arguments
+   *start* and *end* are interpreted as in slice notation.  Return ``-1`` on
+   failure.
 
    The subsequence to search for may be any :term:`bytes-like object` or an
    integer in the range 0 to 255.
 
+   .. seealso::
+      The third-party :pypi:`regex` module, which provides advanced pattern matching.
+
    .. versionchanged:: 3.3
       Also accept an integer in the range 0 to 255 as the subsequence.
 
+   .. versionchanged:: 3.14
+      *sub* can now be a tuple of subsequences.
+
 
 .. method:: bytes.rindex(sub[, start[, end]])
             bytearray.rindex(sub[, start[, end]])
@@ -2970,6 +3011,9 @@ arbitrary binary data.
    .. versionchanged:: 3.3
       Also accept an integer in the range 0 to 255 as the subsequence.
 
+   .. versionchanged:: 3.14
+      *sub* can now be a tuple of subsequences.
+
 
 .. method:: bytes.rpartition(sep)
             bytearray.rpartition(sep)

Lib/test/string_tests.py

@@ -180,8 +180,10 @@ def test_find(self):
 
         if self.contains_bytes:
             self.checkequal(-1, 'hello', 'find', 42)
+            self.checkequal(-1, 'hello', 'find', (42,))
         else:
             self.checkraises(TypeError, 'hello', 'find', 42)
+            self.checkraises(TypeError, 'hello', 'find', (42,))
 
         self.checkequal(0, '', 'find', '')
         self.checkequal(-1, '', 'find', '', 1, 1)
@@ -217,6 +219,33 @@ def test_find(self):
                 if loc != -1:
                     self.assertEqual(i[loc:loc+len(j)], j)
 
+        # test tuple arguments
+        N = 1000  # FIND_CHUNK_SIZE
+        self.checkequal(0, 'foo', 'find', ('foo',))
+        self.checkequal(-1, 'foo', 'find', ('bar',))
+        self.checkequal(2, '__aa__bb__', 'find', ('aa', 'bb'))
+        self.checkequal(2, '__aa__bb__', 'find', ('bb', 'aa'))
+        self.checkequal(-1, '__aa__bb__', 'find', ('cc', 'dd'))
+        self.checkequal(-1, '__aa__bb__', 'find', ())
+        self.checkequal(6, '__aa__bb__', 'find', ('aa', 'bb'), 3)
+        self.checkequal(-1, '__aa__bb__', 'find', ('aa', 'cc'), 3)
+        self.checkequal(2, '__aa__bb__', 'find', ('aa', 'bb'), 0, 10)
+        self.checkequal(-1, '__aa__bb__', 'find', ('aa', 'bb'), 0, 3)
+        self.checkequal(2, '__aa__bb__', 'find', ('aa', 'bb'), 0, 4)
+        self.checkraises(TypeError, 'hello', 'find', (None,))
+        s = '_' * (N - 2) + 'aaaa' + '_' * (N - 2)
+        self.checkequal((N - 2), s, 'find', ('aaaa', 'bb'))
+        self.checkequal(2, 'foobar', 'find', ('ob', 'oba'))
+        self.checkequal(1, 'foobar', 'find', ('ob', 'oob'))
+        self.checkequal(0, '', 'find', ('', '_'))
+        self.checkequal(2, '__abcd__', 'find', ('cd', 'ab'))
+        self.checkequal(2, '__abc__', 'find', ('bc', 'ab'))
+        self.checkequal(1, 'a' + 'b' * N, 'find', ('b' * N, 'c'))
+        s = 'ab' + 'c' * (10 * N)
+        self.checkequal(1, s, 'find', ('c' * (10 * N), 'b' + 'c' * (10 * N)))
+        self.checkequal(0, 'foobar', 'find', ('foo', 'bar'))
+        self.checkequal(-1, 'foo', 'find', ('foobar',))
+
     def test_rfind(self):
         self.checkequal(9,  'abcdefghiabc', 'rfind', 'abc')
         self.checkequal(12, 'abcdefghiabc', 'rfind', '')
@@ -238,8 +267,10 @@ def test_rfind(self):
 
         if self.contains_bytes:
             self.checkequal(-1, 'hello', 'rfind', 42)
+            self.checkequal(-1, 'hello', 'rfind', (42,))
         else:
             self.checkraises(TypeError, 'hello', 'rfind', 42)
+            self.checkraises(TypeError, 'hello', 'rfind', (42,))
 
         # For a variety of combinations,
         #    verify that str.rfind() matches __contains__
@@ -270,6 +301,32 @@ def test_rfind(self):
         # issue #15534
         self.checkequal(0, '<......\u043c...', "rfind", "<")
 
+        # test tuple arguments
+        N = 1000  # RFIND_CHUNK_SIZE
+        self.checkequal(0, 'foo', 'rfind', ('foo',))
+        self.checkequal(-1, 'foo', 'rfind', ('bar',))
+        self.checkequal(6, '__aa__bb__', 'rfind', ('aa', 'bb'))
+        self.checkequal(6, '__aa__bb__', 'rfind', ('bb', 'aa'))
+        self.checkequal(-1, '__aa__bb__', 'rfind', ('cc', 'dd'))
+        self.checkequal(-1, '__aa__bb__', 'rfind', ())
+        self.checkequal(-1, '__aa__bb__', 'rfind', ('aa', 'cc'), 3)
+        self.checkequal(6, '__aa__bb__', 'rfind', ('aa', 'bb'), 0, 10)
+        self.checkequal(-1, '__aa__bb__', 'rfind', ('aa', 'bb'), 7, 10)
+        self.checkequal(6, '__aa__bb__', 'rfind', ('aa', 'bb'), 6, 10)
+        self.checkraises(TypeError, 'hello', 'rfind', (None,))
+        s = '_' * (N - 2) + 'aaaa' + '_' * (N - 2)
+        self.checkequal((N - 2), s, 'rfind', ('aaaa', 'bb'))
+        self.checkequal(2, 'foobar', 'rfind', ('oba', 'ob'))
+        self.checkequal(2, 'foobar', 'rfind', ('oob', 'ob'))
+        self.checkequal(1, '_', 'rfind', ('', 'a'))
+        self.checkequal(4, '__abcd__', 'rfind', ('ab', 'cd'))
+        self.checkequal(3, '__abc__', 'rfind', ('ab', 'bc'))
+        self.checkequal(0, 'b' * N + 'a', 'rfind', ('b' * N, 'c'))
+        s = 'ab' + 'c' * (10 * N)
+        self.checkequal(2, s, 'rfind', ('c' * (10 * N), 'b' + 'c' * (10 * N)))
+        self.checkequal(3, 'foo', 'rfind', ('', 'foo'))
+        self.checkequal(-1, 'foo', 'rfind', ('foobar',))
+
     def test_index(self):
         self.checkequal(0, 'abcdefghiabc', 'index', '')
         self.checkequal(3, 'abcdefghiabc', 'index', 'def')
@@ -295,6 +352,11 @@ def test_index(self):
         else:
             self.checkraises(TypeError, 'hello', 'index', 42)
 
+        # test tuple arguments (should be wrapper around find)
+        self.checkequal(2, '__aa__bb__', 'index', ('aa', 'bb'))
+        self.checkequal(2, '__aa__bb__', 'index', ('aa', 'bb'))
+        self.checkraises(ValueError, '__aa__bb__', 'index', ('cc', 'dd'))
+
     def test_rindex(self):
         self.checkequal(12, 'abcdefghiabc', 'rindex', '')
         self.checkequal(3,  'abcdefghiabc', 'rindex', 'def')
@@ -321,6 +383,11 @@ def test_rindex(self):
         else:
             self.checkraises(TypeError, 'hello', 'rindex', 42)
 
+        # test tuple arguments (should be wrapper around rfind)
+        self.checkequal(6, '__aa__bb__', 'rindex', ('aa', 'bb'))
+        self.checkequal(6, '__aa__bb__', 'rindex', ('bb', 'aa'))
+        self.checkraises(ValueError, '__aa__bb__', 'rindex', ('cc', 'dd'))
+
     def test_find_periodic_pattern(self):
         """Cover the special path for periodic patterns."""
         def reference_find(p, s):

Lib/test/test_bytes.py

@@ -644,6 +644,12 @@ def test_find(self):
                 ValueError, r'byte must be in range\(0, 256\)',
                 b.find, index)
 
+        # test tuple arguments
+        self.assertEqual(b.find((i,)), 1)
+        self.assertEqual(b.find((w,)), -1)
+        self.assertEqual(b.find((i, w)), 1)
+        self.assertEqual(b.find((w, i)), 1)
+
     def test_rfind(self):
         b = self.type2test(b'mississippi')
         i = 105
@@ -663,6 +669,12 @@ def test_rfind(self):
         self.assertEqual(b.rfind(i, 3, 9), 7)
         self.assertEqual(b.rfind(w, 1, 3), -1)
 
+        # test tuple arguments
+        self.assertEqual(b.rfind((i,)), 10)
+        self.assertEqual(b.rfind((w,)), -1)
+        self.assertEqual(b.rfind((i, w)), 10)
+        self.assertEqual(b.rfind((w, i)), 10)
+
     def test_index(self):
         b = self.type2test(b'mississippi')
         i = 105

Lib/test/test_inspect/test_inspect.py

@@ -5414,7 +5414,7 @@ def test_builtins_have_signatures(self):
             'dict': {'pop'},
             'int': {'__round__'},
             'memoryview': {'cast', 'hex'},
-            'str': {'count', 'endswith', 'find', 'index', 'maketrans', 'rfind', 'rindex', 'startswith'},
+            'str': {'count', 'endswith', 'maketrans', 'startswith'},
         }
         self._test_module_has_signatures(builtins,
                 no_signature, unsupported_signature,
@@ -5589,7 +5589,7 @@ def test_typing_module_has_signatures(self):
             'Generic': {'__class_getitem__', '__init_subclass__'},
         }
         methods_unsupported_signature = {
-            'Text': {'count', 'find', 'index', 'rfind', 'rindex', 'startswith', 'endswith', 'maketrans'},
+            'Text': {'count', 'startswith', 'endswith', 'maketrans'},
         }
         self._test_module_has_signatures(typing, no_signature,
                 methods_no_signature=methods_no_signature,

Misc/NEWS.d/next/Core and Builtins/2024-05-24-11-07-16.gh-issue-118184.EK4di_.rst

@@ -0,0 +1 @@
+Support tuples for :class:`str`, :class:`bytes` and :class:`bytearray` methods ``find()``, ``index()``, ``rfind()`` and ``rindex()``.