[Python-checkins] r82460 - in python/branches/release26-maint: Doc/library/string.rst
ezio.melotti
python-checkins at python.org
Sat Jul 3 00:58:12 CEST 2010
Author: ezio.melotti
Date: Sat Jul 3 00:58:12 2010
New Revision: 82460
Log:
Merged revisions 82457,82459 via svnmerge from
svn+ssh://pythondev@svn.python.org/python/trunk
........
r82457 | ezio.melotti | 2010-07-03 01:17:29 +0300 (Sat, 03 Jul 2010) | 1 line
#9139: Add examples for str.format().
........
r82459 | ezio.melotti | 2010-07-03 01:50:39 +0300 (Sat, 03 Jul 2010) | 1 line
#9139: the thousands separator is new in 2.7. Also add a missing variable in the example.
........
Modified:
python/branches/release26-maint/ (props changed)
python/branches/release26-maint/Doc/library/string.rst
Modified: python/branches/release26-maint/Doc/library/string.rst
==============================================================================
--- python/branches/release26-maint/Doc/library/string.rst (original)
+++ python/branches/release26-maint/Doc/library/string.rst Sat Jul 3 00:58:12 2010
@@ -201,7 +201,7 @@
.. method:: convert_field(value, conversion)
Converts the value (returned by :meth:`get_field`) given a conversion type
- (as in the tuple returned by the :meth:`parse` method.) The default
+ (as in the tuple returned by the :meth:`parse` method). The default
version understands 'r' (repr) and 's' (str) conversion types.
@@ -236,6 +236,8 @@
preceded by an exclamation point ``'!'``, and a *format_spec*, which is preceded
by a colon ``':'``.
+See also the :ref:`formatspec` section.
+
The *field_name* itself begins with either a number or a keyword. If it's a
number, it refers to a positional argument, and if it's a keyword it refers to a
named keyword argument. This can be followed by any number of index or
@@ -279,26 +281,7 @@
format_spec are substituted before the *format_spec* string is interpreted.
This allows the formatting of a value to be dynamically specified.
-For example, suppose you wanted to have a replacement field whose field width is
-determined by another variable::
-
- "A man with two {0:{1}}".format("noses", 10)
-
-This would first evaluate the inner replacement field, making the format string
-effectively::
-
- "A man with two {0:10}"
-
-Then the outer replacement field would be evaluated, producing::
-
- "noses "
-
-Which is substituted into the string, yielding::
-
- "A man with two noses "
-
-(The extra space is because we specified a field width of 10, and because left
-alignment is the default for strings.)
+See the :ref:`formatexamples` section for some examples.
.. _formatspec:
@@ -308,7 +291,7 @@
"Format specifications" are used within replacement fields contained within a
format string to define how individual values are presented (see
-:ref:`formatstrings`.) They can also be passed directly to the built-in
+:ref:`formatstrings`). They can also be passed directly to the built-in
:func:`format` function. Each formattable type may define how the format
specification is to be interpreted.
@@ -342,7 +325,7 @@
| Option | Meaning |
+=========+==========================================================+
| ``'<'`` | Forces the field to be left-aligned within the available |
- | | space (This is the default.) |
+ | | space (this is the default). |
+---------+----------------------------------------------------------+
| ``'>'`` | Forces the field to be right-aligned within the |
| | available space. |
@@ -494,6 +477,142 @@
+---------+----------------------------------------------------------+
+
+.. _formatexamples:
+
+Format examples
+^^^^^^^^^^^^^^^
+
+This section contains examples of the new format syntax and comparison with
+the old ``%``-formatting.
+
+In most of the cases the syntax is similar to the old ``%``-formatting, with the
+addition of the ``{}`` and with ``:`` used instead of ``%``.
+For example, ``'%03.2f'`` can be translated to ``'{0:03.2f}'``.
+
+The new format syntax also supports new and different options, shown in the
+follow examples.
+
+Accessing arguments by position::
+
+ >>> '{0}, {1}, {2}'.format('a', 'b', 'c')
+ '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'
+
+Accessing arguments by name::
+
+ >>> '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'
+
+Accessing arguments' attributes::
+
+ >>> 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.'
+ >>> class Point(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)'
+
+
+Accessing arguments' items::
+
+ >>> coord = (3, 5)
+ >>> 'X: {0[0]}; Y: {0[1]}'.format(coord)
+ 'X: 3; Y: 5'
+
+Replacing ``%s`` and ``%r``::
+
+ >>> "repr() shows quotes: {0!r}; str() doesn't: {1!s}".format('test1', 'test2')
+ "repr() shows quotes: 'test1'; str() doesn't: test2"
+
+Aligning the text and specifying a width::
+
+ >>> '{0:<30}'.format('left aligned')
+ 'left aligned '
+ >>> '{0:>30}'.format('right aligned')
+ ' right aligned'
+ >>> '{0:^30}'.format('centered')
+ ' centered '
+ >>> '{0:*^30}'.format('centered') # use '*' as a fill char
+ '***********centered***********'
+
+Replacing ``%+f``, ``%-f``, and ``% f`` and specifying a sign::
+
+ >>> '{0:+f}; {0:+f}'.format(3.14, -3.14) # show it always
+ '+3.140000; -3.140000'
+ >>> '{0: f}; {0: f}'.format(3.14, -3.14) # show a space for positive numbers
+ ' 3.140000; -3.140000'
+ >>> '{0:-f}; {0:-f}'.format(3.14, -3.14) # show only the minus -- same as '{0:f}; {0:f}'
+ '3.140000; -3.140000'
+
+Replacing ``%x`` and ``%o`` and converting the value to different bases::
+
+ >>> # 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'
+
+Expressing a percentage::
+
+ >>> points = 19.5
+ >>> total = 22
+ >>> 'Correct answers: {0:.2%}.'.format(points/total)
+ 'Correct answers: 88.64%'
+
+Using type-specific formatting::
+
+ >>> import datetime
+ >>> d = datetime.datetime(2010, 7, 4, 12, 15, 58)
+ >>> '{0:%Y-%m-%d %H:%M:%S}'.format(d)
+ '2010-07-04 12:15:58'
+
+Nesting arguments and more complex examples::
+
+ >>> for align, text in zip('<^>', ['left', 'center', 'right']):
+ ... '{0:{align}{fill}16}'.format(text, fill=align, align=align)
+ ...
+ 'left<<<<<<<<<<<<'
+ '^^^^^center^^^^^'
+ '>>>>>>>>>>>right'
+ >>>
+ >>> octets = [192, 168, 0, 1]
+ >>> '{0:02X}{1:02X}{2:02X}{3:02X}'.format(*octets)
+ 'C0A80001'
+ >>> int(_, 16)
+ 3232235521
+ >>>
+ >>> width = 5
+ >>> for num in range(5,12):
+ ... for base in '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
+
+
+
Template strings
----------------
More information about the Python-checkins
mailing list