In the previous tutorial in this series, you covered a lot of ground. You saw how to use re.search() to perform pattern matching with regexes in Python and learned about the many regex metacharacters and parsing flags that you can use to fine-tune your pattern-matching capabilities.
But as great as all that is, the re module has much more to offer.
In this tutorial, you’ll:
- Explore more functions, beyond
re.search(), that theremodule provides - Learn when and how to precompile a regex in Python into a regular expression object
- Discover useful things that you can do with the match object returned by the functions in the
remodule
Ready? Let’s dig in!
Free Bonus: Get a sample chapter from Python Basics: A Practical Introduction to Python 3 to see how you can go from beginner to intermediate in Python with a complete curriculum, up to date for Python 3.9.
re Module Functions
In addition to re.search(), the re module contains several other functions to help you perform regex-related tasks.
Note: You saw in the previous tutorial that re.search() can take an optional <flags> argument, which specifies flags that modify parsing behavior. All the functions shown below, with the exception of re.escape(), support the <flags> argument in the same way.
You can specify <flags> as either a positional argument or a keyword argument:
re.search(<regex>, <string>, <flags>)
re.search(<regex>, <string>, flags=<flags>)
The default for <flags> is always 0, which indicates no special modification of matching behavior. Remember from the discussion of flags in the previous tutorial that the re.UNICODE flag is always set by default.
The available regex functions in the Python re module fall into the following three categories:
- Searching functions
- Substitution functions
- Utility functions
The following sections explain these functions in more detail.
Searching Functions
Searching functions scan a search string for one or more matches of the specified regex:
| Function | Description |
|---|---|
re.search() |
Scans a string for a regex match |
re.match() |
Looks for a regex match at the beginning of a string |
re.fullmatch() |
Looks for a regex match on an entire string |
re.findall() |
Returns a list of all regex matches in a string |
re.finditer() |
Returns an iterator that yields regex matches from a string |
As you can see from the table, these functions are similar to one another. But each one tweaks the searching functionality in its own way.
re.search(<regex>, <string>, flags=0)
Scans a string for a regex match.
If you worked through the previous tutorial in this series, then you should be well familiar with this function by now. re.search(<regex>, <string>) looks for any location in <string> where <regex> matches:
>>> re.search(r'(\d+)', 'foo123bar')
<_sre.SRE_Match object; span=(3, 6), match='123'>
>>> re.search(r'[a-z]+', '123FOO456', flags=re.IGNORECASE)
<_sre.SRE_Match object; span=(3, 6), match='FOO'>
>>> print(re.search(r'\d+', 'foo.bar'))
None
The function returns a match object if it finds a match and None otherwise.
re.match(<regex>, <string>, flags=0)
Looks for a regex match at the beginning of a string.
This is identical to re.search(), except that re.search() returns a match if <regex> matches anywhere in <string>, whereas re.match() returns a match only if <regex> matches at the beginning of <string>:
>>> re.search(r'\d+', '123foobar')
<_sre.SRE_Match object; span=(0, 3), match='123'>
>>> re.search(r'\d+', 'foo123bar')
<_sre.SRE_Match object; span=(3, 6), match='123'>
>>> re.match(r'\d+', '123foobar')
<_sre.SRE_Match object; span=(0, 3), match='123'>
>>> print(re.match(r'\d+', 'foo123bar'))
None
In the above example, re.search() matches when the digits are both at the beginning of the string and in the middle, but re.match() matches only when the digits are at the beginning.
Remember from the previous tutorial in this series that if <string> contains embedded newlines, then the MULTILINE flag causes re.search() to match the caret (^) anchor metacharacter either at the beginning of <string> or at the beginning of any line contained within <string>:
1>>> s = 'foo\nbar\nbaz'
2
3>>> re.search('^foo', s)
4<_sre.SRE_Match object; span=(0, 3), match='foo'>
5>>> re.search('^bar', s, re.MULTILINE)
6<_sre.SRE_Match object; span=(4, 7), match='bar'>
The MULTILINE flag does not affect re.match() in this way:
1>>> s = 'foo\nbar\nbaz'
2
3>>> re.match('^foo', s)
4<_sre.SRE_Match object; span=(0, 3), match='foo'>
5>>> print(re.match('^bar', s, re.MULTILINE))
6None
Even with the MULTILINE flag set, re.match() will match the caret (^) anchor only at the beginning of <string>, not at the beginning of lines contained within <string>.
Note that, although it illustrates the point, the caret (^) anchor on line 3 in the above example is redundant. With re.match(), matches are essentially always anchored at the beginning of the string.
re.fullmatch(<regex>, <string>, flags=0)
Looks for a regex match on an entire string.
This is similar to re.search() and re.match(), but re.fullmatch() returns a match only if <regex> matches <string> in its entirety:
1>>> print(re.fullmatch(r'\d+', '123foo'))
2None
3>>> print(re.fullmatch(r'\d+', 'foo123'))
4None
5>>> print(re.fullmatch(r'\d+', 'foo123bar'))
6None
7>>> re.fullmatch(r'\d+', '123')
8<_sre.SRE_Match object; span=(0, 3), match='123'>
9
10>>> re.search(r'^\d+$', '123')
11<_sre.SRE_Match object; span=(0, 3), match='123'>
In the call on line 7, the search string '123' consists entirely of digits from beginning to end. So that is the only case in which re.fullmatch() returns a match.
The re.search() call on line 10, in which the \d+ regex is explicitly anchored at the start and end of the search string, is functionally equivalent.
