Mercurial > cpython-lru_cache-weakref

annotate Doc/library/string.rst @ 78069:a8aa77458e12 3.2

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Add c_size_t and c_ssize_t to the ctypes summary table.
author Antoine Pitrou <solipsis@pitrou.net>
date Thu, 12 Jul 2012 20:31:50 +0200
parents 04e7264e8fcf
children 6bc14974024f
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
67490
5f77907b0041 Merged revisions 87789-87790 via svnmerge from
Georg Brandl <georg@python.org>
parents: 66475
diff changeset
13 :ref:`typesseq`
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
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
94 :meth:`format` is the primary API method. It takes a format template
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
95 string, and an arbitrary set of positional and keyword argument.
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``
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
104 syntax. :meth:`vformat` does the work of breaking up the format template
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
105 string into character data and replacement fields. It calls the various
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
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
176 version understands 'r' (repr) and 's' (str) conversion 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
177
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 .. _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
180
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 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
182 --------------------
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 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
185 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
186 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
187
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 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
189 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
190 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
191 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
192
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 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
194
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 .. productionlist:: sf
55797
afbb2b2ff6f7 Merged revisions 74613,74615,74619-74620,74622 via svnmerge from
Georg Brandl <georg@python.org>
parents: 55580
diff changeset
196 replacement_field: "{" [`field_name`] ["!" `conversion`] [":" `format_spec`] "}"
53307
414ba8efc804 Merged revisions 71788 via svnmerge from
Eric Smith <eric@trueblade.com>
parents: 53094
diff changeset
197 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
198 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
199 attribute_name: `identifier`
59136
5f04e0cd8171 Merged revisions 78446 via svnmerge from
Eric Smith <eric@trueblade.com>
parents: 59132
diff changeset
200 element_index: `integer` | `index_string`
5f04e0cd8171 Merged revisions 78446 via svnmerge from
Eric Smith <eric@trueblade.com>
parents: 59132
diff changeset
201 index_string: <any source character except "]"> +
49698
211151fdc924 update string formatting grammar
Benjamin Peterson <benjamin@python.org>
parents: 49178
diff changeset
202 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
203 format_spec: <described in the next section>
50563
93cf3a6ead63 Merged revisions 68226 via svnmerge from
Georg Brandl <georg@python.org>
parents: 49804
diff changeset
204
55797
afbb2b2ff6f7 Merged revisions 74613,74615,74619-74620,74622 via svnmerge from
Georg Brandl <georg@python.org>
parents: 55580
diff changeset
205 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
206 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
207 into the output instead of the replacement field.
414ba8efc804 Merged revisions 71788 via svnmerge from
Eric Smith <eric@trueblade.com>
parents: 53094
diff changeset
208 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
209 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
210 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
211
62704
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
212 See also the :ref:`formatspec` section.
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
213
72985
e19ccbbe70dd Remove duplication.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 72265
diff changeset
214 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
215 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
216 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
217 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
218 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
219 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
220 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
221 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
222 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
223 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
224 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
225
62704
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
226 .. versionchanged:: 3.1
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
227 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
228 equivalent to ``'{0} {1}'``.
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
229
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
230 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
231
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 "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
233 "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
234 "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
235 "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
236 "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
237 "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
238
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
239 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
240 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
241 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
242 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
243 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
244 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
245
47611
da47e7e135ae #2630: Implement PEP 3138.
Georg Brandl <georg@python.org>
parents: 47279
diff changeset
246 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
247 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
248 :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
249
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 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
251
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 "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
253 "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
254 "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
255
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 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
257 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
258 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
259 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
260
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 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
262 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
263
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 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
265 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
266 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
267 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
268 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
269
62704
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
270 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
271
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 .. _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
274
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 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
276 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
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 "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
279 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
280 :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
281 :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
282 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
283
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 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
285 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
286
59132
2183277cbab1 Merged revisions 78442 via svnmerge from
Eric Smith <eric@trueblade.com>
parents: 58918
diff changeset
287 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
288 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
289 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
290
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 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
292
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 .. productionlist:: sf
55229
88acc10caa6e Document the thousands separator.
Raymond Hettinger <python@rcn.com>
parents: 53884
diff changeset
294 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
295 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
296 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
297 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
298 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
299 precision: `integer`
59132
2183277cbab1 Merged revisions 78442 via svnmerge from
Eric Smith <eric@trueblade.com>
parents: 58918
diff changeset
300 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
301
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
302 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
303 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
304 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
305 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
306 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
307
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 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
309
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 | 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
312 +=========+==========================================================+
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 | ``'<'`` | 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
314 | | 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
315 +---------+----------------------------------------------------------+
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 | ``'>'`` | 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
317 | | 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
318 +---------+----------------------------------------------------------+
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 | ``'='`` | 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
320 | | 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
321 | | 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
322 | | 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
323 +---------+----------------------------------------------------------+
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 | ``'^'`` | 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
325 | | 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
326 +---------+----------------------------------------------------------+
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 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
329 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
330 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
331
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 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
333 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
334
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 | 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
337 +=========+==========================================================+
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 | ``'+'`` | 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
339 | | 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
340 +---------+----------------------------------------------------------+
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 | ``'-'`` | 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
342 | | 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
343 +---------+----------------------------------------------------------+
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 | 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
345 | | 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
346 +---------+----------------------------------------------------------+
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
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
348
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 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
350 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
351 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
352 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
353 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
354 ``'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
355 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
356 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
357 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
358 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
359 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
360
55229
88acc10caa6e Document the thousands separator.
Raymond Hettinger <python@rcn.com>
parents: 53884
diff changeset
361 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
362 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
363 instead.
88acc10caa6e Document the thousands separator.
Raymond Hettinger <python@rcn.com>
parents: 53884
diff changeset
364
62704
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
365 .. versionchanged:: 3.1
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
366 Added the ``','`` option (see also :pep:`378`).
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
367
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
368 *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
369 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
370
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 If the *width* field is preceded by a zero (``'0'``) character, this enables
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
372 zero-padding. This is equivalent to an *alignment* type of ``'='`` and a *fill*
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
373 character of ``'0'``.
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
374
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 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
376 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
377 ``'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
378 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
379 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
380 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
381
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 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
383
59132
2183277cbab1 Merged revisions 78442 via svnmerge from
Eric Smith <eric@trueblade.com>
parents: 58918
diff changeset
384 The available string presentation types are:
2183277cbab1 Merged revisions 78442 via svnmerge from
Eric Smith <eric@trueblade.com>
parents: 58918
diff changeset
385
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 | Type | Meaning |
2183277cbab1 Merged revisions 78442 via svnmerge from
Eric Smith <eric@trueblade.com>
parents: 58918
diff changeset
388 +=========+==========================================================+
2183277cbab1 Merged revisions 78442 via svnmerge from
Eric Smith <eric@trueblade.com>
parents: 58918
diff changeset
389 | ``'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
390 | | may be omitted. |
2183277cbab1 Merged revisions 78442 via svnmerge from
Eric Smith <eric@trueblade.com>
parents: 58918
diff changeset
391 +---------+----------------------------------------------------------+
2183277cbab1 Merged revisions 78442 via svnmerge from
Eric Smith <eric@trueblade.com>
parents: 58918
diff changeset
392 | None | The same as ``'s'``. |
2183277cbab1 Merged revisions 78442 via svnmerge from
Eric Smith <eric@trueblade.com>
parents: 58918
diff changeset
393 +---------+----------------------------------------------------------+
2183277cbab1 Merged revisions 78442 via svnmerge from
Eric Smith <eric@trueblade.com>
parents: 58918
diff changeset
394
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
395 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
396
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 | 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
399 +=========+==========================================================+
48482
c662e8cffddf Merged revisions 64984 via svnmerge from
Eric Smith <eric@trueblade.com>
parents: 47611
diff changeset
400 | ``'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
401 +---------+----------------------------------------------------------+
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 | ``'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
403 | | 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
404 +---------+----------------------------------------------------------+
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 | ``'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
406 +---------+----------------------------------------------------------+
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 | ``'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
408 +---------+----------------------------------------------------------+
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 | ``'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
410 | | 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
411 +---------+----------------------------------------------------------+
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 | ``'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
413 | | 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
414 +---------+----------------------------------------------------------+
46938
837de24ac1f7 Document the 'n' integer presentation type for str.format().
Eric Smith <eric@trueblade.com>
parents: 46556
diff changeset
415 | ``'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
416 | | 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
417 | | number separator characters. |
837de24ac1f7 Document the 'n' integer presentation type for str.format().
Eric Smith <eric@trueblade.com>
parents: 46556
diff changeset
418 +---------+----------------------------------------------------------+
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
419 | 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
420 +---------+----------------------------------------------------------+
50563
93cf3a6ead63 Merged revisions 68226 via svnmerge from
Georg Brandl <georg@python.org>
parents: 49804
diff changeset
421
59132
2183277cbab1 Merged revisions 78442 via svnmerge from
Eric Smith <eric@trueblade.com>
parents: 58918
diff changeset
422 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
423 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
424 ``'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
425 integer to a floating point number before formatting.
2183277cbab1 Merged revisions 78442 via svnmerge from
Eric Smith <eric@trueblade.com>
parents: 58918
diff changeset
426
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
427 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
428
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
429 +---------+----------------------------------------------------------+
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 | 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
431 +=========+==========================================================+
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 | ``'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
433 | | 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
434 +---------+----------------------------------------------------------+
48523
3d526525b3e8 Backed out r65073, pending fixing it in Windows.
Eric Smith <eric@trueblade.com>
parents: 48522
diff changeset
435 | ``'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
436 | | 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
437 +---------+----------------------------------------------------------+
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 | ``'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
439 | | 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
440 +---------+----------------------------------------------------------+
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
441 | ``'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
442 | | ``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
443 +---------+----------------------------------------------------------+
56424
9f631a3bb549 Merged revisions 75290 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 56233
diff changeset
444 | ``'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
445 | | 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
446 | | 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
447 | | or in scientific notation, depending on its magnitude. |
9f631a3bb549 Merged revisions 75290 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 56233
diff changeset
448 | | |
9f631a3bb549 Merged revisions 75290 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 56233
diff changeset
449 | | 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
450 | | result formatted with presentation type ``'e'`` and |
9f631a3bb549 Merged revisions 75290 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 56233
diff changeset
451 | | precision ``p-1`` would have exponent ``exp``. Then |
9f631a3bb549 Merged revisions 75290 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 56233
diff changeset
452 | | if ``-4 <= exp < p``, the number is formatted |
9f631a3bb549 Merged revisions 75290 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 56233
diff changeset
453 | | with presentation type ``'f'`` and precision |
9f631a3bb549 Merged revisions 75290 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 56233
diff changeset
454 | | ``p-1-exp``. Otherwise, the number is formatted |
9f631a3bb549 Merged revisions 75290 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 56233
diff changeset
455 | | with presentation type ``'e'`` and precision ``p-1``. |
9f631a3bb549 Merged revisions 75290 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 56233
diff changeset
456 | | In both cases insignificant trailing zeros are removed |
9f631a3bb549 Merged revisions 75290 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 56233
diff changeset
457 | | 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
458 | | 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
459 | | |
65235
d7a71f1d1e34 Merged revisions 85395 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 65119
diff changeset
460 | | Positive and negative infinity, positive and negative |
56424
9f631a3bb549 Merged revisions 75290 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 56233
diff changeset
461 | | zero, and nans, are formatted as ``inf``, ``-inf``, |
9f631a3bb549 Merged revisions 75290 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 56233
diff changeset
462 | | ``0``, ``-0`` and ``nan`` respectively, regardless of |
9f631a3bb549 Merged revisions 75290 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 56233
diff changeset
463 | | the precision. |
9f631a3bb549 Merged revisions 75290 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 56233
diff changeset
464 | | |
9f631a3bb549 Merged revisions 75290 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 56233
diff changeset
465 | | 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
466 | | 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
467 +---------+----------------------------------------------------------+
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 | ``'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
469 | | ``'E'`` if the number gets too large. The |
9f631a3bb549 Merged revisions 75290 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 56233
diff changeset
470 | | 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
471 +---------+----------------------------------------------------------+
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 | ``'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
473 | | 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
474 | | 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
475 +---------+----------------------------------------------------------+
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 | ``'%'`` | 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
477 | | 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
478 +---------+----------------------------------------------------------+
53795
a7c99e34e239 Improved wording.
Eric Smith <eric@trueblade.com>
parents: 53793
diff changeset
479 | None | Similar to ``'g'``, except with at least one digit past |
a7c99e34e239 Improved wording.
Eric Smith <eric@trueblade.com>
parents: 53793
diff changeset
480 | | the decimal point and a default precision of 12. This is |
a7c99e34e239 Improved wording.
Eric Smith <eric@trueblade.com>
parents: 53793
diff changeset
481 | | intended to match :func:`str`, except you can add the |
a7c99e34e239 Improved wording.
Eric Smith <eric@trueblade.com>
parents: 53793
diff changeset
482 | | 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
483 +---------+----------------------------------------------------------+
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
62704
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
486 .. _formatexamples:
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
487
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
488 Format examples
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
489 ^^^^^^^^^^^^^^^
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 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
492 the old ``%``-formatting.
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
493
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
494 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
495 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
496 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
497
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
498 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
499 follow examples.
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
500
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
501 Accessing arguments by position::
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
502
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
503 >>> '{0}, {1}, {2}'.format('a', 'b', 'c')
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
504 'a, b, c'
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
505 >>> '{}, {}, {}'.format('a', 'b', 'c') # 3.1+ only
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
506 'a, b, c'
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
507 >>> '{2}, {1}, {0}'.format('a', 'b', 'c')
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
508 'c, b, a'
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
509 >>> '{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
510 'c, b, a'
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
511 >>> '{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
512 'abracadabra'
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
513
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
514 Accessing arguments by name::
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
515
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
516 >>> '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
517 'Coordinates: 37.24N, -115.81W'
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
518 >>> coord = {'latitude': '37.24N', 'longitude': '-115.81W'}
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
519 >>> 'Coordinates: {latitude}, {longitude}'.format(**coord)
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
520 'Coordinates: 37.24N, -115.81W'
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
521
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
522 Accessing arguments' attributes::
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
523
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
524 >>> c = 3-5j
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
525 >>> ('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
526 ... '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
527 '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
528 >>> class Point:
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
529 ... def __init__(self, x, y):
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
530 ... self.x, self.y = x, y
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
531 ... def __str__(self):
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
532 ... 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
533 ...
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
534 >>> str(Point(4, 2))
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
535 'Point(4, 2)'
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
536
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
537 Accessing arguments' items::
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
538
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
539 >>> coord = (3, 5)
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
540 >>> '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
541 'X: 3; Y: 5'
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
542
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
543 Replacing ``%s`` and ``%r``::
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
544
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
545 >>> "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
546 "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
547
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
548 Aligning the text and specifying a width::
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
549
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
550 >>> '{:<30}'.format('left aligned')
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
551 'left aligned '
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
552 >>> '{:>30}'.format('right aligned')
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
553 ' right aligned'
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
554 >>> '{:^30}'.format('centered')
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
555 ' centered '
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
556 >>> '{:*^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
557 '***********centered***********'
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
558
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
559 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
560
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
561 >>> '{:+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
562 '+3.140000; -3.140000'
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
563 >>> '{: 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
564 ' 3.140000; -3.140000'
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
565 >>> '{:-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
566 '3.140000; -3.140000'
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
567
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
568 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
569
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
570 >>> # format also supports binary numbers
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
571 >>> "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
572 '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
573 >>> # with 0x, 0o, or 0b as prefix:
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
574 >>> "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
575 '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
576
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
577 Using the comma as a thousands separator::
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
578
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
579 >>> '{:,}'.format(1234567890)
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
580 '1,234,567,890'
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
581
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
582 Expressing a percentage::
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
583
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
584 >>> points = 19
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
585 >>> 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
586 >>> 'Correct answers: {:.2%}'.format(points/total)
62704
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
587 'Correct answers: 86.36%'
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
588
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
589 Using type-specific formatting::
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
590
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
591 >>> import datetime
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
592 >>> 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
593 >>> '{:%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
594 '2010-07-04 12:15:58'
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
595
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
596 Nesting arguments and more complex examples::
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
597
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
598 >>> 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
599 ... '{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
600 ...
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
601 'left<<<<<<<<<<<<'
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
602 '^^^^^center^^^^^'
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
603 '>>>>>>>>>>>right'
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
604 >>>
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
605 >>> octets = [192, 168, 0, 1]
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
606 >>> '{:02X}{:02X}{:02X}{:02X}'.format(*octets)
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
607 'C0A80001'
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
608 >>> int(_, 16)
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
609 3232235521
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
610 >>>
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
611 >>> width = 5
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
612 >>> for num in range(5,12):
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
613 ... for base in 'dXob':
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
614 ... 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
615 ... print()
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
616 ...
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
617 5 5 5 101
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
618 6 6 6 110
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
619 7 7 7 111
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
620 8 8 10 1000
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
621 9 9 11 1001
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
622 10 A 12 1010
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
623 11 B 13 1011
8bf6d8beafe1 Merged revisions 82462 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59136
diff changeset
624
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
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
627 .. _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
628
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
629 Template strings
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
630 ----------------
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 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
633 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
634 -based substitutions, using the following rules:
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
635
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
636 * ``$$`` 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
637
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
638 * ``$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
639 ``"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
640 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
641 terminates this placeholder specification.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
642
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
643 * ``${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
644 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
645 placeholder, such as ``"${noun}ification"``.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
646
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
647 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
648 being raised.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
649
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
650 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
651 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
652
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 .. class:: Template(template)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
655
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
656 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
657
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
658
56002
fa91270b6087 Merged revisions 74821,74828-74831,74833,74835 via svnmerge from
Georg Brandl <georg@python.org>
parents: 55797
diff changeset
659 .. method:: substitute(mapping, **kwds)
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
660
46556
8b718fc15f3d Merged revisions 62490 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 46034
diff changeset
661 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
662 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
663 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
664 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
665 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
666
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
667
56002
fa91270b6087 Merged revisions 74821,74828-74831,74833,74835 via svnmerge from
Georg Brandl <georg@python.org>
parents: 55797
diff changeset
668 .. method:: safe_substitute(mapping, **kwds)
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
669
46556
8b718fc15f3d Merged revisions 62490 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 46034
diff changeset
670 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
671 *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
672 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
673 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
674 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
675
46556
8b718fc15f3d Merged revisions 62490 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 46034
diff changeset
676 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
677 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
678 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
679 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
680 templates containing dangling delimiters, unmatched braces, or
8b718fc15f3d Merged revisions 62490 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 46034
diff changeset
681 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
682
57454
508654cee137 Merged revisions 76518 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 56424
diff changeset
683 :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
684
57454
508654cee137 Merged revisions 76518 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 56424
diff changeset
685 .. attribute:: template
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
686
57454
508654cee137 Merged revisions 76518 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 56424
diff changeset
687 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
688 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
689
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
690 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
691
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
692 >>> from string import Template
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
693 >>> s = Template('$who likes $what')
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
694 >>> s.substitute(who='tim', what='kung pao')
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
695 'tim likes kung pao'
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
696 >>> d = dict(who='tim')
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
697 >>> Template('Give $who $100').substitute(d)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
698 Traceback (most recent call last):
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
699 [...]
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
700 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
701 >>> Template('$who likes $what').substitute(d)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
702 Traceback (most recent call last):
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
703 [...]
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
704 KeyError: 'what'
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
705 >>> Template('$who likes $what').safe_substitute(d)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
706 'tim likes $what'
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
707
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
708 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
709 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
710 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
711
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
712 * *delimiter* -- This is the literal string describing a placeholder introducing
71761
6151d7cea7fe Fix grammar
Eli Bendersky <eliben@gmail.com>
parents: 68257
diff changeset
713 delimiter. The default value is ``$``. Note that this should *not* be a
6151d7cea7fe Fix grammar
Eli Bendersky <eliben@gmail.com>
parents: 68257
diff changeset
714 regular expression, as the implementation will call :meth:`re.escape` on this
6151d7cea7fe Fix grammar
Eli Bendersky <eliben@gmail.com>
parents: 68257
diff changeset
715 string as needed.
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
716
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
717 * *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
718 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
719 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
720 ``[_a-z][_a-z0-9]*``.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
721
63295
91cbb55e20be #6630: allow customizing flags for compiling string.Template.idpattern.
Georg Brandl <georg@python.org>
parents: 63125
diff changeset
722 * *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
723 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
724 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
725 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
726 expressions.
91cbb55e20be #6630: allow customizing flags for compiling string.Template.idpattern.
Georg Brandl <georg@python.org>
parents: 63125
diff changeset
727
91cbb55e20be #6630: allow customizing flags for compiling string.Template.idpattern.
Georg Brandl <georg@python.org>
parents: 63125
diff changeset
728 .. versionadded:: 3.2
91cbb55e20be #6630: allow customizing flags for compiling string.Template.idpattern.
Georg Brandl <georg@python.org>
parents: 63125
diff changeset
729
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
730 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
731 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
732 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
733 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
734 rule:
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
735
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
736 * *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
737 default pattern.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
738
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
739 * *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
740 include the delimiter in capturing group.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
741
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
742 * *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
743 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
744
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
745 * *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
746 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
747
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
748
53094
4407e4d07084 Add bytes/bytearray.maketrans() to mirror str.maketrans(), and deprecate
Georg Brandl <georg@python.org>
parents: 52432
diff changeset
749 Helper functions
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
750 ----------------
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
751
56236
b050ea7baf40 fix default value
Georg Brandl <georg@python.org>
parents: 56235
diff changeset
752 .. function:: capwords(s, sep=None)
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
753
56233
f3c595214abc Merged revisions 75074 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 56002
diff changeset
754 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
755 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
756 :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
757 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
758 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
759 split and join the words.
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
760