Index: Doc/library/re.rst =================================================================== --- Doc/library/re.rst (revision 83215) +++ Doc/library/re.rst (working copy) @@ -33,8 +33,9 @@ string notation. It is important to note that most regular expression operations are available as -module-level functions and :class:`RegexObject` methods. The functions are -shortcuts that don't require you to compile a regex object first, but miss some +module-level functions and methods on +:ref:`compiled regular expressions `. The functions are shortcuts +that don't require you to compile a regex object first, but miss some fine-tuning parameters. .. seealso:: @@ -549,18 +550,18 @@ .. function:: search(pattern, string[, flags]) Scan through *string* looking for a location where the regular expression - *pattern* 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. + *pattern* produces a match, and return a corresponding + :ref:`match object `. 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. .. function:: match(pattern, string, flags=0) 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. + expression *pattern*, return a corresponding + :ref:`match object `. Return ``None`` if the string does + not match the pattern; note that this is different from a zero-length match. .. note:: @@ -620,11 +621,11 @@ .. function:: finditer(pattern, string, flags=0) - Return an :term:`iterator` yielding :class:`MatchObject` instances over all - non-overlapping matches for the RE *pattern* in *string*. The *string* is - scanned left-to-right, and matches are returned in the order found. Empty - matches are included in the result unless they touch the beginning of another - match. + Return an :term:`iterator` yielding + :ref:`match objects ` over all non-overlapping matches for + the RE *pattern* in *string*. The *string* is scanned left-to-right, and + matches are returned in the order found. Empty matches are included in the + result unless they touch the beginning of another match. .. function:: sub(pattern, repl, string, count=0, flags=0) @@ -710,16 +711,19 @@ Regular Expression Objects -------------------------- -.. class:: RegexObject +.. class:: _sre.SRE_Pattern - The :class:`RegexObject` class supports the following methods and attributes: + Compiled regular expression objects support the following methods and + attributes. - .. method:: RegexObject.search(string[, pos[, endpos]]) + .. method:: _sre.SRE_Pattern.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. + produces a match, and return a corresponding + :ref:`match object `. 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 @@ -740,20 +744,20 @@ >>> pattern.search("dog", 1) # No match; search doesn't include the "d" - .. method:: RegexObject.match(string[, pos[, endpos]]) + .. method:: _sre.SRE_Pattern.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. + expression, return a corresponding :ref:`match object `. + 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. + :meth:`~_sre.SRE_Pattern.search` method. .. note:: If you want to locate a match anywhere in *string*, use - :meth:`~RegexObject.search` instead. + :meth:`~_sre.SRE_Pattern.search` instead. >>> pattern = re.compile("o") >>> pattern.match("dog") # No match as "o" is not at the start of "dog". @@ -761,54 +765,54 @@ <_sre.SRE_Match object at ...> - .. method:: RegexObject.split(string[, maxsplit=0]) + .. method:: _sre.SRE_Pattern.split(string[, maxsplit=0]) Identical to the :func:`split` function, using the compiled pattern. - .. method:: RegexObject.findall(string[, pos[, endpos]]) + .. method:: _sre.SRE_Pattern.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]]) + .. method:: _sre.SRE_Pattern.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]) + .. method:: _sre.SRE_Pattern.sub(repl, string[, count=0]) Identical to the :func:`sub` function, using the compiled pattern. - .. method:: RegexObject.subn(repl, string[, count=0]) + .. method:: _sre.SRE_Pattern.subn(repl, string[, count=0]) Identical to the :func:`subn` function, using the compiled pattern. - .. attribute:: RegexObject.flags + .. attribute:: _sre.SRE_Pattern.flags The flags argument used when the RE object was compiled, or ``0`` if no flags were provided. - .. attribute:: RegexObject.groups + .. attribute:: _sre.SRE_Pattern.groups The number of capturing groups in the pattern. - .. attribute:: RegexObject.groupindex + .. attribute:: _sre.SRE_Pattern.groupindex A dictionary mapping any symbolic group names defined by ``(?P)`` to group numbers. The dictionary is empty if no symbolic groups were used in the pattern. - .. attribute:: RegexObject.pattern + .. attribute:: _sre.SRE_Pattern.pattern The pattern string from which the RE object was compiled. @@ -818,23 +822,24 @@ Match Objects ------------- -.. class:: MatchObject +.. class:: _sre.SRE_Match - Match Objects always have a boolean value of :const:`True`, so that you can test + 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) + .. method:: _sre.SRE_Match.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``) are replaced by the contents of the corresponding group. + string *template*, as done by the :meth:`~_sre.SRE_Pattern.sub` method. + Escapes such as ``\n`` are converted to the appropriate characters, + and numeric backreferences (``\1``, ``\2``) and named backreferences + (``\g<1>``, ``\g``) are replaced by the contents of the + corresponding group. - .. method:: MatchObject.group([group1, ...]) + .. method:: _sre.SRE_Match.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 @@ -885,14 +890,11 @@ 'c3' - .. method:: MatchObject.groups(default=None) + .. method:: _sre.SRE_Match.groups(default=None) 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.) + did not participate in the match; it defaults to ``None``. For example: @@ -911,7 +913,7 @@ ('24', '0') - .. method:: MatchObject.groupdict([default]) + .. method:: _sre.SRE_Match.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 @@ -922,8 +924,8 @@ {'first_name': 'Malcolm', 'last_name': 'Reynolds'} - .. method:: MatchObject.start([group]) - MatchObject.end([group]) + .. method:: _sre.SRE_Match.start([group]) + _sre.SRE_Match.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 @@ -946,28 +948,30 @@ 'tony@tiger.net' - .. method:: MatchObject.span([group]) + .. method:: _sre.SRE_Match.span([group]) - For :class:`MatchObject` *m*, return the 2-tuple ``(m.start(group), + For :class:`_sre.SRE_Match` *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 + .. attribute:: _sre.SRE_Match.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. + The value of *pos* which was passed to the + :meth:`~_sre.SRE_Pattern.search` or :meth:`~_sre.SRE_Pattern.match` + method of a :ref:`match object `. This is the index into + the string at which the RE engine started looking for a match. - .. attribute:: MatchObject.endpos + .. attribute:: _sre.SRE_Match.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. + The value of *endpos* which was passed to the + :meth:`~_sre.SRE_Pattern.search` or :meth:`~_sre.SRE_Pattern.match` + method of a :ref:`match object `. This is the index + into the string beyond which the RE engine will not go. - .. attribute:: MatchObject.lastindex + .. attribute:: _sre.SRE_Match.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 @@ -976,23 +980,23 @@ string. - .. attribute:: MatchObject.lastgroup + .. attribute:: _sre.SRE_Match.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 + .. attribute:: _sre.SRE_Match.re - The regular expression object whose :meth:`~RegexObject.match` or - :meth:`~RegexObject.search` method produced this :class:`MatchObject` - instance. + The regular expression object whose :meth:`~_sre.SRE_Pattern.match` or + :meth:`~_sre.SRE_Pattern.search` method produced this + :class:`_sre.SRE_Match` instance. - .. attribute:: MatchObject.string + .. attribute:: _sre.SRE_Match.string - The string passed to :meth:`~RegexObject.match` or - :meth:`~RegexObject.search`. + The string passed to :meth:`~_sre.SRE_Pattern.match` or + :meth:`~_sre.SRE_Pattern.search`. Examples @@ -1038,7 +1042,7 @@ "" To find out what card the pair consists of, one could use the -:meth:`~MatchObject.group` method of :class:`MatchObject` in the following +:meth:`~_sre.SRE_Match.group` method of :class:`_sre.SRE_Match` in the following manner: .. doctest:: @@ -1253,10 +1257,11 @@ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ If one wants more information about all matches of a pattern than the matched -text, :func:`finditer` is useful as it provides instances of -:class:`MatchObject` instead of strings. Continuing with the previous example, -if one was a writer who wanted to find all of the adverbs *and their positions* -in some text, he or she would use :func:`finditer` in the following manner: +text, :func:`finditer` is useful as it provides +:ref:`match objects ` instead of strings. Continuing with the +previous example, if one was a writer who wanted to find all of the adverbs +*and their positions* in some text, he or she would use :func:`finditer` in +the following manner: >>> text = "He was carefully disguised but captured quickly by police." >>> for m in re.finditer(r"\w+ly", text):