This is Info file /home/pdm/tmp/Python-1.5.2p1/Doc/lib/python-lib.info,
produced by Makeinfo version 1.68 from the input file lib.texi.
July 6, 1999 1.5.2
File: python-lib.info, Node: Regular Expression Syntax, Next: Matching vs. Searching, Prev: re, Up: re
Regular Expression Syntax
-------------------------
A regular expression (or RE) specifies a set of strings that matches
it; the functions in this module let you check if a particular string
matches a given regular expression (or if a given regular expression
matches a particular string, which comes down to the same thing).
Regular expressions can be concatenated to form new regular
expressions; if *A* and *B* are both regular expressions, then *AB* is
also an regular expression. If a string *p* matches A and another
string *q* matches B, the string *pq* will match AB. Thus, complex
expressions can easily be constructed from simpler primitive
expressions like the ones described here. For details of the theory
and implementation of regular expressions, consult the Friedl book
referenced below, or almost any textbook about compiler construction.
A brief explanation of the format of regular expressions follows.
For further information and a gentler presentation, consult the Regular
Expression HOWTO, accessible from `http://www.python.org/doc/howto/'.
Regular expressions can contain both special and ordinary characters.
Most ordinary characters, like `A', `a', or `0', are the simplest
regular expressions; they simply match themselves. You can concatenate
ordinary characters, so "last" matches the string `'last''. (In the
rest of this section, we'll write RE's in "this special style", usually
without quotes, and strings to be matched `'in single quotes''.)
Some characters, like `|' or `(', are special. Special characters
either stand for classes of ordinary characters, or affect how the
regular expressions around them are interpreted.
The special characters are:
``.''
(Dot.) In the default mode, this matches any character except a
newline. If the `DOTALL' flag has been specified, this matches
any character including a newline.
``^''
(Caret.) Matches the start of the string, and in `MULTILINE' mode
also matches immediately after each newline.
``$''
Matches the end of the string, and in `MULTILINE' mode also
matches before a newline. "foo" matches both 'foo' and 'foobar',
while the regular expression "foo$" matches only 'foo'.
``*''
Causes the resulting RE to match 0 or more repetitions of the
preceding RE, as many repetitions as are possible. "ab*" will
match 'a', 'ab', or 'a' followed by any number of 'b's.
``+''
Causes the resulting RE to match 1 or more repetitions of the
preceding RE. "ab+" will match 'a' followed by any non-zero
number of 'b's; it will not match just 'a'.
``?''
Causes the resulting RE to match 0 or 1 repetitions of the
preceding RE. "ab?" will match either 'a' or 'ab'.
``*?', `+?', `??''
The `*', `+', and `?' qualifiers are all "greedy"; they match as
much text as possible. Sometimes this behaviour isn't desired; if
the RE "<.*>" is matched against `'title
'', it will match
the entire string, and not just `'''. Adding `?' after the
qualifier makes it perform the match in "non-greedy" or "minimal"
fashion; as *few* characters as possible will be matched. Using
".*?" in the previous expression will match only `'''.
``{M,N}''
Causes the resulting RE to match from M to N repetitions of the
preceding RE, attempting to match as many repetitions as possible.
For example, "a{3,5}" will match from 3 to 5 `a' characters.
Omitting N specifies an infinite upper bound; you can't omit M.
``{M,N}?''
Causes the resulting RE to match from M to N repetitions of the
preceding RE, attempting to match as *few* repetitions as
possible. This is the non-greedy version of the previous
qualifier. For example, on the 6-character string `'aaaaaa'',
"a{3,5}" will match 5 `a' characters, while "a{3,5}?" will only
match 3 characters.
``\''
Either escapes special characters (permitting you to match
characters like `*', `?', and so forth), or signals a special
sequence; special sequences are discussed below.
If you're not using a raw string to express the pattern, remember
that Python also uses the backslash as an escape sequence in
string literals; if the escape sequence isn't recognized by
Python's parser, the backslash and subsequent character are
included in the resulting string. However, if Python would
recognize the resulting sequence, the backslash should be repeated
twice. This is complicated and hard to understand, so it's highly
recommended that you use raw strings for all but the simplest
expressions.
``[ '] Used to indicate a set of characters. Characters can'
be listed individually, or a range of characters can be indicated
by giving two characters and separating them by a `-'. Special
characters are not active inside sets. For example, "[akm$]" will
match any of the characters `a', `k', `m', or `$'; "[a-z]" will
match any lowercase letter, and `[a-zA-Z0-9]' matches any letter
or digit. Character classes such as `\w' or `\S' (defined below)
are also acceptable inside a range. If you want to include a `]'
or a `-' inside a set, precede it with a backslash, or place it as
the first character. The pattern "[]]" will match `']'', for
example.
You can match the characters not within a range by "complementing"
the set. This is indicated by including a `^' as the first
character of the set; `^' elsewhere will simply match the `^'
character. For example, "[{^}5]" will match any character except
`5'.
``|''
`A|B', where A and B can be arbitrary REs, creates a regular
expression that will match either A or B. This can be used inside
groups (see below) as well. To match a literal `|', use "\|", or
enclose it inside a character class, as in "[|]".
``(...)''
Matches whatever regular expression is inside the parentheses, and
indicates the start and end of a group; the contents of a group
can be retrieved after a match has been performed, and can be
matched later in the string with the "\NUMBER" special sequence,
described below. To match the literals `(' or `')', use "\(" or
"\)", or enclose them inside a character class: "[(] [)]".
``(?...)''
This is an extension notation (a `?' following a `(' is not
meaningful otherwise). The first character after the `?'
determines what the meaning and further syntax of the construct is.
Extensions usually do not create a new group; "(?P...)" is
the only exception to this rule. Following are the currently
supported extensions.
``(?iLmsx)''
(One or more letters from the set `i', `L', `m', `s', `x'.) The
group matches the empty string; the letters set the corresponding
flags (`re.I', `re.L', `re.M', `re.S', `re.X') for the entire
regular expression. This is useful if you wish to include the
flags as part of the regular expression, instead of passing a FLAG
argument to the `compile()' function.
``(?:...)''
A non-grouping version of regular parentheses. Matches whatever
regular expression is inside the parentheses, but the substring
matched by the group *cannot* be retrieved after performing a
match or referenced later in the pattern.
``(?P...)''
Similar to regular parentheses, but the substring matched by the
group is accessible via the symbolic group name NAME. Group names
must be valid Python identifiers. A symbolic group is also a
numbered group, just as if the group were not named. So the group
named 'id' in the example above can also be referenced as the
numbered group 1.
For example, if the pattern is "(?P[a-zA-Z_]\w*)", the group
can be referenced by its name in arguments to methods of match
objects, such as `m.group('id')' or `m.end('id')', and also by
name in pattern text (e.g. "(?P=id)") and replacement text (e.g.
`\g').
``(?P=NAME)''
Matches whatever text was matched by the earlier group named NAME.
``(?#...)''
A comment; the contents of the parentheses are simply ignored.
``(?=...)''
Matches if "..." matches next, but doesn't consume any of the
string. This is called a lookahead assertion. For example,
"Isaac (?=Asimov)" will match `'Isaac~'' only if it's followed by
`'Asimov''.
``(?!...)''
Matches if "..." doesn't match next. This is a negative lookahead
assertion. For example, "Isaac (?!Asimov)" will match `'Isaac~''
only if it's *not* followed by `'Asimov''.
The special sequences consist of `\' and a character from the list
below. If the ordinary character is not on the list, then the
resulting RE will match the second character. For example, "\$"
matches the character `$'.
``\NUMBER''
Matches the contents of the group of the same number. Groups are
numbered starting from 1. For example, "(.+) \1" matches `'the
the'' or `'55 55'', but not `'the end'' (note the space after the
group). This special sequence can only be used to match one of
the first 99 groups. If the first digit of NUMBER is 0, or NUMBER
is 3 octal digits long, it will not be interpreted as a group
match, but as the character with octal value NUMBER. Inside the
`[' and `]' of a character class, all numeric escapes are treated
as characters.
``\A''
Matches only at the start of the string.
``\b''
Matches the empty string, but only at the beginning or end of a
word. A word is defined as a sequence of alphanumeric characters,
so the end of a word is indicated by whitespace or a
non-alphanumeric character. Inside a character range, "\b"
represents the backspace character, for compatibility with
Python's string literals.
``\B''
Matches the empty string, but only when it is *not* at the
beginning or end of a word.
``\d''
Matches any decimal digit; this is equivalent to the set "[0-9]".
``\D''
Matches any non-digit character; this is equivalent to the set
"[{^}0-9]".
``\s''
Matches any whitespace character; this is equivalent to the set "[
\t\n\r\f\v]".
``\S''
Matches any non-whitespace character; this is equivalent to the
set "[^ \t\n\r\f\v]".
``\w''
When the `LOCALE' flag is not specified, matches any alphanumeric
character; this is equivalent to the set "[a-zA-Z0-9_]". With
`LOCALE', it will match the set "[0-9_]" plus whatever characters
are defined as letters for the current locale.
``\W''
When the `LOCALE' flag is not specified, matches any
non-alphanumeric character; this is equivalent to the set
"[{^}a-zA-Z0-9_]". With `LOCALE', it will match any character
not in the set "[0-9_]", and not defined as a letter for the
current locale.
``\Z''
Matches only at the end of the string.
``\\''
Matches a literal backslash.
File: python-lib.info, Node: Matching vs. Searching, Next: Contents of Module re, Prev: Regular Expression Syntax, Up: re
Matching vs. Searching
----------------------
This section was written by Fred L. Drake, Jr. .
Python offers two different primitive operations based on regular
expressions: match and search. If you are accustomed to Perl's
semantics, the search operation is what you're looking for. See the
`search()' function and corresponding method of compiled regular
expression objects.
Note that match may differ from search using a regular expression
beginning with `^': `^' matches only at the start of the string, or in
`MULTILINE' mode also immediately following a newline. The "match"
operation succeeds only if the pattern matches at the start of the
string regardless of mode, or at the starting position given by the
optional POS argument regardless of whether a newline precedes it.
re.compile("a").match("ba", 1) # succeeds
re.compile("^a").search("ba", 1) # fails; 'a' not at start
re.compile("^a").search("\na", 1) # fails; 'a' not at start
re.compile("^a", re.M).search("\na", 1) # succeeds
re.compile("^a", re.M).search("ba", 1) # fails; no preceding \n
File: python-lib.info, Node: Contents of Module re, Next: Regular Expression Objects, Prev: Matching vs. Searching, Up: re
Module Contents
---------------
The module defines the following functions and constants, and an
exception:
`compile(pattern[, flags])'
Compile a regular expression pattern into a regular expression
object, which can be used for matching using its `match()' and
`search()' methods, described below.
The expression's behaviour can be modified by specifying a FLAGS
value. Values can be any of the following variables, combined
using bitwise OR (the `|' operator).
The sequence
prog = re.compile(pat)
result = prog.match(str)
is equivalent to
result = re.match(pat, str)
but the version using `compile()' is more efficient when the
expression will be used several times in a single program.
`I'
`IGNORECASE'
Perform case-insensitive matching; expressions like "[A-Z]" will
match lowercase letters, too. This is not affected by the current
locale.
`L'
`LOCALE'
Make "\w", "\W", "\b", "\B", dependent on the current locale.
`M'
`MULTILINE'
When specified, the pattern character `^' matches at the beginning
of the string and at the beginning of each line (immediately
following each newline); and the pattern character `$' matches at
the end of the string and at the end of each line (immediately
preceding each newline). By default, `^' matches only at the
beginning of the string, and `$' only at the end of the string and
immediately before the newline (if any) at the end of the string.
`S'
`DOTALL'
Make the `.' special character match any character at all,
including a newline; without this flag, `.' will match anything
*except* a newline.
`X'
`VERBOSE'
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 `#' neither in a character class or preceded by an
unescaped backslash, all characters from the leftmost such `#'
through the end of the line are ignored.
`search(pattern, string[, flags])'
Scan through STRING looking for a location where the regular
expression PATTERN produces a match, and return a corresponding
`MatchObject' instance. Return `None' 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.
`match(pattern, string[, flags])'
If zero or more characters at the beginning of STRING match the
regular expression PATTERN, return a corresponding `MatchObject'
instance. Return `None' if the string does not match the pattern;
note that this is different from a zero-length match.
*Note:* If you want to locate a match anywhere in STRING, use
`search()' instead.
`split(pattern, string, [, maxsplit` = 0'])'
Split STRING by the occurrences of PATTERN. If capturing
parentheses are used in PATTERN, then the text of all groups in
the pattern are also returned as part of the resulting list. If
MAXSPLIT is nonzero, at most MAXSPLIT 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,
MAXSPLIT was ignored. This has been fixed in later releases.)
>>> re.split('\W+', 'Words, words, words.')
['Words', 'words', 'words', '']
>>> re.split('(\W+)', 'Words, words, words.')
['Words', ', ', 'words', ', ', 'words', '.', '']
>>> re.split('\W+', 'Words, words, words.', 1)
['Words', 'words, words.']
This function combines and extends the functionality of the old
`regsub.split()' and `regsub.splitx()'.
`findall(pattern, string)'
Return a list of all non-overlapping matches of PATTERN in STRING.
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. *Added
in Python version 1.5.2*
`sub(pattern, repl, string[, count` = 0'])'
Return the string obtained by replacing the leftmost
non-overlapping occurrences of PATTERN in STRING by the replacement
REPL. If the pattern isn't found, STRING is returned unchanged.
REPL can be a string or a function; if a function, it is called
for every non-overlapping occurrence of PATTERN. The function
takes a single match object argument, and returns the replacement
string. For example:
>>> def dashrepl(matchobj):
.... if matchobj.group(0) == '-': return ' '
.... else: return '-'
>>> re.sub('-{1,2}', dashrepl, 'pro----gram-files')
'pro--gram files'
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. `sub("(?i)b+", "x",
"bbbb BBBB")' returns `'x x''.
The optional argument COUNT is the maximum number of pattern
occurrences to be replaced; COUNT must be a non-negative integer,
and the default value of 0 means to replace all occurrences.
Empty matches for the pattern are replaced only when not adjacent
to a previous match, so `sub('x*', '-', 'abc')' returns
`'-a-b-c-''.
If REPL is a string, any backslash escapes in it are processed.
That is, `\n' is converted to a single newline character, `\r' is
converted to a linefeed, and so forth. Unknown escapes such as
`\j' are left alone. Backreferences, such as `\6', are replaced
with the substring matched by group 6 in the pattern.
In addition to character escapes and backreferences as described
above, `\g' will use the substring matched by the group
named `name', as defined by the "(?P...)" syntax.
`\g' uses the corresponding group number; `\g<2>' is
therefore equivalent to `\2', but isn't ambiguous in a replacement
such as `\g<2>0'. `\20' would be interpreted as a reference to
group 20, not a reference to group 2 followed by the literal
character `0'.
`subn(pattern, repl, string[, count` = 0'])'
Perform the same operation as `sub()', but return a tuple
`(NEW_STRING, NUMBER_OF_SUBS_MADE)'.
`escape(string)'
Return STRING 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.
`error'
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.
File: python-lib.info, Node: Regular Expression Objects, Next: Match Objects, Prev: Contents of Module re, Up: re
Regular Expression Objects
--------------------------
Compiled regular expression objects support the following methods and
attributes:
`search(string[, pos][, endpos])'
Scan through STRING looking for a location where this regular
expression produces a match, and return a corresponding
`MatchObject' instance. Return `None' 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.
The optional POS and ENDPOS parameters have the same meaning as
for the `match()' method.
`match(string[, pos][, endpos])'
If zero or more characters at the beginning of STRING match this
regular expression, return a corresponding `MatchObject' instance.
Return `None' if the string does not match the pattern; note that
this is different from a zero-length match.
*Note:* If you want to locate a match anywhere in STRING, use
`search()' instead.
The optional second parameter POS gives an index in the string
where the search is to start; it defaults to `0'. This is not
completely equivalent to slicing the string; the `'^'' pattern
character matches at the real beginning of the string and at
positions just after a newline, but not necessarily at the index
where the search is to start.
The optional parameter ENDPOS limits how far the string will be
searched; it will be as if the string is ENDPOS characters long,
so only the characters from POS to ENDPOS will be searched for a
match.
`split(string, [, maxsplit` = 0'])'
Identical to the `split()' function, using the compiled pattern.
`findall(string)'
Identical to the `findall()' function, using the compiled pattern.
`sub(repl, string[, count` = 0'])'
Identical to the `sub()' function, using the compiled pattern.
`subn(repl, string[, count` = 0'])'
Identical to the `subn()' function, using the compiled pattern.
`flags'
The flags argument used when the regex object was compiled, or `0'
if no flags were provided.
`groupindex'
A dictionary mapping any symbolic group names defined by
"(?P)" to group numbers. The dictionary is empty if no
symbolic groups were used in the pattern.
`pattern'
The pattern string from which the regex object was compiled.
File: python-lib.info, Node: Match Objects, Prev: Regular Expression Objects, Up: re
Match Objects
-------------
`MatchObject' instances support the following methods and attributes:
`group([group1, group2, ...])'
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 `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...)" 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\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 `None' 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 `(None, None)'. 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.
File: python-lib.info, Node: regex, Next: regsub, Prev: re, Up: String Services
Regular expression search and match operations.
===============================================
Regular expression search and match operations.
This module provides regular expression matching operations similar
to those found in Emacs.
*Obsolescence note:* This module is obsolete as of Python version
1.5; it is still being maintained because much existing code still uses
it. All new code in need of regular expressions should use the new
`re' module, which supports the more powerful and regular Perl-style
regular expressions. Existing code should be converted. The standard
library module `reconvert' helps in converting `regex' style regular
expressions to `re'style regular expressions. (For more conversion
help, see Andrew Kuchling's "`regex-to-re' HOWTO" at
`http://www.python.org/doc/howto/regex-to-re/'.)
By default the patterns are Emacs-style regular expressions (with
one exception). There is a way to change the syntax to match that of
several well-known UNIX utilities. The exception is that Emacs' `\s'
pattern is not supported, since the original implementation references
the Emacs syntax tables.
This module is 8-bit clean: both patterns and strings may contain
null bytes and characters whose high bit is set.
*Please note:* There is a little-known fact about Python string
literals which means that you don't usually have to worry about
doubling backslashes, even though they are used to escape special
characters in string literals as well as in regular expressions. This
is because Python doesn't remove backslashes from string literals if
they are followed by an unrecognized escape character. *However*, if
you want to include a literal "backslash" in a regular expression
represented as a string literal, you have to *quadruple* it or enclose
it in a singleton character class. E.g. to extract LaTeX
`\section{...}' headers from a document, you can use this pattern:
`'[\]section{\(.*\)}''. *Another exception:* the escape sequece `\b'
is significant in string literals (where it means the ASCII bell
character) as well as in Emacs regular expressions (where it stands for
a word boundary), so in order to search for a word boundary, you should
use the pattern `'\\b''. Similarly, a backslash followed by a digit
0-7 should be doubled to avoid interpretation as an octal escape.
* Menu:
* Regular Expressions::
* Contents of Module regex::
File: python-lib.info, Node: Regular Expressions, Next: Contents of Module regex, Prev: regex, Up: regex
Regular Expressions
-------------------
A regular expression (or RE) specifies a set of strings that matches
it; the functions in this module let you check if a particular string
matches a given regular expression (or if a given regular expression
matches a particular string, which comes down to the same thing).
Regular expressions can be concatenated to form new regular
expressions; if *A* and *B* are both regular expressions, then *AB* is
also an regular expression. If a string *p* matches A and another
string *q* matches B, the string *pq* will match AB. Thus, complex
expressions can easily be constructed from simpler ones like the
primitives described here. For details of the theory and
implementation of regular expressions, consult almost any textbook
about compiler construction.
A brief explanation of the format of regular expressions follows.
Regular expressions can contain both special and ordinary characters.
Ordinary characters, like '`A'', '`a'', or '`0'', are the simplest
regular expressions; they simply match themselves. You can concatenate
ordinary characters, so '`last'' matches the characters 'last'. (In
the rest of this section, we'll write RE's in `this special font',
usually without quotes, and strings to be matched 'in single quotes'.)
Special characters either stand for classes of ordinary characters,
or affect how the regular expressions around them are interpreted.
The special characters are:
* `.' (Dot.) Matches any character except a newline.
* `^' (Caret.) Matches the start of the string.
* `$' Matches the end of the string. `foo' matches both 'foo' and
'foobar', while the regular expression '`foo$'' matches only 'foo'.
* `*' Causes the resulting RE to match 0 or more repetitions of the
preceding RE. `ab*' will match 'a', 'ab', or 'a' followed by any
number of 'b's.
* `+' Causes the resulting RE to match 1 or more repetitions of the
preceding RE. `ab+' will match 'a' followed by any non-zero
number of 'b's; it will not match just 'a'.
* `?' Causes the resulting RE to match 0 or 1 repetitions of the
preceding RE. `ab?' will match either 'a' or 'ab'.
* `\' Either escapes special characters (permitting you to match
characters like '*?+&$'), or signals a special sequence; special
sequences are discussed below. Remember that Python also uses the
backslash as an escape sequence in string literals; if the escape
sequence isn't recognized by Python's parser, the backslash and
subsequent character are included in the resulting string.
However, if Python would recognize the resulting sequence, the
backslash should be repeated twice.
* `[ '] Used to indicate a set of characters. Characters can be
listed individually, or a range is indicated by giving two
characters and separating them by a '-'. Special characters are
not active inside sets. For example, `[akm$]' will match any of
the characters 'a', 'k', 'm', or '$'; `[a-z]' will match any
lowercase letter.
If you want to include a `]' inside a set, it must be the first
character of the set; to include a `-', place it as the first or
last character.
Characters *not* within a range can be matched by including a `^'
as the first character of the set; `^' elsewhere will simply match
the '`^'' character.
The special sequences consist of '`\'' and a character from the list
below. If the ordinary character is not on the list, then the
resulting RE will match the second character. For example, `\$'
matches the character '$'. Ones where the backslash should be doubled
in string literals are indicated.
* `\|' `A\|B', where A and B can be arbitrary REs, creates a regular
expression that will match either A or B. This can be used inside
groups (see below) as well.
* `\( \)' Indicates the start and end of a group; the contents of a
group can be matched later in the string with the `\[1-9]' special
sequence, described next.
``\\1, ... \\7, \8, \9''
Matches the contents of the group of the same number. For
example, `\(.+\) \\1' matches 'the the' or '55 55', but not 'the
end' (note the space after the group). This special sequence can
only be used to match one of the first 9 groups; groups with
higher numbers can be matched using the `\v' sequence. (`\8' and
`\9' don't need a double backslash because they are not octal
digits.)
* `\\b' Matches the empty string, but only at the beginning or end
of a word. A word is defined as a sequence of alphanumeric
characters, so the end of a word is indicated by whitespace or a
non-alphanumeric character.
* `\B' Matches the empty string, but when it is *not* at the
beginning or end of a word.
* `\v' Must be followed by a two digit decimal number, and matches
the contents of the group of the same number. The group number
must be between 1 and 99, inclusive.
* `\w' Matches any alphanumeric character; this is equivalent to the
set `[a-zA-Z0-9]'.
* `\W' Matches any non-alphanumeric character; this is equivalent to
the set `[^a-zA-Z0-9]'.
* `\<' Matches the empty string, but only at the beginning of a
word. A word is defined as a sequence of alphanumeric characters,
so the end of a word is indicated by whitespace or a
non-alphanumeric character.
* `\>' Matches the empty string, but only at the end of a word.
* `\\\\' Matches a literal backslash.
* `\`' Like `^', this only matches at the start of the string.
* `\\'' Like `$', this only matches at the end of the string.
File: python-lib.info, Node: Contents of Module regex, Prev: Regular Expressions, Up: regex
Module Contents
---------------
The module defines these functions, and an exception:
`match(pattern, string)'
Return how many characters at the beginning of STRING match the
regular expression PATTERN. Return `-1' if the string does not
match the pattern (this is different from a zero-length match!).
`search(pattern, string)'
Return the first position in STRING that matches the regular
expression PATTERN. Return `-1' if no position in the string
matches the pattern (this is different from a zero-length match
anywhere!).
`compile(pattern[, translate])'
Compile a regular expression pattern into a regular expression
object, which can be used for matching using its `match()' and
`search()' methods, described below. The optional argument
TRANSLATE, if present, must be a 256-character string indicating
how characters (both of the pattern and of the strings to be
matched) are translated before comparing them; the I-th element of
the string gives the translation for the character with ASCII code
I. This can be used to implement case-insensitive matching; see
the `casefold' data item below.
The sequence
prog = regex.compile(pat)
result = prog.match(str)
is equivalent to
result = regex.match(pat, str)
but the version using `compile()' is more efficient when multiple
regular expressions are used concurrently in a single program.
(The compiled version of the last pattern passed to
`regex.match()' or `regex.search()' is cached, so programs that
use only a single regular expression at a time needn't worry about
compiling regular expressions.)
`set_syntax(flags)'
Set the syntax to be used by future calls to `compile()',
`match()' and `search()'. (Already compiled expression objects
are not affected.) The argument is an integer which is the OR of
several flag bits. The return value is the previous value of the
syntax flags. Names for the flags are defined in the standard
module `regex_syntax'; read the file `regex_syntax.py' for more
information.
`get_syntax()'
Returns the current value of the syntax flags as an integer.
`symcomp(pattern[, translate])'
This is like `compile()', but supports symbolic group names: if a
parenthesis-enclosed group begins with a group name in angular
brackets, e.g. `'\([a-z][a-z0-9]*\)'', the group can be
referenced by its name in arguments to the `group()' method of the
resulting compiled regular expression object, like this:
`p.group('id')'. Group names may contain alphanumeric characters
and `'_'' only.
`error'
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.)
`casefold'
A string suitable to pass as the TRANSLATE argument to `compile()'
to map all upper case characters to their lowercase equivalents.
Compiled regular expression objects support these methods:
`match(string[, pos])'
Return how many characters at the beginning of STRING match the
compiled regular expression. Return `-1' if the string does not
match the pattern (this is different from a zero-length match!).
The optional second parameter, POS, gives an index in the string
where the search is to start; it defaults to `0'. This is not
completely equivalent to slicing the string; the `'^'' pattern
character matches at the real beginning of the string and at
positions just after a newline, not necessarily at the index where
the search is to start.
`search(string[, pos])'
Return the first position in STRING that matches the regular
expression `pattern'. Return `-1' if no position in the string
matches the pattern (this is different from a zero-length match
anywhere!).
The optional second parameter has the same meaning as for the
`match()' method.
`group(index, index, ...)'
This method is only valid when the last call to the `match()' or
`search()' method found a match. It returns one or more groups of
the match. If there is a single INDEX argument, the result is a
single string; if there are multiple arguments, the result is a
tuple with one item per argument. If the INDEX 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 (using the default syntax,
groups are parenthesized using `{\}(' and `{\})'). If no such
group exists, the corresponding result is `None'.
If the regular expression was compiled by `symcomp()' instead of
`compile()', the INDEX arguments may also be strings identifying
groups by their group name.
Compiled regular expressions support these data attributes:
`regs'
When the last call to the `match()' or `search()' method found a
match, this is a tuple of pairs of indexes corresponding to the
beginning and end of all parenthesized groups in the pattern.
Indices are relative to the string argument passed to `match()' or
`search()'. The 0-th tuple gives the beginning and end or the
whole pattern. When the last match or search failed, this is
`None'.
`last'
When the last call to the `match()' or `search()' method found a
match, this is the string argument passed to that method. When the
last match or search failed, this is `None'.
`translate'
This is the value of the TRANSLATE argument to `regex.compile()'
that created this regular expression object. If the TRANSLATE
argument was omitted in the `regex.compile()' call, this is `None'.
`givenpat'
The regular expression pattern as passed to `compile()' or
`symcomp()'.
`realpat'
The regular expression after stripping the group names for regular
expressions compiled with `symcomp()'. Same as `givenpat'
otherwise.
`groupindex'
A dictionary giving the mapping from symbolic group names to
numerical group indexes for regular expressions compiled with
`symcomp()'. `None' otherwise.
File: python-lib.info, Node: regsub, Next: struct, Prev: regex, Up: String Services
String operations using regular expressions
===========================================
Substitution and splitting operations that use regular expressions.
This module defines a number of functions useful for working with
regular expressions (see built-in module `regex').
Warning: these functions are not thread-safe.
*Obsolescence note:* This module is obsolete as of Python version
1.5; it is still being maintained because much existing code still uses
it. All new code in need of regular expressions should use the new
`re' module, which supports the more powerful and regular Perl-style
regular expressions. Existing code should be converted. The standard
library module `reconvert' helps in converting `regex' style regular
expressions to `re' style regular expressions. (For more conversion
help, see Andrew Kuchling's"regex-to-re HOWTO" at
`http://www.python.org/doc/howto/regex-to-re/'.)
`sub(pat, repl, str)'
Replace the first occurrence of pattern PAT in string STR by
replacement REPL. If the pattern isn't found, the string is
returned unchanged. The pattern may be a string or an already
compiled pattern. The replacement may contain references `\DIGIT'
to subpatterns and escaped backslashes.
`gsub(pat, repl, str)'
Replace all (non-overlapping) occurrences of pattern PAT in string
STR by replacement REPL. The same rules as for `sub()' apply.
Empty matches for the pattern are replaced only when not adjacent
to a previous match, so e.g. `gsub('', '-', 'abc')' returns
`'-a-b-c-''.
`split(str, pat[, maxsplit])'
Split the string STR in fields separated by delimiters matching
the pattern PAT, and return a list containing the fields. Only
non-empty matches for the pattern are considered, so e.g.
`split('a:b', ':*')' returns `['a', 'b']' and `split('abc', '')'
returns `['abc']'. The MAXSPLIT defaults to 0. If it is nonzero,
only MAXSPLIT number of splits occur, and the remainder of the
string is returned as the final element of the list.
`splitx(str, pat[, maxsplit])'
Split the string STR in fields separated by delimiters matching
the pattern PAT, and return a list containing the fields as well
as the separators. For example, `splitx('a:::b', ':*')' returns
`['a', ':::', 'b']'. Otherwise, this function behaves the same as
`split'.
`capwords(s[, pat])'
Capitalize words separated by optional pattern PAT. The default
pattern uses any characters except letters, digits and underscores
as word delimiters. Capitalization is done by changing the first
character of each word to upper case.
`clear_cache()'
The regsub module maintains a cache of compiled regular
expressions, keyed on the regular expression string and the syntax
of the regex module at the time the expression was compiled. This
function clears that cache.