Abstract

This PEP describes a simpler string substitution feature, also known as string interpolation. This PEP is “simpler” in two respects:

1. Python’s current string substitution feature (i.e.%-substitution) is complicated and error prone. This PEP is simpler at the cost of some expressiveness.
2. PEP 215proposed an alternative string interpolation feature, introducing a new$string prefix.PEP 292is simpler than this because it involves no syntax changes and has much simpler rules for what substitutions can occur in the string.

Rationale

Python currently supports a string substitution syntax based on C’sprintf()‘%’ formatting character[1].While quite rich, %-formatting codes are also error prone, even for experienced Python programmers. A common mistake is to leave off the trailing format character, e.g. the ‘s’ in"%(name)s".

In addition, the rules for what can follow a%sign are fairly complex, while the usual application rarely needs such complexity. Most scripts need to do some string interpolation, but most of those use simple ‘stringification’ formats, i.e.%sor%(name)s This form should be made simpler and less error prone.

A Simpler Proposal

We propose the addition of a new class, calledTemplate,which will live in the string module. TheTemplateclass supports new rules for string substitution; its value contains placeholders, introduced with the$character. The following rules for $-placeholders apply:

1. $$is an escape; it is replaced with a single$
2. $identifiernames a substitution placeholder matching a mapping key of “identifier”. By default, “identifier” must spell a Python identifier as defined in[2].The first non-identifier character after the$character terminates this placeholder specification.
3. ${identifier}is equivalent to$identifier.It is required when valid identifier characters follow the placeholder but are not part of the placeholder, e.g."${noun}ification".

If the$character appears at the end of the line, or is followed by any other character than those described above, aValueError will be raised at interpolation time. Values in mapping are converted automatically to strings.

No other characters have special meaning, however it is possible to derive from theTemplateclass to define different substitution rules. For example, a derived class could allow for periods in the placeholder (e.g. to support a kind of dynamic namespace and attribute path lookup), or could define a delimiter character other than$.

Once theTemplatehas been created, substitutions can be performed by calling one of two methods:

• substitute().This method returns a new string which results when the values of a mapping are substituted for the placeholders in theTemplate.If there are placeholders which are not present in the mapping, aKeyErrorwill be raised.
• safe_substitute().This is similar to thesubstitute()method, except thatKeyErrorsare never raised (due to placeholders missing from the mapping). When a placeholder is missing, the original placeholder will appear in the resulting string.

  Here are some examples:

  >>>fromstringimportTemplate
  >>>s=Template('${name}was born in ${country}')
  >>>prints.substitute(name='Guido',country='the Netherlands')
  Guido was born in the Netherlands
  >>>prints.substitute(name='Guido')
  Traceback (most recent call last):
  [...]
  KeyError:'country'
  >>>prints.safe_substitute(name='Guido')
  Guido was born in ${country}
  

The signature ofsubstitute()andsafe_substitute()allows for passing the mapping of placeholders to values, either as a single dictionary-like object in the first positional argument, or as keyword arguments as shown above. The exact details and signatures of these two methods is reserved for the standard library documentation.

Why$and Braces?

The BDFL said it best[3]:“The$means “substitution” in so many languages besides Perl that I wonder where you’ve been. […] We’re copying this from the shell.”

Thus the substitution rules are chosen because of the similarity with so many other languages. This makes the substitution rules easier to teach, learn, and remember.

Comparison to PEP 215

PEP 215describes an alternate proposal for string interpolation. Unlike that PEP, this one does not propose any new syntax for Python. All the proposed new features are embodied in a new library module.PEP 215proposes a new string prefix representation such as$ ""which signal to Python that a new type of string is present.$-strings would have to interact with the existing r-prefixes and u-prefixes, essentially doubling the number of string prefix combinations.

PEP 215also allows for arbitrary Python expressions inside the $-strings, so that you could do things like:

import sys
print $ "sys = $sys, sys = $sys.modules['sys']"

which would return:

sys=<module'sys'(built-in)>,sys=<module'sys'(built-in)>

It’s generally accepted that the rules inPEP 215are safe in the sense that they introduce no new security issues (seePEP 215, “Security Issues” for details). However, the rules are still quite complex, and make it more difficult to see the substitution placeholder in the original$-string.

The interesting thing is that theTemplateclass defined in this PEP is designed for inheritance and, with a little extra work, it’s possible to supportPEP 215’s functionality using existing Python syntax.

For example, one could define subclasses ofTemplateand dict that allowed for a more complex placeholder syntax and a mapping that evaluated those placeholders.

Internationalization

The implementation supports internationalization by recording the original template string in theTemplateinstance’stemplate attribute. This attribute would serve as the lookup key in an gettext-based catalog. It is up to the application to turn the resulting string back into aTemplatefor substitution.

However, theTemplateclass was designed to work more intuitively in an internationalized application, by supporting the mi xing -in ofTemplateand unicode subclasses. Thus an internationalized application could create an application-specific subclass, multiply inheriting fromTemplateand unicode, and using instances of that subclass as the gettext catalog key. Further, the subclass could alias the special__mod__()method to either .substitute()or.safe_substitute()to provide a more traditional string/unicode like%-operator substitution syntax.

Reference Implementation

The implementation[4]has been committed to the Python 2.4 source tree.

References

Copyright

This document has been placed in the public domain.