1. Georg Brandl
  2. sphinx


sphinx / Doc-26 / library / string.rst

:mod:`string` --- Common string operations

The :mod:`string` module contains a number of useful constants and classes, as well as some deprecated legacy functions that are also available as methods on strings. In addition, Python's built-in string classes support the sequence type methods described in the :ref:`typesseq` section, and also the string-specific methods described in the :ref:`string-methods` section. To output formatted strings use template strings or the % operator described in the :ref:`typesseq-strings` section. Also, see the :mod:`re` module for string functions based on regular expressions.

String constants

The constants defined in this module are:

Template strings

Templates provide simpler string substitutions as described in PEP 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 Python identifier. The first non-identifier character after the $ character terminates this placeholder specification.
  • ${identifier} is equivalent to $identifier. It is required when valid identifier characters follow the placeholder but are not part of the placeholder, such as "${noun}ification".

Any other appearance of $ in the string will result in a :exc:`ValueError` being raised.

The :mod:`string` module provides a :class:`Template` class that implements these rules. The methods of :class:`Template` are:

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

:class:`Template` instances also provide one public data attribute:

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

  • delimiter -- This is the literal string describing a placeholder introducing delimiter. The default value $. Note that this should not be a regular expression, as the implementation will call :meth:`re.escape` on this string as needed.
  • idpattern -- This is the regular expression describing the pattern for non-braced placeholders (the braces will be added automatically as appropriate). The default value is the regular expression [_a-z][_a-z0-9]*.

Alternatively, you can provide the entire regular expression pattern by overriding the class attribute pattern. If you do this, the value must be a regular expression object with four named capturing groups. The capturing groups correspond to the rules given above, along with the invalid placeholder rule:

  • escaped -- This group matches the escape sequence, e.g. $$, in the default pattern.
  • named -- This group matches the unbraced placeholder name; it should not include the delimiter in capturing group.
  • braced -- This group matches the brace enclosed placeholder name; it should not include either the delimiter or braces in the capturing group.
  • invalid -- This group matches any other delimiter pattern (usually a single delimiter), and it should appear last in the regular expression.

String functions

The following functions are available to operate on string and Unicode objects. They are not available as string methods.

Deprecated string functions

The following list of functions are also defined as methods of string and Unicode objects; see section :ref:`string-methods` for more information on those. You should consider these functions as deprecated, although they will not be removed until Python 3.0. The functions defined in this module are: