| \section{\module{re} --- |
| Regular expression operations} |
| \declaremodule{standard}{re} |
| \moduleauthor{Andrew M. Kuchling}{amk1@bigfoot.com} |
| \moduleauthor{Fredrik Lundh}{effbot@telia.com} |
| \sectionauthor{Andrew M. Kuchling}{amk1@bigfoot.com} |
| |
| |
| \modulesynopsis{Regular expression search and match operations with a |
| Perl-style expression syntax.} |
| |
| |
| This module provides regular expression matching operations similar to |
| those found in Perl. Regular expression pattern strings may not |
| contain null bytes, but can specify the null byte using the |
| \code{\e\var{number}} notation. Both patterns and strings to be |
| searched can be Unicode strings as well as 8-bit strings. The |
| \module{re} module is always available. |
| |
| Regular expressions use the backslash character (\character{\e}) to |
| indicate special forms or to allow special characters to be used |
| without invoking their special meaning. This collides with Python's |
| usage of the same character for the same purpose in string literals; |
| for example, to match a literal backslash, one might have to write |
| \code{'\e\e\e\e'} as the pattern string, because the regular expression |
| must be \samp{\e\e}, and each backslash must be expressed as |
| \samp{\e\e} inside a regular Python string literal. |
| |
| The solution is to use Python's raw string notation for regular |
| expression patterns; backslashes are not handled in any special way in |
| a string literal prefixed with \character{r}. So \code{r"\e n"} is a |
| two-character string containing \character{\e} and \character{n}, |
| while \code{"\e n"} is a one-character string containing a newline. |
| Usually patterns will be expressed in Python code using this raw |
| string notation. |
| |
| \strong{Implementation note:} |
| The \module{re}\refstmodindex{pre} module has two distinct |
| implementations: \module{sre} is the default implementation and |
| includes Unicode support, but may run into stack limitations for some |
| patterns. Though this will be fixed for a future release of Python, |
| the older implementation (without Unicode support) is still available |
| as the \module{pre}\refstmodindex{pre} module. |
| |
| |
| \begin{seealso} |
| \seetitle{Mastering Regular Expressions}{Book on regular expressions |
| by Jeffrey Friedl, published by O'Reilly. The Python |
| material in this book dates from before the \refmodule{re} |
| module, but it covers writing good regular expression |
| patterns in great detail.} |
| \end{seealso} |
| |
| |
| \subsection{Regular Expression Syntax \label{re-syntax}} |
| |
| A regular expression (or RE) specifies a set of strings that matches |
| it; the functions in this module let you check if a particular string |
| matches a given regular expression (or if a given regular expression |
| matches a particular string, which comes down to the same thing). |
| |
| Regular expressions can be concatenated to form new regular |
| expressions; if \emph{A} and \emph{B} are both regular expressions, |
| then \emph{AB} is also a regular expression. If a string \emph{p} |
| matches A and another string \emph{q} matches B, the string \emph{pq} |
| will match AB if \emph{A} and \emph{B} do no specify boundary |
| conditions that are no longer satisfied by \emph{pq}. Thus, complex |
| expressions can easily be constructed from simpler primitive |
| expressions like the ones described here. For details of the theory |
| and implementation of regular expressions, consult the Friedl book |
| referenced below, or almost any textbook about compiler construction. |
| |
| A brief explanation of the format of regular expressions follows. For |
| further information and a gentler presentation, consult the Regular |
| Expression HOWTO, accessible from \url{http://www.python.org/doc/howto/}. |
| |
| Regular expressions can contain both special and ordinary characters. |
| Most ordinary characters, like \character{A}, \character{a}, or |
| \character{0}, are the simplest regular expressions; they simply match |
| themselves. You can concatenate ordinary characters, so \regexp{last} |
| matches the string \code{'last'}. (In the rest of this section, we'll |
| write RE's in \regexp{this special style}, usually without quotes, and |
| strings to be matched \code{'in single quotes'}.) |
| |
| Some characters, like \character{|} or \character{(}, are special. |
| Special characters either stand for classes of ordinary characters, or |
| affect how the regular expressions around them are interpreted. |
| |
| The special characters are: |
| |
| \begin{list}{}{\leftmargin 0.7in \labelwidth 0.65in} |
| |
| \item[\character{.}] (Dot.) In the default mode, this matches any |
| character except a newline. If the \constant{DOTALL} flag has been |
| specified, this matches any character including a newline. |
| |
| \item[\character{\^}] (Caret.) Matches the start of the string, and in |
| \constant{MULTILINE} mode also matches immediately after each newline. |
| |
| \item[\character{\$}] Matches the end of the string or just before the |
| newline at the end of the string, and in \constant{MULTILINE} mode |
| also matches before a newline. \regexp{foo} matches both 'foo' and |
| 'foobar', while the regular expression \regexp{foo\$} matches only |
| 'foo'. More interestingly, searching for \regexp{foo\e d} in |
| 'foo1\textbackslash nfoo2\textbackslash n' matches 'foo2' normally, |
| but 'foo1' in \constant{MULTILINE} mode. |
| |
| \item[\character{*}] Causes the resulting RE to |
| match 0 or more repetitions of the preceding RE, as many repetitions |
| as are possible. \regexp{ab*} will |
| match 'a', 'ab', or 'a' followed by any number of 'b's. |
| |
| \item[\character{+}] Causes the |
| resulting RE to match 1 or more repetitions of the preceding RE. |
| \regexp{ab+} will match 'a' followed by any non-zero number of 'b's; it |
| will not match just 'a'. |
| |
| \item[\character{?}] Causes the resulting RE to |
| match 0 or 1 repetitions of the preceding RE. \regexp{ab?} will |
| match either 'a' or 'ab'. |
| |
| \item[\code{*?}, \code{+?}, \code{??}] The \character{*}, |
| \character{+}, and \character{?} qualifiers are all \dfn{greedy}; they |
| match as much text as possible. Sometimes this behaviour isn't |
| desired; if the RE \regexp{<.*>} is matched against |
| \code{'<H1>title</H1>'}, it will match the entire string, and not just |
| \code{'<H1>'}. Adding \character{?} after the qualifier makes it |
| perform the match in \dfn{non-greedy} or \dfn{minimal} fashion; as |
| \emph{few} characters as possible will be matched. Using \regexp{.*?} |
| in the previous expression will match only \code{'<H1>'}. |
| |
| \item[\code{\{\var{m}\}}] |
| Specifies that exactly \var{m} copies of the previous RE should be |
| matched; fewer matches cause the entire RE not to match. For example, |
| \regexp{a\{6\}} will match exactly six \character{a} characters, but |
| not five. |
| |
| \item[\code{\{\var{m},\var{n}\}}] Causes the resulting RE to match from |
| \var{m} to \var{n} repetitions of the preceding RE, attempting to |
| match as many repetitions as possible. For example, \regexp{a\{3,5\}} |
| will match from 3 to 5 \character{a} characters. Omitting \var{n} |
| specifies an infinite upper bound; you can't omit \var{m}. As an |
| example, \regexp{a\{4,\}b} will match \code{aaaab}, a thousand |
| \character{a} characters followed by a \code{b}, but not \code{aaab}. |
| The comma may not be omitted or the modifier would be confused with |
| the previously described form. |
| |
| \item[\code{\{\var{m},\var{n}\}?}] Causes the resulting RE to |
| match from \var{m} to \var{n} repetitions of the preceding RE, |
| attempting to match as \emph{few} repetitions as possible. This is |
| the non-greedy version of the previous qualifier. For example, on the |
| 6-character string \code{'aaaaaa'}, \regexp{a\{3,5\}} will match 5 |
| \character{a} characters, while \regexp{a\{3,5\}?} will only match 3 |
| characters. |
| |
| \item[\character{\e}] Either escapes special characters (permitting |
| you to match characters like \character{*}, \character{?}, and so |
| forth), or signals a special sequence; special sequences are discussed |
| below. |
| |
| If you're not using a raw string to |
| express the pattern, remember that Python also uses the |
| backslash as an escape sequence in string literals; if the escape |
| sequence isn't recognized by Python's parser, the backslash and |
| subsequent character are included in the resulting string. However, |
| if Python would recognize the resulting sequence, the backslash should |
| be repeated twice. This is complicated and hard to understand, so |
| it's highly recommended that you use raw strings for all but the |
| simplest expressions. |
| |
| \item[\code{[]}] 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 \character{-}. Special |
| characters are not active inside sets. For example, \regexp{[akm\$]} |
| will match any of the characters \character{a}, \character{k}, |
| \character{m}, or \character{\$}; \regexp{[a-z]} |
| will match any lowercase letter, and \code{[a-zA-Z0-9]} matches any |
| letter or digit. Character classes such as \code{\e w} or \code{\e S} |
| (defined below) are also acceptable inside a range. If you want to |
| include a \character{]} or a \character{-} inside a set, precede it with a |
| backslash, or place it as the first character. The |
| pattern \regexp{[]]} will match \code{']'}, for example. |
| |
| You can match the characters not within a range by \dfn{complementing} |
| the set. This is indicated by including a \character{\^} as the first |
| character of the set; \character{\^} elsewhere will simply match the |
| \character{\^} character. For example, \regexp{[{\^}5]} will match |
| any character except \character{5}. |
| |
| \item[\character{|}]\code{A|B}, where A and B can be arbitrary REs, |
| creates a regular expression that will match either A or B. An |
| arbitrary number of REs can be separated by the \character{|} in this |
| way. This can be used inside groups (see below) as well. REs |
| separated by \character{|} are tried from left to right, and the first |
| one that allows the complete pattern to match is considered the |
| accepted branch. This means that if \code{A} matches, \code{B} will |
| never be tested, even if it would produce a longer overall match. In |
| other words, the \character{|} operator is never greedy. To match a |
| literal \character{|}, use \regexp{\e|}, or enclose it inside a |
| character class, as in \regexp{[|]}. |
| |
| \item[\code{(...)}] Matches whatever regular expression is inside the |
| parentheses, and indicates the start and end of a group; the contents |
| of a group can be retrieved after a match has been performed, and can |
| be matched later in the string with the \regexp{\e \var{number}} special |
| sequence, described below. To match the literals \character{(} or |
| \character{)}, use \regexp{\e(} or \regexp{\e)}, or enclose them |
| inside a character class: \regexp{[(] [)]}. |
| |
| \item[\code{(?...)}] This is an extension notation (a \character{?} |
| following a \character{(} is not meaningful otherwise). The first |
| character after the \character{?} |
| determines what the meaning and further syntax of the construct is. |
| Extensions usually do not create a new group; |
| \regexp{(?P<\var{name}>...)} is the only exception to this rule. |
| Following are the currently supported extensions. |
| |
| \item[\code{(?iLmsux)}] (One or more letters from the set \character{i}, |
| \character{L}, \character{m}, \character{s}, \character{u}, |
| \character{x}.) The group matches the empty string; the letters set |
| the corresponding flags (\constant{re.I}, \constant{re.L}, |
| \constant{re.M}, \constant{re.S}, \constant{re.U}, \constant{re.X}) |
| for the entire regular expression. This is useful if you wish to |
| include the flags as part of the regular expression, instead of |
| passing a \var{flag} argument to the \function{compile()} function. |
| |
| Note that the \regexp{(?x)} flag changes how the expression is parsed. |
| It should be used first in the expression string, or after one or more |
| whitespace characters. If there are non-whitespace characters before |
| the flag, the results are undefined. |
| |
| \item[\code{(?:...)}] A non-grouping version of regular parentheses. |
| Matches whatever regular expression is inside the parentheses, but the |
| substring matched by the |
| group \emph{cannot} be retrieved after performing a match or |
| referenced later in the pattern. |
| |
| \item[\code{(?P<\var{name}>...)}] Similar to regular parentheses, but |
| the substring matched by the group is accessible via the symbolic group |
| name \var{name}. Group names must be valid Python identifiers. A |
| symbolic group is also a numbered group, just as if the group were not |
| named. So the group named 'id' in the example above can also be |
| referenced as the numbered group 1. |
| |
| For example, if the pattern is |
| \regexp{(?P<id>[a-zA-Z_]\e w*)}, the group can be referenced by its |
| name in arguments to methods of match objects, such as |
| \code{m.group('id')} or \code{m.end('id')}, and also by name in |
| pattern text (for example, \regexp{(?P=id)}) and replacement text |
| (such as \code{\e g<id>}). |
| |
| \item[\code{(?P=\var{name})}] Matches whatever text was matched by the |
| earlier group named \var{name}. |
| |
| \item[\code{(?\#...)}] A comment; the contents of the parentheses are |
| simply ignored. |
| |
| \item[\code{(?=...)}] Matches if \regexp{...} matches next, but doesn't |
| consume any of the string. This is called a lookahead assertion. For |
| example, \regexp{Isaac (?=Asimov)} will match \code{'Isaac~'} only if it's |
| followed by \code{'Asimov'}. |
| |
| \item[\code{(?!...)}] Matches if \regexp{...} doesn't match next. This |
| is a negative lookahead assertion. For example, |
| \regexp{Isaac (?!Asimov)} will match \code{'Isaac~'} only if it's \emph{not} |
| followed by \code{'Asimov'}. |
| |
| \item[\code{(?<=...)}] Matches if the current position in the string |
| is preceded by a match for \regexp{...} that ends at the current |
| position. This is called a positive lookbehind assertion. |
| \regexp{(?<=abc)def} will match \samp{abcdef}, since the lookbehind |
| will back up 3 characters and check if the contained pattern matches. |
| The contained pattern must only match strings of some fixed length, |
| meaning that \regexp{abc} or \regexp{a|b} are allowed, but \regexp{a*} |
| isn't. |
| |
| \item[\code{(?<!...)}] Matches if the current position in the string |
| is not preceded by a match for \regexp{...}. This |
| is called a negative lookbehind assertion. Similar to positive lookbehind |
| assertions, the contained pattern must only match strings of some |
| fixed length. |
| |
| \end{list} |
| |
| The special sequences consist of \character{\e} and a character from the |
| list below. If the ordinary character is not on the list, then the |
| resulting RE will match the second character. For example, |
| \regexp{\e\$} matches the character \character{\$}. |
| |
| \begin{list}{}{\leftmargin 0.7in \labelwidth 0.65in} |
| |
| \item[\code{\e \var{number}}] Matches the contents of the group of the |
| same number. Groups are numbered starting from 1. For example, |
| \regexp{(.+) \e 1} matches \code{'the the'} or \code{'55 55'}, but not |
| \code{'the end'} (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 \var{number} |
| is 0, or \var{number} is 3 octal digits long, it will not be interpreted |
| as a group match, but as the character with octal value \var{number}. |
| Inside the \character{[} and \character{]} of a character class, all numeric |
| escapes are treated as characters. |
| |
| \item[\code{\e A}] Matches only at the start of the string. |
| |
| \item[\code{\e b}] Matches the empty string, but only at the |
| beginning or end of a word. A word is defined as a sequence of |
| alphanumeric characters, so the end of a word is indicated by |
| whitespace or a non-alphanumeric character. Inside a character range, |
| \regexp{\e b} represents the backspace character, for compatibility with |
| Python's string literals. |
| |
| \item[\code{\e B}] Matches the empty string, but only when it is |
| \emph{not} at the beginning or end of a word. |
| |
| \item[\code{\e d}]Matches any decimal digit; this is |
| equivalent to the set \regexp{[0-9]}. |
| |
| \item[\code{\e D}]Matches any non-digit character; this is |
| equivalent to the set \regexp{[{\^}0-9]}. |
| |
| \item[\code{\e s}]Matches any whitespace character; this is |
| equivalent to the set \regexp{[ \e t\e n\e r\e f\e v]}. |
| |
| \item[\code{\e S}]Matches any non-whitespace character; this is |
| equivalent to the set \regexp{[\^\ \e t\e n\e r\e f\e v]}. |
| |
| \item[\code{\e w}]When the \constant{LOCALE} and \constant{UNICODE} |
| flags are not specified, |
| matches any alphanumeric character; this is equivalent to the set |
| \regexp{[a-zA-Z0-9_]}. With \constant{LOCALE}, it will match the set |
| \regexp{[0-9_]} plus whatever characters are defined as letters for |
| the current locale. If \constant{UNICODE} is set, this will match the |
| characters \regexp{[0-9_]} plus whatever is classified as alphanumeric |
| in the Unicode character properties database. |
| |
| \item[\code{\e W}]When the \constant{LOCALE} and \constant{UNICODE} |
| flags are not specified, matches any non-alphanumeric character; this |
| is equivalent to the set \regexp{[{\^}a-zA-Z0-9_]}. With |
| \constant{LOCALE}, it will match any character not in the set |
| \regexp{[0-9_]}, and not defined as a letter for the current locale. |
| If \constant{UNICODE} is set, this will match anything other than |
| \regexp{[0-9_]} and characters marked at alphanumeric in the Unicode |
| character properties database. |
| |
| \item[\code{\e Z}]Matches only at the end of the string. |
| |
| \item[\code{\e \e}] Matches a literal backslash. |
| |
| \end{list} |
| |
| |
| \subsection{Matching vs. Searching \label{matching-searching}} |
| \sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org} |
| |
| Python offers two different primitive operations based on regular |
| expressions: match and search. If you are accustomed to Perl's |
| semantics, the search operation is what you're looking for. See the |
| \function{search()} function and corresponding method of compiled |
| regular expression objects. |
| |
| Note that match may differ from search using a regular expression |
| beginning with \character{\^}: \character{\^} matches only at the |
| start of the string, or in \constant{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 \var{pos} argument |
| regardless of whether a newline precedes it. |
| |
| % Examples from Tim Peters: |
| \begin{verbatim} |
| re.compile("a").match("ba", 1) # succeeds |
| re.compile("^a").search("ba", 1) # fails; 'a' not at start |
| re.compile("^a").search("\na", 1) # fails; 'a' not at start |
| re.compile("^a", re.M).search("\na", 1) # succeeds |
| re.compile("^a", re.M).search("ba", 1) # fails; no preceding \n |
| \end{verbatim} |
| |
| |
| \subsection{Module Contents} |
| \nodename{Contents of Module re} |
| |
| The module defines the following functions and constants, and an exception: |
| |
| |
| \begin{funcdesc}{compile}{pattern\optional{, flags}} |
| Compile a regular expression pattern into a regular expression |
| object, which can be used for matching using its \function{match()} and |
| \function{search()} methods, described below. |
| |
| The expression's behaviour can be modified by specifying a |
| \var{flags} value. Values can be any of the following variables, |
| combined using bitwise OR (the \code{|} operator). |
| |
| The sequence |
| |
| \begin{verbatim} |
| prog = re.compile(pat) |
| result = prog.match(str) |
| \end{verbatim} |
| |
| is equivalent to |
| |
| \begin{verbatim} |
| result = re.match(pat, str) |
| \end{verbatim} |
| |
| but the version using \function{compile()} is more efficient when the |
| expression will be used several times in a single program. |
| %(The compiled version of the last pattern passed to |
| %\function{re.match()} or \function{re.search()} is cached, so |
| %programs that use only a single regular expression at a time needn't |
| %worry about compiling regular expressions.) |
| \end{funcdesc} |
| |
| \begin{datadesc}{I} |
| \dataline{IGNORECASE} |
| Perform case-insensitive matching; expressions like \regexp{[A-Z]} |
| will match lowercase letters, too. This is not affected by the |
| current locale. |
| \end{datadesc} |
| |
| \begin{datadesc}{L} |
| \dataline{LOCALE} |
| Make \regexp{\e w}, \regexp{\e W}, \regexp{\e b}, and |
| \regexp{\e B} dependent on the current locale. |
| \end{datadesc} |
| |
| \begin{datadesc}{M} |
| \dataline{MULTILINE} |
| When specified, the pattern character \character{\^} matches at the |
| beginning of the string and at the beginning of each line |
| (immediately following each newline); and the pattern character |
| \character{\$} matches at the end of the string and at the end of each |
| line (immediately preceding each newline). By default, \character{\^} |
| matches only at the beginning of the string, and \character{\$} only |
| at the end of the string and immediately before the newline (if any) |
| at the end of the string. |
| \end{datadesc} |
| |
| \begin{datadesc}{S} |
| \dataline{DOTALL} |
| Make the \character{.} special character match any character at all, |
| including a newline; without this flag, \character{.} will match |
| anything \emph{except} a newline. |
| \end{datadesc} |
| |
| \begin{datadesc}{U} |
| \dataline{UNICODE} |
| Make \regexp{\e w}, \regexp{\e W}, \regexp{\e b}, and |
| \regexp{\e B} dependent on the Unicode character properties database. |
| \versionadded{2.0} |
| \end{datadesc} |
| |
| \begin{datadesc}{X} |
| \dataline{VERBOSE} |
| This flag allows you to write regular expressions that look nicer. |
| Whitespace within the pattern is ignored, |
| except when in a character class or preceded by an unescaped |
| backslash, and, when a line contains a \character{\#} neither in a |
| character class or preceded by an unescaped backslash, all characters |
| from the leftmost such \character{\#} through the end of the line are |
| ignored. |
| % XXX should add an example here |
| \end{datadesc} |
| |
| |
| \begin{funcdesc}{search}{pattern, string\optional{, flags}} |
| Scan through \var{string} looking for a location where the regular |
| expression \var{pattern} produces a match, and return a |
| corresponding \class{MatchObject} instance. |
| Return \code{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. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{match}{pattern, string\optional{, flags}} |
| If zero or more characters at the beginning of \var{string} match |
| the regular expression \var{pattern}, return a corresponding |
| \class{MatchObject} instance. Return \code{None} if the string does not |
| match the pattern; note that this is different from a zero-length |
| match. |
| |
| \strong{Note:} If you want to locate a match anywhere in |
| \var{string}, use \method{search()} instead. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{split}{pattern, string\optional{, maxsplit\code{ = 0}}} |
| Split \var{string} by the occurrences of \var{pattern}. If |
| capturing parentheses are used in \var{pattern}, then the text of all |
| groups in the pattern are also returned as part of the resulting list. |
| If \var{maxsplit} is nonzero, at most \var{maxsplit} splits |
| occur, and the remainder of the string is returned as the final |
| element of the list. (Incompatibility note: in the original Python |
| 1.5 release, \var{maxsplit} was ignored. This has been fixed in |
| later releases.) |
| |
| \begin{verbatim} |
| >>> re.split('\W+', 'Words, words, words.') |
| ['Words', 'words', 'words', ''] |
| >>> re.split('(\W+)', 'Words, words, words.') |
| ['Words', ', ', 'words', ', ', 'words', '.', ''] |
| >>> re.split('\W+', 'Words, words, words.', 1) |
| ['Words', 'words, words.'] |
| \end{verbatim} |
| |
| This function combines and extends the functionality of |
| the old \function{regsub.split()} and \function{regsub.splitx()}. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{findall}{pattern, string} |
| Return a list of all non-overlapping matches of \var{pattern} in |
| \var{string}. If one or more groups are present in the pattern, |
| return a list of groups; this will be a list of tuples if the |
| pattern has more than one group. Empty matches are included in the |
| result. |
| \versionadded{1.5.2} |
| \end{funcdesc} |
| |
| \begin{funcdesc}{sub}{pattern, repl, string\optional{, count}} |
| Return the string obtained by replacing the leftmost non-overlapping |
| occurrences of \var{pattern} in \var{string} by the replacement |
| \var{repl}. If the pattern isn't found, \var{string} is returned |
| unchanged. \var{repl} can be a string or a function; if it is a |
| string, any backslash escapes in it are processed. That is, |
| \samp{\e n} is converted to a single newline character, \samp{\e r} |
| is converted to a linefeed, and so forth. Unknown escapes such as |
| \samp{\e j} are left alone. Backreferences, such as \samp{\e6}, are |
| replaced with the substring matched by group 6 in the pattern. For |
| example: |
| |
| \begin{verbatim} |
| >>> re.sub(r'def\s+([a-zA-Z_][a-zA-Z_0-9]*)\s*\(\s*\):', |
| ... r'static PyObject*\npy_\1(void)\n{', |
| ... 'def myfunc():') |
| 'static PyObject*\npy_myfunc(void)\n{' |
| \end{verbatim} |
| |
| If \var{repl} is a function, it is called for every non-overlapping |
| occurrence of \var{pattern}. The function takes a single match |
| object argument, and returns the replacement string. For example: |
| |
| \begin{verbatim} |
| >>> def dashrepl(matchobj): |
| .... if matchobj.group(0) == '-': return ' ' |
| .... else: return '-' |
| >>> re.sub('-{1,2}', dashrepl, 'pro----gram-files') |
| 'pro--gram files' |
| \end{verbatim} |
| |
| 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, \samp{sub("(?i)b+", "x", "bbbb |
| BBBB")} returns \code{'x x'}. |
| |
| The optional argument \var{count} is the maximum number of pattern |
| occurrences to be replaced; \var{count} must be a non-negative |
| integer. If omitted or zero, all occurrences will be replaced. |
| Empty matches for the pattern are replaced only when not adjacent to |
| a previous match, so \samp{sub('x*', '-', 'abc')} returns |
| \code{'-a-b-c-'}. |
| |
| In addition to character escapes and backreferences as described |
| above, \samp{\e g<name>} will use the substring matched by the group |
| named \samp{name}, as defined by the \regexp{(?P<name>...)} syntax. |
| \samp{\e g<number>} uses the corresponding group number; |
| \samp{\e g<2>} is therefore equivalent to \samp{\e 2}, but isn't |
| ambiguous in a replacement such as \samp{\e g<2>0}. \samp{\e 20} |
| would be interpreted as a reference to group 20, not a reference to |
| group 2 followed by the literal character \character{0}. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{subn}{pattern, repl, string\optional{, count}} |
| Perform the same operation as \function{sub()}, but return a tuple |
| \code{(\var{new_string}, \var{number_of_subs_made})}. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{escape}{string} |
| Return \var{string} with all non-alphanumerics backslashed; this is |
| useful if you want to match an arbitrary literal string that may have |
| regular expression metacharacters in it. |
| \end{funcdesc} |
| |
| \begin{excdesc}{error} |
| Exception raised when a string passed to one of the functions here |
| is not a valid regular expression (for example, it might contain |
| unmatched parentheses) or when some other error occurs during |
| compilation or matching. It is never an error if a string contains |
| no match for a pattern. |
| \end{excdesc} |
| |
| |
| \subsection{Regular Expression Objects \label{re-objects}} |
| |
| Compiled regular expression objects support the following methods and |
| attributes: |
| |
| \begin{methoddesc}[RegexObject]{search}{string\optional{, pos\optional{, |
| endpos}}} |
| Scan through \var{string} looking for a location where this regular |
| expression produces a match, and return a |
| corresponding \class{MatchObject} instance. Return \code{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 \var{pos} and \var{endpos} parameters have the same |
| meaning as for the \method{match()} method. |
| \end{methoddesc} |
| |
| \begin{methoddesc}[RegexObject]{match}{string\optional{, pos\optional{, |
| endpos}}} |
| If zero or more characters at the beginning of \var{string} match |
| this regular expression, return a corresponding |
| \class{MatchObject} instance. Return \code{None} if the string does not |
| match the pattern; note that this is different from a zero-length |
| match. |
| |
| \strong{Note:} If you want to locate a match anywhere in |
| \var{string}, use \method{search()} instead. |
| |
| The optional second parameter \var{pos} gives an index in the string |
| where the search is to start; it defaults to \code{0}. This is not |
| completely equivalent to slicing the string; the \code{'\^'} 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 \var{endpos} limits how far the string will |
| be searched; it will be as if the string is \var{endpos} characters |
| long, so only the characters from \var{pos} to \var{endpos} will be |
| searched for a match. |
| \end{methoddesc} |
| |
| \begin{methoddesc}[RegexObject]{split}{string\optional{, |
| maxsplit\code{ = 0}}} |
| Identical to the \function{split()} function, using the compiled pattern. |
| \end{methoddesc} |
| |
| \begin{methoddesc}[RegexObject]{findall}{string} |
| Identical to the \function{findall()} function, using the compiled pattern. |
| \end{methoddesc} |
| |
| \begin{methoddesc}[RegexObject]{sub}{repl, string\optional{, count\code{ = 0}}} |
| Identical to the \function{sub()} function, using the compiled pattern. |
| \end{methoddesc} |
| |
| \begin{methoddesc}[RegexObject]{subn}{repl, string\optional{, |
| count\code{ = 0}}} |
| Identical to the \function{subn()} function, using the compiled pattern. |
| \end{methoddesc} |
| |
| |
| \begin{memberdesc}[RegexObject]{flags} |
| The flags argument used when the RE object was compiled, or |
| \code{0} if no flags were provided. |
| \end{memberdesc} |
| |
| \begin{memberdesc}[RegexObject]{groupindex} |
| A dictionary mapping any symbolic group names defined by |
| \regexp{(?P<\var{id}>)} to group numbers. The dictionary is empty if no |
| symbolic groups were used in the pattern. |
| \end{memberdesc} |
| |
| \begin{memberdesc}[RegexObject]{pattern} |
| The pattern string from which the RE object was compiled. |
| \end{memberdesc} |
| |
| |
| \subsection{Match Objects \label{match-objects}} |
| |
| \class{MatchObject} instances support the following methods and |
| attributes: |
| |
| \begin{methoddesc}[MatchObject]{expand}{template} |
| Return the string obtained by doing backslash substitution on the |
| template string \var{template}, as done by the \method{sub()} method. |
| Escapes such as \samp{\e n} are converted to the appropriate |
| characters, and numeric backreferences (\samp{\e 1}, \samp{\e 2}) and |
| named backreferences (\samp{\e g<1>}, \samp{\e g<name>}) are replaced |
| by the contents of the corresponding group. |
| \end{methoddesc} |
| |
| \begin{methoddesc}[MatchObject]{group}{\optional{group1, \moreargs}} |
| 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, \var{group1} defaults to zero (the whole match |
| is returned). |
| If a \var{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 the corresponding parenthesized group. If a |
| group number is negative or larger than the number of groups defined |
| in the pattern, an \exception{IndexError} exception is raised. |
| If a group is contained in a part of the pattern that did not match, |
| the corresponding result is \code{None}. If a group is contained in a |
| part of the pattern that matched multiple times, the last match is |
| returned. |
| |
| If the regular expression uses the \regexp{(?P<\var{name}>...)} syntax, |
| the \var{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 \exception{IndexError} exception is raised. |
| |
| A moderately complicated example: |
| |
| \begin{verbatim} |
| m = re.match(r"(?P<int>\d+)\.(\d*)", '3.14') |
| \end{verbatim} |
| |
| After performing this match, \code{m.group(1)} is \code{'3'}, as is |
| \code{m.group('int')}, and \code{m.group(2)} is \code{'14'}. |
| \end{methoddesc} |
| |
| \begin{methoddesc}[MatchObject]{groups}{\optional{default}} |
| Return a tuple containing all the subgroups of the match, from 1 up to |
| however many groups are in the pattern. The \var{default} argument is |
| used for groups that did not participate in the match; it defaults to |
| \code{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.) |
| \end{methoddesc} |
| |
| \begin{methoddesc}[MatchObject]{groupdict}{\optional{default}} |
| Return a dictionary containing all the \emph{named} subgroups of the |
| match, keyed by the subgroup name. The \var{default} argument is |
| used for groups that did not participate in the match; it defaults to |
| \code{None}. |
| \end{methoddesc} |
| |
| \begin{methoddesc}[MatchObject]{start}{\optional{group}} |
| \funcline{end}{\optional{group}} |
| Return the indices of the start and end of the substring |
| matched by \var{group}; \var{group} defaults to zero (meaning the whole |
| matched substring). |
| Return \code{-1} if \var{group} exists but |
| did not contribute to the match. For a match object |
| \var{m}, and a group \var{g} that did contribute to the match, the |
| substring matched by group \var{g} (equivalent to |
| \code{\var{m}.group(\var{g})}) is |
| |
| \begin{verbatim} |
| m.string[m.start(g):m.end(g)] |
| \end{verbatim} |
| |
| Note that |
| \code{m.start(\var{group})} will equal \code{m.end(\var{group})} if |
| \var{group} matched a null string. For example, after \code{\var{m} = |
| re.search('b(c?)', 'cba')}, \code{\var{m}.start(0)} is 1, |
| \code{\var{m}.end(0)} is 2, \code{\var{m}.start(1)} and |
| \code{\var{m}.end(1)} are both 2, and \code{\var{m}.start(2)} raises |
| an \exception{IndexError} exception. |
| \end{methoddesc} |
| |
| \begin{methoddesc}[MatchObject]{span}{\optional{group}} |
| For \class{MatchObject} \var{m}, return the 2-tuple |
| \code{(\var{m}.start(\var{group}), \var{m}.end(\var{group}))}. |
| Note that if \var{group} did not contribute to the match, this is |
| \code{(-1, -1)}. Again, \var{group} defaults to zero. |
| \end{methoddesc} |
| |
| \begin{memberdesc}[MatchObject]{pos} |
| The value of \var{pos} which was passed to the |
| \function{search()} or \function{match()} function. This is the index |
| into the string at which the RE engine started looking for a match. |
| \end{memberdesc} |
| |
| \begin{memberdesc}[MatchObject]{endpos} |
| The value of \var{endpos} which was passed to the |
| \function{search()} or \function{match()} function. This is the index |
| into the string beyond which the RE engine will not go. |
| \end{memberdesc} |
| |
| \begin{memberdesc}[MatchObject]{lastgroup} |
| The name of the last matched capturing group, or \code{None} if the |
| group didn't have a name, or if no group was matched at all. |
| \end{memberdesc} |
| |
| \begin{memberdesc}[MatchObject]{lastindex} |
| The integer index of the last matched capturing group, or \code{None} |
| if no group was matched at all. |
| \end{memberdesc} |
| |
| \begin{memberdesc}[MatchObject]{re} |
| The regular expression object whose \method{match()} or |
| \method{search()} method produced this \class{MatchObject} instance. |
| \end{memberdesc} |
| |
| \begin{memberdesc}[MatchObject]{string} |
| The string passed to \function{match()} or \function{search()}. |
| \end{memberdesc} |