re module documentation on search/match is unclear

[richardb]

BPO	1625381
Nosy	@freddrake, @birkenfeld

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = 'https://github.com/freddrake'
closed_at = <Date 2007-08-23.21:36:17.560>
created_at = <Date 2006-12-31.16:42:04.000>
labels = ['docs']
title = 're module documentation on search/match is unclear'
updated_at = <Date 2007-08-23.21:36:17.558>
user = 'https://bugs.python.org/richardb'

bugs.python.org fields:

activity = <Date 2007-08-23.21:36:17.558>
actor = 'georg.brandl'
assignee = 'fdrake'
closed = True
closed_date = <Date 2007-08-23.21:36:17.560>
closer = 'georg.brandl'
components = ['Documentation']
creation = <Date 2006-12-31.16:42:04.000>
creator = 'richardb'
dependencies = []
files = []
hgrepos = []
issue_num = 1625381
keywords = []
message_count = 3.0
messages = ['30885', '30886', '55223']
nosy_count = 4.0
nosy_names = ['fdrake', 'georg.brandl', 'collinwinter', 'richardb']
pr_nums = []
priority = 'normal'
resolution = 'fixed'
stage = None
status = 'closed'
superseder = None
type = None
url = 'https://bugs.python.org/issue1625381'
versions = []

[richardb]

Section 4.2.2 ("Matching vs Searching") of the Python Library Reference covers the match and search methods of regular expression objects. However, it doesn't begin by describing the difference between these methods. Each time I try to remember which way round match and search are, it takes several minutes of checking the documentation to work out which is which. I suggest that the first paragraph of the section is replaced with the following text (in two paragraphs), to make the distinction between the methods clearer:

"Python offers two different primitive operations based on regular expressions: match and search. match() checks for a match at the beginning of the search string, whereas search() checks for a match anywhere in the string.

If you want something equivalent to Perl's semantics, the search operation is what you're looking for. See the search() function and corresponding method of compiled regular expression objects."

[collinwinter]

+1 on the general idea, though I'd change your "match() checks for a match at the beginning..." to "match() checks for a match starting at the beginning...". I'd also like to drop the reference to Perl entirely; saying that I should look to search() for Perl's semantics makes it sound like match() doesn't support PCREs.

Fred, any thoughts?

[birkenfeld]

Clarified in rev. 57354.