Mercurial > cpython-lru_cache-weakref

annotate Doc/library/string.rst @ 65035:87f4b32905df 2.7

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Cosmetic fix to use print function.
author Hirokazu Yamamoto <ocean-city@m2.ccsnet.ne.jp>
date Fri, 01 Oct 2010 10:48:47 +0000
parents fa16acb2ffdd
children ff734f225b47
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1 :mod:`string` --- Common string operations
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2 ==========================================
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
3
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
4 .. module:: string
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
5 :synopsis: Common string operations.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
6
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
7
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
8 .. index:: module: re
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
9
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
10 The :mod:`string` module contains a number of useful constants and
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
11 classes, as well as some deprecated legacy functions that are also
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
12 available as methods on strings. In addition, Python's built-in string
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
13 classes support the sequence type methods described in the
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
14 :ref:`typesseq` section, and also the string-specific methods described
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
15 in the :ref:`string-methods` section. To output formatted strings use
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
16 template strings or the ``%`` operator described in the
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
17 :ref:`string-formatting` section. Also, see the :mod:`re` module for
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
18 string functions based on regular expressions.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
19
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
20
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
21 String constants
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
22 ----------------
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
23
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
24 The constants defined in this module are:
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
25
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
26
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
27 .. data:: ascii_letters
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
28
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
29 The concatenation of the :const:`ascii_lowercase` and :const:`ascii_uppercase`
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
30 constants described below. This value is not locale-dependent.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
31
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
32
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
33 .. data:: ascii_lowercase
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
34
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
35 The lowercase letters ``'abcdefghijklmnopqrstuvwxyz'``. This value is not
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
36 locale-dependent and will not change.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
37
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
38
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
39 .. data:: ascii_uppercase
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
40
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
41 The uppercase letters ``'ABCDEFGHIJKLMNOPQRSTUVWXYZ'``. This value is not
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
42 locale-dependent and will not change.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
43
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
44
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
45 .. data:: digits
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
46
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
47 The string ``'0123456789'``.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
48
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
49
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
50 .. data:: hexdigits
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
51
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
52 The string ``'0123456789abcdefABCDEF'``.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
53
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
54
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
55 .. data:: letters
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
56
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
57 The concatenation of the strings :const:`lowercase` and :const:`uppercase`
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
58 described below. The specific value is locale-dependent, and will be updated
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
59 when :func:`locale.setlocale` is called.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
60
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
61
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
62 .. data:: lowercase
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
63
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
64 A string containing all the characters that are considered lowercase letters.
52003
0c028685b44c Remove obsolete stuff from string module docs.
Georg Brandl <georg@python.org>
parents: 50522
diff changeset
65 On most systems this is the string ``'abcdefghijklmnopqrstuvwxyz'``. The
0c028685b44c Remove obsolete stuff from string module docs.
Georg Brandl <georg@python.org>
parents: 50522
diff changeset
66 specific value is locale-dependent, and will be updated when
0c028685b44c Remove obsolete stuff from string module docs.
Georg Brandl <georg@python.org>
parents: 50522
diff changeset
67 :func:`locale.setlocale` is called.
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
68
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
69
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
70 .. data:: octdigits
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
71
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
72 The string ``'01234567'``.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
73
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
74
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
75 .. data:: punctuation
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
76
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
77 String of ASCII characters which are considered punctuation characters in the
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
78 ``C`` locale.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
79
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
80
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
81 .. data:: printable
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
82
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
83 String of characters which are considered printable. This is a combination of
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
84 :const:`digits`, :const:`letters`, :const:`punctuation`, and
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
85 :const:`whitespace`.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
86
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
87
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
88 .. data:: uppercase
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
89
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
90 A string containing all the characters that are considered uppercase letters.
52003
0c028685b44c Remove obsolete stuff from string module docs.
Georg Brandl <georg@python.org>
parents: 50522
diff changeset
91 On most systems this is the string ``'ABCDEFGHIJKLMNOPQRSTUVWXYZ'``. The
0c028685b44c Remove obsolete stuff from string module docs.
Georg Brandl <georg@python.org>
parents: 50522
diff changeset
92 specific value is locale-dependent, and will be updated when
0c028685b44c Remove obsolete stuff from string module docs.
Georg Brandl <georg@python.org>
parents: 50522
diff changeset
93 :func:`locale.setlocale` is called.
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
94
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
95
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
96 .. data:: whitespace
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
97
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
98 A string containing all characters that are considered whitespace. On most
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
99 systems this includes the characters space, tab, linefeed, return, formfeed, and
52003
0c028685b44c Remove obsolete stuff from string module docs.
Georg Brandl <georg@python.org>
parents: 50522
diff changeset
100 vertical tab.
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
101
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
102
47280
65953ae98122 rename the section about new formatting 'new-string-formatting'
Benjamin Peterson <benjamin@python.org>
parents: 46949
diff changeset
103 .. _new-string-formatting:
46949
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
104
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
105 String Formatting
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
106 -----------------
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
107
57773
76523346e20d #7527: use standard versionadded tags.
Georg Brandl <georg@python.org>
parents: 57328
diff changeset
108 .. versionadded:: 2.6
76523346e20d #7527: use standard versionadded tags.
Georg Brandl <georg@python.org>
parents: 57328
diff changeset
109
76523346e20d #7527: use standard versionadded tags.
Georg Brandl <georg@python.org>
parents: 57328
diff changeset
110 The built-in str and unicode classes provide the ability
47280
65953ae98122 rename the section about new formatting 'new-string-formatting'
Benjamin Peterson <benjamin@python.org>
parents: 46949
diff changeset
111 to do complex variable substitutions and value formatting via the
65953ae98122 rename the section about new formatting 'new-string-formatting'
Benjamin Peterson <benjamin@python.org>
parents: 46949
diff changeset
112 :meth:`str.format` method described in :pep:`3101`. The :class:`Formatter`
65953ae98122 rename the section about new formatting 'new-string-formatting'
Benjamin Peterson <benjamin@python.org>
parents: 46949
diff changeset
113 class in the :mod:`string` module allows you to create and customize your own
65953ae98122 rename the section about new formatting 'new-string-formatting'
Benjamin Peterson <benjamin@python.org>
parents: 46949
diff changeset
114 string formatting behaviors using the same implementation as the built-in
46949
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
115 :meth:`format` method.
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
116
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
117 .. class:: Formatter
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
118
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
119 The :class:`Formatter` class has the following public methods:
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
120
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
121 .. method:: format(format_string, *args, *kwargs)
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
122
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
123 :meth:`format` is the primary API method. It takes a format template
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
124 string, and an arbitrary set of positional and keyword argument.
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
125 :meth:`format` is just a wrapper that calls :meth:`vformat`.
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
126
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
127 .. method:: vformat(format_string, args, kwargs)
50522
ee9ced92843a Merged revisions 68133-68134,68141-68142,68145-68146,68148-68149,68159-68162,68166,68171-68174,68179,68195-68196,68210,68214-68215,68217-68222 via svnmerge from
Georg Brandl <georg@python.org>
parents: 49152
diff changeset
128
46949
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
129 This function does the actual work of formatting. It is exposed as a
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
130 separate function for cases where you want to pass in a predefined
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
131 dictionary of arguments, rather than unpacking and repacking the
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
132 dictionary as individual arguments using the ``*args`` and ``**kwds``
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
133 syntax. :meth:`vformat` does the work of breaking up the format template
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
134 string into character data and replacement fields. It calls the various
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
135 methods described below.
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
136
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
137 In addition, the :class:`Formatter` defines a number of methods that are
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
138 intended to be replaced by subclasses:
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
139
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
140 .. method:: parse(format_string)
50522
ee9ced92843a Merged revisions 68133-68134,68141-68142,68145-68146,68148-68149,68159-68162,68166,68171-68174,68179,68195-68196,68210,68214-68215,68217-68222 via svnmerge from
Georg Brandl <georg@python.org>
parents: 49152
diff changeset
141
46949
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
142 Loop over the format_string and return an iterable of tuples
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
143 (*literal_text*, *field_name*, *format_spec*, *conversion*). This is used
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
144 by :meth:`vformat` to break the string in to either literal text, or
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
145 replacement fields.
50522
ee9ced92843a Merged revisions 68133-68134,68141-68142,68145-68146,68148-68149,68159-68162,68166,68171-68174,68179,68195-68196,68210,68214-68215,68217-68222 via svnmerge from
Georg Brandl <georg@python.org>
parents: 49152
diff changeset
146
46949
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
147 The values in the tuple conceptually represent a span of literal text
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
148 followed by a single replacement field. If there is no literal text
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
149 (which can happen if two replacement fields occur consecutively), then
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
150 *literal_text* will be a zero-length string. If there is no replacement
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
151 field, then the values of *field_name*, *format_spec* and *conversion*
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
152 will be ``None``.
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
153
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
154 .. method:: get_field(field_name, args, kwargs)
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
155
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
156 Given *field_name* as returned by :meth:`parse` (see above), convert it to
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
157 an object to be formatted. Returns a tuple (obj, used_key). The default
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
158 version takes strings of the form defined in :pep:`3101`, such as
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
159 "0[name]" or "label.title". *args* and *kwargs* are as passed in to
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
160 :meth:`vformat`. The return value *used_key* has the same meaning as the
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
161 *key* parameter to :meth:`get_value`.
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
162
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
163 .. method:: get_value(key, args, kwargs)
50522
ee9ced92843a Merged revisions 68133-68134,68141-68142,68145-68146,68148-68149,68159-68162,68166,68171-68174,68179,68195-68196,68210,68214-68215,68217-68222 via svnmerge from
Georg Brandl <georg@python.org>
parents: 49152
diff changeset
164
46949
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
165 Retrieve a given field value. The *key* argument will be either an
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
166 integer or a string. If it is an integer, it represents the index of the
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
167 positional argument in *args*; if it is a string, then it represents a
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
168 named argument in *kwargs*.
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
169
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
170 The *args* parameter is set to the list of positional arguments to
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
171 :meth:`vformat`, and the *kwargs* parameter is set to the dictionary of
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
172 keyword arguments.
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
173
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
174 For compound field names, these functions are only called for the first
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
175 component of the field name; Subsequent components are handled through
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
176 normal attribute and indexing operations.
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
177
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
178 So for example, the field expression '0.name' would cause
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
179 :meth:`get_value` to be called with a *key* argument of 0. The ``name``
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
180 attribute will be looked up after :meth:`get_value` returns by calling the
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
181 built-in :func:`getattr` function.
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
182
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
183 If the index or keyword refers to an item that does not exist, then an
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
184 :exc:`IndexError` or :exc:`KeyError` should be raised.
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
185
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
186 .. method:: check_unused_args(used_args, args, kwargs)
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
187
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
188 Implement checking for unused arguments if desired. The arguments to this
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
189 function is the set of all argument keys that were actually referred to in
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
190 the format string (integers for positional arguments, and strings for
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
191 named arguments), and a reference to the *args* and *kwargs* that was
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
192 passed to vformat. The set of unused args can be calculated from these
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
193 parameters. :meth:`check_unused_args` is assumed to throw an exception if
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
194 the check fails.
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
195
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
196 .. method:: format_field(value, format_spec)
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
197
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
198 :meth:`format_field` simply calls the global :func:`format` built-in. The
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
199 method is provided so that subclasses can override it.
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
200
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
201 .. method:: convert_field(value, conversion)
50522
ee9ced92843a Merged revisions 68133-68134,68141-68142,68145-68146,68148-68149,68159-68162,68166,68171-68174,68179,68195-68196,68210,68214-68215,68217-68222 via svnmerge from
Georg Brandl <georg@python.org>
parents: 49152
diff changeset
202
46949
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
203 Converts the value (returned by :meth:`get_field`) given a conversion type
62698
43c04711aacb #9139: Add examples for str.format().
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62696
diff changeset
204 (as in the tuple returned by the :meth:`parse` method). The default
46949
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
205 version understands 'r' (repr) and 's' (str) conversion types.
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
206
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
207
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
208 .. _formatstrings:
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
209
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
210 Format String Syntax
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
211 --------------------
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
212
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
213 The :meth:`str.format` method and the :class:`Formatter` class share the same
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
214 syntax for format strings (although in the case of :class:`Formatter`,
62696
de16a915bd2a Moved period outside paren, where it belongs.
Eric Smith <eric@trueblade.com>
parents: 62533
diff changeset
215 subclasses can define their own format string syntax).
46949
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
216
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
217 Format strings contain "replacement fields" surrounded by curly braces ``{}``.
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
218 Anything that is not contained in braces is considered literal text, which is
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
219 copied unchanged to the output. If you need to include a brace character in the
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
220 literal text, it can be escaped by doubling: ``{{`` and ``}}``.
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
221
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
222 The grammar for a replacement field is as follows:
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
223
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
224 .. productionlist:: sf
55787
ba5b2683c064 #6813: better documentation for numberless string formats.
Georg Brandl <georg@python.org>
parents: 55449
diff changeset
225 replacement_field: "{" [`field_name`] ["!" `conversion`] [":" `format_spec`] "}"
53305
c30681c66b3f Documentation for issue 5237, auto-numbered format fields. Contributed by Terry J. Reedy.
Eric Smith <eric@trueblade.com>
parents: 52379
diff changeset
226 field_name: arg_name ("." `attribute_name` | "[" `element_index` "]")*
62533
815284c9d719 Use designated syntax for optional grammar element.
Georg Brandl <georg@python.org>
parents: 59133
diff changeset
227 arg_name: [`identifier` | `integer`]
46949
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
228 attribute_name: `identifier`
59133
accab4bab634 Issue #7928: Document str.format element_index better.
Eric Smith <eric@trueblade.com>
parents: 59129
diff changeset
229 element_index: `integer` | `index_string`
accab4bab634 Issue #7928: Document str.format element_index better.
Eric Smith <eric@trueblade.com>
parents: 59129
diff changeset
230 index_string: <any source character except "]"> +
46949
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
231 conversion: "r" | "s"
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
232 format_spec: <described in the next section>
50522
ee9ced92843a Merged revisions 68133-68134,68141-68142,68145-68146,68148-68149,68159-68162,68166,68171-68174,68179,68195-68196,68210,68214-68215,68217-68222 via svnmerge from
Georg Brandl <georg@python.org>
parents: 49152
diff changeset
233
55787
ba5b2683c064 #6813: better documentation for numberless string formats.
Georg Brandl <georg@python.org>
parents: 55449
diff changeset
234 In less formal terms, the replacement field can start with a *field_name* that specifies
53305
c30681c66b3f Documentation for issue 5237, auto-numbered format fields. Contributed by Terry J. Reedy.
Eric Smith <eric@trueblade.com>
parents: 52379
diff changeset
235 the object whose value is to be formatted and inserted
c30681c66b3f Documentation for issue 5237, auto-numbered format fields. Contributed by Terry J. Reedy.
Eric Smith <eric@trueblade.com>
parents: 52379
diff changeset
236 into the output instead of the replacement field.
c30681c66b3f Documentation for issue 5237, auto-numbered format fields. Contributed by Terry J. Reedy.
Eric Smith <eric@trueblade.com>
parents: 52379
diff changeset
237 The *field_name* is optionally followed by a *conversion* field, which is
46949
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
238 preceded by an exclamation point ``'!'``, and a *format_spec*, which is preceded
53305
c30681c66b3f Documentation for issue 5237, auto-numbered format fields. Contributed by Terry J. Reedy.
Eric Smith <eric@trueblade.com>
parents: 52379
diff changeset
239 by a colon ``':'``. These specify a non-default format for the replacement value.
46949
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
240
62698
43c04711aacb #9139: Add examples for str.format().
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62696
diff changeset
241 See also the :ref:`formatspec` section.
43c04711aacb #9139: Add examples for str.format().
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62696
diff changeset
242
53305
c30681c66b3f Documentation for issue 5237, auto-numbered format fields. Contributed by Terry J. Reedy.
Eric Smith <eric@trueblade.com>
parents: 52379
diff changeset
243 The *field_name* itself begins with an *arg_name* that is either either a number or a
c30681c66b3f Documentation for issue 5237, auto-numbered format fields. Contributed by Terry J. Reedy.
Eric Smith <eric@trueblade.com>
parents: 52379
diff changeset
244 keyword. If it's a number, it refers to a positional argument, and if it's a keyword,
c30681c66b3f Documentation for issue 5237, auto-numbered format fields. Contributed by Terry J. Reedy.
Eric Smith <eric@trueblade.com>
parents: 52379
diff changeset
245 it refers to a named keyword argument. If the numerical arg_names in a format string
c30681c66b3f Documentation for issue 5237, auto-numbered format fields. Contributed by Terry J. Reedy.
Eric Smith <eric@trueblade.com>
parents: 52379
diff changeset
246 are 0, 1, 2, ... in sequence, they can all be omitted (not just some)
c30681c66b3f Documentation for issue 5237, auto-numbered format fields. Contributed by Terry J. Reedy.
Eric Smith <eric@trueblade.com>
parents: 52379
diff changeset
247 and the numbers 0, 1, 2, ... will be automatically inserted in that order.
c30681c66b3f Documentation for issue 5237, auto-numbered format fields. Contributed by Terry J. Reedy.
Eric Smith <eric@trueblade.com>
parents: 52379
diff changeset
248 The *arg_name* can be followed by any number of index or
46949
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
249 attribute expressions. An expression of the form ``'.name'`` selects the named
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
250 attribute using :func:`getattr`, while an expression of the form ``'[index]'``
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
251 does an index lookup using :func:`__getitem__`.
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
252
62698
43c04711aacb #9139: Add examples for str.format().
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62696
diff changeset
253 .. versionchanged:: 2.7
43c04711aacb #9139: Add examples for str.format().
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62696
diff changeset
254 The positional argument specifiers can be omitted, so ``'{} {}'`` is
43c04711aacb #9139: Add examples for str.format().
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62696
diff changeset
255 equivalent to ``'{0} {1}'``.
43c04711aacb #9139: Add examples for str.format().
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62696
diff changeset
256
46949
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
257 Some simple format string examples::
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
258
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
259 "First, thou shalt count to {0}" # References first positional argument
52379
da456f42ebe7 give os.symlink and os.link() better parameter names #5564
Benjamin Peterson <benjamin@python.org>
parents: 52186
diff changeset
260 "Bring me a {}" # Implicitly references the first positional argument
55787
ba5b2683c064 #6813: better documentation for numberless string formats.
Georg Brandl <georg@python.org>
parents: 55449
diff changeset
261 "From {} to {}" # Same as "From {0} to {1}"
46949
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
262 "My quest is {name}" # References keyword argument 'name'
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
263 "Weight in tons {0.weight}" # 'weight' attribute of first positional arg
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
264 "Units destroyed: {players[0]}" # First element of keyword argument 'players'.
50522
ee9ced92843a Merged revisions 68133-68134,68141-68142,68145-68146,68148-68149,68159-68162,68166,68171-68174,68179,68195-68196,68210,68214-68215,68217-68222 via svnmerge from
Georg Brandl <georg@python.org>
parents: 49152
diff changeset
265
46949
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
266 The *conversion* field causes a type coercion before formatting. Normally, the
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
267 job of formatting a value is done by the :meth:`__format__` method of the value
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
268 itself. However, in some cases it is desirable to force a type to be formatted
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
269 as a string, overriding its own definition of formatting. By converting the
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
270 value to a string before calling :meth:`__format__`, the normal formatting logic
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
271 is bypassed.
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
272
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
273 Two conversion flags are currently supported: ``'!s'`` which calls :func:`str`
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
274 on the value, and ``'!r'`` which calls :func:`repr`.
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
275
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
276 Some examples::
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
277
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
278 "Harold's a clever {0!s}" # Calls str() on the argument first
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
279 "Bring out the holy {name!r}" # Calls repr() on the argument first
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
280
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
281 The *format_spec* field contains a specification of how the value should be
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
282 presented, including such details as field width, alignment, padding, decimal
58915
b641c1aa643e Remove incorrect apostrophe.
Eric Smith <eric@trueblade.com>
parents: 57773
diff changeset
283 precision and so on. Each value type can define its own "formatting
46949
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
284 mini-language" or interpretation of the *format_spec*.
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
285
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
286 Most built-in types support a common formatting mini-language, which is
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
287 described in the next section.
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
288
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
289 A *format_spec* field can also include nested replacement fields within it.
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
290 These nested replacement fields can contain only a field name; conversion flags
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
291 and format specifications are not allowed. The replacement fields within the
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
292 format_spec are substituted before the *format_spec* string is interpreted.
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
293 This allows the formatting of a value to be dynamically specified.
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
294
62698
43c04711aacb #9139: Add examples for str.format().
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62696
diff changeset
295 See the :ref:`formatexamples` section for some examples.
46949
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
296
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
297
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
298 .. _formatspec:
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
299
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
300 Format Specification Mini-Language
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
301 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
302
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
303 "Format specifications" are used within replacement fields contained within a
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
304 format string to define how individual values are presented (see
62698
43c04711aacb #9139: Add examples for str.format().
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62696
diff changeset
305 :ref:`formatstrings`). They can also be passed directly to the built-in
46949
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
306 :func:`format` function. Each formattable type may define how the format
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
307 specification is to be interpreted.
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
308
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
309 Most built-in types implement the following options for format specifications,
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
310 although some of the formatting options are only supported by the numeric types.
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
311
59129
383f40975c75 Issue #5965: Add documentation for parts of format specification language.
Eric Smith <eric@trueblade.com>
parents: 58915
diff changeset
312 A general convention is that an empty format string (``""``) produces
383f40975c75 Issue #5965: Add documentation for parts of format specification language.
Eric Smith <eric@trueblade.com>
parents: 58915
diff changeset
313 the same result as if you had called :func:`str` on the value. A
383f40975c75 Issue #5965: Add documentation for parts of format specification language.
Eric Smith <eric@trueblade.com>
parents: 58915
diff changeset
314 non-empty format string typically modifies the result.
46949
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
315
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
316 The general form of a *standard format specifier* is:
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
317
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
318 .. productionlist:: sf
56401
a6e7ed52df9b Backport r73983: Document the thousands separator.
Andrew M. Kuchling <amk@amk.ca>
parents: 56228
diff changeset
319 format_spec: [[`fill`]`align`][`sign`][#][0][`width`][,][.`precision`][`type`]
46949
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
320 fill: <a character other than '}'>
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
321 align: "<" | ">" | "=" | "^"
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
322 sign: "+" | "-" | " "
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
323 width: `integer`
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
324 precision: `integer`
59129
383f40975c75 Issue #5965: Add documentation for parts of format specification language.
Eric Smith <eric@trueblade.com>
parents: 58915
diff changeset
325 type: "b" | "c" | "d" | "e" | "E" | "f" | "F" | "g" | "G" | "n" | "o" | "s" | "x" | "X" | "%"
50522
ee9ced92843a Merged revisions 68133-68134,68141-68142,68145-68146,68148-68149,68159-68162,68166,68171-68174,68179,68195-68196,68210,68214-68215,68217-68222 via svnmerge from
Georg Brandl <georg@python.org>
parents: 49152
diff changeset
326
46949
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
327 The *fill* character can be any character other than '}' (which signifies the
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
328 end of the field). The presence of a fill character is signaled by the *next*
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
329 character, which must be one of the alignment options. If the second character
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
330 of *format_spec* is not a valid alignment option, then it is assumed that both
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
331 the fill character and the alignment option are absent.
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
332
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
333 The meaning of the various alignment options is as follows:
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
334
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
335 +---------+----------------------------------------------------------+
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
336 | Option | Meaning |
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
337 +=========+==========================================================+
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
338 | ``'<'`` | Forces the field to be left-aligned within the available |
62698
43c04711aacb #9139: Add examples for str.format().
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62696
diff changeset
339 | | space (this is the default). |
46949
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
340 +---------+----------------------------------------------------------+
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
341 | ``'>'`` | Forces the field to be right-aligned within the |
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
342 | | available space. |
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
343 +---------+----------------------------------------------------------+
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
344 | ``'='`` | Forces the padding to be placed after the sign (if any) |
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
345 | | but before the digits. This is used for printing fields |
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
346 | | in the form '+000000120'. This alignment option is only |
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
347 | | valid for numeric types. |
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
348 +---------+----------------------------------------------------------+
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
349 | ``'^'`` | Forces the field to be centered within the available |
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
350 | | space. |
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
351 +---------+----------------------------------------------------------+
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
352
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
353 Note that unless a minimum field width is defined, the field width will always
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
354 be the same size as the data to fill it, so that the alignment option has no
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
355 meaning in this case.
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
356
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
357 The *sign* option is only valid for number types, and can be one of the
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
358 following:
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
359
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
360 +---------+----------------------------------------------------------+
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
361 | Option | Meaning |
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
362 +=========+==========================================================+
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
363 | ``'+'`` | indicates that a sign should be used for both |
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
364 | | positive as well as negative numbers. |
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
365 +---------+----------------------------------------------------------+
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
366 | ``'-'`` | indicates that a sign should be used only for negative |
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
367 | | numbers (this is the default behavior). |
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
368 +---------+----------------------------------------------------------+
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
369 | space | indicates that a leading space should be used on |
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
370 | | positive numbers, and a minus sign on negative numbers. |
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
371 +---------+----------------------------------------------------------+
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
372
49152
0fcd4db23dff fix typo
Benjamin Peterson <benjamin@python.org>
parents: 48015
diff changeset
373 The ``'#'`` option is only valid for integers, and only for binary, octal, or
0fcd4db23dff fix typo
Benjamin Peterson <benjamin@python.org>
parents: 48015
diff changeset
374 hexadecimal output. If present, it specifies that the output will be prefixed
0fcd4db23dff fix typo
Benjamin Peterson <benjamin@python.org>
parents: 48015
diff changeset
375 by ``'0b'``, ``'0o'``, or ``'0x'``, respectively.
47973
3fa44e5e4e2b Complete issue 3083: add alternate (#) formatting to bin, oct, hex in str.format().
Eric Smith <eric@trueblade.com>
parents: 47937
diff changeset
376
56401
a6e7ed52df9b Backport r73983: Document the thousands separator.
Andrew M. Kuchling <amk@amk.ca>
parents: 56228
diff changeset
377 The ``','`` option signals the use of a comma for a thousands separator.
a6e7ed52df9b Backport r73983: Document the thousands separator.
Andrew M. Kuchling <amk@amk.ca>
parents: 56228
diff changeset
378 For a locale aware separator, use the ``'n'`` integer presentation type
a6e7ed52df9b Backport r73983: Document the thousands separator.
Andrew M. Kuchling <amk@amk.ca>
parents: 56228
diff changeset
379 instead.
a6e7ed52df9b Backport r73983: Document the thousands separator.
Andrew M. Kuchling <amk@amk.ca>
parents: 56228
diff changeset
380
62700
fa16acb2ffdd #9139: the thousands separator is new in 2.7. Also add a missing variable in the example.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62698
diff changeset
381 .. versionchanged:: 2.7
fa16acb2ffdd #9139: the thousands separator is new in 2.7. Also add a missing variable in the example.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62698
diff changeset
382 Added the ``','`` option (see also :pep:`378`).
fa16acb2ffdd #9139: the thousands separator is new in 2.7. Also add a missing variable in the example.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62698
diff changeset
383
46949
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
384 *width* is a decimal integer defining the minimum field width. If not
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
385 specified, then the field width will be determined by the content.
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
386
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
387 If the *width* field is preceded by a zero (``'0'``) character, this enables
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
388 zero-padding. This is equivalent to an *alignment* type of ``'='`` and a *fill*
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
389 character of ``'0'``.
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
390
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
391 The *precision* is a decimal number indicating how many digits should be
48015
ac1cd46bf7d5 Document the different meaning of precision for {:f} and {:g}.
Georg Brandl <georg@python.org>
parents: 48003
diff changeset
392 displayed after the decimal point for a floating point value formatted with
ac1cd46bf7d5 Document the different meaning of precision for {:f} and {:g}.
Georg Brandl <georg@python.org>
parents: 48003
diff changeset
393 ``'f'`` and ``'F'``, or before and after the decimal point for a floating point
ac1cd46bf7d5 Document the different meaning of precision for {:f} and {:g}.
Georg Brandl <georg@python.org>
parents: 48003
diff changeset
394 value formatted with ``'g'`` or ``'G'``. For non-number types the field
ac1cd46bf7d5 Document the different meaning of precision for {:f} and {:g}.
Georg Brandl <georg@python.org>
parents: 48003
diff changeset
395 indicates the maximum field size - in other words, how many characters will be
53882
d78037c16225 Fixed wording for formatting integers: precision is not allowed.
Eric Smith <eric@trueblade.com>
parents: 53508
diff changeset
396 used from the field content. The *precision* is not allowed for integer values.
46949
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
397
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
398 Finally, the *type* determines how the data should be presented.
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
399
59129
383f40975c75 Issue #5965: Add documentation for parts of format specification language.
Eric Smith <eric@trueblade.com>
parents: 58915
diff changeset
400 The available string presentation types are:
383f40975c75 Issue #5965: Add documentation for parts of format specification language.
Eric Smith <eric@trueblade.com>
parents: 58915
diff changeset
401
383f40975c75 Issue #5965: Add documentation for parts of format specification language.
Eric Smith <eric@trueblade.com>
parents: 58915
diff changeset
402 +---------+----------------------------------------------------------+
383f40975c75 Issue #5965: Add documentation for parts of format specification language.
Eric Smith <eric@trueblade.com>
parents: 58915
diff changeset
403 | Type | Meaning |
383f40975c75 Issue #5965: Add documentation for parts of format specification language.
Eric Smith <eric@trueblade.com>
parents: 58915
diff changeset
404 +=========+==========================================================+
383f40975c75 Issue #5965: Add documentation for parts of format specification language.
Eric Smith <eric@trueblade.com>
parents: 58915
diff changeset
405 | ``'s'`` | String format. This is the default type for strings and |
383f40975c75 Issue #5965: Add documentation for parts of format specification language.
Eric Smith <eric@trueblade.com>
parents: 58915
diff changeset
406 | | may be omitted. |
383f40975c75 Issue #5965: Add documentation for parts of format specification language.
Eric Smith <eric@trueblade.com>
parents: 58915
diff changeset
407 +---------+----------------------------------------------------------+
383f40975c75 Issue #5965: Add documentation for parts of format specification language.
Eric Smith <eric@trueblade.com>
parents: 58915
diff changeset
408 | None | The same as ``'s'``. |
383f40975c75 Issue #5965: Add documentation for parts of format specification language.
Eric Smith <eric@trueblade.com>
parents: 58915
diff changeset
409 +---------+----------------------------------------------------------+
383f40975c75 Issue #5965: Add documentation for parts of format specification language.
Eric Smith <eric@trueblade.com>
parents: 58915
diff changeset
410
46949
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
411 The available integer presentation types are:
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
412
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
413 +---------+----------------------------------------------------------+
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
414 | Type | Meaning |
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
415 +=========+==========================================================+
47973
3fa44e5e4e2b Complete issue 3083: add alternate (#) formatting to bin, oct, hex in str.format().
Eric Smith <eric@trueblade.com>
parents: 47937
diff changeset
416 | ``'b'`` | Binary format. Outputs the number in base 2. |
46949
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
417 +---------+----------------------------------------------------------+
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
418 | ``'c'`` | Character. Converts the integer to the corresponding |
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
419 | | unicode character before printing. |
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
420 +---------+----------------------------------------------------------+
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
421 | ``'d'`` | Decimal Integer. Outputs the number in base 10. |
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
422 +---------+----------------------------------------------------------+
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
423 | ``'o'`` | Octal format. Outputs the number in base 8. |
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
424 +---------+----------------------------------------------------------+
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
425 | ``'x'`` | Hex format. Outputs the number in base 16, using lower- |
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
426 | | case letters for the digits above 9. |
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
427 +---------+----------------------------------------------------------+
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
428 | ``'X'`` | Hex format. Outputs the number in base 16, using upper- |
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
429 | | case letters for the digits above 9. |
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
430 +---------+----------------------------------------------------------+
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
431 | ``'n'`` | Number. This is the same as ``'d'``, except that it uses |
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
432 | | the current locale setting to insert the appropriate |
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
433 | | number separator characters. |
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
434 +---------+----------------------------------------------------------+
48015
ac1cd46bf7d5 Document the different meaning of precision for {:f} and {:g}.
Georg Brandl <georg@python.org>
parents: 48003
diff changeset
435 | None | The same as ``'d'``. |
46949
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
436 +---------+----------------------------------------------------------+
50522
ee9ced92843a Merged revisions 68133-68134,68141-68142,68145-68146,68148-68149,68159-68162,68166,68171-68174,68179,68195-68196,68210,68214-68215,68217-68222 via svnmerge from
Georg Brandl <georg@python.org>
parents: 49152
diff changeset
437
59129
383f40975c75 Issue #5965: Add documentation for parts of format specification language.
Eric Smith <eric@trueblade.com>
parents: 58915
diff changeset
438 In addition to the above presentation types, integers can be formatted
383f40975c75 Issue #5965: Add documentation for parts of format specification language.
Eric Smith <eric@trueblade.com>
parents: 58915
diff changeset
439 with the floating point presentation types listed below (except
383f40975c75 Issue #5965: Add documentation for parts of format specification language.
Eric Smith <eric@trueblade.com>
parents: 58915
diff changeset
440 ``'n'`` and None). When doing so, :func:`float` is used to convert the
383f40975c75 Issue #5965: Add documentation for parts of format specification language.
Eric Smith <eric@trueblade.com>
parents: 58915
diff changeset
441 integer to a floating point number before formatting.
383f40975c75 Issue #5965: Add documentation for parts of format specification language.
Eric Smith <eric@trueblade.com>
parents: 58915
diff changeset
442
46949
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
443 The available presentation types for floating point and decimal values are:
50522
ee9ced92843a Merged revisions 68133-68134,68141-68142,68145-68146,68148-68149,68159-68162,68166,68171-68174,68179,68195-68196,68210,68214-68215,68217-68222 via svnmerge from
Georg Brandl <georg@python.org>
parents: 49152
diff changeset
444
46949
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
445 +---------+----------------------------------------------------------+
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
446 | Type | Meaning |
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
447 +=========+==========================================================+
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
448 | ``'e'`` | Exponent notation. Prints the number in scientific |
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
449 | | notation using the letter 'e' to indicate the exponent. |
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
450 +---------+----------------------------------------------------------+
48003
5c33009994b4 Backed out r65069, pending fixing it in Windows.
Eric Smith <eric@trueblade.com>
parents: 48001
diff changeset
451 | ``'E'`` | Exponent notation. Same as ``'e'`` except it uses an |
5c33009994b4 Backed out r65069, pending fixing it in Windows.
Eric Smith <eric@trueblade.com>
parents: 48001
diff changeset
452 | | upper case 'E' as the separator character. |
46949
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
453 +---------+----------------------------------------------------------+
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
454 | ``'f'`` | Fixed point. Displays the number as a fixed-point |
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
455 | | number. |
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
456 +---------+----------------------------------------------------------+
48003
5c33009994b4 Backed out r65069, pending fixing it in Windows.
Eric Smith <eric@trueblade.com>
parents: 48001
diff changeset
457 | ``'F'`` | Fixed point. Same as ``'f'``. |
46949
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
458 +---------+----------------------------------------------------------+
56422
96aff2c2a9a1 Issue #7051: Clarify behaviour of 'g' and 'G'-style formatting.
Mark Dickinson <dickinsm@gmail.com>
parents: 56401
diff changeset
459 | ``'g'`` | General format. For a given precision ``p >= 1``, |
96aff2c2a9a1 Issue #7051: Clarify behaviour of 'g' and 'G'-style formatting.
Mark Dickinson <dickinsm@gmail.com>
parents: 56401
diff changeset
460 | | this rounds the number to ``p`` significant digits and |
96aff2c2a9a1 Issue #7051: Clarify behaviour of 'g' and 'G'-style formatting.
Mark Dickinson <dickinsm@gmail.com>
parents: 56401
diff changeset
461 | | then formats the result in either fixed-point format |
96aff2c2a9a1 Issue #7051: Clarify behaviour of 'g' and 'G'-style formatting.
Mark Dickinson <dickinsm@gmail.com>
parents: 56401
diff changeset
462 | | or in scientific notation, depending on its magnitude. |
96aff2c2a9a1 Issue #7051: Clarify behaviour of 'g' and 'G'-style formatting.
Mark Dickinson <dickinsm@gmail.com>
parents: 56401
diff changeset
463 | | |
96aff2c2a9a1 Issue #7051: Clarify behaviour of 'g' and 'G'-style formatting.
Mark Dickinson <dickinsm@gmail.com>
parents: 56401
diff changeset
464 | | The precise rules are as follows: suppose that the |
96aff2c2a9a1 Issue #7051: Clarify behaviour of 'g' and 'G'-style formatting.
Mark Dickinson <dickinsm@gmail.com>
parents: 56401
diff changeset
465 | | result formatted with presentation type ``'e'`` and |
96aff2c2a9a1 Issue #7051: Clarify behaviour of 'g' and 'G'-style formatting.
Mark Dickinson <dickinsm@gmail.com>
parents: 56401
diff changeset
466 | | precision ``p-1`` would have exponent ``exp``. Then |
96aff2c2a9a1 Issue #7051: Clarify behaviour of 'g' and 'G'-style formatting.
Mark Dickinson <dickinsm@gmail.com>
parents: 56401
diff changeset
467 | | if ``-4 <= exp < p``, the number is formatted |
96aff2c2a9a1 Issue #7051: Clarify behaviour of 'g' and 'G'-style formatting.
Mark Dickinson <dickinsm@gmail.com>
parents: 56401
diff changeset
468 | | with presentation type ``'f'`` and precision |
96aff2c2a9a1 Issue #7051: Clarify behaviour of 'g' and 'G'-style formatting.
Mark Dickinson <dickinsm@gmail.com>
parents: 56401
diff changeset
469 | | ``p-1-exp``. Otherwise, the number is formatted |
96aff2c2a9a1 Issue #7051: Clarify behaviour of 'g' and 'G'-style formatting.
Mark Dickinson <dickinsm@gmail.com>
parents: 56401
diff changeset
470 | | with presentation type ``'e'`` and precision ``p-1``. |
96aff2c2a9a1 Issue #7051: Clarify behaviour of 'g' and 'G'-style formatting.
Mark Dickinson <dickinsm@gmail.com>
parents: 56401
diff changeset
471 | | In both cases insignificant trailing zeros are removed |
96aff2c2a9a1 Issue #7051: Clarify behaviour of 'g' and 'G'-style formatting.
Mark Dickinson <dickinsm@gmail.com>
parents: 56401
diff changeset
472 | | from the significand, and the decimal point is also |
96aff2c2a9a1 Issue #7051: Clarify behaviour of 'g' and 'G'-style formatting.
Mark Dickinson <dickinsm@gmail.com>
parents: 56401
diff changeset
473 | | removed if there are no remaining digits following it. |
96aff2c2a9a1 Issue #7051: Clarify behaviour of 'g' and 'G'-style formatting.
Mark Dickinson <dickinsm@gmail.com>
parents: 56401
diff changeset
474 | | |
96aff2c2a9a1 Issue #7051: Clarify behaviour of 'g' and 'G'-style formatting.
Mark Dickinson <dickinsm@gmail.com>
parents: 56401
diff changeset
475 | | Postive and negative infinity, positive and negative |
96aff2c2a9a1 Issue #7051: Clarify behaviour of 'g' and 'G'-style formatting.
Mark Dickinson <dickinsm@gmail.com>
parents: 56401
diff changeset
476 | | zero, and nans, are formatted as ``inf``, ``-inf``, |
96aff2c2a9a1 Issue #7051: Clarify behaviour of 'g' and 'G'-style formatting.
Mark Dickinson <dickinsm@gmail.com>
parents: 56401
diff changeset
477 | | ``0``, ``-0`` and ``nan`` respectively, regardless of |
96aff2c2a9a1 Issue #7051: Clarify behaviour of 'g' and 'G'-style formatting.
Mark Dickinson <dickinsm@gmail.com>
parents: 56401
diff changeset
478 | | the precision. |
96aff2c2a9a1 Issue #7051: Clarify behaviour of 'g' and 'G'-style formatting.
Mark Dickinson <dickinsm@gmail.com>
parents: 56401
diff changeset
479 | | |
96aff2c2a9a1 Issue #7051: Clarify behaviour of 'g' and 'G'-style formatting.
Mark Dickinson <dickinsm@gmail.com>
parents: 56401
diff changeset
480 | | A precision of ``0`` is treated as equivalent to a |
96aff2c2a9a1 Issue #7051: Clarify behaviour of 'g' and 'G'-style formatting.
Mark Dickinson <dickinsm@gmail.com>
parents: 56401
diff changeset
481 | | precision of ``1``. |
46949
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
482 +---------+----------------------------------------------------------+
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
483 | ``'G'`` | General format. Same as ``'g'`` except switches to |
56422
96aff2c2a9a1 Issue #7051: Clarify behaviour of 'g' and 'G'-style formatting.
Mark Dickinson <dickinsm@gmail.com>
parents: 56401
diff changeset
484 | | ``'E'`` if the number gets too large. The |
96aff2c2a9a1 Issue #7051: Clarify behaviour of 'g' and 'G'-style formatting.
Mark Dickinson <dickinsm@gmail.com>
parents: 56401
diff changeset
485 | | representations of infinity and NaN are uppercased, too. |
46949
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
486 +---------+----------------------------------------------------------+
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
487 | ``'n'`` | Number. This is the same as ``'g'``, except that it uses |
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
488 | | the current locale setting to insert the appropriate |
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
489 | | number separator characters. |
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
490 +---------+----------------------------------------------------------+
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
491 | ``'%'`` | Percentage. Multiplies the number by 100 and displays |
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
492 | | in fixed (``'f'``) format, followed by a percent sign. |
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
493 +---------+----------------------------------------------------------+
48015
ac1cd46bf7d5 Document the different meaning of precision for {:f} and {:g}.
Georg Brandl <georg@python.org>
parents: 48003
diff changeset
494 | None | The same as ``'g'``. |
46949
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
495 +---------+----------------------------------------------------------+
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
496
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
497
62698
43c04711aacb #9139: Add examples for str.format().
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62696
diff changeset
498
43c04711aacb #9139: Add examples for str.format().
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62696
diff changeset
499 .. _formatexamples:
43c04711aacb #9139: Add examples for str.format().
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62696
diff changeset
500
43c04711aacb #9139: Add examples for str.format().
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62696
diff changeset
501 Format examples
43c04711aacb #9139: Add examples for str.format().
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62696
diff changeset
502 ^^^^^^^^^^^^^^^
43c04711aacb #9139: Add examples for str.format().
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62696
diff changeset
503
43c04711aacb #9139: Add examples for str.format().
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62696
diff changeset
504 This section contains examples of the new format syntax and comparison with
43c04711aacb #9139: Add examples for str.format().
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62696
diff changeset
505 the old ``%``-formatting.
43c04711aacb #9139: Add examples for str.format().
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62696
diff changeset
506
43c04711aacb #9139: Add examples for str.format().
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62696
diff changeset
507 In most of the cases the syntax is similar to the old ``%``-formatting, with the
43c04711aacb #9139: Add examples for str.format().
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62696
diff changeset
508 addition of the ``{}`` and with ``:`` used instead of ``%``.
43c04711aacb #9139: Add examples for str.format().
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62696
diff changeset
509 For example, ``'%03.2f'`` can be translated to ``'{:03.2f}'``.
43c04711aacb #9139: Add examples for str.format().
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62696
diff changeset
510
43c04711aacb #9139: Add examples for str.format().
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62696
diff changeset
511 The new format syntax also supports new and different options, shown in the
43c04711aacb #9139: Add examples for str.format().
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62696
diff changeset
512 follow examples.
43c04711aacb #9139: Add examples for str.format().
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62696
diff changeset
513
43c04711aacb #9139: Add examples for str.format().
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62696
diff changeset
514 Accessing arguments by position::
43c04711aacb #9139: Add examples for str.format().
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62696
diff changeset
515
43c04711aacb #9139: Add examples for str.format().
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62696
diff changeset
516 >>> '{0}, {1}, {2}'.format('a', 'b', 'c')
43c04711aacb #9139: Add examples for str.format().
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62696
diff changeset
517 'a, b, c'
43c04711aacb #9139: Add examples for str.format().
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62696
diff changeset
518 >>> '{}, {}, {}'.format('a', 'b', 'c') # 2.7+ only
43c04711aacb #9139: Add examples for str.format().
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62696
diff changeset
519 'a, b, c'
43c04711aacb #9139: Add examples for str.format().
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62696
diff changeset
520 >>> '{2}, {1}, {0}'.format('a', 'b', 'c')
43c04711aacb #9139: Add examples for str.format().
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62696
diff changeset
521 'c, b, a'
43c04711aacb #9139: Add examples for str.format().
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62696
diff changeset
522 >>> '{2}, {1}, {0}'.format(*'abc') # unpacking argument sequence
43c04711aacb #9139: Add examples for str.format().
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62696
diff changeset
523 'c, b, a'
43c04711aacb #9139: Add examples for str.format().
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62696
diff changeset
524 >>> '{0}{1}{0}'.format('abra', 'cad') # arguments' indices can be repeated
43c04711aacb #9139: Add examples for str.format().
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62696
diff changeset
525 'abracadabra'
43c04711aacb #9139: Add examples for str.format().
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62696
diff changeset
526
43c04711aacb #9139: Add examples for str.format().
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62696
diff changeset
527 Accessing arguments by name::
43c04711aacb #9139: Add examples for str.format().
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62696
diff changeset
528
43c04711aacb #9139: Add examples for str.format().
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62696
diff changeset
529 >>> 'Coordinates: {latitude}, {longitude}'.format(latitude='37.24N', longitude='-115.81W')
43c04711aacb #9139: Add examples for str.format().
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62696
diff changeset
530 'Coordinates: 37.24N, -115.81W'
43c04711aacb #9139: Add examples for str.format().
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62696
diff changeset
531 >>> coord = {'latitude': '37.24N', 'longitude': '-115.81W'}
43c04711aacb #9139: Add examples for str.format().
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62696
diff changeset
532 >>> 'Coordinates: {latitude}, {longitude}'.format(**coord)
43c04711aacb #9139: Add examples for str.format().
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62696
diff changeset
533 'Coordinates: 37.24N, -115.81W'
43c04711aacb #9139: Add examples for str.format().
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62696
diff changeset
534
43c04711aacb #9139: Add examples for str.format().
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62696
diff changeset
535 Accessing arguments' attributes::
43c04711aacb #9139: Add examples for str.format().
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62696
diff changeset
536
62700
fa16acb2ffdd #9139: the thousands separator is new in 2.7. Also add a missing variable in the example.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62698
diff changeset
537 >>> c = 3-5j
62698
43c04711aacb #9139: Add examples for str.format().
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62696
diff changeset
538 >>> ('The complex number {0} is formed from the real part {0.real} '
43c04711aacb #9139: Add examples for str.format().
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62696
diff changeset
539 ... 'and the imaginary part {0.imag}.').format(c)
43c04711aacb #9139: Add examples for str.format().
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62696
diff changeset
540 'The complex number (3-5j) is formed from the real part 3.0 and the imaginary part -5.0.'
43c04711aacb #9139: Add examples for str.format().
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62696
diff changeset
541 >>> class Point(object):
43c04711aacb #9139: Add examples for str.format().
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62696
diff changeset
542 ... def __init__(self, x, y):
43c04711aacb #9139: Add examples for str.format().
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62696
diff changeset
543 ... self.x, self.y = x, y
43c04711aacb #9139: Add examples for str.format().
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62696
diff changeset
544 ... def __str__(self):
43c04711aacb #9139: Add examples for str.format().
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62696
diff changeset
545 ... return 'Point({self.x}, {self.y})'.format(self=self)
43c04711aacb #9139: Add examples for str.format().
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62696
diff changeset
546 ...
43c04711aacb #9139: Add examples for str.format().
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62696
diff changeset
547 >>> str(Point(4, 2))
43c04711aacb #9139: Add examples for str.format().
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62696
diff changeset
548 'Point(4, 2)'
43c04711aacb #9139: Add examples for str.format().
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62696
diff changeset
549
43c04711aacb #9139: Add examples for str.format().
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62696
diff changeset
550
43c04711aacb #9139: Add examples for str.format().
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62696
diff changeset
551 Accessing arguments' items::
43c04711aacb #9139: Add examples for str.format().
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62696
diff changeset
552
43c04711aacb #9139: Add examples for str.format().
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62696
diff changeset
553 >>> coord = (3, 5)
43c04711aacb #9139: Add examples for str.format().
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62696
diff changeset
554 >>> 'X: {0[0]}; Y: {0[1]}'.format(coord)
43c04711aacb #9139: Add examples for str.format().
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62696
diff changeset
555 'X: 3; Y: 5'
43c04711aacb #9139: Add examples for str.format().
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62696
diff changeset
556
43c04711aacb #9139: Add examples for str.format().
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62696
diff changeset
557 Replacing ``%s`` and ``%r``::
43c04711aacb #9139: Add examples for str.format().
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62696
diff changeset
558
43c04711aacb #9139: Add examples for str.format().
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62696
diff changeset
559 >>> "repr() shows quotes: {!r}; str() doesn't: {!s}".format('test1', 'test2')
43c04711aacb #9139: Add examples for str.format().
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62696
diff changeset
560 "repr() shows quotes: 'test1'; str() doesn't: test2"
43c04711aacb #9139: Add examples for str.format().
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62696
diff changeset
561
43c04711aacb #9139: Add examples for str.format().
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62696
diff changeset
562 Aligning the text and specifying a width::
43c04711aacb #9139: Add examples for str.format().
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62696
diff changeset
563
43c04711aacb #9139: Add examples for str.format().
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62696
diff changeset
564 >>> '{:<30}'.format('left aligned')
43c04711aacb #9139: Add examples for str.format().
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62696
diff changeset
565 'left aligned '
43c04711aacb #9139: Add examples for str.format().
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62696
diff changeset
566 >>> '{:>30}'.format('right aligned')
43c04711aacb #9139: Add examples for str.format().
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62696
diff changeset
567 ' right aligned'
43c04711aacb #9139: Add examples for str.format().
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62696
diff changeset
568 >>> '{:^30}'.format('centered')
43c04711aacb #9139: Add examples for str.format().
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62696
diff changeset
569 ' centered '
43c04711aacb #9139: Add examples for str.format().
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62696
diff changeset
570 >>> '{:*^30}'.format('centered') # use '*' as a fill char
43c04711aacb #9139: Add examples for str.format().
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62696
diff changeset
571 '***********centered***********'
43c04711aacb #9139: Add examples for str.format().
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62696
diff changeset
572
43c04711aacb #9139: Add examples for str.format().
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62696
diff changeset
573 Replacing ``%+f``, ``%-f``, and ``% f`` and specifying a sign::
43c04711aacb #9139: Add examples for str.format().
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62696
diff changeset
574
43c04711aacb #9139: Add examples for str.format().
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62696
diff changeset
575 >>> '{:+f}; {:+f}'.format(3.14, -3.14) # show it always
43c04711aacb #9139: Add examples for str.format().
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62696
diff changeset
576 '+3.140000; -3.140000'
43c04711aacb #9139: Add examples for str.format().
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62696
diff changeset
577 >>> '{: f}; {: f}'.format(3.14, -3.14) # show a space for positive numbers
43c04711aacb #9139: Add examples for str.format().
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62696
diff changeset
578 ' 3.140000; -3.140000'
43c04711aacb #9139: Add examples for str.format().
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62696
diff changeset
579 >>> '{:-f}; {:-f}'.format(3.14, -3.14) # show only the minus -- same as '{:f}; {:f}'
43c04711aacb #9139: Add examples for str.format().
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62696
diff changeset
580 '3.140000; -3.140000'
43c04711aacb #9139: Add examples for str.format().
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62696
diff changeset
581
43c04711aacb #9139: Add examples for str.format().
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62696
diff changeset
582 Replacing ``%x`` and ``%o`` and converting the value to different bases::
43c04711aacb #9139: Add examples for str.format().
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62696
diff changeset
583
43c04711aacb #9139: Add examples for str.format().
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62696
diff changeset
584 >>> # format also supports binary numbers
43c04711aacb #9139: Add examples for str.format().
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62696
diff changeset
585 >>> "int: {0:d}; hex: {0:x}; oct: {0:o}; bin: {0:b}".format(42)
43c04711aacb #9139: Add examples for str.format().
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62696
diff changeset
586 'int: 42; hex: 2a; oct: 52; bin: 101010'
43c04711aacb #9139: Add examples for str.format().
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62696
diff changeset
587 >>> # with 0x, 0o, or 0b as prefix:
43c04711aacb #9139: Add examples for str.format().
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62696
diff changeset
588 >>> "int: {0:d}; hex: {0:#x}; oct: {0:#o}; bin: {0:#b}".format(42)
43c04711aacb #9139: Add examples for str.format().
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62696
diff changeset
589 'int: 42; hex: 0x2a; oct: 0o52; bin: 0b101010'
43c04711aacb #9139: Add examples for str.format().
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62696
diff changeset
590
43c04711aacb #9139: Add examples for str.format().
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62696
diff changeset
591 Using the comma as a thousands separator::
43c04711aacb #9139: Add examples for str.format().
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62696
diff changeset
592
43c04711aacb #9139: Add examples for str.format().
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62696
diff changeset
593 >>> '{:,}'.format(1234567890)
43c04711aacb #9139: Add examples for str.format().
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62696
diff changeset
594 '1,234,567,890'
43c04711aacb #9139: Add examples for str.format().
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62696
diff changeset
595
43c04711aacb #9139: Add examples for str.format().
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62696
diff changeset
596 Expressing a percentage::
43c04711aacb #9139: Add examples for str.format().
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62696
diff changeset
597
43c04711aacb #9139: Add examples for str.format().
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62696
diff changeset
598 >>> points = 19.5
43c04711aacb #9139: Add examples for str.format().
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62696
diff changeset
599 >>> total = 22
43c04711aacb #9139: Add examples for str.format().
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62696
diff changeset
600 >>> 'Correct answers: {:.2%}.'.format(points/total)
43c04711aacb #9139: Add examples for str.format().
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62696
diff changeset
601 'Correct answers: 88.64%'
43c04711aacb #9139: Add examples for str.format().
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62696
diff changeset
602
43c04711aacb #9139: Add examples for str.format().
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62696
diff changeset
603 Using type-specific formatting::
43c04711aacb #9139: Add examples for str.format().
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62696
diff changeset
604
43c04711aacb #9139: Add examples for str.format().
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62696
diff changeset
605 >>> import datetime
43c04711aacb #9139: Add examples for str.format().
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62696
diff changeset
606 >>> d = datetime.datetime(2010, 7, 4, 12, 15, 58)
43c04711aacb #9139: Add examples for str.format().
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62696
diff changeset
607 >>> '{:%Y-%m-%d %H:%M:%S}'.format(d)
43c04711aacb #9139: Add examples for str.format().
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62696
diff changeset
608 '2010-07-04 12:15:58'
43c04711aacb #9139: Add examples for str.format().
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62696
diff changeset
609
43c04711aacb #9139: Add examples for str.format().
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62696
diff changeset
610 Nesting arguments and more complex examples::
43c04711aacb #9139: Add examples for str.format().
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62696
diff changeset
611
43c04711aacb #9139: Add examples for str.format().
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62696
diff changeset
612 >>> for align, text in zip('<^>', ['left', 'center', 'right']):
43c04711aacb #9139: Add examples for str.format().
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62696
diff changeset
613 ... '{0:{align}{fill}16}'.format(text, fill=align, align=align)
43c04711aacb #9139: Add examples for str.format().
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62696
diff changeset
614 ...
43c04711aacb #9139: Add examples for str.format().
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62696
diff changeset
615 'left<<<<<<<<<<<<'
43c04711aacb #9139: Add examples for str.format().
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62696
diff changeset
616 '^^^^^center^^^^^'
43c04711aacb #9139: Add examples for str.format().
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62696
diff changeset
617 '>>>>>>>>>>>right'
43c04711aacb #9139: Add examples for str.format().
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62696
diff changeset
618 >>>
43c04711aacb #9139: Add examples for str.format().
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62696
diff changeset
619 >>> octets = [192, 168, 0, 1]
43c04711aacb #9139: Add examples for str.format().
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62696
diff changeset
620 >>> '{:02X}{:02X}{:02X}{:02X}'.format(*octets)
43c04711aacb #9139: Add examples for str.format().
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62696
diff changeset
621 'C0A80001'
43c04711aacb #9139: Add examples for str.format().
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62696
diff changeset
622 >>> int(_, 16)
43c04711aacb #9139: Add examples for str.format().
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62696
diff changeset
623 3232235521
43c04711aacb #9139: Add examples for str.format().
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62696
diff changeset
624 >>>
43c04711aacb #9139: Add examples for str.format().
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62696
diff changeset
625 >>> width = 5
43c04711aacb #9139: Add examples for str.format().
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62696
diff changeset
626 >>> for num in range(5,12):
43c04711aacb #9139: Add examples for str.format().
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62696
diff changeset
627 ... for base in 'dXob':
43c04711aacb #9139: Add examples for str.format().
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62696
diff changeset
628 ... print '{0:{width}{base}}'.format(num, base=base, width=width),
43c04711aacb #9139: Add examples for str.format().
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62696
diff changeset
629 ... print
43c04711aacb #9139: Add examples for str.format().
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62696
diff changeset
630 ...
43c04711aacb #9139: Add examples for str.format().
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62696
diff changeset
631 5 5 5 101
43c04711aacb #9139: Add examples for str.format().
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62696
diff changeset
632 6 6 6 110
43c04711aacb #9139: Add examples for str.format().
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62696
diff changeset
633 7 7 7 111
43c04711aacb #9139: Add examples for str.format().
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62696
diff changeset
634 8 8 10 1000
43c04711aacb #9139: Add examples for str.format().
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62696
diff changeset
635 9 9 11 1001
43c04711aacb #9139: Add examples for str.format().
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62696
diff changeset
636 10 A 12 1010
43c04711aacb #9139: Add examples for str.format().
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62696
diff changeset
637 11 B 13 1011
43c04711aacb #9139: Add examples for str.format().
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62696
diff changeset
638
43c04711aacb #9139: Add examples for str.format().
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62696
diff changeset
639
43c04711aacb #9139: Add examples for str.format().
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62696
diff changeset
640
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
641 Template strings
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
642 ----------------
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
643
57773
76523346e20d #7527: use standard versionadded tags.
Georg Brandl <georg@python.org>
parents: 57328
diff changeset
644 .. versionadded:: 2.4
76523346e20d #7527: use standard versionadded tags.
Georg Brandl <georg@python.org>
parents: 57328
diff changeset
645
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
646 Templates provide simpler string substitutions as described in :pep:`292`.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
647 Instead of the normal ``%``\ -based substitutions, Templates support ``$``\
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
648 -based substitutions, using the following rules:
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
649
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
650 * ``$$`` is an escape; it is replaced with a single ``$``.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
651
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
652 * ``$identifier`` names a substitution placeholder matching a mapping key of
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
653 ``"identifier"``. By default, ``"identifier"`` must spell a Python
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
654 identifier. The first non-identifier character after the ``$`` character
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
655 terminates this placeholder specification.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
656
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
657 * ``${identifier}`` is equivalent to ``$identifier``. It is required when valid
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
658 identifier characters follow the placeholder but are not part of the
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
659 placeholder, such as ``"${noun}ification"``.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
660
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
661 Any other appearance of ``$`` in the string will result in a :exc:`ValueError`
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
662 being raised.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
663
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
664 The :mod:`string` module provides a :class:`Template` class that implements
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
665 these rules. The methods of :class:`Template` are:
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
666
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
667
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
668 .. class:: Template(template)
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
669
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
670 The constructor takes a single argument which is the template string.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
671
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
672
46555
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46014
diff changeset
673 .. method:: substitute(mapping[, **kws])
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
674
46555
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46014
diff changeset
675 Performs the template substitution, returning a new string. *mapping* is
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46014
diff changeset
676 any dictionary-like object with keys that match the placeholders in the
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46014
diff changeset
677 template. Alternatively, you can provide keyword arguments, where the
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46014
diff changeset
678 keywords are the placeholders. When both *mapping* and *kws* are given
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46014
diff changeset
679 and there are duplicates, the placeholders from *kws* take precedence.
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
680
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
681
46555
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46014
diff changeset
682 .. method:: safe_substitute(mapping[, **kws])
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
683
46555
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46014
diff changeset
684 Like :meth:`substitute`, except that if placeholders are missing from
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46014
diff changeset
685 *mapping* and *kws*, instead of raising a :exc:`KeyError` exception, the
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46014
diff changeset
686 original placeholder will appear in the resulting string intact. Also,
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46014
diff changeset
687 unlike with :meth:`substitute`, any other appearances of the ``$`` will
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46014
diff changeset
688 simply return ``$`` instead of raising :exc:`ValueError`.
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
689
46555
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46014
diff changeset
690 While other exceptions may still occur, this method is called "safe"
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46014
diff changeset
691 because substitutions always tries to return a usable string instead of
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46014
diff changeset
692 raising an exception. In another sense, :meth:`safe_substitute` may be
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46014
diff changeset
693 anything other than safe, since it will silently ignore malformed
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46014
diff changeset
694 templates containing dangling delimiters, unmatched braces, or
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46014
diff changeset
695 placeholders that are not valid Python identifiers.
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
696
57328
41d29c17fd40 Fix markup.
Georg Brandl <georg@python.org>
parents: 56422
diff changeset
697 :class:`Template` instances also provide one public data attribute:
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
698
57328
41d29c17fd40 Fix markup.
Georg Brandl <georg@python.org>
parents: 56422
diff changeset
699 .. attribute:: template
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
700
57328
41d29c17fd40 Fix markup.
Georg Brandl <georg@python.org>
parents: 56422
diff changeset
701 This is the object passed to the constructor's *template* argument. In
41d29c17fd40 Fix markup.
Georg Brandl <georg@python.org>
parents: 56422
diff changeset
702 general, you shouldn't change it, but read-only access is not enforced.
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
703
46014
31cf38bdaac0 Enable doctest running for several other documents.
Georg Brandl <georg@python.org>
parents: 42603
diff changeset
704 Here is an example of how to use a Template:
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
705
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
706 >>> from string import Template
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
707 >>> s = Template('$who likes $what')
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
708 >>> s.substitute(who='tim', what='kung pao')
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
709 'tim likes kung pao'
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
710 >>> d = dict(who='tim')
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
711 >>> Template('Give $who $100').substitute(d)
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
712 Traceback (most recent call last):
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
713 [...]
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
714 ValueError: Invalid placeholder in string: line 1, col 10
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
715 >>> Template('$who likes $what').substitute(d)
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
716 Traceback (most recent call last):
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
717 [...]
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
718 KeyError: 'what'
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
719 >>> Template('$who likes $what').safe_substitute(d)
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
720 'tim likes $what'
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
721
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
722 Advanced usage: you can derive subclasses of :class:`Template` to customize the
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
723 placeholder syntax, delimiter character, or the entire regular expression used
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
724 to parse template strings. To do this, you can override these class attributes:
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
725
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
726 * *delimiter* -- This is the literal string describing a placeholder introducing
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
727 delimiter. The default value ``$``. Note that this should *not* be a regular
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
728 expression, as the implementation will call :meth:`re.escape` on this string as
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
729 needed.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
730
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
731 * *idpattern* -- This is the regular expression describing the pattern for
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
732 non-braced placeholders (the braces will be added automatically as
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
733 appropriate). The default value is the regular expression
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
734 ``[_a-z][_a-z0-9]*``.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
735
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
736 Alternatively, you can provide the entire regular expression pattern by
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
737 overriding the class attribute *pattern*. If you do this, the value must be a
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
738 regular expression object with four named capturing groups. The capturing
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
739 groups correspond to the rules given above, along with the invalid placeholder
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
740 rule:
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
741
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
742 * *escaped* -- This group matches the escape sequence, e.g. ``$$``, in the
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
743 default pattern.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
744
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
745 * *named* -- This group matches the unbraced placeholder name; it should not
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
746 include the delimiter in capturing group.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
747
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
748 * *braced* -- This group matches the brace enclosed placeholder name; it should
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
749 not include either the delimiter or braces in the capturing group.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
750
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
751 * *invalid* -- This group matches any other delimiter pattern (usually a single
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
752 delimiter), and it should appear last in the regular expression.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
753
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
754
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
755 String functions
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
756 ----------------
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
757
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
758 The following functions are available to operate on string and Unicode objects.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
759 They are not available as string methods.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
760
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
761
56228
89fa2641715d #7000: document "sep" in capwords. Add a few tests
Ezio Melotti <ezio.melotti@gmail.com>
parents: 55787
diff changeset
762 .. function:: capwords(s[, sep])
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
763
56228
89fa2641715d #7000: document "sep" in capwords. Add a few tests
Ezio Melotti <ezio.melotti@gmail.com>
parents: 55787
diff changeset
764 Split the argument into words using :meth:`str.split`, capitalize each word
89fa2641715d #7000: document "sep" in capwords. Add a few tests
Ezio Melotti <ezio.melotti@gmail.com>
parents: 55787
diff changeset
765 using :meth:`str.capitalize`, and join the capitalized words using
89fa2641715d #7000: document "sep" in capwords. Add a few tests
Ezio Melotti <ezio.melotti@gmail.com>
parents: 55787
diff changeset
766 :meth:`str.join`. If the optional second argument *sep* is absent
89fa2641715d #7000: document "sep" in capwords. Add a few tests
Ezio Melotti <ezio.melotti@gmail.com>
parents: 55787
diff changeset
767 or ``None``, runs of whitespace characters are replaced by a single space
89fa2641715d #7000: document "sep" in capwords. Add a few tests
Ezio Melotti <ezio.melotti@gmail.com>
parents: 55787
diff changeset
768 and leading and trailing whitespace are removed, otherwise *sep* is used to
89fa2641715d #7000: document "sep" in capwords. Add a few tests
Ezio Melotti <ezio.melotti@gmail.com>
parents: 55787
diff changeset
769 split and join the words.
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
770
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
771
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
772 .. function:: maketrans(from, to)
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
773
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
774 Return a translation table suitable for passing to :func:`translate`, that will
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
775 map each character in *from* into the character at the same position in *to*;
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
776 *from* and *to* must have the same length.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
777
53508
57812944c961 Demote warnings to notices where appropriate, following the goal that as few "red box" warnings
Georg Brandl <georg@python.org>
parents: 53305
diff changeset
778 .. note::
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
779
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
780 Don't use strings derived from :const:`lowercase` and :const:`uppercase` as
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
781 arguments; in some locales, these don't have the same length. For case
52003
0c028685b44c Remove obsolete stuff from string module docs.
Georg Brandl <georg@python.org>
parents: 50522
diff changeset
782 conversions, always use :meth:`str.lower` and :meth:`str.upper`.
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
783
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
784
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
785 Deprecated string functions
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
786 ---------------------------
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
787
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
788 The following list of functions are also defined as methods of string and
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
789 Unicode objects; see section :ref:`string-methods` for more information on
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
790 those. You should consider these functions as deprecated, although they will
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
791 not be removed until Python 3.0. The functions defined in this module are:
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
792
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
793
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
794 .. function:: atof(s)
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
795
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
796 .. deprecated:: 2.0
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
797 Use the :func:`float` built-in function.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
798
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
799 .. index:: builtin: float
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
800
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
801 Convert a string to a floating point number. The string must have the standard
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
802 syntax for a floating point literal in Python, optionally preceded by a sign
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
803 (``+`` or ``-``). Note that this behaves identical to the built-in function
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
804 :func:`float` when passed a string.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
805
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
806 .. note::
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
807
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
808 .. index::
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
809 single: NaN
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
810 single: Infinity
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
811
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
812 When passing in a string, values for NaN and Infinity may be returned, depending
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
813 on the underlying C library. The specific set of strings accepted which cause
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
814 these values to be returned depends entirely on the C library and is known to
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
815 vary.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
816
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
817
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
818 .. function:: atoi(s[, base])
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
819
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
820 .. deprecated:: 2.0
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
821 Use the :func:`int` built-in function.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
822
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
823 .. index:: builtin: eval
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
824
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
825 Convert string *s* to an integer in the given *base*. The string must consist
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
826 of one or more digits, optionally preceded by a sign (``+`` or ``-``). The
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
827 *base* defaults to 10. If it is 0, a default base is chosen depending on the
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
828 leading characters of the string (after stripping the sign): ``0x`` or ``0X``
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
829 means 16, ``0`` means 8, anything else means 10. If *base* is 16, a leading
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
830 ``0x`` or ``0X`` is always accepted, though not required. This behaves
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
831 identically to the built-in function :func:`int` when passed a string. (Also
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
832 note: for a more flexible interpretation of numeric literals, use the built-in
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
833 function :func:`eval`.)
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
834
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
835
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
836 .. function:: atol(s[, base])
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
837
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
838 .. deprecated:: 2.0
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
839 Use the :func:`long` built-in function.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
840
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
841 .. index:: builtin: long
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
842
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
843 Convert string *s* to a long integer in the given *base*. The string must
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
844 consist of one or more digits, optionally preceded by a sign (``+`` or ``-``).
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
845 The *base* argument has the same meaning as for :func:`atoi`. A trailing ``l``
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
846 or ``L`` is not allowed, except if the base is 0. Note that when invoked
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
847 without *base* or with *base* set to 10, this behaves identical to the built-in
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
848 function :func:`long` when passed a string.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
849
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
850
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
851 .. function:: capitalize(word)
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
852
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
853 Return a copy of *word* with only its first character capitalized.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
854
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
855
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
856 .. function:: expandtabs(s[, tabsize])
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
857
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
858 Expand tabs in a string replacing them by one or more spaces, depending on the
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
859 current column and the given tab size. The column number is reset to zero after
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
860 each newline occurring in the string. This doesn't understand other non-printing
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
861 characters or escape sequences. The tab size defaults to 8.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
862
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
863
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
864 .. function:: find(s, sub[, start[,end]])
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
865
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
866 Return the lowest index in *s* where the substring *sub* is found such that
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
867 *sub* is wholly contained in ``s[start:end]``. Return ``-1`` on failure.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
868 Defaults for *start* and *end* and interpretation of negative values is the same
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
869 as for slices.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
870
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
871
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
872 .. function:: rfind(s, sub[, start[, end]])
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
873
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
874 Like :func:`find` but find the highest index.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
875
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
876
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
877 .. function:: index(s, sub[, start[, end]])
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
878
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
879 Like :func:`find` but raise :exc:`ValueError` when the substring is not found.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
880
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
881
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
882 .. function:: rindex(s, sub[, start[, end]])
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
883
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
884 Like :func:`rfind` but raise :exc:`ValueError` when the substring is not found.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
885
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
886
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
887 .. function:: count(s, sub[, start[, end]])
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
888
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
889 Return the number of (non-overlapping) occurrences of substring *sub* in string
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
890 ``s[start:end]``. Defaults for *start* and *end* and interpretation of negative
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
891 values are the same as for slices.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
892
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
893
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
894 .. function:: lower(s)
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
895
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
896 Return a copy of *s*, but with upper case letters converted to lower case.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
897
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
898
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
899 .. function:: split(s[, sep[, maxsplit]])
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
900
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
901 Return a list of the words of the string *s*. If the optional second argument
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
902 *sep* is absent or ``None``, the words are separated by arbitrary strings of
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
903 whitespace characters (space, tab, newline, return, formfeed). If the second
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
904 argument *sep* is present and not ``None``, it specifies a string to be used as
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
905 the word separator. The returned list will then have one more item than the
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
906 number of non-overlapping occurrences of the separator in the string. The
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
907 optional third argument *maxsplit* defaults to 0. If it is nonzero, at most
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
908 *maxsplit* number of splits occur, and the remainder of the string is returned
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
909 as the final element of the list (thus, the list will have at most
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
910 ``maxsplit+1`` elements).
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
911
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
912 The behavior of split on an empty string depends on the value of *sep*. If *sep*
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
913 is not specified, or specified as ``None``, the result will be an empty list.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
914 If *sep* is specified as any string, the result will be a list containing one
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
915 element which is an empty string.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
916
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
917
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
918 .. function:: rsplit(s[, sep[, maxsplit]])
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
919
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
920 Return a list of the words of the string *s*, scanning *s* from the end. To all
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
921 intents and purposes, the resulting list of words is the same as returned by
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
922 :func:`split`, except when the optional third argument *maxsplit* is explicitly
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
923 specified and nonzero. When *maxsplit* is nonzero, at most *maxsplit* number of
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
924 splits -- the *rightmost* ones -- occur, and the remainder of the string is
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
925 returned as the first element of the list (thus, the list will have at most
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
926 ``maxsplit+1`` elements).
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
927
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
928 .. versionadded:: 2.4
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
929
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
930
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
931 .. function:: splitfields(s[, sep[, maxsplit]])
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
932
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
933 This function behaves identically to :func:`split`. (In the past, :func:`split`
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
934 was only used with one argument, while :func:`splitfields` was only used with
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
935 two arguments.)
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
936
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
937
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
938 .. function:: join(words[, sep])
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
939
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
940 Concatenate a list or tuple of words with intervening occurrences of *sep*.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
941 The default value for *sep* is a single space character. It is always true that
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
942 ``string.join(string.split(s, sep), sep)`` equals *s*.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
943
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
944
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
945 .. function:: joinfields(words[, sep])
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
946
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
947 This function behaves identically to :func:`join`. (In the past, :func:`join`
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
948 was only used with one argument, while :func:`joinfields` was only used with two
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
949 arguments.) Note that there is no :meth:`joinfields` method on string objects;
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
950 use the :meth:`join` method instead.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
951
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
952
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
953 .. function:: lstrip(s[, chars])
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
954
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
955 Return a copy of the string with leading characters removed. If *chars* is
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
956 omitted or ``None``, whitespace characters are removed. If given and not
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
957 ``None``, *chars* must be a string; the characters in the string will be
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
958 stripped from the beginning of the string this method is called on.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
959
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
960 .. versionchanged:: 2.2.3
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
961 The *chars* parameter was added. The *chars* parameter cannot be passed in
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
962 earlier 2.2 versions.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
963
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
964
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
965 .. function:: rstrip(s[, chars])
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
966
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
967 Return a copy of the string with trailing characters removed. If *chars* is
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
968 omitted or ``None``, whitespace characters are removed. If given and not
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
969 ``None``, *chars* must be a string; the characters in the string will be
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
970 stripped from the end of the string this method is called on.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
971
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
972 .. versionchanged:: 2.2.3
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
973 The *chars* parameter was added. The *chars* parameter cannot be passed in
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
974 earlier 2.2 versions.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
975
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
976
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
977 .. function:: strip(s[, chars])
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
978
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
979 Return a copy of the string with leading and trailing characters removed. If
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
980 *chars* is omitted or ``None``, whitespace characters are removed. If given and
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
981 not ``None``, *chars* must be a string; the characters in the string will be
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
982 stripped from the both ends of the string this method is called on.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
983
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
984 .. versionchanged:: 2.2.3
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
985 The *chars* parameter was added. The *chars* parameter cannot be passed in
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
986 earlier 2.2 versions.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
987
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
988
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
989 .. function:: swapcase(s)
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
990
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
991 Return a copy of *s*, but with lower case letters converted to upper case and
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
992 vice versa.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
993
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
994
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
995 .. function:: translate(s, table[, deletechars])
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
996
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
997 Delete all characters from *s* that are in *deletechars* (if present), and then
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
998 translate the characters using *table*, which must be a 256-character string
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
999 giving the translation for each character value, indexed by its ordinal. If
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1000 *table* is ``None``, then only the character deletion step is performed.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1001
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1002
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1003 .. function:: upper(s)
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1004
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1005 Return a copy of *s*, but with lower case letters converted to upper case.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1006
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1007
54627
698557cc5dc5 #6238: add fillchar to string.just function family.
Georg Brandl <georg@python.org>
parents: 53882
diff changeset
1008 .. function:: ljust(s, width[, fillchar])
698557cc5dc5 #6238: add fillchar to string.just function family.
Georg Brandl <georg@python.org>
parents: 53882
diff changeset
1009 rjust(s, width[, fillchar])
698557cc5dc5 #6238: add fillchar to string.just function family.
Georg Brandl <georg@python.org>
parents: 53882
diff changeset
1010 center(s, width[, fillchar])
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1011
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1012 These functions respectively left-justify, right-justify and center a string in
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1013 a field of given width. They return a string that is at least *width*
54627
698557cc5dc5 #6238: add fillchar to string.just function family.
Georg Brandl <georg@python.org>
parents: 53882
diff changeset
1014 characters wide, created by padding the string *s* with the character *fillchar*
698557cc5dc5 #6238: add fillchar to string.just function family.
Georg Brandl <georg@python.org>
parents: 53882
diff changeset
1015 (default is a space) until the given width on the right, left or both sides.
698557cc5dc5 #6238: add fillchar to string.just function family.
Georg Brandl <georg@python.org>
parents: 53882
diff changeset
1016 The string is never truncated.
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1017
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1018
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1019 .. function:: zfill(s, width)
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1020
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1021 Pad a numeric string on the left with zero digits until the given width is
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1022 reached. Strings starting with a sign are handled correctly.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1023
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1024
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1025 .. function:: replace(str, old, new[, maxreplace])
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1026
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1027 Return a copy of string *str* with all occurrences of substring *old* replaced
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1028 by *new*. If the optional argument *maxreplace* is given, the first
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1029 *maxreplace* occurrences are replaced.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1030