6.2.re — Regular expression operations

Source code:Lib/re.py

This module provides regular expression matching operations similar tothose found in Perl.

Both patterns and strings to be searched can be Unicode strings (str)as well as 8-bit strings (bytes).However, Unicode strings and 8-bit strings cannot be mixed:that is, you cannot match a Unicode string with a byte pattern orvice-versa; similarly, when asking for a substitution, the replacementstring must be of the same type as both the pattern and the search string.

Regular expressions use the backslash character ('\') to indicatespecial forms or to allow special characters to be used without invokingtheir special meaning. This collides with Python’s usage of the samecharacter for the same purpose in string literals; for example, to matcha literal backslash, one might have to write'\\\\' as the patternstring, because the regular expression must be\\, and eachbackslash must be expressed as\\ inside a regular Python stringliteral.

The solution is to use Python’s raw string notation for regular expressionpatterns; backslashes are not handled in any special way in a string literalprefixed with'r'. Sor"\n" is a two-character string containing'\' and'n', while"\n" is a one-character string containing anewline. Usually patterns will be expressed in Python code using this rawstring notation.

It is important to note that most regular expression operations are available asmodule-level functions and methods oncompiled regular expressions. The functions are shortcutsthat don’t require you to compile a regex object first, but miss somefine-tuning parameters.

See also

The third-partyregex module,which has an API compatible with the standard libraryre module,but offers additional functionality and a more thorough Unicode support.

6.2.1. Regular Expression Syntax

A regular expression (or RE) specifies a set of strings that matches it; thefunctions in this module let you check if a particular string matches a givenregular expression (or if a given regular expression matches a particularstring, which comes down to the same thing).

Regular expressions can be concatenated to form new regular expressions; ifAandB are both regular expressions, thenAB is also a regular expression.In general, if a stringp matchesA and another stringq matchesB, thestringpq will match AB. This holds unlessA orB contain low precedenceoperations; boundary conditions betweenA andB; or have numbered groupreferences. Thus, complex expressions can easily be constructed from simplerprimitive expressions like the ones described here. For details of the theoryand implementation of regular expressions, consult the Friedl book[Frie09],or almost any textbook about compiler construction.

A brief explanation of the format of regular expressions follows. For furtherinformation and a gentler presentation, consult theRegular Expression HOWTO.

Regular expressions can contain both special and ordinary characters. Mostordinary characters, like'A','a', or'0', are the simplest regularexpressions; they simply match themselves. You can concatenate ordinarycharacters, solast matches the string'last'. (In the rest of thissection, we’ll write RE’s inthisspecialstyle, usually without quotes, andstrings to be matched'insinglequotes'.)

Some characters, like'|' or'(', are special. Specialcharacters either stand for classes of ordinary characters, or affecthow the regular expressions around them are interpreted.

Repetition qualifiers (*,+,?,{m,n}, etc) cannot bedirectly nested. This avoids ambiguity with the non-greedy modifier suffix?, and with other modifiers in other implementations. To apply a secondrepetition to an inner repetition, parentheses may be used. For example,the expression(?:a{6})* matches any multiple of six'a' characters.

The special characters are:

.
(Dot.) In the default mode, this matches any character except a newline. IftheDOTALL flag has been specified, this matches any characterincluding a newline.
^
(Caret.) Matches the start of the string, and inMULTILINE mode alsomatches immediately after each newline.
$
Matches the end of the string or just before the newline at the end of thestring, and inMULTILINE mode also matches before a newline.foomatches both ‘foo’ and ‘foobar’, while the regular expressionfoo$ matchesonly ‘foo’. More interestingly, searching forfoo.$ in'foo1\nfoo2\n'matches ‘foo2’ normally, but ‘foo1’ inMULTILINE mode; searching fora single$ in'foo\n' will find two (empty) matches: one just beforethe newline, and one at the end of the string.
*
Causes the resulting RE to match 0 or more repetitions of the preceding RE, asmany repetitions as are possible.ab* will match ‘a’, ‘ab’, or ‘a’ followedby any number of ‘b’s.
+
Causes the resulting RE to match 1 or more repetitions of the preceding RE.ab+ will match ‘a’ followed by any non-zero number of ‘b’s; it will notmatch just ‘a’.
?
Causes the resulting RE to match 0 or 1 repetitions of the preceding RE.ab? will match either ‘a’ or ‘ab’.
*?,+?,??
The'*','+', and'?' qualifiers are allgreedy; they matchas much text as possible. Sometimes this behaviour isn’t desired; if the RE<.*> is matched against'<a>b<c>', it will match the entirestring, and not just'<a>'. Adding? after the qualifier makes itperform the match innon-greedy orminimal fashion; asfewcharacters as possible will be matched. Using the RE<.*?> will matchonly'<a>'.
{m}
Specifies that exactlym copies of the previous RE should be matched; fewermatches cause the entire RE not to match. For example,a{6} will matchexactly six'a' characters, but not five.
{m,n}
Causes the resulting RE to match fromm ton repetitions of the precedingRE, attempting to match as many repetitions as possible. For example,a{3,5} will match from 3 to 5'a' characters. Omittingm specifies alower bound of zero, and omittingn specifies an infinite upper bound. As anexample,a{4,}b will match'aaaab' or a thousand'a' charactersfollowed by a'b', but not'aaab'. The comma may not be omitted or themodifier would be confused with the previously described form.
{m,n}?
Causes the resulting RE to match fromm ton repetitions of the precedingRE, attempting to match asfew repetitions as possible. This is thenon-greedy version of the previous qualifier. For example, on the6-character string'aaaaaa',a{3,5} will match 5'a' characters,whilea{3,5}? will only match 3 characters.
\

Either escapes special characters (permitting you to match characters like'*','?', and so forth), or signals a special sequence; specialsequences are discussed below.

If you’re not using a raw string to express the pattern, remember that Pythonalso uses the backslash as an escape sequence in string literals; if the escapesequence isn’t recognized by Python’s parser, the backslash and subsequentcharacter are included in the resulting string. However, if Python wouldrecognize the resulting sequence, the backslash should be repeated twice. Thisis complicated and hard to understand, so it’s highly recommended that you useraw strings for all but the simplest expressions.

[]

Used to indicate a set of characters. In a set:

  • Characters can be listed individually, e.g.[amk] will match'a','m', or'k'.
  • Ranges of characters can be indicated by giving two characters and separatingthem by a'-', for example[a-z] will match any lowercase ASCII letter,[0-5][0-9] will match all the two-digits numbers from00 to59, and[0-9A-Fa-f] will match any hexadecimal digit. If- is escaped (e.g.[a\-z]) or if it’s placed as the first or last character(e.g.[-a] or[a-]), it will match a literal'-'.
  • Special characters lose their special meaning inside sets. For example,[(+*)] will match any of the literal characters'(','+','*', or')'.
  • Character classes such as\w or\S (defined below) are also acceptedinside a set, although the characters they match depends on whetherASCII orLOCALE mode is in force.
  • Characters that are not within a range can be matched bycomplementingthe set. If the first character of the set is'^', all the charactersthat arenot in the set will be matched. For example,[^5] will matchany character except'5', and[^^] will match any character except'^'.^ has no special meaning if it’s not the first character inthe set.
  • To match a literal']' inside a set, precede it with a backslash, orplace it at the beginning of the set. For example, both[()[\]{}] and[]()[{}] will both match a parenthesis.
  • Support of nested sets and set operations as inUnicode TechnicalStandard #18 might be added in the future. This would change thesyntax, so to facilitate this change aFutureWarning will be raisedin ambiguous cases for the time being.That include sets starting with a literal'[' or containing literalcharacter sequences'--','&&','~~', and'||'. Toavoid a warning escape them with a backslash.

Changed in version 3.7:FutureWarning is raised if a character set contains constructsthat will change semantically in the future.

|
A|B, whereA andB can be arbitrary REs, creates a regular expression thatwill match eitherA orB. An arbitrary number of REs can be separated by the'|' in this way. This can be used inside groups (see below) as well. Asthe target string is scanned, REs separated by'|' are tried from left toright. When one pattern completely matches, that branch is accepted. This meansthat onceA matches,B will not be tested further, even if it wouldproduce a longer overall match. In other words, the'|' operator is nevergreedy. To match a literal'|', use\|, or enclose it inside acharacter class, as in[|].
(...)
Matches whatever regular expression is inside the parentheses, and indicates thestart and end of a group; the contents of a group can be retrieved after a matchhas been performed, and can be matched later in the string with the\numberspecial sequence, described below. To match the literals'(' or')',use\( or\), or enclose them inside a character class:[(],[)].
(?...)
This is an extension notation (a'?' following a'(' is not meaningfulotherwise). The first character after the'?' determines what the meaningand further syntax of the construct is. Extensions usually do not create a newgroup;(?P<name>...) is the only exception to this rule. Following are thecurrently supported extensions.
(?aiLmsux)
(One or more letters from the set'a','i','L','m','s','u','x'.) The group matches the empty string; theletters set the corresponding flags:re.A (ASCII-only matching),re.I (ignore case),re.L (locale dependent),re.M (multi-line),re.S (dot matches all),re.U (Unicode matching), andre.X (verbose),for the entire regular expression.(The flags are described inModule Contents.)This is useful if you wish to include the flags as part of theregular expression, instead of passing aflag argument to there.compile() function. Flags should be used first in theexpression string.
(?:...)
A non-capturing version of regular parentheses. Matches whatever regularexpression is inside the parentheses, but the substring matched by the groupcannot be retrieved after performing a match or referenced later in thepattern.
(?aiLmsux-imsx:...)

(Zero or more letters from the set'a','i','L','m','s','u','x', optionally followed by'-' followed byone or more letters from the'i','m','s','x'.)The letters set or remove the corresponding flags:re.A (ASCII-only matching),re.I (ignore case),re.L (locale dependent),re.M (multi-line),re.S (dot matches all),re.U (Unicode matching),andre.X (verbose), for the part of the expression.(The flags are described inModule Contents.)

The letters'a','L' and'u' are mutually exclusive when usedas inline flags, so they can’t be combined or follow'-'. Instead,when one of them appears in an inline group, it overrides the matching modein the enclosing group. In Unicode patterns(?a:...) switches toASCII-only matching, and(?u:...) switches to Unicode matching(default). In byte pattern(?L:...) switches to locale dependingmatching, and(?a:...) switches to ASCII-only matching (default).This override is only in effect for the narrow inline group, and theoriginal matching mode is restored outside of the group.

New in version 3.6.

Changed in version 3.7:The letters'a','L' and'u' also can be used in a group.

(?P<name>...)

Similar to regular parentheses, but the substring matched by the group isaccessible via the symbolic group namename. Group names must be validPython identifiers, and each group name must be defined only once within aregular expression. A symbolic group is also a numbered group, just as ifthe group were not named.

Named groups can be referenced in three contexts. If the pattern is(?P<quote>['"]).*?(?P=quote) (i.e. matching a string quoted with eithersingle or double quotes):

Context of reference to group “quote”Ways to reference it
in the same pattern itself
  • (?P=quote) (as shown)
  • \1
when processing match objectm
  • m.group('quote')
  • m.end('quote') (etc.)
in a string passed to thereplargument ofre.sub()
  • \g<quote>
  • \g<1>
  • \1
(?P=name)
A backreference to a named group; it matches whatever text was matched by theearlier group namedname.
(?#...)
A comment; the contents of the parentheses are simply ignored.
(?=...)
Matches if... matches next, but doesn’t consume any of the string. This iscalled alookahead assertion. For example,Isaac(?=Asimov) will match'Isaac' only if it’s followed by'Asimov'.
(?!...)
Matches if... doesn’t match next. This is anegative lookahead assertion.For example,Isaac(?!Asimov) will match'Isaac' only if it’snotfollowed by'Asimov'.
(?<=...)

Matches if the current position in the string is preceded by a match for...that ends at the current position. This is called apositive lookbehindassertion.(?<=abc)def will find a match in'abcdef', since thelookbehind will back up 3 characters and check if the contained pattern matches.The contained pattern must only match strings of some fixed length, meaning thatabc ora|b are allowed, buta* anda{3,4} are not. Note thatpatterns which start with positive lookbehind assertions will not match at thebeginning of the string being searched; you will most likely want to use thesearch() function rather than thematch() function:

>>>importre>>>m=re.search('(?<=abc)def','abcdef')>>>m.group(0)'def'

This example looks for a word following a hyphen:

>>>m=re.search(r'(?<=-)\w+','spam-egg')>>>m.group(0)'egg'

Changed in version 3.5:Added support for group references of fixed length.

(?<!...)
Matches if the current position in the string is not preceded by a match for.... This is called anegative lookbehind assertion. Similar topositive lookbehind assertions, the contained pattern must only match strings ofsome fixed length. Patterns which start with negative lookbehind assertions maymatch at the beginning of the string being searched.
(?(id/name)yes-pattern|no-pattern)
Will try to match withyes-pattern if the group with givenid orname exists, and withno-pattern if it doesn’t.no-pattern isoptional and can be omitted. For example,(<)?(\w+@\w+(?:\.\w+)+)(?(1)>|$) is a poor email matching pattern, whichwill match with'<user@host.com>' as well as'user@host.com', butnot with'<user@host.com' nor'user@host.com>'.

The special sequences consist of'\' and a character from the list below.If the ordinary character is not an ASCII digit or an ASCII letter, then theresulting RE will match the second character. For example,\$ matches thecharacter'$'.

\number
Matches the contents of the group of the same number. Groups are numberedstarting from 1. For example,(.+)\1 matches'thethe' or'5555',but not'thethe' (note the space after the group). This special sequencecan only be used to match one of the first 99 groups. If the first digit ofnumber is 0, ornumber is 3 octal digits long, it will not be interpreted asa group match, but as the character with octal valuenumber. Inside the'[' and']' of a character class, all numeric escapes are treated ascharacters.
\A
Matches only at the start of the string.
\b

Matches the empty string, but only at the beginning or end of a word.A word is defined as a sequence of word characters. Note that formally,\b is defined as the boundary between a\w and a\W character(or vice versa), or between\w and the beginning/end of the string.This means thatr'\bfoo\b' matches'foo','foo.','(foo)','barfoobaz' but not'foobar' or'foo3'.

By default Unicode alphanumerics are the ones used in Unicode patterns, butthis can be changed by using theASCII flag. Word boundaries aredetermined by the current locale if theLOCALE flag is used.Inside a character range,\b represents the backspace character, forcompatibility with Python’s string literals.

\B
Matches the empty string, but only when it isnot at the beginning or endof a word. This means thatr'py\B' matches'python','py3','py2', but not'py','py.', or'py!'.\B is just the opposite of\b, so word characters in Unicodepatterns are Unicode alphanumerics or the underscore, although this canbe changed by using theASCII flag. Word boundaries aredetermined by the current locale if theLOCALE flag is used.
\d
For Unicode (str) patterns:
Matches any Unicode decimal digit (that is, any character inUnicode character category [Nd]). This includes[0-9], andalso many other digit characters. If theASCII flag isused only[0-9] is matched.
For 8-bit (bytes) patterns:
Matches any decimal digit; this is equivalent to[0-9].
\D
Matches any character which is not a decimal digit. This isthe opposite of\d. If theASCII flag is used thisbecomes the equivalent of[^0-9].
\s
For Unicode (str) patterns:
Matches Unicode whitespace characters (which includes[\t\n\r\f\v], and also many other characters, for example thenon-breaking spaces mandated by typography rules in manylanguages). If theASCII flag is used, only[\t\n\r\f\v] is matched.
For 8-bit (bytes) patterns:
Matches characters considered whitespace in the ASCII character set;this is equivalent to[\t\n\r\f\v].
\S
Matches any character which is not a whitespace character. This isthe opposite of\s. If theASCII flag is used thisbecomes the equivalent of[^\t\n\r\f\v].
\w
For Unicode (str) patterns:
Matches Unicode word characters; this includes most charactersthat can be part of a word in any language, as well as numbers andthe underscore. If theASCII flag is used, only[a-zA-Z0-9_] is matched.
For 8-bit (bytes) patterns:
Matches characters considered alphanumeric in the ASCII character set;this is equivalent to[a-zA-Z0-9_]. If theLOCALE flag isused, matches characters considered alphanumeric in the current localeand the underscore.
\W
Matches any character which is not a word character. This isthe opposite of\w. If theASCII flag is used thisbecomes the equivalent of[^a-zA-Z0-9_]. If theLOCALE flag isused, matches characters considered alphanumeric in the current localeand the underscore.
\Z
Matches only at the end of the string.

Most of the standard escapes supported by Python string literals are alsoaccepted by the regular expression parser:

\a      \b      \f      \n\r      \t      \u      \U\v      \x      \\

(Note that\b is used to represent word boundaries, and means “backspace”only inside character classes.)

'\u' and'\U' escape sequences are only recognized in Unicodepatterns. In bytes patterns they are errors.

Octal escapes are included in a limited form. If the first digit is a 0, or ifthere are three octal digits, it is considered an octal escape. Otherwise, it isa group reference. As for string literals, octal escapes are always at mostthree digits in length.

Changed in version 3.3:The'\u' and'\U' escape sequences have been added.

Changed in version 3.6:Unknown escapes consisting of'\' and an ASCII letter now are errors.

6.2.2. Module Contents

The module defines several functions, constants, and an exception. Some of thefunctions are simplified versions of the full featured methods for compiledregular expressions. Most non-trivial applications always use the compiledform.

Changed in version 3.6:Flag constants are now instances ofRegexFlag, which is a subclass ofenum.IntFlag.

re.compile(pattern,flags=0)

Compile a regular expression pattern into aregular expression object, which can be used for matching using itsmatch(),search() and other methods, describedbelow.

The expression’s behaviour can be modified by specifying aflags value.Values can be any of the following variables, combined using bitwise OR (the| operator).

The sequence

prog=re.compile(pattern)result=prog.match(string)

is equivalent to

result=re.match(pattern,string)

but usingre.compile() and saving the resulting regular expressionobject for reuse is more efficient when the expression will be used severaltimes in a single program.

Note

The compiled versions of the most recent patterns passed tore.compile() and the module-level matching functions are cached, soprograms that use only a few regular expressions at a time needn’t worryabout compiling regular expressions.

re.A
re.ASCII

Make\w,\W,\b,\B,\d,\D,\s and\Sperform ASCII-only matching instead of full Unicode matching. This is onlymeaningful for Unicode patterns, and is ignored for byte patterns.Corresponds to the inline flag(?a).

Note that for backward compatibility, there.U flag stillexists (as well as its synonymre.UNICODE and its embeddedcounterpart(?u)), but these are redundant in Python 3 sincematches are Unicode by default for strings (and Unicode matchingisn’t allowed for bytes).

re.DEBUG

Display debug information about compiled expression.No corresponding inline flag.

re.I
re.IGNORECASE

Perform case-insensitive matching; expressions like[A-Z] will alsomatch lowercase letters. Full Unicode matching (such asÜ matchingü) also works unless there.ASCII flag is used to disablenon-ASCII matches. The current locale does not change the effect of thisflag unless there.LOCALE flag is also used.Corresponds to the inline flag(?i).

Note that when the Unicode patterns[a-z] or[A-Z] are used incombination with theIGNORECASE flag, they will match the 52 ASCIIletters and 4 additional non-ASCII letters: ‘İ’ (U+0130, Latin capitalletter I with dot above), ‘ı’ (U+0131, Latin small letter dotless i),‘ſ’ (U+017F, Latin small letter long s) and ‘K’ (U+212A, Kelvin sign).If theASCII flag is used, only letters ‘a’ to ‘z’and ‘A’ to ‘Z’ are matched.

re.L
re.LOCALE

Make\w,\W,\b,\B and case-insensitive matchingdependent on the current locale. This flag can be used only with bytespatterns. The use of this flag is discouraged as the locale mechanismis very unreliable, it only handles one “culture” at a time, and it onlyworks with 8-bit locales. Unicode matching is already enabled by defaultin Python 3 for Unicode (str) patterns, and it is able to handle differentlocales/languages.Corresponds to the inline flag(?L).

Changed in version 3.6:re.LOCALE can be used only with bytes patterns and isnot compatible withre.ASCII.

Changed in version 3.7:Compiled regular expression objects with there.LOCALE flag nolonger depend on the locale at compile time. Only the locale atmatching time affects the result of matching.

re.M
re.MULTILINE

When specified, the pattern character'^' matches at the beginning of thestring and at the beginning of each line (immediately following each newline);and the pattern character'$' matches at the end of the string and at theend of each line (immediately preceding each newline). By default,'^'matches only at the beginning of the string, and'$' only at the end of thestring and immediately before the newline (if any) at the end of the string.Corresponds to the inline flag(?m).

re.S
re.DOTALL

Make the'.' special character match any character at all, including anewline; without this flag,'.' will match anythingexcept a newline.Corresponds to the inline flag(?s).

re.X
re.VERBOSE

This flag allows you to write regular expressions that look nicer and aremore readable by allowing you to visually separate logical sections of thepattern and add comments. Whitespace within the pattern is ignored, exceptwhen in a character class, or when preceded by an unescaped backslash,or within tokens like*?,(?: or(?P<...>.When a line contains a# that is not in a character class and is notpreceded by an unescaped backslash, all characters from the leftmost such# through the end of the line are ignored.

This means that the two following regular expression objects that match adecimal number are functionally equal:

a=re.compile(r"""\d +  # the integral part                   \.    # the decimal point                   \d *  # some fractional digits""",re.X)b=re.compile(r"\d+\.\d*")

Corresponds to the inline flag(?x).

re.search(pattern,string,flags=0)

Scan throughstring looking for the first location where the regular expressionpattern produces a match, and return a correspondingmatch object. ReturnNone if no position in the string matches thepattern; note that this is different from finding a zero-length match at somepoint in the string.

re.match(pattern,string,flags=0)

If zero or more characters at the beginning ofstring match the regularexpressionpattern, return a correspondingmatch object. ReturnNone if the string does not match the pattern;note that this is different from a zero-length match.

Note that even inMULTILINE mode,re.match() will only matchat the beginning of the string and not at the beginning of each line.

If you want to locate a match anywhere instring, usesearch()instead (see alsosearch() vs. match()).

re.fullmatch(pattern,string,flags=0)

If the wholestring matches the regular expressionpattern, return acorrespondingmatch object. ReturnNone if thestring does not match the pattern; note that this is different from azero-length match.

New in version 3.4.

re.split(pattern,string,maxsplit=0,flags=0)

Splitstring by the occurrences ofpattern. If capturing parentheses areused inpattern, then the text of all groups in the pattern are also returnedas part of the resulting list. Ifmaxsplit is nonzero, at mostmaxsplitsplits occur, and the remainder of the string is returned as the final elementof the list.

>>>re.split(r'\W+','Words, words, words.')['Words', 'words', 'words', '']>>>re.split(r'(\W+)','Words, words, words.')['Words', ', ', 'words', ', ', 'words', '.', '']>>>re.split(r'\W+','Words, words, words.',1)['Words', 'words, words.']>>>re.split('[a-f]+','0a3B9',flags=re.IGNORECASE)['0', '3', '9']

If there are capturing groups in the separator and it matches at the start ofthe string, the result will start with an empty string. The same holds forthe end of the string:

>>>re.split(r'(\W+)','...words, words...')['', '...', 'words', ', ', 'words', '...', '']

That way, separator components are always found at the same relativeindices within the result list.

Empty matches for the pattern split the string only when not adjacentto a previous empty match.

>>>re.split(r'\b','Words, words, words.')['', 'Words', ', ', 'words', ', ', 'words', '.']>>>re.split(r'\W*','...words...')['', '', 'w', 'o', 'r', 'd', 's', '', '']>>>re.split(r'(\W*)','...words...')['', '...', '', '', 'w', '', 'o', '', 'r', '', 'd', '', 's', '...', '', '', '']

Changed in version 3.1:Added the optional flags argument.

Changed in version 3.7:Added support of splitting on a pattern that could match an empty string.

re.findall(pattern,string,flags=0)

Return all non-overlapping matches ofpattern instring, as a list ofstrings. Thestring is scanned left-to-right, and matches are returned inthe order found. If one or more groups are present in the pattern, return alist of groups; this will be a list of tuples if the pattern has more thanone group. Empty matches are included in the result.

Changed in version 3.7:Non-empty matches can now start just after a previous empty match.

re.finditer(pattern,string,flags=0)

Return aniterator yieldingmatch objects overall non-overlapping matches for the REpattern instring. Thestringis scanned left-to-right, and matches are returned in the order found. Emptymatches are included in the result.

Changed in version 3.7:Non-empty matches can now start just after a previous empty match.

re.sub(pattern,repl,string,count=0,flags=0)

Return the string obtained by replacing the leftmost non-overlapping occurrencesofpattern instring by the replacementrepl. If the pattern isn’t found,string is returned unchanged.repl can be a string or a function; if it isa string, any backslash escapes in it are processed. That is,\n isconverted to a single newline character,\r is converted to a carriage return, andso forth. Unknown escapes such as\& are left alone. Backreferences, suchas\6, are replaced with the substring matched by group 6 in the pattern.For example:

>>>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{'

Ifrepl is a function, it is called for every non-overlapping occurrence ofpattern. The function takes a singlematch objectargument, and returns the replacement string. For example:

>>>defdashrepl(matchobj):...ifmatchobj.group(0)=='-':return' '...else:return'-'>>>re.sub('-{1,2}',dashrepl,'pro----gram-files')'pro--gram files'>>>re.sub(r'\sAND\s',' & ','Baked Beans And Spam',flags=re.IGNORECASE)'Baked Beans & Spam'

The pattern may be a string or apattern object.

The optional argumentcount is the maximum number of pattern occurrences to bereplaced;count must be a non-negative integer. If omitted or zero, alloccurrences will be replaced. Empty matches for the pattern are replaced onlywhen not adjacent to a previous empty match, sosub('x*','-','abxd') returns'-a-b--d-'.

In string-typerepl arguments, in addition to the character escapes andbackreferences described above,\g<name> will use the substring matched by the group namedname, asdefined by the(?P<name>...) syntax.\g<number> uses the correspondinggroup number;\g<2> is therefore equivalent to\2, but isn’t ambiguousin a replacement such as\g<2>0.\20 would be interpreted as areference to group 20, not a reference to group 2 followed by the literalcharacter'0'. The backreference\g<0> substitutes in the entiresubstring matched by the RE.

Changed in version 3.1:Added the optional flags argument.

Changed in version 3.5:Unmatched groups are replaced with an empty string.

Changed in version 3.6:Unknown escapes inpattern consisting of'\' and an ASCII letternow are errors.

Changed in version 3.7:Unknown escapes inrepl consisting of'\' and an ASCII letternow are errors.

Empty matches for the pattern are replaced when adjacent to a previousnon-empty match.

re.subn(pattern,repl,string,count=0,flags=0)

Perform the same operation assub(), but return a tuple(new_string,number_of_subs_made).

Changed in version 3.1:Added the optional flags argument.

Changed in version 3.5:Unmatched groups are replaced with an empty string.

re.escape(pattern)

Escape special characters inpattern.This is useful if you want to match an arbitrary literal string that mayhave regular expression metacharacters in it. For example:

>>>print(re.escape('python.exe'))python\.exe>>>legal_chars=string.ascii_lowercase+string.digits+"!#$%&'*+-.^_`|~:">>>print('[%s]+'%re.escape(legal_chars))[abcdefghijklmnopqrstuvwxyz0123456789!\#\$%\&'\*\+\-\.\^_`\|\~:]+>>>operators=['+','-','*','/','**']>>>print('|'.join(map(re.escape,sorted(operators,reverse=True))))/|\-|\+|\*\*|\*

This functions must not be used for the replacement string insub()andsubn(), only backslashes should be escaped. For example:

>>>digits_re=r'\d+'>>>sample='/usr/sbin/sendmail - 0 errors, 12 warnings'>>>print(re.sub(digits_re,digits_re.replace('\\',r'\\'),sample))/usr/sbin/sendmail - \d+ errors, \d+ warnings

Changed in version 3.3:The'_' character is no longer escaped.

Changed in version 3.7:Only characters that can have special meaning in a regular expressionare escaped.

re.purge()

Clear the regular expression cache.

exceptionre.error(msg,pattern=None,pos=None)

Exception raised when a string passed to one of the functions here is not avalid regular expression (for example, it might contain unmatched parentheses)or when some other error occurs during compilation or matching. It is never anerror if a string contains no match for a pattern. The error instance hasthe following additional attributes:

msg

The unformatted error message.

pattern

The regular expression pattern.

pos

The index inpattern where compilation failed (may beNone).

lineno

The line corresponding topos (may beNone).

colno

The column corresponding topos (may beNone).

Changed in version 3.5:Added additional attributes.

6.2.3. Regular Expression Objects

Compiled regular expression objects support the following methods andattributes:

Pattern.search(string[,pos[,endpos]])

Scan throughstring looking for the first location where this regularexpression produces a match, and return a correspondingmatch object. ReturnNone if no position in the string matches thepattern; note that this is different from finding a zero-length match at somepoint in the string.

The optional second parameterpos gives an index in the string where thesearch is to start; it defaults to0. This is not completely equivalent toslicing the string; the'^' pattern character matches at the real beginningof the string and at positions just after a newline, but not necessarily at theindex where the search is to start.

The optional parameterendpos limits how far the string will be searched; itwill be as if the string isendpos characters long, so only the charactersfrompos toendpos-1 will be searched for a match. Ifendpos is lessthanpos, no match will be found; otherwise, ifrx is a compiled regularexpression object,rx.search(string,0,50) is equivalent torx.search(string[:50],0).

>>>pattern=re.compile("d")>>>pattern.search("dog")# Match at index 0<re.Match object; span=(0, 1), match='d'>>>>pattern.search("dog",1)# No match; search doesn't include the "d"
Pattern.match(string[,pos[,endpos]])

If zero or more characters at thebeginning ofstring match this regularexpression, return a correspondingmatch object.ReturnNone if the string does not match the pattern; note that this isdifferent from a zero-length match.

The optionalpos andendpos parameters have the same meaning as for thesearch() 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".<re.Match object; span=(1, 2), match='o'>

If you want to locate a match anywhere instring, usesearch() instead (see alsosearch() vs. match()).

Pattern.fullmatch(string[,pos[,endpos]])

If the wholestring matches this regular expression, return a correspondingmatch object. ReturnNone if the string does notmatch the pattern; note that this is different from a zero-length match.

The optionalpos andendpos parameters have the same meaning as for thesearch() 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.<re.Match object; span=(1, 3), match='og'>

New in version 3.4.

Pattern.split(string,maxsplit=0)

Identical to thesplit() function, using the compiled pattern.

Pattern.findall(string[,pos[,endpos]])

Similar to thefindall() function, using the compiled pattern, butalso accepts optionalpos andendpos parameters that limit the searchregion like forsearch().

Pattern.finditer(string[,pos[,endpos]])

Similar to thefinditer() function, using the compiled pattern, butalso accepts optionalpos andendpos parameters that limit the searchregion like forsearch().

Pattern.sub(repl,string,count=0)

Identical to thesub() function, using the compiled pattern.

Pattern.subn(repl,string,count=0)

Identical to thesubn() function, using the compiled pattern.

Pattern.flags

The regex matching flags. This is a combination of the flags given tocompile(), any(?...) inline flags in the pattern, and implicitflags such asUNICODE if the pattern is a Unicode string.

Pattern.groups

The number of capturing groups in the pattern.

Pattern.groupindex

A dictionary mapping any symbolic group names defined by(?P<id>) to groupnumbers. The dictionary is empty if no symbolic groups were used in thepattern.

Pattern.pattern

The pattern string from which the pattern object was compiled.

Changed in version 3.7:Added support ofcopy.copy() andcopy.deepcopy(). Compiledregular expression objects are considered atomic.

6.2.4. Match Objects

Match objects always have a boolean value ofTrue.Sincematch() andsearch() returnNonewhen there is no match, you can test whether there was a match with a simpleif statement:

match=re.search(pattern,string)ifmatch:process(match)

Match objects support the following methods and attributes:

Match.expand(template)

Return the string obtained by doing backslash substitution on the templatestringtemplate, as done by thesub() 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 thecorresponding group.

Changed in version 3.5:Unmatched groups are replaced with an empty string.

Match.group([group1,...])

Returns one or more subgroups of the match. If there is a single argument, theresult is a single string; if there are multiple arguments, the result is atuple with one item per argument. Without arguments,group1 defaults to zero(the whole match is returned). If agroupN argument is zero, the correspondingreturn 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 agroup number is negative or larger than the number of groups defined in thepattern, anIndexError exception is raised. If a group is contained in apart of the pattern that did not match, the corresponding result isNone.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, thegroupNarguments may also be strings identifying groups by their group name. If astring argument is not used as a group name in the pattern, anIndexErrorexception 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'
Match.__getitem__(g)

This is identical tom.group(g). This allows easier access toan 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'

New in version 3.6.

Match.groups(default=None)

Return a tuple containing all the subgroups of the match, from 1 up to howevermany groups are in the pattern. Thedefault argument is used for groups thatdid not participate in the match; it defaults toNone.

For example:

>>>m=re.match(r"(\d+)\.(\d+)","24.1632")>>>m.groups()('24', '1632')

If we make the decimal place and everything after it optional, not all groupsmight participate in the match. These groups will default toNone unlessthedefault 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')
Match.groupdict(default=None)

Return a dictionary containing all thenamed subgroups of the match, keyed bythe subgroup name. Thedefault argument is used for groups that did notparticipate in the match; it defaults toNone. For example:

>>>m=re.match(r"(?P<first_name>\w+) (?P<last_name>\w+)","Malcolm Reynolds")>>>m.groupdict(){'first_name': 'Malcolm', 'last_name': 'Reynolds'}
Match.start([group])
Match.end([group])

Return the indices of the start and end of the substring matched bygroup;group defaults to zero (meaning the whole matched substring). Return-1 ifgroup exists but did not contribute to the match. For a match objectm, anda groupg that did contribute to the match, the substring matched by groupg(equivalent tom.group(g)) is

m.string[m.start(g):m.end(g)]

Note thatm.start(group) will equalm.end(group) ifgroup matched anull string. For example, afterm=re.search('b(c?)','cba'),m.start(0) is 1,m.end(0) is 2,m.start(1) andm.end(1) are both2, andm.start(2) raises anIndexError exception.

An example that will removeremove_this from email addresses:

>>>email="tony@tiremove_thisger.net">>>m=re.search("remove_this",email)>>>email[:m.start()]+email[m.end():]'tony@tiger.net'
Match.span([group])

For a matchm, return the 2-tuple(m.start(group),m.end(group)). Notethat ifgroup did not contribute to the match, this is(-1,-1).group defaults to zero, the entire match.

Match.pos

The value ofpos which was passed to thesearch() ormatch() method of aregex object. This isthe index into the string at which the RE engine started looking for a match.

Match.endpos

The value ofendpos which was passed to thesearch() ormatch() method of aregex object. This isthe index into the string beyond which the RE engine will not go.

Match.lastindex

The integer index of the last matched capturing group, orNone if no groupwas matched at all. For example, the expressions(a)b,((a)(b)), and((ab)) will havelastindex==1 if applied to the string'ab', whilethe expression(a)(b) will havelastindex==2, if applied to the samestring.

Match.lastgroup

The name of the last matched capturing group, orNone if the group didn’thave a name, or if no group was matched at all.

Match.re

Theregular expression object whosematch() orsearch() method produced this match instance.

Match.string

The string passed tomatch() orsearch().

Changed in version 3.7:Added support ofcopy.copy() andcopy.deepcopy(). Match objectsare considered atomic.

6.2.5. Regular Expression Examples

6.2.5.1. Checking for a Pair

In this example, we’ll use the following helper function to display matchobjects a little more gracefully:

defdisplaymatch(match):ifmatchisNone:returnNonereturn'<Match:%r, groups=%r>'%(match.group(),match.groups())

Suppose you are writing a poker program where a player’s hand is represented asa 5-character string with each character representing a card, “a” for ace, “k”for king, “q” for queen, “j” for jack, “t” for 10, and “2” through “9”representing the card with that value.

To see if a given string is a valid hand, one could do the following:

>>>valid=re.compile(r"^[a2-9tjqk]{5}$")>>>displaymatch(valid.match("akt5q"))# Valid."<Match: 'akt5q', groups=()>">>>displaymatch(valid.match("akt5e"))# Invalid.>>>displaymatch(valid.match("akt"))# Invalid.>>>displaymatch(valid.match("727ak"))# Valid."<Match: '727ak', groups=()>"

That last hand,"727ak", contained a pair, or two of the same valued cards.To match this with a regular expression, one could use backreferences as such:

>>>pair=re.compile(r".*(.).*\1")>>>displaymatch(pair.match("717ak"))# Pair of 7s."<Match: '717', groups=('7',)>">>>displaymatch(pair.match("718ak"))# No pairs.>>>displaymatch(pair.match("354aa"))# Pair of aces."<Match: '354aa', groups=('a',)>"

To find out what card the pair consists of, one could use thegroup() method of the match object in the following manner:

>>>pair.match("717ak").group(1)'7'# Error because re.match() returns None, which doesn't have a group() method:>>>pair.match("718ak").group(1)Traceback (most recent call last):  File"<pyshell#23>", line1, in<module>re.match(r".*(.).*\1","718ak").group(1)AttributeError:'NoneType' object has no attribute 'group'>>>pair.match("354aa").group(1)'a'

6.2.5.2. Simulating scanf()

Python does not currently have an equivalent toscanf(). Regularexpressions are generally more powerful, though also more verbose, thanscanf() format strings. The table below offers some more-or-lessequivalent mappings betweenscanf() format tokens and regularexpressions.

scanf() TokenRegular Expression
%c.
%5c.{5}
%d[-+]?\d+
%e,%E,%f,%g[-+]?(\d+(\.\d*)?|\.\d+)([eE][-+]?\d+)?
%i[-+]?(0[xX][\dA-Fa-f]+|0[0-7]*|\d+)
%o[-+]?[0-7]+
%s\S+
%u\d+
%x,%X[-+]?(0[xX])?[\dA-Fa-f]+

To extract the filename and numbers from a string like

/usr/sbin/sendmail-0errors,4warnings

you would use ascanf() format like

%s-%derrors,%dwarnings

The equivalent regular expression would be

(\S+)-(\d+)errors,(\d+)warnings

6.2.5.3. search() vs. match()

Python offers two different primitive operations based on regular expressions:re.match() checks for a match only at the beginning of the string, whilere.search() checks for a match anywhere in the string (this is what Perldoes by default).

For example:

>>>re.match("c","abcdef")# No match>>>re.search("c","abcdef")# Match<re.Match object; span=(2, 3), match='c'>

Regular expressions beginning with'^' can be used withsearch() torestrict the match at the beginning of the string:

>>>re.match("c","abcdef")# No match>>>re.search("^c","abcdef")# No match>>>re.search("^a","abcdef")# Match<re.Match object; span=(0, 1), match='a'>

Note however that inMULTILINE modematch() only matches at thebeginning of the string, whereas usingsearch() with a regular expressionbeginning with'^' will match at the beginning of each line.

>>>re.match('X','A\nB\nX',re.MULTILINE)# No match>>>re.search('^X','A\nB\nX',re.MULTILINE)# Match<re.Match object; span=(4, 5), match='X'>

6.2.5.4. Making a Phonebook

split() splits a string into a list delimited by the passed pattern. Themethod is invaluable for converting textual data into data structures that can beeasily read and modified by Python as demonstrated in the following example thatcreates a phonebook.

First, here is the input. Normally it may come from a file, here we are usingtriple-quoted string syntax:

>>>text="""Ross McFluff: 834.345.1254 155 Elm Street......Ronald Heathmore: 892.345.3428 436 Finley Avenue...Frank Burger: 925.541.7625 662 South Dogwood Way.........Heather Albrecht: 548.326.4584 919 Park Place"""

The entries are separated by one or more newlines. Now we convert the stringinto a list with each nonempty line having its own entry:

>>>entries=re.split("\n+",text)>>>entries['Ross McFluff: 834.345.1254 155 Elm Street','Ronald Heathmore: 892.345.3428 436 Finley Avenue','Frank Burger: 925.541.7625 662 South Dogwood Way','Heather Albrecht: 548.326.4584 919 Park Place']

Finally, split each entry into a list with first name, last name, telephonenumber, and address. We use themaxsplit parameter ofsplit()because the address has spaces, our splitting pattern, in it:

>>>[re.split(":? ",entry,3)forentryinentries][['Ross', 'McFluff', '834.345.1254', '155 Elm Street'],['Ronald', 'Heathmore', '892.345.3428', '436 Finley Avenue'],['Frank', 'Burger', '925.541.7625', '662 South Dogwood Way'],['Heather', 'Albrecht', '548.326.4584', '919 Park Place']]

The:? pattern matches the colon after the last name, so that it does notoccur in the result list. With amaxsplit of4, we could separate thehouse number from the street name:

>>>[re.split(":? ",entry,4)forentryinentries][['Ross', 'McFluff', '834.345.1254', '155', 'Elm Street'],['Ronald', 'Heathmore', '892.345.3428', '436', 'Finley Avenue'],['Frank', 'Burger', '925.541.7625', '662', 'South Dogwood Way'],['Heather', 'Albrecht', '548.326.4584', '919', 'Park Place']]

6.2.5.5. Text Munging

sub() replaces every occurrence of a pattern with a string or theresult of a function. This example demonstrates usingsub() witha function to “munge” text, or randomize the order of all the charactersin each word of a sentence except for the first and last characters:

>>>defrepl(m):...inner_word=list(m.group(2))...random.shuffle(inner_word)...returnm.group(1)+"".join(inner_word)+m.group(3)>>>text="Professor Abdolmalek, please report your absences promptly.">>>re.sub(r"(\w)(\w+)(\w)",repl,text)'Poefsrosr Aealmlobdk, pslaee reorpt your abnseces plmrptoy.'>>>re.sub(r"(\w)(\w+)(\w)",repl,text)'Pofsroser Aodlambelk, plasee reoprt yuor asnebces potlmrpy.'

6.2.5.6. Finding all Adverbs

findall() matchesall occurrences of a pattern, not just the firstone assearch() does. For example, if a writer wanted tofind all of the adverbs in some text, they might usefindall() inthe following manner:

>>>text="He was carefully disguised but captured quickly by police.">>>re.findall(r"\w+ly",text)['carefully', 'quickly']

6.2.5.7. Finding all Adverbs and their Positions

If one wants more information about all matches of a pattern than the matchedtext,finditer() is useful as it providesmatch objects instead of strings. Continuing with the previous example, ifa writer wanted to find all of the adverbsand their positions insome text, they would usefinditer() in the following manner:

>>>text="He was carefully disguised but captured quickly by police.">>>forminre.finditer(r"\w+ly",text):...print('%02d-%02d:%s'%(m.start(),m.end(),m.group(0)))07-16: carefully40-47: quickly

6.2.5.8. Raw String Notation

Raw string notation (r"text") keeps regular expressions sane. Without it,every backslash ('\') in a regular expression would have to be prefixed withanother one to escape it. For example, the two following lines of code arefunctionally identical:

>>>re.match(r"\W(.)\1\W"," ff ")<re.Match object; span=(0, 4), match=' ff '>>>>re.match("\\W(.)\\1\\W"," ff ")<re.Match object; span=(0, 4), match=' ff '>

When one wants to match a literal backslash, it must be escaped in the regularexpression. With raw string notation, this meansr"\\". Without raw stringnotation, one must use"\\\\", making the following lines of codefunctionally identical:

>>>re.match(r"\\",r"\\")<re.Match object; span=(0, 1), match='\\'>>>>re.match("\\\\",r"\\")<re.Match object; span=(0, 1), match='\\'>

6.2.5.9. Writing a Tokenizer

Atokenizer or scanneranalyzes a string to categorize groups of characters. This is a useful firststep in writing a compiler or interpreter.

The text categories are specified with regular expressions. The technique isto combine those into a single master regular expression and to loop oversuccessive matches:

importcollectionsimportreToken=collections.namedtuple('Token',['typ','value','line','column'])deftokenize(code):keywords={'IF','THEN','ENDIF','FOR','NEXT','GOSUB','RETURN'}token_specification=[('NUMBER',r'\d+(\.\d*)?'),# Integer or decimal number('ASSIGN',r':='),# Assignment operator('END',r';'),# Statement terminator('ID',r'[A-Za-z]+'),# Identifiers('OP',r'[+\-*/]'),# Arithmetic operators('NEWLINE',r'\n'),# Line endings('SKIP',r'[ \t]+'),# Skip over spaces and tabs('MISMATCH',r'.'),# Any other character]tok_regex='|'.join('(?P<%s>%s)'%pairforpairintoken_specification)line_num=1line_start=0formoinre.finditer(tok_regex,code):kind=mo.lastgroupvalue=mo.group(kind)ifkind=='NEWLINE':line_start=mo.end()line_num+=1elifkind=='SKIP':passelifkind=='MISMATCH':raiseRuntimeError(f'{value!r} unexpected on line{line_num}')else:ifkind=='ID'andvalueinkeywords:kind=valuecolumn=mo.start()-line_startyieldToken(kind,value,line_num,column)statements='''    IF quantity THEN        total := total + price * quantity;        tax := price * 0.05;    ENDIF;'''fortokenintokenize(statements):print(token)

The tokenizer produces the following output:

Token(typ='IF',value='IF',line=2,column=4)Token(typ='ID',value='quantity',line=2,column=7)Token(typ='THEN',value='THEN',line=2,column=16)Token(typ='ID',value='total',line=3,column=8)Token(typ='ASSIGN',value=':=',line=3,column=14)Token(typ='ID',value='total',line=3,column=17)Token(typ='OP',value='+',line=3,column=23)Token(typ='ID',value='price',line=3,column=25)Token(typ='OP',value='*',line=3,column=31)Token(typ='ID',value='quantity',line=3,column=33)Token(typ='END',value=';',line=3,column=41)Token(typ='ID',value='tax',line=4,column=8)Token(typ='ASSIGN',value=':=',line=4,column=12)Token(typ='ID',value='price',line=4,column=15)Token(typ='OP',value='*',line=4,column=21)Token(typ='NUMBER',value='0.05',line=4,column=23)Token(typ='END',value=';',line=4,column=27)Token(typ='ENDIF',value='ENDIF',line=5,column=4)Token(typ='END',value=';',line=5,column=9)
[Frie09]Friedl, Jeffrey. Mastering Regular Expressions. 3rd ed., O’ReillyMedia, 2009. The third edition of the book no longer covers Python at all,but the first edition covered writing good regular expression patterns ingreat detail.