string — Common string operations (2024)

String constants¶

The constants defined in this module are:

string.ascii_letters¶

The concatenation of the ascii_lowercase and ascii_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 the C locale: !"#$%&'()*+,-./:;<=>?@[\]^_`{|}~.

string.printable¶

String of ASCII characters which are considered printable. This is acombination of digits, ascii_letters, punctuation,and whitespace.

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 the format() method described inPEP 3101. The Formatter class in the string module allowsyou to create and customize your own string formatting behaviors using the sameimplementation as the built-in format() method.

class string.Formatter¶

The Formatter 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 calls vformat().

Changed in version 3.7: A format string argument is now positional-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, the Formatter 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 usedby vformat() 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 of field_name, format_spec and conversionwill be None.

get_field(field_name, args, kwargs)¶

Given field_name as returned by parse() (see above), convert it toan object to be formatted. Returns a tuple (obj, used_key). The defaultversion takes strings of the form defined in PEP 3101, such as“0[name]” or “label.title”. args and kwargs are as passed in tovformat(). The return value used_key has the same meaning as thekey parameter to get_value().

get_value(key, args, kwargs)¶

Retrieve a given field value. The key argument will be either aninteger or a string. If it is an integer, it represents the index of thepositional argument in args; if it is a string, then it represents anamed argument in kwargs.

The args parameter is set to the list of positional arguments tovformat(), and the kwargs 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 a key argument of 0. The nameattribute will be looked up after get_value() returns by calling thebuilt-in getattr() function.

If the index or keyword refers to an item that does not exist, then anIndexError or KeyError 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 the args and kwargs 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 global format() built-in. Themethod is provided so that subclasses can override it.

convert_field(value, conversion)¶

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

Format String Syntax¶

The str.format() method and the Formatter class share the samesyntax for format strings (although in the case of Formatter,subclasses can define their own format string syntax). The syntax isrelated to that of formatted 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 a field_name that specifiesthe object whose value is to be formatted and insertedinto the output instead of the replacement field.The field_name is optionally followed by a conversion field, which ispreceded by an exclamation point '!', and a format_spec, which is precededby a colon ':'. These specify a non-default format for the replacement value.

See also the Format Specification Mini-Language section.

The field_name itself begins with an arg_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. An arg_name is treated as a number ifa call to str.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.Because arg_name is not quote-delimited, it is not possible to specify arbitrarydictionary keys (e.g., the strings '10' or ':-]') within a format string.The arg_name can be followed by any number of index orattribute expressions. An expression of the form '.name' selects the namedattribute using getattr(), 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 for str.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 for Formatter.

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

The conversion 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 calls str()on the value, '!r' which calls repr() 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

The format_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 the format_spec.

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

A format_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 the format_spec string is interpreted.This allows the formatting of a value to be dynamically specified.

See the Format examples section for some examples.

format_spec  ::= [[fill]align][sign]["z"]["#"]["0"][width][grouping_option]["." precision][type]fill  ::= <any character>align  ::= "<" | ">" | "=" | "^"sign  ::= "+" | "-" | " "width  ::= digit+grouping_option ::= "_" | ","precision  ::= digit+type  ::= "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.'>>> class Point:...  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%'

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

>>> for align, text in zip('<^>', ['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>>> for num in range(5,12): ...  for base in '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 a ValueErrorbeing raised.

The string module provides a Template class that implementsthese rules. The methods of Template are:

class string.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 both mapping and kwds are givenand there are duplicates, the placeholders from kwds take precedence.

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

Like substitute(), except that if placeholders are missing frommapping and kwds, instead of raising a KeyError exception, theoriginal placeholder will appear in the resulting string intact. Also,unlike with substitute(), any other appearances of the $ willsimply return $ instead of raising ValueError.

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()¶

Returns false if the template has invalid placeholders that will causesubstitute() to raise ValueError.

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

New in version 3.11.

Template instances also provide one public data attribute:

template¶

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

Here is an example of how to use a Template:

>>> from string import Template>>> 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 of Template 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 and braceidpattern isNone this pattern will also apply to braced placeholders.

  Note

  Since default flags is re.IGNORECASE, pattern [a-z] can matchwith some non-ASCII characters. That’s why we use the local a flaghere.

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

• braceidpattern – This is like idpattern but describes the pattern forbraced placeholders. Defaults to None 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.

  New in version 3.7.

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

  New in version 3.2.

Alternatively, you can provide the entire regular expression pattern byoverriding the class attribute pattern. 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 raise ValueError if the pattern matchesthe template without one of these named groups matching.

Helper functions¶

string.capwords(s, sep=None)¶

Split the argument into words using str.split(), capitalize each wordusing str.capitalize(), and join the capitalized words usingstr.join(). If the optional second argument sep is absentor None, runs of whitespace characters are replaced by a single spaceand leading and trailing whitespace are removed, otherwise sep is used tosplit and join the words.