mirror of https://github.com/python/cpython
#9139: Add examples for str.format().
This commit is contained in:
Ezio Melotti
parent
68f59415b6
commit
e11690ab34
|
|
@ -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
|
||||
----------------
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue