Terry J. Reedy <tjre...@udel.edu> added the comment:
After reading Serhiy's clarification of the old and wonky findall return api, I
agree that reusing it in an unneeded new function would be a retrograde move.
We should instead upgrade the documentation of the more flexible current
functions.
For search, give these examples of common uses:
search(...)[0] # Get entire matched string.
search(...)[1] # Get first captured group string.
search(...).groups() # Get tuple of captured group strings.
Note that the first two (unlike findfirst) may be used even when there are
1/many groups. If one has a pattern with multiple groups, one might want
different return values for different applications of the pattern. Or one may
add a group to a pattern to use as a backreference in the matching process, not
to mark the substring one want to see.
For find: list and explain finditer ***first***. Then list and explain findall
as the old less-flexible list interface, kept for back compatibility, that is
equivalent to one of the following, depending on whether the pattern has 0, 1,
or multiple groups.
[m[0] for m in finditer(...)] # List of full-match strings.
[m[1] for m in finditer(...)] # List of captured strings.
[m.groups() for m in finditer(...)] # List of tuples of strings.
To me, the above is clearer than "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." The first clause implies tuples even with one group;
the second denies that. One must infer that for one group, the match is
extracted from the tuple.
Again, using finditer is more flexible than using findall in that the return,
which limited by the number of groups, is not determined by it.
Given that each function is documented twice, as method and combined module
function, where should the expanded explanation go? Currently, expanded
explanations of search, match, and fullmatch are on the methods, which the same
for split, sub, and escape are on the functions. Instead, all should go on
whichever set of listings is first.
I think https://docs.python.org/3/library/re.html#module-contents should be
split in two sections: re.compile and compile flags; combined compile + method
functions. Then consider moving the functions below the method listings (and
move explanations of all functions that are methods to the methods. Or maybe
interleave the methods and functions.
----------
_______________________________________
Python tracker <rep...@bugs.python.org>
<https://bugs.python.org/issue39165>
_______________________________________
_______________________________________________
Python-bugs-list mailing list
Unsubscribe:
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
