string — Common string operations

Source code:Lib/string.py

String constants

The constants defined in this module are:

string.ascii_letters

The concatenation of theascii_lowercase andascii_uppercaseconstants described below. This value is not locale-dependent.

string.ascii_lowercase

The lowercase letters'abcdefghijklmnopqrstuvwxyz'. This value is notlocale-dependent and will not change.

string.ascii_uppercase

The uppercase letters'ABCDEFGHIJKLMNOPQRSTUVWXYZ'. This value is notlocale-dependent and will not change.

string.digits

The string'0123456789'.

string.hexdigits

The string'0123456789abcdefABCDEF'.

string.octdigits

The string'01234567'.

string.punctuation

String of ASCII characters which are considered punctuation charactersin theC locale:!"#$%&'()*+,-./:;<=>?@[\]^_`{|}~.

string.printable

String of ASCII characters which are considered printable by Python.This is a combination ofdigits,ascii_letters,punctuation, andwhitespace.

Note

By design,string.printable.isprintable()returnsFalse. In particular,string.printable is notprintable in the POSIX sense (seeLC_CTYPE).

string.whitespace

A string containing all ASCII characters that are considered whitespace.This includes the characters space, tab, linefeed, return, formfeed, andvertical tab.

Custom String Formatting

The built-in string class provides the ability to do complex variablesubstitutions and value formatting via theformat() method described inPEP 3101. TheFormatter class in thestring module allowsyou to create and customize your own string formatting behaviors using the sameimplementation as the built-informat() method.

classstring.Formatter

TheFormatter class has the following public methods:

format(format_string,/,*args,**kwargs)

The primary API method. It takes a format string andan arbitrary set of positional and keyword arguments.It is just a wrapper that callsvformat().

Changed in version 3.7:A format string argument is nowpositional-only.

vformat(format_string,args,kwargs)

This function does the actual work of formatting. It is exposed as aseparate function for cases where you want to pass in a predefineddictionary of arguments, rather than unpacking and repacking thedictionary as individual arguments using the*args and**kwargssyntax.vformat() does the work of breaking up the format stringinto character data and replacement fields. It calls the variousmethods described below.

In addition, theFormatter defines a number of methods that areintended to be replaced by subclasses:

parse(format_string)

Loop over the format_string and return an iterable of tuples(literal_text,field_name,format_spec,conversion). This is usedbyvformat() to break the string into either literal text, orreplacement fields.

The values in the tuple conceptually represent a span of literal textfollowed by a single replacement field. If there is no literal text(which can happen if two replacement fields occur consecutively), thenliteral_text will be a zero-length string. If there is no replacementfield, then the values offield_name,format_spec andconversionwill beNone.

get_field(field_name,args,kwargs)

Givenfield_name as returned byparse() (see above), convert it toan object to be formatted. Returns a tuple (obj, used_key). The defaultversion takes strings of the form defined inPEP 3101, such as“0[name]” or “label.title”.args andkwargs are as passed in tovformat(). The return valueused_key has the same meaning as thekey parameter toget_value().

get_value(key,args,kwargs)

Retrieve a given field value. Thekey argument will be either aninteger or a string. If it is an integer, it represents the index of thepositional argument inargs; if it is a string, then it represents anamed argument inkwargs.

Theargs parameter is set to the list of positional arguments tovformat(), and thekwargs parameter is set to the dictionary ofkeyword arguments.

For compound field names, these functions are only called for the firstcomponent of the field name; subsequent components are handled throughnormal attribute and indexing operations.

So for example, the field expression ‘0.name’ would causeget_value() to be called with akey argument of 0. Thenameattribute will be looked up afterget_value() returns by calling thebuilt-ingetattr() function.

If the index or keyword refers to an item that does not exist, then anIndexError orKeyError should be raised.

check_unused_args(used_args,args,kwargs)

Implement checking for unused arguments if desired. The arguments to thisfunction is the set of all argument keys that were actually referred to inthe format string (integers for positional arguments, and strings fornamed arguments), and a reference to theargs andkwargs that waspassed to vformat. The set of unused args can be calculated from theseparameters.check_unused_args() is assumed to raise an exception ifthe check fails.

format_field(value,format_spec)

format_field() simply calls the globalformat() built-in. Themethod is provided so that subclasses can override it.

convert_field(value,conversion)

Converts the value (returned byget_field()) given a conversion type(as in the tuple returned by theparse() method). The defaultversion understands ‘s’ (str), ‘r’ (repr) and ‘a’ (ascii) conversiontypes.

Format String Syntax

Thestr.format() method and theFormatter class share the samesyntax for format strings (although in the case ofFormatter,subclasses can define their own format string syntax). The syntax isrelated to that offormatted string literals, but it isless sophisticated and, in particular, does not support arbitrary expressions.

Format strings contain “replacement fields” surrounded by curly braces{}.Anything that is not contained in braces is considered literal text, which iscopied unchanged to the output. If you need to include a brace character in theliteral text, it can be escaped by doubling:{{ and}}.

The grammar for a replacement field is as follows:

replacement_field ::= "{" [field_name] ["!"conversion] [":"format_spec] "}"field_name        ::=arg_name ("."attribute_name | "["element_index "]")*arg_name          ::= [identifier |digit+]attribute_name    ::=identifierelement_index     ::=digit+ |index_stringindex_string      ::= <any source character except "]"> +conversion        ::= "r" | "s" | "a"format_spec       ::=format-spec:format_spec

In less formal terms, the replacement field can start with afield_name that specifiesthe object whose value is to be formatted and insertedinto the output instead of the replacement field.Thefield_name is optionally followed by aconversion field, which ispreceded by an exclamation point'!', and aformat_spec, which is precededby a colon':'. These specify a non-default format for the replacement value.

See also theFormat Specification Mini-Language section.

Thefield_name itself begins with anarg_name that is either a number or akeyword. If it’s a number, it refers to a positional argument, and if it’s a keyword,it refers to a named keyword argument. Anarg_name is treated as a number ifa call tostr.isdecimal() on the string would return true.If the numerical arg_names in a format stringare 0, 1, 2, … in sequence, they can all be omitted (not just some)and the numbers 0, 1, 2, … will be automatically inserted in that order.Becausearg_name is not quote-delimited, it is not possible to specify arbitrarydictionary keys (e.g., the strings'10' or':-]') within a format string.Thearg_name can be followed by any number of index orattribute expressions. An expression of the form'.name' selects the namedattribute usinggetattr(), while an expression of the form'[index]'does an index lookup using__getitem__().

Changed in version 3.1:The positional argument specifiers can be omitted forstr.format(),so'{}{}'.format(a,b) is equivalent to'{0}{1}'.format(a,b).

Changed in version 3.4:The positional argument specifiers can be omitted forFormatter.

Some simple format string examples:

"First, thou shalt count to{0}"# References first positional argument"Bring me a{}"# Implicitly references the first positional argument"From{} to{}"# Same as "From {0} to {1}""My quest is{name}"# References keyword argument 'name'"Weight in tons{0.weight}"# 'weight' attribute of first positional arg"Units destroyed:{players[0]}"# First element of keyword argument 'players'.

Theconversion field causes a type coercion before formatting. Normally, thejob of formatting a value is done by the__format__() method of the valueitself. However, in some cases it is desirable to force a type to be formattedas a string, overriding its own definition of formatting. By converting thevalue to a string before calling__format__(), the normal formatting logicis bypassed.

Three conversion flags are currently supported:'!s' which callsstr()on the value,'!r' which callsrepr() and'!a' which callsascii().

Some examples:

"Harold's a clever{0!s}"# Calls str() on the argument first"Bring out the holy{name!r}"# Calls repr() on the argument first"More{!a}"# Calls ascii() on the argument first

Theformat_spec field contains a specification of how the value should bepresented, including such details as field width, alignment, padding, decimalprecision and so on. Each value type can define its own “formattingmini-language” or interpretation of theformat_spec.

Most built-in types support a common formatting mini-language, which isdescribed in the next section.

Aformat_spec field can also include nested replacement fields within it.These nested replacement fields may contain a field name, conversion flagand format specification, but deeper nesting isnot allowed. The replacement fields within theformat_spec are substituted before theformat_spec string is interpreted.This allows the formatting of a value to be dynamically specified.

See theFormat examples section for some examples.

Format Specification Mini-Language

“Format specifications” are used within replacement fields contained within aformat string to define how individual values are presented (seeFormat String Syntax andf-strings).They can also be passed directly to the built-informat() function. Each formattable type may define how the formatspecification is to be interpreted.

Most built-in types implement the following options for format specifications,although some of the formatting options are only supported by the numeric types.

A general convention is that an empty format specification producesthe same result as if you had calledstr() on the value. Anon-empty format specification typically modifies the result.

The general form of astandard format specifier is:

format_spec ::= [options][width][grouping]["."precision][type]options     ::= [[fill]align][sign]["z"]["#"]["0"]fill        ::= <any character>align       ::= "<" | ">" | "=" | "^"sign        ::= "+" | "-" | " "width       ::=digit+grouping    ::= "," | "_"precision   ::=digit+type        ::= "b" | "c" | "d" | "e" | "E" | "f" | "F" | "g"                | "G" | "n" | "o" | "s" | "x" | "X" | "%"

If a validalign value is specified, it can be preceded by afillcharacter that can be any character and defaults to a space if omitted.It is not possible to use a literal curly brace (”{” or “}”) asthefill character in aformatted string literal or when using thestr.format()method. However, it is possible to insert a curly bracewith a nested replacement field. This limitation doesn’taffect theformat() function.

The meaning of the various alignment options is as follows:

Option

Meaning

'<'

Forces the field to be left-aligned within the availablespace (this is the default for most objects).

'>'

Forces the field to be right-aligned within theavailable space (this is the default for numbers).

'='

Forces the padding to be placed after the sign (if any)but before the digits. This is used for printing fieldsin the form ‘+000000120’. This alignment option is onlyvalid for numeric types, excludingcomplex.It becomes the default for numbers when ‘0’ immediatelyprecedes the field width.

'^'

Forces the field to be centered within the availablespace.

Note that unless a minimum field width is defined, the field width will alwaysbe the same size as the data to fill it, so that the alignment option has nomeaning in this case.

Thesign option is only valid for number types, and can be one of thefollowing:

Option

Meaning

'+'

Indicates that a sign should be used for bothpositive as well as negative numbers.

'-'

Indicates that a sign should be used only for negativenumbers (this is the default behavior).

space

Indicates that a leading space should be used onpositive numbers, and a minus sign on negative numbers.

The'z' option coerces negative zero floating-point values to positivezero after rounding to the format precision. This option is only valid forfloating-point presentation types.

Changed in version 3.11:Added the'z' option (see alsoPEP 682).

The'#' option causes the “alternate form” to be used for theconversion. The alternate form is defined differently for differenttypes. This option is only valid for integer, float and complextypes. For integers, when binary, octal, or hexadecimal outputis used, this option adds the respective prefix'0b','0o','0x', or'0X' to the output value. For float and complex thealternate form causes the result of the conversion to always contain adecimal-point character, even if no digits follow it. Normally, adecimal-point character appears in the result of these conversionsonly if a digit follows it. In addition, for'g' and'G'conversions, trailing zeros are not removed from the result.

Thewidth is a decimal integer defining the minimum total field width,including any prefixes, separators, and other formatting characters.If not specified, then the field width will be determined by the content.

When no explicit alignment is given, preceding thewidth field by a zero('0') character enables sign-aware zero-padding for numeric types,excludingcomplex. This is equivalent to afill character of'0' with analignment type of'='.

Changed in version 3.10:Preceding thewidth field by'0' no longer affects the defaultalignment for strings.

Thegrouping option after thewidth field specifiesa digit group separator for the integral part of a number.It can be one of the following:

Option

Meaning

','

Inserts a comma every 3 digits forinteger presentation type'd' andfloating-point presentation types, excluding'n'.For other presentation types,this option is not supported.

'_'

Inserts an underscore every 3 digits forinteger presentation type'd' andfloating-point presentation types, excluding'n'.For integer presentation types'b','o','x', and'X',underscores are inserted every 4 digits.For other presentation types,this option is not supported.

For a locale aware separator, use the'n' presentation type instead.

Changed in version 3.1:Added the',' option (see alsoPEP 378).

Changed in version 3.6:Added the'_' option (see alsoPEP 515).

Theprecision is a decimal integer indicating how many digits should bedisplayed after the decimal point for presentation types'f' and'F', or before and after the decimal point for presentationtypes'g' or'G'. For string presentation types the fieldindicates the maximum field size - in other words, how many characters will beused from the field content. Theprecision is not allowed for integerpresentation types.

Finally, thetype determines how the data should be presented.

The available string presentation types are:

Type

Meaning

's'

String format. This is the default type for strings andmay be omitted.

None

The same as's'.

The available integer presentation types are:

Type

Meaning

'b'

Binary format. Outputs the number in base 2.

'c'

Character. Converts the integer to the correspondingunicode character before printing.

'd'

Decimal Integer. Outputs the number in base 10.

'o'

Octal format. Outputs the number in base 8.

'x'

Hex format. Outputs the number in base 16, usinglower-case letters for the digits above 9.

'X'

Hex format. Outputs the number in base 16, usingupper-case letters for the digits above 9.In case'#' is specified, the prefix'0x' willbe upper-cased to'0X' as well.

'n'

Number. This is the same as'd', except that it usesthe current locale setting to insert the appropriatedigit group separators.

None

The same as'd'.

In addition to the above presentation types, integers can be formattedwith the floating-point presentation types listed below (except'n' andNone). When doing so,float() is used to convert theinteger to a floating-point number before formatting.

The available presentation types forfloat andDecimal values are:

Type

Meaning

'e'

Scientific notation. For a given precisionp,formats the number in scientific notation with theletter ‘e’ separating the coefficient from the exponent.The coefficient has one digit before andp digitsafter the decimal point, for a total ofp+1significant digits. With no precision given, uses aprecision of6 digits after the decimal point forfloat, and shows all coefficient digitsforDecimal. Ifp=0, the decimalpoint is omitted unless the# option is used.

'E'

Scientific notation. Same as'e' except it usesan upper case ‘E’ as the separator character.

'f'

Fixed-point notation. For a given precisionp,formats the number as a decimal number with exactlyp digits following the decimal point. With noprecision given, uses a precision of6 digits afterthe decimal point forfloat, and uses aprecision large enough to show all coefficient digitsforDecimal. Ifp=0, the decimalpoint is omitted unless the# option is used.

'F'

Fixed-point notation. Same as'f', but convertsnan toNAN andinf toINF.

'g'

General format. For a given precisionp>=1,this rounds the number top significant digits andthen formats the result in either fixed-point formator in scientific notation, depending on its magnitude.A precision of0 is treated as equivalent to aprecision of1.

The precise rules are as follows: suppose that theresult formatted with presentation type'e' andprecisionp-1 would have exponentexp. Then,ifm<=exp<p, wherem is -4 for floats and -6forDecimals, the number isformatted with presentation type'f' and precisionp-1-exp. Otherwise, the number is formattedwith presentation type'e' and precisionp-1.In both cases insignificant trailing zeros are removedfrom the significand, and the decimal point is alsoremoved if there are no remaining digits following it,unless the'#' option is used.

With no precision given, uses a precision of6significant digits forfloat. ForDecimal, the coefficient of the resultis formed from the coefficient digits of the value;scientific notation is used for values smaller than1e-6 in absolute value and values where the placevalue of the least significant digit is larger than 1,and fixed-point notation is used otherwise.

Positive and negative infinity, positive and negativezero, and nans, are formatted asinf,-inf,0,-0 andnan respectively, regardless ofthe precision.

'G'

General format. Same as'g' except switches to'E' if the number gets too large. Therepresentations of infinity and NaN are uppercased, too.

'n'

Number. This is the same as'g', except that it usesthe current locale setting to insert the appropriatedigit group separatorsfor the integral part of a number.

'%'

Percentage. Multiplies the number by 100 and displaysin fixed ('f') format, followed by a percent sign.

None

Forfloat this is like the'g' type, exceptthat when fixed-point notation is used to format theresult, it always includes at least one digit past thedecimal point, and switches to the scientific notationwhenexp>=p-1. When the precision is notspecified, the latter will be as large as needed torepresent the given value faithfully.

ForDecimal, this is the same aseither'g' or'G' depending on the value ofcontext.capitals for the current decimal context.

The overall effect is to match the output ofstr()as altered by the other format modifiers.

The result should be correctly rounded to a given precisionp of digitsafter the decimal point. The rounding mode forfloat matches thatof theround() builtin. ForDecimal, the roundingmode of the currentcontext will be used.

The available presentation types forcomplex are the same as those forfloat ('%' is not allowed). Both the real and imaginary componentsof a complex number are formatted as floating-point numbers, according to thespecified presentation type. They are separated by the mandatory sign of theimaginary part, the latter being terminated by aj suffix. If the presentationtype is missing, the result will match the output ofstr() (complex numbers witha non-zero real part are also surrounded by parentheses), possibly altered byother format modifiers.

Format examples

This section contains examples of thestr.format() syntax andcomparison with the old%-formatting.

In most of the cases the syntax is similar to the old%-formatting, with theaddition of the{} and with: used instead of%.For example,'%03.2f' can be translated to'{:03.2f}'.

The new format syntax also supports new and different options, shown in thefollowing examples.

Accessing arguments by position:

>>>'{0},{1},{2}'.format('a','b','c')'a, b, c'>>>'{},{},{}'.format('a','b','c')# 3.1+ only'a, b, c'>>>'{2},{1},{0}'.format('a','b','c')'c, b, a'>>>'{2},{1},{0}'.format(*'abc')# unpacking argument sequence'c, b, a'>>>'{0}{1}{0}'.format('abra','cad')# arguments' indices can be repeated'abracadabra'

Accessing arguments by name:

>>>'Coordinates:{latitude},{longitude}'.format(latitude='37.24N',longitude='-115.81W')'Coordinates: 37.24N, -115.81W'>>>coord={'latitude':'37.24N','longitude':'-115.81W'}>>>'Coordinates:{latitude},{longitude}'.format(**coord)'Coordinates: 37.24N, -115.81W'

Accessing arguments’ attributes:

>>>c=3-5j>>>('The complex number{0} is formed from the real part{0.real} '...'and the imaginary part{0.imag}.').format(c)'The complex number (3-5j) is formed from the real part 3.0 and the imaginary part -5.0.'>>>classPoint:...def__init__(self,x,y):...self.x,self.y=x,y...def__str__(self):...return'Point({self.x},{self.y})'.format(self=self)...>>>str(Point(4,2))'Point(4, 2)'

Accessing arguments’ items:

>>>coord=(3,5)>>>'X:{0[0]};  Y:{0[1]}'.format(coord)'X: 3;  Y: 5'

Replacing%s and%r:

>>>"repr() shows quotes:{!r}; str() doesn't:{!s}".format('test1','test2')"repr() shows quotes: 'test1'; str() doesn't: test2"

Aligning the text and specifying a width:

>>>'{:<30}'.format('left aligned')'left aligned                  '>>>'{:>30}'.format('right aligned')'                 right aligned'>>>'{:^30}'.format('centered')'           centered           '>>>'{:*^30}'.format('centered')# use '*' as a fill char'***********centered***********'

Replacing%+f,%-f, and%f and specifying a sign:

>>>'{:+f};{:+f}'.format(3.14,-3.14)# show it always'+3.140000; -3.140000'>>>'{: f};{: f}'.format(3.14,-3.14)# show a space for positive numbers' 3.140000; -3.140000'>>>'{:-f};{:-f}'.format(3.14,-3.14)# show only the minus -- same as '{:f}; {:f}''3.140000; -3.140000'

Replacing%x and%o and converting the value to different bases:

>>># format also supports binary numbers>>>"int:{0:d};  hex:{0:x};  oct:{0:o};  bin:{0:b}".format(42)'int: 42;  hex: 2a;  oct: 52;  bin: 101010'>>># with 0x, 0o, or 0b as prefix:>>>"int:{0:d};  hex:{0:#x};  oct:{0:#o};  bin:{0:#b}".format(42)'int: 42;  hex: 0x2a;  oct: 0o52;  bin: 0b101010'

Using the comma or the underscore as a digit group separator:

>>>'{:,}'.format(1234567890)'1,234,567,890'>>>'{:_}'.format(1234567890)'1_234_567_890'>>>'{:_b}'.format(1234567890)'100_1001_1001_0110_0000_0010_1101_0010'>>>'{:_x}'.format(1234567890)'4996_02d2'

Expressing a percentage:

>>>points=19>>>total=22>>>'Correct answers:{:.2%}'.format(points/total)'Correct answers: 86.36%'

Using type-specific formatting:

>>>importdatetime>>>d=datetime.datetime(2010,7,4,12,15,58)>>>'{:%Y-%m-%d %H:%M:%S}'.format(d)'2010-07-04 12:15:58'

Nesting arguments and more complex examples:

>>>foralign,textinzip('<^>',['left','center','right']):...'{0:{fill}{align}16}'.format(text,fill=align,align=align)...'left<<<<<<<<<<<<''^^^^^center^^^^^''>>>>>>>>>>>right'>>>>>>octets=[192,168,0,1]>>>'{:02X}{:02X}{:02X}{:02X}'.format(*octets)'C0A80001'>>>int(_,16)3232235521>>>>>>width=5>>>fornuminrange(5,12):...forbasein'dXob':...print('{0:{width}{base}}'.format(num,base=base,width=width),end=' ')...print()...    5     5     5   101    6     6     6   110    7     7     7   111    8     8    10  1000    9     9    11  1001   10     A    12  1010   11     B    13  1011

Template strings

Template strings provide simpler string substitutions as described inPEP 292. A primary use case for template strings is forinternationalization (i18n) since in that context, the simpler syntax andfunctionality makes it easier to translate than other built-in stringformatting facilities in Python. As an example of a library built on templatestrings for i18n, see theflufl.i18n package.

Template strings support$-based substitutions, using the following rules:

  • $$ is an escape; it is replaced with a single$.

  • $identifier names a substitution placeholder matching a mapping key of"identifier". By default,"identifier" is restricted to anycase-insensitive ASCII alphanumeric string (including underscores) thatstarts with an underscore or ASCII letter. The first non-identifiercharacter after the$ character terminates this placeholderspecification.

  • ${identifier} is equivalent to$identifier. It is required whenvalid identifier characters follow the placeholder but are not part of theplaceholder, such as"${noun}ification".

Any other appearance of$ in the string will result in aValueErrorbeing raised.

Thestring module provides aTemplate class that implementsthese rules. The methods ofTemplate are:

classstring.Template(template)

The constructor takes a single argument which is the template string.

substitute(mapping={},/,**kwds)

Performs the template substitution, returning a new string.mapping isany dictionary-like object with keys that match the placeholders in thetemplate. Alternatively, you can provide keyword arguments, where thekeywords are the placeholders. When bothmapping andkwds are givenand there are duplicates, the placeholders fromkwds take precedence.

safe_substitute(mapping={},/,**kwds)

Likesubstitute(), except that if placeholders are missing frommapping andkwds, instead of raising aKeyError exception, theoriginal placeholder will appear in the resulting string intact. Also,unlike withsubstitute(), any other appearances of the$ willsimply return$ instead of raisingValueError.

While other exceptions may still occur, this method is called “safe”because it always tries to return a usable string instead ofraising an exception. In another sense,safe_substitute() may beanything other than safe, since it will silently ignore malformedtemplates containing dangling delimiters, unmatched braces, orplaceholders that are not valid Python identifiers.

is_valid()

ReturnsFalse if the template has invalid placeholders that will causesubstitute() to raiseValueError.

Added in version 3.11.

get_identifiers()

Returns a list of the valid identifiers in the template, in the orderthey first appear, ignoring any invalid identifiers.

Added in version 3.11.

Template instances also provide one public data attribute:

template

This is the object passed to the constructor’stemplate argument. Ingeneral, you shouldn’t change it, but read-only access is not enforced.

Here is an example of how to use a Template:

>>>fromstringimportTemplate>>>s=Template('$who likes $what')>>>s.substitute(who='tim',what='kung pao')'tim likes kung pao'>>>d=dict(who='tim')>>>Template('Give $who $100').substitute(d)Traceback (most recent call last):...ValueError:Invalid placeholder in string: line 1, col 11>>>Template('$who likes $what').substitute(d)Traceback (most recent call last):...KeyError:'what'>>>Template('$who likes $what').safe_substitute(d)'tim likes $what'

Advanced usage: you can derive subclasses ofTemplate to customizethe placeholder syntax, delimiter character, or the entire regular expressionused to parse template strings. To do this, you can override these classattributes:

  • delimiter – This is the literal string describing a placeholderintroducing delimiter. The default value is$. Note that this shouldnot be a regular expression, as the implementation will callre.escape() on this string as needed. Note further that you cannotchange the delimiter after class creation (i.e. a different delimiter mustbe set in the subclass’s class namespace).

  • idpattern – This is the regular expression describing the pattern fornon-braced placeholders. The default value is the regular expression(?a:[_a-z][_a-z0-9]*). If this is given andbraceidpattern isNone this pattern will also apply to braced placeholders.

    Note

    Since defaultflags isre.IGNORECASE, pattern[a-z] can matchwith some non-ASCII characters. That’s why we use the locala flaghere.

    Changed in version 3.7:braceidpattern can be used to define separate patterns used inside andoutside the braces.

  • braceidpattern – This is likeidpattern but describes the pattern forbraced placeholders. Defaults toNone which means to fall back toidpattern (i.e. the same pattern is used both inside and outside braces).If given, this allows you to define different patterns for braced andunbraced placeholders.

    Added in version 3.7.

  • flags – The regular expression flags that will be applied when compilingthe regular expression used for recognizing substitutions. The default valueisre.IGNORECASE. Note thatre.VERBOSE will always be added to theflags, so customidpatterns must follow conventions for verbose regularexpressions.

    Added in version 3.2.

Alternatively, you can provide the entire regular expression pattern byoverriding the class attributepattern. If you do this, the value must be aregular expression object with four named capturing groups. The capturinggroups correspond to the rules given above, along with the invalid placeholderrule:

  • escaped – This group matches the escape sequence, e.g.$$, in thedefault pattern.

  • named – This group matches the unbraced placeholder name; it should notinclude the delimiter in capturing group.

  • braced – This group matches the brace enclosed placeholder name; it shouldnot include either the delimiter or braces in the capturing group.

  • invalid – This group matches any other delimiter pattern (usually a singledelimiter), and it should appear last in the regular expression.

The methods on this class will raiseValueError if the pattern matchesthe template without one of these named groups matching.

Helper functions

string.capwords(s,sep=None)

Split the argument into words usingstr.split(), capitalize each wordusingstr.capitalize(), and join the capitalized words usingstr.join(). If the optional second argumentsep is absentorNone, runs of whitespace characters are replaced by a single spaceand leading and trailing whitespace are removed, otherwisesep is used tosplit and join the words.