Mercurial > cpython-lru_cache-weakref

annotate Doc/lib/libstdtypes.tex @ 26261:205fbf1bd075 2.2

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Note that str.zfill() and the optional argument to str.strip(), .lstrip(), and .rstrip() were all added in 2.2.2. ;-( Closes SF bug #639170.
author Fred Drake <fdrake@acm.org>
date Sat, 16 Nov 2002 00:45:14 +0000
parents 6ea9eef99108
children 0c85a947e2c0
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
9083
bc41e86c938c Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9034
diff changeset
1 \section{Built-in Types \label{types}}
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
2
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
3 The following sections describe the standard types that are built into
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
4 the interpreter. These are the numeric types, sequence types, and
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
5 several others, including types themselves. There is no explicit
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
6 Boolean type; use integers instead.
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
7 \indexii{built-in}{types}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
8 \indexii{Boolean}{type}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
9
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
10 Some operations are supported by several object types; in particular,
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
11 all objects can be compared, tested for truth value, and converted to
9558
fa867d8ee7eb Remove some remaining {\rm ...} constructs.
Fred Drake <fdrake@acm.org>
parents: 9523
diff changeset
12 a string (with the \code{`\textrm{\ldots}`} notation). The latter
fa867d8ee7eb Remove some remaining {\rm ...} constructs.
Fred Drake <fdrake@acm.org>
parents: 9523
diff changeset
13 conversion is implicitly used when an object is written by the
fa867d8ee7eb Remove some remaining {\rm ...} constructs.
Fred Drake <fdrake@acm.org>
parents: 9523
diff changeset
14 \keyword{print}\stindex{print} statement.
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
15
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
16
9083
bc41e86c938c Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9034
diff changeset
17 \subsection{Truth Value Testing \label{truth}}
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
18
9558
fa867d8ee7eb Remove some remaining {\rm ...} constructs.
Fred Drake <fdrake@acm.org>
parents: 9523
diff changeset
19 Any object can be tested for truth value, for use in an \keyword{if} or
fa867d8ee7eb Remove some remaining {\rm ...} constructs.
Fred Drake <fdrake@acm.org>
parents: 9523
diff changeset
20 \keyword{while} condition or as operand of the Boolean operations below.
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
21 The following values are considered false:
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
22 \stindex{if}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
23 \stindex{while}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
24 \indexii{truth}{value}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
25 \indexii{Boolean}{operations}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
26 \index{false}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
27
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
28 \begin{itemize}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
29
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
30 \item \code{None}
24632
f6a97cd3ba24 Clarify that the bool instances are acceptable return values from
Fred Drake <fdrake@acm.org>
parents: 24228
diff changeset
31 \withsubitem{(Built-in object)}{\ttindex{None}}
f6a97cd3ba24 Clarify that the bool instances are acceptable return values from
Fred Drake <fdrake@acm.org>
parents: 24228
diff changeset
32
f6a97cd3ba24 Clarify that the bool instances are acceptable return values from
Fred Drake <fdrake@acm.org>
parents: 24228
diff changeset
33 \item \code{False}
f6a97cd3ba24 Clarify that the bool instances are acceptable return values from
Fred Drake <fdrake@acm.org>
parents: 24228
diff changeset
34 \withsubitem{(Built-in object)}{\ttindex{False}}
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
35
12223
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11463
diff changeset
36 \item zero of any numeric type, for example, \code{0}, \code{0L},
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11463
diff changeset
37 \code{0.0}, \code{0j}.
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
38
12223
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11463
diff changeset
39 \item any empty sequence, for example, \code{''}, \code{()}, \code{[]}.
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
40
12223
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11463
diff changeset
41 \item any empty mapping, for example, \code{\{\}}.
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
42
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
43 \item instances of user-defined classes, if the class defines a
24632
f6a97cd3ba24 Clarify that the bool instances are acceptable return values from
Fred Drake <fdrake@acm.org>
parents: 24228
diff changeset
44 \method{__nonzero__()} or \method{__len__()} method, when that
f6a97cd3ba24 Clarify that the bool instances are acceptable return values from
Fred Drake <fdrake@acm.org>
parents: 24228
diff changeset
45 method returns the integer zero or \class{bool} value
f6a97cd3ba24 Clarify that the bool instances are acceptable return values from
Fred Drake <fdrake@acm.org>
parents: 24228
diff changeset
46 \code{False}.\footnote{Additional
24228
5b66e63d7abb Clarify the return value of __nonzero__(): It *must* be an integer.
Fred Drake <fdrake@acm.org>
parents: 23461
diff changeset
47 information on these special methods may be found in the
5b66e63d7abb Clarify the return value of __nonzero__(): It *must* be an integer.
Fred Drake <fdrake@acm.org>
parents: 23461
diff changeset
48 \citetitle[../ref/ref.html]{Python Reference Manual}.}
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
49
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
50 \end{itemize}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
51
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
52 All other values are considered true --- so objects of many types are
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
53 always true.
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
54 \index{true}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
55
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
56 Operations and built-in functions that have a Boolean result always
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
57 return \code{0} for false and \code{1} for true, unless otherwise
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
58 stated. (Important exception: the Boolean operations
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
59 \samp{or}\opindex{or} and \samp{and}\opindex{and} always return one of
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
60 their operands.)
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
61
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
62
9083
bc41e86c938c Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9034
diff changeset
63 \subsection{Boolean Operations \label{boolean}}
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
64
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
65 These are the Boolean operations, ordered by ascending priority:
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
66 \indexii{Boolean}{operations}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
67
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
68 \begin{tableiii}{c|l|c}{code}{Operation}{Result}{Notes}
16285
15e0c10092bb Massively improved documentation for string formatting operations,
Fred Drake <fdrake@acm.org>
parents: 15926
diff changeset
69 \lineiii{\var{x} or \var{y}}
15e0c10092bb Massively improved documentation for string formatting operations,
Fred Drake <fdrake@acm.org>
parents: 15926
diff changeset
70 {if \var{x} is false, then \var{y}, else \var{x}}{(1)}
15e0c10092bb Massively improved documentation for string formatting operations,
Fred Drake <fdrake@acm.org>
parents: 15926
diff changeset
71 \lineiii{\var{x} and \var{y}}
15e0c10092bb Massively improved documentation for string formatting operations,
Fred Drake <fdrake@acm.org>
parents: 15926
diff changeset
72 {if \var{x} is false, then \var{x}, else \var{y}}{(1)}
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
73 \hline
16285
15e0c10092bb Massively improved documentation for string formatting operations,
Fred Drake <fdrake@acm.org>
parents: 15926
diff changeset
74 \lineiii{not \var{x}}
15e0c10092bb Massively improved documentation for string formatting operations,
Fred Drake <fdrake@acm.org>
parents: 15926
diff changeset
75 {if \var{x} is false, then \code{1}, else \code{0}}{(2)}
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
76 \end{tableiii}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
77 \opindex{and}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
78 \opindex{or}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
79 \opindex{not}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
80
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
81 \noindent
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
82 Notes:
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
83
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
84 \begin{description}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
85
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
86 \item[(1)]
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
87 These only evaluate their second argument if needed for their outcome.
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
88
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
89 \item[(2)]
12223
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11463
diff changeset
90 \samp{not} has a lower priority than non-Boolean operators, so
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11463
diff changeset
91 \code{not \var{a} == \var{b}} is interpreted as \code{not (\var{a} ==
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11463
diff changeset
92 \var{b})}, and \code{\var{a} == not \var{b}} is a syntax error.
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
93
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
94 \end{description}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
95
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
96
9083
bc41e86c938c Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9034
diff changeset
97 \subsection{Comparisons \label{comparisons}}
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
98
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
99 Comparison operations are supported by all objects. They all have the
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
100 same priority (which is higher than that of the Boolean operations).
12223
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11463
diff changeset
101 Comparisons can be chained arbitrarily; for example, \code{\var{x} <
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11463
diff changeset
102 \var{y} <= \var{z}} is equivalent to \code{\var{x} < \var{y} and
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11463
diff changeset
103 \var{y} <= \var{z}}, except that \var{y} is evaluated only once (but
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11463
diff changeset
104 in both cases \var{z} is not evaluated at all when \code{\var{x} <
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11463
diff changeset
105 \var{y}} is found to be false).
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
106 \indexii{chaining}{comparisons}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
107
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
108 This table summarizes the comparison operations:
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
109
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
110 \begin{tableiii}{c|l|c}{code}{Operation}{Meaning}{Notes}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
111 \lineiii{<}{strictly less than}{}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
112 \lineiii{<=}{less than or equal}{}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
113 \lineiii{>}{strictly greater than}{}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
114 \lineiii{>=}{greater than or equal}{}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
115 \lineiii{==}{equal}{}
14044
a905c5aa0691 As pointed out by Denis S. Otkidach <den@analyt.chem.msu.ru>, xrange()
Fred Drake <fdrake@acm.org>
parents: 13967
diff changeset
116 \lineiii{!=}{not equal}{(1)}
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
117 \lineiii{<>}{not equal}{(1)}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
118 \lineiii{is}{object identity}{}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
119 \lineiii{is not}{negated object identity}{}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
120 \end{tableiii}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
121 \indexii{operator}{comparison}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
122 \opindex{==} % XXX *All* others have funny characters < ! >
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
123 \opindex{is}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
124 \opindex{is not}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
125
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
126 \noindent
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
127 Notes:
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
128
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
129 \begin{description}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
130
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
131 \item[(1)]
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
132 \code{<>} and \code{!=} are alternate spellings for the same operator.
13933
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
133 (I couldn't choose between \ABC{} and C! :-)
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
134 \index{ABC language@\ABC{} language}
21062
bc02c3b09626 Clean up some markup cruft. A number of the macros that take no
Fred Drake <fdrake@acm.org>
parents: 20767
diff changeset
135 \index{language!ABC@\ABC}
13933
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
136 \indexii{C}{language}
12223
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11463
diff changeset
137 \code{!=} is the preferred spelling; \code{<>} is obsolescent.
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
138
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
139 \end{description}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
140
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
141 Objects of different types, except different numeric types, never
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
142 compare equal; such objects are ordered consistently but arbitrarily
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
143 (so that sorting a heterogeneous array yields a consistent result).
12223
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11463
diff changeset
144 Furthermore, some types (for example, file objects) support only a
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11463
diff changeset
145 degenerate notion of comparison where any two objects of that type are
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11463
diff changeset
146 unequal. Again, such objects are ordered arbitrarily but
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11463
diff changeset
147 consistently.
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11463
diff changeset
148 \indexii{object}{numeric}
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
149 \indexii{objects}{comparing}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
150
12223
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11463
diff changeset
151 Instances of a class normally compare as non-equal unless the class
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11463
diff changeset
152 \withsubitem{(instance method)}{\ttindex{__cmp__()}}
14485
ac0246586d52 Improve a couple of references to the language reference, making them
Fred Drake <fdrake@acm.org>
parents: 14044
diff changeset
153 defines the \method{__cmp__()} method. Refer to the
ac0246586d52 Improve a couple of references to the language reference, making them
Fred Drake <fdrake@acm.org>
parents: 14044
diff changeset
154 \citetitle[../ref/customization.html]{Python Reference Manual} for
ac0246586d52 Improve a couple of references to the language reference, making them
Fred Drake <fdrake@acm.org>
parents: 14044
diff changeset
155 information on the use of this method to effect object comparisons.
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
156
12223
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11463
diff changeset
157 \strong{Implementation note:} Objects of different types except
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11463
diff changeset
158 numbers are ordered by their type names; objects of the same types
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11463
diff changeset
159 that don't support proper comparison are ordered by their address.
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11463
diff changeset
160
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11463
diff changeset
161 Two more operations with the same syntactic priority,
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11463
diff changeset
162 \samp{in}\opindex{in} and \samp{not in}\opindex{not in}, are supported
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11463
diff changeset
163 only by sequence types (below).
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
164
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
165
9083
bc41e86c938c Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9034
diff changeset
166 \subsection{Numeric Types \label{typesnumeric}}
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
167
22340
7ecc49117d7e Take Tim's work on file.truncate out of 2.2.1 again.
Michael W. Hudson <mwh@python.net>
parents: 22337
diff changeset
168 There are four numeric types: \dfn{plain integers}, \dfn{long integers},
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
169 \dfn{floating point numbers}, and \dfn{complex numbers}.
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
170 Plain integers (also just called \dfn{integers})
12223
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11463
diff changeset
171 are implemented using \ctype{long} in C, which gives them at least 32
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
172 bits of precision. Long integers have unlimited precision. Floating
12223
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11463
diff changeset
173 point numbers are implemented using \ctype{double} in C. All bets on
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
174 their precision are off unless you happen to know the machine you are
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
175 working with.
15005
0cf5111bf09c Use \obindex{...} instead of \indexii{...}{type} in many places; this is
Fred Drake <fdrake@acm.org>
parents: 14710
diff changeset
176 \obindex{numeric}
0cf5111bf09c Use \obindex{...} instead of \indexii{...}{type} in many places; this is
Fred Drake <fdrake@acm.org>
parents: 14710
diff changeset
177 \obindex{integer}
0cf5111bf09c Use \obindex{...} instead of \indexii{...}{type} in many places; this is
Fred Drake <fdrake@acm.org>
parents: 14710
diff changeset
178 \obindex{long integer}
0cf5111bf09c Use \obindex{...} instead of \indexii{...}{type} in many places; this is
Fred Drake <fdrake@acm.org>
parents: 14710
diff changeset
179 \obindex{floating point}
0cf5111bf09c Use \obindex{...} instead of \indexii{...}{type} in many places; this is
Fred Drake <fdrake@acm.org>
parents: 14710
diff changeset
180 \obindex{complex number}
12223
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11463
diff changeset
181 \indexii{C}{language}
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
182
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
183 Complex numbers have a real and imaginary part, which are both
12223
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11463
diff changeset
184 implemented using \ctype{double} in C. To extract these parts from
22340
7ecc49117d7e Take Tim's work on file.truncate out of 2.2.1 again.
Michael W. Hudson <mwh@python.net>
parents: 22337
diff changeset
185 a complex number \var{z}, use \code{\var{z}.real} and \code{\var{z}.imag}.
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
186
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
187 Numbers are created by numeric literals or as the result of built-in
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
188 functions and operators. Unadorned integer literals (including hex
12223
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11463
diff changeset
189 and octal numbers) yield plain integers. Integer literals with an
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11463
diff changeset
190 \character{L} or \character{l} suffix yield long integers
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11463
diff changeset
191 (\character{L} is preferred because \samp{1l} looks too much like
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11463
diff changeset
192 eleven!). Numeric literals containing a decimal point or an exponent
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11463
diff changeset
193 sign yield floating point numbers. Appending \character{j} or
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11463
diff changeset
194 \character{J} to a numeric literal yields a complex number.
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
195 \indexii{numeric}{literals}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
196 \indexii{integer}{literals}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
197 \indexiii{long}{integer}{literals}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
198 \indexii{floating point}{literals}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
199 \indexii{complex number}{literals}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
200 \indexii{hexadecimal}{literals}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
201 \indexii{octal}{literals}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
202
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
203 Python fully supports mixed arithmetic: when a binary arithmetic
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
204 operator has operands of different numeric types, the operand with the
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
205 ``smaller'' type is converted to that of the other, where plain
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
206 integer is smaller than long integer is smaller than floating point is
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
207 smaller than complex.
10520
7ee1e3134147 Fixed latex2html weirdness with footnotes.
Fred Drake <fdrake@acm.org>
parents: 10241
diff changeset
208 Comparisons between numbers of mixed type use the same rule.\footnote{
7ee1e3134147 Fixed latex2html weirdness with footnotes.
Fred Drake <fdrake@acm.org>
parents: 10241
diff changeset
209 As a consequence, the list \code{[1, 2]} is considered equal
11100
fa2e3d06c790 Minor markup nit.
Fred Drake <fdrake@acm.org>
parents: 10968
diff changeset
210 to \code{[1.0, 2.0]}, and similar for tuples.
fa2e3d06c790 Minor markup nit.
Fred Drake <fdrake@acm.org>
parents: 10968
diff changeset
211 } The functions \function{int()}, \function{long()}, \function{float()},
9558
fa867d8ee7eb Remove some remaining {\rm ...} constructs.
Fred Drake <fdrake@acm.org>
parents: 9523
diff changeset
212 and \function{complex()} can be used
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
213 to coerce numbers to a specific type.
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
214 \index{arithmetic}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
215 \bifuncindex{int}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
216 \bifuncindex{long}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
217 \bifuncindex{float}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
218 \bifuncindex{complex}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
219
25586
b287bdacde39 Backport 1.94:
Raymond Hettinger <python@rcn.com>
parents: 25585
diff changeset
220 All numeric types (except complex) support the following operations,
b287bdacde39 Backport 1.94:
Raymond Hettinger <python@rcn.com>
parents: 25585
diff changeset
221 sorted by ascending priority (operations in the same box have the same
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
222 priority; all numeric operations have a higher priority than
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
223 comparison operations):
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
224
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
225 \begin{tableiii}{c|l|c}{code}{Operation}{Result}{Notes}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
226 \lineiii{\var{x} + \var{y}}{sum of \var{x} and \var{y}}{}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
227 \lineiii{\var{x} - \var{y}}{difference of \var{x} and \var{y}}{}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
228 \hline
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
229 \lineiii{\var{x} * \var{y}}{product of \var{x} and \var{y}}{}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
230 \lineiii{\var{x} / \var{y}}{quotient of \var{x} and \var{y}}{(1)}
25586
b287bdacde39 Backport 1.94:
Raymond Hettinger <python@rcn.com>
parents: 25585
diff changeset
231 \lineiii{\var{x} \%{} \var{y}}{remainder of \code{\var{x} / \var{y}}}{(4)}
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
232 \hline
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
233 \lineiii{-\var{x}}{\var{x} negated}{}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
234 \lineiii{+\var{x}}{\var{x} unchanged}{}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
235 \hline
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
236 \lineiii{abs(\var{x})}{absolute value or magnitude of \var{x}}{}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
237 \lineiii{int(\var{x})}{\var{x} converted to integer}{(2)}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
238 \lineiii{long(\var{x})}{\var{x} converted to long integer}{(2)}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
239 \lineiii{float(\var{x})}{\var{x} converted to floating point}{}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
240 \lineiii{complex(\var{re},\var{im})}{a complex number with real part \var{re}, imaginary part \var{im}. \var{im} defaults to zero.}{}
10147
3ac7f0066375 Document <complex #>.conjugate().
Fred Drake <fdrake@acm.org>
parents: 9558
diff changeset
241 \lineiii{\var{c}.conjugate()}{conjugate of the complex number \var{c}}{}
25586
b287bdacde39 Backport 1.94:
Raymond Hettinger <python@rcn.com>
parents: 25585
diff changeset
242 \lineiii{divmod(\var{x}, \var{y})}{the pair \code{(\var{x} / \var{y}, \var{x} \%{} \var{y})}}{(3)(4)}
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
243 \lineiii{pow(\var{x}, \var{y})}{\var{x} to the power \var{y}}{}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
244 \lineiii{\var{x} ** \var{y}}{\var{x} to the power \var{y}}{}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
245 \end{tableiii}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
246 \indexiii{operations on}{numeric}{types}
10147
3ac7f0066375 Document <complex #>.conjugate().
Fred Drake <fdrake@acm.org>
parents: 9558
diff changeset
247 \withsubitem{(complex number method)}{\ttindex{conjugate()}}
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
248
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
249 \noindent
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
250 Notes:
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
251 \begin{description}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
252
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
253 \item[(1)]
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
254 For (plain or long) integer division, the result is an integer.
22340
7ecc49117d7e Take Tim's work on file.truncate out of 2.2.1 again.
Michael W. Hudson <mwh@python.net>
parents: 22337
diff changeset
255 The result is always rounded towards minus infinity: 1/2 is 0,
12223
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11463
diff changeset
256 (-1)/2 is -1, 1/(-2) is -1, and (-1)/(-2) is 0. Note that the result
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11463
diff changeset
257 is a long integer if either operand is a long integer, regardless of
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11463
diff changeset
258 the numeric value.
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
259 \indexii{integer}{division}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
260 \indexiii{long}{integer}{division}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
261
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
262 \item[(2)]
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
263 Conversion from floating point to (long or plain) integer may round or
13933
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
264 truncate as in C; see functions \function{floor()} and
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
265 \function{ceil()} in the \refmodule{math}\refbimodindex{math} module
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
266 for well-defined conversions.
10156
0f7d694bc334 Make sure all HTML pages generated from this section have reasonable
Fred Drake <fdrake@acm.org>
parents: 10147
diff changeset
267 \withsubitem{(in module math)}{\ttindex{floor()}\ttindex{ceil()}}
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
268 \indexii{numeric}{conversions}
13933
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
269 \indexii{C}{language}
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
270
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
271 \item[(3)]
12223
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11463
diff changeset
272 See section \ref{built-in-funcs}, ``Built-in Functions,'' for a full
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11463
diff changeset
273 description.
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
274
25586
b287bdacde39 Backport 1.94:
Raymond Hettinger <python@rcn.com>
parents: 25585
diff changeset
275 \item[(4)]
b287bdacde39 Backport 1.94:
Raymond Hettinger <python@rcn.com>
parents: 25585
diff changeset
276 Complex floor division operator, modulo operator, and \function{divmod()}.
b287bdacde39 Backport 1.94:
Raymond Hettinger <python@rcn.com>
parents: 25585
diff changeset
277
b287bdacde39 Backport 1.94:
Raymond Hettinger <python@rcn.com>
parents: 25585
diff changeset
278 \deprecated{2.3}{Instead convert to float using \function{abs()}
b287bdacde39 Backport 1.94:
Raymond Hettinger <python@rcn.com>
parents: 25585
diff changeset
279 if appropriate.}
b287bdacde39 Backport 1.94:
Raymond Hettinger <python@rcn.com>
parents: 25585
diff changeset
280
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
281 \end{description}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
282 % XXXJH exceptions: overflow (when? what operations?) zerodivision
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
283
10241
f138ba72bf2d Update description of what modules "look like" when printed.
Fred Drake <fdrake@acm.org>
parents: 10156
diff changeset
284 \subsubsection{Bit-string Operations on Integer Types \label{bitstring-ops}}
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
285 \nodename{Bit-string Operations}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
286
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
287 Plain and long integer types support additional operations that make
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
288 sense only for bit-strings. Negative numbers are treated as their 2's
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
289 complement value (for long integers, this assumes a sufficiently large
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
290 number of bits that no overflow occurs during the operation).
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
291
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
292 The priorities of the binary bit-wise operations are all lower than
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
293 the numeric operations and higher than the comparisons; the unary
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
294 operation \samp{\~} has the same priority as the other unary numeric
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
295 operations (\samp{+} and \samp{-}).
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
296
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
297 This table lists the bit-string operations sorted in ascending
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
298 priority (operations in the same box have the same priority):
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
299
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
300 \begin{tableiii}{c|l|c}{code}{Operation}{Result}{Notes}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
301 \lineiii{\var{x} | \var{y}}{bitwise \dfn{or} of \var{x} and \var{y}}{}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
302 \lineiii{\var{x} \^{} \var{y}}{bitwise \dfn{exclusive or} of \var{x} and \var{y}}{}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
303 \lineiii{\var{x} \&{} \var{y}}{bitwise \dfn{and} of \var{x} and \var{y}}{}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
304 \lineiii{\var{x} << \var{n}}{\var{x} shifted left by \var{n} bits}{(1), (2)}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
305 \lineiii{\var{x} >> \var{n}}{\var{x} shifted right by \var{n} bits}{(1), (3)}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
306 \hline
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
307 \lineiii{\~\var{x}}{the bits of \var{x} inverted}{}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
308 \end{tableiii}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
309 \indexiii{operations on}{integer}{types}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
310 \indexii{bit-string}{operations}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
311 \indexii{shifting}{operations}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
312 \indexii{masking}{operations}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
313
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
314 \noindent
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
315 Notes:
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
316 \begin{description}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
317 \item[(1)] Negative shift counts are illegal and cause a
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
318 \exception{ValueError} to be raised.
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
319 \item[(2)] A left shift by \var{n} bits is equivalent to
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
320 multiplication by \code{pow(2, \var{n})} without overflow check.
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
321 \item[(3)] A right shift by \var{n} bits is equivalent to
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
322 division by \code{pow(2, \var{n})} without overflow check.
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
323 \end{description}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
324
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
325
17658
d6498b1ef50d Added section describing the iterator protocol.
Fred Drake <fdrake@acm.org>
parents: 17616
diff changeset
326 \subsection{Iterator Types \label{typeiter}}
d6498b1ef50d Added section describing the iterator protocol.
Fred Drake <fdrake@acm.org>
parents: 17616
diff changeset
327
17663
d76649bd38d0 The general iteration support is part of 2.2, not 2.1 -- fixed the version
Fred Drake <fdrake@acm.org>
parents: 17658
diff changeset
328 \versionadded{2.2}
17658
d6498b1ef50d Added section describing the iterator protocol.
Fred Drake <fdrake@acm.org>
parents: 17616
diff changeset
329 \index{iterator protocol}
d6498b1ef50d Added section describing the iterator protocol.
Fred Drake <fdrake@acm.org>
parents: 17616
diff changeset
330 \index{protocol!iterator}
d6498b1ef50d Added section describing the iterator protocol.
Fred Drake <fdrake@acm.org>
parents: 17616
diff changeset
331 \index{sequence!iteration}
d6498b1ef50d Added section describing the iterator protocol.
Fred Drake <fdrake@acm.org>
parents: 17616
diff changeset
332 \index{container!iteration over}
d6498b1ef50d Added section describing the iterator protocol.
Fred Drake <fdrake@acm.org>
parents: 17616
diff changeset
333
d6498b1ef50d Added section describing the iterator protocol.
Fred Drake <fdrake@acm.org>
parents: 17616
diff changeset
334 Python supports a concept of iteration over containers. This is
d6498b1ef50d Added section describing the iterator protocol.
Fred Drake <fdrake@acm.org>
parents: 17616
diff changeset
335 implemented using two distinct methods; these are used to allow
d6498b1ef50d Added section describing the iterator protocol.
Fred Drake <fdrake@acm.org>
parents: 17616
diff changeset
336 user-defined classes to support iteration. Sequences, described below
d6498b1ef50d Added section describing the iterator protocol.
Fred Drake <fdrake@acm.org>
parents: 17616
diff changeset
337 in more detail, always support the iteration methods.
d6498b1ef50d Added section describing the iterator protocol.
Fred Drake <fdrake@acm.org>
parents: 17616
diff changeset
338
d6498b1ef50d Added section describing the iterator protocol.
Fred Drake <fdrake@acm.org>
parents: 17616
diff changeset
339 One method needs to be defined for container objects to provide
d6498b1ef50d Added section describing the iterator protocol.
Fred Drake <fdrake@acm.org>
parents: 17616
diff changeset
340 iteration support:
d6498b1ef50d Added section describing the iterator protocol.
Fred Drake <fdrake@acm.org>
parents: 17616
diff changeset
341
d6498b1ef50d Added section describing the iterator protocol.
Fred Drake <fdrake@acm.org>
parents: 17616
diff changeset
342 \begin{methoddesc}[container]{__iter__}{}
18839
ab8aa4302109 Typo fix.
Greg Ward <gward@python.net>
parents: 18829
diff changeset
343 Return an iterator object. The object is required to support the
17658
d6498b1ef50d Added section describing the iterator protocol.
Fred Drake <fdrake@acm.org>
parents: 17616
diff changeset
344 iterator protocol described below. If a container supports
d6498b1ef50d Added section describing the iterator protocol.
Fred Drake <fdrake@acm.org>
parents: 17616
diff changeset
345 different types of iteration, additional methods can be provided to
d6498b1ef50d Added section describing the iterator protocol.
Fred Drake <fdrake@acm.org>
parents: 17616
diff changeset
346 specifically request iterators for those iteration types. (An
d6498b1ef50d Added section describing the iterator protocol.
Fred Drake <fdrake@acm.org>
parents: 17616
diff changeset
347 example of an object supporting multiple forms of iteration would be
d6498b1ef50d Added section describing the iterator protocol.
Fred Drake <fdrake@acm.org>
parents: 17616
diff changeset
348 a tree structure which supports both breadth-first and depth-first
d6498b1ef50d Added section describing the iterator protocol.
Fred Drake <fdrake@acm.org>
parents: 17616
diff changeset
349 traversal.) This method corresponds to the \member{tp_iter} slot of
d6498b1ef50d Added section describing the iterator protocol.
Fred Drake <fdrake@acm.org>
parents: 17616
diff changeset
350 the type structure for Python objects in the Python/C API.
d6498b1ef50d Added section describing the iterator protocol.
Fred Drake <fdrake@acm.org>
parents: 17616
diff changeset
351 \end{methoddesc}
d6498b1ef50d Added section describing the iterator protocol.
Fred Drake <fdrake@acm.org>
parents: 17616
diff changeset
352
d6498b1ef50d Added section describing the iterator protocol.
Fred Drake <fdrake@acm.org>
parents: 17616
diff changeset
353 The iterator objects themselves are required to support the following
d6498b1ef50d Added section describing the iterator protocol.
Fred Drake <fdrake@acm.org>
parents: 17616
diff changeset
354 two methods, which together form the \dfn{iterator protocol}:
d6498b1ef50d Added section describing the iterator protocol.
Fred Drake <fdrake@acm.org>
parents: 17616
diff changeset
355
d6498b1ef50d Added section describing the iterator protocol.
Fred Drake <fdrake@acm.org>
parents: 17616
diff changeset
356 \begin{methoddesc}[iterator]{__iter__}{}
d6498b1ef50d Added section describing the iterator protocol.
Fred Drake <fdrake@acm.org>
parents: 17616
diff changeset
357 Return the iterator object itself. This is required to allow both
d6498b1ef50d Added section describing the iterator protocol.
Fred Drake <fdrake@acm.org>
parents: 17616
diff changeset
358 containers and iterators to be used with the \keyword{for} and
d6498b1ef50d Added section describing the iterator protocol.
Fred Drake <fdrake@acm.org>
parents: 17616
diff changeset
359 \keyword{in} statements. This method corresponds to the
d6498b1ef50d Added section describing the iterator protocol.
Fred Drake <fdrake@acm.org>
parents: 17616
diff changeset
360 \member{tp_iter} slot of the type structure for Python objects in
d6498b1ef50d Added section describing the iterator protocol.
Fred Drake <fdrake@acm.org>
parents: 17616
diff changeset
361 the Python/C API.
d6498b1ef50d Added section describing the iterator protocol.
Fred Drake <fdrake@acm.org>
parents: 17616
diff changeset
362 \end{methoddesc}
d6498b1ef50d Added section describing the iterator protocol.
Fred Drake <fdrake@acm.org>
parents: 17616
diff changeset
363
17663
d76649bd38d0 The general iteration support is part of 2.2, not 2.1 -- fixed the version
Fred Drake <fdrake@acm.org>
parents: 17658
diff changeset
364 \begin{methoddesc}[iterator]{next}{}
17658
d6498b1ef50d Added section describing the iterator protocol.
Fred Drake <fdrake@acm.org>
parents: 17616
diff changeset
365 Return the next item from the container. If there are no further
d6498b1ef50d Added section describing the iterator protocol.
Fred Drake <fdrake@acm.org>
parents: 17616
diff changeset
366 items, raise the \exception{StopIteration} exception. This method
d6498b1ef50d Added section describing the iterator protocol.
Fred Drake <fdrake@acm.org>
parents: 17616
diff changeset
367 corresponds to the \member{tp_iternext} slot of the type structure
d6498b1ef50d Added section describing the iterator protocol.
Fred Drake <fdrake@acm.org>
parents: 17616
diff changeset
368 for Python objects in the Python/C API.
d6498b1ef50d Added section describing the iterator protocol.
Fred Drake <fdrake@acm.org>
parents: 17616
diff changeset
369 \end{methoddesc}
d6498b1ef50d Added section describing the iterator protocol.
Fred Drake <fdrake@acm.org>
parents: 17616
diff changeset
370
d6498b1ef50d Added section describing the iterator protocol.
Fred Drake <fdrake@acm.org>
parents: 17616
diff changeset
371 Python defines several iterator objects to support iteration over
d6498b1ef50d Added section describing the iterator protocol.
Fred Drake <fdrake@acm.org>
parents: 17616
diff changeset
372 general and specific sequence types, dictionaries, and other more
d6498b1ef50d Added section describing the iterator protocol.
Fred Drake <fdrake@acm.org>
parents: 17616
diff changeset
373 specialized forms. The specific types are not important beyond their
d6498b1ef50d Added section describing the iterator protocol.
Fred Drake <fdrake@acm.org>
parents: 17616
diff changeset
374 implementation of the iterator protocol.
d6498b1ef50d Added section describing the iterator protocol.
Fred Drake <fdrake@acm.org>
parents: 17616
diff changeset
375
25585
dae2282bc76b Backport 1.100: Discussion of Stop Iteration in the Iterator Protocol.
Raymond Hettinger <python@rcn.com>
parents: 24903
diff changeset
376 The intention of the protocol is that once an iterator's
dae2282bc76b Backport 1.100: Discussion of Stop Iteration in the Iterator Protocol.
Raymond Hettinger <python@rcn.com>
parents: 24903
diff changeset
377 \method{next()} method raises \exception{StopIteration}, it will
dae2282bc76b Backport 1.100: Discussion of Stop Iteration in the Iterator Protocol.
Raymond Hettinger <python@rcn.com>
parents: 24903
diff changeset
378 continue to do so on subsequent calls. Implementations that
dae2282bc76b Backport 1.100: Discussion of Stop Iteration in the Iterator Protocol.
Raymond Hettinger <python@rcn.com>
parents: 24903
diff changeset
379 do not obey this property are deemed broken. (This constraint
dae2282bc76b Backport 1.100: Discussion of Stop Iteration in the Iterator Protocol.
Raymond Hettinger <python@rcn.com>
parents: 24903
diff changeset
380 was added in Python 2.3; in Python 2.2, various iterators are
dae2282bc76b Backport 1.100: Discussion of Stop Iteration in the Iterator Protocol.
Raymond Hettinger <python@rcn.com>
parents: 24903
diff changeset
381 broken according to this rule.)
dae2282bc76b Backport 1.100: Discussion of Stop Iteration in the Iterator Protocol.
Raymond Hettinger <python@rcn.com>
parents: 24903
diff changeset
382
17658
d6498b1ef50d Added section describing the iterator protocol.
Fred Drake <fdrake@acm.org>
parents: 17616
diff changeset
383
9083
bc41e86c938c Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9034
diff changeset
384 \subsection{Sequence Types \label{typesseq}}
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
385
13967
7b7ee58901fb Document the range type, as suggested by Denis S. Otkidach
Fred Drake <fdrake@acm.org>
parents: 13933
diff changeset
386 There are six sequence types: strings, Unicode strings, lists,
14044
a905c5aa0691 As pointed out by Denis S. Otkidach <den@analyt.chem.msu.ru>, xrange()
Fred Drake <fdrake@acm.org>
parents: 13967
diff changeset
387 tuples, buffers, and xrange objects.
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
388
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
389 Strings literals are written in single or double quotes:
12223
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11463
diff changeset
390 \code{'xyzzy'}, \code{"frobozz"}. See chapter 2 of the
13933
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
391 \citetitle[../ref/strings.html]{Python Reference Manual} for more about
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
392 string literals. Unicode strings are much like strings, but are
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
393 specified in the syntax using a preceeding \character{u} character:
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
394 \code{u'abc'}, \code{u"def"}. Lists are constructed with square brackets,
11463
17e12305973e Use \citetitle and \programopt as appropriate.
Fred Drake <fdrake@acm.org>
parents: 11183
diff changeset
395 separating items with commas: \code{[a, b, c]}. Tuples are
17e12305973e Use \citetitle and \programopt as appropriate.
Fred Drake <fdrake@acm.org>
parents: 11183
diff changeset
396 constructed by the comma operator (not within square brackets), with
17e12305973e Use \citetitle and \programopt as appropriate.
Fred Drake <fdrake@acm.org>
parents: 11183
diff changeset
397 or without enclosing parentheses, but an empty tuple must have the
17e12305973e Use \citetitle and \programopt as appropriate.
Fred Drake <fdrake@acm.org>
parents: 11183
diff changeset
398 enclosing parentheses, e.g., \code{a, b, c} or \code{()}. A single
18395
1d0d3e6a3201 List constraints on xrange() objects.
Guido van Rossum <guido@python.org>
parents: 18391
diff changeset
399 item tuple must have a trailing comma, e.g., \code{(d,)}.
15005
0cf5111bf09c Use \obindex{...} instead of \indexii{...}{type} in many places; this is
Fred Drake <fdrake@acm.org>
parents: 14710
diff changeset
400 \obindex{sequence}
0cf5111bf09c Use \obindex{...} instead of \indexii{...}{type} in many places; this is
Fred Drake <fdrake@acm.org>
parents: 14710
diff changeset
401 \obindex{string}
0cf5111bf09c Use \obindex{...} instead of \indexii{...}{type} in many places; this is
Fred Drake <fdrake@acm.org>
parents: 14710
diff changeset
402 \obindex{Unicode}
0cf5111bf09c Use \obindex{...} instead of \indexii{...}{type} in many places; this is
Fred Drake <fdrake@acm.org>
parents: 14710
diff changeset
403 \obindex{tuple}
0cf5111bf09c Use \obindex{...} instead of \indexii{...}{type} in many places; this is
Fred Drake <fdrake@acm.org>
parents: 14710
diff changeset
404 \obindex{list}
18395
1d0d3e6a3201 List constraints on xrange() objects.
Guido van Rossum <guido@python.org>
parents: 18391
diff changeset
405
1d0d3e6a3201 List constraints on xrange() objects.
Guido van Rossum <guido@python.org>
parents: 18391
diff changeset
406 Buffer objects are not directly supported by Python syntax, but can be
1d0d3e6a3201 List constraints on xrange() objects.
Guido van Rossum <guido@python.org>
parents: 18391
diff changeset
407 created by calling the builtin function
23355
67bcb4f5237f Remove extra period produced by previous change.
Fred Drake <fdrake@acm.org>
parents: 23341
diff changeset
408 \function{buffer()}.\bifuncindex{buffer} They support concatenation
67bcb4f5237f Remove extra period produced by previous change.
Fred Drake <fdrake@acm.org>
parents: 23341
diff changeset
409 and repetition, but the result is a new string object rather than a
67bcb4f5237f Remove extra period produced by previous change.
Fred Drake <fdrake@acm.org>
parents: 23341
diff changeset
410 new buffer object.
18395
1d0d3e6a3201 List constraints on xrange() objects.
Guido van Rossum <guido@python.org>
parents: 18391
diff changeset
411 \obindex{buffer}
1d0d3e6a3201 List constraints on xrange() objects.
Guido van Rossum <guido@python.org>
parents: 18391
diff changeset
412
1d0d3e6a3201 List constraints on xrange() objects.
Guido van Rossum <guido@python.org>
parents: 18391
diff changeset
413 Xrange objects are similar to buffers in that there is no specific
23341
55423c1abcd1 Correct information on support for repietition & concatenation for buffer
Fred Drake <fdrake@acm.org>
parents: 23319
diff changeset
414 syntax to create them, but they are created using the
55423c1abcd1 Correct information on support for repietition & concatenation for buffer
Fred Drake <fdrake@acm.org>
parents: 23319
diff changeset
415 \function{xrange()} function.\bifuncindex{xrange} They don't support
55423c1abcd1 Correct information on support for repietition & concatenation for buffer
Fred Drake <fdrake@acm.org>
parents: 23319
diff changeset
416 slicing or concatenation, but do support repetition, and using
55423c1abcd1 Correct information on support for repietition & concatenation for buffer
Fred Drake <fdrake@acm.org>
parents: 23319
diff changeset
417 \code{in}, \code{not in}, \function{min()} or \function{max()} on them
55423c1abcd1 Correct information on support for repietition & concatenation for buffer
Fred Drake <fdrake@acm.org>
parents: 23319
diff changeset
418 is inefficient.
15005
0cf5111bf09c Use \obindex{...} instead of \indexii{...}{type} in many places; this is
Fred Drake <fdrake@acm.org>
parents: 14710
diff changeset
419 \obindex{xrange}
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
420
18395
1d0d3e6a3201 List constraints on xrange() objects.
Guido van Rossum <guido@python.org>
parents: 18391
diff changeset
421 Most sequence types support the following operations. The \samp{in} and
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
422 \samp{not in} operations have the same priorities as the comparison
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
423 operations. The \samp{+} and \samp{*} operations have the same
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
424 priority as the corresponding numeric operations.\footnote{They must
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
425 have since the parser can't tell the type of the operands.}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
426
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
427 This table lists the sequence operations sorted in ascending priority
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
428 (operations in the same box have the same priority). In the table,
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
429 \var{s} and \var{t} are sequences of the same type; \var{n}, \var{i}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
430 and \var{j} are integers:
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
431
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
432 \begin{tableiii}{c|l|c}{code}{Operation}{Result}{Notes}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
433 \lineiii{\var{x} in \var{s}}{\code{1} if an item of \var{s} is equal to \var{x}, else \code{0}}{}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
434 \lineiii{\var{x} not in \var{s}}{\code{0} if an item of \var{s} is
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
435 equal to \var{x}, else \code{1}}{}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
436 \hline
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
437 \lineiii{\var{s} + \var{t}}{the concatenation of \var{s} and \var{t}}{}
19529
dd8d6153a8c6 Added explanation that [...] * n generates shallow copies of [...], so
Fred Drake <fdrake@acm.org>
parents: 19243
diff changeset
438 \lineiii{\var{s} * \var{n}\textrm{,} \var{n} * \var{s}}{\var{n} shallow copies of \var{s} concatenated}{(1)}
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
439 \hline
12223
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11463
diff changeset
440 \lineiii{\var{s}[\var{i}]}{\var{i}'th item of \var{s}, origin 0}{(2)}
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11463
diff changeset
441 \lineiii{\var{s}[\var{i}:\var{j}]}{slice of \var{s} from \var{i} to \var{j}}{(2), (3)}
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
442 \hline
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
443 \lineiii{len(\var{s})}{length of \var{s}}{}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
444 \lineiii{min(\var{s})}{smallest item of \var{s}}{}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
445 \lineiii{max(\var{s})}{largest item of \var{s}}{}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
446 \end{tableiii}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
447 \indexiii{operations on}{sequence}{types}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
448 \bifuncindex{len}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
449 \bifuncindex{min}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
450 \bifuncindex{max}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
451 \indexii{concatenation}{operation}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
452 \indexii{repetition}{operation}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
453 \indexii{subscript}{operation}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
454 \indexii{slice}{operation}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
455 \opindex{in}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
456 \opindex{not in}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
457
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
458 \noindent
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
459 Notes:
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
460
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
461 \begin{description}
12223
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11463
diff changeset
462 \item[(1)] Values of \var{n} less than \code{0} are treated as
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11463
diff changeset
463 \code{0} (which yields an empty sequence of the same type as
19529
dd8d6153a8c6 Added explanation that [...] * n generates shallow copies of [...], so
Fred Drake <fdrake@acm.org>
parents: 19243
diff changeset
464 \var{s}). Note also that the copies are shallow; nested structures
dd8d6153a8c6 Added explanation that [...] * n generates shallow copies of [...], so
Fred Drake <fdrake@acm.org>
parents: 19243
diff changeset
465 are not copied. This often haunts new Python programmers; consider:
dd8d6153a8c6 Added explanation that [...] * n generates shallow copies of [...], so
Fred Drake <fdrake@acm.org>
parents: 19243
diff changeset
466
dd8d6153a8c6 Added explanation that [...] * n generates shallow copies of [...], so
Fred Drake <fdrake@acm.org>
parents: 19243
diff changeset
467 \begin{verbatim}
dd8d6153a8c6 Added explanation that [...] * n generates shallow copies of [...], so
Fred Drake <fdrake@acm.org>
parents: 19243
diff changeset
468 >>> lists = [[]] * 3
dd8d6153a8c6 Added explanation that [...] * n generates shallow copies of [...], so
Fred Drake <fdrake@acm.org>
parents: 19243
diff changeset
469 >>> lists
dd8d6153a8c6 Added explanation that [...] * n generates shallow copies of [...], so
Fred Drake <fdrake@acm.org>
parents: 19243
diff changeset
470 [[], [], []]
dd8d6153a8c6 Added explanation that [...] * n generates shallow copies of [...], so
Fred Drake <fdrake@acm.org>
parents: 19243
diff changeset
471 >>> lists[0].append(3)
dd8d6153a8c6 Added explanation that [...] * n generates shallow copies of [...], so
Fred Drake <fdrake@acm.org>
parents: 19243
diff changeset
472 >>> lists
dd8d6153a8c6 Added explanation that [...] * n generates shallow copies of [...], so
Fred Drake <fdrake@acm.org>
parents: 19243
diff changeset
473 [[3], [3], [3]]
dd8d6153a8c6 Added explanation that [...] * n generates shallow copies of [...], so
Fred Drake <fdrake@acm.org>
parents: 19243
diff changeset
474 \end{verbatim}
dd8d6153a8c6 Added explanation that [...] * n generates shallow copies of [...], so
Fred Drake <fdrake@acm.org>
parents: 19243
diff changeset
475
dd8d6153a8c6 Added explanation that [...] * n generates shallow copies of [...], so
Fred Drake <fdrake@acm.org>
parents: 19243
diff changeset
476 What has happened is that \code{lists} is a list containing three
dd8d6153a8c6 Added explanation that [...] * n generates shallow copies of [...], so
Fred Drake <fdrake@acm.org>
parents: 19243
diff changeset
477 copies of the list \code{[[]]} (a one-element list containing an
dd8d6153a8c6 Added explanation that [...] * n generates shallow copies of [...], so
Fred Drake <fdrake@acm.org>
parents: 19243
diff changeset
478 empty list), but the contained list is shared by each copy. You can
dd8d6153a8c6 Added explanation that [...] * n generates shallow copies of [...], so
Fred Drake <fdrake@acm.org>
parents: 19243
diff changeset
479 create a list of different lists this way:
dd8d6153a8c6 Added explanation that [...] * n generates shallow copies of [...], so
Fred Drake <fdrake@acm.org>
parents: 19243
diff changeset
480
dd8d6153a8c6 Added explanation that [...] * n generates shallow copies of [...], so
Fred Drake <fdrake@acm.org>
parents: 19243
diff changeset
481 \begin{verbatim}
dd8d6153a8c6 Added explanation that [...] * n generates shallow copies of [...], so
Fred Drake <fdrake@acm.org>
parents: 19243
diff changeset
482 >>> lists = [[] for i in range(3)]
dd8d6153a8c6 Added explanation that [...] * n generates shallow copies of [...], so
Fred Drake <fdrake@acm.org>
parents: 19243
diff changeset
483 >>> lists[0].append(3)
dd8d6153a8c6 Added explanation that [...] * n generates shallow copies of [...], so
Fred Drake <fdrake@acm.org>
parents: 19243
diff changeset
484 >>> lists[1].append(5)
dd8d6153a8c6 Added explanation that [...] * n generates shallow copies of [...], so
Fred Drake <fdrake@acm.org>
parents: 19243
diff changeset
485 >>> lists[2].append(7)
dd8d6153a8c6 Added explanation that [...] * n generates shallow copies of [...], so
Fred Drake <fdrake@acm.org>
parents: 19243
diff changeset
486 >>> lists
dd8d6153a8c6 Added explanation that [...] * n generates shallow copies of [...], so
Fred Drake <fdrake@acm.org>
parents: 19243
diff changeset
487 [[3], [5], [7]]
dd8d6153a8c6 Added explanation that [...] * n generates shallow copies of [...], so
Fred Drake <fdrake@acm.org>
parents: 19243
diff changeset
488 \end{verbatim}
12223
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11463
diff changeset
489
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11463
diff changeset
490 \item[(2)] If \var{i} or \var{j} is negative, the index is relative to
18416
33b4357aebb8 Fix up a few style nits -- avoid "e.g." and "i.e." -- these make
Fred Drake <fdrake@acm.org>
parents: 18395
diff changeset
491 the end of the string: \code{len(\var{s}) + \var{i}} or
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
492 \code{len(\var{s}) + \var{j}} is substituted. But note that \code{-0} is
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
493 still \code{0}.
22340
7ecc49117d7e Take Tim's work on file.truncate out of 2.2.1 again.
Michael W. Hudson <mwh@python.net>
parents: 22337
diff changeset
494
12223
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11463
diff changeset
495 \item[(3)] The slice of \var{s} from \var{i} to \var{j} is defined as
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
496 the sequence of items with index \var{k} such that \code{\var{i} <=
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
497 \var{k} < \var{j}}. If \var{i} or \var{j} is greater than
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
498 \code{len(\var{s})}, use \code{len(\var{s})}. If \var{i} is omitted,
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
499 use \code{0}. If \var{j} is omitted, use \code{len(\var{s})}. If
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
500 \var{i} is greater than or equal to \var{j}, the slice is empty.
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
501 \end{description}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
502
10156
0f7d694bc334 Make sure all HTML pages generated from this section have reasonable
Fred Drake <fdrake@acm.org>
parents: 10147
diff changeset
503
13933
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
504 \subsubsection{String Methods \label{string-methods}}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
505
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
506 These are the string methods which both 8-bit strings and Unicode
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
507 objects support:
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
508
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
509 \begin{methoddesc}[string]{capitalize}{}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
510 Return a copy of the string with only its first character capitalized.
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
511 \end{methoddesc}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
512
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
513 \begin{methoddesc}[string]{center}{width}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
514 Return centered in a string of length \var{width}. Padding is done
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
515 using spaces.
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
516 \end{methoddesc}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
517
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
518 \begin{methoddesc}[string]{count}{sub\optional{, start\optional{, end}}}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
519 Return the number of occurrences of substring \var{sub} in string
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
520 S\code{[\var{start}:\var{end}]}. Optional arguments \var{start} and
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
521 \var{end} are interpreted as in slice notation.
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
522 \end{methoddesc}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
523
21332
fbbd8a4ca7a6 Added documentation for str.decode().
Fred Drake <fdrake@acm.org>
parents: 21177
diff changeset
524 \begin{methoddesc}[string]{decode}{\optional{encoding\optional{, errors}}}
fbbd8a4ca7a6 Added documentation for str.decode().
Fred Drake <fdrake@acm.org>
parents: 21177
diff changeset
525 Decodes the string using the codec registered for \var{encoding}.
fbbd8a4ca7a6 Added documentation for str.decode().
Fred Drake <fdrake@acm.org>
parents: 21177
diff changeset
526 \var{encoding} defaults to the default string encoding. \var{errors}
fbbd8a4ca7a6 Added documentation for str.decode().
Fred Drake <fdrake@acm.org>
parents: 21177
diff changeset
527 may be given to set a different error handling scheme. The default is
fbbd8a4ca7a6 Added documentation for str.decode().
Fred Drake <fdrake@acm.org>
parents: 21177
diff changeset
528 \code{'strict'}, meaning that encoding errors raise
fbbd8a4ca7a6 Added documentation for str.decode().
Fred Drake <fdrake@acm.org>
parents: 21177
diff changeset
529 \exception{ValueError}. Other possible values are \code{'ignore'} and
fbbd8a4ca7a6 Added documentation for str.decode().
Fred Drake <fdrake@acm.org>
parents: 21177
diff changeset
530 \code{replace'}.
fbbd8a4ca7a6 Added documentation for str.decode().
Fred Drake <fdrake@acm.org>
parents: 21177
diff changeset
531 \versionadded{2.2}
fbbd8a4ca7a6 Added documentation for str.decode().
Fred Drake <fdrake@acm.org>
parents: 21177
diff changeset
532 \end{methoddesc}
fbbd8a4ca7a6 Added documentation for str.decode().
Fred Drake <fdrake@acm.org>
parents: 21177
diff changeset
533
13933
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
534 \begin{methoddesc}[string]{encode}{\optional{encoding\optional{,errors}}}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
535 Return an encoded version of the string. Default encoding is the current
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
536 default string encoding. \var{errors} may be given to set a different
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
537 error handling scheme. The default for \var{errors} is
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
538 \code{'strict'}, meaning that encoding errors raise a
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
539 \exception{ValueError}. Other possible values are \code{'ignore'} and
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
540 \code{'replace'}.
15332
12aec3381c94 Marc-Andre Lemburg <mal@lemburg.com> noted that the encode() string method
Fred Drake <fdrake@acm.org>
parents: 15005
diff changeset
541 \versionadded{2.0}
13933
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
542 \end{methoddesc}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
543
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
544 \begin{methoddesc}[string]{endswith}{suffix\optional{, start\optional{, end}}}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
545 Return true if the string ends with the specified \var{suffix},
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
546 otherwise return false. With optional \var{start}, test beginning at
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
547 that position. With optional \var{end}, stop comparing at that position.
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
548 \end{methoddesc}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
549
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
550 \begin{methoddesc}[string]{expandtabs}{\optional{tabsize}}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
551 Return a copy of the string where all tab characters are expanded
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
552 using spaces. If \var{tabsize} is not given, a tab size of \code{8}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
553 characters is assumed.
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
554 \end{methoddesc}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
555
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
556 \begin{methoddesc}[string]{find}{sub\optional{, start\optional{, end}}}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
557 Return the lowest index in the string where substring \var{sub} is
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
558 found, such that \var{sub} is contained in the range [\var{start},
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
559 \var{end}). Optional arguments \var{start} and \var{end} are
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
560 interpreted as in slice notation. Return \code{-1} if \var{sub} is
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
561 not found.
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
562 \end{methoddesc}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
563
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
564 \begin{methoddesc}[string]{index}{sub\optional{, start\optional{, end}}}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
565 Like \method{find()}, but raise \exception{ValueError} when the
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
566 substring is not found.
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
567 \end{methoddesc}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
568
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
569 \begin{methoddesc}[string]{isalnum}{}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
570 Return true if all characters in the string are alphanumeric and there
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
571 is at least one character, false otherwise.
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
572 \end{methoddesc}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
573
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
574 \begin{methoddesc}[string]{isalpha}{}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
575 Return true if all characters in the string are alphabetic and there
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
576 is at least one character, false otherwise.
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
577 \end{methoddesc}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
578
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
579 \begin{methoddesc}[string]{isdigit}{}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
580 Return true if there are only digit characters, false otherwise.
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
581 \end{methoddesc}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
582
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
583 \begin{methoddesc}[string]{islower}{}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
584 Return true if all cased characters in the string are lowercase and
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
585 there is at least one cased character, false otherwise.
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
586 \end{methoddesc}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
587
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
588 \begin{methoddesc}[string]{isspace}{}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
589 Return true if there are only whitespace characters in the string and
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
590 the string is not empty, false otherwise.
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
591 \end{methoddesc}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
592
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
593 \begin{methoddesc}[string]{istitle}{}
18416
33b4357aebb8 Fix up a few style nits -- avoid "e.g." and "i.e." -- these make
Fred Drake <fdrake@acm.org>
parents: 18395
diff changeset
594 Return true if the string is a titlecased string: uppercase
13933
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
595 characters may only follow uncased characters and lowercase characters
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
596 only cased ones. Return false otherwise.
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
597 \end{methoddesc}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
598
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
599 \begin{methoddesc}[string]{isupper}{}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
600 Return true if all cased characters in the string are uppercase and
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
601 there is at least one cased character, false otherwise.
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
602 \end{methoddesc}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
603
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
604 \begin{methoddesc}[string]{join}{seq}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
605 Return a string which is the concatenation of the strings in the
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
606 sequence \var{seq}. The separator between elements is the string
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
607 providing this method.
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
608 \end{methoddesc}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
609
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
610 \begin{methoddesc}[string]{ljust}{width}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
611 Return the string left justified in a string of length \var{width}.
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
612 Padding is done using spaces. The original string is returned if
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
613 \var{width} is less than \code{len(\var{s})}.
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
614 \end{methoddesc}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
615
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
616 \begin{methoddesc}[string]{lower}{}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
617 Return a copy of the string converted to lowercase.
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
618 \end{methoddesc}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
619
23147
dbf013cc3dee backport fdrake's patch:
Anthony Baxter <anthonybaxter@gmail.com>
parents: 22340
diff changeset
620 \begin{methoddesc}[string]{lstrip}{\optional{chars}}
dbf013cc3dee backport fdrake's patch:
Anthony Baxter <anthonybaxter@gmail.com>
parents: 22340
diff changeset
621 Return a copy of the string with leading characters removed. If
dbf013cc3dee backport fdrake's patch:
Anthony Baxter <anthonybaxter@gmail.com>
parents: 22340
diff changeset
622 \var{chars} is omitted or \code{None}, whitespace characters are
dbf013cc3dee backport fdrake's patch:
Anthony Baxter <anthonybaxter@gmail.com>
parents: 22340
diff changeset
623 removed. If given and not \code{None}, \var{chars} must be a string;
dbf013cc3dee backport fdrake's patch:
Anthony Baxter <anthonybaxter@gmail.com>
parents: 22340
diff changeset
624 the characters in the string will be stripped from the beginning of
dbf013cc3dee backport fdrake's patch:
Anthony Baxter <anthonybaxter@gmail.com>
parents: 22340
diff changeset
625 the string this method is called on.
26261
205fbf1bd075 Note that str.zfill() and the optional argument to str.strip(),
Fred Drake <fdrake@acm.org>
parents: 25907
diff changeset
626 \versionchanged[Support for the \var{chars} argument]{2.2.2}
13933
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
627 \end{methoddesc}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
628
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
629 \begin{methoddesc}[string]{replace}{old, new\optional{, maxsplit}}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
630 Return a copy of the string with all occurrences of substring
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
631 \var{old} replaced by \var{new}. If the optional argument
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
632 \var{maxsplit} is given, only the first \var{maxsplit} occurrences are
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
633 replaced.
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
634 \end{methoddesc}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
635
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
636 \begin{methoddesc}[string]{rfind}{sub \optional{,start \optional{,end}}}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
637 Return the highest index in the string where substring \var{sub} is
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
638 found, such that \var{sub} is contained within s[start,end]. Optional
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
639 arguments \var{start} and \var{end} are interpreted as in slice
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
640 notation. Return \code{-1} on failure.
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
641 \end{methoddesc}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
642
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
643 \begin{methoddesc}[string]{rindex}{sub\optional{, start\optional{, end}}}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
644 Like \method{rfind()} but raises \exception{ValueError} when the
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
645 substring \var{sub} is not found.
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
646 \end{methoddesc}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
647
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
648 \begin{methoddesc}[string]{rjust}{width}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
649 Return the string right justified in a string of length \var{width}.
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
650 Padding is done using spaces. The original string is returned if
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
651 \var{width} is less than \code{len(\var{s})}.
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
652 \end{methoddesc}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
653
23147
dbf013cc3dee backport fdrake's patch:
Anthony Baxter <anthonybaxter@gmail.com>
parents: 22340
diff changeset
654 \begin{methoddesc}[string]{rstrip}{\optional{chars}}
dbf013cc3dee backport fdrake's patch:
Anthony Baxter <anthonybaxter@gmail.com>
parents: 22340
diff changeset
655 Return a copy of the string with trailing characters removed. If
dbf013cc3dee backport fdrake's patch:
Anthony Baxter <anthonybaxter@gmail.com>
parents: 22340
diff changeset
656 \var{chars} is omitted or \code{None}, whitespace characters are
dbf013cc3dee backport fdrake's patch:
Anthony Baxter <anthonybaxter@gmail.com>
parents: 22340
diff changeset
657 removed. If given and not \code{None}, \var{chars} must be a string;
dbf013cc3dee backport fdrake's patch:
Anthony Baxter <anthonybaxter@gmail.com>
parents: 22340
diff changeset
658 the characters in the string will be stripped from the end of the
dbf013cc3dee backport fdrake's patch:
Anthony Baxter <anthonybaxter@gmail.com>
parents: 22340
diff changeset
659 string this method is called on.
26261
205fbf1bd075 Note that str.zfill() and the optional argument to str.strip(),
Fred Drake <fdrake@acm.org>
parents: 25907
diff changeset
660 \versionchanged[Support for the \var{chars} argument]{2.2.2}
13933
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
661 \end{methoddesc}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
662
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
663 \begin{methoddesc}[string]{split}{\optional{sep \optional{,maxsplit}}}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
664 Return a list of the words in the string, using \var{sep} as the
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
665 delimiter string. If \var{maxsplit} is given, at most \var{maxsplit}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
666 splits are done. If \var{sep} is not specified or \code{None}, any
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
667 whitespace string is a separator.
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
668 \end{methoddesc}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
669
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
670 \begin{methoddesc}[string]{splitlines}{\optional{keepends}}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
671 Return a list of the lines in the string, breaking at line
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
672 boundaries. Line breaks are not included in the resulting list unless
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
673 \var{keepends} is given and true.
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
674 \end{methoddesc}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
675
23147
dbf013cc3dee backport fdrake's patch:
Anthony Baxter <anthonybaxter@gmail.com>
parents: 22340
diff changeset
676 \begin{methoddesc}[string]{startswith}{prefix\optional{,
dbf013cc3dee backport fdrake's patch:
Anthony Baxter <anthonybaxter@gmail.com>
parents: 22340
diff changeset
677 start\optional{, end}}}
13933
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
678 Return true if string starts with the \var{prefix}, otherwise
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
679 return false. With optional \var{start}, test string beginning at
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
680 that position. With optional \var{end}, stop comparing string at that
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
681 position.
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
682 \end{methoddesc}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
683
23147
dbf013cc3dee backport fdrake's patch:
Anthony Baxter <anthonybaxter@gmail.com>
parents: 22340
diff changeset
684 \begin{methoddesc}[string]{strip}{\optional{chars}}
dbf013cc3dee backport fdrake's patch:
Anthony Baxter <anthonybaxter@gmail.com>
parents: 22340
diff changeset
685 Return a copy of the string with leading and trailing characters
dbf013cc3dee backport fdrake's patch:
Anthony Baxter <anthonybaxter@gmail.com>
parents: 22340
diff changeset
686 removed. If \var{chars} is omitted or \code{None}, whitespace
dbf013cc3dee backport fdrake's patch:
Anthony Baxter <anthonybaxter@gmail.com>
parents: 22340
diff changeset
687 characters are removed. If given and not \code{None}, \var{chars}
dbf013cc3dee backport fdrake's patch:
Anthony Baxter <anthonybaxter@gmail.com>
parents: 22340
diff changeset
688 must be a string; the characters in the string will be stripped from
dbf013cc3dee backport fdrake's patch:
Anthony Baxter <anthonybaxter@gmail.com>
parents: 22340
diff changeset
689 the both ends of the string this method is called on.
26261
205fbf1bd075 Note that str.zfill() and the optional argument to str.strip(),
Fred Drake <fdrake@acm.org>
parents: 25907
diff changeset
690 \versionchanged[Support for the \var{chars} argument]{2.2.2}
13933
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
691 \end{methoddesc}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
692
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
693 \begin{methoddesc}[string]{swapcase}{}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
694 Return a copy of the string with uppercase characters converted to
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
695 lowercase and vice versa.
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
696 \end{methoddesc}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
697
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
698 \begin{methoddesc}[string]{title}{}
18416
33b4357aebb8 Fix up a few style nits -- avoid "e.g." and "i.e." -- these make
Fred Drake <fdrake@acm.org>
parents: 18395
diff changeset
699 Return a titlecased version of the string: words start with uppercase
13933
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
700 characters, all remaining cased characters are lowercase.
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
701 \end{methoddesc}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
702
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
703 \begin{methoddesc}[string]{translate}{table\optional{, deletechars}}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
704 Return a copy of the string where all characters occurring in the
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
705 optional argument \var{deletechars} are removed, and the remaining
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
706 characters have been mapped through the given translation table, which
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
707 must be a string of length 256.
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
708 \end{methoddesc}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
709
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
710 \begin{methoddesc}[string]{upper}{}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
711 Return a copy of the string converted to uppercase.
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
712 \end{methoddesc}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
713
23219
b08b51dce264 Backport the following changes:
Walter Dörwald <walter@livinglogic.de>
parents: 23147
diff changeset
714 \begin{methoddesc}[string]{zfill}{width}
b08b51dce264 Backport the following changes:
Walter Dörwald <walter@livinglogic.de>
parents: 23147
diff changeset
715 Return the numeric string left filled with zeros in a string
b08b51dce264 Backport the following changes:
Walter Dörwald <walter@livinglogic.de>
parents: 23147
diff changeset
716 of length \var{width}. The original string is returned if
b08b51dce264 Backport the following changes:
Walter Dörwald <walter@livinglogic.de>
parents: 23147
diff changeset
717 \var{width} is less than \code{len(\var{s})}.
26261
205fbf1bd075 Note that str.zfill() and the optional argument to str.strip(),
Fred Drake <fdrake@acm.org>
parents: 25907
diff changeset
718 \versionadded{2.2.2}
23219
b08b51dce264 Backport the following changes:
Walter Dörwald <walter@livinglogic.de>
parents: 23147
diff changeset
719 \end{methoddesc}
b08b51dce264 Backport the following changes:
Walter Dörwald <walter@livinglogic.de>
parents: 23147
diff changeset
720
13933
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
721
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
722 \subsubsection{String Formatting Operations \label{typesseq-strings}}
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
723
21177
7d1eac41ce3e Slightly improved indexing for the string-% operator, thanks to comments
Fred Drake <fdrake@acm.org>
parents: 21163
diff changeset
724 \index{formatting, string (\%{})}
21572
812d1543ba08 Added index entries similar to some recommended by Skip, and used the word
Fred Drake <fdrake@acm.org>
parents: 21332
diff changeset
725 \index{interpolation, string (\%{})}
14552
a8d1c030b19f Add some index entries to make it easier to find information on
Fred Drake <fdrake@acm.org>
parents: 14520
diff changeset
726 \index{string!formatting}
21572
812d1543ba08 Added index entries similar to some recommended by Skip, and used the word
Fred Drake <fdrake@acm.org>
parents: 21332
diff changeset
727 \index{string!interpolation}
14552
a8d1c030b19f Add some index entries to make it easier to find information on
Fred Drake <fdrake@acm.org>
parents: 14520
diff changeset
728 \index{printf-style formatting}
a8d1c030b19f Add some index entries to make it easier to find information on
Fred Drake <fdrake@acm.org>
parents: 14520
diff changeset
729 \index{sprintf-style formatting}
21177
7d1eac41ce3e Slightly improved indexing for the string-% operator, thanks to comments
Fred Drake <fdrake@acm.org>
parents: 21163
diff changeset
730 \index{\protect\%{} formatting}
21572
812d1543ba08 Added index entries similar to some recommended by Skip, and used the word
Fred Drake <fdrake@acm.org>
parents: 21332
diff changeset
731 \index{\protect\%{} interpolation}
14552
a8d1c030b19f Add some index entries to make it easier to find information on
Fred Drake <fdrake@acm.org>
parents: 14520
diff changeset
732
16285
15e0c10092bb Massively improved documentation for string formatting operations,
Fred Drake <fdrake@acm.org>
parents: 15926
diff changeset
733 String and Unicode objects have one unique built-in operation: the
21572
812d1543ba08 Added index entries similar to some recommended by Skip, and used the word
Fred Drake <fdrake@acm.org>
parents: 21332
diff changeset
734 \code{\%} operator (modulo). This is also known as the string
812d1543ba08 Added index entries similar to some recommended by Skip, and used the word
Fred Drake <fdrake@acm.org>
parents: 21332
diff changeset
735 \emph{formatting} or \emph{interpolation} operator. Given
812d1543ba08 Added index entries similar to some recommended by Skip, and used the word
Fred Drake <fdrake@acm.org>
parents: 21332
diff changeset
736 \code{\var{format} \% \var{values}} (where \var{format} is a string or
812d1543ba08 Added index entries similar to some recommended by Skip, and used the word
Fred Drake <fdrake@acm.org>
parents: 21332
diff changeset
737 Unicode object), \code{\%} conversion specifications in \var{format}
812d1543ba08 Added index entries similar to some recommended by Skip, and used the word
Fred Drake <fdrake@acm.org>
parents: 21332
diff changeset
738 are replaced with zero or more elements of \var{values}. The effect
812d1543ba08 Added index entries similar to some recommended by Skip, and used the word
Fred Drake <fdrake@acm.org>
parents: 21332
diff changeset
739 is similar to the using \cfunction{sprintf()} in the C language. If
812d1543ba08 Added index entries similar to some recommended by Skip, and used the word
Fred Drake <fdrake@acm.org>
parents: 21332
diff changeset
740 \var{format} is a Unicode object, or if any of the objects being
812d1543ba08 Added index entries similar to some recommended by Skip, and used the word
Fred Drake <fdrake@acm.org>
parents: 21332
diff changeset
741 converted using the \code{\%s} conversion are Unicode objects, the
812d1543ba08 Added index entries similar to some recommended by Skip, and used the word
Fred Drake <fdrake@acm.org>
parents: 21332
diff changeset
742 result will be a Unicode object as well.
16285
15e0c10092bb Massively improved documentation for string formatting operations,
Fred Drake <fdrake@acm.org>
parents: 15926
diff changeset
743
15e0c10092bb Massively improved documentation for string formatting operations,
Fred Drake <fdrake@acm.org>
parents: 15926
diff changeset
744 If \var{format} requires a single argument, \var{values} may be a
15e0c10092bb Massively improved documentation for string formatting operations,
Fred Drake <fdrake@acm.org>
parents: 15926
diff changeset
745 single non-tuple object. \footnote{A tuple object in this case should
15e0c10092bb Massively improved documentation for string formatting operations,
Fred Drake <fdrake@acm.org>
parents: 15926
diff changeset
746 be a singleton.} Otherwise, \var{values} must be a tuple with
15e0c10092bb Massively improved documentation for string formatting operations,
Fred Drake <fdrake@acm.org>
parents: 15926
diff changeset
747 exactly the number of items specified by the format string, or a
15e0c10092bb Massively improved documentation for string formatting operations,
Fred Drake <fdrake@acm.org>
parents: 15926
diff changeset
748 single mapping object (for example, a dictionary).
15e0c10092bb Massively improved documentation for string formatting operations,
Fred Drake <fdrake@acm.org>
parents: 15926
diff changeset
749
15e0c10092bb Massively improved documentation for string formatting operations,
Fred Drake <fdrake@acm.org>
parents: 15926
diff changeset
750 A conversion specifier contains two or more characters and has the
15e0c10092bb Massively improved documentation for string formatting operations,
Fred Drake <fdrake@acm.org>
parents: 15926
diff changeset
751 following components, which must occur in this order:
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
752
16285
15e0c10092bb Massively improved documentation for string formatting operations,
Fred Drake <fdrake@acm.org>
parents: 15926
diff changeset
753 \begin{enumerate}
15e0c10092bb Massively improved documentation for string formatting operations,
Fred Drake <fdrake@acm.org>
parents: 15926
diff changeset
754 \item The \character{\%} character, which marks the start of the
15e0c10092bb Massively improved documentation for string formatting operations,
Fred Drake <fdrake@acm.org>
parents: 15926
diff changeset
755 specifier.
15e0c10092bb Massively improved documentation for string formatting operations,
Fred Drake <fdrake@acm.org>
parents: 15926
diff changeset
756 \item Mapping key value (optional), consisting of an identifier in
15e0c10092bb Massively improved documentation for string formatting operations,
Fred Drake <fdrake@acm.org>
parents: 15926
diff changeset
757 parentheses (for example, \code{(somename)}).
15e0c10092bb Massively improved documentation for string formatting operations,
Fred Drake <fdrake@acm.org>
parents: 15926
diff changeset
758 \item Conversion flags (optional), which affect the result of some
15e0c10092bb Massively improved documentation for string formatting operations,
Fred Drake <fdrake@acm.org>
parents: 15926
diff changeset
759 conversion types.
15e0c10092bb Massively improved documentation for string formatting operations,
Fred Drake <fdrake@acm.org>
parents: 15926
diff changeset
760 \item Minimum field width (optional). If specified as an
15e0c10092bb Massively improved documentation for string formatting operations,
Fred Drake <fdrake@acm.org>
parents: 15926
diff changeset
761 \character{*} (asterisk), the actual width is read from the
15e0c10092bb Massively improved documentation for string formatting operations,
Fred Drake <fdrake@acm.org>
parents: 15926
diff changeset
762 next element of the tuple in \var{values}, and the object to
15e0c10092bb Massively improved documentation for string formatting operations,
Fred Drake <fdrake@acm.org>
parents: 15926
diff changeset
763 convert comes after the minimum field width and optional
15e0c10092bb Massively improved documentation for string formatting operations,
Fred Drake <fdrake@acm.org>
parents: 15926
diff changeset
764 precision.
15e0c10092bb Massively improved documentation for string formatting operations,
Fred Drake <fdrake@acm.org>
parents: 15926
diff changeset
765 \item Precision (optional), given as a \character{.} (dot) followed
15e0c10092bb Massively improved documentation for string formatting operations,
Fred Drake <fdrake@acm.org>
parents: 15926
diff changeset
766 by the precision. If specified as \character{*} (an
15e0c10092bb Massively improved documentation for string formatting operations,
Fred Drake <fdrake@acm.org>
parents: 15926
diff changeset
767 asterisk), the actual width is read from the next element of
15e0c10092bb Massively improved documentation for string formatting operations,
Fred Drake <fdrake@acm.org>
parents: 15926
diff changeset
768 the tuple in \var{values}, and the value to convert comes after
15e0c10092bb Massively improved documentation for string formatting operations,
Fred Drake <fdrake@acm.org>
parents: 15926
diff changeset
769 the precision.
15e0c10092bb Massively improved documentation for string formatting operations,
Fred Drake <fdrake@acm.org>
parents: 15926
diff changeset
770 \item Length modifier (optional).
15e0c10092bb Massively improved documentation for string formatting operations,
Fred Drake <fdrake@acm.org>
parents: 15926
diff changeset
771 \item Conversion type.
15e0c10092bb Massively improved documentation for string formatting operations,
Fred Drake <fdrake@acm.org>
parents: 15926
diff changeset
772 \end{enumerate}
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
773
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
774 If the right argument is a dictionary (or any kind of mapping), then
16285
15e0c10092bb Massively improved documentation for string formatting operations,
Fred Drake <fdrake@acm.org>
parents: 15926
diff changeset
775 the formats in the string \emph{must} have a parenthesized key into
15e0c10092bb Massively improved documentation for string formatting operations,
Fred Drake <fdrake@acm.org>
parents: 15926
diff changeset
776 that dictionary inserted immediately after the \character{\%}
15e0c10092bb Massively improved documentation for string formatting operations,
Fred Drake <fdrake@acm.org>
parents: 15926
diff changeset
777 character, and each format formats the corresponding entry from the
15e0c10092bb Massively improved documentation for string formatting operations,
Fred Drake <fdrake@acm.org>
parents: 15926
diff changeset
778 mapping. For example:
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
779
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
780 \begin{verbatim}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
781 >>> count = 2
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
782 >>> language = 'Python'
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
783 >>> print '%(language)s has %(count)03d quote types.' % vars()
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
784 Python has 002 quote types.
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
785 \end{verbatim}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
786
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
787 In this case no \code{*} specifiers may occur in a format (since they
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
788 require a sequential parameter list).
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
789
16285
15e0c10092bb Massively improved documentation for string formatting operations,
Fred Drake <fdrake@acm.org>
parents: 15926
diff changeset
790 The conversion flag characters are:
15e0c10092bb Massively improved documentation for string formatting operations,
Fred Drake <fdrake@acm.org>
parents: 15926
diff changeset
791
15e0c10092bb Massively improved documentation for string formatting operations,
Fred Drake <fdrake@acm.org>
parents: 15926
diff changeset
792 \begin{tableii}{c|l}{character}{Flag}{Meaning}
15e0c10092bb Massively improved documentation for string formatting operations,
Fred Drake <fdrake@acm.org>
parents: 15926
diff changeset
793 \lineii{\#}{The value conversion will use the ``alternate form''
15e0c10092bb Massively improved documentation for string formatting operations,
Fred Drake <fdrake@acm.org>
parents: 15926
diff changeset
794 (where defined below).}
15e0c10092bb Massively improved documentation for string formatting operations,
Fred Drake <fdrake@acm.org>
parents: 15926
diff changeset
795 \lineii{0}{The conversion will be zero padded.}
15e0c10092bb Massively improved documentation for string formatting operations,
Fred Drake <fdrake@acm.org>
parents: 15926
diff changeset
796 \lineii{-}{The converted value is left adjusted (overrides
25907
6ea9eef99108 - The "-" format flag overrides the "0" flag, not the "-" flag.
Fred Drake <fdrake@acm.org>
parents: 25586
diff changeset
797 the \character{0} conversion if both are given).}
16285
15e0c10092bb Massively improved documentation for string formatting operations,
Fred Drake <fdrake@acm.org>
parents: 15926
diff changeset
798 \lineii{{~}}{(a space) A blank should be left before a positive number
15e0c10092bb Massively improved documentation for string formatting operations,
Fred Drake <fdrake@acm.org>
parents: 15926
diff changeset
799 (or empty string) produced by a signed conversion.}
15e0c10092bb Massively improved documentation for string formatting operations,
Fred Drake <fdrake@acm.org>
parents: 15926
diff changeset
800 \lineii{+}{A sign character (\character{+} or \character{-}) will
15e0c10092bb Massively improved documentation for string formatting operations,
Fred Drake <fdrake@acm.org>
parents: 15926
diff changeset
801 precede the conversion (overrides a "space" flag).}
15e0c10092bb Massively improved documentation for string formatting operations,
Fred Drake <fdrake@acm.org>
parents: 15926
diff changeset
802 \end{tableii}
15e0c10092bb Massively improved documentation for string formatting operations,
Fred Drake <fdrake@acm.org>
parents: 15926
diff changeset
803
15e0c10092bb Massively improved documentation for string formatting operations,
Fred Drake <fdrake@acm.org>
parents: 15926
diff changeset
804 The length modifier may be \code{h}, \code{l}, and \code{L} may be
15e0c10092bb Massively improved documentation for string formatting operations,
Fred Drake <fdrake@acm.org>
parents: 15926
diff changeset
805 present, but are ignored as they are not necessary for Python.
15e0c10092bb Massively improved documentation for string formatting operations,
Fred Drake <fdrake@acm.org>
parents: 15926
diff changeset
806
15e0c10092bb Massively improved documentation for string formatting operations,
Fred Drake <fdrake@acm.org>
parents: 15926
diff changeset
807 The conversion types are:
15e0c10092bb Massively improved documentation for string formatting operations,
Fred Drake <fdrake@acm.org>
parents: 15926
diff changeset
808
25907
6ea9eef99108 - The "-" format flag overrides the "0" flag, not the "-" flag.
Fred Drake <fdrake@acm.org>
parents: 25586
diff changeset
809 \begin{tableiii}{c|l|c}{character}{Conversion}{Meaning}{Notes}
6ea9eef99108 - The "-" format flag overrides the "0" flag, not the "-" flag.
Fred Drake <fdrake@acm.org>
parents: 25586
diff changeset
810 \lineiii{d}{Signed integer decimal.}{}
6ea9eef99108 - The "-" format flag overrides the "0" flag, not the "-" flag.
Fred Drake <fdrake@acm.org>
parents: 25586
diff changeset
811 \lineiii{i}{Signed integer decimal.}{}
6ea9eef99108 - The "-" format flag overrides the "0" flag, not the "-" flag.
Fred Drake <fdrake@acm.org>
parents: 25586
diff changeset
812 \lineiii{o}{Unsigned octal.}{(1)}
6ea9eef99108 - The "-" format flag overrides the "0" flag, not the "-" flag.
Fred Drake <fdrake@acm.org>
parents: 25586
diff changeset
813 \lineiii{u}{Unsigned decimal.}{}
6ea9eef99108 - The "-" format flag overrides the "0" flag, not the "-" flag.
Fred Drake <fdrake@acm.org>
parents: 25586
diff changeset
814 \lineiii{x}{Unsigned hexidecimal (lowercase).}{(2)}
6ea9eef99108 - The "-" format flag overrides the "0" flag, not the "-" flag.
Fred Drake <fdrake@acm.org>
parents: 25586
diff changeset
815 \lineiii{X}{Unsigned hexidecimal (uppercase).}{(2)}
6ea9eef99108 - The "-" format flag overrides the "0" flag, not the "-" flag.
Fred Drake <fdrake@acm.org>
parents: 25586
diff changeset
816 \lineiii{e}{Floating point exponential format (lowercase).}{}
6ea9eef99108 - The "-" format flag overrides the "0" flag, not the "-" flag.
Fred Drake <fdrake@acm.org>
parents: 25586
diff changeset
817 \lineiii{E}{Floating point exponential format (uppercase).}{}
6ea9eef99108 - The "-" format flag overrides the "0" flag, not the "-" flag.
Fred Drake <fdrake@acm.org>
parents: 25586
diff changeset
818 \lineiii{f}{Floating point decimal format.}{}
6ea9eef99108 - The "-" format flag overrides the "0" flag, not the "-" flag.
Fred Drake <fdrake@acm.org>
parents: 25586
diff changeset
819 \lineiii{F}{Floating point decimal format.}{}
6ea9eef99108 - The "-" format flag overrides the "0" flag, not the "-" flag.
Fred Drake <fdrake@acm.org>
parents: 25586
diff changeset
820 \lineiii{g}{Same as \character{e} if exponent is greater than -4 or
6ea9eef99108 - The "-" format flag overrides the "0" flag, not the "-" flag.
Fred Drake <fdrake@acm.org>
parents: 25586
diff changeset
821 less than precision, \character{f} otherwise.}{}
6ea9eef99108 - The "-" format flag overrides the "0" flag, not the "-" flag.
Fred Drake <fdrake@acm.org>
parents: 25586
diff changeset
822 \lineiii{G}{Same as \character{E} if exponent is greater than -4 or
6ea9eef99108 - The "-" format flag overrides the "0" flag, not the "-" flag.
Fred Drake <fdrake@acm.org>
parents: 25586
diff changeset
823 less than precision, \character{F} otherwise.}{}
6ea9eef99108 - The "-" format flag overrides the "0" flag, not the "-" flag.
Fred Drake <fdrake@acm.org>
parents: 25586
diff changeset
824 \lineiii{c}{Single character (accepts integer or single character
6ea9eef99108 - The "-" format flag overrides the "0" flag, not the "-" flag.
Fred Drake <fdrake@acm.org>
parents: 25586
diff changeset
825 string).}{}
6ea9eef99108 - The "-" format flag overrides the "0" flag, not the "-" flag.
Fred Drake <fdrake@acm.org>
parents: 25586
diff changeset
826 \lineiii{r}{String (converts any python object using
6ea9eef99108 - The "-" format flag overrides the "0" flag, not the "-" flag.
Fred Drake <fdrake@acm.org>
parents: 25586
diff changeset
827 \function{repr()}).}{(3)}
6ea9eef99108 - The "-" format flag overrides the "0" flag, not the "-" flag.
Fred Drake <fdrake@acm.org>
parents: 25586
diff changeset
828 \lineiii{s}{String (converts any python object using
6ea9eef99108 - The "-" format flag overrides the "0" flag, not the "-" flag.
Fred Drake <fdrake@acm.org>
parents: 25586
diff changeset
829 \function{str()}).}{}
6ea9eef99108 - The "-" format flag overrides the "0" flag, not the "-" flag.
Fred Drake <fdrake@acm.org>
parents: 25586
diff changeset
830 \lineiii{\%}{No argument is converted, results in a \character{\%}
6ea9eef99108 - The "-" format flag overrides the "0" flag, not the "-" flag.
Fred Drake <fdrake@acm.org>
parents: 25586
diff changeset
831 character in the result.}{}
6ea9eef99108 - The "-" format flag overrides the "0" flag, not the "-" flag.
Fred Drake <fdrake@acm.org>
parents: 25586
diff changeset
832 \end{tableiii}
6ea9eef99108 - The "-" format flag overrides the "0" flag, not the "-" flag.
Fred Drake <fdrake@acm.org>
parents: 25586
diff changeset
833
6ea9eef99108 - The "-" format flag overrides the "0" flag, not the "-" flag.
Fred Drake <fdrake@acm.org>
parents: 25586
diff changeset
834 \noindent
6ea9eef99108 - The "-" format flag overrides the "0" flag, not the "-" flag.
Fred Drake <fdrake@acm.org>
parents: 25586
diff changeset
835 Notes:
6ea9eef99108 - The "-" format flag overrides the "0" flag, not the "-" flag.
Fred Drake <fdrake@acm.org>
parents: 25586
diff changeset
836 \begin{description}
6ea9eef99108 - The "-" format flag overrides the "0" flag, not the "-" flag.
Fred Drake <fdrake@acm.org>
parents: 25586
diff changeset
837 \item[(1)]
6ea9eef99108 - The "-" format flag overrides the "0" flag, not the "-" flag.
Fred Drake <fdrake@acm.org>
parents: 25586
diff changeset
838 The alternate form causes a leading zero (\character{0}) to be
6ea9eef99108 - The "-" format flag overrides the "0" flag, not the "-" flag.
Fred Drake <fdrake@acm.org>
parents: 25586
diff changeset
839 inserted between left-hand padding and the formatting of the
6ea9eef99108 - The "-" format flag overrides the "0" flag, not the "-" flag.
Fred Drake <fdrake@acm.org>
parents: 25586
diff changeset
840 number if the leading character of the result is not already a
6ea9eef99108 - The "-" format flag overrides the "0" flag, not the "-" flag.
Fred Drake <fdrake@acm.org>
parents: 25586
diff changeset
841 zero.
6ea9eef99108 - The "-" format flag overrides the "0" flag, not the "-" flag.
Fred Drake <fdrake@acm.org>
parents: 25586
diff changeset
842 \item[(2)]
6ea9eef99108 - The "-" format flag overrides the "0" flag, not the "-" flag.
Fred Drake <fdrake@acm.org>
parents: 25586
diff changeset
843 The alternate form causes a leading \code{'0x'} or \code{'0X'}
6ea9eef99108 - The "-" format flag overrides the "0" flag, not the "-" flag.
Fred Drake <fdrake@acm.org>
parents: 25586
diff changeset
844 (depending on whether the \character{x} or \character{X} format
6ea9eef99108 - The "-" format flag overrides the "0" flag, not the "-" flag.
Fred Drake <fdrake@acm.org>
parents: 25586
diff changeset
845 was used) to be inserted between left-hand padding and the
6ea9eef99108 - The "-" format flag overrides the "0" flag, not the "-" flag.
Fred Drake <fdrake@acm.org>
parents: 25586
diff changeset
846 formatting of the number if the leading character of the result is
6ea9eef99108 - The "-" format flag overrides the "0" flag, not the "-" flag.
Fred Drake <fdrake@acm.org>
parents: 25586
diff changeset
847 not already a zero.
6ea9eef99108 - The "-" format flag overrides the "0" flag, not the "-" flag.
Fred Drake <fdrake@acm.org>
parents: 25586
diff changeset
848 \item[(3)]
6ea9eef99108 - The "-" format flag overrides the "0" flag, not the "-" flag.
Fred Drake <fdrake@acm.org>
parents: 25586
diff changeset
849 The \code{\%r} conversion was added in Python 2.0.
6ea9eef99108 - The "-" format flag overrides the "0" flag, not the "-" flag.
Fred Drake <fdrake@acm.org>
parents: 25586
diff changeset
850 \end{description}
16285
15e0c10092bb Massively improved documentation for string formatting operations,
Fred Drake <fdrake@acm.org>
parents: 15926
diff changeset
851
15e0c10092bb Massively improved documentation for string formatting operations,
Fred Drake <fdrake@acm.org>
parents: 15926
diff changeset
852 % XXX Examples?
15e0c10092bb Massively improved documentation for string formatting operations,
Fred Drake <fdrake@acm.org>
parents: 15926
diff changeset
853
15e0c10092bb Massively improved documentation for string formatting operations,
Fred Drake <fdrake@acm.org>
parents: 15926
diff changeset
854 Since Python strings have an explicit length, \code{\%s} conversions
15e0c10092bb Massively improved documentation for string formatting operations,
Fred Drake <fdrake@acm.org>
parents: 15926
diff changeset
855 do not assume that \code{'\e0'} is the end of the string.
15e0c10092bb Massively improved documentation for string formatting operations,
Fred Drake <fdrake@acm.org>
parents: 15926
diff changeset
856
15e0c10092bb Massively improved documentation for string formatting operations,
Fred Drake <fdrake@acm.org>
parents: 15926
diff changeset
857 For safety reasons, floating point precisions are clipped to 50;
15e0c10092bb Massively improved documentation for string formatting operations,
Fred Drake <fdrake@acm.org>
parents: 15926
diff changeset
858 \code{\%f} conversions for numbers whose absolute value is over 1e25
15e0c10092bb Massively improved documentation for string formatting operations,
Fred Drake <fdrake@acm.org>
parents: 15926
diff changeset
859 are replaced by \code{\%g} conversions.\footnote{
15e0c10092bb Massively improved documentation for string formatting operations,
Fred Drake <fdrake@acm.org>
parents: 15926
diff changeset
860 These numbers are fairly arbitrary. They are intended to
15e0c10092bb Massively improved documentation for string formatting operations,
Fred Drake <fdrake@acm.org>
parents: 15926
diff changeset
861 avoid printing endless strings of meaningless digits without hampering
15e0c10092bb Massively improved documentation for string formatting operations,
Fred Drake <fdrake@acm.org>
parents: 15926
diff changeset
862 correct use and without having to know the exact precision of floating
15e0c10092bb Massively improved documentation for string formatting operations,
Fred Drake <fdrake@acm.org>
parents: 15926
diff changeset
863 point values on a particular machine.
15e0c10092bb Massively improved documentation for string formatting operations,
Fred Drake <fdrake@acm.org>
parents: 15926
diff changeset
864 } All other errors raise exceptions.
15e0c10092bb Massively improved documentation for string formatting operations,
Fred Drake <fdrake@acm.org>
parents: 15926
diff changeset
865
21163
7b6879714b74 Make no assumption about how modules are built when referring to them; this
Fred Drake <fdrake@acm.org>
parents: 21159
diff changeset
866 Additional string operations are defined in standard modules
7b6879714b74 Make no assumption about how modules are built when referring to them; this
Fred Drake <fdrake@acm.org>
parents: 21159
diff changeset
867 \refmodule{string}\refstmodindex{string} and
22340
7ecc49117d7e Take Tim's work on file.truncate out of 2.2.1 again.
Michael W. Hudson <mwh@python.net>
parents: 22337
diff changeset
868 \refmodule{re}.\refstmodindex{re}
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
869
13967
7b7ee58901fb Document the range type, as suggested by Denis S. Otkidach
Fred Drake <fdrake@acm.org>
parents: 13933
diff changeset
870
14044
a905c5aa0691 As pointed out by Denis S. Otkidach <den@analyt.chem.msu.ru>, xrange()
Fred Drake <fdrake@acm.org>
parents: 13967
diff changeset
871 \subsubsection{XRange Type \label{typesseq-xrange}}
13967
7b7ee58901fb Document the range type, as suggested by Denis S. Otkidach
Fred Drake <fdrake@acm.org>
parents: 13933
diff changeset
872
15005
0cf5111bf09c Use \obindex{...} instead of \indexii{...}{type} in many places; this is
Fred Drake <fdrake@acm.org>
parents: 14710
diff changeset
873 The xrange\obindex{xrange} type is an immutable sequence which is
14044
a905c5aa0691 As pointed out by Denis S. Otkidach <den@analyt.chem.msu.ru>, xrange()
Fred Drake <fdrake@acm.org>
parents: 13967
diff changeset
874 commonly used for looping. The advantage of the xrange type is that an
a905c5aa0691 As pointed out by Denis S. Otkidach <den@analyt.chem.msu.ru>, xrange()
Fred Drake <fdrake@acm.org>
parents: 13967
diff changeset
875 xrange object will always take the same amount of memory, no matter the
13967
7b7ee58901fb Document the range type, as suggested by Denis S. Otkidach
Fred Drake <fdrake@acm.org>
parents: 13933
diff changeset
876 size of the range it represents. There are no consistent performance
7b7ee58901fb Document the range type, as suggested by Denis S. Otkidach
Fred Drake <fdrake@acm.org>
parents: 13933
diff changeset
877 advantages.
7b7ee58901fb Document the range type, as suggested by Denis S. Otkidach
Fred Drake <fdrake@acm.org>
parents: 13933
diff changeset
878
18391
aadd99830531 Rip out the fancy behaviors of xrange that nobody uses: repeat, slice,
Guido van Rossum <guido@python.org>
parents: 18286
diff changeset
879 XRange objects have very little behavior: they only support indexing
aadd99830531 Rip out the fancy behaviors of xrange that nobody uses: repeat, slice,
Guido van Rossum <guido@python.org>
parents: 18286
diff changeset
880 and the \function{len()} function.
13967
7b7ee58901fb Document the range type, as suggested by Denis S. Otkidach
Fred Drake <fdrake@acm.org>
parents: 13933
diff changeset
881
7b7ee58901fb Document the range type, as suggested by Denis S. Otkidach
Fred Drake <fdrake@acm.org>
parents: 13933
diff changeset
882
10156
0f7d694bc334 Make sure all HTML pages generated from this section have reasonable
Fred Drake <fdrake@acm.org>
parents: 10147
diff changeset
883 \subsubsection{Mutable Sequence Types \label{typesseq-mutable}}
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
884
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
885 List objects support additional operations that allow in-place
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
886 modification of the object.
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
887 These operations would be supported by other mutable sequence types
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
888 (when added to the language) as well.
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
889 Strings and tuples are immutable sequence types and such objects cannot
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
890 be modified once created.
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
891 The following operations are defined on mutable sequence types (where
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
892 \var{x} is an arbitrary object):
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
893 \indexiii{mutable}{sequence}{types}
15005
0cf5111bf09c Use \obindex{...} instead of \indexii{...}{type} in many places; this is
Fred Drake <fdrake@acm.org>
parents: 14710
diff changeset
894 \obindex{list}
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
895
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
896 \begin{tableiii}{c|l|c}{code}{Operation}{Result}{Notes}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
897 \lineiii{\var{s}[\var{i}] = \var{x}}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
898 {item \var{i} of \var{s} is replaced by \var{x}}{}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
899 \lineiii{\var{s}[\var{i}:\var{j}] = \var{t}}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
900 {slice of \var{s} from \var{i} to \var{j} is replaced by \var{t}}{}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
901 \lineiii{del \var{s}[\var{i}:\var{j}]}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
902 {same as \code{\var{s}[\var{i}:\var{j}] = []}}{}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
903 \lineiii{\var{s}.append(\var{x})}
12223
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11463
diff changeset
904 {same as \code{\var{s}[len(\var{s}):len(\var{s})] = [\var{x}]}}{(1)}
9318
8a26e55e18b8 Document the new list.extend() method. Interesting enough, the
Barry Warsaw <barry@python.org>
parents: 9083
diff changeset
905 \lineiii{\var{s}.extend(\var{x})}
12223
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11463
diff changeset
906 {same as \code{\var{s}[len(\var{s}):len(\var{s})] = \var{x}}}{(2)}
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
907 \lineiii{\var{s}.count(\var{x})}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
908 {return number of \var{i}'s for which \code{\var{s}[\var{i}] == \var{x}}}{}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
909 \lineiii{\var{s}.index(\var{x})}
12223
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11463
diff changeset
910 {return smallest \var{i} such that \code{\var{s}[\var{i}] == \var{x}}}{(3)}
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
911 \lineiii{\var{s}.insert(\var{i}, \var{x})}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
912 {same as \code{\var{s}[\var{i}:\var{i}] = [\var{x}]}
20701
5f6850d1f9e8 Explain what [].insert() does when the target index is negative.
Fred Drake <fdrake@acm.org>
parents: 20580
diff changeset
913 if \code{\var{i} >= 0}}{(4)}
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
914 \lineiii{\var{s}.pop(\optional{\var{i}})}
20701
5f6850d1f9e8 Explain what [].insert() does when the target index is negative.
Fred Drake <fdrake@acm.org>
parents: 20580
diff changeset
915 {same as \code{\var{x} = \var{s}[\var{i}]; del \var{s}[\var{i}]; return \var{x}}}{(5)}
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
916 \lineiii{\var{s}.remove(\var{x})}
12223
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11463
diff changeset
917 {same as \code{del \var{s}[\var{s}.index(\var{x})]}}{(3)}
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
918 \lineiii{\var{s}.reverse()}
20701
5f6850d1f9e8 Explain what [].insert() does when the target index is negative.
Fred Drake <fdrake@acm.org>
parents: 20580
diff changeset
919 {reverses the items of \var{s} in place}{(6)}
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
920 \lineiii{\var{s}.sort(\optional{\var{cmpfunc}})}
20701
5f6850d1f9e8 Explain what [].insert() does when the target index is negative.
Fred Drake <fdrake@acm.org>
parents: 20580
diff changeset
921 {sort the items of \var{s} in place}{(6), (7)}
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
922 \end{tableiii}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
923 \indexiv{operations on}{mutable}{sequence}{types}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
924 \indexiii{operations on}{sequence}{types}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
925 \indexiii{operations on}{list}{type}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
926 \indexii{subscript}{assignment}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
927 \indexii{slice}{assignment}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
928 \stindex{del}
10156
0f7d694bc334 Make sure all HTML pages generated from this section have reasonable
Fred Drake <fdrake@acm.org>
parents: 10147
diff changeset
929 \withsubitem{(list method)}{
11183
1e0b1967be7f In note mentioning [].remove()'s exception, tell what exception is
Fred Drake <fdrake@acm.org>
parents: 11100
diff changeset
930 \ttindex{append()}\ttindex{extend()}\ttindex{count()}\ttindex{index()}
1e0b1967be7f In note mentioning [].remove()'s exception, tell what exception is
Fred Drake <fdrake@acm.org>
parents: 11100
diff changeset
931 \ttindex{insert()}\ttindex{pop()}\ttindex{remove()}\ttindex{reverse()}
9523
ed6cacddc6c6 Fix indexing of func_code attribute; this is on a function, not a code
Fred Drake <fdrake@acm.org>
parents: 9461
diff changeset
932 \ttindex{sort()}}
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
933 \noindent
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
934 Notes:
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
935 \begin{description}
12223
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11463
diff changeset
936 \item[(1)] The C implementation of Python has historically accepted
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11463
diff changeset
937 multiple parameters and implicitly joined them into a tuple; this
13222
5dd381aeb23b Update version numbering from 1.6 to 2.0.
Fred Drake <fdrake@acm.org>
parents: 12223
diff changeset
938 no longer works in Python 2.0. Use of this misfeature has been
12223
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11463
diff changeset
939 deprecated since Python 1.4.
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11463
diff changeset
940
22340
7ecc49117d7e Take Tim's work on file.truncate out of 2.2.1 again.
Michael W. Hudson <mwh@python.net>
parents: 22337
diff changeset
941 \item[(2)] Raises an exception when \var{x} is not a list object. The
12223
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11463
diff changeset
942 \method{extend()} method is experimental and not supported by
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11463
diff changeset
943 mutable sequence types other than lists.
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11463
diff changeset
944
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11463
diff changeset
945 \item[(3)] Raises \exception{ValueError} when \var{x} is not found in
11183
1e0b1967be7f In note mentioning [].remove()'s exception, tell what exception is
Fred Drake <fdrake@acm.org>
parents: 11100
diff changeset
946 \var{s}.
1e0b1967be7f In note mentioning [].remove()'s exception, tell what exception is
Fred Drake <fdrake@acm.org>
parents: 11100
diff changeset
947
20701
5f6850d1f9e8 Explain what [].insert() does when the target index is negative.
Fred Drake <fdrake@acm.org>
parents: 20580
diff changeset
948 \item[(4)] When a negative index is passed as the first parameter to
5f6850d1f9e8 Explain what [].insert() does when the target index is negative.
Fred Drake <fdrake@acm.org>
parents: 20580
diff changeset
949 the \method{insert()} method, the new element is prepended to the
5f6850d1f9e8 Explain what [].insert() does when the target index is negative.
Fred Drake <fdrake@acm.org>
parents: 20580
diff changeset
950 sequence.
5f6850d1f9e8 Explain what [].insert() does when the target index is negative.
Fred Drake <fdrake@acm.org>
parents: 20580
diff changeset
951
5f6850d1f9e8 Explain what [].insert() does when the target index is negative.
Fred Drake <fdrake@acm.org>
parents: 20580
diff changeset
952 \item[(5)] The \method{pop()} method is only supported by the list and
13777
b3903e05017f Stop lying about [].pop() being experimental! There is no backing it out
Fred Drake <fdrake@acm.org>
parents: 13772
diff changeset
953 array types. The optional argument \var{i} defaults to \code{-1},
b3903e05017f Stop lying about [].pop() being experimental! There is no backing it out
Fred Drake <fdrake@acm.org>
parents: 13772
diff changeset
954 so that by default the last item is removed and returned.
12223
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11463
diff changeset
955
20701
5f6850d1f9e8 Explain what [].insert() does when the target index is negative.
Fred Drake <fdrake@acm.org>
parents: 20580
diff changeset
956 \item[(6)] The \method{sort()} and \method{reverse()} methods modify the
12223
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11463
diff changeset
957 list in place for economy of space when sorting or reversing a large
18829
1bc1fdf1482b trivial rewording in footnote 5.
Skip Montanaro <skip@pobox.com>
parents: 18416
diff changeset
958 list. To remind you that they operate by side effect, they don't return
1bc1fdf1482b trivial rewording in footnote 5.
Skip Montanaro <skip@pobox.com>
parents: 18416
diff changeset
959 the sorted or reversed list.
12223
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11463
diff changeset
960
20701
5f6850d1f9e8 Explain what [].insert() does when the target index is negative.
Fred Drake <fdrake@acm.org>
parents: 20580
diff changeset
961 \item[(7)] The \method{sort()} method takes an optional argument
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
962 specifying a comparison function of two arguments (list items) which
20173
f100793ca9af The list.sort() docs require a function that returns -1, 0 or +1. That's
Tim Peters <tim.peters@gmail.com>
parents: 20045
diff changeset
963 should return a negative, zero or positive number depending on whether
11183
1e0b1967be7f In note mentioning [].remove()'s exception, tell what exception is
Fred Drake <fdrake@acm.org>
parents: 11100
diff changeset
964 the first argument is considered smaller than, equal to, or larger
1e0b1967be7f In note mentioning [].remove()'s exception, tell what exception is
Fred Drake <fdrake@acm.org>
parents: 11100
diff changeset
965 than the second argument. Note that this slows the sorting process
1e0b1967be7f In note mentioning [].remove()'s exception, tell what exception is
Fred Drake <fdrake@acm.org>
parents: 11100
diff changeset
966 down considerably; e.g. to sort a list in reverse order it is much
1e0b1967be7f In note mentioning [].remove()'s exception, tell what exception is
Fred Drake <fdrake@acm.org>
parents: 11100
diff changeset
967 faster to use calls to the methods \method{sort()} and
1e0b1967be7f In note mentioning [].remove()'s exception, tell what exception is
Fred Drake <fdrake@acm.org>
parents: 11100
diff changeset
968 \method{reverse()} than to use the built-in function
1e0b1967be7f In note mentioning [].remove()'s exception, tell what exception is
Fred Drake <fdrake@acm.org>
parents: 11100
diff changeset
969 \function{sort()} with a comparison function that reverses the
1e0b1967be7f In note mentioning [].remove()'s exception, tell what exception is
Fred Drake <fdrake@acm.org>
parents: 11100
diff changeset
970 ordering of the elements.
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
971 \end{description}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
972
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
973
9083
bc41e86c938c Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9034
diff changeset
974 \subsection{Mapping Types \label{typesmapping}}
15005
0cf5111bf09c Use \obindex{...} instead of \indexii{...}{type} in many places; this is
Fred Drake <fdrake@acm.org>
parents: 14710
diff changeset
975 \obindex{mapping}
0cf5111bf09c Use \obindex{...} instead of \indexii{...}{type} in many places; this is
Fred Drake <fdrake@acm.org>
parents: 14710
diff changeset
976 \obindex{dictionary}
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
977
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
978 A \dfn{mapping} object maps values of one type (the key type) to
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
979 arbitrary objects. Mappings are mutable objects. There is currently
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
980 only one standard mapping type, the \dfn{dictionary}. A dictionary's keys are
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
981 almost arbitrary values. The only types of values not acceptable as
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
982 keys are values containing lists or dictionaries or other mutable
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
983 types that are compared by value rather than by object identity.
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
984 Numeric types used for keys obey the normal rules for numeric
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
985 comparison: if two numbers compare equal (e.g. \code{1} and
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
986 \code{1.0}) then they can be used interchangeably to index the same
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
987 dictionary entry.
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
988
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
989 Dictionaries are created by placing a comma-separated list of
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
990 \code{\var{key}: \var{value}} pairs within braces, for example:
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
991 \code{\{'jack': 4098, 'sjoerd': 4127\}} or
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
992 \code{\{4098: 'jack', 4127: 'sjoerd'\}}.
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
993
10968
5ba2e4ce58cb Some clarifications on operations for mapping types, based on comments
Fred Drake <fdrake@acm.org>
parents: 10785
diff changeset
994 The following operations are defined on mappings (where \var{a} and
5ba2e4ce58cb Some clarifications on operations for mapping types, based on comments
Fred Drake <fdrake@acm.org>
parents: 10785
diff changeset
995 \var{b} are mappings, \var{k} is a key, and \var{v} and \var{x} are
5ba2e4ce58cb Some clarifications on operations for mapping types, based on comments
Fred Drake <fdrake@acm.org>
parents: 10785
diff changeset
996 arbitrary objects):
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
997 \indexiii{operations on}{mapping}{types}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
998 \indexiii{operations on}{dictionary}{type}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
999 \stindex{del}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1000 \bifuncindex{len}
10156
0f7d694bc334 Make sure all HTML pages generated from this section have reasonable
Fred Drake <fdrake@acm.org>
parents: 10147
diff changeset
1001 \withsubitem{(dictionary method)}{
0f7d694bc334 Make sure all HTML pages generated from this section have reasonable
Fred Drake <fdrake@acm.org>
parents: 10147
diff changeset
1002 \ttindex{clear()}
0f7d694bc334 Make sure all HTML pages generated from this section have reasonable
Fred Drake <fdrake@acm.org>
parents: 10147
diff changeset
1003 \ttindex{copy()}
0f7d694bc334 Make sure all HTML pages generated from this section have reasonable
Fred Drake <fdrake@acm.org>
parents: 10147
diff changeset
1004 \ttindex{has_key()}
0f7d694bc334 Make sure all HTML pages generated from this section have reasonable
Fred Drake <fdrake@acm.org>
parents: 10147
diff changeset
1005 \ttindex{items()}
0f7d694bc334 Make sure all HTML pages generated from this section have reasonable
Fred Drake <fdrake@acm.org>
parents: 10147
diff changeset
1006 \ttindex{keys()}
0f7d694bc334 Make sure all HTML pages generated from this section have reasonable
Fred Drake <fdrake@acm.org>
parents: 10147
diff changeset
1007 \ttindex{update()}
0f7d694bc334 Make sure all HTML pages generated from this section have reasonable
Fred Drake <fdrake@acm.org>
parents: 10147
diff changeset
1008 \ttindex{values()}
23461
e43aafffb03c Added missing index entries for mapping methods. Closes patch #548693.
Raymond Hettinger <python@rcn.com>
parents: 23355
diff changeset
1009 \ttindex{get()}
e43aafffb03c Added missing index entries for mapping methods. Closes patch #548693.
Raymond Hettinger <python@rcn.com>
parents: 23355
diff changeset
1010 \ttindex{setdefault()}
e43aafffb03c Added missing index entries for mapping methods. Closes patch #548693.
Raymond Hettinger <python@rcn.com>
parents: 23355
diff changeset
1011 \ttindex{popitem()}
e43aafffb03c Added missing index entries for mapping methods. Closes patch #548693.
Raymond Hettinger <python@rcn.com>
parents: 23355
diff changeset
1012 \ttindex{iteritems()}
e43aafffb03c Added missing index entries for mapping methods. Closes patch #548693.
Raymond Hettinger <python@rcn.com>
parents: 23355
diff changeset
1013 \ttindex{iterkeys)}
e43aafffb03c Added missing index entries for mapping methods. Closes patch #548693.
Raymond Hettinger <python@rcn.com>
parents: 23355
diff changeset
1014 \ttindex{itervalues()}}
10968
5ba2e4ce58cb Some clarifications on operations for mapping types, based on comments
Fred Drake <fdrake@acm.org>
parents: 10785
diff changeset
1015
5ba2e4ce58cb Some clarifications on operations for mapping types, based on comments
Fred Drake <fdrake@acm.org>
parents: 10785
diff changeset
1016 \begin{tableiii}{c|l|c}{code}{Operation}{Result}{Notes}
5ba2e4ce58cb Some clarifications on operations for mapping types, based on comments
Fred Drake <fdrake@acm.org>
parents: 10785
diff changeset
1017 \lineiii{len(\var{a})}{the number of items in \var{a}}{}
5ba2e4ce58cb Some clarifications on operations for mapping types, based on comments
Fred Drake <fdrake@acm.org>
parents: 10785
diff changeset
1018 \lineiii{\var{a}[\var{k}]}{the item of \var{a} with key \var{k}}{(1)}
13764
fdbc8730d356 Two minor nits from Gerry Weiner (no working email address) about
Fred Drake <fdrake@acm.org>
parents: 13222
diff changeset
1019 \lineiii{\var{a}[\var{k}] = \var{v}}
fdbc8730d356 Two minor nits from Gerry Weiner (no working email address) about
Fred Drake <fdrake@acm.org>
parents: 13222
diff changeset
1020 {set \code{\var{a}[\var{k}]} to \var{v}}
10968
5ba2e4ce58cb Some clarifications on operations for mapping types, based on comments
Fred Drake <fdrake@acm.org>
parents: 10785
diff changeset
1021 {}
5ba2e4ce58cb Some clarifications on operations for mapping types, based on comments
Fred Drake <fdrake@acm.org>
parents: 10785
diff changeset
1022 \lineiii{del \var{a}[\var{k}]}
5ba2e4ce58cb Some clarifications on operations for mapping types, based on comments
Fred Drake <fdrake@acm.org>
parents: 10785
diff changeset
1023 {remove \code{\var{a}[\var{k}]} from \var{a}}
5ba2e4ce58cb Some clarifications on operations for mapping types, based on comments
Fred Drake <fdrake@acm.org>
parents: 10785
diff changeset
1024 {(1)}
5ba2e4ce58cb Some clarifications on operations for mapping types, based on comments
Fred Drake <fdrake@acm.org>
parents: 10785
diff changeset
1025 \lineiii{\var{a}.clear()}{remove all items from \code{a}}{}
5ba2e4ce58cb Some clarifications on operations for mapping types, based on comments
Fred Drake <fdrake@acm.org>
parents: 10785
diff changeset
1026 \lineiii{\var{a}.copy()}{a (shallow) copy of \code{a}}{}
17616
7acba78e1e09 At the suggestion of Peter Funk, document 'key in dict' and 'key not
Guido van Rossum <guido@python.org>
parents: 17612
diff changeset
1027 \lineiii{\var{a}.has_key(\var{k})}
17594
bf94af396b1e Implement, test and document "key in dict" and "key not in dict".
Guido van Rossum <guido@python.org>
parents: 16778
diff changeset
1028 {\code{1} if \var{a} has a key \var{k}, else \code{0}}
bf94af396b1e Implement, test and document "key in dict" and "key not in dict".
Guido van Rossum <guido@python.org>
parents: 16778
diff changeset
1029 {}
17616
7acba78e1e09 At the suggestion of Peter Funk, document 'key in dict' and 'key not
Guido van Rossum <guido@python.org>
parents: 17612
diff changeset
1030 \lineiii{\var{k} \code{in} \var{a}}
7acba78e1e09 At the suggestion of Peter Funk, document 'key in dict' and 'key not
Guido van Rossum <guido@python.org>
parents: 17612
diff changeset
1031 {Equivalent to \var{a}.has_key(\var{k})}
17966
178bedf9536d Add descriptions of {}.iteritems(), {}.iterkeys(), and {}.itervalues()
Fred Drake <fdrake@acm.org>
parents: 17663
diff changeset
1032 {(2)}
17594
bf94af396b1e Implement, test and document "key in dict" and "key not in dict".
Guido van Rossum <guido@python.org>
parents: 16778
diff changeset
1033 \lineiii{\var{k} not in \var{a}}
17616
7acba78e1e09 At the suggestion of Peter Funk, document 'key in dict' and 'key not
Guido van Rossum <guido@python.org>
parents: 17612
diff changeset
1034 {Equivalent to \code{not} \var{a}.has_key(\var{k})}
17966
178bedf9536d Add descriptions of {}.iteritems(), {}.iterkeys(), and {}.itervalues()
Fred Drake <fdrake@acm.org>
parents: 17663
diff changeset
1035 {(2)}
10968
5ba2e4ce58cb Some clarifications on operations for mapping types, based on comments
Fred Drake <fdrake@acm.org>
parents: 10785
diff changeset
1036 \lineiii{\var{a}.items()}
5ba2e4ce58cb Some clarifications on operations for mapping types, based on comments
Fred Drake <fdrake@acm.org>
parents: 10785
diff changeset
1037 {a copy of \var{a}'s list of (\var{key}, \var{value}) pairs}
17966
178bedf9536d Add descriptions of {}.iteritems(), {}.iterkeys(), and {}.itervalues()
Fred Drake <fdrake@acm.org>
parents: 17663
diff changeset
1038 {(3)}
18085
7e459fb3c332 Fixed reference to table notes for {}.keys() and {}.items() -- these
Fred Drake <fdrake@acm.org>
parents: 17966
diff changeset
1039 \lineiii{\var{a}.keys()}{a copy of \var{a}'s list of keys}{(3)}
10968
5ba2e4ce58cb Some clarifications on operations for mapping types, based on comments
Fred Drake <fdrake@acm.org>
parents: 10785
diff changeset
1040 \lineiii{\var{a}.update(\var{b})}
13764
fdbc8730d356 Two minor nits from Gerry Weiner (no working email address) about
Fred Drake <fdrake@acm.org>
parents: 13222
diff changeset
1041 {\code{for k in \var{b}.keys(): \var{a}[k] = \var{b}[k]}}
18286
bc05a95242a3 Remove the restriction on a mapping's .update() method.
Barry Warsaw <barry@python.org>
parents: 18085
diff changeset
1042 {}
18085
7e459fb3c332 Fixed reference to table notes for {}.keys() and {}.items() -- these
Fred Drake <fdrake@acm.org>
parents: 17966
diff changeset
1043 \lineiii{\var{a}.values()}{a copy of \var{a}'s list of values}{(3)}
10968
5ba2e4ce58cb Some clarifications on operations for mapping types, based on comments
Fred Drake <fdrake@acm.org>
parents: 10785
diff changeset
1044 \lineiii{\var{a}.get(\var{k}\optional{, \var{x}})}
17603
d638e419c304 Fix a number of minor markup errors.
Fred Drake <fdrake@acm.org>
parents: 17594
diff changeset
1045 {\code{\var{a}[\var{k}]} if \code{\var{k} in \var{a}},
10968
5ba2e4ce58cb Some clarifications on operations for mapping types, based on comments
Fred Drake <fdrake@acm.org>
parents: 10785
diff changeset
1046 else \var{x}}
18286
bc05a95242a3 Remove the restriction on a mapping's .update() method.
Barry Warsaw <barry@python.org>
parents: 18085
diff changeset
1047 {(4)}
13894
77b9e041b595 Barry's patch to document the new setdefault() method. Slightly
Guido van Rossum <guido@python.org>
parents: 13780
diff changeset
1048 \lineiii{\var{a}.setdefault(\var{k}\optional{, \var{x}})}
17603
d638e419c304 Fix a number of minor markup errors.
Fred Drake <fdrake@acm.org>
parents: 17594
diff changeset
1049 {\code{\var{a}[\var{k}]} if \code{\var{k} in \var{a}},
13894
77b9e041b595 Barry's patch to document the new setdefault() method. Slightly
Guido van Rossum <guido@python.org>
parents: 13780
diff changeset
1050 else \var{x} (also setting it)}
18286
bc05a95242a3 Remove the restriction on a mapping's .update() method.
Barry Warsaw <barry@python.org>
parents: 18085
diff changeset
1051 {(5)}
15522
aaa54752e4ba "Documentation" for {}.popitem().
Guido van Rossum <guido@python.org>
parents: 15463
diff changeset
1052 \lineiii{\var{a}.popitem()}
aaa54752e4ba "Documentation" for {}.popitem().
Guido van Rossum <guido@python.org>
parents: 15463
diff changeset
1053 {remove and return an arbitrary (\var{key}, \var{value}) pair}
18286
bc05a95242a3 Remove the restriction on a mapping's .update() method.
Barry Warsaw <barry@python.org>
parents: 18085
diff changeset
1054 {(6)}
17966
178bedf9536d Add descriptions of {}.iteritems(), {}.iterkeys(), and {}.itervalues()
Fred Drake <fdrake@acm.org>
parents: 17663
diff changeset
1055 \lineiii{\var{a}.iteritems()}
178bedf9536d Add descriptions of {}.iteritems(), {}.iterkeys(), and {}.itervalues()
Fred Drake <fdrake@acm.org>
parents: 17663
diff changeset
1056 {return an iterator over (\var{key}, \var{value}) pairs}
24903
ecd4ada252bc Extend some comments on the order of values in the returns from
Fred Drake <fdrake@acm.org>
parents: 24632
diff changeset
1057 {(2), (3)}
17966
178bedf9536d Add descriptions of {}.iteritems(), {}.iterkeys(), and {}.itervalues()
Fred Drake <fdrake@acm.org>
parents: 17663
diff changeset
1058 \lineiii{\var{a}.iterkeys()}
178bedf9536d Add descriptions of {}.iteritems(), {}.iterkeys(), and {}.itervalues()
Fred Drake <fdrake@acm.org>
parents: 17663
diff changeset
1059 {return an iterator over the mapping's keys}
24903
ecd4ada252bc Extend some comments on the order of values in the returns from
Fred Drake <fdrake@acm.org>
parents: 24632
diff changeset
1060 {(2), (3)}
17966
178bedf9536d Add descriptions of {}.iteritems(), {}.iterkeys(), and {}.itervalues()
Fred Drake <fdrake@acm.org>
parents: 17663
diff changeset
1061 \lineiii{\var{a}.itervalues()}
178bedf9536d Add descriptions of {}.iteritems(), {}.iterkeys(), and {}.itervalues()
Fred Drake <fdrake@acm.org>
parents: 17663
diff changeset
1062 {return an iterator over the mapping's values}
24903
ecd4ada252bc Extend some comments on the order of values in the returns from
Fred Drake <fdrake@acm.org>
parents: 24632
diff changeset
1063 {(2), (3)}
10968
5ba2e4ce58cb Some clarifications on operations for mapping types, based on comments
Fred Drake <fdrake@acm.org>
parents: 10785
diff changeset
1064 \end{tableiii}
5ba2e4ce58cb Some clarifications on operations for mapping types, based on comments
Fred Drake <fdrake@acm.org>
parents: 10785
diff changeset
1065
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1066 \noindent
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1067 Notes:
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1068 \begin{description}
10968
5ba2e4ce58cb Some clarifications on operations for mapping types, based on comments
Fred Drake <fdrake@acm.org>
parents: 10785
diff changeset
1069 \item[(1)] Raises a \exception{KeyError} exception if \var{k} is not
5ba2e4ce58cb Some clarifications on operations for mapping types, based on comments
Fred Drake <fdrake@acm.org>
parents: 10785
diff changeset
1070 in the map.
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1071
17966
178bedf9536d Add descriptions of {}.iteritems(), {}.iterkeys(), and {}.itervalues()
Fred Drake <fdrake@acm.org>
parents: 17663
diff changeset
1072 \item[(2)] \versionadded{2.2}
178bedf9536d Add descriptions of {}.iteritems(), {}.iterkeys(), and {}.itervalues()
Fred Drake <fdrake@acm.org>
parents: 17663
diff changeset
1073
178bedf9536d Add descriptions of {}.iteritems(), {}.iterkeys(), and {}.itervalues()
Fred Drake <fdrake@acm.org>
parents: 17663
diff changeset
1074 \item[(3)] Keys and values are listed in random order. If
24903
ecd4ada252bc Extend some comments on the order of values in the returns from
Fred Drake <fdrake@acm.org>
parents: 24632
diff changeset
1075 \method{items()}, \method{keys()}, \method{values()},
ecd4ada252bc Extend some comments on the order of values in the returns from
Fred Drake <fdrake@acm.org>
parents: 24632
diff changeset
1076 \method{iteritems()}, \method{iterkeys()}, and \method{itervalues()}
ecd4ada252bc Extend some comments on the order of values in the returns from
Fred Drake <fdrake@acm.org>
parents: 24632
diff changeset
1077 are called with no intervening modifications to the dictionary, the
ecd4ada252bc Extend some comments on the order of values in the returns from
Fred Drake <fdrake@acm.org>
parents: 24632
diff changeset
1078 lists will directly correspond. This allows the creation of
ecd4ada252bc Extend some comments on the order of values in the returns from
Fred Drake <fdrake@acm.org>
parents: 24632
diff changeset
1079 \code{(\var{value}, \var{key})} pairs using \function{zip()}:
ecd4ada252bc Extend some comments on the order of values in the returns from
Fred Drake <fdrake@acm.org>
parents: 24632
diff changeset
1080 \samp{pairs = zip(\var{a}.values(), \var{a}.keys())}. The same
ecd4ada252bc Extend some comments on the order of values in the returns from
Fred Drake <fdrake@acm.org>
parents: 24632
diff changeset
1081 relationship holds for the \method{iterkeys()} and
ecd4ada252bc Extend some comments on the order of values in the returns from
Fred Drake <fdrake@acm.org>
parents: 24632
diff changeset
1082 \method{itervalues()} methods: \samp{pairs = zip(\var{a}.itervalues(),
ecd4ada252bc Extend some comments on the order of values in the returns from
Fred Drake <fdrake@acm.org>
parents: 24632
diff changeset
1083 \var{a}.iterkeys())} provides the same value for \code{pairs}.
ecd4ada252bc Extend some comments on the order of values in the returns from
Fred Drake <fdrake@acm.org>
parents: 24632
diff changeset
1084 Another way to create the same list is \samp{pairs = [(v, k) for (k,
ecd4ada252bc Extend some comments on the order of values in the returns from
Fred Drake <fdrake@acm.org>
parents: 24632
diff changeset
1085 v) in \var{a}.iteritems()]}.
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1086
18286
bc05a95242a3 Remove the restriction on a mapping's .update() method.
Barry Warsaw <barry@python.org>
parents: 18085
diff changeset
1087 \item[(4)] Never raises an exception if \var{k} is not in the map,
12223
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11463
diff changeset
1088 instead it returns \var{x}. \var{x} is optional; when \var{x} is not
10968
5ba2e4ce58cb Some clarifications on operations for mapping types, based on comments
Fred Drake <fdrake@acm.org>
parents: 10785
diff changeset
1089 provided and \var{k} is not in the map, \code{None} is returned.
13894
77b9e041b595 Barry's patch to document the new setdefault() method. Slightly
Guido van Rossum <guido@python.org>
parents: 13780
diff changeset
1090
18286
bc05a95242a3 Remove the restriction on a mapping's .update() method.
Barry Warsaw <barry@python.org>
parents: 18085
diff changeset
1091 \item[(5)] \function{setdefault()} is like \function{get()}, except
13894
77b9e041b595 Barry's patch to document the new setdefault() method. Slightly
Guido van Rossum <guido@python.org>
parents: 13780
diff changeset
1092 that if \var{k} is missing, \var{x} is both returned and inserted into
77b9e041b595 Barry's patch to document the new setdefault() method. Slightly
Guido van Rossum <guido@python.org>
parents: 13780
diff changeset
1093 the dictionary as the value of \var{k}.
15522
aaa54752e4ba "Documentation" for {}.popitem().
Guido van Rossum <guido@python.org>
parents: 15463
diff changeset
1094
18286
bc05a95242a3 Remove the restriction on a mapping's .update() method.
Barry Warsaw <barry@python.org>
parents: 18085
diff changeset
1095 \item[(6)] \function{popitem()} is useful to destructively iterate
15522
aaa54752e4ba "Documentation" for {}.popitem().
Guido van Rossum <guido@python.org>
parents: 15463
diff changeset
1096 over a dictionary, as often used in set algorithms.
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1097 \end{description}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1098
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1099
20767
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1100 \subsection{File Objects
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1101 \label{bltin-file-objects}}
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1102
20767
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1103 File objects\obindex{file} are implemented using C's \code{stdio}
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1104 package and can be created with the built-in constructor
22340
7ecc49117d7e Take Tim's work on file.truncate out of 2.2.1 again.
Michael W. Hudson <mwh@python.net>
parents: 22337
diff changeset
1105 \function{file()}\bifuncindex{file} described in section
20764
37b8d92e12f5 Mention the new file() builtin in the section on file objects.
Tim Peters <tim.peters@gmail.com>
parents: 20701
diff changeset
1106 \ref{built-in-funcs}, ``Built-in Functions.''\footnote{\function{file()}
37b8d92e12f5 Mention the new file() builtin in the section on file objects.
Tim Peters <tim.peters@gmail.com>
parents: 20701
diff changeset
1107 is new in Python 2.2. The older built-in \function{open()} is an
37b8d92e12f5 Mention the new file() builtin in the section on file objects.
Tim Peters <tim.peters@gmail.com>
parents: 20701
diff changeset
1108 alias for \function{file()}.}
37b8d92e12f5 Mention the new file() builtin in the section on file objects.
Tim Peters <tim.peters@gmail.com>
parents: 20701
diff changeset
1109 They are also returned
18416
33b4357aebb8 Fix up a few style nits -- avoid "e.g." and "i.e." -- these make
Fred Drake <fdrake@acm.org>
parents: 18395
diff changeset
1110 by some other built-in functions and methods, such as
13933
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
1111 \function{os.popen()} and \function{os.fdopen()} and the
9461
9ffd604807c2 Don't describe something as "below"; that won't make sense for the
Fred Drake <fdrake@acm.org>
parents: 9318
diff changeset
1112 \method{makefile()} method of socket objects.
13933
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
1113 \refstmodindex{os}
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1114 \refbimodindex{socket}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1115
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1116 When a file operation fails for an I/O-related reason, the exception
9558
fa867d8ee7eb Remove some remaining {\rm ...} constructs.
Fred Drake <fdrake@acm.org>
parents: 9523
diff changeset
1117 \exception{IOError} is raised. This includes situations where the
fa867d8ee7eb Remove some remaining {\rm ...} constructs.
Fred Drake <fdrake@acm.org>
parents: 9523
diff changeset
1118 operation is not defined for some reason, like \method{seek()} on a tty
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1119 device or writing a file opened for reading.
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1120
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1121 Files have the following methods:
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1122
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1123
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1124 \begin{methoddesc}[file]{close}{}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1125 Close the file. A closed file cannot be read or written anymore.
15383
eeb7c8a5b79f Document the proper exception to be raised by I/O operations on closed
Fred Drake <fdrake@acm.org>
parents: 15332
diff changeset
1126 Any operation which requires that the file be open will raise a
eeb7c8a5b79f Document the proper exception to be raised by I/O operations on closed
Fred Drake <fdrake@acm.org>
parents: 15332
diff changeset
1127 \exception{ValueError} after the file has been closed. Calling
14685
faf3e734254d Clarify a number of issues about the file-like object API based on
Fred Drake <fdrake@acm.org>
parents: 14557
diff changeset
1128 \method{close()} more than once is allowed.
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1129 \end{methoddesc}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1130
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1131 \begin{methoddesc}[file]{flush}{}
14685
faf3e734254d Clarify a number of issues about the file-like object API based on
Fred Drake <fdrake@acm.org>
parents: 14557
diff changeset
1132 Flush the internal buffer, like \code{stdio}'s
faf3e734254d Clarify a number of issues about the file-like object API based on
Fred Drake <fdrake@acm.org>
parents: 14557
diff changeset
1133 \cfunction{fflush()}. This may be a no-op on some file-like
faf3e734254d Clarify a number of issues about the file-like object API based on
Fred Drake <fdrake@acm.org>
parents: 14557
diff changeset
1134 objects.
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1135 \end{methoddesc}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1136
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1137 \begin{methoddesc}[file]{isatty}{}
14685
faf3e734254d Clarify a number of issues about the file-like object API based on
Fred Drake <fdrake@acm.org>
parents: 14557
diff changeset
1138 Return true if the file is connected to a tty(-like) device, else
20580
376ee174ecd0 Use the \note and \warning macros where appropriate.
Fred Drake <fdrake@acm.org>
parents: 20173
diff changeset
1139 false. \note{If a file-like object is not associated
376ee174ecd0 Use the \note and \warning macros where appropriate.
Fred Drake <fdrake@acm.org>
parents: 20173
diff changeset
1140 with a real file, this method should \emph{not} be implemented.}
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1141 \end{methoddesc}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1142
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1143 \begin{methoddesc}[file]{fileno}{}
14685
faf3e734254d Clarify a number of issues about the file-like object API based on
Fred Drake <fdrake@acm.org>
parents: 14557
diff changeset
1144 \index{file descriptor}
faf3e734254d Clarify a number of issues about the file-like object API based on
Fred Drake <fdrake@acm.org>
parents: 14557
diff changeset
1145 \index{descriptor, file}
faf3e734254d Clarify a number of issues about the file-like object API based on
Fred Drake <fdrake@acm.org>
parents: 14557
diff changeset
1146 Return the integer ``file descriptor'' that is used by the
faf3e734254d Clarify a number of issues about the file-like object API based on
Fred Drake <fdrake@acm.org>
parents: 14557
diff changeset
1147 underlying implementation to request I/O operations from the
faf3e734254d Clarify a number of issues about the file-like object API based on
Fred Drake <fdrake@acm.org>
parents: 14557
diff changeset
1148 operating system. This can be useful for other, lower level
18416
33b4357aebb8 Fix up a few style nits -- avoid "e.g." and "i.e." -- these make
Fred Drake <fdrake@acm.org>
parents: 18395
diff changeset
1149 interfaces that use file descriptors, such as the
33b4357aebb8 Fix up a few style nits -- avoid "e.g." and "i.e." -- these make
Fred Drake <fdrake@acm.org>
parents: 18395
diff changeset
1150 \refmodule{fcntl}\refbimodindex{fcntl} module or
20580
376ee174ecd0 Use the \note and \warning macros where appropriate.
Fred Drake <fdrake@acm.org>
parents: 20173
diff changeset
1151 \function{os.read()} and friends. \note{File-like objects
18416
33b4357aebb8 Fix up a few style nits -- avoid "e.g." and "i.e." -- these make
Fred Drake <fdrake@acm.org>
parents: 18395
diff changeset
1152 which do not have a real file descriptor should \emph{not} provide
20580
376ee174ecd0 Use the \note and \warning macros where appropriate.
Fred Drake <fdrake@acm.org>
parents: 20173
diff changeset
1153 this method!}
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1154 \end{methoddesc}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1155
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1156 \begin{methoddesc}[file]{read}{\optional{size}}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1157 Read at most \var{size} bytes from the file (less if the read hits
10606
fe5fcb7e73f7 Correct documentation for <file>.read(); Python makes a serious
Fred Drake <fdrake@acm.org>
parents: 10520
diff changeset
1158 \EOF{} before obtaining \var{size} bytes). If the \var{size}
fe5fcb7e73f7 Correct documentation for <file>.read(); Python makes a serious
Fred Drake <fdrake@acm.org>
parents: 10520
diff changeset
1159 argument is negative or omitted, read all data until \EOF{} is
fe5fcb7e73f7 Correct documentation for <file>.read(); Python makes a serious
Fred Drake <fdrake@acm.org>
parents: 10520
diff changeset
1160 reached. The bytes are returned as a string object. An empty
fe5fcb7e73f7 Correct documentation for <file>.read(); Python makes a serious
Fred Drake <fdrake@acm.org>
parents: 10520
diff changeset
1161 string is returned when \EOF{} is encountered immediately. (For
fe5fcb7e73f7 Correct documentation for <file>.read(); Python makes a serious
Fred Drake <fdrake@acm.org>
parents: 10520
diff changeset
1162 certain files, like ttys, it makes sense to continue reading after
fe5fcb7e73f7 Correct documentation for <file>.read(); Python makes a serious
Fred Drake <fdrake@acm.org>
parents: 10520
diff changeset
1163 an \EOF{} is hit.) Note that this method may call the underlying
fe5fcb7e73f7 Correct documentation for <file>.read(); Python makes a serious
Fred Drake <fdrake@acm.org>
parents: 10520
diff changeset
1164 C function \cfunction{fread()} more than once in an effort to
fe5fcb7e73f7 Correct documentation for <file>.read(); Python makes a serious
Fred Drake <fdrake@acm.org>
parents: 10520
diff changeset
1165 acquire as close to \var{size} bytes as possible.
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1166 \end{methoddesc}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1167
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1168 \begin{methoddesc}[file]{readline}{\optional{size}}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1169 Read one entire line from the file. A trailing newline character is
10520
7ee1e3134147 Fixed latex2html weirdness with footnotes.
Fred Drake <fdrake@acm.org>
parents: 10241
diff changeset
1170 kept in the string\footnote{
22340
7ecc49117d7e Take Tim's work on file.truncate out of 2.2.1 again.
Michael W. Hudson <mwh@python.net>
parents: 22337
diff changeset
1171 The advantage of leaving the newline on is that an empty string
7ecc49117d7e Take Tim's work on file.truncate out of 2.2.1 again.
Michael W. Hudson <mwh@python.net>
parents: 22337
diff changeset
1172 can be returned to mean \EOF{} without being ambiguous. Another
7ecc49117d7e Take Tim's work on file.truncate out of 2.2.1 again.
Michael W. Hudson <mwh@python.net>
parents: 22337
diff changeset
1173 advantage is that (in cases where it might matter, for example. if you
7ecc49117d7e Take Tim's work on file.truncate out of 2.2.1 again.
Michael W. Hudson <mwh@python.net>
parents: 22337
diff changeset
1174 want to make an exact copy of a file while scanning its lines)
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1175 you can tell whether the last line of a file ended in a newline
13933
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
1176 or not (yes this happens!).
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
1177 } (but may be absent when a file ends with an
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1178 incomplete line). If the \var{size} argument is present and
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1179 non-negative, it is a maximum byte count (including the trailing
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1180 newline) and an incomplete line may be returned.
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1181 An empty string is returned when \EOF{} is hit
20580
376ee174ecd0 Use the \note and \warning macros where appropriate.
Fred Drake <fdrake@acm.org>
parents: 20173
diff changeset
1182 immediately. \note{Unlike \code{stdio}'s \cfunction{fgets()}, the
14685
faf3e734254d Clarify a number of issues about the file-like object API based on
Fred Drake <fdrake@acm.org>
parents: 14557
diff changeset
1183 returned string contains null characters (\code{'\e 0'}) if they
20580
376ee174ecd0 Use the \note and \warning macros where appropriate.
Fred Drake <fdrake@acm.org>
parents: 20173
diff changeset
1184 occurred in the input.}
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1185 \end{methoddesc}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1186
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1187 \begin{methoddesc}[file]{readlines}{\optional{sizehint}}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1188 Read until \EOF{} using \method{readline()} and return a list containing
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1189 the lines thus read. If the optional \var{sizehint} argument is
21062
bc02c3b09626 Clean up some markup cruft. A number of the macros that take no
Fred Drake <fdrake@acm.org>
parents: 20767
diff changeset
1190 present, instead of reading up to \EOF, whole lines totalling
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1191 approximately \var{sizehint} bytes (possibly after rounding up to an
14685
faf3e734254d Clarify a number of issues about the file-like object API based on
Fred Drake <fdrake@acm.org>
parents: 14557
diff changeset
1192 internal buffer size) are read. Objects implementing a file-like
faf3e734254d Clarify a number of issues about the file-like object API based on
Fred Drake <fdrake@acm.org>
parents: 14557
diff changeset
1193 interface may choose to ignore \var{sizehint} if it cannot be
faf3e734254d Clarify a number of issues about the file-like object API based on
Fred Drake <fdrake@acm.org>
parents: 14557
diff changeset
1194 implemented, or cannot be implemented efficiently.
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1195 \end{methoddesc}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1196
15926
ac13cef423c8 Document xreadlines() method. (Forgot to check this in before!)
Guido van Rossum <guido@python.org>
parents: 15896
diff changeset
1197 \begin{methoddesc}[file]{xreadlines}{}
17612
c19d6db6e99b Only document <file>.xreadlines() once; added version annotation.
Fred Drake <fdrake@acm.org>
parents: 17603
diff changeset
1198 Equivalent to
c19d6db6e99b Only document <file>.xreadlines() once; added version annotation.
Fred Drake <fdrake@acm.org>
parents: 17603
diff changeset
1199 \function{xreadlines.xreadlines(\var{file})}.\refstmodindex{xreadlines}
c19d6db6e99b Only document <file>.xreadlines() once; added version annotation.
Fred Drake <fdrake@acm.org>
parents: 17603
diff changeset
1200 (See the \refmodule{xreadlines} module for more information.)
c19d6db6e99b Only document <file>.xreadlines() once; added version annotation.
Fred Drake <fdrake@acm.org>
parents: 17603
diff changeset
1201 \versionadded{2.1}
15926
ac13cef423c8 Document xreadlines() method. (Forgot to check this in before!)
Guido van Rossum <guido@python.org>
parents: 15896
diff changeset
1202 \end{methoddesc}
ac13cef423c8 Document xreadlines() method. (Forgot to check this in before!)
Guido van Rossum <guido@python.org>
parents: 15896
diff changeset
1203
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1204 \begin{methoddesc}[file]{seek}{offset\optional{, whence}}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1205 Set the file's current position, like \code{stdio}'s \cfunction{fseek()}.
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1206 The \var{whence} argument is optional and defaults to \code{0}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1207 (absolute file positioning); other values are \code{1} (seek
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1208 relative to the current position) and \code{2} (seek relative to the
15731
a06415994cb5 Added information about the interaction of opening a file in append mode
Fred Drake <fdrake@acm.org>
parents: 15522
diff changeset
1209 file's end). There is no return value. Note that if the file is
a06415994cb5 Added information about the interaction of opening a file in append mode
Fred Drake <fdrake@acm.org>
parents: 15522
diff changeset
1210 opened for appending (mode \code{'a'} or \code{'a+'}), any
a06415994cb5 Added information about the interaction of opening a file in append mode
Fred Drake <fdrake@acm.org>
parents: 15522
diff changeset
1211 \method{seek()} operations will be undone at the next write. If the
a06415994cb5 Added information about the interaction of opening a file in append mode
Fred Drake <fdrake@acm.org>
parents: 15522
diff changeset
1212 file is only opened for writing in append mode (mode \code{'a'}),
a06415994cb5 Added information about the interaction of opening a file in append mode
Fred Drake <fdrake@acm.org>
parents: 15522
diff changeset
1213 this method is essentially a no-op, but it remains useful for files
a06415994cb5 Added information about the interaction of opening a file in append mode
Fred Drake <fdrake@acm.org>
parents: 15522
diff changeset
1214 opened in append mode with reading enabled (mode \code{'a+'}).
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1215 \end{methoddesc}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1216
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1217 \begin{methoddesc}[file]{tell}{}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1218 Return the file's current position, like \code{stdio}'s
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1219 \cfunction{ftell()}.
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1220 \end{methoddesc}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1221
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1222 \begin{methoddesc}[file]{truncate}{\optional{size}}
22340
7ecc49117d7e Take Tim's work on file.truncate out of 2.2.1 again.
Michael W. Hudson <mwh@python.net>
parents: 22337
diff changeset
1223 Truncate the file's size. If the optional \var{size} argument
14685
faf3e734254d Clarify a number of issues about the file-like object API based on
Fred Drake <fdrake@acm.org>
parents: 14557
diff changeset
1224 present, the file is truncated to (at most) that size. The size
22340
7ecc49117d7e Take Tim's work on file.truncate out of 2.2.1 again.
Michael W. Hudson <mwh@python.net>
parents: 22337
diff changeset
1225 defaults to the current position. Availability of this function
7ecc49117d7e Take Tim's work on file.truncate out of 2.2.1 again.
Michael W. Hudson <mwh@python.net>
parents: 22337
diff changeset
1226 depends on the operating system version (for example, not all
7ecc49117d7e Take Tim's work on file.truncate out of 2.2.1 again.
Michael W. Hudson <mwh@python.net>
parents: 22337
diff changeset
1227 \UNIX{} versions support this operation).
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1228 \end{methoddesc}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1229
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1230 \begin{methoddesc}[file]{write}{str}
20580
376ee174ecd0 Use the \note and \warning macros where appropriate.
Fred Drake <fdrake@acm.org>
parents: 20173
diff changeset
1231 Write a string to the file. There is no return value. Due to
15789
9e9556924b0a Added documentation for the xreadlines module & related changes. The
Fred Drake <fdrake@acm.org>
parents: 15731
diff changeset
1232 buffering, the string may not actually show up in the file until
9e9556924b0a Added documentation for the xreadlines module & related changes. The
Fred Drake <fdrake@acm.org>
parents: 15731
diff changeset
1233 the \method{flush()} or \method{close()} method is called.
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1234 \end{methoddesc}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1235
20045
7b8c11739714 Generalize file.writelines() to allow iterable objects.
Tim Peters <tim.peters@gmail.com>
parents: 20031
diff changeset
1236 \begin{methoddesc}[file]{writelines}{sequence}
7b8c11739714 Generalize file.writelines() to allow iterable objects.
Tim Peters <tim.peters@gmail.com>
parents: 20031
diff changeset
1237 Write a sequence of strings to the file. The sequence can be any
7b8c11739714 Generalize file.writelines() to allow iterable objects.
Tim Peters <tim.peters@gmail.com>
parents: 20031
diff changeset
1238 iterable object producing strings, typically a list of strings.
7b8c11739714 Generalize file.writelines() to allow iterable objects.
Tim Peters <tim.peters@gmail.com>
parents: 20031
diff changeset
1239 There is no return value.
15789
9e9556924b0a Added documentation for the xreadlines module & related changes. The
Fred Drake <fdrake@acm.org>
parents: 15731
diff changeset
1240 (The name is intended to match \method{readlines()};
9e9556924b0a Added documentation for the xreadlines module & related changes. The
Fred Drake <fdrake@acm.org>
parents: 15731
diff changeset
1241 \method{writelines()} does not add line separators.)
9e9556924b0a Added documentation for the xreadlines module & related changes. The
Fred Drake <fdrake@acm.org>
parents: 15731
diff changeset
1242 \end{methoddesc}
9e9556924b0a Added documentation for the xreadlines module & related changes. The
Fred Drake <fdrake@acm.org>
parents: 15731
diff changeset
1243
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1244
20031
e5a3f9d7766b Note that files are iterable; describe what the iterator returns.
Fred Drake <fdrake@acm.org>
parents: 19529
diff changeset
1245 Files support the iterator protocol. Each iteration returns the same
e5a3f9d7766b Note that files are iterable; describe what the iterator returns.
Fred Drake <fdrake@acm.org>
parents: 19529
diff changeset
1246 result as \code{\var{file}.readline()}, and iteration ends when the
e5a3f9d7766b Note that files are iterable; describe what the iterator returns.
Fred Drake <fdrake@acm.org>
parents: 19529
diff changeset
1247 \method{readline()} method returns an empty string.
e5a3f9d7766b Note that files are iterable; describe what the iterator returns.
Fred Drake <fdrake@acm.org>
parents: 19529
diff changeset
1248
e5a3f9d7766b Note that files are iterable; describe what the iterator returns.
Fred Drake <fdrake@acm.org>
parents: 19529
diff changeset
1249
14685
faf3e734254d Clarify a number of issues about the file-like object API based on
Fred Drake <fdrake@acm.org>
parents: 14557
diff changeset
1250 File objects also offer a number of other interesting attributes.
faf3e734254d Clarify a number of issues about the file-like object API based on
Fred Drake <fdrake@acm.org>
parents: 14557
diff changeset
1251 These are not required for file-like objects, but should be
faf3e734254d Clarify a number of issues about the file-like object API based on
Fred Drake <fdrake@acm.org>
parents: 14557
diff changeset
1252 implemented if they make sense for the particular object.
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1253
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1254 \begin{memberdesc}[file]{closed}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1255 Boolean indicating the current state of the file object. This is a
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1256 read-only attribute; the \method{close()} method changes the value.
14685
faf3e734254d Clarify a number of issues about the file-like object API based on
Fred Drake <fdrake@acm.org>
parents: 14557
diff changeset
1257 It may not be available on all file-like objects.
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1258 \end{memberdesc}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1259
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1260 \begin{memberdesc}[file]{mode}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1261 The I/O mode for the file. If the file was created using the
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1262 \function{open()} built-in function, this will be the value of the
14685
faf3e734254d Clarify a number of issues about the file-like object API based on
Fred Drake <fdrake@acm.org>
parents: 14557
diff changeset
1263 \var{mode} parameter. This is a read-only attribute and may not be
faf3e734254d Clarify a number of issues about the file-like object API based on
Fred Drake <fdrake@acm.org>
parents: 14557
diff changeset
1264 present on all file-like objects.
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1265 \end{memberdesc}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1266
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1267 \begin{memberdesc}[file]{name}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1268 If the file object was created using \function{open()}, the name of
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1269 the file. Otherwise, some string that indicates the source of the
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1270 file object, of the form \samp{<\mbox{\ldots}>}. This is a read-only
14685
faf3e734254d Clarify a number of issues about the file-like object API based on
Fred Drake <fdrake@acm.org>
parents: 14557
diff changeset
1271 attribute and may not be present on all file-like objects.
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1272 \end{memberdesc}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1273
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1274 \begin{memberdesc}[file]{softspace}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1275 Boolean that indicates whether a space character needs to be printed
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1276 before another value when using the \keyword{print} statement.
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1277 Classes that are trying to simulate a file object should also have a
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1278 writable \member{softspace} attribute, which should be initialized to
14485
ac0246586d52 Improve a couple of references to the language reference, making them
Fred Drake <fdrake@acm.org>
parents: 14044
diff changeset
1279 zero. This will be automatic for most classes implemented in Python
ac0246586d52 Improve a couple of references to the language reference, making them
Fred Drake <fdrake@acm.org>
parents: 14044
diff changeset
1280 (care may be needed for objects that override attribute access); types
ac0246586d52 Improve a couple of references to the language reference, making them
Fred Drake <fdrake@acm.org>
parents: 14044
diff changeset
1281 implemented in C will have to provide a writable
ac0246586d52 Improve a couple of references to the language reference, making them
Fred Drake <fdrake@acm.org>
parents: 14044
diff changeset
1282 \member{softspace} attribute.
20580
376ee174ecd0 Use the \note and \warning macros where appropriate.
Fred Drake <fdrake@acm.org>
parents: 20173
diff changeset
1283 \note{This attribute is not used to control the
14705
4712f5b8f279 Clarify that the softspace attribute is used by print for state management,
Fred Drake <fdrake@acm.org>
parents: 14685
diff changeset
1284 \keyword{print} statement, but to allow the implementation of
20580
376ee174ecd0 Use the \note and \warning macros where appropriate.
Fred Drake <fdrake@acm.org>
parents: 20173
diff changeset
1285 \keyword{print} to keep track of its internal state.}
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1286 \end{memberdesc}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1287
15383
eeb7c8a5b79f Document the proper exception to be raised by I/O operations on closed
Fred Drake <fdrake@acm.org>
parents: 15332
diff changeset
1288
20767
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1289 \subsection{Other Built-in Types \label{typesother}}
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1290
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1291 The interpreter supports several other kinds of objects.
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1292 Most of these support only one or two operations.
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1293
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1294
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1295 \subsubsection{Modules \label{typesmodules}}
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1296
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1297 The only special operation on a module is attribute access:
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1298 \code{\var{m}.\var{name}}, where \var{m} is a module and \var{name}
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1299 accesses a name defined in \var{m}'s symbol table. Module attributes
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1300 can be assigned to. (Note that the \keyword{import} statement is not,
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1301 strictly speaking, an operation on a module object; \code{import
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1302 \var{foo}} does not require a module object named \var{foo} to exist,
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1303 rather it requires an (external) \emph{definition} for a module named
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1304 \var{foo} somewhere.)
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1305
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1306 A special member of every module is \member{__dict__}.
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1307 This is the dictionary containing the module's symbol table.
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1308 Modifying this dictionary will actually change the module's symbol
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1309 table, but direct assignment to the \member{__dict__} attribute is not
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1310 possible (you can write \code{\var{m}.__dict__['a'] = 1}, which
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1311 defines \code{\var{m}.a} to be \code{1}, but you can't write
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1312 \code{\var{m}.__dict__ = \{\}}.
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1313
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1314 Modules built into the interpreter are written like this:
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1315 \code{<module 'sys' (built-in)>}. If loaded from a file, they are
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1316 written as \code{<module 'os' from
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1317 '/usr/local/lib/python\shortversion/os.pyc'>}.
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1318
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1319
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1320 \subsubsection{Classes and Class Instances \label{typesobjects}}
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1321 \nodename{Classes and Instances}
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1322
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1323 See chapters 3 and 7 of the \citetitle[../ref/ref.html]{Python
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1324 Reference Manual} for these.
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1325
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1326
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1327 \subsubsection{Functions \label{typesfunctions}}
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1328
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1329 Function objects are created by function definitions. The only
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1330 operation on a function object is to call it:
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1331 \code{\var{func}(\var{argument-list})}.
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1332
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1333 There are really two flavors of function objects: built-in functions
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1334 and user-defined functions. Both support the same operation (to call
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1335 the function), but the implementation is different, hence the
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1336 different object types.
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1337
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1338 The implementation adds two special read-only attributes:
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1339 \code{\var{f}.func_code} is a function's \dfn{code
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1340 object}\obindex{code} (see below) and \code{\var{f}.func_globals} is
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1341 the dictionary used as the function's global namespace (this is the
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1342 same as \code{\var{m}.__dict__} where \var{m} is the module in which
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1343 the function \var{f} was defined).
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1344
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1345 Function objects also support getting and setting arbitrary
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1346 attributes, which can be used to, e.g. attach metadata to functions.
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1347 Regular attribute dot-notation is used to get and set such
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1348 attributes. \emph{Note that the current implementation only supports
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1349 function attributes on user-defined functions. Function attributes on
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1350 built-in functions may be supported in the future.}
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1351
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1352 Functions have another special attribute \code{\var{f}.__dict__}
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1353 (a.k.a. \code{\var{f}.func_dict}) which contains the namespace used to
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1354 support function attributes. \code{__dict__} and \code{func_dict} can
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1355 be accessed directly or set to a dictionary object. A function's
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1356 dictionary cannot be deleted.
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1357
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1358 \subsubsection{Methods \label{typesmethods}}
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1359 \obindex{method}
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1360
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1361 Methods are functions that are called using the attribute notation.
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1362 There are two flavors: built-in methods (such as \method{append()} on
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1363 lists) and class instance methods. Built-in methods are described
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1364 with the types that support them.
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1365
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1366 The implementation adds two special read-only attributes to class
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1367 instance methods: \code{\var{m}.im_self} is the object on which the
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1368 method operates, and \code{\var{m}.im_func} is the function
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1369 implementing the method. Calling \code{\var{m}(\var{arg-1},
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1370 \var{arg-2}, \textrm{\ldots}, \var{arg-n})} is completely equivalent to
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1371 calling \code{\var{m}.im_func(\var{m}.im_self, \var{arg-1},
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1372 \var{arg-2}, \textrm{\ldots}, \var{arg-n})}.
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1373
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1374 Class instance methods are either \emph{bound} or \emph{unbound},
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1375 referring to whether the method was accessed through an instance or a
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1376 class, respectively. When a method is unbound, its \code{im_self}
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1377 attribute will be \code{None} and if called, an explicit \code{self}
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1378 object must be passed as the first argument. In this case,
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1379 \code{self} must be an instance of the unbound method's class (or a
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1380 subclass of that class), otherwise a \code{TypeError} is raised.
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1381
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1382 Like function objects, methods objects support getting
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1383 arbitrary attributes. However, since method attributes are actually
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1384 stored on the underlying function object (\code{meth.im_func}),
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1385 setting method attributes on either bound or unbound methods is
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1386 disallowed. Attempting to set a method attribute results in a
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1387 \code{TypeError} being raised. In order to set a method attribute,
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1388 you need to explicitly set it on the underlying function object:
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1389
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1390 \begin{verbatim}
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1391 class C:
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1392 def method(self):
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1393 pass
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1394
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1395 c = C()
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1396 c.method.im_func.whoami = 'my name is c'
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1397 \end{verbatim}
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1398
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1399 See the \citetitle[../ref/ref.html]{Python Reference Manual} for more
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1400 information.
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1401
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1402
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1403 \subsubsection{Code Objects \label{bltin-code-objects}}
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1404 \obindex{code}
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1405
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1406 Code objects are used by the implementation to represent
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1407 ``pseudo-compiled'' executable Python code such as a function body.
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1408 They differ from function objects because they don't contain a
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1409 reference to their global execution environment. Code objects are
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1410 returned by the built-in \function{compile()} function and can be
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1411 extracted from function objects through their \member{func_code}
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1412 attribute.
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1413 \bifuncindex{compile}
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1414 \withsubitem{(function object attribute)}{\ttindex{func_code}}
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1415
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1416 A code object can be executed or evaluated by passing it (instead of a
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1417 source string) to the \keyword{exec} statement or the built-in
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1418 \function{eval()} function.
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1419 \stindex{exec}
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1420 \bifuncindex{eval}
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1421
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1422 See the \citetitle[../ref/ref.html]{Python Reference Manual} for more
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1423 information.
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1424
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1425
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1426 \subsubsection{Type Objects \label{bltin-type-objects}}
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1427
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1428 Type objects represent the various object types. An object's type is
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1429 accessed by the built-in function \function{type()}. There are no special
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1430 operations on types. The standard module \module{types} defines names
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1431 for all standard built-in types.
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1432 \bifuncindex{type}
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1433 \refstmodindex{types}
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1434
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1435 Types are written like this: \code{<type 'int'>}.
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1436
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1437
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1438 \subsubsection{The Null Object \label{bltin-null-object}}
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1439
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1440 This object is returned by functions that don't explicitly return a
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1441 value. It supports no special operations. There is exactly one null
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1442 object, named \code{None} (a built-in name).
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1443
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1444 It is written as \code{None}.
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1445
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1446
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1447 \subsubsection{The Ellipsis Object \label{bltin-ellipsis-object}}
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1448
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1449 This object is used by extended slice notation (see the
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1450 \citetitle[../ref/ref.html]{Python Reference Manual}). It supports no
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1451 special operations. There is exactly one ellipsis object, named
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1452 \constant{Ellipsis} (a built-in name).
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1453
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1454 It is written as \code{Ellipsis}.
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1455
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1456
10156
0f7d694bc334 Make sure all HTML pages generated from this section have reasonable
Fred Drake <fdrake@acm.org>
parents: 10147
diff changeset
1457 \subsubsection{Internal Objects \label{typesinternal}}
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1458
11463
17e12305973e Use \citetitle and \programopt as appropriate.
Fred Drake <fdrake@acm.org>
parents: 11183
diff changeset
1459 See the \citetitle[../ref/ref.html]{Python Reference Manual} for this
14044
a905c5aa0691 As pointed out by Denis S. Otkidach <den@analyt.chem.msu.ru>, xrange()
Fred Drake <fdrake@acm.org>
parents: 13967
diff changeset
1460 information. It describes stack frame objects, traceback objects, and
a905c5aa0691 As pointed out by Denis S. Otkidach <den@analyt.chem.msu.ru>, xrange()
Fred Drake <fdrake@acm.org>
parents: 13967
diff changeset
1461 slice objects.
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1462
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1463
9083
bc41e86c938c Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9034
diff changeset
1464 \subsection{Special Attributes \label{specialattrs}}
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1465
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1466 The implementation adds a few special read-only attributes to several
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1467 object types, where they are relevant:
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1468
15383
eeb7c8a5b79f Document the proper exception to be raised by I/O operations on closed
Fred Drake <fdrake@acm.org>
parents: 15332
diff changeset
1469 \begin{memberdesc}[object]{__dict__}
eeb7c8a5b79f Document the proper exception to be raised by I/O operations on closed
Fred Drake <fdrake@acm.org>
parents: 15332
diff changeset
1470 A dictionary or other mapping object used to store an
9083
bc41e86c938c Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9034
diff changeset
1471 object's (writable) attributes.
15383
eeb7c8a5b79f Document the proper exception to be raised by I/O operations on closed
Fred Drake <fdrake@acm.org>
parents: 15332
diff changeset
1472 \end{memberdesc}
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1473
15383
eeb7c8a5b79f Document the proper exception to be raised by I/O operations on closed
Fred Drake <fdrake@acm.org>
parents: 15332
diff changeset
1474 \begin{memberdesc}[object]{__methods__}
21159
6fa96b329e15 Remove most references to __members__ and __methods__, leaving only one pair
Fred Drake <fdrake@acm.org>
parents: 21062
diff changeset
1475 \deprecated{2.2}{Use the built-in function \function{dir()} to get a
6fa96b329e15 Remove most references to __members__ and __methods__, leaving only one pair
Fred Drake <fdrake@acm.org>
parents: 21062
diff changeset
1476 list of an object's attributes. This attribute is no longer available.}
15383
eeb7c8a5b79f Document the proper exception to be raised by I/O operations on closed
Fred Drake <fdrake@acm.org>
parents: 15332
diff changeset
1477 \end{memberdesc}
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1478
15383
eeb7c8a5b79f Document the proper exception to be raised by I/O operations on closed
Fred Drake <fdrake@acm.org>
parents: 15332
diff changeset
1479 \begin{memberdesc}[object]{__members__}
21159
6fa96b329e15 Remove most references to __members__ and __methods__, leaving only one pair
Fred Drake <fdrake@acm.org>
parents: 21062
diff changeset
1480 \deprecated{2.2}{Use the built-in function \function{dir()} to get a
6fa96b329e15 Remove most references to __members__ and __methods__, leaving only one pair
Fred Drake <fdrake@acm.org>
parents: 21062
diff changeset
1481 list of an object's attributes. This attribute is no longer available.}
15383
eeb7c8a5b79f Document the proper exception to be raised by I/O operations on closed
Fred Drake <fdrake@acm.org>
parents: 15332
diff changeset
1482 \end{memberdesc}
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1483
15383
eeb7c8a5b79f Document the proper exception to be raised by I/O operations on closed
Fred Drake <fdrake@acm.org>
parents: 15332
diff changeset
1484 \begin{memberdesc}[instance]{__class__}
eeb7c8a5b79f Document the proper exception to be raised by I/O operations on closed
Fred Drake <fdrake@acm.org>
parents: 15332
diff changeset
1485 The class to which a class instance belongs.
eeb7c8a5b79f Document the proper exception to be raised by I/O operations on closed
Fred Drake <fdrake@acm.org>
parents: 15332
diff changeset
1486 \end{memberdesc}
eeb7c8a5b79f Document the proper exception to be raised by I/O operations on closed
Fred Drake <fdrake@acm.org>
parents: 15332
diff changeset
1487
eeb7c8a5b79f Document the proper exception to be raised by I/O operations on closed
Fred Drake <fdrake@acm.org>
parents: 15332
diff changeset
1488 \begin{memberdesc}[class]{__bases__}
18416
33b4357aebb8 Fix up a few style nits -- avoid "e.g." and "i.e." -- these make
Fred Drake <fdrake@acm.org>
parents: 18395
diff changeset
1489 The tuple of base classes of a class object. If there are no base
33b4357aebb8 Fix up a few style nits -- avoid "e.g." and "i.e." -- these make
Fred Drake <fdrake@acm.org>
parents: 18395
diff changeset
1490 classes, this will be an empty tuple.
15383
eeb7c8a5b79f Document the proper exception to be raised by I/O operations on closed
Fred Drake <fdrake@acm.org>
parents: 15332
diff changeset
1491 \end{memberdesc}