From 64f9e7b19dc1603fcbd07c17c9860085b9d21465 Mon Sep 17 00:00:00 2001 From: Serhiy Storchaka Date: Sun, 22 Aug 2021 10:24:20 +0300 Subject: bpo-44940: Clarify the documentation of re.findall() (GH-27849) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Ken Jin <28750310+Fidget-Spinner@users.noreply.github.com> Co-authored-by: Vedran Čačić --- Doc/library/re.rst | 18 ++++++++++++++---- 1 file 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. -- cgit v0.12