Author: georg.brandl Date: Thu Jul 29 13:49:05 2010 New Revision: 83218 Log: #6538: fix regex documentation again -- use fictional class names "regex" and "match" but do not document them as classes, remove 1.5 compat info and use new default argument syntax where possible. Modified: python/branches/py3k/Doc/library/re.rst Modified: python/branches/py3k/Doc/library/re.rst ============================================================================== --- python/branches/py3k/Doc/library/re.rst (original) +++ python/branches/py3k/Doc/library/re.rst Thu Jul 29 13:49:05 2010 @@ -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 <re-objects>`. The functions are shortcuts +that don't require you to compile a regex object first, but miss some fine-tuning parameters. .. seealso:: @@ -546,21 +547,21 @@ -.. function:: search(pattern, string[, flags]) +.. function:: search(pattern, string, flags=0) 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 + <match-objects>`. 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 + <match-objects>`. Return ``None`` if the string does not match the pattern; + note that this is different from a zero-length match. .. note:: @@ -620,9 +621,9 @@ .. 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 + Return an :term:`iterator` yielding :ref:`match objects <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. @@ -710,107 +711,107 @@ Regular Expression Objects -------------------------- -.. class:: RegexObject - - The :class:`RegexObject` class supports the following methods and attributes: - - .. method:: RegexObject.search(string[, pos[, endpos]]) +Compiled regular expression objects support the following methods and +attributes. - 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. +.. method:: regex.search(string[, pos[, endpos]]) - 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. + Scan through *string* looking for a location where this regular expression + produces a match, and return a corresponding :ref:`match object + <match-objects>`. 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)``. - 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" + >>> 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]]) +.. method:: regex.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. + If zero or more characters at the *beginning* of *string* match this regular + expression, return a corresponding :ref:`match object <match-objects>`. + 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. + The optional *pos* and *endpos* parameters have the same meaning as for the + :meth:`~regex.search` method. - .. note:: + .. note:: - If you want to locate a match anywhere in *string*, use - :meth:`~RegexObject.search` instead. + If you want to locate a match anywhere in *string*, use + :meth:`~regex.search` instead. - >>> 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 ...> + >>> 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:: regex.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:: regex.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`. + 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:: regex.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`. + 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:: regex.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:: regex.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:: regex.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:: regex.groups - The number of capturing groups in the pattern. + The number of capturing groups in the pattern. - .. attribute:: RegexObject.groupindex +.. attribute:: regex.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:: regex.pattern - The pattern string from which the RE object was compiled. + The pattern string from which the RE object was compiled. .. _match-objects: @@ -818,178 +819,176 @@ Match Objects ------------- -.. class:: MatchObject - - 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. +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:: match.expand(template) + + Return the string obtained by doing backslash substitution on the template + string *template*, as done by the :meth:`~regex.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:: 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 + 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:: 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``. + For example: - .. 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=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``. - - For example: - - >>> m = re.match(r"(\d+)\.(\d+)", "24.1632") - >>> m.groups() - ('24', '1632') + >>> 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: + 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') + >>> 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]) +.. method:: match.groupdict(default=None) - 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: + 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'} + >>> 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]) +.. method:: match.start([group]) + 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 - *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 :: + 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)] + 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. + 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: + 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' + >>> email = "tony@tiremove_thisger.net" + >>> m = re.search("remove_this", email) + >>> email[:m.start()] + email[m.end():] + 'tony@tiger.net' - .. method:: MatchObject.span([group]) +.. method:: match.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. + For a 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:: 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:`~regex.search` or + :meth:`~regex.match` method of a :ref:`match object <match-objects>`. This + is the index into the string at which the RE engine started looking for a + match. - .. attribute:: MatchObject.endpos +.. attribute:: 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:`~regex.search` or + :meth:`~regex.match` method of a :ref:`match object <match-objects>`. This + is the index into the string beyond which the RE engine will not go. - .. attribute:: MatchObject.lastindex +.. attribute:: 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 - ``((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. + 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:: 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. + 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:: 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:`~regex.match` or + :meth:`~regex.search` method produced this match instance. - .. attribute:: MatchObject.string +.. attribute:: match.string - The string passed to :meth:`~RegexObject.match` or - :meth:`~RegexObject.search`. + The string passed to :meth:`~regex.match` or :meth:`~regex.search`. Examples @@ -1035,8 +1034,7 @@ "<Match: '354aa', groups=('a',)>" To find out what card the pair consists of, one could use the -:meth:`~MatchObject.group` method of :class:`MatchObject` in the following -manner: +:meth:`~match.group` method of the match object in the following manner: .. doctest:: @@ -1250,10 +1248,10 @@ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 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 +<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):