blob: c3a54f60f1354cb0b49672fdac4a2743e21ab7ea [file] [log] [blame]
Fred Drake7a2f0661998-09-10 18:25:58 +00001\section{Built-in Types \label{types}}
Fred Drake64e3b431998-07-24 13:56:11 +00002
3The following sections describe the standard types that are built into
4the interpreter. These are the numeric types, sequence types, and
5several others, including types themselves. There is no explicit
6Boolean type; use integers instead.
7\indexii{built-in}{types}
8\indexii{Boolean}{type}
9
10Some operations are supported by several object types; in particular,
11all objects can be compared, tested for truth value, and converted to
Fred Drake84538cd1998-11-30 21:51:25 +000012a string (with the \code{`\textrm{\ldots}`} notation). The latter
13conversion is implicitly used when an object is written by the
14\keyword{print}\stindex{print} statement.
Fred Drake64e3b431998-07-24 13:56:11 +000015
16
Fred Drake7a2f0661998-09-10 18:25:58 +000017\subsection{Truth Value Testing \label{truth}}
Fred Drake64e3b431998-07-24 13:56:11 +000018
Fred Drake84538cd1998-11-30 21:51:25 +000019Any object can be tested for truth value, for use in an \keyword{if} or
20\keyword{while} condition or as operand of the Boolean operations below.
Fred Drake64e3b431998-07-24 13:56:11 +000021The following values are considered false:
22\stindex{if}
23\stindex{while}
24\indexii{truth}{value}
25\indexii{Boolean}{operations}
26\index{false}
27
Fred Drake64e3b431998-07-24 13:56:11 +000028\begin{itemize}
29
30\item \code{None}
Fred Drake7a2f0661998-09-10 18:25:58 +000031 \withsubitem{(Built-in object)}{\ttindex{None}}
Fred Drake64e3b431998-07-24 13:56:11 +000032
33\item zero of any numeric type, e.g., \code{0}, \code{0L}, \code{0.0}.
34
35\item any empty sequence, e.g., \code{''}, \code{()}, \code{[]}.
36
37\item any empty mapping, e.g., \code{\{\}}.
38
39\item instances of user-defined classes, if the class defines a
Fred Drake7a2f0661998-09-10 18:25:58 +000040 \method{__nonzero__()} or \method{__len__()} method, when that
Fred Drake64e3b431998-07-24 13:56:11 +000041 method returns zero.
42
43\end{itemize}
44
45All other values are considered true --- so objects of many types are
46always true.
47\index{true}
48
49Operations and built-in functions that have a Boolean result always
50return \code{0} for false and \code{1} for true, unless otherwise
51stated. (Important exception: the Boolean operations
52\samp{or}\opindex{or} and \samp{and}\opindex{and} always return one of
53their operands.)
54
55
Fred Drake7a2f0661998-09-10 18:25:58 +000056\subsection{Boolean Operations \label{boolean}}
Fred Drake64e3b431998-07-24 13:56:11 +000057
58These are the Boolean operations, ordered by ascending priority:
59\indexii{Boolean}{operations}
60
61\begin{tableiii}{c|l|c}{code}{Operation}{Result}{Notes}
62 \lineiii{\var{x} or \var{y}}{if \var{x} is false, then \var{y}, else \var{x}}{(1)}
63 \lineiii{\var{x} and \var{y}}{if \var{x} is false, then \var{x}, else \var{y}}{(1)}
64 \hline
65 \lineiii{not \var{x}}{if \var{x} is false, then \code{1}, else \code{0}}{(2)}
66\end{tableiii}
67\opindex{and}
68\opindex{or}
69\opindex{not}
70
71\noindent
72Notes:
73
74\begin{description}
75
76\item[(1)]
77These only evaluate their second argument if needed for their outcome.
78
79\item[(2)]
80\samp{not} has a lower priority than non-Boolean operators, so e.g.
81\code{not a == b} is interpreted as \code{not(a == b)}, and
82\code{a == not b} is a syntax error.
83
84\end{description}
85
86
Fred Drake7a2f0661998-09-10 18:25:58 +000087\subsection{Comparisons \label{comparisons}}
Fred Drake64e3b431998-07-24 13:56:11 +000088
89Comparison operations are supported by all objects. They all have the
90same priority (which is higher than that of the Boolean operations).
91Comparisons can be chained arbitrarily, e.g. \code{x < y <= z} is
92equivalent to \code{x < y and y <= z}, except that \code{y} is
93evaluated only once (but in both cases \code{z} is not evaluated at
94all when \code{x < y} is found to be false).
95\indexii{chaining}{comparisons}
96
97This table summarizes the comparison operations:
98
99\begin{tableiii}{c|l|c}{code}{Operation}{Meaning}{Notes}
100 \lineiii{<}{strictly less than}{}
101 \lineiii{<=}{less than or equal}{}
102 \lineiii{>}{strictly greater than}{}
103 \lineiii{>=}{greater than or equal}{}
104 \lineiii{==}{equal}{}
105 \lineiii{<>}{not equal}{(1)}
106 \lineiii{!=}{not equal}{(1)}
107 \lineiii{is}{object identity}{}
108 \lineiii{is not}{negated object identity}{}
109\end{tableiii}
110\indexii{operator}{comparison}
111\opindex{==} % XXX *All* others have funny characters < ! >
112\opindex{is}
113\opindex{is not}
114
115\noindent
116Notes:
117
118\begin{description}
119
120\item[(1)]
121\code{<>} and \code{!=} are alternate spellings for the same operator.
122(I couldn't choose between \ABC{} and \C{}! :-)
123\index{ABC language@\ABC{} language}
124\index{language!ABC@\ABC{}}
125\indexii{C@\C{}}{language}
126
127\end{description}
128
129Objects of different types, except different numeric types, never
130compare equal; such objects are ordered consistently but arbitrarily
131(so that sorting a heterogeneous array yields a consistent result).
132Furthermore, some types (e.g., windows) support only a degenerate
133notion of comparison where any two objects of that type are unequal.
134Again, such objects are ordered arbitrarily but consistently.
135\indexii{types}{numeric}
136\indexii{objects}{comparing}
137
138(Implementation note: objects of different types except numbers are
139ordered by their type names; objects of the same types that don't
140support proper comparison are ordered by their address.)
141
142Two more operations with the same syntactic priority, \samp{in} and
143\samp{not in}, are supported only by sequence types (below).
144\opindex{in}
145\opindex{not in}
146
147
Fred Drake7a2f0661998-09-10 18:25:58 +0000148\subsection{Numeric Types \label{typesnumeric}}
Fred Drake64e3b431998-07-24 13:56:11 +0000149
150There are four numeric types: \dfn{plain integers}, \dfn{long integers},
151\dfn{floating point numbers}, and \dfn{complex numbers}.
152Plain integers (also just called \dfn{integers})
Fred Drake84538cd1998-11-30 21:51:25 +0000153are implemented using \ctype{long} in \C{}, which gives them at least 32
Fred Drake64e3b431998-07-24 13:56:11 +0000154bits of precision. Long integers have unlimited precision. Floating
Fred Drake84538cd1998-11-30 21:51:25 +0000155point numbers are implemented using \ctype{double} in \C{}. All bets on
Fred Drake64e3b431998-07-24 13:56:11 +0000156their precision are off unless you happen to know the machine you are
157working with.
158\indexii{numeric}{types}
159\indexii{integer}{types}
160\indexii{integer}{type}
161\indexiii{long}{integer}{type}
162\indexii{floating point}{type}
163\indexii{complex number}{type}
164\indexii{C@\C{}}{language}
165
166Complex numbers have a real and imaginary part, which are both
Fred Drake84538cd1998-11-30 21:51:25 +0000167implemented using \ctype{double} in \C{}. To extract these parts from
Fred Drake64e3b431998-07-24 13:56:11 +0000168a complex number \var{z}, use \code{\var{z}.real} and \code{\var{z}.imag}.
169
170Numbers are created by numeric literals or as the result of built-in
171functions and operators. Unadorned integer literals (including hex
172and octal numbers) yield plain integers. Integer literals with an \samp{L}
173or \samp{l} suffix yield long integers
174(\samp{L} is preferred because \samp{1l} looks too much like eleven!).
175Numeric literals containing a decimal point or an exponent sign yield
176floating point numbers. Appending \samp{j} or \samp{J} to a numeric
177literal yields a complex number.
178\indexii{numeric}{literals}
179\indexii{integer}{literals}
180\indexiii{long}{integer}{literals}
181\indexii{floating point}{literals}
182\indexii{complex number}{literals}
183\indexii{hexadecimal}{literals}
184\indexii{octal}{literals}
185
186Python fully supports mixed arithmetic: when a binary arithmetic
187operator has operands of different numeric types, the operand with the
188``smaller'' type is converted to that of the other, where plain
189integer is smaller than long integer is smaller than floating point is
190smaller than complex.
191Comparisons between numbers of mixed type use the same rule.%
192\footnote{As a consequence, the list \code{[1, 2]} is considered equal
Fred Drake84538cd1998-11-30 21:51:25 +0000193 to \code{[1.0, 2.0]}, and similar for tuples.}
194The functions \function{int()}, \function{long()}, \function{float()},
195and \function{complex()} can be used
Fred Drake64e3b431998-07-24 13:56:11 +0000196to coerce numbers to a specific type.
197\index{arithmetic}
198\bifuncindex{int}
199\bifuncindex{long}
200\bifuncindex{float}
201\bifuncindex{complex}
202
203All numeric types support the following operations, sorted by
204ascending priority (operations in the same box have the same
205priority; all numeric operations have a higher priority than
206comparison operations):
207
208\begin{tableiii}{c|l|c}{code}{Operation}{Result}{Notes}
209 \lineiii{\var{x} + \var{y}}{sum of \var{x} and \var{y}}{}
210 \lineiii{\var{x} - \var{y}}{difference of \var{x} and \var{y}}{}
211 \hline
212 \lineiii{\var{x} * \var{y}}{product of \var{x} and \var{y}}{}
213 \lineiii{\var{x} / \var{y}}{quotient of \var{x} and \var{y}}{(1)}
214 \lineiii{\var{x} \%{} \var{y}}{remainder of \code{\var{x} / \var{y}}}{}
215 \hline
216 \lineiii{-\var{x}}{\var{x} negated}{}
217 \lineiii{+\var{x}}{\var{x} unchanged}{}
218 \hline
219 \lineiii{abs(\var{x})}{absolute value or magnitude of \var{x}}{}
220 \lineiii{int(\var{x})}{\var{x} converted to integer}{(2)}
221 \lineiii{long(\var{x})}{\var{x} converted to long integer}{(2)}
222 \lineiii{float(\var{x})}{\var{x} converted to floating point}{}
223 \lineiii{complex(\var{re},\var{im})}{a complex number with real part \var{re}, imaginary part \var{im}. \var{im} defaults to zero.}{}
Fred Drake26b698f1999-02-12 18:27:31 +0000224 \lineiii{\var{c}.conjugate()}{conjugate of the complex number \var{c}}{}
Fred Drake64e3b431998-07-24 13:56:11 +0000225 \lineiii{divmod(\var{x}, \var{y})}{the pair \code{(\var{x} / \var{y}, \var{x} \%{} \var{y})}}{(3)}
226 \lineiii{pow(\var{x}, \var{y})}{\var{x} to the power \var{y}}{}
227 \lineiii{\var{x} ** \var{y}}{\var{x} to the power \var{y}}{}
228\end{tableiii}
229\indexiii{operations on}{numeric}{types}
Fred Drake26b698f1999-02-12 18:27:31 +0000230\withsubitem{(complex number method)}{\ttindex{conjugate()}}
Fred Drake64e3b431998-07-24 13:56:11 +0000231
232\noindent
233Notes:
234\begin{description}
235
236\item[(1)]
237For (plain or long) integer division, the result is an integer.
238The result is always rounded towards minus infinity: 1/2 is 0,
239(-1)/2 is -1, 1/(-2) is -1, and (-1)/(-2) is 0.
240\indexii{integer}{division}
241\indexiii{long}{integer}{division}
242
243\item[(2)]
244Conversion from floating point to (long or plain) integer may round or
Fred Drake84538cd1998-11-30 21:51:25 +0000245truncate as in \C{}; see functions \function{floor()} and \function{ceil()} in
246module \module{math} for well-defined conversions.
Fred Drake9474d861999-02-12 22:05:33 +0000247\withsubitem{(in module math)}{\ttindex{floor()}\ttindex{ceil()}}
Fred Drake64e3b431998-07-24 13:56:11 +0000248\indexii{numeric}{conversions}
249\refbimodindex{math}
250\indexii{C@\C{}}{language}
251
252\item[(3)]
253See the section on built-in functions for an exact definition.
254
255\end{description}
256% XXXJH exceptions: overflow (when? what operations?) zerodivision
257
258\subsubsection{Bit-string Operations on Integer Types}
259\nodename{Bit-string Operations}
260
261Plain and long integer types support additional operations that make
262sense only for bit-strings. Negative numbers are treated as their 2's
263complement value (for long integers, this assumes a sufficiently large
264number of bits that no overflow occurs during the operation).
265
266The priorities of the binary bit-wise operations are all lower than
267the numeric operations and higher than the comparisons; the unary
268operation \samp{\~} has the same priority as the other unary numeric
269operations (\samp{+} and \samp{-}).
270
271This table lists the bit-string operations sorted in ascending
272priority (operations in the same box have the same priority):
273
274\begin{tableiii}{c|l|c}{code}{Operation}{Result}{Notes}
275 \lineiii{\var{x} | \var{y}}{bitwise \dfn{or} of \var{x} and \var{y}}{}
276 \lineiii{\var{x} \^{} \var{y}}{bitwise \dfn{exclusive or} of \var{x} and \var{y}}{}
277 \lineiii{\var{x} \&{} \var{y}}{bitwise \dfn{and} of \var{x} and \var{y}}{}
278 \lineiii{\var{x} << \var{n}}{\var{x} shifted left by \var{n} bits}{(1), (2)}
279 \lineiii{\var{x} >> \var{n}}{\var{x} shifted right by \var{n} bits}{(1), (3)}
280 \hline
281 \lineiii{\~\var{x}}{the bits of \var{x} inverted}{}
282\end{tableiii}
283\indexiii{operations on}{integer}{types}
284\indexii{bit-string}{operations}
285\indexii{shifting}{operations}
286\indexii{masking}{operations}
287
288\noindent
289Notes:
290\begin{description}
291\item[(1)] Negative shift counts are illegal and cause a
292\exception{ValueError} to be raised.
293\item[(2)] A left shift by \var{n} bits is equivalent to
294multiplication by \code{pow(2, \var{n})} without overflow check.
295\item[(3)] A right shift by \var{n} bits is equivalent to
296division by \code{pow(2, \var{n})} without overflow check.
297\end{description}
298
299
Fred Drake7a2f0661998-09-10 18:25:58 +0000300\subsection{Sequence Types \label{typesseq}}
Fred Drake64e3b431998-07-24 13:56:11 +0000301
302There are three sequence types: strings, lists and tuples.
303
304Strings literals are written in single or double quotes:
305\code{'xyzzy'}, \code{"frobozz"}. See Chapter 2 of the \emph{Python
306Reference Manual} for more about string literals. Lists are
307constructed with square brackets, separating items with commas:
308\code{[a, b, c]}. Tuples are constructed by the comma operator (not
309within square brackets), with or without enclosing parentheses, but an
310empty tuple must have the enclosing parentheses, e.g.,
311\code{a, b, c} or \code{()}. A single item tuple must have a trailing
312comma, e.g., \code{(d,)}.
313\indexii{sequence}{types}
314\indexii{string}{type}
315\indexii{tuple}{type}
316\indexii{list}{type}
317
318Sequence types support the following operations. The \samp{in} and
319\samp{not in} operations have the same priorities as the comparison
320operations. The \samp{+} and \samp{*} operations have the same
321priority as the corresponding numeric operations.\footnote{They must
322have since the parser can't tell the type of the operands.}
323
324This table lists the sequence operations sorted in ascending priority
325(operations in the same box have the same priority). In the table,
326\var{s} and \var{t} are sequences of the same type; \var{n}, \var{i}
327and \var{j} are integers:
328
329\begin{tableiii}{c|l|c}{code}{Operation}{Result}{Notes}
330 \lineiii{\var{x} in \var{s}}{\code{1} if an item of \var{s} is equal to \var{x}, else \code{0}}{}
331 \lineiii{\var{x} not in \var{s}}{\code{0} if an item of \var{s} is
332equal to \var{x}, else \code{1}}{}
333 \hline
334 \lineiii{\var{s} + \var{t}}{the concatenation of \var{s} and \var{t}}{}
Fred Drake84538cd1998-11-30 21:51:25 +0000335 \lineiii{\var{s} * \var{n}\textrm{,} \var{n} * \var{s}}{\var{n} copies of \var{s} concatenated}{(3)}
Fred Drake64e3b431998-07-24 13:56:11 +0000336 \hline
337 \lineiii{\var{s}[\var{i}]}{\var{i}'th item of \var{s}, origin 0}{(1)}
338 \lineiii{\var{s}[\var{i}:\var{j}]}{slice of \var{s} from \var{i} to \var{j}}{(1), (2)}
339 \hline
340 \lineiii{len(\var{s})}{length of \var{s}}{}
341 \lineiii{min(\var{s})}{smallest item of \var{s}}{}
342 \lineiii{max(\var{s})}{largest item of \var{s}}{}
343\end{tableiii}
344\indexiii{operations on}{sequence}{types}
345\bifuncindex{len}
346\bifuncindex{min}
347\bifuncindex{max}
348\indexii{concatenation}{operation}
349\indexii{repetition}{operation}
350\indexii{subscript}{operation}
351\indexii{slice}{operation}
352\opindex{in}
353\opindex{not in}
354
355\noindent
356Notes:
357
358\begin{description}
359
360\item[(1)] If \var{i} or \var{j} is negative, the index is relative to
361 the end of the string, i.e., \code{len(\var{s}) + \var{i}} or
362 \code{len(\var{s}) + \var{j}} is substituted. But note that \code{-0} is
363 still \code{0}.
364
365\item[(2)] The slice of \var{s} from \var{i} to \var{j} is defined as
366 the sequence of items with index \var{k} such that \code{\var{i} <=
367 \var{k} < \var{j}}. If \var{i} or \var{j} is greater than
368 \code{len(\var{s})}, use \code{len(\var{s})}. If \var{i} is omitted,
369 use \code{0}. If \var{j} is omitted, use \code{len(\var{s})}. If
370 \var{i} is greater than or equal to \var{j}, the slice is empty.
371
372\item[(3)] Values of \var{n} less than \code{0} are treated as
373 \code{0} (which yields an empty sequence of the same type as
374 \var{s}).
375
376\end{description}
377
Fred Drake9474d861999-02-12 22:05:33 +0000378
379\subsubsection{More String Operations \label{typesseq-strings}}
Fred Drake64e3b431998-07-24 13:56:11 +0000380
381String objects have one unique built-in operation: the \code{\%}
382operator (modulo) with a string left argument interprets this string
383as a \C{} \cfunction{sprintf()} format string to be applied to the
384right argument, and returns the string resulting from this formatting
385operation.
386
387The right argument should be a tuple with one item for each argument
388required by the format string; if the string requires a single
389argument, the right argument may also be a single non-tuple object.%
390\footnote{A tuple object in this case should be a singleton.}
391The following format characters are understood:
392\code{\%}, \code{c}, \code{s}, \code{i}, \code{d}, \code{u}, \code{o},
393\code{x}, \code{X}, \code{e}, \code{E}, \code{f}, \code{g}, \code{G}.
394Width and precision may be a \code{*} to specify that an integer argument
395specifies the actual width or precision. The flag characters
396\code{-}, \code{+}, blank, \code{\#} and \code{0} are understood. The
397size specifiers \code{h}, \code{l} or \code{L} may be
398present but are ignored. The \code{\%s} conversion takes any Python
399object and converts it to a string using \code{str()} before
400formatting it. The ANSI features \code{\%p} and \code{\%n}
401are not supported. Since Python strings have an explicit length,
402\code{\%s} conversions don't assume that \code{'\e0'} is the end of
403the string.
404
405For safety reasons, floating point precisions are clipped to 50;
406\code{\%f} conversions for numbers whose absolute value is over 1e25
407are replaced by \code{\%g} conversions.%
408\footnote{These numbers are fairly arbitrary. They are intended to
409avoid printing endless strings of meaningless digits without hampering
410correct use and without having to know the exact precision of floating
411point values on a particular machine.}
412All other errors raise exceptions.
413
414If the right argument is a dictionary (or any kind of mapping), then
415the formats in the string must have a parenthesized key into that
416dictionary inserted immediately after the \character{\%} character,
417and each format formats the corresponding entry from the mapping.
418For example:
419
420\begin{verbatim}
421>>> count = 2
422>>> language = 'Python'
423>>> print '%(language)s has %(count)03d quote types.' % vars()
424Python has 002 quote types.
425\end{verbatim}
426
427In this case no \code{*} specifiers may occur in a format (since they
428require a sequential parameter list).
429
430Additional string operations are defined in standard module
431\module{string} and in built-in module \module{re}.
432\refstmodindex{string}
Fred Drake66da9d61998-08-07 18:57:18 +0000433\refstmodindex{re}
Fred Drake64e3b431998-07-24 13:56:11 +0000434
Fred Drake9474d861999-02-12 22:05:33 +0000435\subsubsection{Mutable Sequence Types \label{typesseq-mutable}}
Fred Drake64e3b431998-07-24 13:56:11 +0000436
437List objects support additional operations that allow in-place
438modification of the object.
439These operations would be supported by other mutable sequence types
440(when added to the language) as well.
441Strings and tuples are immutable sequence types and such objects cannot
442be modified once created.
443The following operations are defined on mutable sequence types (where
444\var{x} is an arbitrary object):
445\indexiii{mutable}{sequence}{types}
446\indexii{list}{type}
447
448\begin{tableiii}{c|l|c}{code}{Operation}{Result}{Notes}
449 \lineiii{\var{s}[\var{i}] = \var{x}}
450 {item \var{i} of \var{s} is replaced by \var{x}}{}
451 \lineiii{\var{s}[\var{i}:\var{j}] = \var{t}}
452 {slice of \var{s} from \var{i} to \var{j} is replaced by \var{t}}{}
453 \lineiii{del \var{s}[\var{i}:\var{j}]}
454 {same as \code{\var{s}[\var{i}:\var{j}] = []}}{}
455 \lineiii{\var{s}.append(\var{x})}
456 {same as \code{\var{s}[len(\var{s}):len(\var{s})] = [\var{x}]}}{}
Barry Warsawafd974c1998-10-09 16:39:58 +0000457 \lineiii{\var{s}.extend(\var{x})}
458 {same as \code{\var{s}[len(\var{s}):len(\var{s})] = \var{x}}}{(5)}
Fred Drake64e3b431998-07-24 13:56:11 +0000459 \lineiii{\var{s}.count(\var{x})}
460 {return number of \var{i}'s for which \code{\var{s}[\var{i}] == \var{x}}}{}
461 \lineiii{\var{s}.index(\var{x})}
462 {return smallest \var{i} such that \code{\var{s}[\var{i}] == \var{x}}}{(1)}
463 \lineiii{\var{s}.insert(\var{i}, \var{x})}
464 {same as \code{\var{s}[\var{i}:\var{i}] = [\var{x}]}
465 if \code{\var{i} >= 0}}{}
466 \lineiii{\var{s}.pop(\optional{\var{i}})}
467 {same as \code{\var{x} = \var{s}[\var{i}]; del \var{s}[\var{i}]; return \var{x}}}{(4)}
468 \lineiii{\var{s}.remove(\var{x})}
469 {same as \code{del \var{s}[\var{s}.index(\var{x})]}}{(1)}
470 \lineiii{\var{s}.reverse()}
471 {reverses the items of \var{s} in place}{(3)}
472 \lineiii{\var{s}.sort(\optional{\var{cmpfunc}})}
473 {sort the items of \var{s} in place}{(2), (3)}
474\end{tableiii}
475\indexiv{operations on}{mutable}{sequence}{types}
476\indexiii{operations on}{sequence}{types}
477\indexiii{operations on}{list}{type}
478\indexii{subscript}{assignment}
479\indexii{slice}{assignment}
480\stindex{del}
Fred Drake9474d861999-02-12 22:05:33 +0000481\withsubitem{(list method)}{
482 \ttindex{append()}
483 \ttindex{extend()}
484 \ttindex{count()}
485 \ttindex{index()}
486 \ttindex{insert()}
487 \ttindex{pop()}
488 \ttindex{remove()}
489 \ttindex{reverse()}
Fred Drakee8391991998-11-25 17:09:19 +0000490 \ttindex{sort()}}
Fred Drake64e3b431998-07-24 13:56:11 +0000491\noindent
492Notes:
493\begin{description}
494\item[(1)] Raises an exception when \var{x} is not found in \var{s}.
495
Fred Drake84538cd1998-11-30 21:51:25 +0000496\item[(2)] The \method{sort()} method takes an optional argument
Fred Drake64e3b431998-07-24 13:56:11 +0000497 specifying a comparison function of two arguments (list items) which
498 should return \code{-1}, \code{0} or \code{1} depending on whether the
499 first argument is considered smaller than, equal to, or larger than the
500 second argument. Note that this slows the sorting process down
501 considerably; e.g. to sort a list in reverse order it is much faster
Fred Drake84538cd1998-11-30 21:51:25 +0000502 to use calls to the methods \method{sort()} and \method{reverse()}
503 than to use the built-in function \function{sort()} with a
504 comparison function that reverses the ordering of the elements.
Fred Drake64e3b431998-07-24 13:56:11 +0000505
Fred Drake84538cd1998-11-30 21:51:25 +0000506\item[(3)] The \method{sort()} and \method{reverse()} methods modify the
Fred Drake64e3b431998-07-24 13:56:11 +0000507list in place for economy of space when sorting or reversing a large
508list. They don't return the sorted or reversed list to remind you of
509this side effect.
510
511\item[(4)] The \method{pop()} method is experimental and not supported
512by other mutable sequence types than lists.
513The optional argument \var{i} defaults to \code{-1}, so that
514by default the last item is removed and returned.
515
Barry Warsawafd974c1998-10-09 16:39:58 +0000516\item[(5)] Raises an exception when \var{x} is not a list object. The
517\method{extend()} method is experimental and not supported by mutable types
518other than lists.
Fred Drake64e3b431998-07-24 13:56:11 +0000519\end{description}
520
521
Fred Drake7a2f0661998-09-10 18:25:58 +0000522\subsection{Mapping Types \label{typesmapping}}
Fred Drake64e3b431998-07-24 13:56:11 +0000523
524A \dfn{mapping} object maps values of one type (the key type) to
525arbitrary objects. Mappings are mutable objects. There is currently
526only one standard mapping type, the \dfn{dictionary}. A dictionary's keys are
527almost arbitrary values. The only types of values not acceptable as
528keys are values containing lists or dictionaries or other mutable
529types that are compared by value rather than by object identity.
530Numeric types used for keys obey the normal rules for numeric
531comparison: if two numbers compare equal (e.g. \code{1} and
532\code{1.0}) then they can be used interchangeably to index the same
533dictionary entry.
534
535\indexii{mapping}{types}
536\indexii{dictionary}{type}
537
538Dictionaries are created by placing a comma-separated list of
539\code{\var{key}: \var{value}} pairs within braces, for example:
540\code{\{'jack': 4098, 'sjoerd': 4127\}} or
541\code{\{4098: 'jack', 4127: 'sjoerd'\}}.
542
543The following operations are defined on mappings (where \var{a} is a
544mapping, \var{k} is a key and \var{x} is an arbitrary object):
545
546\begin{tableiii}{c|l|c}{code}{Operation}{Result}{Notes}
547 \lineiii{len(\var{a})}{the number of items in \var{a}}{}
548 \lineiii{\var{a}[\var{k}]}{the item of \var{a} with key \var{k}}{(1)}
549 \lineiii{\var{a}[\var{k}] = \var{x}}{set \code{\var{a}[\var{k}]} to \var{x}}{}
550 \lineiii{del \var{a}[\var{k}]}{remove \code{\var{a}[\var{k}]} from \var{a}}{(1)}
551 \lineiii{\var{a}.clear()}{remove all items from \code{a}}{}
552 \lineiii{\var{a}.copy()}{a (shallow) copy of \code{a}}{}
553 \lineiii{\var{a}.has_key(\var{k})}{\code{1} if \var{a} has a key \var{k}, else \code{0}}{}
Fred Drake7a2f0661998-09-10 18:25:58 +0000554 \lineiii{\var{a}.items()}{a copy of \var{a}'s list of (\var{key}, \var{value}) pairs}{(2)}
Fred Drake64e3b431998-07-24 13:56:11 +0000555 \lineiii{\var{a}.keys()}{a copy of \var{a}'s list of keys}{(2)}
556 \lineiii{\var{a}.update(\var{b})}{\code{for k, v in \var{b}.items(): \var{a}[k] = v}}{(3)}
557 \lineiii{\var{a}.values()}{a copy of \var{a}'s list of values}{(2)}
Fred Drake7a2f0661998-09-10 18:25:58 +0000558 \lineiii{\var{a}.get(\var{k}\optional{, \var{f}})}{the value of \var{a} with key \var{k}}{(4)}
Fred Drake64e3b431998-07-24 13:56:11 +0000559\end{tableiii}
560\indexiii{operations on}{mapping}{types}
561\indexiii{operations on}{dictionary}{type}
562\stindex{del}
563\bifuncindex{len}
Fred Drake9474d861999-02-12 22:05:33 +0000564\withsubitem{(dictionary method)}{
565 \ttindex{clear()}
566 \ttindex{copy()}
567 \ttindex{has_key()}
568 \ttindex{items()}
569 \ttindex{keys()}
570 \ttindex{update()}
571 \ttindex{values()}
Fred Drakee8391991998-11-25 17:09:19 +0000572 \ttindex{get()}}
Fred Drake64e3b431998-07-24 13:56:11 +0000573\noindent
574Notes:
575\begin{description}
576\item[(1)] Raises an exception if \var{k} is not in the map.
577
578\item[(2)] Keys and values are listed in random order.
579
580\item[(3)] \var{b} must be of the same type as \var{a}.
581
582\item[(4)] Never raises an exception if \var{k} is not in the map,
583instead it returns \var{f}. \var{f} is optional, when not provided
584and \var{k} is not in the map, \code{None} is returned.
585\end{description}
586
587
Fred Drake7a2f0661998-09-10 18:25:58 +0000588\subsection{Other Built-in Types \label{typesother}}
Fred Drake64e3b431998-07-24 13:56:11 +0000589
590The interpreter supports several other kinds of objects.
591Most of these support only one or two operations.
592
Fred Drake9474d861999-02-12 22:05:33 +0000593\subsubsection{Modules \label{typesmodules}}
Fred Drake64e3b431998-07-24 13:56:11 +0000594
595The only special operation on a module is attribute access:
596\code{\var{m}.\var{name}}, where \var{m} is a module and \var{name}
597accesses a name defined in \var{m}'s symbol table. Module attributes
Fred Drake84538cd1998-11-30 21:51:25 +0000598can be assigned to. (Note that the \keyword{import} statement is not,
Fred Draked0421dd1998-08-24 17:57:20 +0000599strictly speaking, an operation on a module object; \code{import
Fred Drake64e3b431998-07-24 13:56:11 +0000600\var{foo}} does not require a module object named \var{foo} to exist,
601rather it requires an (external) \emph{definition} for a module named
602\var{foo} somewhere.)
603
Fred Drake84538cd1998-11-30 21:51:25 +0000604A special member of every module is \member{__dict__}.
Fred Drake64e3b431998-07-24 13:56:11 +0000605This is the dictionary containing the module's symbol table.
606Modifying this dictionary will actually change the module's symbol
Fred Drake84538cd1998-11-30 21:51:25 +0000607table, but direct assignment to the \member{__dict__} attribute is not
Fred Drake64e3b431998-07-24 13:56:11 +0000608possible (i.e., you can write \code{\var{m}.__dict__['a'] = 1}, which
609defines \code{\var{m}.a} to be \code{1}, but you can't write
610\code{\var{m}.__dict__ = \{\}}.
611
612Modules are written like this: \code{<module 'sys'>}.
613
Fred Drake9474d861999-02-12 22:05:33 +0000614\subsubsection{Classes and Class Instances \label{typesobjects}}
Fred Drake64e3b431998-07-24 13:56:11 +0000615\nodename{Classes and Instances}
616
617See Chapters 3 and 7 of the \emph{Python Reference Manual} for these.
618
Fred Drake9474d861999-02-12 22:05:33 +0000619\subsubsection{Functions \label{typesfunctions}}
Fred Drake64e3b431998-07-24 13:56:11 +0000620
621Function objects are created by function definitions. The only
622operation on a function object is to call it:
623\code{\var{func}(\var{argument-list})}.
624
625There are really two flavors of function objects: built-in functions
626and user-defined functions. Both support the same operation (to call
627the function), but the implementation is different, hence the
628different object types.
629
630The implementation adds two special read-only attributes:
631\code{\var{f}.func_code} is a function's \dfn{code
632object}\obindex{code} (see below) and \code{\var{f}.func_globals} is
633the dictionary used as the function's global name space (this is the
634same as \code{\var{m}.__dict__} where \var{m} is the module in which
635the function \var{f} was defined).
636
637
Fred Drake9474d861999-02-12 22:05:33 +0000638\subsubsection{Methods \label{typesmethods}}
Fred Drake64e3b431998-07-24 13:56:11 +0000639\obindex{method}
640
641Methods are functions that are called using the attribute notation.
Fred Drake84538cd1998-11-30 21:51:25 +0000642There are two flavors: built-in methods (such as \method{append()} on
Fred Drake64e3b431998-07-24 13:56:11 +0000643lists) and class instance methods. Built-in methods are described
644with the types that support them.
645
646The implementation adds two special read-only attributes to class
Fred Draked0421dd1998-08-24 17:57:20 +0000647instance methods: \code{\var{m}.im_self} is the object on which the
648method operates, and \code{\var{m}.im_func} is the function
649implementing the method. Calling \code{\var{m}(\var{arg-1},
Fred Drake84538cd1998-11-30 21:51:25 +0000650\var{arg-2}, \textrm{\ldots}, \var{arg-n})} is completely equivalent to
Fred Draked0421dd1998-08-24 17:57:20 +0000651calling \code{\var{m}.im_func(\var{m}.im_self, \var{arg-1},
Fred Drake84538cd1998-11-30 21:51:25 +0000652\var{arg-2}, \textrm{\ldots}, \var{arg-n})}.
Fred Drake64e3b431998-07-24 13:56:11 +0000653
654See the \emph{Python Reference Manual} for more information.
655
Fred Drake7a2f0661998-09-10 18:25:58 +0000656
657\subsubsection{Code Objects \label{bltin-code-objects}}
Fred Drake64e3b431998-07-24 13:56:11 +0000658\obindex{code}
659
660Code objects are used by the implementation to represent
661``pseudo-compiled'' executable Python code such as a function body.
662They differ from function objects because they don't contain a
663reference to their global execution environment. Code objects are
Fred Drake84538cd1998-11-30 21:51:25 +0000664returned by the built-in \function{compile()} function and can be
665extracted from function objects through their \member{func_code}
Fred Drake64e3b431998-07-24 13:56:11 +0000666attribute.
667\bifuncindex{compile}
Fred Drakee8391991998-11-25 17:09:19 +0000668\withsubitem{(function object attribute)}{\ttindex{func_code}}
Fred Drake64e3b431998-07-24 13:56:11 +0000669
670A code object can be executed or evaluated by passing it (instead of a
Fred Drake84538cd1998-11-30 21:51:25 +0000671source string) to the \keyword{exec} statement or the built-in
672\function{eval()} function.
Fred Drake64e3b431998-07-24 13:56:11 +0000673\stindex{exec}
674\bifuncindex{eval}
675
676See the \emph{Python Reference Manual} for more information.
677
Fred Drake7a2f0661998-09-10 18:25:58 +0000678
679\subsubsection{Type Objects \label{bltin-type-objects}}
Fred Drake64e3b431998-07-24 13:56:11 +0000680
681Type objects represent the various object types. An object's type is
Fred Drake84538cd1998-11-30 21:51:25 +0000682accessed by the built-in function \function{type()}. There are no special
683operations on types. The standard module \module{types} defines names
Fred Drake64e3b431998-07-24 13:56:11 +0000684for all standard built-in types.
685\bifuncindex{type}
686\refstmodindex{types}
687
688Types are written like this: \code{<type 'int'>}.
689
Fred Drake7a2f0661998-09-10 18:25:58 +0000690
691\subsubsection{The Null Object \label{bltin-null-object}}
Fred Drake64e3b431998-07-24 13:56:11 +0000692
693This object is returned by functions that don't explicitly return a
694value. It supports no special operations. There is exactly one null
695object, named \code{None} (a built-in name).
696
697It is written as \code{None}.
698
Fred Drake7a2f0661998-09-10 18:25:58 +0000699
700\subsubsection{The Ellipsis Object \label{bltin-ellipsis-object}}
Guido van Rossumb193c951998-07-24 15:02:02 +0000701
702This object is used by extended slice notation (see the \emph{Python
703Reference Manual}). It supports no special operations. There is
704exactly one ellipsis object, named \code{Ellipsis} (a built-in name).
705
706It is written as \code{Ellipsis}.
707
Fred Drake7a2f0661998-09-10 18:25:58 +0000708\subsubsection{File Objects \label{bltin-file-objects}}
Fred Drake64e3b431998-07-24 13:56:11 +0000709
710File objects are implemented using \C{}'s \code{stdio} package and can be
Fred Drake130072d1998-10-28 20:08:35 +0000711created with the built-in function \function{open()} described Section
712\ref{built-in-funcs}, ``Built-in Functions.'' They are also returned
713by some other built-in functions and methods, e.g.,
714\function{posix.popen()} and \function{posix.fdopen()} and the
715\method{makefile()} method of socket objects.
Fred Drake64e3b431998-07-24 13:56:11 +0000716\bifuncindex{open}
717\refbimodindex{posix}
718\refbimodindex{socket}
719
720When a file operation fails for an I/O-related reason, the exception
Fred Drake84538cd1998-11-30 21:51:25 +0000721\exception{IOError} is raised. This includes situations where the
722operation is not defined for some reason, like \method{seek()} on a tty
Fred Drake64e3b431998-07-24 13:56:11 +0000723device or writing a file opened for reading.
724
725Files have the following methods:
726
727
728\begin{methoddesc}[file]{close}{}
729 Close the file. A closed file cannot be read or written anymore.
730\end{methoddesc}
731
732\begin{methoddesc}[file]{flush}{}
Fred Drake84538cd1998-11-30 21:51:25 +0000733 Flush the internal buffer, like \code{stdio}'s \cfunction{fflush()}.
Fred Drake64e3b431998-07-24 13:56:11 +0000734\end{methoddesc}
735
736\begin{methoddesc}[file]{isatty}{}
737 Return \code{1} if the file is connected to a tty(-like) device, else
738 \code{0}.
739\end{methoddesc}
740
741\begin{methoddesc}[file]{fileno}{}
742Return the integer ``file descriptor'' that is used by the underlying
743implementation to request I/O operations from the operating system.
744This can be useful for other, lower level interfaces that use file
Fred Drake84538cd1998-11-30 21:51:25 +0000745descriptors, e.g. module \module{fcntl} or \function{os.read()} and friends.
Fred Drake64e3b431998-07-24 13:56:11 +0000746\refbimodindex{fcntl}
747\end{methoddesc}
748
749\begin{methoddesc}[file]{read}{\optional{size}}
750 Read at most \var{size} bytes from the file (less if the read hits
751 \EOF{} or no more data is immediately available on a pipe, tty or
752 similar device). If the \var{size} argument is negative or omitted,
753 read all data until \EOF{} is reached. The bytes are returned as a string
754 object. An empty string is returned when \EOF{} is encountered
755 immediately. (For certain files, like ttys, it makes sense to
756 continue reading after an \EOF{} is hit.)
757\end{methoddesc}
758
759\begin{methoddesc}[file]{readline}{\optional{size}}
760 Read one entire line from the file. A trailing newline character is
761 kept in the string%
762\footnote{The advantage of leaving the newline on is that an empty string
763 can be returned to mean \EOF{} without being ambiguous. Another
764 advantage is that (in cases where it might matter, e.g. if you
765 want to make an exact copy of a file while scanning its lines)
766 you can tell whether the last line of a file ended in a newline
767 or not (yes this happens!).}
768 (but may be absent when a file ends with an
769 incomplete line). If the \var{size} argument is present and
770 non-negative, it is a maximum byte count (including the trailing
771 newline) and an incomplete line may be returned.
772 An empty string is returned when \EOF{} is hit
773 immediately. Note: unlike \code{stdio}'s \cfunction{fgets()}, the returned
774 string contains null characters (\code{'\e 0'}) if they occurred in the
775 input.
776\end{methoddesc}
777
778\begin{methoddesc}[file]{readlines}{\optional{sizehint}}
779 Read until \EOF{} using \method{readline()} and return a list containing
780 the lines thus read. If the optional \var{sizehint} argument is
781 present, instead of reading up to \EOF{}, whole lines totalling
782 approximately \var{sizehint} bytes (possibly after rounding up to an
783 internal buffer size) are read.
784\end{methoddesc}
785
786\begin{methoddesc}[file]{seek}{offset\optional{, whence}}
787 Set the file's current position, like \code{stdio}'s \cfunction{fseek()}.
788 The \var{whence} argument is optional and defaults to \code{0}
789 (absolute file positioning); other values are \code{1} (seek
790 relative to the current position) and \code{2} (seek relative to the
791 file's end). There is no return value.
792\end{methoddesc}
793
794\begin{methoddesc}[file]{tell}{}
795 Return the file's current position, like \code{stdio}'s
796 \cfunction{ftell()}.
797\end{methoddesc}
798
799\begin{methoddesc}[file]{truncate}{\optional{size}}
800Truncate the file's size. If the optional size argument present, the
801file is truncated to (at most) that size. The size defaults to the
802current position. Availability of this function depends on the
803operating system version (e.g., not all \UNIX{} versions support this
804operation).
805\end{methoddesc}
806
807\begin{methoddesc}[file]{write}{str}
808Write a string to the file. There is no return value. Note: due to
809buffering, the string may not actually show up in the file until
810the \method{flush()} or \method{close()} method is called.
811\end{methoddesc}
812
813\begin{methoddesc}[file]{writelines}{list}
814Write a list of strings to the file. There is no return value.
815(The name is intended to match \method{readlines()};
816\method{writelines()} does not add line separators.)
817\end{methoddesc}
818
819
820File objects also offer the following attributes:
821
822\begin{memberdesc}[file]{closed}
823Boolean indicating the current state of the file object. This is a
824read-only attribute; the \method{close()} method changes the value.
825\end{memberdesc}
826
827\begin{memberdesc}[file]{mode}
828The I/O mode for the file. If the file was created using the
829\function{open()} built-in function, this will be the value of the
830\var{mode} parameter. This is a read-only attribute.
831\end{memberdesc}
832
833\begin{memberdesc}[file]{name}
834If the file object was created using \function{open()}, the name of
835the file. Otherwise, some string that indicates the source of the
836file object, of the form \samp{<\mbox{\ldots}>}. This is a read-only
837attribute.
838\end{memberdesc}
839
840\begin{memberdesc}[file]{softspace}
841Boolean that indicates whether a space character needs to be printed
842before another value when using the \keyword{print} statement.
843Classes that are trying to simulate a file object should also have a
844writable \member{softspace} attribute, which should be initialized to
845zero. This will be automatic for classes implemented in Python; types
846implemented in \C{} will have to provide a writable \member{softspace}
847attribute.
848\end{memberdesc}
849
Fred Drake9474d861999-02-12 22:05:33 +0000850\subsubsection{Internal Objects \label{typesinternal}}
Fred Drake64e3b431998-07-24 13:56:11 +0000851
852See the \emph{Python Reference Manual} for this information. It
853describes code objects, stack frame objects, traceback objects, and
854slice objects.
855
856
Fred Drake7a2f0661998-09-10 18:25:58 +0000857\subsection{Special Attributes \label{specialattrs}}
Fred Drake64e3b431998-07-24 13:56:11 +0000858
859The implementation adds a few special read-only attributes to several
860object types, where they are relevant:
861
Fred Drake7a2f0661998-09-10 18:25:58 +0000862\begin{memberdescni}{__dict__}
863A dictionary of some sort used to store an
864object's (writable) attributes.
865\end{memberdescni}
Fred Drake64e3b431998-07-24 13:56:11 +0000866
Fred Drake7a2f0661998-09-10 18:25:58 +0000867\begin{memberdescni}{__methods__}
868List of the methods of many built-in object types,
Fred Drake64e3b431998-07-24 13:56:11 +0000869e.g., \code{[].__methods__} yields
Fred Drake7a2f0661998-09-10 18:25:58 +0000870\code{['append', 'count', 'index', 'insert', 'pop', 'remove',
871'reverse', 'sort']}.
872\end{memberdescni}
Fred Drake64e3b431998-07-24 13:56:11 +0000873
Fred Drake7a2f0661998-09-10 18:25:58 +0000874\begin{memberdescni}{__members__}
875Similar to \member{__methods__}, but lists data attributes.
876\end{memberdescni}
Fred Drake64e3b431998-07-24 13:56:11 +0000877
Fred Drake7a2f0661998-09-10 18:25:58 +0000878\begin{memberdescni}{__class__}
879The class to which a class instance belongs.
880\end{memberdescni}
Fred Drake64e3b431998-07-24 13:56:11 +0000881
Fred Drake7a2f0661998-09-10 18:25:58 +0000882\begin{memberdescni}{__bases__}
883The tuple of base classes of a class object.
884\end{memberdescni}