GNU Info

Info Node: (python2.1-lib.info)String Formatting Operations

(python2.1-lib.info)String Formatting Operations


Next: XRange Type Prev: String Methods Up: Sequence Types
Enter node , (file) or (file)node

String Formatting Operations
............................

String and Unicode objects have one unique built-in operation: the `%'
operator (modulo).  Given `FORMAT % VALUES' (where FORMAT is a string
or Unicode object), `%' conversion specifications in FORMAT are
replaced with zero or more elements of VALUES.  The effect is similar
to the using `sprintf()' in the C language.  If FORMAT is a Unicode
object, or if any of the objects being converted using the `%s'
conversion are Unicode objects, the result will be a Unicode object as
well.

If FORMAT requires a single argument, VALUES may be a single non-tuple
object. (1)  Otherwise, VALUES 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:

  1. The `%' character, which marks the start of the specifier.

  2. Mapping key value (optional), consisting of an identifier in
     parentheses (for example, `(somename)').

  3. Conversion flags (optional), which affect the result of some
     conversion types.

  4. Minimum field width (optional).  If specified as an `*'
     (asterisk), the actual width is read from the next element of the
     tuple in VALUES, and the object to convert comes after the minimum
     field width and optional precision.

  5. Precision (optional), given as a `.' (dot) followed by the
     precision.  If specified as `*' (an asterisk), the actual width is
     read from the next element of the tuple in VALUES, and the value
     to convert comes after the precision.

  6. Length modifier (optional).

  7. Conversion type.

If the right argument is a dictionary (or any kind of mapping), then
the formats in the string _must_ have a parenthesized key into that
dictionary inserted immediately after the `%' character, and each
format formats the corresponding entry from the mapping.  For example:

     >>> count = 2
     >>> language = 'Python'
     >>> print '%(language)s has %(count)03d quote types.' % vars()
     Python has 002 quote types.

In this case no `*' specifiers may occur in a format (since they
require a sequential parameter list).

The conversion flag characters are:

Flag                                 Meaning
------                               -----
#                                    The value conversion will use the
                                     "alternate form" (where defined
                                     below).
0                                    The conversion will be zero padded.
-                                    The converted value is left
                                     adjusted (overrides `-').
{~}                                  (a space) A blank should be left
                                     before a positive number (or empty
                                     string) produced by a signed
                                     conversion.
+                                    A sign character (`+' or `-') will
                                     precede the conversion (overrides a
                                     "space" flag).

The length modifier may be `h', `l', and `L' may be present, but are
ignored as they are not necessary for Python.

The conversion types are:

Conversion                           Meaning
------                               -----
d                                    Signed integer decimal.
i                                    Signed integer decimal.
o                                    Unsigned octal.
u                                    Unsigned decimal.
x                                    Unsigned hexidecimal (lowercase).
X                                    Unsigned hexidecimal (uppercase).
e                                    Floating point exponential format
                                     (lowercase).
E                                    Floating point exponential format
                                     (uppercase).
f                                    Floating point decimal format.
F                                    Floating point decimal format.
g                                    Same as `e' if exponent is greater
                                     than -4 or less than precision, `f'
                                     otherwise.
G                                    Same as `E' if exponent is greater
                                     than -4 or less than precision, `F'
                                     otherwise.
c                                    Single character (accepts integer
                                     or single character string).
r                                    String (converts any python object
                                     using `repr()').
s                                    String (converts any python object
                                     using `str()').
%                                    No argument is converted, results
                                     in a `%' character in the result.
                                     (The complete specification is
                                     `%%'.)

Since Python strings have an explicit length, `%s' conversions do not
assume that `'\0'' is the end of the string.

For safety reasons, floating point precisions are clipped to 50; `%f'
conversions for numbers whose absolute value is over 1e25 are replaced
by `%g' conversions.(2)  All other errors raise exceptions.

Additional string operations are defined in standard module `string'
and in built-in module `re'.

---------- Footnotes ----------

(1) A tuple object in this case should be a singleton.

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


automatically generated by info2www version 1.2.2.9