bpo-44940: Clarify the documentation of re.findall() (GH-27849) (GH-27880)

Co-authored-by: Ken Jin <28750310+Fidget-Spinner@users.noreply.github.com>
Co-authored-by: Vedran Čačić <vedgar+github@gmail.com>
(cherry picked from commit 64f9e7b19dc1603fcbd07c17c9860085b9d21465)

Co-authored-by: Serhiy Storchaka <storchaka@gmail.com>

1 files changed, 14 insertions, 4 deletions

diff --git a/Doc/library/re.rst b/Doc/library/re.rst
index 950012a..ff7687c 100644
--- a/Doc/library/re.rst
+++ b/Doc/library/re.rst
@@ -824,10 +824,20 @@ form.
 .. function:: findall(pattern, string, flags=0)
 
    Return all non-overlapping matches of *pattern* in *string*, as a list of
-   strings.  The *string* is scanned left-to-right, and matches are returned in
-   the order found.  If one or more groups are present in the pattern, return a
-   list of groups; this will be a list of tuples if the pattern has more than
-   one group.  Empty matches are included in the result.
+   strings or tuples.  The *string* is scanned left-to-right, and matches
+   are returned in the order found.  Empty matches are included in the result.
+
+   The result depends on the number of capturing groups in the pattern.
+   If there are no groups, return a list of strings matching the whole
+   pattern.  If there is exactly one group, return a list of strings
+   matching that group.  If multiple groups are present, return a list
+   of tuples of strings matching the groups.  Non-capturing groups do not
+   affect the form of the result.
+
+      >>> re.findall(r'\bf[a-z]*', 'which foot or hand fell fastest')
+      ['foot', 'fell', 'fastest']
+      >>> re.findall(r'(\w+)=(\d+)', 'set width=20 and height=10')
+      [('width', '20'), ('height', '10')]
 
    .. versionchanged:: 3.7
       Non-empty matches can now start just after a previous empty match.