Patch by Jeffrey Chang to add docstrings everywhere.

The text is condensed from the library manual.

1 files changed, 314 insertions, 31 deletions

diff --git a/Lib/re.py b/Lib/re.py
index d190363..8f6bc5f 100644
--- a/Lib/re.py
+++ b/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.
-
-        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.
+        """findall(source) -> list
+    
+        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]