Merged revisions 82455,82457,82459 via svnmerge from

svn+ssh://pythondev@svn.python.org/python/trunk

........
  r82455 | eric.smith | 2010-07-03 00:44:16 +0300 (Sat, 03 Jul 2010) | 1 line

  Moved period outside paren, where it belongs.
........
  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.
........

1 files changed, 155 insertions, 24 deletions

diff --git a/Doc/library/string.rst b/Doc/library/string.rst
index 6b8b2bc..6d1e0b3 100644
--- a/Doc/library/string.rst
+++ b/Doc/library/string.rst
@@ -174,7 +174,7 @@ implementation as the built-in :meth:`format` method.
    .. 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.
 
 
@@ -185,7 +185,7 @@ Format String Syntax
 
 The :meth:`str.format` method and the :class:`Formatter` class share the same
 syntax for format strings (although in the case of :class:`Formatter`,
-subclasses can define their own format string syntax.)
+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 is
@@ -211,6 +211,8 @@ The *field_name* is optionally followed by a  *conversion* field, which is
 preceded by an exclamation point ``'!'``, and a *format_spec*, which is preceded
 by a colon ``':'``.  These specify a non-default format for the replacement value.
 
+See also the :ref:`formatspec` section.
+
 The *field_name* itself begins with an *arg_name* that is either 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.  If the numerical arg_names in a format string
@@ -221,6 +223,10 @@ attribute expressions. An expression of the form ``'.name'`` selects the named
 attribute using :func:`getattr`, while an expression of the form ``'[index]'``
 does an index lookup using :func:`__getitem__`.
 
+.. versionchanged:: 3.1
+   The positional argument specifiers can be omitted, so ``'{} {}'`` is
+   equivalent to ``'{0} {1}'``.
+
 Some simple format string examples::
 
    "First, thou shalt count to {0}" # References first positional argument
@@ -261,26 +267,7 @@ and format specifications are not allowed.  The replacement fields within the
 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:
@@ -290,7 +277,7 @@ Format Specification Mini-Language
 
 "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.
 
@@ -324,7 +311,7 @@ The meaning of the various alignment options is as follows:
    | 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.                                         |
@@ -366,6 +353,9 @@ The ``','`` option signals the use of a comma for a thousands separator.
 For a locale aware separator, use the ``'n'`` integer presentation type
 instead.
 
+.. versionchanged:: 3.1
+   Added the ``','`` option (see also :pep:`378`).
+
 *width* is a decimal integer defining the minimum field width.  If not
 specified, then the field width will be determined by the content.
 
@@ -484,6 +474,147 @@ The available presentation types for floating point and decimal values are:
    +---------+----------------------------------------------------------+
 
 
+.. _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 ``'{: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'
+   >>> '{}, {}, {}'.format('a', 'b', 'c')  # 3.1+ 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'
+
+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:
+   ...     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: {!r}; str() doesn't: {!s}".format('test1', 'test2')
+   "repr() shows quotes: 'test1'; str() doesn't: test2"
+
+Aligning the text and specifying a width::
+
+   >>> '{:<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***********'
+
+Replacing ``%+f``, ``%-f``, and ``% f`` and specifying a sign::
+
+   >>> '{:+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'
+
+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'
+
+Using the comma as a thousands separator::
+
+   >>> '{:,}'.format(1234567890)
+   '1,234,567,890'
+
+Expressing a percentage::
+
+   >>> points = 19
+   >>> total = 22
+   >>> 'Correct answers: {:.2%}.'.format(points/total)
+   'Correct answers: 86.36%'
+
+Using type-specific formatting::
+
+   >>> import datetime
+   >>> d = datetime.datetime(2010, 7, 4, 12, 15, 58)
+   >>> '{:%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]
+   >>> '{:02X}{:02X}{:02X}{: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), end=' ')
+   ...     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:
 
 Template strings