From d2191e04a490b8bc43917a18604dde6a626aa7aa Mon Sep 17 00:00:00 2001 From: Ezio Melotti Date: Fri, 2 Jul 2010 23:18:51 +0000 Subject: [PATCH] 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. ........ --- Doc/library/string.rst | 179 +++++++++++++++++++++++++++++++++++------ 1 file changed, 155 insertions(+), 24 deletions(-) diff --git a/Doc/library/string.rst b/Doc/library/string.rst index 6b8b2bc216c..6d1e0b3ea5d 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