[Python-checkins] bpo-44940: Clarify the documentation of re.findall() (GH-27849)
webhook-mailer at python.org
Sun Aug 22 03:45:13 EDT 2021
author: Miss Islington (bot) <31488909+miss-islington at users.noreply.github.com>
committer: miss-islington <31488909+miss-islington at users.noreply.github.com>
bpo-44940: Clarify the documentation of re.findall() (GH-27849)
Co-authored-by: Ken Jin <28750310+Fidget-Spinner at users.noreply.github.com>
Co-authored-by: Vedran Čačić <vedgar+github at gmail.com>
(cherry picked from commit 64f9e7b19dc1603fcbd07c17c9860085b9d21465)
Co-authored-by: Serhiy Storchaka <storchaka at gmail.com>
diff --git a/Doc/library/re.rst b/Doc/library/re.rst
index 950012a9b0fe2..ff7687cc936ec 100644
@@ -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.
More information about the Python-checkins