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: The grammar for a replacement field is as follows:
.. productionlist:: sf .. productionlist:: sf
replacement_field: "{" `field_name` ["!" `conversion`] [":" `format_spec`] "}" replacement_field: "{" [`field_name`] ["!" `conversion`] [":" `format_spec`] "}"
field_name: arg_name ("." `attribute_name` | "[" `element_index` "]")* field_name: arg_name ("." `attribute_name` | "[" `element_index` "]")*
arg_name: (`identifier` | `integer`)? arg_name: (`identifier` | `integer`)?
attribute_name: `identifier` attribute_name: `identifier`
@ -228,7 +228,7 @@ The grammar for a replacement field is as follows:
conversion: "r" | "s" conversion: "r" | "s"
format_spec: <described in the next section> 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 the object whose value is to be formatted and inserted
into the output instead of the replacement field. into the output instead of the replacement field.
The *field_name* is optionally followed by a *conversion* field, which is 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 "First, thou shalt count to {0}" # References first positional argument
"Bring me a {}" # Implicitly references the 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' "My quest is {name}" # References keyword argument 'name'
"Weight in tons {0.weight}" # 'weight' attribute of first positional arg "Weight in tons {0.weight}" # 'weight' attribute of first positional arg
"Units destroyed: {players[0]}" # First element of keyword argument 'players'. "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:: 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!" We are the knights who say "Ni!"
The brackets and characters within them (called format fields) are replaced with 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 brackets refers to the position of the object passed into the
:meth:`~str.format` method. :: :meth:`~str.format` method. ::
@ -149,6 +149,15 @@ Positional and keyword arguments can be arbitrarily combined::
... other='Georg') ... other='Georg')
The story of Bill, Manfred, and 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 An optional ``':'`` and format specifier can follow the field name. This allows
greater control over how the value is formatted. The following example greater control over how the value is formatted. The following example
truncates Pi to three places after the decimal. truncates Pi to three places after the decimal.