summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorEric Smith <eric@trueblade.com>2009-04-22 00:47:00 (GMT)
committerEric Smith <eric@trueblade.com>2009-04-22 00:47:00 (GMT)
commit4c074382bd2dc4857a8c9afcac7e5322dc6c77e5 (patch)
tree6bb3d66247645c2a0c2a64d798fa27aacdd00811
parente56101136c53b18b9aeba0fc0f067655ce3e5c66 (diff)
downloadcpython-4c074382bd2dc4857a8c9afcac7e5322dc6c77e5.zip
cpython-4c074382bd2dc4857a8c9afcac7e5322dc6c77e5.tar.gz
cpython-4c074382bd2dc4857a8c9afcac7e5322dc6c77e5.tar.bz2
Documentation for issue 5237, auto-numbered format fields. Contributed by Terry J. Reedy.
-rw-r--r--Doc/ACKS.txt1
-rw-r--r--Doc/library/string.rst24
2 files changed, 16 insertions, 9 deletions
diff --git a/Doc/ACKS.txt b/Doc/ACKS.txt
index 849886a..e9ea0b3 100644
--- a/Doc/ACKS.txt
+++ b/Doc/ACKS.txt
@@ -156,6 +156,7 @@ docs@python.org), and we'll be glad to correct the problem.
* Paul Prescod
* Eric S. Raymond
* Edward K. Ream
+ * Terry J. Reedy
* Sean Reifschneider
* Bernhard Reiter
* Armin Rigo
diff --git a/Doc/library/string.rst b/Doc/library/string.rst
index 40aa07c..6ca0873 100644
--- a/Doc/library/string.rst
+++ b/Doc/library/string.rst
@@ -221,21 +221,26 @@ The grammar for a replacement field is as follows:
.. productionlist:: sf
replacement_field: "{" `field_name` ["!" `conversion`] [":" `format_spec`] "}"
- field_name: (`identifier` | `integer`) ("." `attribute_name` | "[" `element_index` "]")*
+ field_name: arg_name ("." `attribute_name` | "[" `element_index` "]")*
+ arg_name: (`identifier` | `integer`)?
attribute_name: `identifier`
element_index: `integer`
conversion: "r" | "s"
format_spec: <described in the next section>
-In less formal terms, the replacement field starts with a *field_name*, which
-can either be a number (for a positional argument), or an identifier (for
-keyword arguments). Following this is an optional *conversion* field, which is
+In less formal terms, the replacement field starts 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
preceded by an exclamation point ``'!'``, and a *format_spec*, which is preceded
-by a colon ``':'``.
-
-The *field_name* itself begins with 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. This can be followed by any number of index or
+by a colon ``':'``. These specify a non-default format for the replacement value.
+
+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
+are 0, 1, 2, ... in sequence, they can all be omitted (not just some)
+and the numbers 0, 1, 2, ... will be automatically inserted in that order.
+The *arg_name* can be followed by any number of index or
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__`.
@@ -244,6 +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}"
"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'.