4.2.5 Match Objects
MatchObject instances support the following methods and attributes:
- Return the string obtained by doing backslash substitution on the template string template, as done by the sub() method. Escapes such as "\n" are converted to the appropriate characters, and numeric backreferences ("\1", "\2") and named backreferences ("\g<1>", "\g<name>") are replaced by the contents of the corresponding group.
-
Returns one or more subgroups of the match. If there is a single
argument, the result is a single string; if there are
multiple arguments, the result is a tuple with one item per argument.
Without arguments, group1 defaults to zero (the whole match
is returned).
If a groupN argument is zero, the corresponding return value is the
entire matching string; if it is in the inclusive range [1..99], it is
the string matching the corresponding parenthesized group. If a
group number is negative or larger than the number of groups defined
in the pattern, an IndexError exception is raised.
If a group is contained in a part of the pattern that did not match,
the corresponding result is
None
. If a group is contained in a part of the pattern that matched multiple times, the last match is returned.If the regular expression uses the (?P<name>...) syntax, the groupN arguments may also be strings identifying groups by their group name. If a string argument is not used as a group name in the pattern, an IndexError exception is raised.
A moderately complicated example:
m = re.match(r"(?P<int>\d+)\.(\d*)", '3.14')
After performing this match,
m.group(1)
is'3'
, as ism.group('int')
, andm.group(2)
is'14'
.
-
Return a tuple containing all the subgroups of the match, from 1 up to
however many groups are in the pattern. The default argument is
used for groups that did not participate in the match; it defaults to
None
. (Incompatibility note: in the original Python 1.5 release, if the tuple was one element long, a string would be returned instead. In later versions (from 1.5.1 on), a singleton tuple is returned in such cases.)
-
Return a dictionary containing all the named subgroups of the
match, keyed by the subgroup name. The default argument is
used for groups that did not participate in the match; it defaults to
None
.
- Return the indices of the start and end of the substring
matched by group; group defaults to zero (meaning the whole
matched substring).
Return
-1
if group exists but did not contribute to the match. For a match object m, and a group g that did contribute to the match, the substring matched by group g (equivalent tom.group(g)
) ism.string[m.start(g):m.end(g)]
Note that
m.start(group)
will equalm.end(group)
if group matched a null string. For example, afterm = re.search('b(c?)', 'cba')
,m.start(0)
is 1,m.end(0)
is 2,m.start(1)
andm.end(1)
are both 2, andm.start(2)
raises an IndexError exception.
-
For MatchObject m, return the 2-tuple
(m.start(group), m.end(group))
. Note that if group did not contribute to the match, this is(-1, -1)
. Again, group defaults to zero.
- The value of pos which was passed to the search() or match() method of the RegexObject. This is the index into the string at which the RE engine started looking for a match.
- The value of endpos which was passed to the search() or match() method of the RegexObject. This is the index into the string beyond which the RE engine will not go.
-
The integer index of the last matched capturing group, or
None
if no group was matched at all. For example, the expressions (a)b, ((a)(b)), and ((ab)) will havelastindex == 1
if applyied to the string'ab'
, while the expression (a)(b) will havelastindex == 2
, if applyied to the same string.
-
The name of the last matched capturing group, or
None
if the group didn't have a name, or if no group was matched at all.
- The regular expression object whose match() or search() method produced this MatchObject instance.
- The string passed to match() or search().
See About this document... for information on suggesting changes.