<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<!--Converted with LaTeX2HTML 98.2 beta6 (August 14th, 1998)
original version by:  Nikos Drakos, CBLU, University of Leeds
* revised and updated by:  Marcus Hennecke, Ross Moore, Herb Swan
* with significant contributions from:
  Jens Lippmann, Marek Rouchal, Martin Wilck and others -->
<HTML>
<HEAD>
<TITLE>4.2.3 Module Contents</TITLE>
<META NAME="description" CONTENT="4.2.3 Module Contents">
<META NAME="keywords" CONTENT="lib">
<META NAME="resource-type" CONTENT="document">
<META NAME="distribution" CONTENT="global">
<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=iso-8859-1">
<LINK REL="STYLESHEET" HREF="lib.css">
<LINK REL="next" HREF="re-objects.html">
<LINK REL="previous" HREF="matching-searching.html">
<LINK REL="up" HREF="module-re.html">
<LINK REL="next" HREF="re-objects.html">
</HEAD>
<BODY bgcolor="#ffffff">
<div class=navigation>
<table align=center width="100%" cellpadding=0 cellspacing=2>
<tr>
<td><A HREF="re-objects.html"><img width=32 height=32 align=bottom border=0 alt="next"
 src="../icons/next.gif"></A></td>
<td><A HREF="module-re.html"><img width=32 height=32 align=bottom border=0 alt="up"
 src="../icons/up.gif"></A></td>
<td><A HREF="matching-searching.html"><img width=32 height=32 align=bottom border=0 alt="previous"
 src="../icons/previous.gif"></A></td>
<td align=center bgcolor="#99CCFF" width="100%">
 <b class=title>Python Library Reference</b></td>
<td><A HREF="contents.html"><img width=32 height=32 align=bottom border=0 alt="contents"
 src="../icons/contents.gif"></A></td>
<td><a
 href="modindex.html"><img width=32 height=32 align=bottom border=0 alt="modules"
 src="../icons/modules.gif"></a></td>
<td><A HREF="genindex.html"><img width=32 height=32 align=bottom border=0 alt="index"
 src="../icons/index.gif"></A></td>
</tr></table><b class=navlabel>Next:</b> <span class=sectref><A HREF="re-objects.html">4.2.4 Regular Expression Objects</A></span>
<b class=navlabel>Up:</b> <span class=sectref><A HREF="module-re.html">4.2 re  </A></span>
<b class=navlabel>Previous:</b> <span class=sectref><A HREF="matching-searching.html">4.2.2 Matching vs. Searching</A></span>
<br><hr></div>
<!--End of Navigation Panel-->

<H2><A NAME="SECTION006230000000000000000">
4.2.3 Module Contents</A>
</H2>

<P>
The module defines the following functions and constants, and an exception:

<P>
<dl><dt><b><a name="l2h-628"><tt class=function>compile</tt></a></b> (<var>pattern</var><big>[</big><var>, flags</var><big>]</big>)
<dd>
  Compile a regular expression pattern into a regular expression
  object, which can be used for matching using its <tt class=function>match()</tt> and
  <tt class=function>search()</tt> methods, described below.  

<P>
The expression's behaviour can be modified by specifying a
  <var>flags</var> value.  Values can be any of the following variables,
  combined using bitwise OR (the <tt>|</tt> operator).

<P>
The sequence

<P>
<dl><dd><pre class=verbatim>
prog = re.compile(pat)
result = prog.match(str)
</pre></dl>

<P>
is equivalent to

<P>
<dl><dd><pre class=verbatim>
result = re.match(pat, str)
</pre></dl>

<P>
but the version using <tt class=function>compile()</tt> is more efficient when the
expression will be used several times in a single program.
</dl>

<P>
<dl><dt><b><a name="l2h-629"><tt>I</tt></a></b>
<dd>
<dt><b><a name="l2h-642"><tt>IGNORECASE</tt></a></b><dd>
Perform case-insensitive matching; expressions like <tt class=regexp>[A-Z]</tt> will match
lowercase letters, too.  This is not affected by the current locale.
</dl>

<P>
<dl><dt><b><a name="l2h-630"><tt>L</tt></a></b>
<dd>
<dt><b><a name="l2h-643"><tt>LOCALE</tt></a></b><dd>
Make <tt class=regexp>&#92;w</tt>, <tt class=regexp>&#92;W</tt>, <tt class=regexp>&#92;b</tt>,
<tt class=regexp>&#92;B</tt>, dependent on the current locale. 
</dl>

<P>
<dl><dt><b><a name="l2h-631"><tt>M</tt></a></b>
<dd>
<dt><b><a name="l2h-644"><tt>MULTILINE</tt></a></b><dd>
When specified, the pattern character "<tt class=character>^</tt>" matches at the
beginning of the string and at the beginning of each line
(immediately following each newline); and the pattern character
"<tt class=character>$</tt>" matches at the end of the string and at the end of each line
(immediately preceding each newline).
By default, "<tt class=character>^</tt>" matches only at the beginning of the string, and
"<tt class=character>$</tt>" only at the end of the string and immediately before the
newline (if any) at the end of the string. 
</dl>

<P>
<dl><dt><b><a name="l2h-632"><tt>S</tt></a></b>
<dd>
<dt><b><a name="l2h-645"><tt>DOTALL</tt></a></b><dd>
Make the "<tt class=character>.</tt>" special character match any character at all, including a
newline; without this flag, "<tt class=character>.</tt>" will match anything <i>except</i>
a newline.
</dl>

<P>
<dl><dt><b><a name="l2h-633"><tt>X</tt></a></b>
<dd>
<dt><b><a name="l2h-646"><tt>VERBOSE</tt></a></b><dd>
This flag allows you to write regular expressions that look nicer.
Whitespace within the pattern is ignored, 
except when in a character class or preceded by an unescaped
backslash, and, when a line contains a "<tt class=character>#</tt>" neither in a character
class or preceded by an unescaped backslash, all characters from the
leftmost such "<tt class=character>#</tt>" through the end of the line are ignored.
</dl>

<P>
<dl><dt><b><a name="l2h-634"><tt class=function>search</tt></a></b> (<var>pattern, string</var><big>[</big><var>, flags</var><big>]</big>)
<dd>
  Scan through <var>string</var> looking for a location where the regular
  expression <var>pattern</var> produces a match, and return a
  corresponding <tt class=class>MatchObject</tt> instance.
  Return <tt>None</tt> if no
  position in the string matches the pattern; note that this is
  different from finding a zero-length match at some point in the string.
</dl>

<P>
<dl><dt><b><a name="l2h-635"><tt class=function>match</tt></a></b> (<var>pattern, string</var><big>[</big><var>, flags</var><big>]</big>)
<dd>
  If zero or more characters at the beginning of <var>string</var> match
  the regular expression <var>pattern</var>, return a corresponding
  <tt class=class>MatchObject</tt> instance.  Return <tt>None</tt> if the string does not
  match the pattern; note that this is different from a zero-length
  match.

<P>
<b>Note:</b>  If you want to locate a match anywhere in
  <var>string</var>, use <tt class=method>search()</tt> instead.
</dl>

<P>
<dl><dt><b><a name="l2h-636"><tt class=function>split</tt></a></b> (<var>pattern, string, </var><big>[</big><var>, maxsplit<tt> = 0</tt></var><big>]</big>)
<dd>
  Split <var>string</var> by the occurrences of <var>pattern</var>.  If
  capturing parentheses are used in <var>pattern</var>, then the text of all
  groups in the pattern are also returned as part of the resulting list.
  If <var>maxsplit</var> is nonzero, at most <var>maxsplit</var> splits
  occur, and the remainder of the string is returned as the final
  element of the list.  (Incompatibility note: in the original Python
  1.5 release, <var>maxsplit</var> was ignored.  This has been fixed in
  later releases.)

<P>
<dl><dd><pre class=verbatim>
&gt;&gt;&gt; re.split('\W+', 'Words, words, words.')
['Words', 'words', 'words', '']
&gt;&gt;&gt; re.split('(\W+)', 'Words, words, words.')
['Words', ', ', 'words', ', ', 'words', '.', '']
&gt;&gt;&gt; re.split('\W+', 'Words, words, words.', 1)
['Words', 'words, words.']
</pre></dl>

<P>
This function combines and extends the functionality of
  the old <tt class=function>regsub.split()</tt> and <tt class=function>regsub.splitx()</tt>.
</dl>

<P>
<dl><dt><b><a name="l2h-637"><tt class=function>findall</tt></a></b> (<var>pattern, string</var>)
<dd>
Return a list of all non-overlapping matches of <var>pattern</var> in
<var>string</var>.  If one or more groups are present in the pattern,
return a list of groups; this will be a list of tuples if the pattern
has more than one group.  Empty matches are included in the result.

New in version 1.5.2.

</dl>

<P>
<dl><dt><b><a name="l2h-638"><tt class=function>sub</tt></a></b> (<var>pattern, repl, string</var><big>[</big><var>, count<tt> = 0</tt></var><big>]</big>)
<dd>
Return the string obtained by replacing the leftmost non-overlapping
occurrences of <var>pattern</var> in <var>string</var> by the replacement
<var>repl</var>.  If the pattern isn't found, <var>string</var> is returned
unchanged.  <var>repl</var> can be a string or a function; if a function,
it is called for every non-overlapping occurrence of <var>pattern</var>.
The function takes a single match object argument, and returns the
replacement string.  For example:

<P>
<dl><dd><pre class=verbatim>
&gt;&gt;&gt; def dashrepl(matchobj):
....    if matchobj.group(0) == '-': return ' '
....    else: return '-'
&gt;&gt;&gt; re.sub('-{1,2}', dashrepl, 'pro----gram-files')
'pro--gram files'
</pre></dl>

<P>
The pattern may be a string or a 
regex object; if you need to specify
regular expression flags, you must use a regex object, or use
embedded modifiers in a pattern; e.g.
"<tt class=samp>sub("(?i)b+", "x", "bbbb BBBB")</tt>" returns <tt>'x x'</tt>.

<P>
The optional argument <var>count</var> is the maximum number of pattern
occurrences to be replaced; <var>count</var> must be a non-negative integer, and
the default value of 0 means to replace all occurrences.

<P>
Empty matches for the pattern are replaced only when not adjacent to a
previous match, so "<tt class=samp>sub('x*', '-', 'abc')</tt>" returns <tt>'-a-b-c-'</tt>.

<P>
If <var>repl</var> is a string, any backslash escapes in it are processed.
That is, "<tt class=samp>&#92;n</tt>" is converted to a single newline character,
"<tt class=samp>&#92;r</tt>" is converted to a linefeed, and so forth.  Unknown escapes
such as "<tt class=samp>&#92;j</tt>" are left alone.  Backreferences, such as "<tt class=samp>&#92;6</tt>", are
replaced with the substring matched by group 6 in the pattern. 

<P>
In addition to character escapes and backreferences as described
above, "<tt class=samp>&#92;g&lt;name&gt;</tt>" will use the substring matched by the group
named "<tt class=samp>name</tt>", as defined by the <tt class=regexp>(?P&lt;name&gt;...)</tt> syntax.
"<tt class=samp>&#92;g&lt;number&gt;</tt>" uses the corresponding group number; "<tt class=samp>&#92;
g&lt;2&gt;</tt>" is therefore equivalent to "<tt class=samp>&#92;2</tt>", but isn't ambiguous in a
replacement such as "<tt class=samp>&#92;g&lt;2&gt;0</tt>".  "<tt class=samp>&#92;20</tt>" would be
interpreted as a reference to group 20, not a reference to group 2
followed by the literal character "<tt class=character>0</tt>".  
</dl>

<P>
<dl><dt><b><a name="l2h-639"><tt class=function>subn</tt></a></b> (<var>pattern, repl, string</var><big>[</big><var>, count<tt> = 0</tt></var><big>]</big>)
<dd>
Perform the same operation as <tt class=function>sub()</tt>, but return a tuple
<tt>(<var>new_string</var>, <var>number_of_subs_made</var>)</tt>.
</dl>

<P>
<dl><dt><b><a name="l2h-640"><tt class=function>escape</tt></a></b> (<var>string</var>)
<dd>
  Return <var>string</var> with all non-alphanumerics backslashed; this is
  useful if you want to match an arbitrary literal string that may have
  regular expression metacharacters in it.
</dl>

<P>
<dl><dt><b><a name="l2h-641"><tt class=exception>error</tt></a></b>
<dd>
  Exception raised when a string passed to one of the functions here
  is not a valid regular expression (e.g., unmatched parentheses) or
  when some other error occurs during compilation or matching.  It is
  never an error if a string contains no match for a pattern.
</dl>

<P>
<p>
<div class=navigation><hr><table align=center width="100%" cellpadding=0 cellspacing=2>
<tr>
<td><A HREF="re-objects.html"><img width=32 height=32 align=bottom border=0 alt="next"
 src="../icons/next.gif"></A></td>
<td><A HREF="module-re.html"><img width=32 height=32 align=bottom border=0 alt="up"
 src="../icons/up.gif"></A></td>
<td><A HREF="matching-searching.html"><img width=32 height=32 align=bottom border=0 alt="previous"
 src="../icons/previous.gif"></A></td>
<td align=center bgcolor="#99CCFF" width="100%">
 <b class=title>Python Library Reference</b></td>
<td><A HREF="contents.html"><img width=32 height=32 align=bottom border=0 alt="contents"
 src="../icons/contents.gif"></A></td>
<td><a
 href="modindex.html"><img width=32 height=32 align=bottom border=0 alt="modules"
 src="../icons/modules.gif"></a></td>
<td><A HREF="genindex.html"><img width=32 height=32 align=bottom border=0 alt="index"
 src="../icons/index.gif"></A></td>
</tr></table><b class=navlabel>Next:</b> <span class=sectref><A HREF="re-objects.html">4.2.4 Regular Expression Objects</A></span>
<b class=navlabel>Up:</b> <span class=sectref><A HREF="module-re.html">4.2 re  </A></span>
<b class=navlabel>Previous:</b> <span class=sectref><A HREF="matching-searching.html">4.2.2 Matching vs. Searching</A></span>
</div>
<!--End of Navigation Panel-->
<ADDRESS>
<hr>Send comments on this document to <a href="mailto:python-docs@python.org">python-docs@python.org</a>.
</ADDRESS>
</BODY>
</HTML>
