/library/diff/re.rst.diff

--- r262/library/re.rst	2009-04-06 06:48:06.719229000 +0900
+++ r266/library/re.rst	2010-08-02 06:48:47.574872000 +0900
@@ -207,25 +207,25 @@
    currently supported extensions.
 
 ``(?iLmsux)``
    (One or more letters from the set ``'i'``, ``'L'``, ``'m'``, ``'s'``,
    ``'u'``, ``'x'``.)  The group matches the empty string; the letters
    set the corresponding flags: :const:`re.I` (ignore case),
    :const:`re.L` (locale dependent), :const:`re.M` (multi-line),
    :const:`re.S` (dot matches all), :const:`re.U` (Unicode dependent),
    and :const:`re.X` (verbose), for the entire regular expression. (The
    flags are described in :ref:`contents-of-module-re`.) This
    is useful if you wish to include the flags as part of the regular
    expression, instead of passing a *flag* argument to the
-   :func:`compile` function.
+   :func:`re.compile` function.
 
    Note that the ``(?x)`` flag changes how the expression is parsed. It should be
    used first in the expression string, or after one or more whitespace characters.
    If there are non-whitespace characters before the flag, the results are
    undefined.
 
 ``(?:...)``
    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.
 
@@ -310,25 +310,25 @@
    *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 or underscore characters, so the end of a
    word is indicated by whitespace or a non-alphanumeric, non-underscore character.
-   Note that  ``\b`` is defined as the boundary between ``\w`` and ``\ W``, so the
+   Note that  ``\b`` is defined as the boundary between ``\w`` and ``\W``, so the
    precise set of characters deemed to be alphanumeric depends on the values of the
    ``UNICODE`` and ``LOCALE`` flags.  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.  This is just the opposite of ``\b``, so is also subject to the settings
    of ``LOCALE`` and ``UNICODE``.
 
 ``\d``
    When the :const:`UNICODE` flag is not specified, matches any decimal digit; this
    is equivalent to the set ``[0-9]``.  With :const:`UNICODE`, it will match
@@ -434,27 +434,27 @@
    Values can be any of the following variables, combined using bitwise OR (the
    ``|`` operator).
 
    The sequence ::
 
       prog = re.compile(pattern)
       result = prog.match(string)
 
    is equivalent to ::
 
       result = re.match(pattern, string)
 
-   but using :func:`compile` and saving the resulting regular expression object
-   for reuse is more efficient when the expression will be used several times
-   in a single program.
+   but using :func:`re.compile` and saving the resulting regular expression
+   object for reuse is more efficient when the expression will be used several
+   times in a single program.
 
    .. note::
 
       The compiled versions of the most recent patterns passed to
       :func:`re.match`, :func:`re.search` or :func:`re.compile` are cached, so
       programs that use only a few regular expressions at a time needn't worry
       about compiling regular expressions.
 
 
 .. data:: I
           IGNORECASE
 
@@ -523,25 +523,25 @@
    string.
 
 
 .. function:: match(pattern, string[, flags])
 
    If zero or more characters at the beginning of *string* match the regular
    expression *pattern*, return a corresponding :class:`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 :meth:`search`
+      If you want to locate a match anywhere in *string*, use :func:`search`
       instead.
 
 
 .. function:: 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.)
 
@@ -651,307 +651,325 @@
 
    Perform the same operation as :func:`sub`, but return a tuple ``(new_string,
    number_of_subs_made)``.
 
 
 .. function:: 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.
 
 
+.. function:: purge()
+
+   Clear the regular expression cache.
+
+
 .. exception:: error
 
    Exception raised when a string passed to one of the functions here is not a
    valid regular expression (for example, it might contain 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.
 
 
 .. _re-objects:
 
 Regular Expression Objects
 --------------------------
 
-Compiled regular expression objects support the following methods and
-attributes:
+.. class:: RegexObject
 
+   The :class:`RegexObject` class supports the following methods and attributes:
 
-.. method:: RegexObject.match(string[, pos[, endpos]])
+   .. method:: RegexObject.search(string[, pos[, endpos]])
 
-   If zero or more characters at the beginning of *string* match this regular
-   expression, return a corresponding :class:`MatchObject` instance.  Return
-   ``None`` if the string does not match the pattern; note that this is different
-   from a zero-length match.
+      Scan through *string* looking for a location where this regular expression
+      produces a match, and return a corresponding :class:`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 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 - 1`` will be searched for a match.  If *endpos* is less
+      than *pos*, no match will be found, otherwise, if *rx* is a compiled regular
+      expression object, ``rx.search(string, 0, 50)`` is equivalent to
+      ``rx.search(string[:50], 0)``.
 
-   .. note::
+      >>> pattern = re.compile("d")
+      >>> pattern.search("dog")     # Match at index 0
+      <_sre.SRE_Match object at ...>
+      >>> pattern.search("dog", 1)  # No match; search doesn't include the "d"
 
-      If you want to locate a match anywhere in *string*, use :meth:`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 - 1`` will be searched for a match.  If *endpos* is less
-   than *pos*, no match will be found, otherwise, if *rx* is a compiled regular
-   expression object, ``rx.match(string, 0, 50)`` is equivalent to
-   ``rx.match(string[:50], 0)``.
+   .. method:: RegexObject.match(string[, pos[, endpos]])
 
-      >>> pattern = re.compile("o")
-      >>> pattern.match("dog")      # No match as "o" is not at the start of "dog."
-      >>> pattern.match("dog", 1)   # Match as "o" is the 2nd character of "dog".
-      <_sre.SRE_Match object at ...>
+      If zero or more characters at the *beginning* of *string* match this regular
+      expression, return a corresponding :class:`MatchObject` instance.  Return
+      ``None`` if the string does not match the pattern; note that this is different
+      from a zero-length match.
 
+      The optional *pos* and *endpos* parameters have the same meaning as for the
+      :meth:`~RegexObject.search` method.
 
-.. method:: RegexObject.search(string[, pos[, endpos]])
+      .. note::
 
-   Scan through *string* looking for a location where this regular expression
-   produces a match, and return a corresponding :class:`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.
+         If you want to locate a match anywhere in *string*, use
+         :meth:`~RegexObject.search` instead.
 
-   The optional *pos* and *endpos* parameters have the same meaning as for the
-   :meth:`match` method.
+      >>> pattern = re.compile("o")
+      >>> pattern.match("dog")      # No match as "o" is not at the start of "dog".
+      >>> pattern.match("dog", 1)   # Match as "o" is the 2nd character of "dog".
+      <_sre.SRE_Match object at ...>
 
 
-.. method:: RegexObject.split(string[, maxsplit=0])
+   .. method:: RegexObject.split(string[, maxsplit=0])
 
-   Identical to the :func:`split` function, using the compiled pattern.
+      Identical to the :func:`split` function, using the compiled pattern.
 
 
-.. method:: RegexObject.findall(string[, pos[, endpos]])
+   .. method:: RegexObject.findall(string[, pos[, endpos]])
 
-   Identical to the :func:`findall` function, using the compiled pattern.
+      Similar to the :func:`findall` function, using the compiled pattern, but
+      also accepts optional *pos* and *endpos* parameters that limit the search
+      region like for :meth:`match`.
 
 
-.. method:: RegexObject.finditer(string[, pos[, endpos]])
+   .. method:: RegexObject.finditer(string[, pos[, endpos]])
 
-   Identical to the :func:`finditer` function, using the compiled pattern.
+      Similar to the :func:`finditer` function, using the compiled pattern, but
+      also accepts optional *pos* and *endpos* parameters that limit the search
+      region like for :meth:`match`.
 
 
-.. method:: RegexObject.sub(repl, string[, count=0])
+   .. method:: RegexObject.sub(repl, string[, count=0])
 
-   Identical to the :func:`sub` function, using the compiled pattern.
+      Identical to the :func:`sub` function, using the compiled pattern.
 
 
-.. method:: RegexObject.subn(repl, string[, count=0])
+   .. method:: RegexObject.subn(repl, string[, count=0])
 
-   Identical to the :func:`subn` function, using the compiled pattern.
+      Identical to the :func:`subn` function, using the compiled pattern.
 
 
-.. attribute:: RegexObject.flags
+   .. attribute:: RegexObject.flags
 
-   The flags argument used when the RE object was compiled, or ``0`` if no flags
-   were provided.
+      The flags argument used when the RE object was compiled, or ``0`` if no flags
+      were provided.
 
 
-.. attribute:: RegexObject.groups
+   .. attribute:: RegexObject.groups
 
-   The number of capturing groups in the pattern.
+      The number of capturing groups in the pattern.
 
 
-.. attribute:: RegexObject.groupindex
+   .. attribute:: RegexObject.groupindex
 
-   A dictionary mapping any symbolic group names defined by ``(?P<id>)`` to group
-   numbers.  The dictionary is empty if no symbolic groups were used in the
-   pattern.
+      A dictionary mapping any symbolic group names defined by ``(?P<id>)`` to group
+      numbers.  The dictionary is empty if no symbolic groups were used in the
+      pattern.
 
 
-.. attribute:: RegexObject.pattern
+   .. attribute:: RegexObject.pattern
 
-   The pattern string from which the RE object was compiled.
+      The pattern string from which the RE object was compiled.
 
 
 .. _match-objects:
 
 Match Objects
 -------------
 
-Match objects always have a boolean value of :const:`True`, so that you can test
-whether e.g. :func:`match` resulted in a match with a simple if statement.  They
-support the following methods and attributes:
-
-
-.. method:: MatchObject.expand(template)
-
-   Return the string obtained by doing backslash substitution on the template
-   string *template*, as done by the :meth:`sub` method. Escapes such as ``\n`` are
-   converted to the appropriate characters, and numeric backreferences (``\1``,
-   ``\2``) and named backreferences (``\g<1>``, ``\g<name>``) are replaced by the
-   contents of the corresponding group.
-
-
-.. method:: MatchObject.group([group1, ...])
-
-   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
-   (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 corresponding parenthesized group.  If a
-   group number is negative or larger than the number of groups defined in the
-   pattern, an :exc:`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.
-
-      >>> m = re.match(r"(\w+) (\w+)", "Isaac Newton, physicist")
-      >>> m.group(0)       # The entire match
-      'Isaac Newton'
-      >>> m.group(1)       # The first parenthesized subgroup.
-      'Isaac'
-      >>> m.group(2)       # The second parenthesized subgroup.
-      'Newton'
-      >>> m.group(1, 2)    # Multiple arguments give us a tuple.
-      ('Isaac', 'Newton')
-
-   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 :exc:`IndexError`
-   exception is raised.
-
-   A moderately complicated example:
-
-      >>> m = re.match(r"(?P<first_name>\w+) (?P<last_name>\w+)", "Malcom Reynolds")
-      >>> m.group('first_name')
-      'Malcom'
-      >>> m.group('last_name')
-      'Reynolds'
-
-   Named groups can also be referred to by their index:
-
-      >>> m.group(1)
-      'Malcom'
-      >>> m.group(2)
-      'Reynolds'
-
-   If a group matches multiple times, only the last match is accessible:
-
-      >>> m = re.match(r"(..)+", "a1b2c3")  # Matches 3 times.
-      >>> m.group(1)                        # Returns only the last match.
-      'c3'
-
-
-.. method:: MatchObject.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.)
+.. class:: MatchObject
 
-   For example:
+   Match Objects always have a boolean value of :const:`True`, so that you can test
+   whether e.g. :func:`match` resulted in a match with a simple if statement.  They
+   support the following methods and attributes:
 
-      >>> m = re.match(r"(\d+)\.(\d+)", "24.1632")
-      >>> m.groups()
-      ('24', '1632')
 
-   If we make the decimal place and everything after it optional, not all groups
-   might participate in the match.  These groups will default to ``None`` unless
-   the *default* argument is given:
+   .. method:: MatchObject.expand(template)
 
-      >>> m = re.match(r"(\d+)\.?(\d+)?", "24")
-      >>> m.groups()      # Second group defaults to None.
-      ('24', None)
-      >>> m.groups('0')   # Now, the second group defaults to '0'.
-      ('24', '0')
+      Return the string obtained by doing backslash substitution on the template
+      string *template*, as done by the :meth:`~RegexObject.sub` method.  Escapes
+      such as ``\n`` are converted to the appropriate characters, and numeric
+      backreferences (``\1``, ``\2``) and named backreferences (``\g<1>``,
+      ``\g<name>``) are replaced by the contents of the corresponding group.
 
 
-.. method:: MatchObject.groupdict([default])
+   .. method:: MatchObject.group([group1, ...])
 
-   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``.  For example:
+      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
+      (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 corresponding parenthesized group.  If a
+      group number is negative or larger than the number of groups defined in the
+      pattern, an :exc:`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.
 
-      >>> m = re.match(r"(?P<first_name>\w+) (?P<last_name>\w+)", "Malcom Reynolds")
-      >>> m.groupdict()
-      {'first_name': 'Malcom', 'last_name': 'Reynolds'}
+         >>> m = re.match(r"(\w+) (\w+)", "Isaac Newton, physicist")
+         >>> m.group(0)       # The entire match
+         'Isaac Newton'
+         >>> m.group(1)       # The first parenthesized subgroup.
+         'Isaac'
+         >>> m.group(2)       # The second parenthesized subgroup.
+         'Newton'
+         >>> m.group(1, 2)    # Multiple arguments give us a tuple.
+         ('Isaac', 'Newton')
 
+      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 :exc:`IndexError`
+      exception is raised.
 
-.. method:: MatchObject.start([group])
-            MatchObject.end([group])
+      A moderately complicated example:
 
-   Return the indices of the start and end of the substring matched by *group*;
-   *group* defaults to zero (meaning the whole matched substring). Return ``-1`` 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 = re.match(r"(?P<first_name>\w+) (?P<last_name>\w+)", "Malcolm Reynolds")
+         >>> m.group('first_name')
+         'Malcolm'
+         >>> m.group('last_name')
+         'Reynolds'
 
-      m.string[m.start(g):m.end(g)]
+      Named groups can also be referred to by their index:
 
-   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 :exc:`IndexError` exception.
+         >>> m.group(1)
+         'Malcolm'
+         >>> m.group(2)
+         'Reynolds'
 
-   An example that will remove *remove_this* from email addresses:
+      If a group matches multiple times, only the last match is accessible:
 
-      >>> email = "tony@tiremove_thisger.net"
-      >>> m = re.search("remove_this", email)
-      >>> email[:m.start()] + email[m.end():]
-      'tony@tiger.net'
+         >>> m = re.match(r"(..)+", "a1b2c3")  # Matches 3 times.
+         >>> m.group(1)                        # Returns only the last match.
+         'c3'
 
 
-.. method:: MatchObject.span([group])
+   .. method:: MatchObject.groups([default])
 
-   For :class:`MatchObject` *m*, return the 2-tuple ``(m.start(group),
-   m.end(group))``. Note that if *group* did not contribute to the match, this is
-   ``(-1, -1)``.  *group* defaults to zero, the entire match.
+      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.)
 
+      For example:
 
-.. attribute:: MatchObject.pos
+         >>> m = re.match(r"(\d+)\.(\d+)", "24.1632")
+         >>> m.groups()
+         ('24', '1632')
 
-   The value of *pos* which was passed to the :func:`search` or :func:`match`
-   method of the :class:`RegexObject`.  This is the index into the string at which
-   the RE engine started looking for a match.
+      If we make the decimal place and everything after it optional, not all groups
+      might participate in the match.  These groups will default to ``None`` unless
+      the *default* argument is given:
 
+         >>> m = re.match(r"(\d+)\.?(\d+)?", "24")
+         >>> m.groups()      # Second group defaults to None.
+         ('24', None)
+         >>> m.groups('0')   # Now, the second group defaults to '0'.
+         ('24', '0')
 
-.. attribute:: MatchObject.endpos
 
-   The value of *endpos* which was passed to the :func:`search` or :func:`match`
-   method of the :class:`RegexObject`.  This is the index into the string beyond
-   which the RE engine will not go.
+   .. method:: MatchObject.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``.  For example:
 
-.. attribute:: MatchObject.lastindex
+         >>> m = re.match(r"(?P<first_name>\w+) (?P<last_name>\w+)", "Malcolm Reynolds")
+         >>> m.groupdict()
+         {'first_name': 'Malcolm', 'last_name': 'Reynolds'}
 
-   The integer index of the last matched capturing group, or ``None`` if no group
-   was matched at all. For example, the expressions ``(a)b``, ``((a)(b))``, and
-   ``((ab))`` will have ``lastindex == 1`` if applied to the string ``'ab'``, while
-   the expression ``(a)(b)`` will have ``lastindex == 2``, if applied to the same
-   string.
+
+   .. method:: MatchObject.start([group])
+               MatchObject.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 ``-1`` 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 :exc:`IndexError` exception.
+
+      An example that will remove *remove_this* from email addresses:
+
+         >>> email = "tony@tiremove_thisger.net"
+         >>> m = re.search("remove_this", email)
+         >>> email[:m.start()] + email[m.end():]
+         'tony@tiger.net'
+
+
+   .. method:: MatchObject.span([group])
+
+      For :class:`MatchObject` *m*, return the 2-tuple ``(m.start(group),
+      m.end(group))``. Note that if *group* did not contribute to the match, this is
+      ``(-1, -1)``.  *group* defaults to zero, the entire match.
+
+
+   .. attribute:: MatchObject.pos
+
+      The value of *pos* which was passed to the :meth:`~RegexObject.search` or
+      :meth:`~RegexObject.match` method of the :class:`RegexObject`.  This is the
+      index into the string at which the RE engine started looking for a match.
+
+
+   .. attribute:: MatchObject.endpos
+
+      The value of *endpos* which was passed to the :meth:`~RegexObject.search` or
+      :meth:`~RegexObject.match` method of the :class:`RegexObject`.  This is the
+      index into the string beyond which the RE engine will not go.
+
+
+   .. attribute:: MatchObject.lastindex
+
+      The integer index of the last matched capturing group, or ``None`` if no group
+      was matched at all. For example, the expressions ``(a)b``, ``((a)(b))``, and
+      ``((ab))`` will have ``lastindex == 1`` if applied to the string ``'ab'``, while
+      the expression ``(a)(b)`` will have ``lastindex == 2``, if applied to the same
+      string.
 
 
-.. attribute:: MatchObject.lastgroup
+   .. attribute:: MatchObject.lastgroup
 
-   The name of the last matched capturing group, or ``None`` if the group didn't
-   have a name, or if no group was matched at all.
+      The name of the last matched capturing group, or ``None`` if the group didn't
+      have a name, or if no group was matched at all.
 
 
-.. attribute:: MatchObject.re
+   .. attribute:: MatchObject.re
 
-   The regular expression object whose :meth:`match` or :meth:`search` method
-   produced this :class:`MatchObject` instance.
+      The regular expression object whose :meth:`~RegexObject.match` or
+      :meth:`~RegexObject.search` method produced this :class:`MatchObject`
+      instance.
 
 
-.. attribute:: MatchObject.string
+   .. attribute:: MatchObject.string
 
-   The string passed to :func:`match` or :func:`search`.
+      The string passed to :meth:`~RegexObject.match` or
+      :meth:`~RegexObject.search`.
 
 
 Examples
 --------
 
 
 Checking For a Pair
 ^^^^^^^^^^^^^^^^^^^
 
 In this example, we'll use the following helper function to display match
 objects a little more gracefully:
 
@@ -978,26 +996,27 @@
    "<Match: '727ak', groups=()>"
 
 That last hand, ``"727ak"``, contained a pair, or two of the same valued cards.
 To match this with a regular expression, one could use backreferences as such:
 
    >>> pair = re.compile(r".*(.).*\1")
    >>> displaymatch(pair.match("717ak"))     # Pair of 7s.
    "<Match: '717', groups=('7',)>"
    >>> displaymatch(pair.match("718ak"))     # No pairs.
    >>> displaymatch(pair.match("354aa"))     # Pair of aces.
    "<Match: '354aa', groups=('a',)>"
 
-To find out what card the pair consists of, one could use the :func:`group`
-method of :class:`MatchObject` in the following manner:
+To find out what card the pair consists of, one could use the
+:meth:`~MatchObject.group` method of :class:`MatchObject` in the following
+manner:
 
 .. doctest::
 
    >>> pair.match("717ak").group(1)
    '7'
 
    # Error because re.match() returns None, which doesn't have a group() method:
    >>> pair.match("718ak").group(1)
    Traceback (most recent call last):
      File "<pyshell#23>", line 1, in <module>
        re.match(r".*(.).*\1", "718ak").group(1)
    AttributeError: 'NoneType' object has no attribute 'group'
@@ -1170,27 +1189,27 @@
 ^^^^^^^^^^^^
 
 :func:`sub` replaces every occurrence of a pattern with a string or the
 result of a function.  This example demonstrates using :func:`sub` with
 a function to "munge" text, or randomize the order of all the characters
 in each word of a sentence except for the first and last characters::
 
    >>> def repl(m):
    ...   inner_word = list(m.group(2))
    ...   random.shuffle(inner_word)
    ...   return m.group(1) + "".join(inner_word) + m.group(3)
    >>> text = "Professor Abdolmalek, please report your absences promptly."
-   >>> re.sub("(\w)(\w+)(\w)", repl, text)
+   >>> re.sub(r"(\w)(\w+)(\w)", repl, text)
    'Poefsrosr Aealmlobdk, pslaee reorpt your abnseces plmrptoy.'
-   >>> re.sub("(\w)(\w+)(\w)", repl, text)
+   >>> re.sub(r"(\w)(\w+)(\w)", repl, text)
    'Pofsroser Aodlambelk, plasee reoprt yuor asnebces potlmrpy.'
 
 
 Finding all Adverbs
 ^^^^^^^^^^^^^^^^^^^
 
 :func:`findall` matches *all* occurrences of a pattern, not just the first
 one as :func:`search` does.  For example, if one was a writer and wanted to
 find all of the adverbs in some text, he or she might use :func:`findall` in
 the following manner:
 
    >>> text = "He was carefully disguised but captured quickly by police."