7.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.letters¶

The concatenation of the stringslowercase anduppercasedescribed below. The specific value is locale-dependent, and will be updatedwhenlocale.setlocale() is called.

string.lowercase¶

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.

string.octdigits¶

The string'01234567'.

string.punctuation¶

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

string.printable¶

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

string.uppercase¶

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.

string.whitespace¶

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 inPEP 3101. TheFormatterclass in thestring module allows you to create and customize your ownstring formatting behaviors using the same implementation as the built-informat() method.

classstring.Formatter¶

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

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

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

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

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 may contain a field name, conversion flagand format specification, but deeper nesting isnot 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')# 2.7+ 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(object):...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.5>>>total=22>>>'Correct answers:{:.2%}'.format(points/total)'Correct answers: 88.64%'

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

7.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[,**kws])¶

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

safe_substitute(mapping[,**kws])¶

Likesubstitute(), except that if placeholders are missing frommapping andkws, 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 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:

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]*.

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.

7.1.5.String functions¶

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

string.capwords(s[,sep])¶

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.

string.maketrans(from,to)¶

Return a translation table suitable for passing totranslate(), that willmap each character infrom into the character at the same position into;from andto must have the same length.

Note

Don’t use strings derived fromlowercase anduppercase asarguments; in some locales, these don’t have the same length. For caseconversions, always usestr.lower() andstr.upper().

7.1.6.Deprecated string functions¶

The following list of functions are also defined as methods of string andUnicode objects; see sectionString 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.atof(s)¶

Deprecated since version 2.0:Use thefloat() 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.

string.atoi(s[,base])¶

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

Convert strings to an integer in the givenbase. 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 or0Xmeans 16,0 means 8, anything else means 10. Ifbase is 16, a leading0x or0X is always accepted, though not required. This behavesidentically to the built-in functionint() when passed a string. (Alsonote: for a more flexible interpretation of numeric literals, use the built-infunctioneval().)

string.atol(s[,base])¶

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

Convert strings to a long integer in the givenbase. The string mustconsist of one or more digits, optionally preceded by a sign (+ or-).Thebase argument has the same meaning as foratoi(). A trailinglorL is not allowed, except if the base is 0. Note that when invokedwithoutbase or withbase set to 10, this behaves identical to the built-infunctionlong() when passed a string.

string.capitalize(word)¶

Return a copy ofword with only its first character capitalized.

string.expandtabs(s[,tabsize])¶

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.

string.find(s,sub[,start[,end]])¶

Return the lowest index ins where the substringsub is found such thatsub is wholly contained ins[start:end]. Return-1 on failure.Defaults forstart andend and interpretation of negative values is the sameas for slices.

string.rfind(s,sub[,start[,end]])¶

Likefind() but find the highest index.

string.index(s,sub[,start[,end]])¶

Likefind() but raiseValueError when the substring is not found.

string.rindex(s,sub[,start[,end]])¶

Likerfind() but raiseValueError when the substring is not found.

string.count(s,sub[,start[,end]])¶

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

string.lower(s)¶

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

string.split(s[,sep[,maxsplit]])¶

Return a list of the words of the strings. If the optional second argumentsep is absent orNone, the words are separated by arbitrary strings ofwhitespace characters (space, tab, newline, return, formfeed). If the secondargumentsep is present and notNone, 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.Ifmaxsplit is given, at mostmaxsplit number of splits occur, and theremainder of the string is returned as the final element of the list (thus,the list will have at mostmaxsplit+1 elements). Ifmaxsplit 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 ofsep. Ifsepis not specified, or specified asNone, the result will be an empty list.Ifsep is specified as any string, the result will be a list containing oneelement which is an empty string.

string.rsplit(s[,sep[,maxsplit]])¶

Return a list of the words of the strings, scannings from the end. To allintents and purposes, the resulting list of words is the same as returned bysplit(), except when the optional third argumentmaxsplit is explicitlyspecified and nonzero. Ifmaxsplit is given, at mostmaxsplit number ofsplits – therightmost 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).

New in version 2.4.

string.splitfields(s[,sep[,maxsplit]])¶

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

string.join(words[,sep])¶

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

string.joinfields(words[,sep])¶

This function behaves identically tojoin(). (In the past,join()was only used with one argument, whilejoinfields() was only used with twoarguments.) Note that there is nojoinfields() method on string objects;use thejoin() method instead.

string.lstrip(s[,chars])¶

Return a copy of the string with leading characters removed. Ifchars isomitted orNone, 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:Thechars parameter was added. Thechars parameter cannot be passed inearlier 2.2 versions.

string.rstrip(s[,chars])¶

Return a copy of the string with trailing characters removed. Ifchars isomitted orNone, 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:Thechars parameter was added. Thechars parameter cannot be passed inearlier 2.2 versions.

string.strip(s[,chars])¶

Return a copy of the string with leading and trailing characters removed. Ifchars is omitted orNone, whitespace characters are removed. If given andnotNone,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:Thechars parameter was added. Thechars parameter cannot be passed inearlier 2.2 versions.

string.swapcase(s)¶

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

string.translate(s,table[,deletechars])¶

Delete all characters froms that are indeletechars (if present), and thentranslate the characters usingtable, which must be a 256-character stringgiving the translation for each character value, indexed by its ordinal. Iftable isNone, then only the character deletion step is performed.

string.upper(s)¶

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

string.ljust(s,width[,fillchar])¶

string.rjust(s,width[,fillchar])¶

string.center(s,width[,fillchar])¶

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

string.zfill(s,width)¶

Pad a numeric strings on the left with zero digits until thegivenwidth is reached. Strings starting with a sign are handledcorrectly.

string.replace(s,old,new[,maxreplace])¶

Return a copy of strings with all occurrences of substringold replacedbynew. If the optional argumentmaxreplace is given, the firstmaxreplace occurrences are replaced.