This issue tracker has been migrated to GitHub, and is currently read-only.
For more information, see the GitHub FAQs in the Python's Developer Guide.

Author terry.reedy
Recipients apalala, ezio.melotti, mrabarnett, rhettinger, serhiy.storchaka, terry.reedy
Date 2020-01-04.19:11:16
SpamBayes Score -1.0
Marked as misclassified Yes
Message-id <1578165077.49.0.426229289188.issue39165@roundup.psfhosted.org>
In-reply-to
Content
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.
History
Date User Action Args
2020-01-04 19:11:17terry.reedysetrecipients: + terry.reedy, rhettinger, ezio.melotti, mrabarnett, serhiy.storchaka, apalala
2020-01-04 19:11:17terry.reedysetmessageid: <1578165077.49.0.426229289188.issue39165@roundup.psfhosted.org>
2020-01-04 19:11:17terry.reedylinkissue39165 messages
2020-01-04 19:11:17terry.reedycreate