mirrors/cpython
1
0
Fork 0
mirror of https://github.com/python/cpython.git synced 2025-11-28 14:11:15 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 8

#6813: better documentation for numberless string formats.

Browse source
This commit is contained in:
Georg Brandl 2009-09-01 07:40:54 +00:00
parent 90161375c6
commit 254c17c758
2 changed files with 14 additions and 5 deletions
Download patch file Download diff file Expand all files Collapse all files

6
Doc/library/string.rst
View file

@ -220,7 +220,7 @@ literal text, it can be escaped by doubling: ``{{`` and ``}}``.
The grammar for a replacement field is as follows:
.. productionlist:: sf
replacement_field: "{" `field_name` ["!" `conversion`] [":" `format_spec`] "}"
replacement_field: "{" [`field_name`] ["!" `conversion`] [":" `format_spec`] "}"
field_name: arg_name ("." `attribute_name` | "[" `element_index` "]")*
arg_name: (`identifier` | `integer`)?
attribute_name: `identifier`
@ -228,7 +228,7 @@ The grammar for a replacement field is as follows:
conversion: "r" | "s"
format_spec: <described in the next section>
In less formal terms, the replacement field starts with a *field_name* that specifies
In less formal terms, the replacement field can start with a *field_name* that specifies
the object whose value is to be formatted and inserted
into the output instead of the replacement field.
The *field_name* is optionally followed by a *conversion* field, which is
@ -249,7 +249,7 @@ Some simple format string examples::
"First, thou shalt count to {0}" # References first positional argument
"Bring me a {}" # Implicitly references the first positional argument
"From {} to {}" # Same as "From {0] to {1}"
"From {} to {}" # Same as "From {0} to {1}"
"My quest is {name}" # References keyword argument 'name'
"Weight in tons {0.weight}" # 'weight' attribute of first positional arg
"Units destroyed: {players[0]}" # First element of keyword argument 'players'.

13
Doc/tutorial/inputoutput.rst
View file

@ -123,11 +123,11 @@ with zeros. It understands about plus and minus signs::
Basic usage of the :meth:`str.format` method looks like this::
>>> print 'We are the {0} who say "{1}!"'.format('knights', 'Ni')
>>> print 'We are the {} who say "{}!"'.format('knights', 'Ni')
We are the knights who say "Ni!"
The brackets and characters within them (called format fields) are replaced with
the objects passed into the :meth:`~str.format` method. The number in the
the objects passed into the :meth:`~str.format` method. A number in the
brackets refers to the position of the object passed into the
:meth:`~str.format` method. ::
@ -149,6 +149,15 @@ Positional and keyword arguments can be arbitrarily combined::
... other='Georg')
The story of Bill, Manfred, and Georg.
``'!s'`` (apply :func:`str`) and ``'!r'`` (apply :func:`repr`) can be used to
convert the value before it is formatted. ::
>>> import math
>>> print 'The value of PI is approximately {}.'.format(math.pi)
The value of PI is approximately 3.14159265359.
>>> print 'The value of PI is approximately {!r}.'.format(math.pi)
The value of PI is approximately 3.141592653589793.
An optional ``':'`` and format specifier can follow the field name. This allows
greater control over how the value is formatted. The following example
truncates Pi to three places after the decimal.