4.2.5 Match Objects
Keywords: lib

##
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 (i.e. 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 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 `-1`. 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 `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.

`pos`
  The value of pos which was passed to the `search()` or `match()` function. This is the index into the string at which the regex engine started looking for a match.

`endpos`
  The value of endpos which was passed to the `search()` or `match()` function. This is the index into the string beyond which the regex engine will not go.

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

`string`
  The string passed to `match()` or `search()`.

See Also:

Jeffrey Friedl, Mastering Regular Expressions, O'Reilly. The Python material in this book dates from before the `re` module, but it covers writing good regular expression patterns in great detail.