4.2.5 Match Objects

MatchObject instances support the following methods and
attributes:

expand(

template)

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.

group(

[group1, ...])

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 is
m.group('int'), and m.group(2) is '14'.

groups(

[default])

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.)

groupdict(

[default])

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.

start(

[group])

end(

[group])

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 to
m.group(g)) is

m.string[m.start(g):m.end(g)]

Note that
m.start(group) will equal m.end(group) if
group matched a null string. For example, after m =
re.search('b(c?)', 'cba'), m.start(0) is 1,
m.end(0) is 2, m.start(1) and
m.end(1) are both 2, and m.start(2) raises
an IndexError exception.

span(

[group])

For MatchObjectm, 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.

pos

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.

endpos

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.

lastindex

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 have
lastindex == 1 if applyied to the string 'ab',
while the expression (a)(b) will have lastindex == 2,
if applyied to the same string.

lastgroup

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.

re

The regular expression object whose match() or
search() method produced this MatchObject instance.