Patch by Jeffrey Chang to add docstrings everywhere.
The text is condensed from the library manual.
This commit is contained in:
Guido van Rossum
parent
7c85ab829d
commit
6ebb387a08
339
Lib/re.py
339
Lib/re.py
|
|
@ -1,3 +1,89 @@
|
|||
# module 're' -- A collection of regular expression operations
|
||||
|
||||
"""Support for regular expressions (RE).
|
||||
|
||||
This module provides regular expression matching operations similar to
|
||||
those found in Perl. It's 8-bit clean: the strings being processed may
|
||||
contain both null bytes and characters whose high bit is set. Regular
|
||||
expression pattern strings may not contain null bytes, but can specify
|
||||
the null byte using the \\number notation. Characters with the high
|
||||
bit set may be included.
|
||||
|
||||
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'.
|
||||
|
||||
The special characters are:
|
||||
"." Matches any character except a newline.
|
||||
"^" Matches the start of the string.
|
||||
"$" Matches the end of the string.
|
||||
"*" Matches 0 or more (greedy) repetitions of the preceding RE.
|
||||
Greedy means that it will match as many repetitions as possible.
|
||||
"+" Matches 0 or more (greedy) repetitions of the preceding RE.
|
||||
"?" Matches 0 or 1 (greedy) of the preceding RE.
|
||||
*?,+?,?? Non-greedy versions of the previous three special characters.
|
||||
{m,n} Matches from m to n repetitions of the preceding RE.
|
||||
{m,n}? Non-greedy version of the above.
|
||||
"\\" Either escapes special characters or signals a special sequence.
|
||||
[] Indicates a set of characters.
|
||||
A "^" as the first character indicates a complementing set.
|
||||
"|" A|B, creates an RE that will match either A or B.
|
||||
(...) Matches the RE inside the parentheses.
|
||||
The contents can be retrieved or matched later in the string.
|
||||
(?iLmsx) Set the I, L, M, S, or X flag for the RE.
|
||||
(?:...) Non-grouping version of regular parentheses.
|
||||
(?P<name>...) The substring matched by the group is accessible by name.
|
||||
(?P=name) Matches the text matched earlier by the group named name.
|
||||
(?#...) A comment; ignored.
|
||||
(?=...) Matches if ... matches next, but doesn't consume the string.
|
||||
(?!...) Matches if ... doesn't match next.
|
||||
|
||||
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.
|
||||
\\number Matches the contents of the group of the same number.
|
||||
\\A Matches only at the start of the string.
|
||||
\\Z Matches only at the end of the string.
|
||||
\\b Matches the empty string, but only at the start or end of a word.
|
||||
\\B Matches the empty string, but not at the start or end of a word.
|
||||
\\d Matches any decimal digit; equivalent to the set [0-9].
|
||||
\\D Matches any non-digit character; equivalent to the set [^0-9].
|
||||
\\s Matches any whitespace character; equivalent to [ \\t\\n\\r\\f\\v].
|
||||
\\S Matches any non-whitespace character; equiv. to [^ \\t\\n\\r\\f\\v].
|
||||
\\w Matches any alphanumeric character; equivalent to [a-zA-Z0-9_].
|
||||
With LOCALE, it will match the set [0-9_] plus characters defined
|
||||
as letters for the current locale.
|
||||
\\W Matches the complement of \\w.
|
||||
\\\\ Matches a literal backslash.
|
||||
|
||||
This module exports the following functions:
|
||||
match Match a regular expression pattern to the beginning of a string.
|
||||
search Search a string for the presence of a pattern.
|
||||
sub Substitute occurrences of a pattern found in a string.
|
||||
subn Same as sub, but also return the number of substitutions made.
|
||||
split Split a string by the occurrences of a pattern.
|
||||
findall Find all occurrences of a pattern in a string.
|
||||
compile Compile a pattern into a RegexObject.
|
||||
escape Backslash all non-alphanumerics in a string.
|
||||
|
||||
This module exports the following classes:
|
||||
RegexObject Holds a compiled regular expression pattern.
|
||||
MatchObject Contains information about pattern matches.
|
||||
|
||||
Some of the functions in this module takes flags as optional parameters:
|
||||
I IGNORECASE Perform case-insensitive matching.
|
||||
L LOCALE Make \w, \W, \b, \B, dependent on the current locale.
|
||||
M MULTILINE "^" matches the beginning of lines as well as the string.
|
||||
"$" matches the end of lines as well as the string.
|
||||
S DOTALL "." matches any character at all, including the newline.
|
||||
X VERBOSE Ignore whitespaces and comments for nicer looking RE's.
|
||||
|
||||
This module also defines an exception 'error'.
|
||||
|
||||
"""
|
||||
|
||||
|
||||
import sys
|
||||
import string
|
||||
from pcre import *
|
||||
|
|
@ -17,6 +103,7 @@ M = MULTILINE
|
|||
S = DOTALL
|
||||
X = VERBOSE
|
||||
|
||||
|
||||
#
|
||||
#
|
||||
#
|
||||
|
|
@ -37,33 +124,104 @@ def _cachecompile(pattern, flags=0):
|
|||
return value
|
||||
|
||||
def match(pattern, string, flags=0):
|
||||
"""match (pattern, string[, flags]) -> MatchObject or None
|
||||
|
||||
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.
|
||||
|
||||
"""
|
||||
|
||||
return _cachecompile(pattern, flags).match(string)
|
||||
|
||||
def search(pattern, string, flags=0):
|
||||
"""search (pattern, string[, flags]) -> MatchObject or None
|
||||
|
||||
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.
|
||||
|
||||
"""
|
||||
return _cachecompile(pattern, flags).search(string)
|
||||
|
||||
def sub(pattern, repl, string, count=0):
|
||||
"""sub(pattern, repl, string[, count=0]) -> string
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
"""
|
||||
if type(pattern) == type(''):
|
||||
pattern = _cachecompile(pattern)
|
||||
return pattern.sub(repl, string, count)
|
||||
|
||||
def subn(pattern, repl, string, count=0):
|
||||
"""subn(pattern, repl, string[, count=0]) -> (string, num substitutions)
|
||||
|
||||
Perform the same operation as sub(), but return a tuple
|
||||
(new_string, number_of_subs_made).
|
||||
|
||||
"""
|
||||
if type(pattern) == type(''):
|
||||
pattern = _cachecompile(pattern)
|
||||
return pattern.subn(repl, string, count)
|
||||
|
||||
def split(pattern, string, maxsplit=0):
|
||||
"""split(pattern, string[, maxsplit=0]) -> list of strings
|
||||
|
||||
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.
|
||||
|
||||
"""
|
||||
if type(pattern) == type(''):
|
||||
pattern = _cachecompile(pattern)
|
||||
return pattern.split(string, maxsplit)
|
||||
|
||||
def findall(pattern, string):
|
||||
"""findall(pattern, string) -> list
|
||||
|
||||
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.
|
||||
|
||||
"""
|
||||
if type(pattern) == type(''):
|
||||
pattern = _cachecompile(pattern)
|
||||
return pattern.findall(string)
|
||||
|
||||
def escape(pattern):
|
||||
"Escape all non-alphanumeric characters in pattern."
|
||||
"""escape(string) -> 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.
|
||||
|
||||
"""
|
||||
result = list(pattern)
|
||||
alphanum=string.letters+'_'+string.digits
|
||||
for i in range(len(pattern)):
|
||||
|
|
@ -74,7 +232,13 @@ def escape(pattern):
|
|||
return string.join(result, '')
|
||||
|
||||
def compile(pattern, flags=0):
|
||||
"Compile a regular expression pattern, returning a RegexObject."
|
||||
"""compile(pattern[, flags]) -> RegexObject
|
||||
|
||||
Compile a regular expression pattern into a regular expression
|
||||
object, which can be used for matching using its match() and
|
||||
search() methods.
|
||||
|
||||
"""
|
||||
groupindex={}
|
||||
code=pcre_compile(pattern, flags, groupindex)
|
||||
return RegexObject(pattern, flags, code, groupindex)
|
||||
|
|
@ -85,6 +249,17 @@ def compile(pattern, flags=0):
|
|||
#
|
||||
|
||||
class RegexObject:
|
||||
"""Holds a compiled regular expression pattern.
|
||||
|
||||
Methods:
|
||||
match Match the pattern to the beginning of a string.
|
||||
search Search a string for the presence of the pattern.
|
||||
sub Substitute occurrences of the pattern found in a string.
|
||||
subn Same as sub, but also return the number of substitutions made.
|
||||
split Split a string by the occurrences of the pattern.
|
||||
findall Find all occurrences of the pattern in a string.
|
||||
|
||||
"""
|
||||
|
||||
def __init__(self, pattern, flags, code, groupindex):
|
||||
self.code = code
|
||||
|
|
@ -93,9 +268,17 @@ class RegexObject:
|
|||
self.groupindex = groupindex
|
||||
|
||||
def search(self, string, pos=0, endpos=None):
|
||||
"""Scan through string looking for a match to the pattern, returning
|
||||
a MatchObject instance, or None if no match was found."""
|
||||
"""search(string[, pos][, endpos]) -> MatchObject or None
|
||||
|
||||
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.
|
||||
|
||||
"""
|
||||
if endpos is None or endpos>len(string):
|
||||
endpos=len(string)
|
||||
if endpos<pos: endpos=pos
|
||||
|
|
@ -110,9 +293,29 @@ class RegexObject:
|
|||
regs)
|
||||
|
||||
def match(self, string, pos=0, endpos=None):
|
||||
"""Try to apply the pattern at the start of the string, returning
|
||||
a MatchObject instance, or None if no match was found."""
|
||||
"""match(string[, pos][, endpos]) -> MatchObject or None
|
||||
|
||||
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.
|
||||
|
||||
"""
|
||||
if endpos is None or endpos>len(string):
|
||||
endpos=len(string)
|
||||
if endpos<pos: endpos=pos
|
||||
|
|
@ -126,19 +329,25 @@ class RegexObject:
|
|||
regs)
|
||||
|
||||
def sub(self, repl, string, count=0):
|
||||
"""Return the string obtained by replacing the leftmost
|
||||
non-overlapping occurrences of the pattern in string by the
|
||||
replacement repl"""
|
||||
"""sub(repl, string[, count=0]) -> string
|
||||
|
||||
Return the string obtained by replacing the leftmost
|
||||
non-overlapping occurrences of the compiled pattern in string
|
||||
by the replacement repl. If the pattern isn't found, string is
|
||||
returned unchanged.
|
||||
|
||||
Identical to the sub() function, using the compiled pattern.
|
||||
|
||||
"""
|
||||
return self.subn(repl, string, count)[0]
|
||||
|
||||
def subn(self, repl, source, count=0):
|
||||
"""Return a 2-tuple containing (new_string, number).
|
||||
new_string is the string obtained by replacing the leftmost
|
||||
non-overlapping occurrences of the pattern in the source
|
||||
string by the replacement repl. number is the number of
|
||||
substitutions that were made."""
|
||||
"""subn(repl, string[, count=0]) -> tuple
|
||||
|
||||
Perform the same operation as sub(), but return a tuple
|
||||
(new_string, number_of_subs_made).
|
||||
|
||||
"""
|
||||
if count < 0:
|
||||
raise error, "negative substitution count"
|
||||
if count == 0:
|
||||
|
|
@ -192,9 +401,16 @@ class RegexObject:
|
|||
return (string.join(results, ''), n)
|
||||
|
||||
def split(self, source, maxsplit=0):
|
||||
"""Split the source string by the occurrences of the pattern,
|
||||
returning a list containing the resulting substrings."""
|
||||
"""split(source[, maxsplit=0]) -> list of strings
|
||||
|
||||
Split string by the occurrences of the compiled pattern. If
|
||||
capturing parentheses are used in the 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.
|
||||
|
||||
"""
|
||||
if maxsplit < 0:
|
||||
raise error, "negative split count"
|
||||
if maxsplit == 0:
|
||||
|
|
@ -232,13 +448,13 @@ class RegexObject:
|
|||
return results
|
||||
|
||||
def findall(self, source):
|
||||
"""Return a list of all non-overlapping matches in the string.
|
||||
"""findall(source) -> list
|
||||
|
||||
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.
|
||||
Return a list of all non-overlapping matches of the compiled
|
||||
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.
|
||||
|
||||
"""
|
||||
pos = 0
|
||||
|
|
@ -286,6 +502,17 @@ class _Dummy:
|
|||
group = None
|
||||
|
||||
class MatchObject:
|
||||
"""Holds a compiled regular expression pattern.
|
||||
|
||||
Methods:
|
||||
start Return the index of the start of a matched substring.
|
||||
end Return the index of the end of a matched substring.
|
||||
span Return a tuple of (start, end) of a matched substring.
|
||||
groups Return a tuple of all the subgroups of the match.
|
||||
group Return one or more subgroups of the match.
|
||||
groupdict Return a dictionary of all the named subgroups of the match.
|
||||
|
||||
"""
|
||||
|
||||
def __init__(self, re, string, pos, endpos, regs):
|
||||
self.re = re
|
||||
|
|
@ -295,7 +522,14 @@ class MatchObject:
|
|||
self.regs = regs
|
||||
|
||||
def start(self, g = 0):
|
||||
"Return the start of the substring matched by group g"
|
||||
"""start([group=0]) -> int or None
|
||||
|
||||
Return the index of the start 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.
|
||||
|
||||
"""
|
||||
if type(g) == type(''):
|
||||
try:
|
||||
g = self.re.groupindex[g]
|
||||
|
|
@ -304,7 +538,14 @@ class MatchObject:
|
|||
return self.regs[g][0]
|
||||
|
||||
def end(self, g = 0):
|
||||
"Return the end of the substring matched by group g"
|
||||
"""end([group=0]) -> int or None
|
||||
|
||||
Return the indices of the 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.
|
||||
|
||||
"""
|
||||
if type(g) == type(''):
|
||||
try:
|
||||
g = self.re.groupindex[g]
|
||||
|
|
@ -313,7 +554,14 @@ class MatchObject:
|
|||
return self.regs[g][1]
|
||||
|
||||
def span(self, g = 0):
|
||||
"Return (start, end) of the substring matched by group g"
|
||||
"""span([group=0]) -> tuple
|
||||
|
||||
Return the 2-tuple (m.start(group), m.end(group)). Note that
|
||||
if group did not contribute to the match, this is (None,
|
||||
None). Group defaults to zero (meaning the whole matched
|
||||
substring).
|
||||
|
||||
"""
|
||||
if type(g) == type(''):
|
||||
try:
|
||||
g = self.re.groupindex[g]
|
||||
|
|
@ -322,7 +570,14 @@ class MatchObject:
|
|||
return self.regs[g]
|
||||
|
||||
def groups(self, default=None):
|
||||
"Return a tuple containing all subgroups of the match object"
|
||||
"""groups([default=None]) -> tuple
|
||||
|
||||
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.
|
||||
|
||||
"""
|
||||
result = []
|
||||
for g in range(1, self.re._num_regs):
|
||||
a, b = self.regs[g]
|
||||
|
|
@ -333,7 +588,29 @@ class MatchObject:
|
|||
return tuple(result)
|
||||
|
||||
def group(self, *groups):
|
||||
"Return one or more groups of the match"
|
||||
"""group([group1, group2, ...]) -> string or tuple
|
||||
|
||||
Return 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<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.
|
||||
|
||||
"""
|
||||
if len(groups) == 0:
|
||||
groups = (0,)
|
||||
result = []
|
||||
|
|
@ -358,7 +635,13 @@ class MatchObject:
|
|||
return ()
|
||||
|
||||
def groupdict(self, default=None):
|
||||
"Return a dictionary containing all named subgroups of the match"
|
||||
"""groupdict([default=None]) -> dictionary
|
||||
|
||||
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.
|
||||
|
||||
"""
|
||||
dict = {}
|
||||
for name, index in self.re.groupindex.items():
|
||||
a, b = self.regs[index]
|
||||
|
|
|
|||
Loading…
Reference in New Issue