See also

Text Sequence Type — str

String Methods

6.1.1. 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. This is acombination ofdigits,ascii_letters,punctuation,andwhitespace.

string.whitespace¶

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

6.1.2. 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)¶

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

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.

6.1.3. 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).

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 |integer]attribute_name ::=identifierelement_index ::=integer |index_stringindex_string ::=  <any source character except "]"> +conversion ::=  "r" | "s" | "a"format_spec ::=  <described in the next section>

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. 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__().

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 can contain only a field name; conversion flagsand format specifications are not 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_spec ::=  [[fill]align][sign][#][0][width][,][.precision][type]fill ::=  <any character>align ::=  "<" | ">" | "=" | "^"sign ::=  "+" | "-" | " "width ::=integerprecision ::=integertype ::=  "b" | "c" | "d" | "e" | "E" | "f" | "F" | "g" | "G" | "n" | "o" | "s" | "x" | "X" | "%"

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

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

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

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

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

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

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

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

>>>'{:,}'.format(1234567890)'1,234,567,890'

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

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

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

6.1.4. Template strings¶

Templates provide simpler string substitutions as described inPEP 292.Instead of the normal%-based substitutions, Templates 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" must spell a Pythonidentifier. The first non-identifier character after the$ characterterminates this placeholder specification.
• ${identifier} is equivalent to$identifier. It is required when valididentifier 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 substitutions 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.

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 customize theplaceholder syntax, delimiter character, or the entire regular expression usedto parse template strings. To do this, you can override these class attributes:

• delimiter – This is the literal string describing a placeholder introducingdelimiter. The default value is$. Note that this shouldnot be aregular expression, as the implementation will callre.escape() on thisstring as needed.

• idpattern – This is the regular expression describing the pattern fornon-braced placeholders (the braces will be added automatically asappropriate). The default value is the regular expression[_a-z][_a-z0-9]*.

• 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.

  New 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.

6.1.5. 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.