1. String Substitution Python
2. Python Template Substitution Worksheets
3. Python Variable Substitution

Source code:Lib/string.py

Templates support $-based substitutions instead of%-based substitution. Substitute (mapping, keywords) performs template substitution, returning a new string. Mapping is any dictionary-like object with keys that match with the template placeholders. In this example, price and qty are placeholders. Keyword arguments can also be used as placeholders.

The string module contains a number of useful constants andclasses, as well as some deprecated legacy functions that are alsoavailable as methods on strings. In addition, Python’s built-in stringclasses support the sequence type methods described in theSequence Types — str, unicode, list, tuple, bytearray, buffer, xrange section, and also the string-specific methods describedin the String Methods section. To output formatted strings usetemplate strings or the % operator described in theString Formatting Operations section. Also, see the re module forstring functions based on regular expressions.

7.1.1. String constants¶

The constants defined in this module are:

The concatenation of the ascii_lowercase and ascii_uppercaseconstants described below. This value is not locale-dependent.

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

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

The string '0123456789'.

The string '0123456789abcdefABCDEF'.

The concatenation of the strings lowercase and uppercasedescribed below. The specific value is locale-dependent, and will be updatedwhen locale.setlocale() is called.

A string containing all the characters that are considered lowercase letters.On most systems this is the string 'abcdefghijklmnopqrstuvwxyz'. Thespecific value is locale-dependent, and will be updated whenlocale.setlocale() is called.

The string '01234567'.

String of ASCII characters which are considered punctuation characters in theC locale.

String of characters which are considered printable. This is a combination ofdigits, letters, punctuation, andwhitespace.

A string containing all the characters that are considered uppercase letters.On most systems this is the string 'ABCDEFGHIJKLMNOPQRSTUVWXYZ'. Thespecific value is locale-dependent, and will be updated whenlocale.setlocale() is called.

A string containing all characters that are considered whitespace. On mostsystems this includes the characters space, tab, linefeed, return, formfeed, andvertical tab.

7.1.2. Custom String Formatting¶

The built-in str and unicode classes provide the abilityto do complex variable substitutions and value formatting via thestr.format() method described in PEP 3101. The Formatterclass in the string module allows you to create and customize your ownstring formatting behaviors using the same implementation as the built-informat() method.

The Formatter class has the following public methods:

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

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:

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.

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

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.

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() simply calls the global format() built-in. Themethod is provided so that subclasses can override it.

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.

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

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:

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. 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 2.7: The positional argument specifiers can be omitted for str.format() andunicode.format(), so '{}{}' is equivalent to '{0}{1}',u'{}{}' is equivalent to u'{0}{1}'.

Some simple format string examples:

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.

Two conversion flags are currently supported: '!s' which calls str()on the value, and '!r' which calls repr().

Some examples:

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.

7.1.3.1. 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). 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 string (') producesthe same result as if you had called str() on the value. Anon-empty format string typically modifies the result.

The general form of a standard format specifier is:

If a valid align value is specified, it can be preceded by a fillcharacter that can be any character and defaults to a space if omitted.It is not possible to use a literal curly brace (“{” or “}”) asthe fill character when using the str.format()method. However, it is possible to insert a curly bracewith a nested replacement field. This limitation doesn’taffect the format() function.

The meaning of the various alignment options is as follows:

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.

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

The '#' option is only valid for integers, and only for binary, octal, orhexadecimal output. If present, it specifies that the output will be prefixedby '0b', '0o', or '0x', respectively.

The ',' option signals the use of a comma for a thousands separator.For a locale aware separator, use the 'n' integer presentation typeinstead.

Changed in version 2.7: Added the ',' option (see also PEP 378).

width is a decimal integer defining the minimum field width. If notspecified, then the field width will be determined by the content.

When no explicit alignment is given, preceding the width field by a zero('0') character enablessign-aware zero-padding for numeric types. This is equivalent to a fillcharacter of '0' with an alignment type of '='.

The precision is a decimal number indicating how many digits should bedisplayed after the decimal point for a floating point value formatted with'f' and 'F', or before and after the decimal point for a floating pointvalue formatted with 'g' or 'G'. For non-number types the fieldindicates the maximum field size - in other words, how many characters will beused from the field content. The precision is not allowed for integer values.

Finally, the type determines how the data should be presented.

The available string presentation types are:

The available integer presentation types are:

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

The available presentation types for floating point and decimal values are:

7.1.3.2. Format examples¶

This section contains examples of the str.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:

Accessing arguments by name:

Accessing arguments’ attributes:

Accessing arguments’ items:

Replacing %s and %r:

Aligning the text and specifying a width:

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

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

Using the comma as a thousands separator:

Expressing a percentage:

Using type-specific formatting:

Nesting arguments and more complex examples:

7.1.4. 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 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 a ValueErrorbeing raised.

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

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

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 kws are givenand there are duplicates, the placeholders from kws take precedence.

Like substitute(), except that if placeholders are missing frommapping and kws, 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.

Template instances also provide one public data attribute:

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:

Advanced usage: you can derive subclasses of Template 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 should not be aregular expression, as the implementation will call re.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]*.

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.

7.1.5. String functions¶

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

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.

Return a translation table suitable for passing to translate(), that willmap each character in from into the character at the same position in to;from and to must have the same length.

Note

Don’t use strings derived from lowercase and uppercase asarguments; in some locales, these don’t have the same length. For caseconversions, always use str.lower() and str.upper().

7.1.6. Deprecated string functions¶

The following list of functions are also defined as methods of string andUnicode objects; see section String Methods for more information onthose. You should consider these functions as deprecated, although they willnot be removed until Python 3. The functions defined in this module are:

String Substitution Python

Deprecated since version 2.0: Use the float() built-in function.

Convert a string to a floating point number. The string must have the standardsyntax for a floating point literal in Python, optionally preceded by a sign(+ or -). Note that this behaves identical to the built-in functionfloat() when passed a string.

Note

When passing in a string, values for NaN and Infinity may be returned, dependingon the underlying C library. The specific set of strings accepted which causethese values to be returned depends entirely on the C library and is known tovary.

Deprecated since version 2.0: Use the int() built-in function.

Convert string s to an integer in the given base. The string must consistof one or more digits, optionally preceded by a sign (+ or -). Thebase defaults to 10. If it is 0, a default base is chosen depending on theleading characters of the string (after stripping the sign): 0x or 0Xmeans 16, 0 means 8, anything else means 10. If base is 16, a leading0x or 0X is always accepted, though not required. This behavesidentically to the built-in function int() when passed a string. (Alsonote: for a more flexible interpretation of numeric literals, use the built-infunction eval().)

Deprecated since version 2.0: Use the long() built-in function.

Python Template Substitution Worksheets

Convert string s to a long integer in the given base. The string mustconsist of one or more digits, optionally preceded by a sign (+ or -).The base argument has the same meaning as for atoi(). A trailing lor L is not allowed, except if the base is 0. Note that when invokedwithout base or with base set to 10, this behaves identical to the built-infunction long() when passed a string.

Return a copy of word with only its first character capitalized.

Expand tabs in a string replacing them by one or more spaces, depending on thecurrent column and the given tab size. The column number is reset to zero aftereach newline occurring in the string. This doesn’t understand other non-printingcharacters or escape sequences. The tab size defaults to 8.

Return the lowest index in s where the substring sub is found such thatsub is wholly contained in s[start:end]. Return -1 on failure.Defaults for start and end and interpretation of negative values is the sameas for slices.

Like find() but find the highest index.

Like find() but raise ValueError when the substring is not found.

Like rfind() but raise ValueError when the substring is not found.

Return the number of (non-overlapping) occurrences of substring sub in strings[start:end]. Defaults for start and end and interpretation of negativevalues are the same as for slices.

Return a copy of s, but with upper case letters converted to lower case.

Return a list of the words of the string s. If the optional second argumentsep is absent or None, the words are separated by arbitrary strings ofwhitespace characters (space, tab, newline, return, formfeed). If the secondargument sep is present and not None, it specifies a string to be used asthe word separator. The returned list will then have one more item than thenumber of non-overlapping occurrences of the separator in the string.If maxsplit is given, at most maxsplit number of splits occur, and theremainder of the string is returned as the final element of the list (thus,the list will have at most maxsplit+1 elements). If maxsplit is notspecified or -1, then there is no limit on the number of splits (allpossible splits are made).

The behavior of split on an empty string depends on the value of sep. If sepis not specified, or specified as None, the result will be an empty list.If sep is specified as any string, the result will be a list containing oneelement which is an empty string.

Return a list of the words of the string s, scanning s from the end. To allintents and purposes, the resulting list of words is the same as returned bysplit(), except when the optional third argument maxsplit is explicitlyspecified and nonzero. If maxsplit is given, at most maxsplit number ofsplits – the rightmost ones – occur, and the remainder of the string isreturned as the first element of the list (thus, the list will have at mostmaxsplit+1 elements).

This function behaves identically to split(). (In the past, split()was only used with one argument, while splitfields() was only used withtwo arguments.)

Concatenate a list or tuple of words with intervening occurrences of sep.The default value for sep is a single space character. It is always true thatstring.join(string.split(s,sep),sep) equals s.

Python Variable Substitution

This function behaves identically to join(). (In the past, join()was only used with one argument, while joinfields() was only used with twoarguments.) Note that there is no joinfields() method on string objects;use the join() method instead.

Return a copy of the string with leading characters removed. If chars isomitted or None, whitespace characters are removed. If given and notNone, chars must be a string; the characters in the string will bestripped from the beginning of the string this method is called on.

Changed in version 2.2.3: The chars parameter was added. The chars parameter cannot be passed inearlier 2.2 versions.

Return a copy of the string with trailing characters removed. If chars isomitted or None, whitespace characters are removed. If given and notNone, chars must be a string; the characters in the string will bestripped from the end of the string this method is called on.

Changed in version 2.2.3: The chars parameter was added. The chars parameter cannot be passed inearlier 2.2 versions.

Return a copy of the string with leading and trailing characters removed. Ifchars is omitted or None, whitespace characters are removed. If given andnot None, chars must be a string; the characters in the string will bestripped from the both ends of the string this method is called on.

Changed in version 2.2.3: The chars parameter was added. The chars parameter cannot be passed inearlier 2.2 versions.

Return a copy of s, but with lower case letters converted to upper case andvice versa.

Delete all characters from s that are in deletechars (if present), and thentranslate the characters using table, which must be a 256-character stringgiving the translation for each character value, indexed by its ordinal. Iftable is None, then only the character deletion step is performed.

Return a copy of s, but with lower case letters converted to upper case.

These functions respectively left-justify, right-justify and center a string ina field of given width. They return a string that is at least widthcharacters wide, created by padding the string s with the character fillchar(default is a space) until the given width on the right, left or both sides.The string is never truncated.

Pad a numeric string s on the left with zero digits until thegiven width is reached. Strings starting with a sign are handledcorrectly.

Return a copy of string s with all occurrences of substring old replacedby new. If the optional argument maxreplace is given, the firstmaxreplace occurrences are replaced.

Python is an interpreted, object-oriented, high-level programming language. It is easy to learn because its syntax emphasizes readability, which reduces the expense of program maintenance. Many programmers love working with Python because—without the compilation step—testing and debugging go quickly.​

Python Web Templating

Templating, especially web templating, represents data in forms usually intended to be readable by a viewer. The simplest form of a templating engine substitutes values into the template to produce the output.

Aside from the string constants and the deprecated string functions, which moved to string methods, Python's string module also includes string templates. The template itself is a class that receives a string as its argument. The object instantiated from that class is called a template string object. Template strings were first introduced in Python 2.4. Where string formatting operators used the percentage sign for substitutions, the template object uses dollar signs.

• $$ is an escape sequence; 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.

Outside of these uses of the dollar sign, any appearance of $ causes a ValueError to be raised. The methods available through template strings are as follows:

• Class string. Template(template): The constructor takes a single argument, which is the template string.
• Substitute(mapping, **keywords): Method that substitutes the string values (mapping) for the template string values. Mapping is a dictionary-like object, and its values may be accessed as a dictionary. If the keywords argument is used, it represents placeholders. Where both mapping and keywords are used, the latter takes precedence. If a placeholder is missing from mapping or keywords, a KeyError is thrown.
• Safe_substitute(mapping, **keywords): Functions similarly to substitute(). However, if a placeholder is missing from mapping or keywords, the original placeholder is used by default, thus avoiding the KeyError. Also, any occurrence of '$' returns a dollar sign.

Template objects also have one publicly available attribute:

• Template is the object passed to the constructor's template argument. While read-only access is not enforced, it is best not to change this attribute in your program.

The sample shell session below serves to illustrate template string objects.