From 254c17c7580404f2b197336e2a6b8a10f5419343 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Tue, 1 Sep 2009 07:40:54 +0000 Subject: #6813: better documentation for numberless string formats. --- Doc/library/string.rst | 6 +++--- Doc/tutorial/inputoutput.rst | 13 +++++++++++-- 2 files changed, 14 insertions(+), 5 deletions(-) diff --git a/Doc/library/string.rst b/Doc/library/string.rst index 0b9b1fb..52aa41c 100644 --- a/Doc/library/string.rst +++ b/Doc/library/string.rst @@ -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: -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'. diff --git a/Doc/tutorial/inputoutput.rst b/Doc/tutorial/inputoutput.rst index 9352f40..9efbca5 100644 --- a/Doc/tutorial/inputoutput.rst +++ b/Doc/tutorial/inputoutput.rst @@ -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. -- cgit v0.12