<!DOCTYPE html PUBLIC
"-//W3C//DTD HTML 4.0 Transitional//EN">
<link rel=
"STYLESHEET" href=
"lib.css" type='text/css'
/>
<link rel=
"SHORTCUT ICON" href=
"../icons/pyfav.png" type=
"image/png" />
<link rel='start' href='../index.html' title='Python Documentation Index'
/>
<link rel=
"first" href=
"lib.html" title='Python Library Reference'
/>
<link rel='contents' href='contents.html'
title=
"Contents" />
<link rel='index' href='genindex.html' title='Index'
/>
<link rel='last' href='about.html' title='About this document...'
/>
<link rel='help' href='about.html' title='About this document...'
/>
<link rel=
"next" href=
"node118.html" />
<link rel=
"prev" href=
"re-objects.html" />
<link rel=
"parent" href=
"module-re.html" />
<link rel=
"next" href=
"node118.html" />
<meta name='aesop' content='information'
/>
<title>4.2.5 Match Objects
</title>
<div id='top-navigation-panel' xml:id='top-navigation-panel'
>
<table align=
"center" width=
"100%" cellpadding=
"0" cellspacing=
"2">
<td class='online-navigation'
><a rel=
"prev" title=
"4.2.4 Regular Expression Objects"
href=
"re-objects.html"><img src='../icons/previous.png'
border='
0' height='
32' alt='Previous Page' width='
32'
/></A></td>
<td class='online-navigation'
><a rel=
"parent" title=
"4.2 re "
href=
"module-re.html"><img src='../icons/up.png'
border='
0' height='
32' alt='Up One Level' width='
32'
/></A></td>
<td class='online-navigation'
><a rel=
"next" title=
"4.2.6 Examples"
href=
"node118.html"><img src='../icons/next.png'
border='
0' height='
32' alt='Next Page' width='
32'
/></A></td>
<td align=
"center" width=
"100%">Python Library Reference
</td>
<td class='online-navigation'
><a rel=
"contents" title=
"Table of Contents"
href=
"contents.html"><img src='../icons/contents.png'
border='
0' height='
32' alt='Contents' width='
32'
/></A></td>
<td class='online-navigation'
><a href=
"modindex.html" title=
"Module Index"><img src='../icons/modules.png'
border='
0' height='
32' alt='Module Index' width='
32'
/></a></td>
<td class='online-navigation'
><a rel=
"index" title=
"Index"
href=
"genindex.html"><img src='../icons/index.png'
border='
0' height='
32' alt='Index' width='
32'
/></A></td>
<div class='online-navigation'
>
<b class=
"navlabel">Previous:
</b>
<a class=
"sectref" rel=
"prev" href=
"re-objects.html">4.2.4 Regular Expression Objects
</A>
<b class=
"navlabel">Up:
</b>
<a class=
"sectref" rel=
"parent" href=
"module-re.html">4.2 re
</A>
<b class=
"navlabel">Next:
</b>
<a class=
"sectref" rel=
"next" href=
"node118.html">4.2.6 Examples
</A>
<!--End of Navigation Panel-->
<H2><A NAME=
"SECTION006250000000000000000"></A><A NAME=
"match-objects"></A>
<tt class=
"class">MatchObject
</tt> instances support the following methods and
<dl><dt><table cellpadding=
"0" cellspacing=
"0"><tr valign=
"baseline">
<td><nobr><b><tt id='l2h-
901' xml:id='l2h-
901'
class=
"method">expand
</tt></b>(
</nobr></td>
<td><var>template
</var>)
</td></tr></table></dt>
Return the string obtained by doing backslash substitution on the
template string
<var>template
</var>, as done by the
<tt class=
"method">sub()
</tt> method.
Escapes such as
"<tt class="samp
">\n</tt>" are converted to the appropriate
characters, and numeric backreferences (
"<tt class="samp
">\1</tt>",
"<tt class="samp
">\2</tt>") and
named backreferences (
"<tt class="samp
">\g<1></tt>",
"<tt class="samp
">\g<name></tt>") are replaced
by the contents of the corresponding group.
<dl><dt><table cellpadding=
"0" cellspacing=
"0"><tr valign=
"baseline">
<td><nobr><b><tt id='l2h-
902' xml:id='l2h-
902'
class=
"method">group
</tt></b>(
</nobr></td>
<td><var></var><big>[
</big><var>group1, ...
</var><big>]
</big><var></var>)
</td></tr></table></dt>
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,
<var>group1
</var> defaults to zero (the whole match
If a
<var>groupN
</var> 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
<tt class=
"exception">IndexError
</tt> exception is raised.
If a group is contained in a part of the pattern that did not match,
the corresponding result is
<code>None
</code>. If a group is contained in a
part of the pattern that matched multiple times, the last match is
If the regular expression uses the
<tt class=
"regexp">(?P
<<var>name
</var>>...)
</tt> syntax,
the
<var>groupN
</var> 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
<tt class=
"exception">IndexError
</tt> exception is raised.
A moderately complicated example:
<div class=
"verbatim"><pre>
m = re.match(r
"(?P<int>\d+)\.(\d*)", '
3.14')
After performing this match,
<code>m.group(
1)
</code> is
<code>'
3'
</code>, as is
<code>m.group('int')
</code>, and
<code>m.group(
2)
</code> is
<code>'
14'
</code>.
<dl><dt><table cellpadding=
"0" cellspacing=
"0"><tr valign=
"baseline">
<td><nobr><b><tt id='l2h-
903' xml:id='l2h-
903'
class=
"method">groups
</tt></b>(
</nobr></td>
<td><var></var><big>[
</big><var>default
</var><big>]
</big><var></var>)
</td></tr></table></dt>
Return a tuple containing all the subgroups of the match, from
1 up to
however many groups are in the pattern. The
<var>default
</var> argument is
used for groups that did not participate in the match; it defaults to
<code>None
</code>. (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
<dl><dt><table cellpadding=
"0" cellspacing=
"0"><tr valign=
"baseline">
<td><nobr><b><tt id='l2h-
904' xml:id='l2h-
904'
class=
"method">groupdict
</tt></b>(
</nobr></td>
<td><var></var><big>[
</big><var>default
</var><big>]
</big><var></var>)
</td></tr></table></dt>
Return a dictionary containing all the
<em>named
</em> subgroups of the
match, keyed by the subgroup name. The
<var>default
</var> argument is
used for groups that did not participate in the match; it defaults to
<dl><dt><table cellpadding=
"0" cellspacing=
"0"><tr valign=
"baseline">
<td><nobr><b><tt id='l2h-
905' xml:id='l2h-
905'
class=
"method">start
</tt></b>(
</nobr></td>
<td><var></var><big>[
</big><var>group
</var><big>]
</big><var></var>)
</td></tr></table></dt>
<dt><table cellpadding=
"0" cellspacing=
"0"><tr valign=
"baseline">
<td><nobr><b><tt id='l2h-
906' xml:id='l2h-
906'
class=
"method">end
</tt></b>(
</nobr></td>
<td><var></var><big>[
</big><var>group
</var><big>]
</big><var></var>)
</td></tr></table></dt>
<dd>Return the indices of the start and end of the substring
matched by
<var>group
</var>;
<var>group
</var> defaults to zero (meaning the whole
Return
<code>-
1</code> if
<var>group
</var> exists but
did not contribute to the match. For a match object
<var>m
</var>, and a group
<var>g
</var> that did contribute to the match, the
substring matched by group
<var>g
</var> (equivalent to
<code><var>m
</var>.group(
<var>g
</var>)
</code>) is
<div class=
"verbatim"><pre>
m.string[m.start(g):m.end(g)]
<code>m.start(
<var>group
</var>)
</code> will equal
<code>m.end(
<var>group
</var>)
</code> if
<var>group
</var> matched a null string. For example, after
<code><var>m
</var> =
re.search('b(c?)', 'cba')
</code>,
<code><var>m
</var>.start(
0)
</code> is
1,
<code><var>m
</var>.end(
0)
</code> is
2,
<code><var>m
</var>.start(
1)
</code> and
<code><var>m
</var>.end(
1)
</code> are both
2, and
<code><var>m
</var>.start(
2)
</code> raises
an
<tt class=
"exception">IndexError
</tt> exception.
<dl><dt><table cellpadding=
"0" cellspacing=
"0"><tr valign=
"baseline">
<td><nobr><b><tt id='l2h-
907' xml:id='l2h-
907'
class=
"method">span
</tt></b>(
</nobr></td>
<td><var></var><big>[
</big><var>group
</var><big>]
</big><var></var>)
</td></tr></table></dt>
For
<tt class=
"class">MatchObject
</tt> <var>m
</var>, return the
2-tuple
<code>(
<var>m
</var>.start(
<var>group
</var>),
<var>m
</var>.end(
<var>group
</var>))
</code>.
Note that if
<var>group
</var> did not contribute to the match, this is
<code>(-
1, -
1)
</code>. Again,
<var>group
</var> defaults to zero.
<dl><dt><b><tt id='l2h-
908' xml:id='l2h-
908'
class=
"member">pos
</tt></b></dt>
The value of
<var>pos
</var> which was passed to the
<tt class=
"function">search()
</tt> or
<tt class=
"function">match()
</tt> method of the
<tt class=
"class">RegexObject
</tt>. This is the
index into the string at which the RE engine started looking for a
<dl><dt><b><tt id='l2h-
909' xml:id='l2h-
909'
class=
"member">endpos
</tt></b></dt>
The value of
<var>endpos
</var> which was passed to the
<tt class=
"function">search()
</tt>
or
<tt class=
"function">match()
</tt> method of the
<tt class=
"class">RegexObject
</tt>. This is the
index into the string beyond which the RE engine will not go.
<dl><dt><b><tt id='l2h-
910' xml:id='l2h-
910'
class=
"member">lastindex
</tt></b></dt>
The integer index of the last matched capturing group, or
<code>None
</code>
if no group was matched at all. For example, the expressions
<tt class=
"regexp">(a)b
</tt>,
<tt class=
"regexp">((a)(b))
</tt>, and
<tt class=
"regexp">((ab))
</tt> will have
<code>lastindex ==
1</code> if applied to the string
<code>'ab'
</code>,
while the expression
<tt class=
"regexp">(a)(b)
</tt> will have
<code>lastindex ==
2</code>,
if applied to the same string.
<dl><dt><b><tt id='l2h-
911' xml:id='l2h-
911'
class=
"member">lastgroup
</tt></b></dt>
The name of the last matched capturing group, or
<code>None
</code> if the
group didn't have a name, or if no group was matched at all.
<dl><dt><b><tt id='l2h-
912' xml:id='l2h-
912'
class=
"member">re
</tt></b></dt>
The regular expression object whose
<tt class=
"method">match()
</tt> or
<tt class=
"method">search()
</tt> method produced this
<tt class=
"class">MatchObject
</tt> instance.
<dl><dt><b><tt id='l2h-
913' xml:id='l2h-
913'
class=
"member">string
</tt></b></dt>
The string passed to
<tt class=
"function">match()
</tt> or
<tt class=
"function">search()
</tt>.
<div class='online-navigation'
>
<table align=
"center" width=
"100%" cellpadding=
"0" cellspacing=
"2">
<td class='online-navigation'
><a rel=
"prev" title=
"4.2.4 Regular Expression Objects"
href=
"re-objects.html"><img src='../icons/previous.png'
border='
0' height='
32' alt='Previous Page' width='
32'
/></A></td>
<td class='online-navigation'
><a rel=
"parent" title=
"4.2 re "
href=
"module-re.html"><img src='../icons/up.png'
border='
0' height='
32' alt='Up One Level' width='
32'
/></A></td>
<td class='online-navigation'
><a rel=
"next" title=
"4.2.6 Examples"
href=
"node118.html"><img src='../icons/next.png'
border='
0' height='
32' alt='Next Page' width='
32'
/></A></td>
<td align=
"center" width=
"100%">Python Library Reference
</td>
<td class='online-navigation'
><a rel=
"contents" title=
"Table of Contents"
href=
"contents.html"><img src='../icons/contents.png'
border='
0' height='
32' alt='Contents' width='
32'
/></A></td>
<td class='online-navigation'
><a href=
"modindex.html" title=
"Module Index"><img src='../icons/modules.png'
border='
0' height='
32' alt='Module Index' width='
32'
/></a></td>
<td class='online-navigation'
><a rel=
"index" title=
"Index"
href=
"genindex.html"><img src='../icons/index.png'
border='
0' height='
32' alt='Index' width='
32'
/></A></td>
<div class='online-navigation'
>
<b class=
"navlabel">Previous:
</b>
<a class=
"sectref" rel=
"prev" href=
"re-objects.html">4.2.4 Regular Expression Objects
</A>
<b class=
"navlabel">Up:
</b>
<a class=
"sectref" rel=
"parent" href=
"module-re.html">4.2 re
</A>
<b class=
"navlabel">Next:
</b>
<a class=
"sectref" rel=
"next" href=
"node118.html">4.2.6 Examples
</A>
<span class=
"release-info">Release
2.4.2, documentation updated on
28 September
2005.
</span>
<!--End of Navigation Panel-->
See
<i><a href=
"about.html">About this document...
</a></i> for information on suggesting changes.