From 5e49320cb4962bbbedf442cdf6fd13c8ae9b8e9b Mon Sep 17 00:00:00 2001 From: Jean Abou Samra Date: Mon, 3 May 2021 21:49:31 +0200 Subject: [PATCH 1/2] Clarify rx parameter of compileall functions This includes nesting re.Pattern (and, while at it, re.Match) in a class directive so it can be cross-referenced. --- Doc/library/compileall.rst | 10 +- Doc/library/re.rst | 437 +++++++++++++++++++------------------ 2 files changed, 226 insertions(+), 221 deletions(-) diff --git a/Doc/library/compileall.rst b/Doc/library/compileall.rst index 5c6e68f93047537..be132015987b065 100644 --- a/Doc/library/compileall.rst +++ b/Doc/library/compileall.rst @@ -166,9 +166,10 @@ Public functions If *force* is true, modules are re-compiled even if the timestamps are up to date. - If *rx* is given, its search method is called on the complete path to each + If *rx* is given, its ``search`` method is called on the complete path to each file considered for compilation, and if it returns a true value, the file - is skipped. + is skipped. This can be used to exclude files matching a regular expression, + given as a :class:`re.Pattern` object. If *quiet* is ``False`` or ``0`` (the default), the filenames and other information are printed to standard out. Set to ``1``, only errors are @@ -242,9 +243,10 @@ Public functions cases where the source file does not exist at the time the byte-code file is executed. - If *rx* is given, its search method is passed the full path name to the + If *rx* is given, its ``search`` method is passed the full path name to the file being compiled, and if it returns a true value, the file is not - compiled and ``True`` is returned. + compiled and ``True`` is returned. This can be used to exclude files matching + a regular expression, given as a :class:`re.Pattern` object. If *quiet* is ``False`` or ``0`` (the default), the filenames and other information are printed to standard out. Set to ``1``, only errors are diff --git a/Doc/library/re.rst b/Doc/library/re.rst index 9abbd8ba73616ee..2f11ceae82627a8 100644 --- a/Doc/library/re.rst +++ b/Doc/library/re.rst @@ -1004,126 +1004,128 @@ Regular Expression Objects Compiled regular expression objects support the following methods and attributes: -.. method:: Pattern.search(string[, pos[, endpos]]) +.. class:: Pattern - Scan through *string* looking for the first location where this regular - expression 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. + .. method:: 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 the first location where this regular + expression 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 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 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. - >>> pattern = re.compile("d") - >>> pattern.search("dog") # Match at index 0 - - >>> pattern.search("dog", 1) # No match; search doesn't include the "d" + 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 + + >>> pattern.search("dog", 1) # No match; search doesn't include the "d" -.. method:: Pattern.match(string[, pos[, endpos]]) - If zero or more characters at the *beginning* of *string* match this regular - 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. + .. method:: match(string[, pos[, endpos]]) - The optional *pos* and *endpos* parameters have the same meaning as for the - :meth:`~Pattern.search` method. :: + If zero or more characters at the *beginning* of *string* match this regular + 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. - >>> 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". - + The optional *pos* and *endpos* parameters have the same meaning as for the + :meth:`~Pattern.search` method. :: - If you want to locate a match anywhere in *string*, use - :meth:`~Pattern.search` instead (see also :ref:`search-vs-match`). + >>> 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". + + If you want to locate a match anywhere in *string*, use + :meth:`~Pattern.search` instead (see also :ref:`search-vs-match`). -.. method:: Pattern.fullmatch(string[, pos[, endpos]]) - If the whole *string* matches this regular 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. + .. method:: fullmatch(string[, pos[, endpos]]) - The optional *pos* and *endpos* parameters have the same meaning as for the - :meth:`~Pattern.search` method. :: + If the whole *string* matches this regular 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. - >>> pattern = re.compile("o[gh]") - >>> pattern.fullmatch("dog") # No match as "o" is not at the start of "dog". - >>> pattern.fullmatch("ogre") # No match as not the full string matches. - >>> pattern.fullmatch("doggie", 1, 3) # Matches within given limits. - + The optional *pos* and *endpos* parameters have the same meaning as for the + :meth:`~Pattern.search` method. :: - .. versionadded:: 3.4 + >>> pattern = re.compile("o[gh]") + >>> pattern.fullmatch("dog") # No match as "o" is not at the start of "dog". + >>> pattern.fullmatch("ogre") # No match as not the full string matches. + >>> pattern.fullmatch("doggie", 1, 3) # Matches within given limits. + + .. versionadded:: 3.4 -.. method:: Pattern.split(string, maxsplit=0) - Identical to the :func:`split` function, using the compiled pattern. + .. method:: split(string, maxsplit=0) + Identical to the :func:`split` function, using the compiled pattern. -.. method:: 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:`search`. + .. method:: 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:`search`. -.. method:: 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:`search`. + .. method:: 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:`search`. -.. method:: Pattern.sub(repl, string, count=0) - Identical to the :func:`sub` function, using the compiled pattern. + .. method:: sub(repl, string, count=0) + Identical to the :func:`sub` function, using the compiled pattern. -.. method:: Pattern.subn(repl, string, count=0) - Identical to the :func:`subn` function, using the compiled pattern. + .. method:: subn(repl, string, count=0) + Identical to the :func:`subn` function, using the compiled pattern. -.. attribute:: Pattern.flags - The regex matching flags. This is a combination of the flags given to - :func:`.compile`, any ``(?...)`` inline flags in the pattern, and implicit - flags such as :data:`UNICODE` if the pattern is a Unicode string. + .. attribute:: flags + The regex matching flags. This is a combination of the flags given to + :func:`.compile`, any ``(?...)`` inline flags in the pattern, and implicit + flags such as :data:`UNICODE` if the pattern is a Unicode string. -.. attribute:: Pattern.groups - The number of capturing groups in the pattern. + .. attribute:: groups + The number of capturing groups in the pattern. -.. attribute:: 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:: 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:: Pattern.pattern + .. attribute:: pattern - The pattern string from which the pattern object was compiled. + The pattern string from which the pattern object was compiled. -.. versionchanged:: 3.7 - Added support of :func:`copy.copy` and :func:`copy.deepcopy`. Compiled - regular expression objects are considered atomic. + .. versionchanged:: 3.7 + Added support of :func:`copy.copy` and :func:`copy.deepcopy`. Compiled + regular expression objects are considered atomic. .. _match-objects: @@ -1142,194 +1144,195 @@ when there is no match, you can test whether there was a match with a simple Match objects support the following methods and attributes: +.. class:: Match -.. method:: Match.expand(template) + .. method:: expand(template) - Return the string obtained by doing backslash substitution on the template - string *template*, as done by the :meth:`~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. + Return the string obtained by doing backslash substitution on the template + string *template*, as done by the :meth:`~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. - .. versionchanged:: 3.5 - Unmatched groups are replaced with an empty string. + .. versionchanged:: 3.5 + Unmatched groups are replaced with an empty string. -.. 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...)`` 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\w+) (?P\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.__getitem__(g) - - This is identical to ``m.group(g)``. This allows easier access to - an individual group from a match:: - - >>> m = re.match(r"(\w+) (\w+)", "Isaac Newton, physicist") - >>> m[0] # The entire match - 'Isaac Newton' - >>> m[1] # The first parenthesized subgroup. - 'Isaac' - >>> m[2] # The second parenthesized subgroup. - 'Newton' + .. method:: group([group1, ...]) - .. versionadded:: 3.6 + 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') -.. method:: Match.groups(default=None) + If the regular expression uses the ``(?P...)`` 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. - 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``. + A moderately complicated example:: - For example:: + >>> m = re.match(r"(?P\w+) (?P\w+)", "Malcolm Reynolds") + >>> m.group('first_name') + 'Malcolm' + >>> m.group('last_name') + 'Reynolds' + + Named groups can also be referred to by their index:: - >>> m = re.match(r"(\d+)\.(\d+)", "24.1632") - >>> m.groups() - ('24', '1632') + >>> m.group(1) + 'Malcolm' + >>> m.group(2) + 'Reynolds' - 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 a group matches multiple times, only the last match is accessible:: - >>> 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"(..)+", "a1b2c3") # Matches 3 times. + >>> m.group(1) # Returns only the last match. + 'c3' -.. method:: Match.groupdict(default=None) + .. method:: __getitem__(g) - 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:: + This is identical to ``m.group(g)``. This allows easier access to + an individual group from a match:: - >>> m = re.match(r"(?P\w+) (?P\w+)", "Malcolm Reynolds") - >>> m.groupdict() - {'first_name': 'Malcolm', 'last_name': 'Reynolds'} + >>> m = re.match(r"(\w+) (\w+)", "Isaac Newton, physicist") + >>> m[0] # The entire match + 'Isaac Newton' + >>> m[1] # The first parenthesized subgroup. + 'Isaac' + >>> m[2] # The second parenthesized subgroup. + 'Newton' + .. versionadded:: 3.6 -.. 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 :: + .. method:: groups(default=None) - m.string[m.start(g):m.end(g)] + 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``. - 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. + For example:: - An example that will remove *remove_this* from email addresses:: + >>> m = re.match(r"(\d+)\.(\d+)", "24.1632") + >>> m.groups() + ('24', '1632') - >>> email = "tony@tiremove_thisger.net" - >>> m = re.search("remove_this", email) - >>> email[:m.start()] + email[m.end():] - 'tony@tiger.net' + 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:: Match.span([group]) - 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. + .. method:: 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:: -.. attribute:: Match.pos + >>> m = re.match(r"(?P\w+) (?P\w+)", "Malcolm Reynolds") + >>> m.groupdict() + {'first_name': 'Malcolm', 'last_name': 'Reynolds'} - The value of *pos* which was passed to the :meth:`~Pattern.search` or - :meth:`~Pattern.match` method of a :ref:`regex object `. This is - the index into the string at which the RE engine started looking for a match. + .. method:: start([group]) + Match.end([group]) -.. attribute:: Match.endpos + 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 :: - The value of *endpos* which was passed to the :meth:`~Pattern.search` or - :meth:`~Pattern.match` method of a :ref:`regex object `. This is - the index into the string beyond which the RE engine will not go. + 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. -.. attribute:: Match.lastindex + An example that will remove *remove_this* from email addresses:: - 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. + >>> email = "tony@tiremove_thisger.net" + >>> m = re.search("remove_this", email) + >>> email[:m.start()] + email[m.end():] + 'tony@tiger.net' -.. attribute:: Match.lastgroup + .. method:: span([group]) - 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. + 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:: Match.re + .. attribute:: pos - The :ref:`regular expression object ` whose :meth:`~Pattern.match` or - :meth:`~Pattern.search` method produced this match instance. + The value of *pos* which was passed to the :meth:`~Pattern.search` or + :meth:`~Pattern.match` method of a :ref:`regex object `. This is + the index into the string at which the RE engine started looking for a match. -.. attribute:: Match.string + .. attribute:: endpos - The string passed to :meth:`~Pattern.match` or :meth:`~Pattern.search`. + The value of *endpos* which was passed to the :meth:`~Pattern.search` or + :meth:`~Pattern.match` method of a :ref:`regex object `. This is + the index into the string beyond which the RE engine will not go. -.. versionchanged:: 3.7 - Added support of :func:`copy.copy` and :func:`copy.deepcopy`. Match objects - are considered atomic. + .. attribute:: 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:: 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:: re + + The :ref:`regular expression object ` whose :meth:`~Pattern.match` or + :meth:`~Pattern.search` method produced this match instance. + + + .. attribute:: string + + The string passed to :meth:`~Pattern.match` or :meth:`~Pattern.search`. + + + .. versionchanged:: 3.7 + Added support of :func:`copy.copy` and :func:`copy.deepcopy`. Match objects + are considered atomic. .. _re-examples: From 015a3678fe474ced5d56a120a3a76f841060fbf6 Mon Sep 17 00:00:00 2001 From: Jean Abou Samra Date: Tue, 4 May 2021 20:41:15 +0200 Subject: [PATCH 2/2] Avoid touching re.rst, use :ref: with title and target --- Doc/library/compileall.rst | 4 +- Doc/library/re.rst | 437 ++++++++++++++++++------------------- 2 files changed, 219 insertions(+), 222 deletions(-) diff --git a/Doc/library/compileall.rst b/Doc/library/compileall.rst index be132015987b065..de34664acb84ab7 100644 --- a/Doc/library/compileall.rst +++ b/Doc/library/compileall.rst @@ -169,7 +169,7 @@ Public functions If *rx* is given, its ``search`` method is called on the complete path to each file considered for compilation, and if it returns a true value, the file is skipped. This can be used to exclude files matching a regular expression, - given as a :class:`re.Pattern` object. + given as a :ref:`re.Pattern ` object. If *quiet* is ``False`` or ``0`` (the default), the filenames and other information are printed to standard out. Set to ``1``, only errors are @@ -246,7 +246,7 @@ Public functions If *rx* is given, its ``search`` method is passed the full path name to the file being compiled, and if it returns a true value, the file is not compiled and ``True`` is returned. This can be used to exclude files matching - a regular expression, given as a :class:`re.Pattern` object. + a regular expression, given as a :ref:`re.Pattern ` object. If *quiet* is ``False`` or ``0`` (the default), the filenames and other information are printed to standard out. Set to ``1``, only errors are diff --git a/Doc/library/re.rst b/Doc/library/re.rst index 2f11ceae82627a8..9abbd8ba73616ee 100644 --- a/Doc/library/re.rst +++ b/Doc/library/re.rst @@ -1004,128 +1004,126 @@ Regular Expression Objects Compiled regular expression objects support the following methods and attributes: -.. class:: Pattern +.. method:: Pattern.search(string[, pos[, endpos]]) - .. method:: search(string[, pos[, endpos]]) - - Scan through *string* looking for the first location where this regular - expression 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. + Scan through *string* looking for the first location where this regular + expression 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 - 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 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 - - >>> pattern.search("dog", 1) # No match; search doesn't include the "d" + >>> pattern = re.compile("d") + >>> pattern.search("dog") # Match at index 0 + + >>> pattern.search("dog", 1) # No match; search doesn't include the "d" - .. method:: match(string[, pos[, endpos]]) +.. method:: Pattern.match(string[, pos[, endpos]]) - If zero or more characters at the *beginning* of *string* match this regular - 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. + If zero or more characters at the *beginning* of *string* match this regular + 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:`~Pattern.search` method. :: + The optional *pos* and *endpos* parameters have the same meaning as for the + :meth:`~Pattern.search` 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". - + >>> 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". + - If you want to locate a match anywhere in *string*, use - :meth:`~Pattern.search` instead (see also :ref:`search-vs-match`). + If you want to locate a match anywhere in *string*, use + :meth:`~Pattern.search` instead (see also :ref:`search-vs-match`). - .. method:: fullmatch(string[, pos[, endpos]]) +.. method:: Pattern.fullmatch(string[, pos[, endpos]]) - If the whole *string* matches this regular 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. + If the whole *string* matches this regular 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:`~Pattern.search` method. :: + The optional *pos* and *endpos* parameters have the same meaning as for the + :meth:`~Pattern.search` method. :: - >>> pattern = re.compile("o[gh]") - >>> pattern.fullmatch("dog") # No match as "o" is not at the start of "dog". - >>> pattern.fullmatch("ogre") # No match as not the full string matches. - >>> pattern.fullmatch("doggie", 1, 3) # Matches within given limits. - + >>> pattern = re.compile("o[gh]") + >>> pattern.fullmatch("dog") # No match as "o" is not at the start of "dog". + >>> pattern.fullmatch("ogre") # No match as not the full string matches. + >>> pattern.fullmatch("doggie", 1, 3) # Matches within given limits. + - .. versionadded:: 3.4 + .. versionadded:: 3.4 - .. method:: split(string, maxsplit=0) +.. method:: Pattern.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:: findall(string[, pos[, endpos]]) +.. method:: 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:`search`. + 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:`search`. - .. method:: finditer(string[, pos[, endpos]]) +.. method:: 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:`search`. + 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:`search`. - .. method:: sub(repl, string, count=0) +.. method:: Pattern.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:: subn(repl, string, count=0) +.. method:: Pattern.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:: flags +.. attribute:: Pattern.flags - The regex matching flags. This is a combination of the flags given to - :func:`.compile`, any ``(?...)`` inline flags in the pattern, and implicit - flags such as :data:`UNICODE` if the pattern is a Unicode string. + The regex matching flags. This is a combination of the flags given to + :func:`.compile`, any ``(?...)`` inline flags in the pattern, and implicit + flags such as :data:`UNICODE` if the pattern is a Unicode string. - .. attribute:: groups +.. attribute:: Pattern.groups - The number of capturing groups in the pattern. + The number of capturing groups in the pattern. - .. attribute:: groupindex +.. attribute:: 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. + 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:: pattern +.. attribute:: Pattern.pattern - The pattern string from which the pattern object was compiled. + The pattern string from which the pattern object was compiled. - .. versionchanged:: 3.7 - Added support of :func:`copy.copy` and :func:`copy.deepcopy`. Compiled - regular expression objects are considered atomic. +.. versionchanged:: 3.7 + Added support of :func:`copy.copy` and :func:`copy.deepcopy`. Compiled + regular expression objects are considered atomic. .. _match-objects: @@ -1144,195 +1142,194 @@ when there is no match, you can test whether there was a match with a simple Match objects support the following methods and attributes: -.. class:: Match - - .. method:: expand(template) - - Return the string obtained by doing backslash substitution on the template - string *template*, as done by the :meth:`~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. - - .. versionchanged:: 3.5 - Unmatched groups are replaced with an empty string. - - .. method:: 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...)`` 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:: Match.expand(template) - A moderately complicated example:: + Return the string obtained by doing backslash substitution on the template + string *template*, as done by the :meth:`~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. - >>> m = re.match(r"(?P\w+) (?P\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:: __getitem__(g) - - This is identical to ``m.group(g)``. This allows easier access to - an individual group from a match:: + .. versionchanged:: 3.5 + Unmatched groups are replaced with an empty string. - >>> m = re.match(r"(\w+) (\w+)", "Isaac Newton, physicist") - >>> m[0] # The entire match - 'Isaac Newton' - >>> m[1] # The first parenthesized subgroup. - 'Isaac' - >>> m[2] # The second parenthesized subgroup. - 'Newton' +.. 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...)`` 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\w+) (?P\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.__getitem__(g) + + This is identical to ``m.group(g)``. This allows easier access to + an individual group from a match:: + + >>> m = re.match(r"(\w+) (\w+)", "Isaac Newton, physicist") + >>> m[0] # The entire match + 'Isaac Newton' + >>> m[1] # The first parenthesized subgroup. + 'Isaac' + >>> m[2] # The second parenthesized subgroup. + 'Newton' - .. versionadded:: 3.6 + .. versionadded:: 3.6 - .. method:: groups(default=None) +.. 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``. + 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:: + 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:: groupdict(default=None) +.. 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\w+) (?P\w+)", "Malcolm Reynolds") - >>> m.groupdict() - {'first_name': 'Malcolm', 'last_name': 'Reynolds'} + >>> m = re.match(r"(?P\w+) (?P\w+)", "Malcolm Reynolds") + >>> m.groupdict() + {'first_name': 'Malcolm', 'last_name': 'Reynolds'} - .. method:: start([group]) - Match.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:: span([group]) +.. method:: Match.span([group]) - 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. + 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:: pos +.. attribute:: Match.pos - The value of *pos* which was passed to the :meth:`~Pattern.search` or - :meth:`~Pattern.match` method of a :ref:`regex object `. 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:`~Pattern.search` or + :meth:`~Pattern.match` method of a :ref:`regex object `. This is + the index into the string at which the RE engine started looking for a match. - .. attribute:: endpos +.. attribute:: Match.endpos - The value of *endpos* which was passed to the :meth:`~Pattern.search` or - :meth:`~Pattern.match` method of a :ref:`regex object `. 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:`~Pattern.search` or + :meth:`~Pattern.match` method of a :ref:`regex object `. This is + the index into the string beyond which the RE engine will not go. - .. attribute:: 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:: 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:: re +.. attribute:: Match.re - The :ref:`regular expression object ` whose :meth:`~Pattern.match` or - :meth:`~Pattern.search` method produced this match instance. + The :ref:`regular expression object ` whose :meth:`~Pattern.match` or + :meth:`~Pattern.search` method produced this match instance. - .. attribute:: string +.. attribute:: Match.string - The string passed to :meth:`~Pattern.match` or :meth:`~Pattern.search`. + The string passed to :meth:`~Pattern.match` or :meth:`~Pattern.search`. - .. versionchanged:: 3.7 - Added support of :func:`copy.copy` and :func:`copy.deepcopy`. Match objects - are considered atomic. +.. versionchanged:: 3.7 + Added support of :func:`copy.copy` and :func:`copy.deepcopy`. Match objects + are considered atomic. .. _re-examples: