Context Navigation

← Previous Change
Next Change →

re.rst

Timestamp:

Mar 19, 2014, 11:31:01 PM (11 years ago)

Author:

dmik

Message:

python: Merge vendor 2.7.6 to trunk.

Location:

python/trunk

Files:

: 2 edited

. (modified) (1 prop)
Doc/library/re.rst (modified) (36 diffs)

Legend:

: Unmodified
: Added
: Removed

python/trunk
- Property svn:mergeinfo set to
  /python/vendor/Python-2.7.6 merged eligible
  /python/vendor/current merged eligible

python/trunk/Doc/library/re.rst

-              r2
+              r391
 ``[]``
+   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, although the characters they match depends on whether :const:`LOCALE`
+   or  :const:`UNICODE` mode is in force.  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 :dfn:`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'``, and ``[^^]`` will match any
+   character except ``'^'``.
+   Note that inside ``[]`` the special forms and special characters lose
+   their meanings and only the syntaxes described here are valid. For
+   example, ``+``, ``*``, ``(``, ``)``, and so on are treated as
+   literals inside ``[]``, and backreferences cannot be used inside
+   ``[]``.
+   Used to indicate a set of characters.  In a set:
+   * Characters can be listed individually, e.g. ``[amk]`` will match ``'a'``,
+     ``'m'``, or ``'k'``.
+   * Ranges of characters can be indicated by giving two characters and separating
+     them by a ``'-'``, for example ``[a-z]`` will match any lowercase ASCII letter,
+     ``[0-5][0-9]`` will match all the two-digits numbers from ``00`` to ``59``, and
+     ``[0-9A-Fa-f]`` will match any hexadecimal digit.  If ``-`` is escaped (e.g.
+     ``[a\-z]``) or if it's placed as the first or last character (e.g. ``[a-]``),
+     it will match a literal ``'-'``.
+   * Special characters lose their special meaning inside sets.  For example,
+     ``[(+*)]`` will match any of the literal characters ``'('``, ``'+'``,
+     ``'*'``, or ``')'``.
+   * Character classes such as ``\w`` or ``\S`` (defined below) are also accepted
+     inside a set, although the characters they match depends on whether
+     :const:`LOCALE` or  :const:`UNICODE` mode is in force.
+   * Characters that are not within a range can be matched by :dfn:`complementing`
+     the set.  If the first character of the set is ``'^'``, all the characters
+     that are *not* in the set will be matched.  For example, ``[^5]`` will match
+     any character except ``'5'``, and ``[^^]`` will match any character except
+     ``'^'``.  ``^`` has no special meaning if it's not the first character in
+     the set.
+   * To match a literal ``']'`` inside a set, precede it with a backslash, or
+     place it at the beginning of the set.  For example, both ``[()[\]{}]`` and
+     ``[]()[{}]`` will both match a parenthesis.
 ``'|'``
 …
 ``(?:...)``
    A non-grouping version of regular parentheses. Matches whatever regular
+   A non-capturing 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
 …
 ``(?P<name>...)``
    Similar to regular parentheses, but the substring matched by the group is
+   accessible within the rest of the regular expression via the symbolic group
+   name *name*.  Group names must be valid Python identifiers, and each group
+   name must be defined only once within a regular expression.  A symbolic group
+   is also a numbered group, just as if the group were not named.  So the group
+   named ``id`` in the example below can also be referenced as the numbered group
+   ``1``.
+   For example, if the pattern is ``(?P<id>[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 the regular
+   expression itself (using ``(?P=id)``) and replacement text given to
+   ``.sub()`` (using ``\g<id>``).
+   accessible via the symbolic group name *name*.  Group names must be valid
+   Python identifiers, and each group name must be defined only once within a
+   regular expression.  A symbolic group is also a numbered group, just as if
+   the group were not named.
+   Named groups can be referenced in three contexts.  If the pattern is
+   ``(?P<quote>['"]).*?(?P=quote)`` (i.e. matching a string quoted with either
+   single or double quotes):
+   +---------------------------------------+----------------------------------+
+   | Context of reference to group "quote" | Ways to reference it             |
+   +=======================================+==================================+
+   | in the same pattern itself            | * ``(?P=quote)`` (as shown)      |
+   |                                       | * ``\1``                         |
+   +---------------------------------------+----------------------------------+
+   | when processing match object ``m``    | * ``m.group('quote')``           |
+   |                                       | * ``m.end('quote')`` (etc.)      |
+   +---------------------------------------+----------------------------------+
+   | in a string passed to the ``repl``    | * ``\g<quote>``                  |
+   | argument of ``re.sub()``              | * ``\g<1>``                      |
+   |                                       | * ``\1``                         |
+   +---------------------------------------+----------------------------------+
 ``(?P=name)``
+   Matches whatever text was matched by the earlier group named *name*.
+   A backreference to a named group; it matches whatever text was matched by the
+   earlier group named *name*.
 ``(?#...)``
 …
    The contained pattern must only match strings of some fixed length, meaning that
    ``abc`` or ``a|b`` are allowed, but ``a*`` and ``a{3,4}`` are not.  Note that
    patterns which start with positive lookbehind assertions will never match at the
+   patterns which start with positive lookbehind assertions will not match at the
    beginning of the string being searched; you will most likely want to use the
    :func:`search` function rather than the :func:`match` function:
 …
    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
+   but not ``'thethe'`` (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
 …
    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
+   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.
+   Note that formally, ``\b`` is defined as the boundary between a ``\w`` and
+   a ``\W`` character (or vice versa), or between ``\w`` and the beginning/end
+   of the string, so the precise set of characters deemed to be alphanumeric
+   depends on the values of the ``UNICODE`` and ``LOCALE`` flags.
+   For example, ``r'\bfoo\b'`` matches ``'foo'``, ``'foo.'``, ``'(foo)'``,
+   ``'bar foo baz'`` but not ``'foobar'`` or ``'foo3'``.
+   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
+   word.  This means that ``r'py\B'`` matches ``'python'``, ``'py3'``, ``'py2'``,
+   but not ``'py'``, ``'py.'``, or ``'py!'``.
+   ``\B`` is just the opposite of ``\b``, so is also subject to the settings
    of ``LOCALE`` and ``UNICODE``.
 …
    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
+   whatever is classified as a digit in the Unicode character properties database.
+   whatever is classified as a decimal digit in the Unicode character properties
+   database.
 ``\D``
 …
 ``\s``
    When the :const:`LOCALE` and :const:`UNICODE` flags are not specified, matches
    any whitespace character; this is equivalent to the set ``[ \t\n\r\f\v]``. With
    :const:`LOCALE`, it will match this set plus whatever characters are defined as
    space for the current locale. If :const:`UNICODE` is set, this will match the
    characters ``[ \t\n\r\f\v]`` plus whatever is classified as space in the Unicode
    character properties database.
+   When the :const:`UNICODE` flag is not specified, it matches any whitespace
+   character, this is equivalent to the set ``[ \t\n\r\f\v]``. The
+   :const:`LOCALE` flag has no extra effect on matching of the space.
+   If :const:`UNICODE` is set, this will match the characters ``[ \t\n\r\f\v]``
+   plus whatever is classified as space in the Unicode character properties
+   database.
 ``\S``
    When the :const:`LOCALE` and :const:`UNICODE` flags are not specified, matches
    any non-whitespace character; this is equivalent to the set ``[^ \t\n\r\f\v]``
    With :const:`LOCALE`, it will match any character not in this set, and not
    defined as space in the current locale. If :const:`UNICODE` is set, this will
    match anything other than ``[ \t\n\r\f\v]`` and characters marked as space in
+   the Unicode character properties database.
+   When the :const:`UNICODE` flags is not specified, matches any non-whitespace
+   character; this is equivalent to the set ``[^ \t\n\r\f\v]`` The
+   :const:`LOCALE` flag has no extra effect on non-whitespace match.  If
+   :const:`UNICODE` is set, then any character not marked as space in the
+   Unicode character properties database is matched.
 ``\w``
 …
    With :const:`LOCALE`, it will match any character not in the set ``[0-9_]``, and
    not defined as alphanumeric for the current locale. If :const:`UNICODE` is set,
    this will match anything other than ``[0-9_]`` and characters marked as
    alphanumeric in the Unicode character properties database.
+   this will match anything other than ``[0-9_]`` plus characters classied as
+   not alphanumeric in the Unicode character properties database.
 ``\Z``
    Matches only at the end of the string.
+If both :const:`LOCALE` and :const:`UNICODE` flags are included for a
+particular sequence, then :const:`LOCALE` flag takes effect first followed by
+the :const:`UNICODE`.
 Most of the standard escapes supported by Python string literals are also
 …
    \r      \t      \v      \x
    \\
+(Note that ``\b`` is used to represent word boundaries, and means "backspace"
+only inside character classes.)
 Octal escapes are included in a limited form: If the first digit is a 0, or if
 …
-.. _matching-searching:
-Matching vs Searching
----------------------
-.. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org>
-Python offers two different primitive operations based on regular expressions:
-**match** checks for a match only at the beginning of the string, while
-**search** checks for a match anywhere in the string (this is what Perl does
-by default).
-Note that match may differ from search even when using a regular expression
-beginning with ``'^'``: ``'^'`` matches only at the start of the string, or in
-:const:`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.match("c", "abcdef")  # No match
-   >>> re.search("c", "abcdef") # Match
-   <_sre.SRE_Match object at ...>
 .. _contents-of-module-re:
 …
 .. function:: compile(pattern[, flags])
+.. function:: compile(pattern, flags=0)
    Compile a regular expression pattern into a regular expression object, which
 …
       programs that use only a few regular expressions at a time needn't worry
       about compiling regular expressions.
+.. data:: DEBUG
+   Display debug information about compiled expression.
 …
 .. function:: search(pattern, string[, flags])
+.. function:: search(pattern, string, flags=0)
    Scan through *string* looking for a location where the regular expression
 …
 .. function:: match(pattern, string[, flags])
+.. function:: match(pattern, string, flags=0)
    If zero or more characters at the beginning of *string* match the regular
 …
    different from a zero-length match.
+   .. note::
+      If you want to locate a match anywhere in *string*, use :func:`search`
+      instead.
+.. function:: split(pattern, string[, maxsplit=0])
+   Note that even in :const:`MULTILINE` mode, :func:`re.match` will only match
+   at the beginning of the string and not at the beginning of each line.
+   If you want to locate a match anywhere in *string*, use :func:`search`
+   instead (see also :ref:`search-vs-match`).
+.. function:: split(pattern, string, maxsplit=0, flags=0)
    Split *string* by the occurrences of *pattern*.  If capturing parentheses are
 …
       >>> re.split('\W+', 'Words, words, words.', 1)
       ['Words', 'words, words.']
+      >>> re.split('[a-f]+', '0a3B9', flags=re.IGNORECASE)
+      ['0', '3', '9']
    If there are capturing groups in the separator and it matches at the start of
 …
       ['foo\n\nbar\n']
+.. function:: findall(pattern, string[, flags])
+   .. versionchanged:: 2.7
+      Added the optional flags argument.
+.. function:: findall(pattern, string, flags=0)
    Return all non-overlapping matches of *pattern* in *string*, as a list of
 …
 .. function:: finditer(pattern, string[, flags])
+.. function:: finditer(pattern, string, flags=0)
    Return an :term:`iterator` yielding :class:`MatchObject` instances over all
 …
 .. function:: sub(pattern, repl, string[, count])
+.. function:: sub(pattern, repl, string, count=0, flags=0)
    Return the string obtained by replacing the leftmost non-overlapping occurrences
 …
    *string* is returned unchanged.  *repl* can be a string or a function; if it 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
+   converted to a single newline character, ``\r`` is converted to a carriage return, 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.
 …
       >>> re.sub('-{1,2}', dashrepl, 'pro----gram-files')
       'pro--gram files'
    The pattern may be a string or an RE object; if you need to specify regular
+   expression flags, you must use a RE object, or use embedded modifiers in a
    pattern; for example, ``sub("(?i)b+", "x", "bbbb BBBB")`` returns ``'x x'``.
+      >>> re.sub(r'\sAND\s', ' & ', 'Baked Beans And Spam', flags=re.IGNORECASE)
+      'Baked Beans & Spam'
+   The pattern may be a string or an RE object.
    The optional argument *count* is the maximum number of pattern occurrences to be
 …
    ``'-a-b-c-'``.
+   In addition to character escapes and backreferences as described above,
+   In string-type *repl* arguments, in addition to the character escapes and
+   backreferences described above,
    ``\g<name>`` will use the substring matched by the group named ``name``, as
    defined by the ``(?P<name>...)`` syntax. ``\g<number>`` uses the corresponding
 …
    substring matched by the RE.
+.. function:: subn(pattern, repl, string[, count])
+   .. versionchanged:: 2.7
+      Added the optional flags argument.
+.. function:: subn(pattern, repl, string, count=0, flags=0)
    Perform the same operation as :func:`sub`, but return a tuple ``(new_string,
    number_of_subs_made)``.
+   .. versionchanged:: 2.7
+      Added the optional flags argument.
 …
    want to match an arbitrary literal string that may have regular expression
    metacharacters in it.
+.. function:: purge()
+   Clear the regular expression cache.
 …
 --------------------------
+Compiled regular expression objects support the following methods and
+attributes:
+.. method:: RegexObject.match(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.
+   .. note::
+      If you want to locate a match anywhere in *string*, use
+      :meth:`~RegexObject.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)``.
+.. class:: RegexObject
+   The :class:`RegexObject` class supports the following methods and attributes:
+   .. method:: RegexObject.search(string[, pos[, endpos]])
+      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)``.
+      >>> 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"
+   .. method:: RegexObject.match(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.
+      The optional *pos* and *endpos* parameters have the same meaning as for the
+      :meth:`~RegexObject.search` method.
       >>> pattern = re.compile("o")
       >>> pattern.match("dog")      # No match as "o" is not at the start of "dog."
+      >>> 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.search(string[, pos[, endpos]])
+   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 *pos* and *endpos* parameters have the same meaning as for the
+   :meth:`~RegexObject.match` method.
+.. method:: RegexObject.split(string[, maxsplit=0])
+   Identical to the :func:`split` function, using the compiled pattern.
+.. method:: RegexObject.findall(string[, pos[, endpos]])
+   Identical to the :func:`findall` function, using the compiled pattern.
+.. method:: RegexObject.finditer(string[, pos[, endpos]])
+   Identical to the :func:`finditer` function, using the compiled pattern.
+.. method:: RegexObject.sub(repl, string[, count=0])
+   Identical to the :func:`sub` function, using the compiled pattern.
+.. method:: RegexObject.subn(repl, string[, count=0])
+   Identical to the :func:`subn` function, using the compiled pattern.
+.. attribute:: RegexObject.flags
+   The flags argument used when the RE object was compiled, or ``0`` if no flags
+   were provided.
+.. attribute:: RegexObject.groups
+   The number of capturing groups in the pattern.
+.. 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.
+.. attribute:: RegexObject.pattern
+   The pattern string from which the RE object was compiled.
+      If you want to locate a match anywhere in *string*, use
+      :meth:`~RegexObject.search` instead (see also :ref:`search-vs-match`).
+   .. method:: RegexObject.split(string, maxsplit=0)
+      Identical to the :func:`split` function, using the compiled pattern.
+   .. method:: RegexObject.findall(string[, pos[, endpos]])
+      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]])
+      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)
+      Identical to the :func:`sub` function, using the compiled pattern.
+   .. method:: RegexObject.subn(repl, string, count=0)
+      Identical to the :func:`subn` function, using the compiled pattern.
+   .. attribute:: RegexObject.flags
+      The regex matching flags.  This is a combination of the flags given to
+      :func:`.compile` and any ``(?...)`` inline flags in the pattern.
+   .. attribute:: RegexObject.groups
+      The number of capturing groups in the pattern.
+   .. 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.
+   .. attribute:: RegexObject.pattern
+      The pattern string from which the RE object was compiled.
 …
 -------------
+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:`~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.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+)", "Malcolm Reynolds")
+      >>> m.group('first_name')
+      'Malcolm'
+      >>> m.group('last_name')
+      'Reynolds'
+   Named groups can also be referred to by their index:
+      >>> m.group(1)
+      'Malcolm'
+      >>> 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.)
+   For example:
+      >>> 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:
+      >>> 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')
+.. 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:
+      >>> m = re.match(r"(?P<first_name>\w+) (?P<last_name>\w+)", "Malcolm Reynolds")
+      >>> m.groupdict()
+      {'first_name': 'Malcolm', 'last_name': 'Reynolds'}
+.. 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
+, 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
+   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
+   The regular expression object whose :meth:`~RegexObject.match` or
+   :meth:`~RegexObject.search` method produced this :class:`MatchObject`
+   instance.
+.. attribute:: MatchObject.string
+   The string passed to :meth:`~RegexObject.match` or
+   :meth:`~RegexObject.search`.
+.. class:: MatchObject
+   Match objects always have a boolean value of ``True``.
+   Since :meth:`~regex.match` and :meth:`~regex.search` return ``None``
+   when there is no match, you can test whether there was a match with a simple
+   ``if`` statement::
+      match = re.search(pattern, string)
+      if match:
+          process(match)
+   Match objects 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:`~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.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+)", "Malcolm Reynolds")
+         >>> m.group('first_name')
+         'Malcolm'
+         >>> m.group('last_name')
+         'Reynolds'
+      Named groups can also be referred to by their index:
+         >>> m.group(1)
+         'Malcolm'
+         >>> 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.)
+      For example:
+         >>> 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:
+         >>> 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')
+   .. 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:
+         >>> m = re.match(r"(?P<first_name>\w+) (?P<last_name>\w+)", "Malcolm Reynolds")
+         >>> m.groupdict()
+         {'first_name': 'Malcolm', 'last_name': 'Reynolds'}
+   .. 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
+, 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
+      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
+      The regular expression object whose :meth:`~RegexObject.match` or
+      :meth:`~RegexObject.search` method produced this :class:`MatchObject`
+      instance.
+   .. attribute:: MatchObject.string
+      The string passed to :meth:`~RegexObject.match` or
+      :meth:`~RegexObject.search`.
 …
 Suppose you are writing a poker program where a player's hand is represented as
 a 5-character string with each character representing a card, "a" for ace, "k"
 for king, "q" for queen, j for jack, "0" for 10, and "1" through "9"
+for king, "q" for queen, "j" for jack, "t" for 10, and "2" through "9"
 representing the card with that value.
 To see if a given string is a valid hand, one could do the following:
    >>> valid = re.compile(r"[0-9akqj]{5}$")
    >>> displaymatch(valid.match("ak05q"))  # Valid.
    "<Match: 'ak05q', groups=()>"
    >>> displaymatch(valid.match("ak05e"))  # Invalid.
    >>> displaymatch(valid.match("ak0"))    # Invalid.
+   >>> valid = re.compile(r"^[a2-9tjqk]{5}$")
+   >>> displaymatch(valid.match("akt5q"))  # Valid.
+   "<Match: 'akt5q', groups=()>"
+   >>> displaymatch(valid.match("akt5e"))  # Invalid.
+   >>> displaymatch(valid.match("akt"))    # Invalid.
    >>> displaymatch(valid.match("727ak"))  # Valid.
    "<Match: '727ak', groups=()>"
 …
 .. index:: single: scanf()
 Python does not currently have an equivalent to :cfunc:`scanf`.  Regular
+Python does not currently have an equivalent to :c:func:`scanf`.  Regular
 expressions are generally more powerful, though also more verbose, than
 :cfunc:`scanf` format strings.  The table below offers some more-or-less
 equivalent mappings between :cfunc:`scanf` format tokens and regular
+:c:func:`scanf` format strings.  The table below offers some more-or-less
+equivalent mappings between :c:func:`scanf` format tokens and regular
 expressions.
 +--------------------------------+---------------------------------------------+
 | :cfunc:`scanf` Token           | Regular Expression                          |
+| :c:func:`scanf` Token          | Regular Expression                          |
 +================================+=============================================+
 | ``%c``                         | ``.``                                       |
 …
 | ``%i``                         | ``[-+]?(0[xX][\dA-Fa-f]+|0[0-7]*|\d+)``     |
 +--------------------------------+---------------------------------------------+
 | ``%o``                         | ``0[0-7]*``                                 |
+| ``%o``                         | ``[-+]?[0-7]+``                             |
 +--------------------------------+---------------------------------------------+
 | ``%s``                         | ``\S+``                                     |
 …
 | ``%u``                         | ``\d+``                                     |
 +--------------------------------+---------------------------------------------+
 | ``%x``, ``%X``                 | ``0[xX][\dA-Fa-f]+``                        |
+| ``%x``, ``%X``                 | ``[-+]?(0[xX])?[\dA-Fa-f]+``                |
 +--------------------------------+---------------------------------------------+
 …
    /usr/sbin/sendmail - 0 errors, 4 warnings
 you would use a :cfunc:`scanf` format like ::
+you would use a :c:func:`scanf` format like ::
    %s - %d errors, %d warnings
 …
+Avoiding recursion
+^^^^^^^^^^^^^^^^^^
+If you create regular expressions that require the engine to perform a lot of
+recursion, you may encounter a :exc:`RuntimeError` exception with the message
+``maximum recursion limit`` exceeded. For example, ::
+   >>> s = 'Begin ' + 1000*'a very long string ' + 'end'
+   >>> re.match('Begin (\w| )*? end', s).end()
+   Traceback (most recent call last):
+     File "<stdin>", line 1, in ?
+     File "/usr/local/lib/python2.5/re.py", line 132, in match
+       return _compile(pattern, flags).match(string)
+   RuntimeError: maximum recursion limit exceeded
+You can often restructure your regular expression to avoid recursion.
+Starting with Python 2.3, simple uses of the ``*?`` pattern are special-cased to
+avoid recursion.  Thus, the above regular expression can avoid recursion by
+being recast as ``Begin [a-zA-Z0-9_ ]*?end``.  As a further benefit, such
+regular expressions will run faster than their recursive equivalents.
+.. _search-vs-match:
 search() vs. match()
 ^^^^^^^^^^^^^^^^^^^^
+In a nutshell, :func:`match` only attempts to match a pattern at the beginning
+of a string where :func:`search` will match a pattern anywhere in a string.
+For example:
+   >>> re.match("o", "dog")  # No match as "o" is not the first letter of "dog".
+   >>> re.search("o", "dog") # Match as search() looks everywhere in the string.
+.. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org>
+Python offers two different primitive operations based on regular expressions:
+:func:`re.match` checks for a match only at the beginning of the string, while
+:func:`re.search` checks for a match anywhere in the string (this is what Perl
+does by default).
+For example::
+   >>> re.match("c", "abcdef")  # No match
+   >>> re.search("c", "abcdef") # Match
    <_sre.SRE_Match object at ...>
+.. note::
+   The following applies only to regular expression objects like those created
+   with ``re.compile("pattern")``, not the primitives ``re.match(pattern,
+   string)`` or ``re.search(pattern, string)``.
+:func:`match` has an optional second parameter that gives an index in the string
+where the search is to start::
+   >>> pattern = re.compile("o")
+   >>> pattern.match("dog")      # No match as "o" is not at the start of "dog."
+   # Equivalent to the above expression as 0 is the default starting index:
+   >>> pattern.match("dog", 0)
+   # Match as "o" is the 2nd character of "dog" (index 0 is the first):
+   >>> pattern.match("dog", 1)
+Regular expressions beginning with ``'^'`` can be used with :func:`search` to
+restrict the match at the beginning of the string::
+   >>> re.match("c", "abcdef")  # No match
+   >>> re.search("^c", "abcdef") # No match
+   >>> re.search("^a", "abcdef")  # Match
    <_sre.SRE_Match object at ...>
+   >>> pattern.match("dog", 2)   # No match as "o" is not the 3rd character of "dog."
+Note however that in :const:`MULTILINE` mode :func:`match` only matches at the
+beginning of the string, whereas using :func:`search` with a regular expression
+beginning with ``'^'`` will match at the beginning of each line.
+   >>> re.match('X', 'A\nB\nX', re.MULTILINE)  # No match
+   >>> re.search('^X', 'A\nB\nX', re.MULTILINE)  # Match
+   <_sre.SRE_Match object at ...>
 …
 triple-quoted string syntax:
    >>> input = """Ross McFluff: 834.345.1254 155 Elm Street
+   >>> text = """Ross McFluff: 834.345.1254 155 Elm Street
    ...
    ... Ronald Heathmore: 892.345.3428 436 Finley Avenue
 …
    :options: +NORMALIZE_WHITESPACE
    >>> entries = re.split("\n+", input)
+   >>> entries = re.split("\n+", text)
    >>> entries
    ['Ross McFluff: 834.345.1254 155 Elm Street',
 …
    ...   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.'

Note: See TracChangeset for help on using the changeset viewer.

/python/vendor/Python-2.7.6	merged	eligible
/python/vendor/current	merged	eligible

Context Navigation

Changeset 391 for python/trunk/Doc/library/re.rst

Legend:

python/trunk

python/trunk/Doc/library/re.rst

Download in other formats: