<!DOCTYPE html PUBLIC
"-//W3C//DTD HTML 4.0 Transitional//EN">
<link rel=
"STYLESHEET" href=
"lib.css" type='text/css'
/>
<link rel=
"SHORTCUT ICON" href=
"../icons/pyfav.png" type=
"image/png" />
<link rel='start' href='../index.html' title='Python Documentation Index'
/>
<link rel=
"first" href=
"lib.html" title='Python Library Reference'
/>
<link rel='contents' href='contents.html'
title=
"Contents" />
<link rel='index' href='genindex.html' title='Index'
/>
<link rel='last' href='about.html' title='About this document...'
/>
<link rel='help' href='about.html' title='About this document...'
/>
<link rel=
"next" href=
"typesseq-xrange.html" />
<link rel=
"prev" href=
"string-methods.html" />
<link rel=
"parent" href=
"typesseq.html" />
<link rel=
"next" href=
"typesseq-xrange.html" />
<meta name='aesop' content='information'
/>
<title>2.3.6.2 String Formatting Operations
</title>
<div id='top-navigation-panel' xml:id='top-navigation-panel'
>
<table align=
"center" width=
"100%" cellpadding=
"0" cellspacing=
"2">
<td class='online-navigation'
><a rel=
"prev" title=
"2.3.6.1 String Methods"
href=
"string-methods.html"><img src='../icons/previous.png'
border='
0' height='
32' alt='Previous Page' width='
32'
/></A></td>
<td class='online-navigation'
><a rel=
"parent" title=
"2.3.6 Sequence Types "
href=
"typesseq.html"><img src='../icons/up.png'
border='
0' height='
32' alt='Up One Level' width='
32'
/></A></td>
<td class='online-navigation'
><a rel=
"next" title=
"2.3.6.3 XRange Type"
href=
"typesseq-xrange.html"><img src='../icons/next.png'
border='
0' height='
32' alt='Next Page' width='
32'
/></A></td>
<td align=
"center" width=
"100%">Python Library Reference
</td>
<td class='online-navigation'
><a rel=
"contents" title=
"Table of Contents"
href=
"contents.html"><img src='../icons/contents.png'
border='
0' height='
32' alt='Contents' width='
32'
/></A></td>
<td class='online-navigation'
><a href=
"modindex.html" title=
"Module Index"><img src='../icons/modules.png'
border='
0' height='
32' alt='Module Index' width='
32'
/></a></td>
<td class='online-navigation'
><a rel=
"index" title=
"Index"
href=
"genindex.html"><img src='../icons/index.png'
border='
0' height='
32' alt='Index' width='
32'
/></A></td>
<div class='online-navigation'
>
<b class=
"navlabel">Previous:
</b>
<a class=
"sectref" rel=
"prev" href=
"string-methods.html">2.3.6.1 String Methods
</A>
<b class=
"navlabel">Up:
</b>
<a class=
"sectref" rel=
"parent" href=
"typesseq.html">2.3.6 Sequence Types
</A>
<b class=
"navlabel">Next:
</b>
<a class=
"sectref" rel=
"next" href=
"typesseq-xrange.html">2.3.6.3 XRange Type
</A>
<!--End of Navigation Panel-->
<H3><A NAME=
"SECTION004362000000000000000"></A><A NAME=
"typesseq-strings"></A>
2.3.6.2 String Formatting Operations
<a id='l2h-
211' xml:id='l2h-
211'
></a>
String and Unicode objects have one unique built-in operation: the
<code>%
</code> operator (modulo). This is also known as the string
<em>formatting
</em> or
<em>interpolation
</em> operator. Given
<code><var>format
</var> %
<var>values
</var></code> (where
<var>format
</var> is a string or
Unicode object),
<code>%
</code> conversion specifications in
<var>format
</var>
are replaced with zero or more elements of
<var>values
</var>. The effect
is similar to the using
<tt class=
"cfunction">sprintf()
</tt> in the C language. If
<var>format
</var> is a Unicode object, or if any of the objects being
converted using the
<code>%s
</code> conversion are Unicode objects, the
result will also be a Unicode object.
If
<var>format
</var> requires a single argument,
<var>values
</var> may be a
single non-tuple object.
<A NAME=
"tex2html9"
HREF=
"#foot2430"><SUP>2.8</SUP></A> Otherwise,
<var>values
</var> must be a tuple with
exactly the number of items specified by the format string, or a
single mapping object (for example, a dictionary).
A conversion specifier contains two or more characters and has the
following components, which must occur in this order:
<LI>The
"<tt class="character
">%</tt>" character, which marks the start of the
<LI>Mapping key (optional), consisting of a parenthesised sequence
of characters (for example,
<code>(somename)
</code>).
<LI>Conversion flags (optional), which affect the result of some
<LI>Minimum field width (optional). If specified as an
"<tt class="character
">*</tt>" (asterisk), the actual width is read from the
next element of the tuple in
<var>values
</var>, and the object to
convert comes after the minimum field width and optional
<LI>Precision (optional), given as a
"<tt class="character
">.</tt>" (dot) followed
by the precision. If specified as
"<tt class="character
">*</tt>" (an
asterisk), the actual width is read from the next element of
the tuple in
<var>values
</var>, and the value to convert comes after
<LI>Length modifier (optional).
When the right argument is a dictionary (or other mapping type), then
the formats in the string
<em>must
</em> include a parenthesised mapping key into
that dictionary inserted immediately after the
"<tt class="character
">%</tt>"
character. The mapping key selects the value to be formatted from the
<div class=
"verbatim"><pre>
>>> print '%(language)s has %(#)
03d quote types.' % \
{'language':
"Python",
"#":
2}
Python has
002 quote types.
In this case no
<code>*
</code> specifiers may occur in a format (since they
require a sequential parameter list).
The conversion flag characters are:
<div class=
"center"><table class=
"realtable">
<th class=
"center">Flag
</th>
<th class=
"left" >Meaning
</th>
<tr><td class=
"center" valign=
"baseline"><tt class=
"character">#
</tt></td>
<td class=
"left" >The value conversion will use the ``alternate form''
(where defined below).
</td></tr>
<tr><td class=
"center" valign=
"baseline"><tt class=
"character">0</tt></td>
<td class=
"left" >The conversion will be zero padded for numeric values.
</td></tr>
<tr><td class=
"center" valign=
"baseline"><tt class=
"character">-
</tt></td>
<td class=
"left" >The converted value is left adjusted (overrides
the
"<tt class="character
">0</tt>" conversion if both are given).
</td></tr>
<tr><td class=
"center" valign=
"baseline"><tt class=
"character"> </tt></td>
<td class=
"left" >(a space) A blank should be left before a positive number
(or empty string) produced by a signed conversion.
</td></tr>
<tr><td class=
"center" valign=
"baseline"><tt class=
"character">+
</tt></td>
<td class=
"left" >A sign character (
"<tt class="character
">+</tt>" or
"<tt class="character
">-</tt>") will
precede the conversion (overrides a
"space" flag).
</td></tr></tbody>
The length modifier may be
<code>h
</code>,
<code>l
</code>, and
<code>L
</code> may be
present, but are ignored as they are not necessary for Python.
The conversion types are:
<div class=
"center"><table class=
"realtable">
<th class=
"center">Conversion
</th>
<th class=
"left" >Meaning
</th>
<th class=
"center">Notes
</th>
<tr><td class=
"center" valign=
"baseline"><tt class=
"character">d
</tt></td>
<td class=
"left" >Signed integer decimal.
</td>
<td class=
"center"></td></tr>
<tr><td class=
"center" valign=
"baseline"><tt class=
"character">i
</tt></td>
<td class=
"left" >Signed integer decimal.
</td>
<td class=
"center"></td></tr>
<tr><td class=
"center" valign=
"baseline"><tt class=
"character">o
</tt></td>
<td class=
"left" >Unsigned octal.
</td>
<td class=
"center">(
1)
</td></tr>
<tr><td class=
"center" valign=
"baseline"><tt class=
"character">u
</tt></td>
<td class=
"left" >Unsigned decimal.
</td>
<td class=
"center"></td></tr>
<tr><td class=
"center" valign=
"baseline"><tt class=
"character">x
</tt></td>
<td class=
"left" >Unsigned hexadecimal (lowercase).
</td>
<td class=
"center">(
2)
</td></tr>
<tr><td class=
"center" valign=
"baseline"><tt class=
"character">X
</tt></td>
<td class=
"left" >Unsigned hexadecimal (uppercase).
</td>
<td class=
"center">(
2)
</td></tr>
<tr><td class=
"center" valign=
"baseline"><tt class=
"character">e
</tt></td>
<td class=
"left" >Floating point exponential format (lowercase).
</td>
<td class=
"center"></td></tr>
<tr><td class=
"center" valign=
"baseline"><tt class=
"character">E
</tt></td>
<td class=
"left" >Floating point exponential format (uppercase).
</td>
<td class=
"center"></td></tr>
<tr><td class=
"center" valign=
"baseline"><tt class=
"character">f
</tt></td>
<td class=
"left" >Floating point decimal format.
</td>
<td class=
"center"></td></tr>
<tr><td class=
"center" valign=
"baseline"><tt class=
"character">F
</tt></td>
<td class=
"left" >Floating point decimal format.
</td>
<td class=
"center"></td></tr>
<tr><td class=
"center" valign=
"baseline"><tt class=
"character">g
</tt></td>
<td class=
"left" >Same as
"<tt class="character
">e</tt>" if exponent is greater than -
4 or
less than precision,
"<tt class="character
">f</tt>" otherwise.
</td>
<td class=
"center"></td></tr>
<tr><td class=
"center" valign=
"baseline"><tt class=
"character">G
</tt></td>
<td class=
"left" >Same as
"<tt class="character
">E</tt>" if exponent is greater than -
4 or
less than precision,
"<tt class="character
">F</tt>" otherwise.
</td>
<td class=
"center"></td></tr>
<tr><td class=
"center" valign=
"baseline"><tt class=
"character">c
</tt></td>
<td class=
"left" >Single character (accepts integer or single character
<td class=
"center"></td></tr>
<tr><td class=
"center" valign=
"baseline"><tt class=
"character">r
</tt></td>
<td class=
"left" >String (converts any python object using
<tt class=
"function">repr()
</tt>).
</td>
<td class=
"center">(
3)
</td></tr>
<tr><td class=
"center" valign=
"baseline"><tt class=
"character">s
</tt></td>
<td class=
"left" >String (converts any python object using
<tt class=
"function">str()
</tt>).
</td>
<td class=
"center">(
4)
</td></tr>
<tr><td class=
"center" valign=
"baseline"><tt class=
"character">%
</tt></td>
<td class=
"left" >No argument is converted, results in a
"<tt class="character
">%</tt>"
character in the result.
</td>
<td class=
"center"></td></tr></tbody>
<DT><STRONG>(
1)
</STRONG></DT>
<DD>The alternate form causes a leading zero (
"<tt class="character
">0</tt>") to be
inserted between left-hand padding and the formatting of the
number if the leading character of the result is not already a
<DT><STRONG>(
2)
</STRONG></DT>
<DD>The alternate form causes a leading
<code>'
0x'
</code> or
<code>'
0X'
</code>
(depending on whether the
"<tt class="character
">x</tt>" or
"<tt class="character
">X</tt>" format
was used) to be inserted between left-hand padding and the
formatting of the number if the leading character of the result is
<DT><STRONG>(
3)
</STRONG></DT>
<DD>The
<code>%r
</code> conversion was added in Python
2.0.
<DT><STRONG>(
4)
</STRONG></DT>
<DD>If the object or format provided is a
<tt class=
"class">unicode
</tt> string,
the resulting string will also be
<tt class=
"class">unicode
</tt>.
Since Python strings have an explicit length,
<code>%s
</code> conversions
do not assume that
<code>'
\0'
</code> is the end of the string.
For safety reasons, floating point precisions are clipped to
50;
<code>%f
</code> conversions for numbers whose absolute value is over
1e25
are replaced by
<code>%g
</code> conversions.
<A NAME=
"tex2html10"
HREF=
"#foot2537"><SUP>2.9</SUP></A> All other errors raise exceptions.
Additional string operations are defined in standard modules
<tt class=
"module"><a href=
"module-string.html">string
</a></tt><a id='l2h-
212' xml:id='l2h-
212'
></a> and
<tt class=
"module"><a href=
"module-re.html">re
</a></tt>.
<a id='l2h-
213' xml:id='l2h-
213'
></a>
<BR><HR><H4>Footnotes
</H4>
<DT><A NAME=
"foot2430">... object.
</A><A
href=
"typesseq-strings.html#tex2html9"><SUP>2.8</SUP></A></DT>
<DD>To format only a tuple you
should therefore provide a singleton tuple whose only element
is the tuple to be formatted.
<DT><A NAME=
"foot2537">... conversions.
</A><A
href=
"typesseq-strings.html#tex2html10"><SUP>2.9</SUP></A></DT>
These numbers are fairly arbitrary. They are intended to
avoid printing endless strings of meaningless digits without hampering
correct use and without having to know the exact precision of floating
point values on a particular machine.
<div class='online-navigation'
>
<table align=
"center" width=
"100%" cellpadding=
"0" cellspacing=
"2">
<td class='online-navigation'
><a rel=
"prev" title=
"2.3.6.1 String Methods"
href=
"string-methods.html"><img src='../icons/previous.png'
border='
0' height='
32' alt='Previous Page' width='
32'
/></A></td>
<td class='online-navigation'
><a rel=
"parent" title=
"2.3.6 Sequence Types "
href=
"typesseq.html"><img src='../icons/up.png'
border='
0' height='
32' alt='Up One Level' width='
32'
/></A></td>
<td class='online-navigation'
><a rel=
"next" title=
"2.3.6.3 XRange Type"
href=
"typesseq-xrange.html"><img src='../icons/next.png'
border='
0' height='
32' alt='Next Page' width='
32'
/></A></td>
<td align=
"center" width=
"100%">Python Library Reference
</td>
<td class='online-navigation'
><a rel=
"contents" title=
"Table of Contents"
href=
"contents.html"><img src='../icons/contents.png'
border='
0' height='
32' alt='Contents' width='
32'
/></A></td>
<td class='online-navigation'
><a href=
"modindex.html" title=
"Module Index"><img src='../icons/modules.png'
border='
0' height='
32' alt='Module Index' width='
32'
/></a></td>
<td class='online-navigation'
><a rel=
"index" title=
"Index"
href=
"genindex.html"><img src='../icons/index.png'
border='
0' height='
32' alt='Index' width='
32'
/></A></td>
<div class='online-navigation'
>
<b class=
"navlabel">Previous:
</b>
<a class=
"sectref" rel=
"prev" href=
"string-methods.html">2.3.6.1 String Methods
</A>
<b class=
"navlabel">Up:
</b>
<a class=
"sectref" rel=
"parent" href=
"typesseq.html">2.3.6 Sequence Types
</A>
<b class=
"navlabel">Next:
</b>
<a class=
"sectref" rel=
"next" href=
"typesseq-xrange.html">2.3.6.3 XRange Type
</A>
<span class=
"release-info">Release
2.4.2, documentation updated on
28 September
2005.
</span>
<!--End of Navigation Panel-->
See
<i><a href=
"about.html">About this document...
</a></i> for information on suggesting changes.