Mercurial > cpython-lru_cache-weakref

annotate Doc/library/string.rst @ 80661:94de77bd0b4b 2.7

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Issue #16194: document imp.load_dynamic problems when read several extension modules from the same binary object file.
author Andrew Svetlov <andrew.svetlov@gmail.com>
date Thu, 29 Nov 2012 19:51:28 +0200
parents d805982336a0
children 9b3d0bdb9256
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
71952
b5674229d0f9 Backport source links from 3.x.
Éric Araujo <merwok@netwok.org>
parents: 71760
diff changeset
10 **Source code:** :source:`Lib/string.py`
b5674229d0f9 Backport source links from 3.x.
Éric Araujo <merwok@netwok.org>
parents: 71760
diff changeset
11
b5674229d0f9 Backport source links from 3.x.
Éric Araujo <merwok@netwok.org>
parents: 71760
diff changeset
12 --------------
b5674229d0f9 Backport source links from 3.x.
Éric Araujo <merwok@netwok.org>
parents: 71760
diff changeset
13
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
14 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
15 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
16 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
17 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
18 :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
19 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
20 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
21 :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
22 string functions based on regular expressions.
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 String constants
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 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
28
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
29
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
30 .. data:: ascii_letters
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 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
33 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
34
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
35
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
36 .. data:: ascii_lowercase
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 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
39 locale-dependent and will not change.
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
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
42 .. data:: ascii_uppercase
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 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
45 locale-dependent and will not change.
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
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
48 .. data:: digits
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 The string ``'0123456789'``.
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
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
53 .. data:: hexdigits
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 The string ``'0123456789abcdefABCDEF'``.
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
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
58 .. data:: letters
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
59
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
60 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
61 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
62 when :func:`locale.setlocale` is called.
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
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
65 .. data:: lowercase
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
66
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
67 A string containing all the characters that are considered lowercase letters.
52909
f3b26a729e82 Merged revisions 69578-69580,69901,69907,69994,70022-70023,70025-70026,70166,70273,70275,70342,70386-70387,70389-70390,70392-70393,70395,70397,70400,70418 via svnmerge
Georg Brandl <georg@python.org>
parents: 50522
diff changeset
68 On most systems this is the string ``'abcdefghijklmnopqrstuvwxyz'``. The
f3b26a729e82 Merged revisions 69578-69580,69901,69907,69994,70022-70023,70025-70026,70166,70273,70275,70342,70386-70387,70389-70390,70392-70393,70395,70397,70400,70418 via svnmerge
Georg Brandl <georg@python.org>
parents: 50522
diff changeset
69 specific value is locale-dependent, and will be updated when
f3b26a729e82 Merged revisions 69578-69580,69901,69907,69994,70022-70023,70025-70026,70166,70273,70275,70342,70386-70387,70389-70390,70392-70393,70395,70397,70400,70418 via svnmerge
Georg Brandl <georg@python.org>
parents: 50522
diff changeset
70 :func:`locale.setlocale` is called.
42603
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
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
73 .. data:: octdigits
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 The string ``'01234567'``.
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
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
78 .. data:: punctuation
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 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
81 ``C`` locale.
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
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
84 .. data:: printable
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
85
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
86 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
87 :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
88 :const:`whitespace`.
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
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
91 .. data:: uppercase
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
92
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
93 A string containing all the characters that are considered uppercase letters.
52909
f3b26a729e82 Merged revisions 69578-69580,69901,69907,69994,70022-70023,70025-70026,70166,70273,70275,70342,70386-70387,70389-70390,70392-70393,70395,70397,70400,70418 via svnmerge
Georg Brandl <georg@python.org>
parents: 50522
diff changeset
94 On most systems this is the string ``'ABCDEFGHIJKLMNOPQRSTUVWXYZ'``. The
f3b26a729e82 Merged revisions 69578-69580,69901,69907,69994,70022-70023,70025-70026,70166,70273,70275,70342,70386-70387,70389-70390,70392-70393,70395,70397,70400,70418 via svnmerge
Georg Brandl <georg@python.org>
parents: 50522
diff changeset
95 specific value is locale-dependent, and will be updated when
f3b26a729e82 Merged revisions 69578-69580,69901,69907,69994,70022-70023,70025-70026,70166,70273,70275,70342,70386-70387,70389-70390,70392-70393,70395,70397,70400,70418 via svnmerge
Georg Brandl <georg@python.org>
parents: 50522
diff changeset
96 :func:`locale.setlocale` is called.
42603
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
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
99 .. data:: whitespace
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
100
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
101 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
102 systems this includes the characters space, tab, linefeed, return, formfeed, and
52909
f3b26a729e82 Merged revisions 69578-69580,69901,69907,69994,70022-70023,70025-70026,70166,70273,70275,70342,70386-70387,70389-70390,70392-70393,70395,70397,70400,70418 via svnmerge
Georg Brandl <georg@python.org>
parents: 50522
diff changeset
103 vertical tab.
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
104
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
105
47280
65953ae98122 rename the section about new formatting 'new-string-formatting'
Benjamin Peterson <benjamin@python.org>
parents: 46949
diff changeset
106 .. _new-string-formatting:
46949
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
107
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
108 String Formatting
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
109 -----------------
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
110
59831
38e9b9da0164 Merged revisions 76538,76559,76882-76883,76886,76891-76892,76920,76924-76925,77081,77084,77086,77092 via svnmerge from
Georg Brandl <georg@python.org>
parents: 59829
diff changeset
111 .. versionadded:: 2.6
38e9b9da0164 Merged revisions 76538,76559,76882-76883,76886,76891-76892,76920,76924-76925,77081,77084,77086,77092 via svnmerge from
Georg Brandl <georg@python.org>
parents: 59829
diff changeset
112
38e9b9da0164 Merged revisions 76538,76559,76882-76883,76886,76891-76892,76920,76924-76925,77081,77084,77086,77092 via svnmerge from
Georg Brandl <georg@python.org>
parents: 59829
diff changeset
113 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
114 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
115 :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
116 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
117 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
118 :meth:`format` method.
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
119
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
120 .. class:: Formatter
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
121
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
122 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
123
68016
c7c76cfbdb4e Merged revisions 87627,87638,87760,87986,88108,88115,88165,88263,88329,88364-88365,88423-88424 via svnmerge from
Georg Brandl <georg@python.org>
parents: 66465
diff changeset
124 .. method:: format(format_string, *args, **kwargs)
46949
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
125
78660
c793d62cdecc #13579: minimize code base drift for 'a' string.Formatter change.
R David Murray <rdmurray@bitdance.com>
parents: 78621
diff changeset
126 :meth:`format` is the primary API method. It takes a format string and
c793d62cdecc #13579: minimize code base drift for 'a' string.Formatter change.
R David Murray <rdmurray@bitdance.com>
parents: 78621
diff changeset
127 an arbitrary set of positional and keyword arguments.
46949
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
128 :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
129
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
130 .. 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
131
46949
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
132 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
133 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
134 dictionary of arguments, rather than unpacking and repacking the
80602
d805982336a0 #16556: Fix inconsistency between kwds and kwargs. Patch by Taavi Burns.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 79206
diff changeset
135 dictionary as individual arguments using the ``*args`` and ``**kwargs``
78660
c793d62cdecc #13579: minimize code base drift for 'a' string.Formatter change.
R David Murray <rdmurray@bitdance.com>
parents: 78621
diff changeset
136 syntax. :meth:`vformat` does the work of breaking up the format string
c793d62cdecc #13579: minimize code base drift for 'a' string.Formatter change.
R David Murray <rdmurray@bitdance.com>
parents: 78621
diff changeset
137 into character data and replacement fields. It calls the various
46949
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
138 methods described below.
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 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
141 intended to be replaced by subclasses:
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
142
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
143 .. 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
144
46949
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
145 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
146 (*literal_text*, *field_name*, *format_spec*, *conversion*). This is used
66465
2e58126dbad0 Merged revisions 85843,85849-85850,85867,85907,85914,86134,86187,86315-86316,86390,86424-86425,86428 via svnmerge from
Georg Brandl <georg@python.org>
parents: 66024
diff changeset
147 by :meth:`vformat` to break the string into either literal text, or
46949
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
148 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
149
46949
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
150 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
151 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
152 (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
153 *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
154 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
155 will be ``None``.
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
156
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
157 .. method:: get_field(field_name, args, kwargs)
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
158
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
159 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
160 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
161 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
162 "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
163 :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
164 *key* parameter to :meth:`get_value`.
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
165
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
166 .. 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
167
46949
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
168 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
169 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
170 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
171 named argument in *kwargs*.
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
172
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
173 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
174 :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
175 keyword arguments.
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
176
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
177 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
178 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
179 normal attribute and indexing operations.
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
180
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
181 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
182 :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
183 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
184 built-in :func:`getattr` function.
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 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
187 :exc:`IndexError` or :exc:`KeyError` should be raised.
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
188
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
189 .. method:: check_unused_args(used_args, args, kwargs)
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
190
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
191 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
192 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
193 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
194 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
195 passed to vformat. The set of unused args can be calculated from these
65127
ff734f225b47 Merged revisions 82798,82805,83659,83977,84015,84018,84141,84264,84326-84327,84480,84482,84484,84530-84531,84553,84619,84915-84916 via svnmerge from
Georg Brandl <georg@python.org>
parents: 62700
diff changeset
196 parameters. :meth:`check_unused_args` is assumed to raise an exception if
46949
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
197 the check fails.
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
198
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
199 .. method:: format_field(value, format_spec)
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 :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
202 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
203
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
204 .. 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
205
46949
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
206 Converts the value (returned by :meth:`get_field`) given a conversion type
62701
c72fd8a2ae01 Merged revisions 82457,82459 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62699
diff changeset
207 (as in the tuple returned by the :meth:`parse` method). The default
78660
c793d62cdecc #13579: minimize code base drift for 'a' string.Formatter change.
R David Murray <rdmurray@bitdance.com>
parents: 78621
diff changeset
208 version understands 's' (str), 'r' (repr) and 'a' (ascii) conversion
c793d62cdecc #13579: minimize code base drift for 'a' string.Formatter change.
R David Murray <rdmurray@bitdance.com>
parents: 78621
diff changeset
209 types.
46949
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
210
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 .. _formatstrings:
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
213
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
214 Format String Syntax
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
215 --------------------
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 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
218 syntax for format strings (although in the case of :class:`Formatter`,
62699
31443cf4def2 Merged revisions 82455 via svnmerge from
Eric Smith <eric@trueblade.com>
parents: 59831
diff changeset
219 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
220
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
221 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
222 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
223 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
224 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
225
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
226 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
227
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
228 .. productionlist:: sf
55787
ba5b2683c064 #6813: better documentation for numberless string formats.
Georg Brandl <georg@python.org>
parents: 55449
diff changeset
229 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
230 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
231 arg_name: [`identifier` | `integer`]
46949
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
232 attribute_name: `identifier`
59134
ecfe9cfaa334 Merged revisions 78444 via svnmerge from
Eric Smith <eric@trueblade.com>
parents: 59130
diff changeset
233 element_index: `integer` | `index_string`
ecfe9cfaa334 Merged revisions 78444 via svnmerge from
Eric Smith <eric@trueblade.com>
parents: 59130
diff changeset
234 index_string: <any source character except "]"> +
46949
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
235 conversion: "r" | "s"
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
236 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
237
55787
ba5b2683c064 #6813: better documentation for numberless string formats.
Georg Brandl <georg@python.org>
parents: 55449
diff changeset
238 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
239 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
240 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
241 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
242 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
243 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
244
62701
c72fd8a2ae01 Merged revisions 82457,82459 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62699
diff changeset
245 See also the :ref:`formatspec` section.
c72fd8a2ae01 Merged revisions 82457,82459 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62699
diff changeset
246
72984
86e3943d0d5b Remove duplication.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 72199
diff changeset
247 The *field_name* itself begins with an *arg_name* that is either a number or a
53305
c30681c66b3f Documentation for issue 5237, auto-numbered format fields. Contributed by Terry J. Reedy.
Eric Smith <eric@trueblade.com>
parents: 52379
diff changeset
248 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
249 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
250 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
251 and the numbers 0, 1, 2, ... will be automatically inserted in that order.
72199
e75272e9c12d Document that format string don’t support arbitrary dictonary keys.
Éric Araujo <merwok@netwok.org>
parents: 71952
diff changeset
252 Because *arg_name* is not quote-delimited, it is not possible to specify arbitrary
e75272e9c12d Document that format string don’t support arbitrary dictonary keys.
Éric Araujo <merwok@netwok.org>
parents: 71952
diff changeset
253 dictionary keys (e.g., the strings ``'10'`` or ``':-]'``) within a format string.
53305
c30681c66b3f Documentation for issue 5237, auto-numbered format fields. Contributed by Terry J. Reedy.
Eric Smith <eric@trueblade.com>
parents: 52379
diff changeset
254 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
255 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
256 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
257 does an index lookup using :func:`__getitem__`.
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
258
62698
43c04711aacb #9139: Add examples for str.format().
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62696
diff changeset
259 .. versionchanged:: 2.7
43c04711aacb #9139: Add examples for str.format().
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62696
diff changeset
260 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
261 equivalent to ``'{0} {1}'``.
43c04711aacb #9139: Add examples for str.format().
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62696
diff changeset
262
46949
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
263 Some simple format string examples::
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
264
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
265 "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
266 "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
267 "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
268 "My quest is {name}" # References keyword argument 'name'
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
269 "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
270 "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
271
46949
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
272 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
273 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
274 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
275 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
276 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
277 is bypassed.
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
278
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
279 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
280 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
281
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
282 Some examples::
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
283
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
284 "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
285 "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
286
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
287 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
288 presented, including such details as field width, alignment, padding, decimal
58916
465c047ef311 Merged revisions 78198 via svnmerge from
Eric Smith <eric@trueblade.com>
parents: 56822
diff changeset
289 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
290 mini-language" or interpretation of the *format_spec*.
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
291
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
292 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
293 described in the next section.
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
294
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
295 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
296 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
297 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
298 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
299 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
300
62701
c72fd8a2ae01 Merged revisions 82457,82459 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62699
diff changeset
301 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
302
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
303
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
304 .. _formatspec:
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
305
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
306 Format Specification Mini-Language
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
307 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
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 "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
310 format string to define how individual values are presented (see
62701
c72fd8a2ae01 Merged revisions 82457,82459 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62699
diff changeset
311 :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
312 :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
313 specification is to be interpreted.
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
314
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
315 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
316 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
317
59130
bd8357a91d3e Merged revisions 78440 via svnmerge from
Eric Smith <eric@trueblade.com>
parents: 58916
diff changeset
318 A general convention is that an empty format string (``""``) produces
bd8357a91d3e Merged revisions 78440 via svnmerge from
Eric Smith <eric@trueblade.com>
parents: 58916
diff changeset
319 the same result as if you had called :func:`str` on the value. A
bd8357a91d3e Merged revisions 78440 via svnmerge from
Eric Smith <eric@trueblade.com>
parents: 58916
diff changeset
320 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
321
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
322 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
323
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
324 .. productionlist:: sf
56401
a6e7ed52df9b Backport r73983: Document the thousands separator.
Andrew M. Kuchling <amk@amk.ca>
parents: 56228
diff changeset
325 format_spec: [[`fill`]`align`][`sign`][#][0][`width`][,][.`precision`][`type`]
76886
94fb31fb3a9b correctly define what 'fill' could be; thanks to Leland Hulbert from docs@
Sandro Tosi <sandro.tosi@gmail.com>
parents: 76849
diff changeset
326 fill: <a character other than '{' or '}'>
46949
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
327 align: "<" | ">" | "=" | "^"
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
328 sign: "+" | "-" | " "
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
329 width: `integer`
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
330 precision: `integer`
59130
bd8357a91d3e Merged revisions 78440 via svnmerge from
Eric Smith <eric@trueblade.com>
parents: 58916
diff changeset
331 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
332
65127
ff734f225b47 Merged revisions 82798,82805,83659,83977,84015,84018,84141,84264,84326-84327,84480,84482,84484,84530-84531,84553,84619,84915-84916 via svnmerge from
Georg Brandl <georg@python.org>
parents: 62700
diff changeset
333 The *fill* character can be any character other than '{' or '}'. The presence
ff734f225b47 Merged revisions 82798,82805,83659,83977,84015,84018,84141,84264,84326-84327,84480,84482,84484,84530-84531,84553,84619,84915-84916 via svnmerge from
Georg Brandl <georg@python.org>
parents: 62700
diff changeset
334 of a fill character is signaled by the character following it, which must be
ff734f225b47 Merged revisions 82798,82805,83659,83977,84015,84018,84141,84264,84326-84327,84480,84482,84484,84530-84531,84553,84619,84915-84916 via svnmerge from
Georg Brandl <georg@python.org>
parents: 62700
diff changeset
335 one of the alignment options. If the second character of *format_spec* is not
ff734f225b47 Merged revisions 82798,82805,83659,83977,84015,84018,84141,84264,84326-84327,84480,84482,84484,84530-84531,84553,84619,84915-84916 via svnmerge from
Georg Brandl <georg@python.org>
parents: 62700
diff changeset
336 a valid alignment option, then it is assumed that both the fill character and
ff734f225b47 Merged revisions 82798,82805,83659,83977,84015,84018,84141,84264,84326-84327,84480,84482,84484,84530-84531,84553,84619,84915-84916 via svnmerge from
Georg Brandl <georg@python.org>
parents: 62700
diff changeset
337 the alignment option are absent.
46949
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
338
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
339 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
340
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
341 +---------+----------------------------------------------------------+
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
342 | Option | Meaning |
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 field to be left-aligned within the available |
68016
c7c76cfbdb4e Merged revisions 87627,87638,87760,87986,88108,88115,88165,88263,88329,88364-88365,88423-88424 via svnmerge from
Georg Brandl <georg@python.org>
parents: 66465
diff changeset
345 | | space (this is the default for most objects). |
46949
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
346 +---------+----------------------------------------------------------+
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
347 | ``'>'`` | Forces the field to be right-aligned within the |
68016
c7c76cfbdb4e Merged revisions 87627,87638,87760,87986,88108,88115,88165,88263,88329,88364-88365,88423-88424 via svnmerge from
Georg Brandl <georg@python.org>
parents: 66465
diff changeset
348 | | available space (this is the default for numbers). |
46949
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
349 +---------+----------------------------------------------------------+
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
350 | ``'='`` | 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
351 | | 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
352 | | 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
353 | | valid for numeric types. |
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
354 +---------+----------------------------------------------------------+
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
355 | ``'^'`` | 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
356 | | space. |
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
357 +---------+----------------------------------------------------------+
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
358
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
359 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
360 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
361 meaning in this case.
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 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
364 following:
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 +---------+----------------------------------------------------------+
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
367 | Option | Meaning |
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 | ``'+'`` | 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
370 | | positive as well as 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 | ``'-'`` | 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
373 | | numbers (this is the default behavior). |
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
374 +---------+----------------------------------------------------------+
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
375 | 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
376 | | 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
377 +---------+----------------------------------------------------------+
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
378
49152
0fcd4db23dff fix typo
Benjamin Peterson <benjamin@python.org>
parents: 48015
diff changeset
379 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
380 hexadecimal output. If present, it specifies that the output will be prefixed
0fcd4db23dff fix typo
Benjamin Peterson <benjamin@python.org>
parents: 48015
diff changeset
381 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
382
56401
a6e7ed52df9b Backport r73983: Document the thousands separator.
Andrew M. Kuchling <amk@amk.ca>
parents: 56228
diff changeset
383 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
384 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
385 instead.
a6e7ed52df9b Backport r73983: Document the thousands separator.
Andrew M. Kuchling <amk@amk.ca>
parents: 56228
diff changeset
386
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
387 .. 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
388 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
389
46949
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
390 *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
391 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
392
78621
85cd54b2d3a1 Issue 15660: Clarify 0 prefix for width field in str.format doc.
Terry Jan Reedy <tjreedy@udel.edu>
parents: 76886
diff changeset
393 Preceding the *width* field by a zero (``'0'``) character enables
85cd54b2d3a1 Issue 15660: Clarify 0 prefix for width field in str.format doc.
Terry Jan Reedy <tjreedy@udel.edu>
parents: 76886
diff changeset
394 sign-aware zero-padding for numeric types. This is equivalent to a *fill*
85cd54b2d3a1 Issue 15660: Clarify 0 prefix for width field in str.format doc.
Terry Jan Reedy <tjreedy@udel.edu>
parents: 76886
diff changeset
395 character of ``'0'`` with an *alignment* type of ``'='``.
46949
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
396
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
397 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
398 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
399 ``'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
400 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
401 indicates the maximum field size - in other words, how many characters will be
53883
5502ff2fbdd6 Merged revisions 72439 via svnmerge from
Eric Smith <eric@trueblade.com>
parents: 53573
diff changeset
402 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
403
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
404 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
405
59130
bd8357a91d3e Merged revisions 78440 via svnmerge from
Eric Smith <eric@trueblade.com>
parents: 58916
diff changeset
406 The available string presentation types are:
bd8357a91d3e Merged revisions 78440 via svnmerge from
Eric Smith <eric@trueblade.com>
parents: 58916
diff changeset
407
bd8357a91d3e Merged revisions 78440 via svnmerge from
Eric Smith <eric@trueblade.com>
parents: 58916
diff changeset
408 +---------+----------------------------------------------------------+
bd8357a91d3e Merged revisions 78440 via svnmerge from
Eric Smith <eric@trueblade.com>
parents: 58916
diff changeset
409 | Type | Meaning |
bd8357a91d3e Merged revisions 78440 via svnmerge from
Eric Smith <eric@trueblade.com>
parents: 58916
diff changeset
410 +=========+==========================================================+
bd8357a91d3e Merged revisions 78440 via svnmerge from
Eric Smith <eric@trueblade.com>
parents: 58916
diff changeset
411 | ``'s'`` | String format. This is the default type for strings and |
bd8357a91d3e Merged revisions 78440 via svnmerge from
Eric Smith <eric@trueblade.com>
parents: 58916
diff changeset
412 | | may be omitted. |
bd8357a91d3e Merged revisions 78440 via svnmerge from
Eric Smith <eric@trueblade.com>
parents: 58916
diff changeset
413 +---------+----------------------------------------------------------+
bd8357a91d3e Merged revisions 78440 via svnmerge from
Eric Smith <eric@trueblade.com>
parents: 58916
diff changeset
414 | None | The same as ``'s'``. |
bd8357a91d3e Merged revisions 78440 via svnmerge from
Eric Smith <eric@trueblade.com>
parents: 58916
diff changeset
415 +---------+----------------------------------------------------------+
bd8357a91d3e Merged revisions 78440 via svnmerge from
Eric Smith <eric@trueblade.com>
parents: 58916
diff changeset
416
46949
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
417 The available integer presentation types are:
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
418
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
419 +---------+----------------------------------------------------------+
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
420 | Type | Meaning |
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
421 +=========+==========================================================+
47973
3fa44e5e4e2b Complete issue 3083: add alternate (#) formatting to bin, oct, hex in str.format().
Eric Smith <eric@trueblade.com>
parents: 47937
diff changeset
422 | ``'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
423 +---------+----------------------------------------------------------+
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
424 | ``'c'`` | Character. Converts the integer to the corresponding |
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
425 | | unicode character before printing. |
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
426 +---------+----------------------------------------------------------+
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
427 | ``'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
428 +---------+----------------------------------------------------------+
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
429 | ``'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
430 +---------+----------------------------------------------------------+
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
431 | ``'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
432 | | case letters for the digits above 9. |
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
433 +---------+----------------------------------------------------------+
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
434 | ``'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
435 | | case letters for the digits above 9. |
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
436 +---------+----------------------------------------------------------+
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
437 | ``'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
438 | | the current locale setting to insert the appropriate |
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
439 | | number separator characters. |
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
440 +---------+----------------------------------------------------------+
48015
ac1cd46bf7d5 Document the different meaning of precision for {:f} and {:g}.
Georg Brandl <georg@python.org>
parents: 48003
diff changeset
441 | None | The same as ``'d'``. |
46949
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
442 +---------+----------------------------------------------------------+
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
443
59130
bd8357a91d3e Merged revisions 78440 via svnmerge from
Eric Smith <eric@trueblade.com>
parents: 58916
diff changeset
444 In addition to the above presentation types, integers can be formatted
bd8357a91d3e Merged revisions 78440 via svnmerge from
Eric Smith <eric@trueblade.com>
parents: 58916
diff changeset
445 with the floating point presentation types listed below (except
bd8357a91d3e Merged revisions 78440 via svnmerge from
Eric Smith <eric@trueblade.com>
parents: 58916
diff changeset
446 ``'n'`` and None). When doing so, :func:`float` is used to convert the
bd8357a91d3e Merged revisions 78440 via svnmerge from
Eric Smith <eric@trueblade.com>
parents: 58916
diff changeset
447 integer to a floating point number before formatting.
bd8357a91d3e Merged revisions 78440 via svnmerge from
Eric Smith <eric@trueblade.com>
parents: 58916
diff changeset
448
46949
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
449 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
450
46949
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
451 +---------+----------------------------------------------------------+
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
452 | Type | Meaning |
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 | ``'e'`` | Exponent notation. Prints the number in scientific |
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
455 | | 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
456 +---------+----------------------------------------------------------+
48003
5c33009994b4 Backed out r65069, pending fixing it in Windows.
Eric Smith <eric@trueblade.com>
parents: 48001
diff changeset
457 | ``'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
458 | | upper case 'E' as the separator character. |
46949
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
459 +---------+----------------------------------------------------------+
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
460 | ``'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
461 | | number. |
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
462 +---------+----------------------------------------------------------+
48003
5c33009994b4 Backed out r65069, pending fixing it in Windows.
Eric Smith <eric@trueblade.com>
parents: 48001
diff changeset
463 | ``'F'`` | Fixed point. Same as ``'f'``. |
46949
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
464 +---------+----------------------------------------------------------+
56822
c4c429b08a57 Merged revisions 74861-74863,74876,74896,74930,74933,74952-74953,75015,75019,75260-75263,75265-75266,75289 via svnmerge from
Georg Brandl <georg@python.org>
parents: 56820
diff changeset
465 | ``'g'`` | General format. For a given precision ``p >= 1``, |
c4c429b08a57 Merged revisions 74861-74863,74876,74896,74930,74933,74952-74953,75015,75019,75260-75263,75265-75266,75289 via svnmerge from
Georg Brandl <georg@python.org>
parents: 56820
diff changeset
466 | | this rounds the number to ``p`` significant digits and |
c4c429b08a57 Merged revisions 74861-74863,74876,74896,74930,74933,74952-74953,75015,75019,75260-75263,75265-75266,75289 via svnmerge from
Georg Brandl <georg@python.org>
parents: 56820
diff changeset
467 | | then formats the result in either fixed-point format |
c4c429b08a57 Merged revisions 74861-74863,74876,74896,74930,74933,74952-74953,75015,75019,75260-75263,75265-75266,75289 via svnmerge from
Georg Brandl <georg@python.org>
parents: 56820
diff changeset
468 | | or in scientific notation, depending on its magnitude. |
c4c429b08a57 Merged revisions 74861-74863,74876,74896,74930,74933,74952-74953,75015,75019,75260-75263,75265-75266,75289 via svnmerge from
Georg Brandl <georg@python.org>
parents: 56820
diff changeset
469 | | |
c4c429b08a57 Merged revisions 74861-74863,74876,74896,74930,74933,74952-74953,75015,75019,75260-75263,75265-75266,75289 via svnmerge from
Georg Brandl <georg@python.org>
parents: 56820
diff changeset
470 | | The precise rules are as follows: suppose that the |
c4c429b08a57 Merged revisions 74861-74863,74876,74896,74930,74933,74952-74953,75015,75019,75260-75263,75265-75266,75289 via svnmerge from
Georg Brandl <georg@python.org>
parents: 56820
diff changeset
471 | | result formatted with presentation type ``'e'`` and |
c4c429b08a57 Merged revisions 74861-74863,74876,74896,74930,74933,74952-74953,75015,75019,75260-75263,75265-75266,75289 via svnmerge from
Georg Brandl <georg@python.org>
parents: 56820
diff changeset
472 | | precision ``p-1`` would have exponent ``exp``. Then |
c4c429b08a57 Merged revisions 74861-74863,74876,74896,74930,74933,74952-74953,75015,75019,75260-75263,75265-75266,75289 via svnmerge from
Georg Brandl <georg@python.org>
parents: 56820
diff changeset
473 | | if ``-4 <= exp < p``, the number is formatted |
c4c429b08a57 Merged revisions 74861-74863,74876,74896,74930,74933,74952-74953,75015,75019,75260-75263,75265-75266,75289 via svnmerge from
Georg Brandl <georg@python.org>
parents: 56820
diff changeset
474 | | with presentation type ``'f'`` and precision |
c4c429b08a57 Merged revisions 74861-74863,74876,74896,74930,74933,74952-74953,75015,75019,75260-75263,75265-75266,75289 via svnmerge from
Georg Brandl <georg@python.org>
parents: 56820
diff changeset
475 | | ``p-1-exp``. Otherwise, the number is formatted |
c4c429b08a57 Merged revisions 74861-74863,74876,74896,74930,74933,74952-74953,75015,75019,75260-75263,75265-75266,75289 via svnmerge from
Georg Brandl <georg@python.org>
parents: 56820
diff changeset
476 | | with presentation type ``'e'`` and precision ``p-1``. |
c4c429b08a57 Merged revisions 74861-74863,74876,74896,74930,74933,74952-74953,75015,75019,75260-75263,75265-75266,75289 via svnmerge from
Georg Brandl <georg@python.org>
parents: 56820
diff changeset
477 | | In both cases insignificant trailing zeros are removed |
c4c429b08a57 Merged revisions 74861-74863,74876,74896,74930,74933,74952-74953,75015,75019,75260-75263,75265-75266,75289 via svnmerge from
Georg Brandl <georg@python.org>
parents: 56820
diff changeset
478 | | from the significand, and the decimal point is also |
c4c429b08a57 Merged revisions 74861-74863,74876,74896,74930,74933,74952-74953,75015,75019,75260-75263,75265-75266,75289 via svnmerge from
Georg Brandl <georg@python.org>
parents: 56820
diff changeset
479 | | removed if there are no remaining digits following it. |
c4c429b08a57 Merged revisions 74861-74863,74876,74896,74930,74933,74952-74953,75015,75019,75260-75263,75265-75266,75289 via svnmerge from
Georg Brandl <georg@python.org>
parents: 56820
diff changeset
480 | | |
65236
21957b3b0aca Merged revisions 85395 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 65127
diff changeset
481 | | Positive and negative infinity, positive and negative |
56822
c4c429b08a57 Merged revisions 74861-74863,74876,74896,74930,74933,74952-74953,75015,75019,75260-75263,75265-75266,75289 via svnmerge from
Georg Brandl <georg@python.org>
parents: 56820
diff changeset
482 | | zero, and nans, are formatted as ``inf``, ``-inf``, |
c4c429b08a57 Merged revisions 74861-74863,74876,74896,74930,74933,74952-74953,75015,75019,75260-75263,75265-75266,75289 via svnmerge from
Georg Brandl <georg@python.org>
parents: 56820
diff changeset
483 | | ``0``, ``-0`` and ``nan`` respectively, regardless of |
c4c429b08a57 Merged revisions 74861-74863,74876,74896,74930,74933,74952-74953,75015,75019,75260-75263,75265-75266,75289 via svnmerge from
Georg Brandl <georg@python.org>
parents: 56820
diff changeset
484 | | the precision. |
c4c429b08a57 Merged revisions 74861-74863,74876,74896,74930,74933,74952-74953,75015,75019,75260-75263,75265-75266,75289 via svnmerge from
Georg Brandl <georg@python.org>
parents: 56820
diff changeset
485 | | |
c4c429b08a57 Merged revisions 74861-74863,74876,74896,74930,74933,74952-74953,75015,75019,75260-75263,75265-75266,75289 via svnmerge from
Georg Brandl <georg@python.org>
parents: 56820
diff changeset
486 | | A precision of ``0`` is treated as equivalent to a |
c4c429b08a57 Merged revisions 74861-74863,74876,74896,74930,74933,74952-74953,75015,75019,75260-75263,75265-75266,75289 via svnmerge from
Georg Brandl <georg@python.org>
parents: 56820
diff changeset
487 | | precision of ``1``. |
46949
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
488 +---------+----------------------------------------------------------+
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
489 | ``'G'`` | General format. Same as ``'g'`` except switches to |
56822
c4c429b08a57 Merged revisions 74861-74863,74876,74896,74930,74933,74952-74953,75015,75019,75260-75263,75265-75266,75289 via svnmerge from
Georg Brandl <georg@python.org>
parents: 56820
diff changeset
490 | | ``'E'`` if the number gets too large. The |
c4c429b08a57 Merged revisions 74861-74863,74876,74896,74930,74933,74952-74953,75015,75019,75260-75263,75265-75266,75289 via svnmerge from
Georg Brandl <georg@python.org>
parents: 56820
diff changeset
491 | | 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
492 +---------+----------------------------------------------------------+
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
493 | ``'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
494 | | the current locale setting to insert the appropriate |
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
495 | | number separator characters. |
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 | ``'%'`` | Percentage. Multiplies the number by 100 and displays |
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
498 | | 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
499 +---------+----------------------------------------------------------+
48015
ac1cd46bf7d5 Document the different meaning of precision for {:f} and {:g}.
Georg Brandl <georg@python.org>
parents: 48003
diff changeset
500 | None | The same as ``'g'``. |
46949
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
501 +---------+----------------------------------------------------------+
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
502
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
503
62701
c72fd8a2ae01 Merged revisions 82457,82459 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62699
diff changeset
504
c72fd8a2ae01 Merged revisions 82457,82459 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62699
diff changeset
505 .. _formatexamples:
c72fd8a2ae01 Merged revisions 82457,82459 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62699
diff changeset
506
c72fd8a2ae01 Merged revisions 82457,82459 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62699
diff changeset
507 Format examples
c72fd8a2ae01 Merged revisions 82457,82459 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62699
diff changeset
508 ^^^^^^^^^^^^^^^
c72fd8a2ae01 Merged revisions 82457,82459 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62699
diff changeset
509
c72fd8a2ae01 Merged revisions 82457,82459 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62699
diff changeset
510 This section contains examples of the new format syntax and comparison with
c72fd8a2ae01 Merged revisions 82457,82459 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62699
diff changeset
511 the old ``%``-formatting.
c72fd8a2ae01 Merged revisions 82457,82459 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62699
diff changeset
512
c72fd8a2ae01 Merged revisions 82457,82459 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62699
diff changeset
513 In most of the cases the syntax is similar to the old ``%``-formatting, with the
c72fd8a2ae01 Merged revisions 82457,82459 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62699
diff changeset
514 addition of the ``{}`` and with ``:`` used instead of ``%``.
62698
43c04711aacb #9139: Add examples for str.format().
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62696
diff changeset
515 For example, ``'%03.2f'`` can be translated to ``'{:03.2f}'``.
62701
c72fd8a2ae01 Merged revisions 82457,82459 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62699
diff changeset
516
c72fd8a2ae01 Merged revisions 82457,82459 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62699
diff changeset
517 The new format syntax also supports new and different options, shown in the
c72fd8a2ae01 Merged revisions 82457,82459 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62699
diff changeset
518 follow examples.
c72fd8a2ae01 Merged revisions 82457,82459 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62699
diff changeset
519
c72fd8a2ae01 Merged revisions 82457,82459 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62699
diff changeset
520 Accessing arguments by position::
c72fd8a2ae01 Merged revisions 82457,82459 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62699
diff changeset
521
c72fd8a2ae01 Merged revisions 82457,82459 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62699
diff changeset
522 >>> '{0}, {1}, {2}'.format('a', 'b', 'c')
c72fd8a2ae01 Merged revisions 82457,82459 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62699
diff changeset
523 'a, b, c'
62698
43c04711aacb #9139: Add examples for str.format().
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62696
diff changeset
524 >>> '{}, {}, {}'.format('a', 'b', 'c') # 2.7+ only
43c04711aacb #9139: Add examples for str.format().
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62696
diff changeset
525 'a, b, c'
62701
c72fd8a2ae01 Merged revisions 82457,82459 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62699
diff changeset
526 >>> '{2}, {1}, {0}'.format('a', 'b', 'c')
c72fd8a2ae01 Merged revisions 82457,82459 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62699
diff changeset
527 'c, b, a'
c72fd8a2ae01 Merged revisions 82457,82459 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62699
diff changeset
528 >>> '{2}, {1}, {0}'.format(*'abc') # unpacking argument sequence
c72fd8a2ae01 Merged revisions 82457,82459 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62699
diff changeset
529 'c, b, a'
c72fd8a2ae01 Merged revisions 82457,82459 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62699
diff changeset
530 >>> '{0}{1}{0}'.format('abra', 'cad') # arguments' indices can be repeated
c72fd8a2ae01 Merged revisions 82457,82459 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62699
diff changeset
531 'abracadabra'
c72fd8a2ae01 Merged revisions 82457,82459 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62699
diff changeset
532
c72fd8a2ae01 Merged revisions 82457,82459 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62699
diff changeset
533 Accessing arguments by name::
c72fd8a2ae01 Merged revisions 82457,82459 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62699
diff changeset
534
c72fd8a2ae01 Merged revisions 82457,82459 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62699
diff changeset
535 >>> 'Coordinates: {latitude}, {longitude}'.format(latitude='37.24N', longitude='-115.81W')
c72fd8a2ae01 Merged revisions 82457,82459 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62699
diff changeset
536 'Coordinates: 37.24N, -115.81W'
c72fd8a2ae01 Merged revisions 82457,82459 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62699
diff changeset
537 >>> coord = {'latitude': '37.24N', 'longitude': '-115.81W'}
c72fd8a2ae01 Merged revisions 82457,82459 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62699
diff changeset
538 >>> 'Coordinates: {latitude}, {longitude}'.format(**coord)
c72fd8a2ae01 Merged revisions 82457,82459 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62699
diff changeset
539 'Coordinates: 37.24N, -115.81W'
c72fd8a2ae01 Merged revisions 82457,82459 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62699
diff changeset
540
c72fd8a2ae01 Merged revisions 82457,82459 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62699
diff changeset
541 Accessing arguments' attributes::
c72fd8a2ae01 Merged revisions 82457,82459 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62699
diff changeset
542
c72fd8a2ae01 Merged revisions 82457,82459 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62699
diff changeset
543 >>> c = 3-5j
c72fd8a2ae01 Merged revisions 82457,82459 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62699
diff changeset
544 >>> ('The complex number {0} is formed from the real part {0.real} '
c72fd8a2ae01 Merged revisions 82457,82459 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62699
diff changeset
545 ... 'and the imaginary part {0.imag}.').format(c)
c72fd8a2ae01 Merged revisions 82457,82459 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62699
diff changeset
546 'The complex number (3-5j) is formed from the real part 3.0 and the imaginary part -5.0.'
c72fd8a2ae01 Merged revisions 82457,82459 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62699
diff changeset
547 >>> class Point(object):
c72fd8a2ae01 Merged revisions 82457,82459 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62699
diff changeset
548 ... def __init__(self, x, y):
c72fd8a2ae01 Merged revisions 82457,82459 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62699
diff changeset
549 ... self.x, self.y = x, y
c72fd8a2ae01 Merged revisions 82457,82459 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62699
diff changeset
550 ... def __str__(self):
c72fd8a2ae01 Merged revisions 82457,82459 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62699
diff changeset
551 ... return 'Point({self.x}, {self.y})'.format(self=self)
c72fd8a2ae01 Merged revisions 82457,82459 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62699
diff changeset
552 ...
c72fd8a2ae01 Merged revisions 82457,82459 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62699
diff changeset
553 >>> str(Point(4, 2))
c72fd8a2ae01 Merged revisions 82457,82459 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62699
diff changeset
554 'Point(4, 2)'
c72fd8a2ae01 Merged revisions 82457,82459 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62699
diff changeset
555
c72fd8a2ae01 Merged revisions 82457,82459 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62699
diff changeset
556
c72fd8a2ae01 Merged revisions 82457,82459 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62699
diff changeset
557 Accessing arguments' items::
c72fd8a2ae01 Merged revisions 82457,82459 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62699
diff changeset
558
c72fd8a2ae01 Merged revisions 82457,82459 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62699
diff changeset
559 >>> coord = (3, 5)
c72fd8a2ae01 Merged revisions 82457,82459 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62699
diff changeset
560 >>> 'X: {0[0]}; Y: {0[1]}'.format(coord)
c72fd8a2ae01 Merged revisions 82457,82459 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62699
diff changeset
561 'X: 3; Y: 5'
c72fd8a2ae01 Merged revisions 82457,82459 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62699
diff changeset
562
c72fd8a2ae01 Merged revisions 82457,82459 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62699
diff changeset
563 Replacing ``%s`` and ``%r``::
c72fd8a2ae01 Merged revisions 82457,82459 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62699
diff changeset
564
62698
43c04711aacb #9139: Add examples for str.format().
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62696
diff changeset
565 >>> "repr() shows quotes: {!r}; str() doesn't: {!s}".format('test1', 'test2')
62701
c72fd8a2ae01 Merged revisions 82457,82459 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62699
diff changeset
566 "repr() shows quotes: 'test1'; str() doesn't: test2"
c72fd8a2ae01 Merged revisions 82457,82459 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62699
diff changeset
567
c72fd8a2ae01 Merged revisions 82457,82459 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62699
diff changeset
568 Aligning the text and specifying a width::
c72fd8a2ae01 Merged revisions 82457,82459 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62699
diff changeset
569
62698
43c04711aacb #9139: Add examples for str.format().
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62696
diff changeset
570 >>> '{:<30}'.format('left aligned')
62701
c72fd8a2ae01 Merged revisions 82457,82459 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62699
diff changeset
571 'left aligned '
62698
43c04711aacb #9139: Add examples for str.format().
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62696
diff changeset
572 >>> '{:>30}'.format('right aligned')
62701
c72fd8a2ae01 Merged revisions 82457,82459 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62699
diff changeset
573 ' right aligned'
62698
43c04711aacb #9139: Add examples for str.format().
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62696
diff changeset
574 >>> '{:^30}'.format('centered')
62701
c72fd8a2ae01 Merged revisions 82457,82459 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62699
diff changeset
575 ' centered '
62698
43c04711aacb #9139: Add examples for str.format().
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62696
diff changeset
576 >>> '{:*^30}'.format('centered') # use '*' as a fill char
62701
c72fd8a2ae01 Merged revisions 82457,82459 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62699
diff changeset
577 '***********centered***********'
c72fd8a2ae01 Merged revisions 82457,82459 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62699
diff changeset
578
c72fd8a2ae01 Merged revisions 82457,82459 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62699
diff changeset
579 Replacing ``%+f``, ``%-f``, and ``% f`` and specifying a sign::
c72fd8a2ae01 Merged revisions 82457,82459 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62699
diff changeset
580
62698
43c04711aacb #9139: Add examples for str.format().
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62696
diff changeset
581 >>> '{:+f}; {:+f}'.format(3.14, -3.14) # show it always
62701
c72fd8a2ae01 Merged revisions 82457,82459 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62699
diff changeset
582 '+3.140000; -3.140000'
62698
43c04711aacb #9139: Add examples for str.format().
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62696
diff changeset
583 >>> '{: f}; {: f}'.format(3.14, -3.14) # show a space for positive numbers
62701
c72fd8a2ae01 Merged revisions 82457,82459 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62699
diff changeset
584 ' 3.140000; -3.140000'
62698
43c04711aacb #9139: Add examples for str.format().
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62696
diff changeset
585 >>> '{:-f}; {:-f}'.format(3.14, -3.14) # show only the minus -- same as '{:f}; {:f}'
62701
c72fd8a2ae01 Merged revisions 82457,82459 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62699
diff changeset
586 '3.140000; -3.140000'
c72fd8a2ae01 Merged revisions 82457,82459 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62699
diff changeset
587
c72fd8a2ae01 Merged revisions 82457,82459 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62699
diff changeset
588 Replacing ``%x`` and ``%o`` and converting the value to different bases::
c72fd8a2ae01 Merged revisions 82457,82459 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62699
diff changeset
589
c72fd8a2ae01 Merged revisions 82457,82459 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62699
diff changeset
590 >>> # format also supports binary numbers
c72fd8a2ae01 Merged revisions 82457,82459 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62699
diff changeset
591 >>> "int: {0:d}; hex: {0:x}; oct: {0:o}; bin: {0:b}".format(42)
c72fd8a2ae01 Merged revisions 82457,82459 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62699
diff changeset
592 'int: 42; hex: 2a; oct: 52; bin: 101010'
c72fd8a2ae01 Merged revisions 82457,82459 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62699
diff changeset
593 >>> # with 0x, 0o, or 0b as prefix:
c72fd8a2ae01 Merged revisions 82457,82459 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62699
diff changeset
594 >>> "int: {0:d}; hex: {0:#x}; oct: {0:#o}; bin: {0:#b}".format(42)
c72fd8a2ae01 Merged revisions 82457,82459 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62699
diff changeset
595 'int: 42; hex: 0x2a; oct: 0o52; bin: 0b101010'
c72fd8a2ae01 Merged revisions 82457,82459 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62699
diff changeset
596
62698
43c04711aacb #9139: Add examples for str.format().
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62696
diff changeset
597 Using the comma as a thousands separator::
43c04711aacb #9139: Add examples for str.format().
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62696
diff changeset
598
43c04711aacb #9139: Add examples for str.format().
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62696
diff changeset
599 >>> '{:,}'.format(1234567890)
43c04711aacb #9139: Add examples for str.format().
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62696
diff changeset
600 '1,234,567,890'
43c04711aacb #9139: Add examples for str.format().
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62696
diff changeset
601
62701
c72fd8a2ae01 Merged revisions 82457,82459 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62699
diff changeset
602 Expressing a percentage::
c72fd8a2ae01 Merged revisions 82457,82459 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62699
diff changeset
603
c72fd8a2ae01 Merged revisions 82457,82459 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62699
diff changeset
604 >>> points = 19.5
c72fd8a2ae01 Merged revisions 82457,82459 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62699
diff changeset
605 >>> total = 22
74155
a1edc6e4b49c remove spurious dot from string formatting example; thanks to Anthon van der Neut from docs@
Sandro Tosi <sandro.tosi@gmail.com>
parents: 72984
diff changeset
606 >>> 'Correct answers: {:.2%}'.format(points/total)
62701
c72fd8a2ae01 Merged revisions 82457,82459 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62699
diff changeset
607 'Correct answers: 88.64%'
c72fd8a2ae01 Merged revisions 82457,82459 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62699
diff changeset
608
c72fd8a2ae01 Merged revisions 82457,82459 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62699
diff changeset
609 Using type-specific formatting::
c72fd8a2ae01 Merged revisions 82457,82459 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62699
diff changeset
610
c72fd8a2ae01 Merged revisions 82457,82459 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62699
diff changeset
611 >>> import datetime
c72fd8a2ae01 Merged revisions 82457,82459 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62699
diff changeset
612 >>> d = datetime.datetime(2010, 7, 4, 12, 15, 58)
62698
43c04711aacb #9139: Add examples for str.format().
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62696
diff changeset
613 >>> '{:%Y-%m-%d %H:%M:%S}'.format(d)
62701
c72fd8a2ae01 Merged revisions 82457,82459 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62699
diff changeset
614 '2010-07-04 12:15:58'
c72fd8a2ae01 Merged revisions 82457,82459 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62699
diff changeset
615
c72fd8a2ae01 Merged revisions 82457,82459 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62699
diff changeset
616 Nesting arguments and more complex examples::
c72fd8a2ae01 Merged revisions 82457,82459 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62699
diff changeset
617
c72fd8a2ae01 Merged revisions 82457,82459 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62699
diff changeset
618 >>> for align, text in zip('<^>', ['left', 'center', 'right']):
68016
c7c76cfbdb4e Merged revisions 87627,87638,87760,87986,88108,88115,88165,88263,88329,88364-88365,88423-88424 via svnmerge from
Georg Brandl <georg@python.org>
parents: 66465
diff changeset
619 ... '{0:{fill}{align}16}'.format(text, fill=align, align=align)
62701
c72fd8a2ae01 Merged revisions 82457,82459 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62699
diff changeset
620 ...
c72fd8a2ae01 Merged revisions 82457,82459 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62699
diff changeset
621 'left<<<<<<<<<<<<'
c72fd8a2ae01 Merged revisions 82457,82459 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62699
diff changeset
622 '^^^^^center^^^^^'
c72fd8a2ae01 Merged revisions 82457,82459 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62699
diff changeset
623 '>>>>>>>>>>>right'
c72fd8a2ae01 Merged revisions 82457,82459 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62699
diff changeset
624 >>>
c72fd8a2ae01 Merged revisions 82457,82459 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62699
diff changeset
625 >>> octets = [192, 168, 0, 1]
62698
43c04711aacb #9139: Add examples for str.format().
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62696
diff changeset
626 >>> '{:02X}{:02X}{:02X}{:02X}'.format(*octets)
62701
c72fd8a2ae01 Merged revisions 82457,82459 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62699
diff changeset
627 'C0A80001'
c72fd8a2ae01 Merged revisions 82457,82459 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62699
diff changeset
628 >>> int(_, 16)
c72fd8a2ae01 Merged revisions 82457,82459 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62699
diff changeset
629 3232235521
c72fd8a2ae01 Merged revisions 82457,82459 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62699
diff changeset
630 >>>
c72fd8a2ae01 Merged revisions 82457,82459 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62699
diff changeset
631 >>> width = 5
c72fd8a2ae01 Merged revisions 82457,82459 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62699
diff changeset
632 >>> for num in range(5,12):
c72fd8a2ae01 Merged revisions 82457,82459 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62699
diff changeset
633 ... for base in 'dXob':
c72fd8a2ae01 Merged revisions 82457,82459 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62699
diff changeset
634 ... print '{0:{width}{base}}'.format(num, base=base, width=width),
c72fd8a2ae01 Merged revisions 82457,82459 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62699
diff changeset
635 ... print
c72fd8a2ae01 Merged revisions 82457,82459 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62699
diff changeset
636 ...
c72fd8a2ae01 Merged revisions 82457,82459 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62699
diff changeset
637 5 5 5 101
c72fd8a2ae01 Merged revisions 82457,82459 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62699
diff changeset
638 6 6 6 110
c72fd8a2ae01 Merged revisions 82457,82459 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62699
diff changeset
639 7 7 7 111
c72fd8a2ae01 Merged revisions 82457,82459 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62699
diff changeset
640 8 8 10 1000
c72fd8a2ae01 Merged revisions 82457,82459 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62699
diff changeset
641 9 9 11 1001
c72fd8a2ae01 Merged revisions 82457,82459 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62699
diff changeset
642 10 A 12 1010
c72fd8a2ae01 Merged revisions 82457,82459 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62699
diff changeset
643 11 B 13 1011
c72fd8a2ae01 Merged revisions 82457,82459 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62699
diff changeset
644
c72fd8a2ae01 Merged revisions 82457,82459 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62699
diff changeset
645
c72fd8a2ae01 Merged revisions 82457,82459 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 62699
diff changeset
646
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
647 Template strings
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
648 ----------------
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
649
59831
38e9b9da0164 Merged revisions 76538,76559,76882-76883,76886,76891-76892,76920,76924-76925,77081,77084,77086,77092 via svnmerge from
Georg Brandl <georg@python.org>
parents: 59829
diff changeset
650 .. versionadded:: 2.4
38e9b9da0164 Merged revisions 76538,76559,76882-76883,76886,76891-76892,76920,76924-76925,77081,77084,77086,77092 via svnmerge from
Georg Brandl <georg@python.org>
parents: 59829
diff changeset
651
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
652 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
653 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
654 -based substitutions, using the following rules:
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
655
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
656 * ``$$`` 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
657
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
658 * ``$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
659 ``"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
660 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
661 terminates this placeholder specification.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
662
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
663 * ``${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
664 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
665 placeholder, such as ``"${noun}ification"``.
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 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
668 being raised.
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 :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
671 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
672
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
673
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
674 .. class:: Template(template)
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
675
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
676 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
677
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
678
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
679 .. method:: substitute(mapping[, **kws])
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
680
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
681 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
682 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
683 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
684 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
685 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
686
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
687
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
688 .. method:: safe_substitute(mapping[, **kws])
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 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
691 *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
692 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
693 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
694 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
695
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
696 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
697 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
698 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
699 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
700 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
701 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
702
59829
edc92bce4d6e Merged revisions 75952-75953,75955,76105,76143,76223,76259,76326,76376-76377 via svnmerge from
Georg Brandl <georg@python.org>
parents: 59134
diff changeset
703 :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
704
59829
edc92bce4d6e Merged revisions 75952-75953,75955,76105,76143,76223,76259,76326,76376-76377 via svnmerge from
Georg Brandl <georg@python.org>
parents: 59134
diff changeset
705 .. attribute:: template
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
706
59829
edc92bce4d6e Merged revisions 75952-75953,75955,76105,76143,76223,76259,76326,76376-76377 via svnmerge from
Georg Brandl <georg@python.org>
parents: 59134
diff changeset
707 This is the object passed to the constructor's *template* argument. In
edc92bce4d6e Merged revisions 75952-75953,75955,76105,76143,76223,76259,76326,76376-76377 via svnmerge from
Georg Brandl <georg@python.org>
parents: 59134
diff changeset
708 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
709
46014
31cf38bdaac0 Enable doctest running for several other documents.
Georg Brandl <georg@python.org>
parents: 42603
diff changeset
710 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
711
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
712 >>> from string import Template
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
713 >>> s = Template('$who likes $what')
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
714 >>> 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
715 'tim likes kung pao'
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
716 >>> d = dict(who='tim')
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
717 >>> Template('Give $who $100').substitute(d)
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
718 Traceback (most recent call last):
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
719 [...]
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
720 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
721 >>> Template('$who likes $what').substitute(d)
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
722 Traceback (most recent call last):
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
723 [...]
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
724 KeyError: 'what'
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
725 >>> 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
726 'tim likes $what'
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
727
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
728 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
729 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
730 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
731
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
732 * *delimiter* -- This is the literal string describing a placeholder introducing
71760
532cad687332 Fix grammar
Eli Bendersky <eliben@gmail.com>
parents: 68256
diff changeset
733 delimiter. The default value is ``$``. Note that this should *not* be a
532cad687332 Fix grammar
Eli Bendersky <eliben@gmail.com>
parents: 68256
diff changeset
734 regular expression, as the implementation will call :meth:`re.escape` on this
532cad687332 Fix grammar
Eli Bendersky <eliben@gmail.com>
parents: 68256
diff changeset
735 string as needed.
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
736
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
737 * *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
738 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
739 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
740 ``[_a-z][_a-z0-9]*``.
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 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
743 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
744 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
745 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
746 rule:
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 * *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
749 default pattern.
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 * *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
752 include the delimiter in capturing group.
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 * *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
755 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
756
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
757 * *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
758 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
759
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 String functions
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
762 ----------------
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
763
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
764 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
765 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
766
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
767
56229
acbfc69b55f3 Merged revisions 75070 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 53883
diff changeset
768 .. function:: capwords(s[, sep])
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
769
56229
acbfc69b55f3 Merged revisions 75070 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 53883
diff changeset
770 Split the argument into words using :meth:`str.split`, capitalize each word
acbfc69b55f3 Merged revisions 75070 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 53883
diff changeset
771 using :meth:`str.capitalize`, and join the capitalized words using
acbfc69b55f3 Merged revisions 75070 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 53883
diff changeset
772 :meth:`str.join`. If the optional second argument *sep* is absent
acbfc69b55f3 Merged revisions 75070 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 53883
diff changeset
773 or ``None``, runs of whitespace characters are replaced by a single space
acbfc69b55f3 Merged revisions 75070 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 53883
diff changeset
774 and leading and trailing whitespace are removed, otherwise *sep* is used to
acbfc69b55f3 Merged revisions 75070 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 53883
diff changeset
775 split and join the words.
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
776
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
777
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
778 .. function:: maketrans(from, to)
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 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
781 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
782 *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
783
53573
503f0f41f35f Merged revisions 72007-72010,72036-72037 via svnmerge from
Georg Brandl <georg@python.org>
parents: 52909
diff changeset
784 .. note::
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
785
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
786 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
787 arguments; in some locales, these don't have the same length. For case
52909
f3b26a729e82 Merged revisions 69578-69580,69901,69907,69994,70022-70023,70025-70026,70166,70273,70275,70342,70386-70387,70389-70390,70392-70393,70395,70397,70400,70418 via svnmerge
Georg Brandl <georg@python.org>
parents: 50522
diff changeset
788 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
789
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
790
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
791 Deprecated string functions
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 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
795 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
796 those. You should consider these functions as deprecated, although they will
76732
8aab13719c02 Use Python 3 instead of 3.0.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 74155
diff changeset
797 not be removed until Python 3. The functions defined in this module are:
42603
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
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
800 .. function:: atof(s)
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
801
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
802 .. deprecated:: 2.0
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
803 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
804
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
805 .. index:: builtin: float
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
806
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
807 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
808 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
809 (``+`` 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
810 :func:`float` when passed a string.
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 .. note::
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
813
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
814 .. index::
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
815 single: NaN
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
816 single: Infinity
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 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
819 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
820 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
821 vary.
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
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
824 .. function:: atoi(s[, base])
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
825
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
826 .. deprecated:: 2.0
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
827 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
828
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
829 .. index:: builtin: eval
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
830
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
831 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
832 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
833 *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
834 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
835 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
836 ``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
837 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
838 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
839 function :func:`eval`.)
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
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
842 .. function:: atol(s[, base])
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
843
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
844 .. deprecated:: 2.0
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
845 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
846
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
847 .. index:: builtin: long
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
848
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
849 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
850 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
851 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
852 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
853 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
854 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
855
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
856
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
857 .. function:: capitalize(word)
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
858
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
859 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
860
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
861
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
862 .. function:: expandtabs(s[, tabsize])
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 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
865 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
866 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
867 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
868
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
869
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
870 .. function:: find(s, sub[, start[,end]])
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 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
873 *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
874 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
875 as for slices.
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
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
878 .. function:: rfind(s, sub[, start[, end]])
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
879
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
880 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
881
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
882
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
883 .. function:: index(s, sub[, start[, end]])
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
884
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
885 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
886
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
887
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
888 .. function:: rindex(s, sub[, start[, end]])
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
889
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
890 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
891
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 .. function:: count(s, sub[, start[, end]])
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
894
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
895 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
896 ``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
897 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
898
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
899
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
900 .. function:: lower(s)
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
901
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
902 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
903
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
904
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
905 .. function:: split(s[, sep[, maxsplit]])
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
906
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
907 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
908 *sep* is absent or ``None``, the words are separated by arbitrary strings of
76849
d3ddbad31b3e #14763: fix documentation for string.split/rsplit.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 76732
diff changeset
909 whitespace characters (space, tab, newline, return, formfeed). If the second
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
910 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
911 the word separator. The returned list will then have one more item than the
76849
d3ddbad31b3e #14763: fix documentation for string.split/rsplit.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 76732
diff changeset
912 number of non-overlapping occurrences of the separator in the string.
d3ddbad31b3e #14763: fix documentation for string.split/rsplit.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 76732
diff changeset
913 If *maxsplit* is given, at most *maxsplit* number of splits occur, and the
d3ddbad31b3e #14763: fix documentation for string.split/rsplit.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 76732
diff changeset
914 remainder of the string is returned as the final element of the list (thus,
d3ddbad31b3e #14763: fix documentation for string.split/rsplit.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 76732
diff changeset
915 the list will have at most ``maxsplit+1`` elements). If *maxsplit* is not
d3ddbad31b3e #14763: fix documentation for string.split/rsplit.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 76732
diff changeset
916 specified or ``-1``, then there is no limit on the number of splits (all
d3ddbad31b3e #14763: fix documentation for string.split/rsplit.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 76732
diff changeset
917 possible splits are made).
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
918
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
919 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
920 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
921 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
922 element which is an empty string.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
923
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
924
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
925 .. function:: rsplit(s[, sep[, maxsplit]])
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
926
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
927 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
928 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
929 :func:`split`, except when the optional third argument *maxsplit* is explicitly
76849
d3ddbad31b3e #14763: fix documentation for string.split/rsplit.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 76732
diff changeset
930 specified and nonzero. If *maxsplit* is given, at most *maxsplit* number of
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
931 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
932 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
933 ``maxsplit+1`` elements).
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
934
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
935 .. versionadded:: 2.4
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:: splitfields(s[, sep[, maxsplit]])
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 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
941 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
942 two arguments.)
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:: join(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 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
948 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
949 ``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
950
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 .. function:: joinfields(words[, sep])
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
953
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
954 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
955 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
956 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
957 use the :meth:`join` method instead.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
958
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 .. function:: lstrip(s[, chars])
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
961
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
962 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
963 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
964 ``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
965 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
966
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
967 .. versionchanged:: 2.2.3
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
968 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
969 earlier 2.2 versions.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
970
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 .. function:: rstrip(s[, chars])
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
973
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
974 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
975 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
976 ``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
977 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
978
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
979 .. versionchanged:: 2.2.3
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
980 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
981 earlier 2.2 versions.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
982
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 .. function:: strip(s[, chars])
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
985
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
986 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
987 *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
988 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
989 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
990
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
991 .. versionchanged:: 2.2.3
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
992 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
993 earlier 2.2 versions.
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
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
996 .. function:: swapcase(s)
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
997
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
998 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
999 vice versa.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1000
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 .. function:: translate(s, table[, deletechars])
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1003
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1004 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
1005 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
1006 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
1007 *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
1008
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1009
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1010 .. function:: upper(s)
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 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
1013
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1014
56814
127d623396ab Merged revisions 73286,73294,73296,73459,73462-73463,73544,73576-73577,73595-73596,73693-73694,73704-73705,73707,73713,73937-73940,73945,73951,73979 via svnmerge from
Georg Brandl <georg@python.org>
parents: 56807
diff changeset
1015 .. function:: ljust(s, width[, fillchar])
127d623396ab Merged revisions 73286,73294,73296,73459,73462-73463,73544,73576-73577,73595-73596,73693-73694,73704-73705,73707,73713,73937-73940,73945,73951,73979 via svnmerge from
Georg Brandl <georg@python.org>
parents: 56807
diff changeset
1016 rjust(s, width[, fillchar])
127d623396ab Merged revisions 73286,73294,73296,73459,73462-73463,73544,73576-73577,73595-73596,73693-73694,73704-73705,73707,73713,73937-73940,73945,73951,73979 via svnmerge from
Georg Brandl <georg@python.org>
parents: 56807
diff changeset
1017 center(s, width[, fillchar])
42603
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 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
1020 a field of given width. They return a string that is at least *width*
56814
127d623396ab Merged revisions 73286,73294,73296,73459,73462-73463,73544,73576-73577,73595-73596,73693-73694,73704-73705,73707,73713,73937-73940,73945,73951,73979 via svnmerge from
Georg Brandl <georg@python.org>
parents: 56807
diff changeset
1021 characters wide, created by padding the string *s* with the character *fillchar*
127d623396ab Merged revisions 73286,73294,73296,73459,73462-73463,73544,73576-73577,73595-73596,73693-73694,73704-73705,73707,73713,73937-73940,73945,73951,73979 via svnmerge from
Georg Brandl <georg@python.org>
parents: 56807
diff changeset
1022 (default is a space) until the given width on the right, left or both sides.
127d623396ab Merged revisions 73286,73294,73296,73459,73462-73463,73544,73576-73577,73595-73596,73693-73694,73704-73705,73707,73713,73937-73940,73945,73951,73979 via svnmerge from
Georg Brandl <georg@python.org>
parents: 56807
diff changeset
1023 The string is never truncated.
42603
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
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1026 .. function:: zfill(s, width)
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1027
79206
2d359ef01dd5 Update docs for string.zfill
Andrew Svetlov <andrew.svetlov@gmail.com>
parents: 79205
diff changeset
1028 Pad a numeric string *s* on the left with zero digits until the
2d359ef01dd5 Update docs for string.zfill
Andrew Svetlov <andrew.svetlov@gmail.com>
parents: 79205
diff changeset
1029 given *width* is reached. Strings starting with a sign are handled
2d359ef01dd5 Update docs for string.zfill
Andrew Svetlov <andrew.svetlov@gmail.com>
parents: 79205
diff changeset
1030 correctly.
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1031
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1032
79205
c34a177d1f38 Update documentation for string.replace. Thanks to docs@
Andrew Svetlov <andrew.svetlov@gmail.com>
parents: 78660
diff changeset
1033 .. function:: replace(s, old, new[, maxreplace])
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1034
79205
c34a177d1f38 Update documentation for string.replace. Thanks to docs@
Andrew Svetlov <andrew.svetlov@gmail.com>
parents: 78660
diff changeset
1035 Return a copy of string *s* with all occurrences of substring *old* replaced
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1036 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
1037 *maxreplace* occurrences are replaced.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1038