Mercurial > cpython-lru_cache-weakref

annotate Doc/library/string.rst @ 79691:05c8928362ee

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Merge __next__ method link fixes with 3.3.
author Ezio Melotti <ezio.melotti@gmail.com>
date Fri, 12 Oct 2012 13:46:37 +0300
parents 06deefec71e3
children ae19d86b71c8
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1 :mod:`string` --- Common string operations
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2 ==========================================
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
3
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
4 .. module:: string
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
5 :synopsis: Common string operations.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
6
71926
3bbb1a3eca01 Add a few missing source links from 2.7 and harmonize lib docs headers
Éric Araujo <merwok@netwok.org>
parents: 71761
diff changeset
7 **Source code:** :source:`Lib/string.py`
3bbb1a3eca01 Add a few missing source links from 2.7 and harmonize lib docs headers
Éric Araujo <merwok@netwok.org>
parents: 71761
diff changeset
8
3bbb1a3eca01 Add a few missing source links from 2.7 and harmonize lib docs headers
Éric Araujo <merwok@netwok.org>
parents: 71761
diff changeset
9 --------------
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
10
67490
5f77907b0041 Merged revisions 87789-87790 via svnmerge from
Georg Brandl <georg@python.org>
parents: 66475
diff changeset
11 .. seealso::
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
12
79681
06deefec71e3 Fix and add more links.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 78658
diff changeset
13 :ref:`textseq`
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
14
67490
5f77907b0041 Merged revisions 87789-87790 via svnmerge from
Georg Brandl <georg@python.org>
parents: 66475
diff changeset
15 :ref:`string-methods`
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
16
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
17 String constants
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
18 ----------------
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
19
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
20 The constants defined in this module are:
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
21
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
22
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
23 .. data:: ascii_letters
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
24
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
25 The concatenation of the :const:`ascii_lowercase` and :const:`ascii_uppercase`
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
26 constants described below. This value is not locale-dependent.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
27
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
28
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
29 .. data:: ascii_lowercase
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
30
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
31 The lowercase letters ``'abcdefghijklmnopqrstuvwxyz'``. This value is not
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
32 locale-dependent and will not change.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
33
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
34
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
35 .. data:: ascii_uppercase
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
36
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
37 The uppercase letters ``'ABCDEFGHIJKLMNOPQRSTUVWXYZ'``. This value is not
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
38 locale-dependent and will not change.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
39
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
40
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
41 .. data:: digits
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
42
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
43 The string ``'0123456789'``.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
44
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
45
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
46 .. data:: hexdigits
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
47
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
48 The string ``'0123456789abcdefABCDEF'``.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
49
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
50
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
51 .. data:: octdigits
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
52
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
53 The string ``'01234567'``.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
54
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
55
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
56 .. data:: punctuation
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
57
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
58 String of ASCII characters which are considered punctuation characters
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
59 in the ``C`` locale.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
60
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
61
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
62 .. data:: printable
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
63
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
64 String of ASCII characters which are considered printable. This is a
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
65 combination of :const:`digits`, :const:`ascii_letters`, :const:`punctuation`,
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
66 and :const:`whitespace`.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
67
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
68
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
69 .. data:: whitespace
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
70
49804
8f0a175f04be #4361: fix string.py docstring, clarify that only ASCII characters are in its constants.
Georg Brandl <georg@python.org>
parents: 49698
diff changeset
71 A string containing all ASCII characters that are considered whitespace.
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
72 This includes the characters space, tab, linefeed, return, formfeed, and
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
73 vertical tab.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
74
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
75
43138
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
76 .. _string-formatting:
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
77
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
78 String Formatting
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
79 -----------------
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
80
47279
c9d717b5b7a2 remove version note
Benjamin Peterson <benjamin@python.org>
parents: 46938
diff changeset
81 The built-in string class provides the ability to do complex variable
c9d717b5b7a2 remove version note
Benjamin Peterson <benjamin@python.org>
parents: 46938
diff changeset
82 substitutions and value formatting via the :func:`format` method described in
c9d717b5b7a2 remove version note
Benjamin Peterson <benjamin@python.org>
parents: 46938
diff changeset
83 :pep:`3101`. The :class:`Formatter` class in the :mod:`string` module allows
c9d717b5b7a2 remove version note
Benjamin Peterson <benjamin@python.org>
parents: 46938
diff changeset
84 you to create and customize your own string formatting behaviors using the same
c9d717b5b7a2 remove version note
Benjamin Peterson <benjamin@python.org>
parents: 46938
diff changeset
85 implementation as the built-in :meth:`format` method.
43138
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
86
58026
e078579984a4 Merged revisions 77167 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 57454
diff changeset
87
43138
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
88 .. class:: Formatter
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
89
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
90 The :class:`Formatter` class has the following public methods:
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
91
68009
92629ccaae76 Merged revisions 87627,87638,87739,87760,87771,87787,87984,87986,88108,88115,88144,88165,88329,88364-88365,88369-88370,88423-88424 via svnmerge from
Georg Brandl <georg@python.org>
parents: 67490
diff changeset
92 .. method:: format(format_string, *args, **kwargs)
43138
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
93
78658
24b449a77e88 #13579: teach string.Formatter about 'a'.
R David Murray <rdmurray@bitdance.com>
parents: 78622
diff changeset
94 :meth:`format` is the primary API method. It takes a format string and
24b449a77e88 #13579: teach string.Formatter about 'a'.
R David Murray <rdmurray@bitdance.com>
parents: 78622
diff changeset
95 an arbitrary set of positional and keyword arguments.
43138
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
96 :meth:`format` is just a wrapper that calls :meth:`vformat`.
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
97
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
98 .. method:: vformat(format_string, args, kwargs)
50563
93cf3a6ead63 Merged revisions 68226 via svnmerge from
Georg Brandl <georg@python.org>
parents: 49804
diff changeset
99
43138
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
100 This function does the actual work of formatting. It is exposed as a
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
101 separate function for cases where you want to pass in a predefined
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
102 dictionary of arguments, rather than unpacking and repacking the
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
103 dictionary as individual arguments using the ``*args`` and ``**kwds``
78658
24b449a77e88 #13579: teach string.Formatter about 'a'.
R David Murray <rdmurray@bitdance.com>
parents: 78622
diff changeset
104 syntax. :meth:`vformat` does the work of breaking up the format string
24b449a77e88 #13579: teach string.Formatter about 'a'.
R David Murray <rdmurray@bitdance.com>
parents: 78622
diff changeset
105 into character data and replacement fields. It calls the various
43138
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
106 methods described below.
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
107
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
108 In addition, the :class:`Formatter` defines a number of methods that are
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
109 intended to be replaced by subclasses:
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
110
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
111 .. method:: parse(format_string)
50563
93cf3a6ead63 Merged revisions 68226 via svnmerge from
Georg Brandl <georg@python.org>
parents: 49804
diff changeset
112
43138
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
113 Loop over the format_string and return an iterable of tuples
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
114 (*literal_text*, *field_name*, *format_spec*, *conversion*). This is used
66475
9bead909d8ef Merged revisions 85820,85823,85825,85840,85843-85845,85849-85851,85855,85867,85875,85907-85908,85911,85914 via svnmerge from
Georg Brandl <georg@python.org>
parents: 65235
diff changeset
115 by :meth:`vformat` to break the string into either literal text, or
43138
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
116 replacement fields.
50563
93cf3a6ead63 Merged revisions 68226 via svnmerge from
Georg Brandl <georg@python.org>
parents: 49804
diff changeset
117
43138
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
118 The values in the tuple conceptually represent a span of literal text
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
119 followed by a single replacement field. If there is no literal text
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
120 (which can happen if two replacement fields occur consecutively), then
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
121 *literal_text* will be a zero-length string. If there is no replacement
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
122 field, then the values of *field_name*, *format_spec* and *conversion*
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
123 will be ``None``.
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
124
43200
463b341a9d63 Removed used_args param from string.Formatter.get_field. It was left in by mistake from an earlier edit.
Eric Smith <eric@trueblade.com>
parents: 43176
diff changeset
125 .. method:: get_field(field_name, args, kwargs)
43138
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
126
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
127 Given *field_name* as returned by :meth:`parse` (see above), convert it to
43144
5c30f15a6b87 string.maketrans() now produces translation tables for bytes.translate() -- wrong module?
Georg Brandl <georg@python.org>
parents: 43138
diff changeset
128 an object to be formatted. Returns a tuple (obj, used_key). The default
5c30f15a6b87 string.maketrans() now produces translation tables for bytes.translate() -- wrong module?
Georg Brandl <georg@python.org>
parents: 43138
diff changeset
129 version takes strings of the form defined in :pep:`3101`, such as
5c30f15a6b87 string.maketrans() now produces translation tables for bytes.translate() -- wrong module?
Georg Brandl <georg@python.org>
parents: 43138
diff changeset
130 "0[name]" or "label.title". *args* and *kwargs* are as passed in to
5c30f15a6b87 string.maketrans() now produces translation tables for bytes.translate() -- wrong module?
Georg Brandl <georg@python.org>
parents: 43138
diff changeset
131 :meth:`vformat`. The return value *used_key* has the same meaning as the
5c30f15a6b87 string.maketrans() now produces translation tables for bytes.translate() -- wrong module?
Georg Brandl <georg@python.org>
parents: 43138
diff changeset
132 *key* parameter to :meth:`get_value`.
43138
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
133
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
134 .. method:: get_value(key, args, kwargs)
50563
93cf3a6ead63 Merged revisions 68226 via svnmerge from
Georg Brandl <georg@python.org>
parents: 49804
diff changeset
135
43138
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
136 Retrieve a given field value. The *key* argument will be either an
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
137 integer or a string. If it is an integer, it represents the index of the
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
138 positional argument in *args*; if it is a string, then it represents a
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
139 named argument in *kwargs*.
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
140
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
141 The *args* parameter is set to the list of positional arguments to
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
142 :meth:`vformat`, and the *kwargs* parameter is set to the dictionary of
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
143 keyword arguments.
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
144
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
145 For compound field names, these functions are only called for the first
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
146 component of the field name; Subsequent components are handled through
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
147 normal attribute and indexing operations.
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
148
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
149 So for example, the field expression '0.name' would cause
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
150 :meth:`get_value` to be called with a *key* argument of 0. The ``name``
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
151 attribute will be looked up after :meth:`get_value` returns by calling the
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
152 built-in :func:`getattr` function.
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
153
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
154 If the index or keyword refers to an item that does not exist, then an
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
155 :exc:`IndexError` or :exc:`KeyError` should be raised.
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
156
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
157 .. method:: check_unused_args(used_args, args, kwargs)
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
158
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
159 Implement checking for unused arguments if desired. The arguments to this
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
160 function is the set of all argument keys that were actually referred to in
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
161 the format string (integers for positional arguments, and strings for
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
162 named arguments), and a reference to the *args* and *kwargs* that was
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
163 passed to vformat. The set of unused args can be calculated from these
65116
90e1735df4d9 Merged revisions 83561,83563,83565-83566,83569,83571,83574-83575,83580,83584,83599,83612,83659,83977,84015-84018,84020,84141 via svnmerge from
Georg Brandl <georg@python.org>
parents: 63126
diff changeset
164 parameters. :meth:`check_unused_args` is assumed to raise an exception if
43138
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
165 the check fails.
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
166
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
167 .. method:: format_field(value, format_spec)
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
168
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
169 :meth:`format_field` simply calls the global :func:`format` built-in. The
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
170 method is provided so that subclasses can override it.
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
171
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
172 .. method:: convert_field(value, conversion)
50563
93cf3a6ead63 Merged revisions 68226 via svnmerge from
Georg Brandl <georg@python.org>
parents: 49804
diff changeset
173
43138
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
174 Converts the value (returned by :meth:`get_field`) given a conversion type
62704
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
175 (as in the tuple returned by the :meth:`parse` method). The default
78658
24b449a77e88 #13579: teach string.Formatter about 'a'.
R David Murray <rdmurray@bitdance.com>
parents: 78622
diff changeset
176 version understands 's' (str), 'r' (repr) and 'a' (ascii) conversion
24b449a77e88 #13579: teach string.Formatter about 'a'.
R David Murray <rdmurray@bitdance.com>
parents: 78622
diff changeset
177 types.
43138
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
178
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
179
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
180 .. _formatstrings:
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
181
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
182 Format String Syntax
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
183 --------------------
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
184
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
185 The :meth:`str.format` method and the :class:`Formatter` class share the same
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
186 syntax for format strings (although in the case of :class:`Formatter`,
62704
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
187 subclasses can define their own format string syntax).
43138
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
188
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
189 Format strings contain "replacement fields" surrounded by curly braces ``{}``.
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
190 Anything that is not contained in braces is considered literal text, which is
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
191 copied unchanged to the output. If you need to include a brace character in the
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
192 literal text, it can be escaped by doubling: ``{{`` and ``}}``.
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
193
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
194 The grammar for a replacement field is as follows:
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
195
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
196 .. productionlist:: sf
55797
afbb2b2ff6f7 Merged revisions 74613,74615,74619-74620,74622 via svnmerge from
Georg Brandl <georg@python.org>
parents: 55580
diff changeset
197 replacement_field: "{" [`field_name`] ["!" `conversion`] [":" `format_spec`] "}"
53307
414ba8efc804 Merged revisions 71788 via svnmerge from
Eric Smith <eric@trueblade.com>
parents: 53094
diff changeset
198 field_name: arg_name ("." `attribute_name` | "[" `element_index` "]")*
62962
365eeab4a350 Merged revisions 82301 via svnmerge from
Georg Brandl <georg@python.org>
parents: 62704
diff changeset
199 arg_name: [`identifier` | `integer`]
43138
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
200 attribute_name: `identifier`
59136
5f04e0cd8171 Merged revisions 78446 via svnmerge from
Eric Smith <eric@trueblade.com>
parents: 59132
diff changeset
201 element_index: `integer` | `index_string`
5f04e0cd8171 Merged revisions 78446 via svnmerge from
Eric Smith <eric@trueblade.com>
parents: 59132
diff changeset
202 index_string: <any source character except "]"> +
49698
211151fdc924 update string formatting grammar
Benjamin Peterson <benjamin@python.org>
parents: 49178
diff changeset
203 conversion: "r" | "s" | "a"
43138
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
204 format_spec: <described in the next section>
50563
93cf3a6ead63 Merged revisions 68226 via svnmerge from
Georg Brandl <georg@python.org>
parents: 49804
diff changeset
205
55797
afbb2b2ff6f7 Merged revisions 74613,74615,74619-74620,74622 via svnmerge from
Georg Brandl <georg@python.org>
parents: 55580
diff changeset
206 In less formal terms, the replacement field can start with a *field_name* that specifies
53307
414ba8efc804 Merged revisions 71788 via svnmerge from
Eric Smith <eric@trueblade.com>
parents: 53094
diff changeset
207 the object whose value is to be formatted and inserted
414ba8efc804 Merged revisions 71788 via svnmerge from
Eric Smith <eric@trueblade.com>
parents: 53094
diff changeset
208 into the output instead of the replacement field.
414ba8efc804 Merged revisions 71788 via svnmerge from
Eric Smith <eric@trueblade.com>
parents: 53094
diff changeset
209 The *field_name* is optionally followed by a *conversion* field, which is
43138
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
210 preceded by an exclamation point ``'!'``, and a *format_spec*, which is preceded
53307
414ba8efc804 Merged revisions 71788 via svnmerge from
Eric Smith <eric@trueblade.com>
parents: 53094
diff changeset
211 by a colon ``':'``. These specify a non-default format for the replacement value.
43138
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
212
62704
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
213 See also the :ref:`formatspec` section.
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
214
72985
e19ccbbe70dd Remove duplication.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 72265
diff changeset
215 The *field_name* itself begins with an *arg_name* that is either a number or a
53307
414ba8efc804 Merged revisions 71788 via svnmerge from
Eric Smith <eric@trueblade.com>
parents: 53094
diff changeset
216 keyword. If it's a number, it refers to a positional argument, and if it's a keyword,
414ba8efc804 Merged revisions 71788 via svnmerge from
Eric Smith <eric@trueblade.com>
parents: 53094
diff changeset
217 it refers to a named keyword argument. If the numerical arg_names in a format string
414ba8efc804 Merged revisions 71788 via svnmerge from
Eric Smith <eric@trueblade.com>
parents: 53094
diff changeset
218 are 0, 1, 2, ... in sequence, they can all be omitted (not just some)
414ba8efc804 Merged revisions 71788 via svnmerge from
Eric Smith <eric@trueblade.com>
parents: 53094
diff changeset
219 and the numbers 0, 1, 2, ... will be automatically inserted in that order.
72248
2c27eb4033f5 Document that format string don’t support arbitrary dictonary keys.
Éric Araujo <merwok@netwok.org>
parents: 71761
diff changeset
220 Because *arg_name* is not quote-delimited, it is not possible to specify arbitrary
2c27eb4033f5 Document that format string don’t support arbitrary dictonary keys.
Éric Araujo <merwok@netwok.org>
parents: 71761
diff changeset
221 dictionary keys (e.g., the strings ``'10'`` or ``':-]'``) within a format string.
53307
414ba8efc804 Merged revisions 71788 via svnmerge from
Eric Smith <eric@trueblade.com>
parents: 53094
diff changeset
222 The *arg_name* can be followed by any number of index or
43138
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
223 attribute expressions. An expression of the form ``'.name'`` selects the named
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
224 attribute using :func:`getattr`, while an expression of the form ``'[index]'``
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
225 does an index lookup using :func:`__getitem__`.
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
226
62704
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
227 .. versionchanged:: 3.1
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
228 The positional argument specifiers can be omitted, so ``'{} {}'`` is
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
229 equivalent to ``'{0} {1}'``.
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
230
43138
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
231 Some simple format string examples::
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
232
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
233 "First, thou shalt count to {0}" # References first positional argument
52432
9e4bb941a1ea Merged revisions 70707 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 52260
diff changeset
234 "Bring me a {}" # Implicitly references the first positional argument
55797
afbb2b2ff6f7 Merged revisions 74613,74615,74619-74620,74622 via svnmerge from
Georg Brandl <georg@python.org>
parents: 55580
diff changeset
235 "From {} to {}" # Same as "From {0} to {1}"
43138
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
236 "My quest is {name}" # References keyword argument 'name'
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
237 "Weight in tons {0.weight}" # 'weight' attribute of first positional arg
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
238 "Units destroyed: {players[0]}" # First element of keyword argument 'players'.
50563
93cf3a6ead63 Merged revisions 68226 via svnmerge from
Georg Brandl <georg@python.org>
parents: 49804
diff changeset
239
43138
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
240 The *conversion* field causes a type coercion before formatting. Normally, the
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
241 job of formatting a value is done by the :meth:`__format__` method of the value
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
242 itself. However, in some cases it is desirable to force a type to be formatted
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
243 as a string, overriding its own definition of formatting. By converting the
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
244 value to a string before calling :meth:`__format__`, the normal formatting logic
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
245 is bypassed.
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
246
47611
da47e7e135ae #2630: Implement PEP 3138.
Georg Brandl <georg@python.org>
parents: 47279
diff changeset
247 Three conversion flags are currently supported: ``'!s'`` which calls :func:`str`
da47e7e135ae #2630: Implement PEP 3138.
Georg Brandl <georg@python.org>
parents: 47279
diff changeset
248 on the value, ``'!r'`` which calls :func:`repr` and ``'!a'`` which calls
da47e7e135ae #2630: Implement PEP 3138.
Georg Brandl <georg@python.org>
parents: 47279
diff changeset
249 :func:`ascii`.
43138
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
250
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
251 Some examples::
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
252
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
253 "Harold's a clever {0!s}" # Calls str() on the argument first
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
254 "Bring out the holy {name!r}" # Calls repr() on the argument first
55797
afbb2b2ff6f7 Merged revisions 74613,74615,74619-74620,74622 via svnmerge from
Georg Brandl <georg@python.org>
parents: 55580
diff changeset
255 "More {!a}" # Calls ascii() on the argument first
43138
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
256
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
257 The *format_spec* field contains a specification of how the value should be
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
258 presented, including such details as field width, alignment, padding, decimal
58918
4f6c1b8277eb Merged revisions 78200 via svnmerge from
Eric Smith <eric@trueblade.com>
parents: 58546
diff changeset
259 precision and so on. Each value type can define its own "formatting
43138
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
260 mini-language" or interpretation of the *format_spec*.
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
261
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
262 Most built-in types support a common formatting mini-language, which is
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
263 described in the next section.
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
264
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
265 A *format_spec* field can also include nested replacement fields within it.
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
266 These nested replacement fields can contain only a field name; conversion flags
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
267 and format specifications are not allowed. The replacement fields within the
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
268 format_spec are substituted before the *format_spec* string is interpreted.
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
269 This allows the formatting of a value to be dynamically specified.
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
270
62704
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
271 See the :ref:`formatexamples` section for some examples.
43138
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
272
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
273
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
274 .. _formatspec:
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
275
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
276 Format Specification Mini-Language
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
277 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
278
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
279 "Format specifications" are used within replacement fields contained within a
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
280 format string to define how individual values are presented (see
62704
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
281 :ref:`formatstrings`). They can also be passed directly to the built-in
43138
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
282 :func:`format` function. Each formattable type may define how the format
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
283 specification is to be interpreted.
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
284
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
285 Most built-in types implement the following options for format specifications,
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
286 although some of the formatting options are only supported by the numeric types.
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
287
59132
2183277cbab1 Merged revisions 78442 via svnmerge from
Eric Smith <eric@trueblade.com>
parents: 58918
diff changeset
288 A general convention is that an empty format string (``""``) produces
2183277cbab1 Merged revisions 78442 via svnmerge from
Eric Smith <eric@trueblade.com>
parents: 58918
diff changeset
289 the same result as if you had called :func:`str` on the value. A
2183277cbab1 Merged revisions 78442 via svnmerge from
Eric Smith <eric@trueblade.com>
parents: 58918
diff changeset
290 non-empty format string typically modifies the result.
43138
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
291
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
292 The general form of a *standard format specifier* is:
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
293
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
294 .. productionlist:: sf
55229
88acc10caa6e Document the thousands separator.
Raymond Hettinger <python@rcn.com>
parents: 53884
diff changeset
295 format_spec: [[`fill`]`align`][`sign`][#][0][`width`][,][.`precision`][`type`]
76887
04e7264e8fcf correctly define what 'fill' could be; thanks to Leland Hulbert from docs@
Sandro Tosi <sandro.tosi@gmail.com>
parents: 74156
diff changeset
296 fill: <a character other than '{' or '}'>
43138
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
297 align: "<" | ">" | "=" | "^"
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
298 sign: "+" | "-" | " "
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
299 width: `integer`
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
300 precision: `integer`
59132
2183277cbab1 Merged revisions 78442 via svnmerge from
Eric Smith <eric@trueblade.com>
parents: 58918
diff changeset
301 type: "b" | "c" | "d" | "e" | "E" | "f" | "F" | "g" | "G" | "n" | "o" | "s" | "x" | "X" | "%"
50563
93cf3a6ead63 Merged revisions 68226 via svnmerge from
Georg Brandl <georg@python.org>
parents: 49804
diff changeset
302
65119
f00440af9413 Merged revisions 84249,84264,84326-84327,84407,84476,84480-84482,84484,84530-84531,84553,84619,84684,84915-84916 via svnmerge from
Georg Brandl <georg@python.org>
parents: 65116
diff changeset
303 The *fill* character can be any character other than '{' or '}'. The presence
f00440af9413 Merged revisions 84249,84264,84326-84327,84407,84476,84480-84482,84484,84530-84531,84553,84619,84684,84915-84916 via svnmerge from
Georg Brandl <georg@python.org>
parents: 65116
diff changeset
304 of a fill character is signaled by the character following it, which must be
f00440af9413 Merged revisions 84249,84264,84326-84327,84407,84476,84480-84482,84484,84530-84531,84553,84619,84684,84915-84916 via svnmerge from
Georg Brandl <georg@python.org>
parents: 65116
diff changeset
305 one of the alignment options. If the second character of *format_spec* is not
f00440af9413 Merged revisions 84249,84264,84326-84327,84407,84476,84480-84482,84484,84530-84531,84553,84619,84684,84915-84916 via svnmerge from
Georg Brandl <georg@python.org>
parents: 65116
diff changeset
306 a valid alignment option, then it is assumed that both the fill character and
f00440af9413 Merged revisions 84249,84264,84326-84327,84407,84476,84480-84482,84484,84530-84531,84553,84619,84684,84915-84916 via svnmerge from
Georg Brandl <georg@python.org>
parents: 65116
diff changeset
307 the alignment option are absent.
43138
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
308
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
309 The meaning of the various alignment options is as follows:
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
310
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
311 +---------+----------------------------------------------------------+
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
312 | Option | Meaning |
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
313 +=========+==========================================================+
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
314 | ``'<'`` | Forces the field to be left-aligned within the available |
68009
92629ccaae76 Merged revisions 87627,87638,87739,87760,87771,87787,87984,87986,88108,88115,88144,88165,88329,88364-88365,88369-88370,88423-88424 via svnmerge from
Georg Brandl <georg@python.org>
parents: 67490
diff changeset
315 | | space (this is the default for most objects). |
43138
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
316 +---------+----------------------------------------------------------+
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
317 | ``'>'`` | Forces the field to be right-aligned within the |
68009
92629ccaae76 Merged revisions 87627,87638,87739,87760,87771,87787,87984,87986,88108,88115,88144,88165,88329,88364-88365,88369-88370,88423-88424 via svnmerge from
Georg Brandl <georg@python.org>
parents: 67490
diff changeset
318 | | available space (this is the default for numbers). |
43138
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
319 +---------+----------------------------------------------------------+
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
320 | ``'='`` | Forces the padding to be placed after the sign (if any) |
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
321 | | but before the digits. This is used for printing fields |
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
322 | | in the form '+000000120'. This alignment option is only |
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
323 | | valid for numeric types. |
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
324 +---------+----------------------------------------------------------+
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
325 | ``'^'`` | Forces the field to be centered within the available |
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
326 | | space. |
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
327 +---------+----------------------------------------------------------+
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
328
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
329 Note that unless a minimum field width is defined, the field width will always
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
330 be the same size as the data to fill it, so that the alignment option has no
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
331 meaning in this case.
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
332
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
333 The *sign* option is only valid for number types, and can be one of the
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
334 following:
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
335
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
336 +---------+----------------------------------------------------------+
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
337 | Option | Meaning |
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
338 +=========+==========================================================+
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
339 | ``'+'`` | indicates that a sign should be used for both |
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
340 | | positive as well as negative numbers. |
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
341 +---------+----------------------------------------------------------+
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
342 | ``'-'`` | indicates that a sign should be used only for negative |
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
343 | | numbers (this is the default behavior). |
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
344 +---------+----------------------------------------------------------+
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
345 | space | indicates that a leading space should be used on |
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
346 | | positive numbers, and a minus sign on negative numbers. |
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
347 +---------+----------------------------------------------------------+
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
348
66444
eded691497b7 Issue #7094: Add alternate ('#') flag to __format__ methods for float, complex and Decimal. Allows greater control over when decimal points appear. Added to make transitioning from %-formatting easier. '#g' still has a problem with Decimal which I'll fix soon.
Eric Smith <eric@trueblade.com>
parents: 66209
diff changeset
349
eded691497b7 Issue #7094: Add alternate ('#') flag to __format__ methods for float, complex and Decimal. Allows greater control over when decimal points appear. Added to make transitioning from %-formatting easier. '#g' still has a problem with Decimal which I'll fix soon.
Eric Smith <eric@trueblade.com>
parents: 66209
diff changeset
350 The ``'#'`` option causes the "alternate form" to be used for the
eded691497b7 Issue #7094: Add alternate ('#') flag to __format__ methods for float, complex and Decimal. Allows greater control over when decimal points appear. Added to make transitioning from %-formatting easier. '#g' still has a problem with Decimal which I'll fix soon.
Eric Smith <eric@trueblade.com>
parents: 66209
diff changeset
351 conversion. The alternate form is defined differently for different
eded691497b7 Issue #7094: Add alternate ('#') flag to __format__ methods for float, complex and Decimal. Allows greater control over when decimal points appear. Added to make transitioning from %-formatting easier. '#g' still has a problem with Decimal which I'll fix soon.
Eric Smith <eric@trueblade.com>
parents: 66209
diff changeset
352 types. This option is only valid for integer, float, complex and
eded691497b7 Issue #7094: Add alternate ('#') flag to __format__ methods for float, complex and Decimal. Allows greater control over when decimal points appear. Added to make transitioning from %-formatting easier. '#g' still has a problem with Decimal which I'll fix soon.
Eric Smith <eric@trueblade.com>
parents: 66209
diff changeset
353 Decimal types. For integers, when binary, octal, or hexadecimal output
eded691497b7 Issue #7094: Add alternate ('#') flag to __format__ methods for float, complex and Decimal. Allows greater control over when decimal points appear. Added to make transitioning from %-formatting easier. '#g' still has a problem with Decimal which I'll fix soon.
Eric Smith <eric@trueblade.com>
parents: 66209
diff changeset
354 is used, this option adds the prefix respective ``'0b'``, ``'0o'``, or
eded691497b7 Issue #7094: Add alternate ('#') flag to __format__ methods for float, complex and Decimal. Allows greater control over when decimal points appear. Added to make transitioning from %-formatting easier. '#g' still has a problem with Decimal which I'll fix soon.
Eric Smith <eric@trueblade.com>
parents: 66209
diff changeset
355 ``'0x'`` to the output value. For floats, complex and Decimal the
eded691497b7 Issue #7094: Add alternate ('#') flag to __format__ methods for float, complex and Decimal. Allows greater control over when decimal points appear. Added to make transitioning from %-formatting easier. '#g' still has a problem with Decimal which I'll fix soon.
Eric Smith <eric@trueblade.com>
parents: 66209
diff changeset
356 alternate form causes the result of the conversion to always contain a
eded691497b7 Issue #7094: Add alternate ('#') flag to __format__ methods for float, complex and Decimal. Allows greater control over when decimal points appear. Added to make transitioning from %-formatting easier. '#g' still has a problem with Decimal which I'll fix soon.
Eric Smith <eric@trueblade.com>
parents: 66209
diff changeset
357 decimal-point character, even if no digits follow it. Normally, a
eded691497b7 Issue #7094: Add alternate ('#') flag to __format__ methods for float, complex and Decimal. Allows greater control over when decimal points appear. Added to make transitioning from %-formatting easier. '#g' still has a problem with Decimal which I'll fix soon.
Eric Smith <eric@trueblade.com>
parents: 66209
diff changeset
358 decimal-point character appears in the result of these conversions
eded691497b7 Issue #7094: Add alternate ('#') flag to __format__ methods for float, complex and Decimal. Allows greater control over when decimal points appear. Added to make transitioning from %-formatting easier. '#g' still has a problem with Decimal which I'll fix soon.
Eric Smith <eric@trueblade.com>
parents: 66209
diff changeset
359 only if a digit follows it. In addition, for ``'g'`` and ``'G'``
eded691497b7 Issue #7094: Add alternate ('#') flag to __format__ methods for float, complex and Decimal. Allows greater control over when decimal points appear. Added to make transitioning from %-formatting easier. '#g' still has a problem with Decimal which I'll fix soon.
Eric Smith <eric@trueblade.com>
parents: 66209
diff changeset
360 conversions, trailing zeros are not removed from the result.
48482
c662e8cffddf Merged revisions 64984 via svnmerge from
Eric Smith <eric@trueblade.com>
parents: 47611
diff changeset
361
55229
88acc10caa6e Document the thousands separator.
Raymond Hettinger <python@rcn.com>
parents: 53884
diff changeset
362 The ``','`` option signals the use of a comma for a thousands separator.
88acc10caa6e Document the thousands separator.
Raymond Hettinger <python@rcn.com>
parents: 53884
diff changeset
363 For a locale aware separator, use the ``'n'`` integer presentation type
88acc10caa6e Document the thousands separator.
Raymond Hettinger <python@rcn.com>
parents: 53884
diff changeset
364 instead.
88acc10caa6e Document the thousands separator.
Raymond Hettinger <python@rcn.com>
parents: 53884
diff changeset
365
62704
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
366 .. versionchanged:: 3.1
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
367 Added the ``','`` option (see also :pep:`378`).
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
368
43138
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
369 *width* is a decimal integer defining the minimum field width. If not
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
370 specified, then the field width will be determined by the content.
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
371
78622
6bc14974024f Issue 15660: Clarify 0 prefix for width field in str.format doc.
Terry Jan Reedy <tjreedy@udel.edu>
parents: 76887
diff changeset
372 Preceding the *width* field by a zero (``'0'``) character enables
6bc14974024f Issue 15660: Clarify 0 prefix for width field in str.format doc.
Terry Jan Reedy <tjreedy@udel.edu>
parents: 76887
diff changeset
373 sign-aware zero-padding for numeric types. This is equivalent to a *fill*
6bc14974024f Issue 15660: Clarify 0 prefix for width field in str.format doc.
Terry Jan Reedy <tjreedy@udel.edu>
parents: 76887
diff changeset
374 character of ``'0'`` with an *alignment* type of ``'='``.
43138
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
375
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
376 The *precision* is a decimal number indicating how many digits should be
48563
b51cd5d3795c Merged revisions 65012,65035,65037-65040,65048,65057,65077,65091-65095,65097-65099,65127-65128,65131,65133-65136,65139,65149-65151,65155,65158-65159,65176-65178,65183-65184,65187-65190,65192,65194 via svnmerge from
Georg Brandl <georg@python.org>
parents: 48529
diff changeset
377 displayed after the decimal point for a floating point value formatted with
b51cd5d3795c Merged revisions 65012,65035,65037-65040,65048,65057,65077,65091-65095,65097-65099,65127-65128,65131,65133-65136,65139,65149-65151,65155,65158-65159,65176-65178,65183-65184,65187-65190,65192,65194 via svnmerge from
Georg Brandl <georg@python.org>
parents: 48529
diff changeset
378 ``'f'`` and ``'F'``, or before and after the decimal point for a floating point
b51cd5d3795c Merged revisions 65012,65035,65037-65040,65048,65057,65077,65091-65095,65097-65099,65127-65128,65131,65133-65136,65139,65149-65151,65155,65158-65159,65176-65178,65183-65184,65187-65190,65192,65194 via svnmerge from
Georg Brandl <georg@python.org>
parents: 48529
diff changeset
379 value formatted with ``'g'`` or ``'G'``. For non-number types the field
b51cd5d3795c Merged revisions 65012,65035,65037-65040,65048,65057,65077,65091-65095,65097-65099,65127-65128,65131,65133-65136,65139,65149-65151,65155,65158-65159,65176-65178,65183-65184,65187-65190,65192,65194 via svnmerge from
Georg Brandl <georg@python.org>
parents: 48529
diff changeset
380 indicates the maximum field size - in other words, how many characters will be
53884
c693003b15e2 Merged revisions 72439 via svnmerge from
Eric Smith <eric@trueblade.com>
parents: 53849
diff changeset
381 used from the field content. The *precision* is not allowed for integer values.
43138
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
382
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
383 Finally, the *type* determines how the data should be presented.
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
384
59132
2183277cbab1 Merged revisions 78442 via svnmerge from
Eric Smith <eric@trueblade.com>
parents: 58918
diff changeset
385 The available string presentation types are:
2183277cbab1 Merged revisions 78442 via svnmerge from
Eric Smith <eric@trueblade.com>
parents: 58918
diff changeset
386
2183277cbab1 Merged revisions 78442 via svnmerge from
Eric Smith <eric@trueblade.com>
parents: 58918
diff changeset
387 +---------+----------------------------------------------------------+
2183277cbab1 Merged revisions 78442 via svnmerge from
Eric Smith <eric@trueblade.com>
parents: 58918
diff changeset
388 | Type | Meaning |
2183277cbab1 Merged revisions 78442 via svnmerge from
Eric Smith <eric@trueblade.com>
parents: 58918
diff changeset
389 +=========+==========================================================+
2183277cbab1 Merged revisions 78442 via svnmerge from
Eric Smith <eric@trueblade.com>
parents: 58918
diff changeset
390 | ``'s'`` | String format. This is the default type for strings and |
2183277cbab1 Merged revisions 78442 via svnmerge from
Eric Smith <eric@trueblade.com>
parents: 58918
diff changeset
391 | | may be omitted. |
2183277cbab1 Merged revisions 78442 via svnmerge from
Eric Smith <eric@trueblade.com>
parents: 58918
diff changeset
392 +---------+----------------------------------------------------------+
2183277cbab1 Merged revisions 78442 via svnmerge from
Eric Smith <eric@trueblade.com>
parents: 58918
diff changeset
393 | None | The same as ``'s'``. |
2183277cbab1 Merged revisions 78442 via svnmerge from
Eric Smith <eric@trueblade.com>
parents: 58918
diff changeset
394 +---------+----------------------------------------------------------+
2183277cbab1 Merged revisions 78442 via svnmerge from
Eric Smith <eric@trueblade.com>
parents: 58918
diff changeset
395
43138
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
396 The available integer presentation types are:
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
397
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
398 +---------+----------------------------------------------------------+
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
399 | Type | Meaning |
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
400 +=========+==========================================================+
48482
c662e8cffddf Merged revisions 64984 via svnmerge from
Eric Smith <eric@trueblade.com>
parents: 47611
diff changeset
401 | ``'b'`` | Binary format. Outputs the number in base 2. |
43138
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
402 +---------+----------------------------------------------------------+
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
403 | ``'c'`` | Character. Converts the integer to the corresponding |
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
404 | | unicode character before printing. |
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
405 +---------+----------------------------------------------------------+
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
406 | ``'d'`` | Decimal Integer. Outputs the number in base 10. |
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
407 +---------+----------------------------------------------------------+
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
408 | ``'o'`` | Octal format. Outputs the number in base 8. |
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
409 +---------+----------------------------------------------------------+
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
410 | ``'x'`` | Hex format. Outputs the number in base 16, using lower- |
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
411 | | case letters for the digits above 9. |
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
412 +---------+----------------------------------------------------------+
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
413 | ``'X'`` | Hex format. Outputs the number in base 16, using upper- |
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
414 | | case letters for the digits above 9. |
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
415 +---------+----------------------------------------------------------+
46938
837de24ac1f7 Document the 'n' integer presentation type for str.format().
Eric Smith <eric@trueblade.com>
parents: 46556
diff changeset
416 | ``'n'`` | Number. This is the same as ``'d'``, except that it uses |
837de24ac1f7 Document the 'n' integer presentation type for str.format().
Eric Smith <eric@trueblade.com>
parents: 46556
diff changeset
417 | | the current locale setting to insert the appropriate |
837de24ac1f7 Document the 'n' integer presentation type for str.format().
Eric Smith <eric@trueblade.com>
parents: 46556
diff changeset
418 | | number separator characters. |
837de24ac1f7 Document the 'n' integer presentation type for str.format().
Eric Smith <eric@trueblade.com>
parents: 46556
diff changeset
419 +---------+----------------------------------------------------------+
48563
b51cd5d3795c Merged revisions 65012,65035,65037-65040,65048,65057,65077,65091-65095,65097-65099,65127-65128,65131,65133-65136,65139,65149-65151,65155,65158-65159,65176-65178,65183-65184,65187-65190,65192,65194 via svnmerge from
Georg Brandl <georg@python.org>
parents: 48529
diff changeset
420 | None | The same as ``'d'``. |
43138
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
421 +---------+----------------------------------------------------------+
50563
93cf3a6ead63 Merged revisions 68226 via svnmerge from
Georg Brandl <georg@python.org>
parents: 49804
diff changeset
422
59132
2183277cbab1 Merged revisions 78442 via svnmerge from
Eric Smith <eric@trueblade.com>
parents: 58918
diff changeset
423 In addition to the above presentation types, integers can be formatted
2183277cbab1 Merged revisions 78442 via svnmerge from
Eric Smith <eric@trueblade.com>
parents: 58918
diff changeset
424 with the floating point presentation types listed below (except
2183277cbab1 Merged revisions 78442 via svnmerge from
Eric Smith <eric@trueblade.com>
parents: 58918
diff changeset
425 ``'n'`` and None). When doing so, :func:`float` is used to convert the
2183277cbab1 Merged revisions 78442 via svnmerge from
Eric Smith <eric@trueblade.com>
parents: 58918
diff changeset
426 integer to a floating point number before formatting.
2183277cbab1 Merged revisions 78442 via svnmerge from
Eric Smith <eric@trueblade.com>
parents: 58918
diff changeset
427
43138
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
428 The available presentation types for floating point and decimal values are:
50563
93cf3a6ead63 Merged revisions 68226 via svnmerge from
Georg Brandl <georg@python.org>
parents: 49804
diff changeset
429
43138
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
430 +---------+----------------------------------------------------------+
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
431 | Type | Meaning |
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
432 +=========+==========================================================+
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
433 | ``'e'`` | Exponent notation. Prints the number in scientific |
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
434 | | notation using the letter 'e' to indicate the exponent. |
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
435 +---------+----------------------------------------------------------+
48523
3d526525b3e8 Backed out r65073, pending fixing it in Windows.
Eric Smith <eric@trueblade.com>
parents: 48522
diff changeset
436 | ``'E'`` | Exponent notation. Same as ``'e'`` except it uses an |
3d526525b3e8 Backed out r65073, pending fixing it in Windows.
Eric Smith <eric@trueblade.com>
parents: 48522
diff changeset
437 | | upper case 'E' as the separator character. |
43138
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
438 +---------+----------------------------------------------------------+
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
439 | ``'f'`` | Fixed point. Displays the number as a fixed-point |
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
440 | | number. |
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
441 +---------+----------------------------------------------------------+
53849
04bdc944718a Issue #3382. float 'F' formatting no longer maps to 'f'. This only affects nan and inf.
Eric Smith <eric@trueblade.com>
parents: 53795
diff changeset
442 | ``'F'`` | Fixed point. Same as ``'f'``, but converts ``nan`` to |
04bdc944718a Issue #3382. float 'F' formatting no longer maps to 'f'. This only affects nan and inf.
Eric Smith <eric@trueblade.com>
parents: 53795
diff changeset
443 | | ``NAN`` and ``inf`` to ``INF``. |
43138
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
444 +---------+----------------------------------------------------------+
56424
9f631a3bb549 Merged revisions 75290 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 56233
diff changeset
445 | ``'g'`` | General format. For a given precision ``p >= 1``, |
9f631a3bb549 Merged revisions 75290 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 56233
diff changeset
446 | | this rounds the number to ``p`` significant digits and |
9f631a3bb549 Merged revisions 75290 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 56233
diff changeset
447 | | then formats the result in either fixed-point format |
9f631a3bb549 Merged revisions 75290 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 56233
diff changeset
448 | | or in scientific notation, depending on its magnitude. |
9f631a3bb549 Merged revisions 75290 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 56233
diff changeset
449 | | |
9f631a3bb549 Merged revisions 75290 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 56233
diff changeset
450 | | The precise rules are as follows: suppose that the |
9f631a3bb549 Merged revisions 75290 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 56233
diff changeset
451 | | result formatted with presentation type ``'e'`` and |
9f631a3bb549 Merged revisions 75290 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 56233
diff changeset
452 | | precision ``p-1`` would have exponent ``exp``. Then |
9f631a3bb549 Merged revisions 75290 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 56233
diff changeset
453 | | if ``-4 <= exp < p``, the number is formatted |
9f631a3bb549 Merged revisions 75290 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 56233
diff changeset
454 | | with presentation type ``'f'`` and precision |
9f631a3bb549 Merged revisions 75290 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 56233
diff changeset
455 | | ``p-1-exp``. Otherwise, the number is formatted |
9f631a3bb549 Merged revisions 75290 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 56233
diff changeset
456 | | with presentation type ``'e'`` and precision ``p-1``. |
9f631a3bb549 Merged revisions 75290 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 56233
diff changeset
457 | | In both cases insignificant trailing zeros are removed |
9f631a3bb549 Merged revisions 75290 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 56233
diff changeset
458 | | from the significand, and the decimal point is also |
9f631a3bb549 Merged revisions 75290 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 56233
diff changeset
459 | | removed if there are no remaining digits following it. |
9f631a3bb549 Merged revisions 75290 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 56233
diff changeset
460 | | |
65235
d7a71f1d1e34 Merged revisions 85395 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 65119
diff changeset
461 | | Positive and negative infinity, positive and negative |
56424
9f631a3bb549 Merged revisions 75290 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 56233
diff changeset
462 | | zero, and nans, are formatted as ``inf``, ``-inf``, |
9f631a3bb549 Merged revisions 75290 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 56233
diff changeset
463 | | ``0``, ``-0`` and ``nan`` respectively, regardless of |
9f631a3bb549 Merged revisions 75290 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 56233
diff changeset
464 | | the precision. |
9f631a3bb549 Merged revisions 75290 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 56233
diff changeset
465 | | |
9f631a3bb549 Merged revisions 75290 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 56233
diff changeset
466 | | A precision of ``0`` is treated as equivalent to a |
9f631a3bb549 Merged revisions 75290 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 56233
diff changeset
467 | | precision of ``1``. |
43138
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
468 +---------+----------------------------------------------------------+
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
469 | ``'G'`` | General format. Same as ``'g'`` except switches to |
56424
9f631a3bb549 Merged revisions 75290 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 56233
diff changeset
470 | | ``'E'`` if the number gets too large. The |
9f631a3bb549 Merged revisions 75290 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 56233
diff changeset
471 | | representations of infinity and NaN are uppercased, too. |
43138
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
472 +---------+----------------------------------------------------------+
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
473 | ``'n'`` | Number. This is the same as ``'g'``, except that it uses |
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
474 | | the current locale setting to insert the appropriate |
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
475 | | number separator characters. |
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
476 +---------+----------------------------------------------------------+
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
477 | ``'%'`` | Percentage. Multiplies the number by 100 and displays |
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
478 | | in fixed (``'f'``) format, followed by a percent sign. |
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
479 +---------+----------------------------------------------------------+
53795
a7c99e34e239 Improved wording.
Eric Smith <eric@trueblade.com>
parents: 53793
diff changeset
480 | None | Similar to ``'g'``, except with at least one digit past |
a7c99e34e239 Improved wording.
Eric Smith <eric@trueblade.com>
parents: 53793
diff changeset
481 | | the decimal point and a default precision of 12. This is |
a7c99e34e239 Improved wording.
Eric Smith <eric@trueblade.com>
parents: 53793
diff changeset
482 | | intended to match :func:`str`, except you can add the |
a7c99e34e239 Improved wording.
Eric Smith <eric@trueblade.com>
parents: 53793
diff changeset
483 | | other format modifiers. |
43138
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
484 +---------+----------------------------------------------------------+
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
485
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
486
62704
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
487 .. _formatexamples:
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
488
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
489 Format examples
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
490 ^^^^^^^^^^^^^^^
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
491
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
492 This section contains examples of the new format syntax and comparison with
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
493 the old ``%``-formatting.
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
494
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
495 In most of the cases the syntax is similar to the old ``%``-formatting, with the
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
496 addition of the ``{}`` and with ``:`` used instead of ``%``.
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
497 For example, ``'%03.2f'`` can be translated to ``'{:03.2f}'``.
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
498
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
499 The new format syntax also supports new and different options, shown in the
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
500 follow examples.
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
501
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
502 Accessing arguments by position::
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
503
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
504 >>> '{0}, {1}, {2}'.format('a', 'b', 'c')
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
505 'a, b, c'
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
506 >>> '{}, {}, {}'.format('a', 'b', 'c') # 3.1+ only
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
507 'a, b, c'
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
508 >>> '{2}, {1}, {0}'.format('a', 'b', 'c')
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
509 'c, b, a'
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
510 >>> '{2}, {1}, {0}'.format(*'abc') # unpacking argument sequence
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
511 'c, b, a'
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
512 >>> '{0}{1}{0}'.format('abra', 'cad') # arguments' indices can be repeated
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
513 'abracadabra'
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
514
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
515 Accessing arguments by name::
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
516
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
517 >>> 'Coordinates: {latitude}, {longitude}'.format(latitude='37.24N', longitude='-115.81W')
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
518 'Coordinates: 37.24N, -115.81W'
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
519 >>> coord = {'latitude': '37.24N', 'longitude': '-115.81W'}
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
520 >>> 'Coordinates: {latitude}, {longitude}'.format(**coord)
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
521 'Coordinates: 37.24N, -115.81W'
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
522
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
523 Accessing arguments' attributes::
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
524
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
525 >>> c = 3-5j
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
526 >>> ('The complex number {0} is formed from the real part {0.real} '
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
527 ... 'and the imaginary part {0.imag}.').format(c)
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
528 'The complex number (3-5j) is formed from the real part 3.0 and the imaginary part -5.0.'
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
529 >>> class Point:
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
530 ... def __init__(self, x, y):
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
531 ... self.x, self.y = x, y
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
532 ... def __str__(self):
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
533 ... return 'Point({self.x}, {self.y})'.format(self=self)
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
534 ...
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
535 >>> str(Point(4, 2))
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
536 'Point(4, 2)'
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
537
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
538 Accessing arguments' items::
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
539
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
540 >>> coord = (3, 5)
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
541 >>> 'X: {0[0]}; Y: {0[1]}'.format(coord)
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
542 'X: 3; Y: 5'
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
543
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
544 Replacing ``%s`` and ``%r``::
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
545
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
546 >>> "repr() shows quotes: {!r}; str() doesn't: {!s}".format('test1', 'test2')
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
547 "repr() shows quotes: 'test1'; str() doesn't: test2"
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
548
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
549 Aligning the text and specifying a width::
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
550
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
551 >>> '{:<30}'.format('left aligned')
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
552 'left aligned '
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
553 >>> '{:>30}'.format('right aligned')
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
554 ' right aligned'
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
555 >>> '{:^30}'.format('centered')
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
556 ' centered '
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
557 >>> '{:*^30}'.format('centered') # use '*' as a fill char
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
558 '***********centered***********'
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
559
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
560 Replacing ``%+f``, ``%-f``, and ``% f`` and specifying a sign::
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
561
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
562 >>> '{:+f}; {:+f}'.format(3.14, -3.14) # show it always
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
563 '+3.140000; -3.140000'
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
564 >>> '{: f}; {: f}'.format(3.14, -3.14) # show a space for positive numbers
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
565 ' 3.140000; -3.140000'
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
566 >>> '{:-f}; {:-f}'.format(3.14, -3.14) # show only the minus -- same as '{:f}; {:f}'
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
567 '3.140000; -3.140000'
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
568
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
569 Replacing ``%x`` and ``%o`` and converting the value to different bases::
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
570
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
571 >>> # format also supports binary numbers
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
572 >>> "int: {0:d}; hex: {0:x}; oct: {0:o}; bin: {0:b}".format(42)
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
573 'int: 42; hex: 2a; oct: 52; bin: 101010'
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
574 >>> # with 0x, 0o, or 0b as prefix:
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
575 >>> "int: {0:d}; hex: {0:#x}; oct: {0:#o}; bin: {0:#b}".format(42)
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
576 'int: 42; hex: 0x2a; oct: 0o52; bin: 0b101010'
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
577
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
578 Using the comma as a thousands separator::
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
579
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
580 >>> '{:,}'.format(1234567890)
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
581 '1,234,567,890'
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
582
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
583 Expressing a percentage::
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
584
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
585 >>> points = 19
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
586 >>> total = 22
74156
6be3cbbe5013 remove spurious dot from string formatting example; thanks to Anthon van der Neut from docs@
Sandro Tosi <sandro.tosi@gmail.com>
parents: 72985
diff changeset
587 >>> 'Correct answers: {:.2%}'.format(points/total)
62704
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
588 'Correct answers: 86.36%'
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
589
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
590 Using type-specific formatting::
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
591
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
592 >>> import datetime
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
593 >>> d = datetime.datetime(2010, 7, 4, 12, 15, 58)
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
594 >>> '{:%Y-%m-%d %H:%M:%S}'.format(d)
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
595 '2010-07-04 12:15:58'
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
596
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
597 Nesting arguments and more complex examples::
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
598
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
599 >>> for align, text in zip('<^>', ['left', 'center', 'right']):
68009
92629ccaae76 Merged revisions 87627,87638,87739,87760,87771,87787,87984,87986,88108,88115,88144,88165,88329,88364-88365,88369-88370,88423-88424 via svnmerge from
Georg Brandl <georg@python.org>
parents: 67490
diff changeset
600 ... '{0:{fill}{align}16}'.format(text, fill=align, align=align)
62704
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
601 ...
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
602 'left<<<<<<<<<<<<'
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
603 '^^^^^center^^^^^'
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
604 '>>>>>>>>>>>right'
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
605 >>>
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
606 >>> octets = [192, 168, 0, 1]
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
607 >>> '{:02X}{:02X}{:02X}{:02X}'.format(*octets)
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
608 'C0A80001'
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
609 >>> int(_, 16)
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
610 3232235521
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
611 >>>
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
612 >>> width = 5
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
613 >>> for num in range(5,12):
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
614 ... for base in 'dXob':
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
615 ... print('{0:{width}{base}}'.format(num, base=base, width=width), end=' ')
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
616 ... print()
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
617 ...
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
618 5 5 5 101
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
619 6 6 6 110
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
620 7 7 7 111
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
621 8 8 10 1000
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
622 9 9 11 1001
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
623 10 A 12 1010
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
624 11 B 13 1011
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
625
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
626
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
627
43138
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
628 .. _template-strings:
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
629
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
630 Template strings
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
631 ----------------
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
632
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
633 Templates provide simpler string substitutions as described in :pep:`292`.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
634 Instead of the normal ``%``\ -based substitutions, Templates support ``$``\
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
635 -based substitutions, using the following rules:
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
636
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
637 * ``$$`` is an escape; it is replaced with a single ``$``.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
638
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
639 * ``$identifier`` names a substitution placeholder matching a mapping key of
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
640 ``"identifier"``. By default, ``"identifier"`` must spell a Python
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
641 identifier. The first non-identifier character after the ``$`` character
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
642 terminates this placeholder specification.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
643
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
644 * ``${identifier}`` is equivalent to ``$identifier``. It is required when valid
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
645 identifier characters follow the placeholder but are not part of the
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
646 placeholder, such as ``"${noun}ification"``.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
647
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
648 Any other appearance of ``$`` in the string will result in a :exc:`ValueError`
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
649 being raised.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
650
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
651 The :mod:`string` module provides a :class:`Template` class that implements
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
652 these rules. The methods of :class:`Template` are:
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
653
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
654
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
655 .. class:: Template(template)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
656
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
657 The constructor takes a single argument which is the template string.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
658
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
659
56002
fa91270b6087 Merged revisions 74821,74828-74831,74833,74835 via svnmerge from
Georg Brandl <georg@python.org>
parents: 55797
diff changeset
660 .. method:: substitute(mapping, **kwds)
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
661
46556
8b718fc15f3d Merged revisions 62490 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 46034
diff changeset
662 Performs the template substitution, returning a new string. *mapping* is
8b718fc15f3d Merged revisions 62490 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 46034
diff changeset
663 any dictionary-like object with keys that match the placeholders in the
8b718fc15f3d Merged revisions 62490 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 46034
diff changeset
664 template. Alternatively, you can provide keyword arguments, where the
56002
fa91270b6087 Merged revisions 74821,74828-74831,74833,74835 via svnmerge from
Georg Brandl <georg@python.org>
parents: 55797
diff changeset
665 keywords are the placeholders. When both *mapping* and *kwds* are given
fa91270b6087 Merged revisions 74821,74828-74831,74833,74835 via svnmerge from
Georg Brandl <georg@python.org>
parents: 55797
diff changeset
666 and there are duplicates, the placeholders from *kwds* take precedence.
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
667
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
668
56002
fa91270b6087 Merged revisions 74821,74828-74831,74833,74835 via svnmerge from
Georg Brandl <georg@python.org>
parents: 55797
diff changeset
669 .. method:: safe_substitute(mapping, **kwds)
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
670
46556
8b718fc15f3d Merged revisions 62490 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 46034
diff changeset
671 Like :meth:`substitute`, except that if placeholders are missing from
56002
fa91270b6087 Merged revisions 74821,74828-74831,74833,74835 via svnmerge from
Georg Brandl <georg@python.org>
parents: 55797
diff changeset
672 *mapping* and *kwds*, instead of raising a :exc:`KeyError` exception, the
46556
8b718fc15f3d Merged revisions 62490 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 46034
diff changeset
673 original placeholder will appear in the resulting string intact. Also,
8b718fc15f3d Merged revisions 62490 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 46034
diff changeset
674 unlike with :meth:`substitute`, any other appearances of the ``$`` will
8b718fc15f3d Merged revisions 62490 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 46034
diff changeset
675 simply return ``$`` instead of raising :exc:`ValueError`.
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
676
46556
8b718fc15f3d Merged revisions 62490 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 46034
diff changeset
677 While other exceptions may still occur, this method is called "safe"
8b718fc15f3d Merged revisions 62490 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 46034
diff changeset
678 because substitutions always tries to return a usable string instead of
8b718fc15f3d Merged revisions 62490 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 46034
diff changeset
679 raising an exception. In another sense, :meth:`safe_substitute` may be
8b718fc15f3d Merged revisions 62490 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 46034
diff changeset
680 anything other than safe, since it will silently ignore malformed
8b718fc15f3d Merged revisions 62490 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 46034
diff changeset
681 templates containing dangling delimiters, unmatched braces, or
8b718fc15f3d Merged revisions 62490 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 46034
diff changeset
682 placeholders that are not valid Python identifiers.
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
683
57454
508654cee137 Merged revisions 76518 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 56424
diff changeset
684 :class:`Template` instances also provide one public data attribute:
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
685
57454
508654cee137 Merged revisions 76518 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 56424
diff changeset
686 .. attribute:: template
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
687
57454
508654cee137 Merged revisions 76518 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 56424
diff changeset
688 This is the object passed to the constructor's *template* argument. In
508654cee137 Merged revisions 76518 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 56424
diff changeset
689 general, you shouldn't change it, but read-only access is not enforced.
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
690
46034
0a485593ae1c Merged revisions 61724-61725,61731-61735,61737,61739,61741,61743-61744,61753,61761,61765-61767,61769,61773,61776-61778,61780-61783,61788,61793,61796,61807,61813 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents: 45084
diff changeset
691 Here is an example of how to use a Template:
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
692
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
693 >>> from string import Template
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
694 >>> s = Template('$who likes $what')
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
695 >>> s.substitute(who='tim', what='kung pao')
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
696 'tim likes kung pao'
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
697 >>> d = dict(who='tim')
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
698 >>> Template('Give $who $100').substitute(d)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
699 Traceback (most recent call last):
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
700 [...]
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
701 ValueError: Invalid placeholder in string: line 1, col 10
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
702 >>> Template('$who likes $what').substitute(d)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
703 Traceback (most recent call last):
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
704 [...]
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
705 KeyError: 'what'
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
706 >>> Template('$who likes $what').safe_substitute(d)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
707 'tim likes $what'
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
708
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
709 Advanced usage: you can derive subclasses of :class:`Template` to customize the
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
710 placeholder syntax, delimiter character, or the entire regular expression used
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
711 to parse template strings. To do this, you can override these class attributes:
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
712
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
713 * *delimiter* -- This is the literal string describing a placeholder introducing
71761
6151d7cea7fe Fix grammar
Eli Bendersky <eliben@gmail.com>
parents: 68257
diff changeset
714 delimiter. The default value is ``$``. Note that this should *not* be a
6151d7cea7fe Fix grammar
Eli Bendersky <eliben@gmail.com>
parents: 68257
diff changeset
715 regular expression, as the implementation will call :meth:`re.escape` on this
6151d7cea7fe Fix grammar
Eli Bendersky <eliben@gmail.com>
parents: 68257
diff changeset
716 string as needed.
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
717
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
718 * *idpattern* -- This is the regular expression describing the pattern for
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
719 non-braced placeholders (the braces will be added automatically as
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
720 appropriate). The default value is the regular expression
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
721 ``[_a-z][_a-z0-9]*``.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
722
63295
91cbb55e20be #6630: allow customizing flags for compiling string.Template.idpattern.
Georg Brandl <georg@python.org>
parents: 63125
diff changeset
723 * *flags* -- The regular expression flags that will be applied when compiling
91cbb55e20be #6630: allow customizing flags for compiling string.Template.idpattern.
Georg Brandl <georg@python.org>
parents: 63125
diff changeset
724 the regular expression used for recognizing substitutions. The default value
91cbb55e20be #6630: allow customizing flags for compiling string.Template.idpattern.
Georg Brandl <georg@python.org>
parents: 63125
diff changeset
725 is ``re.IGNORECASE``. Note that ``re.VERBOSE`` will always be added to the
91cbb55e20be #6630: allow customizing flags for compiling string.Template.idpattern.
Georg Brandl <georg@python.org>
parents: 63125
diff changeset
726 flags, so custom *idpattern*\ s must follow conventions for verbose regular
91cbb55e20be #6630: allow customizing flags for compiling string.Template.idpattern.
Georg Brandl <georg@python.org>
parents: 63125
diff changeset
727 expressions.
91cbb55e20be #6630: allow customizing flags for compiling string.Template.idpattern.
Georg Brandl <georg@python.org>
parents: 63125
diff changeset
728
91cbb55e20be #6630: allow customizing flags for compiling string.Template.idpattern.
Georg Brandl <georg@python.org>
parents: 63125
diff changeset
729 .. versionadded:: 3.2
91cbb55e20be #6630: allow customizing flags for compiling string.Template.idpattern.
Georg Brandl <georg@python.org>
parents: 63125
diff changeset
730
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
731 Alternatively, you can provide the entire regular expression pattern by
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
732 overriding the class attribute *pattern*. If you do this, the value must be a
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
733 regular expression object with four named capturing groups. The capturing
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
734 groups correspond to the rules given above, along with the invalid placeholder
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
735 rule:
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
736
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
737 * *escaped* -- This group matches the escape sequence, e.g. ``$$``, in the
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
738 default pattern.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
739
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
740 * *named* -- This group matches the unbraced placeholder name; it should not
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
741 include the delimiter in capturing group.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
742
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
743 * *braced* -- This group matches the brace enclosed placeholder name; it should
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
744 not include either the delimiter or braces in the capturing group.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
745
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
746 * *invalid* -- This group matches any other delimiter pattern (usually a single
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
747 delimiter), and it should appear last in the regular expression.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
748
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
749
53094
4407e4d07084 Add bytes/bytearray.maketrans() to mirror str.maketrans(), and deprecate
Georg Brandl <georg@python.org>
parents: 52432
diff changeset
750 Helper functions
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
751 ----------------
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
752
56236
b050ea7baf40 fix default value
Georg Brandl <georg@python.org>
parents: 56235
diff changeset
753 .. function:: capwords(s, sep=None)
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
754
56233
f3c595214abc Merged revisions 75074 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 56002
diff changeset
755 Split the argument into words using :meth:`str.split`, capitalize each word
f3c595214abc Merged revisions 75074 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 56002
diff changeset
756 using :meth:`str.capitalize`, and join the capitalized words using
f3c595214abc Merged revisions 75074 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 56002
diff changeset
757 :meth:`str.join`. If the optional second argument *sep* is absent
f3c595214abc Merged revisions 75074 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 56002
diff changeset
758 or ``None``, runs of whitespace characters are replaced by a single space
f3c595214abc Merged revisions 75074 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 56002
diff changeset
759 and leading and trailing whitespace are removed, otherwise *sep* is used to
f3c595214abc Merged revisions 75074 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 56002
diff changeset
760 split and join the words.
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
761