From e11690ab342b8cae920b71c83d32666eea692326 Mon Sep 17 00:00:00 2001 From: Ezio Melotti Date: Fri, 2 Jul 2010 22:17:29 +0000 Subject: [PATCH] #9139: Add examples for str.format(). --- Doc/library/string.rst | 175 +++++++++++++++++++++++++++++++++++------ 1 file changed, 152 insertions(+), 23 deletions(-) diff --git a/Doc/library/string.rst b/Doc/library/string.rst index 74129761055..cd56737ed12 100644 --- a/Doc/library/string.rst +++ b/Doc/library/string.rst @@ -201,7 +201,7 @@ string formatting behaviors using the same implementation as the built-in .. 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. @@ -238,6 +238,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 @@ -248,6 +250,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:: 2.7 + 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 @@ -286,26 +292,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: @@ -315,7 +302,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. @@ -349,7 +336,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. | @@ -505,6 +492,148 @@ 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') # 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' + +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:: + + >>> ('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: {!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.5 + >>> total = 22 + >>> 'Correct answers: {:.2%}.'.format(points/total) + 'Correct answers: 88.64%' + +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), + ... 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 ----------------