blob: cef8d5cb500acd57760491a9fff021158e18d349 [file] [log] [blame]
Fred Drake61c77281998-07-28 19:34:22 +00001\chapter{Data model\label{datamodel}}
Fred Drakef6669171998-05-06 19:52:49 +00002
Fred Drake2829f1c2001-06-23 05:27:20 +00003
Fred Drake61c77281998-07-28 19:34:22 +00004\section{Objects, values and types\label{objects}}
Fred Drakef6669171998-05-06 19:52:49 +00005
6\dfn{Objects} are Python's abstraction for data. All data in a Python
7program is represented by objects or by relations between objects.
8(In a sense, and in conformance to Von Neumann's model of a
Guido van Rossum83b2f8a1998-07-23 17:12:46 +00009``stored program computer,'' code is also represented by objects.)
Fred Drakef6669171998-05-06 19:52:49 +000010\index{object}
11\index{data}
12
13Every object has an identity, a type and a value. An object's
14\emph{identity} never changes once it has been created; you may think
Fred Drake293dd4b2002-06-04 16:25:57 +000015of it as the object's address in memory. The `\keyword{is}' operator
Fred Drake82385871998-10-01 20:40:43 +000016compares the identity of two objects; the
17\function{id()}\bifuncindex{id} function returns an integer
18representing its identity (currently implemented as its address).
Guido van Rossum83b2f8a1998-07-23 17:12:46 +000019An object's \dfn{type} is
Raymond Hettingere701dcb2003-01-19 13:08:18 +000020also unchangeable.\footnote{Since Python 2.2, a gradual merging of
21types and classes has been started that makes this and a few other
22assertions made in this manual not 100\% accurate and complete:
23for example, it \emph{is} now possible in some cases to change an
24object's type, under certain controlled conditions. Until this manual
25undergoes extensive revision, it must now be taken as authoritative
26only regarding ``classic classes'', that are still the default, for
27compatibility purposes, in Python 2.2 and 2.3.}
28An object's type determines the operations that the object
Guido van Rossum83b2f8a1998-07-23 17:12:46 +000029supports (e.g., ``does it have a length?'') and also defines the
Fred Drake82385871998-10-01 20:40:43 +000030possible values for objects of that type. The
31\function{type()}\bifuncindex{type} function returns an object's type
32(which is an object itself). The \emph{value} of some
Fred Drakef6669171998-05-06 19:52:49 +000033objects can change. Objects whose value can change are said to be
34\emph{mutable}; objects whose value is unchangeable once they are
Guido van Rossum83b2f8a1998-07-23 17:12:46 +000035created are called \emph{immutable}.
Guido van Rossum264bd591999-02-23 16:40:55 +000036(The value of an immutable container object that contains a reference
37to a mutable object can change when the latter's value is changed;
38however the container is still considered immutable, because the
39collection of objects it contains cannot be changed. So, immutability
40is not strictly the same as having an unchangeable value, it is more
41subtle.)
Guido van Rossum83b2f8a1998-07-23 17:12:46 +000042An object's mutability is determined by its type; for instance,
43numbers, strings and tuples are immutable, while dictionaries and
44lists are mutable.
Fred Drakef6669171998-05-06 19:52:49 +000045\index{identity of an object}
46\index{value of an object}
47\index{type of an object}
48\index{mutable object}
49\index{immutable object}
50
51Objects are never explicitly destroyed; however, when they become
52unreachable they may be garbage-collected. An implementation is
Barry Warsaw92a6ed91998-08-07 16:33:51 +000053allowed to postpone garbage collection or omit it altogether --- it is
54a matter of implementation quality how garbage collection is
Fred Drakef6669171998-05-06 19:52:49 +000055implemented, as long as no objects are collected that are still
56reachable. (Implementation note: the current implementation uses a
Fred Drakec8e82812001-01-22 17:46:18 +000057reference-counting scheme with (optional) delayed detection of
Raymond Hettingere701dcb2003-01-19 13:08:18 +000058cyclically linked garbage, which collects most objects as soon as they
Fred Drakec8e82812001-01-22 17:46:18 +000059become unreachable, but is not guaranteed to collect garbage
60containing circular references. See the
61\citetitle[../lib/module-gc.html]{Python Library Reference} for
62information on controlling the collection of cyclic garbage.)
Fred Drakef6669171998-05-06 19:52:49 +000063\index{garbage collection}
64\index{reference counting}
65\index{unreachable object}
66
67Note that the use of the implementation's tracing or debugging
68facilities may keep objects alive that would normally be collectable.
Guido van Rossum83b2f8a1998-07-23 17:12:46 +000069Also note that catching an exception with a
Fred Drake4856d011999-01-12 04:15:20 +000070`\keyword{try}...\keyword{except}' statement may keep objects alive.
Fred Drakef6669171998-05-06 19:52:49 +000071
72Some objects contain references to ``external'' resources such as open
73files or windows. It is understood that these resources are freed
74when the object is garbage-collected, but since garbage collection is
75not guaranteed to happen, such objects also provide an explicit way to
76release the external resource, usually a \method{close()} method.
Guido van Rossum83b2f8a1998-07-23 17:12:46 +000077Programs are strongly recommended to explicitly close such
Fred Drake4856d011999-01-12 04:15:20 +000078objects. The `\keyword{try}...\keyword{finally}' statement provides
79a convenient way to do this.
Fred Drakef6669171998-05-06 19:52:49 +000080
81Some objects contain references to other objects; these are called
82\emph{containers}. Examples of containers are tuples, lists and
83dictionaries. The references are part of a container's value. In
84most cases, when we talk about the value of a container, we imply the
85values, not the identities of the contained objects; however, when we
Guido van Rossum83b2f8a1998-07-23 17:12:46 +000086talk about the mutability of a container, only the identities of
87the immediately contained objects are implied. So, if an immutable
88container (like a tuple)
89contains a reference to a mutable object, its value changes
90if that mutable object is changed.
Fred Drakef6669171998-05-06 19:52:49 +000091\index{container}
92
Guido van Rossum83b2f8a1998-07-23 17:12:46 +000093Types affect almost all aspects of object behavior. Even the importance
Fred Drakef6669171998-05-06 19:52:49 +000094of object identity is affected in some sense: for immutable types,
95operations that compute new values may actually return a reference to
96any existing object with the same type and value, while for mutable
Guido van Rossum83b2f8a1998-07-23 17:12:46 +000097objects this is not allowed. E.g., after
Fred Drake82385871998-10-01 20:40:43 +000098\samp{a = 1; b = 1},
Fred Drakef6669171998-05-06 19:52:49 +000099\code{a} and \code{b} may or may not refer to the same object with the
Guido van Rossum83b2f8a1998-07-23 17:12:46 +0000100value one, depending on the implementation, but after
Fred Drake82385871998-10-01 20:40:43 +0000101\samp{c = []; d = []}, \code{c} and \code{d}
Fred Drakef6669171998-05-06 19:52:49 +0000102are guaranteed to refer to two different, unique, newly created empty
103lists.
Fred Drake82385871998-10-01 20:40:43 +0000104(Note that \samp{c = d = []} assigns the same object to both
Guido van Rossum83b2f8a1998-07-23 17:12:46 +0000105\code{c} and \code{d}.)
Fred Drakef6669171998-05-06 19:52:49 +0000106
Fred Drake2829f1c2001-06-23 05:27:20 +0000107
Fred Drake61c77281998-07-28 19:34:22 +0000108\section{The standard type hierarchy\label{types}}
Fred Drakef6669171998-05-06 19:52:49 +0000109
110Below is a list of the types that are built into Python. Extension
Raymond Hettingere701dcb2003-01-19 13:08:18 +0000111modules (written in C, Java, or other languages, depending on
112the implementation) can define additional types. Future versions of
Guido van Rossum83b2f8a1998-07-23 17:12:46 +0000113Python may add types to the type hierarchy (e.g., rational
Fred Drakef6669171998-05-06 19:52:49 +0000114numbers, efficiently stored arrays of integers, etc.).
115\index{type}
116\indexii{data}{type}
117\indexii{type}{hierarchy}
118\indexii{extension}{module}
119\indexii{C}{language}
120
121Some of the type descriptions below contain a paragraph listing
Guido van Rossum83b2f8a1998-07-23 17:12:46 +0000122`special attributes.' These are attributes that provide access to the
Fred Drakef6669171998-05-06 19:52:49 +0000123implementation and are not intended for general use. Their definition
Fred Drake35705512001-12-03 17:32:27 +0000124may change in the future.
Fred Drakef6669171998-05-06 19:52:49 +0000125\index{attribute}
126\indexii{special}{attribute}
127\indexiii{generic}{special}{attribute}
Fred Drakef6669171998-05-06 19:52:49 +0000128
129\begin{description}
130
131\item[None]
132This type has a single value. There is a single object with this value.
133This object is accessed through the built-in name \code{None}.
Guido van Rossum83b2f8a1998-07-23 17:12:46 +0000134It is used to signify the absence of a value in many situations, e.g.,
135it is returned from functions that don't explicitly return anything.
136Its truth value is false.
Fred Drakef6669171998-05-06 19:52:49 +0000137\ttindex{None}
Fred Drake78eebfd1998-11-25 19:09:24 +0000138\obindex{None@{\texttt{None}}}
Fred Drakef6669171998-05-06 19:52:49 +0000139
Neil Schemenauer48c2eb92001-01-04 01:25:50 +0000140\item[NotImplemented]
141This type has a single value. There is a single object with this value.
142This object is accessed through the built-in name \code{NotImplemented}.
Guido van Rossumab782dd2001-01-18 15:17:06 +0000143Numeric methods and rich comparison methods may return this value if
144they do not implement the operation for the operands provided. (The
145interpreter will then try the reflected operation, or some other
146fallback, depending on the operator.) Its truth value is true.
Neil Schemenauer48c2eb92001-01-04 01:25:50 +0000147\ttindex{NotImplemented}
148\obindex{NotImplemented@{\texttt{NotImplemented}}}
149
Guido van Rossum83b2f8a1998-07-23 17:12:46 +0000150\item[Ellipsis]
151This type has a single value. There is a single object with this value.
152This object is accessed through the built-in name \code{Ellipsis}.
Fred Drake82385871998-10-01 20:40:43 +0000153It is used to indicate the presence of the \samp{...} syntax in a
Guido van Rossum83b2f8a1998-07-23 17:12:46 +0000154slice. Its truth value is true.
Fred Drakec0a02c02002-04-16 02:03:05 +0000155\obindex{Ellipsis}
Guido van Rossum83b2f8a1998-07-23 17:12:46 +0000156
Fred Drakef6669171998-05-06 19:52:49 +0000157\item[Numbers]
158These are created by numeric literals and returned as results by
159arithmetic operators and arithmetic built-in functions. Numeric
160objects are immutable; once created their value never changes. Python
161numbers are of course strongly related to mathematical numbers, but
162subject to the limitations of numerical representation in computers.
Fred Drakef6669171998-05-06 19:52:49 +0000163\obindex{numeric}
164
Fred Drakeb3384d32001-05-14 16:04:22 +0000165Python distinguishes between integers, floating point numbers, and
166complex numbers:
Fred Drakef6669171998-05-06 19:52:49 +0000167
168\begin{description}
169\item[Integers]
170These represent elements from the mathematical set of whole numbers.
171\obindex{integer}
172
Guido van Rossum77f6a652002-04-03 22:41:51 +0000173There are three types of integers:
Fred Drakef6669171998-05-06 19:52:49 +0000174
175\begin{description}
176
177\item[Plain integers]
178These represent numbers in the range -2147483648 through 2147483647.
179(The range may be larger on machines with a larger natural word
180size, but not smaller.)
Fred Drakee15956b2000-04-03 04:51:13 +0000181When the result of an operation would fall outside this range, the
Raymond Hettingere701dcb2003-01-19 13:08:18 +0000182result is normally returned as a long integer (in some cases, the
183exception \exception{OverflowError} is raised instead).
Fred Drakef6669171998-05-06 19:52:49 +0000184For the purpose of shift and mask operations, integers are assumed to
185have a binary, 2's complement notation using 32 or more bits, and
186hiding no bits from the user (i.e., all 4294967296 different bit
187patterns correspond to different values).
188\obindex{plain integer}
189\withsubitem{(built-in exception)}{\ttindex{OverflowError}}
190
191\item[Long integers]
192These represent numbers in an unlimited range, subject to available
193(virtual) memory only. For the purpose of shift and mask operations,
194a binary representation is assumed, and negative numbers are
195represented in a variant of 2's complement which gives the illusion of
196an infinite string of sign bits extending to the left.
197\obindex{long integer}
198
Guido van Rossum77f6a652002-04-03 22:41:51 +0000199\item[Booleans]
200These represent the truth values False and True. The two objects
201representing the values False and True are the only Boolean objects.
202The Boolean type is a subtype of plain integers, and Boolean values
203behave like the values 0 and 1, respectively, in almost all contexts,
204the exception being that when converted to a string, the strings
205\code{"False"} or \code{"True"} are returned, respectively.
206\obindex{Boolean}
207\ttindex{False}
208\ttindex{True}
209
Fred Drakef6669171998-05-06 19:52:49 +0000210\end{description} % Integers
211
212The rules for integer representation are intended to give the most
213meaningful interpretation of shift and mask operations involving
214negative integers and the least surprises when switching between the
Raymond Hettingere701dcb2003-01-19 13:08:18 +0000215plain and long integer domains. Any operation except left shift,
Fred Drakef6669171998-05-06 19:52:49 +0000216if it yields a result in the plain integer domain without causing
Raymond Hettingere701dcb2003-01-19 13:08:18 +0000217overflow, will yield the same result in the long integer domain or
Fred Drakef6669171998-05-06 19:52:49 +0000218when using mixed operands.
219\indexii{integer}{representation}
220
221\item[Floating point numbers]
222These represent machine-level double precision floating point numbers.
Raymond Hettingere701dcb2003-01-19 13:08:18 +0000223You are at the mercy of the underlying machine architecture (and
224C or Java implementation) for the accepted range and handling of overflow.
Guido van Rossum83b2f8a1998-07-23 17:12:46 +0000225Python does not support single-precision floating point numbers; the
Fred Drake6e5e1d92001-07-14 02:12:27 +0000226savings in processor and memory usage that are usually the reason for using
Guido van Rossum83b2f8a1998-07-23 17:12:46 +0000227these is dwarfed by the overhead of using objects in Python, so there
228is no reason to complicate the language with two kinds of floating
229point numbers.
Fred Drakef6669171998-05-06 19:52:49 +0000230\obindex{floating point}
231\indexii{floating point}{number}
232\indexii{C}{language}
Raymond Hettingere701dcb2003-01-19 13:08:18 +0000233\indexii{Java}{language}
Fred Drakef6669171998-05-06 19:52:49 +0000234
Guido van Rossum83b2f8a1998-07-23 17:12:46 +0000235\item[Complex numbers]
236These represent complex numbers as a pair of machine-level double
237precision floating point numbers. The same caveats apply as for
Raymond Hettingere701dcb2003-01-19 13:08:18 +0000238floating point numbers. The real and imaginary parts of a complex
239number \code{z} can be retrieved through the read-only attributes
240\code{z.real} and \code{z.imag}.
Guido van Rossum83b2f8a1998-07-23 17:12:46 +0000241\obindex{complex}
242\indexii{complex}{number}
243
Fred Drakef6669171998-05-06 19:52:49 +0000244\end{description} % Numbers
245
Guido van Rossum77f6a652002-04-03 22:41:51 +0000246
Fred Drakef6669171998-05-06 19:52:49 +0000247\item[Sequences]
Fred Drake230d17d2001-02-22 21:28:04 +0000248These represent finite ordered sets indexed by non-negative numbers.
Fred Drakef6669171998-05-06 19:52:49 +0000249The built-in function \function{len()}\bifuncindex{len} returns the
Guido van Rossum83b2f8a1998-07-23 17:12:46 +0000250number of items of a sequence.
Thomas Woutersf9b526d2000-07-16 19:05:38 +0000251When the length of a sequence is \var{n}, the
Guido van Rossum83b2f8a1998-07-23 17:12:46 +0000252index set contains the numbers 0, 1, \ldots, \var{n}-1. Item
Fred Drakef6669171998-05-06 19:52:49 +0000253\var{i} of sequence \var{a} is selected by \code{\var{a}[\var{i}]}.
Fred Drakee15956b2000-04-03 04:51:13 +0000254\obindex{sequence}
Fred Drakef6669171998-05-06 19:52:49 +0000255\index{index operation}
256\index{item selection}
257\index{subscription}
258
259Sequences also support slicing: \code{\var{a}[\var{i}:\var{j}]}
Guido van Rossum83b2f8a1998-07-23 17:12:46 +0000260selects all items with index \var{k} such that \var{i} \code{<=}
Fred Drakef6669171998-05-06 19:52:49 +0000261\var{k} \code{<} \var{j}. When used as an expression, a slice is a
Guido van Rossum83b2f8a1998-07-23 17:12:46 +0000262sequence of the same type. This implies that the index set is
263renumbered so that it starts at 0.
Fred Drakef6669171998-05-06 19:52:49 +0000264\index{slicing}
265
Michael W. Hudson5efaf7e2002-06-11 10:55:12 +0000266Some sequences also support ``extended slicing'' with a third ``step''
267parameter: \code{\var{a}[\var{i}:\var{j}:\var{k}]} selects all items
268of \var{a} with index \var{x} where \code{\var{x} = \var{i} +
269\var{n}*\var{k}}, \var{n} \code{>=} \code{0} and \var{i} \code{<=}
270\var{x} \code{<} \var{j}.
271\index{extended slicing}
272
Fred Drakef6669171998-05-06 19:52:49 +0000273Sequences are distinguished according to their mutability:
274
275\begin{description}
Fred Drake4856d011999-01-12 04:15:20 +0000276
Fred Drakef6669171998-05-06 19:52:49 +0000277\item[Immutable sequences]
278An object of an immutable sequence type cannot change once it is
279created. (If the object contains references to other objects,
Guido van Rossum83b2f8a1998-07-23 17:12:46 +0000280these other objects may be mutable and may be changed; however,
Fred Drakef6669171998-05-06 19:52:49 +0000281the collection of objects directly referenced by an immutable object
282cannot change.)
283\obindex{immutable sequence}
284\obindex{immutable}
285
286The following types are immutable sequences:
287
288\begin{description}
289
290\item[Strings]
Guido van Rossum83b2f8a1998-07-23 17:12:46 +0000291The items of a string are characters. There is no separate
292character type; a character is represented by a string of one item.
Fred Drakef6669171998-05-06 19:52:49 +0000293Characters represent (at least) 8-bit bytes. The built-in
294functions \function{chr()}\bifuncindex{chr} and
295\function{ord()}\bifuncindex{ord} convert between characters and
296nonnegative integers representing the byte values. Bytes with the
Guido van Rossum83b2f8a1998-07-23 17:12:46 +0000297values 0-127 usually represent the corresponding \ASCII{} values, but
298the interpretation of values is up to the program. The string
299data type is also used to represent arrays of bytes, e.g., to hold data
Fred Drakef6669171998-05-06 19:52:49 +0000300read from a file.
301\obindex{string}
302\index{character}
303\index{byte}
Fred Drakec37b65e2001-11-28 07:26:15 +0000304\index{ASCII@\ASCII}
Fred Drakef6669171998-05-06 19:52:49 +0000305
Fred Drakec37b65e2001-11-28 07:26:15 +0000306(On systems whose native character set is not \ASCII, strings may use
Fred Drakef6669171998-05-06 19:52:49 +0000307EBCDIC in their internal representation, provided the functions
308\function{chr()} and \function{ord()} implement a mapping between \ASCII{} and
309EBCDIC, and string comparison preserves the \ASCII{} order.
310Or perhaps someone can propose a better rule?)
Fred Drakec37b65e2001-11-28 07:26:15 +0000311\index{ASCII@\ASCII}
Fred Drakef6669171998-05-06 19:52:49 +0000312\index{EBCDIC}
313\index{character set}
314\indexii{string}{comparison}
315\bifuncindex{chr}
316\bifuncindex{ord}
317
Fred Drakef0aff8e2000-04-06 13:57:21 +0000318\item[Unicode]
Fred Drake5ec22f22002-09-24 21:09:13 +0000319The items of a Unicode object are Unicode code units. A Unicode code
320unit is represented by a Unicode object of one item and can hold
321either a 16-bit or 32-bit value representing a Unicode ordinal (the
322maximum value for the ordinal is given in \code{sys.maxunicode}, and
323depends on how Python is configured at compile time). Surrogate pairs
324may be present in the Unicode object, and will be reported as two
325separate items. The built-in functions
Fred Drakef0aff8e2000-04-06 13:57:21 +0000326\function{unichr()}\bifuncindex{unichr} and
Fred Drake5ec22f22002-09-24 21:09:13 +0000327\function{ord()}\bifuncindex{ord} convert between code units and
Fred Drakef0aff8e2000-04-06 13:57:21 +0000328nonnegative integers representing the Unicode ordinals as defined in
329the Unicode Standard 3.0. Conversion from and to other encodings are
330possible through the Unicode method \method{encode} and the built-in
Fred Drake5ec22f22002-09-24 21:09:13 +0000331function \function{unicode()}.\bifuncindex{unicode}
Fred Drakef0aff8e2000-04-06 13:57:21 +0000332\obindex{unicode}
333\index{character}
334\index{integer}
Fred Drake8b3ce9e2000-04-06 14:00:14 +0000335\index{Unicode}
Fred Drakef0aff8e2000-04-06 13:57:21 +0000336
Fred Drakef6669171998-05-06 19:52:49 +0000337\item[Tuples]
Guido van Rossum83b2f8a1998-07-23 17:12:46 +0000338The items of a tuple are arbitrary Python objects.
339Tuples of two or more items are formed by comma-separated lists
340of expressions. A tuple of one item (a `singleton') can be formed
Fred Drakef6669171998-05-06 19:52:49 +0000341by affixing a comma to an expression (an expression by itself does
342not create a tuple, since parentheses must be usable for grouping of
Guido van Rossum83b2f8a1998-07-23 17:12:46 +0000343expressions). An empty tuple can be formed by an empty pair of
Fred Drakef6669171998-05-06 19:52:49 +0000344parentheses.
345\obindex{tuple}
346\indexii{singleton}{tuple}
347\indexii{empty}{tuple}
348
349\end{description} % Immutable sequences
350
351\item[Mutable sequences]
352Mutable sequences can be changed after they are created. The
353subscription and slicing notations can be used as the target of
354assignment and \keyword{del} (delete) statements.
Thomas Woutersf9b526d2000-07-16 19:05:38 +0000355\obindex{mutable sequence}
Fred Drakef6669171998-05-06 19:52:49 +0000356\obindex{mutable}
357\indexii{assignment}{statement}
358\index{delete}
359\stindex{del}
360\index{subscription}
361\index{slicing}
362
Raymond Hettingere701dcb2003-01-19 13:08:18 +0000363There is currently a single intrinsic mutable sequence type:
Fred Drakef6669171998-05-06 19:52:49 +0000364
365\begin{description}
366
367\item[Lists]
Guido van Rossum83b2f8a1998-07-23 17:12:46 +0000368The items of a list are arbitrary Python objects. Lists are formed
Fred Drakef6669171998-05-06 19:52:49 +0000369by placing a comma-separated list of expressions in square brackets.
370(Note that there are no special cases needed to form lists of length 0
371or 1.)
372\obindex{list}
373
374\end{description} % Mutable sequences
375
Guido van Rossum83b2f8a1998-07-23 17:12:46 +0000376The extension module \module{array}\refstmodindex{array} provides an
377additional example of a mutable sequence type.
378
379
Fred Drakef6669171998-05-06 19:52:49 +0000380\end{description} % Sequences
381
Guido van Rossum83b2f8a1998-07-23 17:12:46 +0000382\item[Mappings]
Fred Drakef6669171998-05-06 19:52:49 +0000383These represent finite sets of objects indexed by arbitrary index sets.
Guido van Rossum83b2f8a1998-07-23 17:12:46 +0000384The subscript notation \code{a[k]} selects the item indexed
Fred Drakef6669171998-05-06 19:52:49 +0000385by \code{k} from the mapping \code{a}; this can be used in
386expressions and as the target of assignments or \keyword{del} statements.
Guido van Rossum83b2f8a1998-07-23 17:12:46 +0000387The built-in function \function{len()} returns the number of items
Fred Drakef6669171998-05-06 19:52:49 +0000388in a mapping.
389\bifuncindex{len}
390\index{subscription}
391\obindex{mapping}
392
Guido van Rossum83b2f8a1998-07-23 17:12:46 +0000393There is currently a single intrinsic mapping type:
Fred Drakef6669171998-05-06 19:52:49 +0000394
395\begin{description}
396
397\item[Dictionaries]
Fred Drake8cdee961999-02-23 18:50:38 +0000398These\obindex{dictionary} represent finite sets of objects indexed by
399nearly arbitrary values. The only types of values not acceptable as
400keys are values containing lists or dictionaries or other mutable
401types that are compared by value rather than by object identity, the
402reason being that the efficient implementation of dictionaries
403requires a key's hash value to remain constant.
Fred Drakef6669171998-05-06 19:52:49 +0000404Numeric types used for keys obey the normal rules for numeric
Guido van Rossum83b2f8a1998-07-23 17:12:46 +0000405comparison: if two numbers compare equal (e.g., \code{1} and
Fred Drakef6669171998-05-06 19:52:49 +0000406\code{1.0}) then they can be used interchangeably to index the same
407dictionary entry.
408
Raymond Hettingere701dcb2003-01-19 13:08:18 +0000409Dictionaries are mutable; they can be created by the
Fred Drake62364ff2003-03-20 18:17:16 +0000410\code{\{...\}} notation (see section~\ref{dict}, ``Dictionary
Fred Drake8cdee961999-02-23 18:50:38 +0000411Displays'').
Fred Drakef6669171998-05-06 19:52:49 +0000412
Guido van Rossum83b2f8a1998-07-23 17:12:46 +0000413The extension modules \module{dbm}\refstmodindex{dbm},
414\module{gdbm}\refstmodindex{gdbm}, \module{bsddb}\refstmodindex{bsddb}
415provide additional examples of mapping types.
416
Fred Drakef6669171998-05-06 19:52:49 +0000417\end{description} % Mapping types
418
419\item[Callable types]
Fred Drake8cdee961999-02-23 18:50:38 +0000420These\obindex{callable} are the types to which the function call
Fred Drake62364ff2003-03-20 18:17:16 +0000421operation (see section~\ref{calls}, ``Calls'') can be applied:
Fred Drakef6669171998-05-06 19:52:49 +0000422\indexii{function}{call}
423\index{invocation}
424\indexii{function}{argument}
Fred Drakef6669171998-05-06 19:52:49 +0000425
426\begin{description}
427
428\item[User-defined functions]
429A user-defined function object is created by a function definition
Fred Drake62364ff2003-03-20 18:17:16 +0000430(see section~\ref{function}, ``Function definitions''). It should be
Guido van Rossum83b2f8a1998-07-23 17:12:46 +0000431called with an argument
Fred Drakef6669171998-05-06 19:52:49 +0000432list containing the same number of items as the function's formal
433parameter list.
434\indexii{user-defined}{function}
435\obindex{function}
436\obindex{user-defined function}
437
Guido van Rossum264bd591999-02-23 16:40:55 +0000438Special attributes: \member{func_doc} or \member{__doc__} is the
Jeremy Hyltonf9b0cc72003-01-31 18:52:45 +0000439function's documentation string, or \code{None} if unavailable;
Fred Drake82385871998-10-01 20:40:43 +0000440\member{func_name} or \member{__name__} is the function's name;
Jeremy Hyltonf9b0cc72003-01-31 18:52:45 +0000441\member{__module__} is the name of the module the function was defined
442in, or \code{None} if unavailable;
Fred Drake82385871998-10-01 20:40:43 +0000443\member{func_defaults} is a tuple containing default argument values for
Guido van Rossum83b2f8a1998-07-23 17:12:46 +0000444those arguments that have defaults, or \code{None} if no arguments
Fred Drake82385871998-10-01 20:40:43 +0000445have a default value; \member{func_code} is the code object representing
446the compiled function body; \member{func_globals} is (a reference to)
Guido van Rossum83b2f8a1998-07-23 17:12:46 +0000447the dictionary that holds the function's global variables --- it
Guido van Rossumdfb658c1998-07-23 17:54:36 +0000448defines the global namespace of the module in which the function was
Barry Warsaw7a5e80e2001-02-27 03:36:30 +0000449defined; \member{func_dict} or \member{__dict__} contains the
Jeremy Hyltonaa90adc2001-03-23 17:23:50 +0000450namespace supporting arbitrary function attributes;
451\member{func_closure} is \code{None} or a tuple of cells that contain
Jeremy Hylton26c49b62002-04-01 17:58:39 +0000452bindings for the function's free variables.
Barry Warsaw7a5e80e2001-02-27 03:36:30 +0000453
Jeremy Hylton26c49b62002-04-01 17:58:39 +0000454Of these, \member{func_code}, \member{func_defaults},
Barry Warsaw7a5e80e2001-02-27 03:36:30 +0000455\member{func_doc}/\member{__doc__}, and
456\member{func_dict}/\member{__dict__} may be writable; the
Jeremy Hyltonaa90adc2001-03-23 17:23:50 +0000457others can never be changed. Additional information about a
458function's definition can be retrieved from its code object; see the
459description of internal types below.
460
Fred Drake4856d011999-01-12 04:15:20 +0000461\withsubitem{(function attribute)}{
462 \ttindex{func_doc}
463 \ttindex{__doc__}
464 \ttindex{__name__}
Jeremy Hyltonf9b0cc72003-01-31 18:52:45 +0000465 \ttindex{__module__}
Barry Warsaw7a5e80e2001-02-27 03:36:30 +0000466 \ttindex{__dict__}
Fred Drake4856d011999-01-12 04:15:20 +0000467 \ttindex{func_defaults}
Jeremy Hylton26c49b62002-04-01 17:58:39 +0000468 \ttindex{func_closure}
Fred Drake4856d011999-01-12 04:15:20 +0000469 \ttindex{func_code}
Barry Warsaw7a5e80e2001-02-27 03:36:30 +0000470 \ttindex{func_globals}
471 \ttindex{func_dict}}
Guido van Rossumdfb658c1998-07-23 17:54:36 +0000472\indexii{global}{namespace}
Fred Drakef6669171998-05-06 19:52:49 +0000473
474\item[User-defined methods]
Guido van Rossum83b2f8a1998-07-23 17:12:46 +0000475A user-defined method object combines a class, a class instance (or
Fred Drake8dd6ffd2001-08-02 21:34:53 +0000476\code{None}) and any callable object (normally a user-defined
477function).
Fred Drakef6669171998-05-06 19:52:49 +0000478\obindex{method}
479\obindex{user-defined method}
480\indexii{user-defined}{method}
Fred Drakef6669171998-05-06 19:52:49 +0000481
482Special read-only attributes: \member{im_self} is the class instance
Guido van Rossum83b2f8a1998-07-23 17:12:46 +0000483object, \member{im_func} is the function object;
Raymond Hettinger03ec6d52003-06-25 18:29:36 +0000484\member{im_class} is the class of \member{im_self} for bound methods
485or the class that asked for the method for unbound methods;
Fred Drake82385871998-10-01 20:40:43 +0000486\member{__doc__} is the method's documentation (same as
487\code{im_func.__doc__}); \member{__name__} is the method name (same as
Jeremy Hyltonf9b0cc72003-01-31 18:52:45 +0000488\code{im_func.__name__}); \member{__module__} is the name of the
489module the method was defined in, or \code{None} if unavailable.
Fred Drakef9d58032001-12-07 23:13:53 +0000490\versionchanged[\member{im_self} used to refer to the class that
491 defined the method]{2.2}
Fred Drake4856d011999-01-12 04:15:20 +0000492\withsubitem{(method attribute)}{
Jeremy Hyltonf9b0cc72003-01-31 18:52:45 +0000493 \ttindex{__doc__}
494 \ttindex{__name__}
495 \ttindex{__module__}
Fred Drake4856d011999-01-12 04:15:20 +0000496 \ttindex{im_func}
Fred Drake1e42d8a1998-11-25 17:58:50 +0000497 \ttindex{im_self}}
Guido van Rossum83b2f8a1998-07-23 17:12:46 +0000498
Barry Warsaw7a5e80e2001-02-27 03:36:30 +0000499Methods also support accessing (but not setting) the arbitrary
500function attributes on the underlying function object.
501
Guido van Rossum83b2f8a1998-07-23 17:12:46 +0000502User-defined method objects are created in two ways: when getting an
503attribute of a class that is a user-defined function object, or when
Fred Drake35c09f22000-06-28 20:15:47 +0000504getting an attribute of a class instance that is a user-defined
505function object defined by the class of the instance. In the former
506case (class attribute), the \member{im_self} attribute is \code{None},
507and the method object is said to be unbound; in the latter case
508(instance attribute), \method{im_self} is the instance, and the method
509object is said to be bound. For
Guido van Rossumb62f0e12001-12-07 22:03:18 +0000510instance, when \class{C} is a class which has a method
511\method{f()}, \code{C.f} does not yield the function object
Guido van Rossum83b2f8a1998-07-23 17:12:46 +0000512\code{f}; rather, it yields an unbound method object \code{m} where
Fred Drake82385871998-10-01 20:40:43 +0000513\code{m.im_class} is \class{C}, \code{m.im_func} is \method{f()}, and
514\code{m.im_self} is \code{None}. When \code{x} is a \class{C}
Guido van Rossum83b2f8a1998-07-23 17:12:46 +0000515instance, \code{x.f} yields a bound method object \code{m} where
Fred Drake82385871998-10-01 20:40:43 +0000516\code{m.im_class} is \code{C}, \code{m.im_func} is \method{f()}, and
Guido van Rossum83b2f8a1998-07-23 17:12:46 +0000517\code{m.im_self} is \code{x}.
Fred Drake4856d011999-01-12 04:15:20 +0000518\withsubitem{(method attribute)}{
Fred Drake35c09f22000-06-28 20:15:47 +0000519 \ttindex{im_class}\ttindex{im_func}\ttindex{im_self}}
Guido van Rossum83b2f8a1998-07-23 17:12:46 +0000520
521When an unbound user-defined method object is called, the underlying
Fred Drake82385871998-10-01 20:40:43 +0000522function (\member{im_func}) is called, with the restriction that the
Guido van Rossum83b2f8a1998-07-23 17:12:46 +0000523first argument must be an instance of the proper class
Fred Drake82385871998-10-01 20:40:43 +0000524(\member{im_class}) or of a derived class thereof.
Guido van Rossum83b2f8a1998-07-23 17:12:46 +0000525
526When a bound user-defined method object is called, the underlying
Fred Drake82385871998-10-01 20:40:43 +0000527function (\member{im_func}) is called, inserting the class instance
528(\member{im_self}) in front of the argument list. For instance, when
529\class{C} is a class which contains a definition for a function
530\method{f()}, and \code{x} is an instance of \class{C}, calling
Guido van Rossum83b2f8a1998-07-23 17:12:46 +0000531\code{x.f(1)} is equivalent to calling \code{C.f(x, 1)}.
532
533Note that the transformation from function object to (unbound or
534bound) method object happens each time the attribute is retrieved from
535the class or instance. In some cases, a fruitful optimization is to
536assign the attribute to a local variable and call that local variable.
537Also notice that this transformation only happens for user-defined
538functions; other callable objects (and all non-callable objects) are
Fred Drake35c09f22000-06-28 20:15:47 +0000539retrieved without transformation. It is also important to note that
540user-defined functions which are attributes of a class instance are
541not converted to bound methods; this \emph{only} happens when the
542function is an attribute of the class.
Guido van Rossum83b2f8a1998-07-23 17:12:46 +0000543
Fred Drakee31e9ce2001-12-11 21:10:08 +0000544\item[Generator functions\index{generator!function}\index{generator!iterator}]
545A function or method which uses the \keyword{yield} statement (see
546section~\ref{yield}, ``The \keyword{yield} statement'') is called a
547\dfn{generator function}. Such a function, when called, always
548returns an iterator object which can be used to execute the body of
549the function: calling the iterator's \method{next()} method will
550cause the function to execute until it provides a value using the
551\keyword{yield} statement. When the function executes a
552\keyword{return} statement or falls off the end, a
553\exception{StopIteration} exception is raised and the iterator will
554have reached the end of the set of values to be returned.
555
Fred Drakef6669171998-05-06 19:52:49 +0000556\item[Built-in functions]
Guido van Rossum83b2f8a1998-07-23 17:12:46 +0000557A built-in function object is a wrapper around a \C{} function. Examples
558of built-in functions are \function{len()} and \function{math.sin()}
559(\module{math} is a standard built-in module).
560The number and type of the arguments are
Fred Drakef6669171998-05-06 19:52:49 +0000561determined by the C function.
Fred Drake82385871998-10-01 20:40:43 +0000562Special read-only attributes: \member{__doc__} is the function's
563documentation string, or \code{None} if unavailable; \member{__name__}
564is the function's name; \member{__self__} is set to \code{None} (but see
Jeremy Hyltonf9b0cc72003-01-31 18:52:45 +0000565the next item); \member{__module__} is the name of the module the
566function was defined in or \code{None} if unavailable.
Fred Drakef6669171998-05-06 19:52:49 +0000567\obindex{built-in function}
568\obindex{function}
569\indexii{C}{language}
570
571\item[Built-in methods]
572This is really a different disguise of a built-in function, this time
Raymond Hettingere701dcb2003-01-19 13:08:18 +0000573containing an object passed to the C function as an implicit extra
Guido van Rossum83b2f8a1998-07-23 17:12:46 +0000574argument. An example of a built-in method is
Raymond Hettingere701dcb2003-01-19 13:08:18 +0000575\code{\var{alist}.append()}, assuming
576\var{alist} is a list object.
Fred Drake82385871998-10-01 20:40:43 +0000577In this case, the special read-only attribute \member{__self__} is set
Fred Drakee31e9ce2001-12-11 21:10:08 +0000578to the object denoted by \var{list}.
Fred Drakef6669171998-05-06 19:52:49 +0000579\obindex{built-in method}
580\obindex{method}
581\indexii{built-in}{method}
582
583\item[Classes]
Guido van Rossum83b2f8a1998-07-23 17:12:46 +0000584Class objects are described below. When a class object is called,
585a new class instance (also described below) is created and
Fred Drakef6669171998-05-06 19:52:49 +0000586returned. This implies a call to the class's \method{__init__()} method
587if it has one. Any arguments are passed on to the \method{__init__()}
Guido van Rossum83b2f8a1998-07-23 17:12:46 +0000588method. If there is no \method{__init__()} method, the class must be called
Fred Drakef6669171998-05-06 19:52:49 +0000589without arguments.
Fred Drake1e42d8a1998-11-25 17:58:50 +0000590\withsubitem{(object method)}{\ttindex{__init__()}}
Fred Drakef6669171998-05-06 19:52:49 +0000591\obindex{class}
592\obindex{class instance}
593\obindex{instance}
594\indexii{class object}{call}
595
Guido van Rossum83b2f8a1998-07-23 17:12:46 +0000596\item[Class instances]
597Class instances are described below. Class instances are callable
Fred Drake82385871998-10-01 20:40:43 +0000598only when the class has a \method{__call__()} method; \code{x(arguments)}
Guido van Rossum83b2f8a1998-07-23 17:12:46 +0000599is a shorthand for \code{x.__call__(arguments)}.
600
Fred Drakef6669171998-05-06 19:52:49 +0000601\end{description}
602
603\item[Modules]
Fred Drake62364ff2003-03-20 18:17:16 +0000604Modules are imported by the \keyword{import} statement (see
605section~\ref{import}, ``The \keyword{import} statement'').
Guido van Rossumdfb658c1998-07-23 17:54:36 +0000606A module object has a namespace implemented by a dictionary object
Guido van Rossum83b2f8a1998-07-23 17:12:46 +0000607(this is the dictionary referenced by the func_globals attribute of
608functions defined in the module). Attribute references are translated
609to lookups in this dictionary, e.g., \code{m.x} is equivalent to
610\code{m.__dict__["x"]}.
611A module object does not contain the code object used to
Fred Drakef6669171998-05-06 19:52:49 +0000612initialize the module (since it isn't needed once the initialization
613is done).
614\stindex{import}
615\obindex{module}
616
Guido van Rossumdfb658c1998-07-23 17:54:36 +0000617Attribute assignment updates the module's namespace dictionary,
Fred Drake82385871998-10-01 20:40:43 +0000618e.g., \samp{m.x = 1} is equivalent to \samp{m.__dict__["x"] = 1}.
Fred Drakef6669171998-05-06 19:52:49 +0000619
Guido van Rossumdfb658c1998-07-23 17:54:36 +0000620Special read-only attribute: \member{__dict__} is the module's
621namespace as a dictionary object.
Fred Drake1e42d8a1998-11-25 17:58:50 +0000622\withsubitem{(module attribute)}{\ttindex{__dict__}}
Guido van Rossum83b2f8a1998-07-23 17:12:46 +0000623
624Predefined (writable) attributes: \member{__name__}
625is the module's name; \member{__doc__} is the
626module's documentation string, or
Fred Drake82385871998-10-01 20:40:43 +0000627\code{None} if unavailable; \member{__file__} is the pathname of the
Guido van Rossum83b2f8a1998-07-23 17:12:46 +0000628file from which the module was loaded, if it was loaded from a file.
Fred Drake82385871998-10-01 20:40:43 +0000629The \member{__file__} attribute is not present for C{} modules that are
Guido van Rossum83b2f8a1998-07-23 17:12:46 +0000630statically linked into the interpreter; for extension modules loaded
631dynamically from a shared library, it is the pathname of the shared
632library file.
Fred Drake4856d011999-01-12 04:15:20 +0000633\withsubitem{(module attribute)}{
634 \ttindex{__name__}
635 \ttindex{__doc__}
Fred Drake1e42d8a1998-11-25 17:58:50 +0000636 \ttindex{__file__}}
Guido van Rossumdfb658c1998-07-23 17:54:36 +0000637\indexii{module}{namespace}
Fred Drakef6669171998-05-06 19:52:49 +0000638
639\item[Classes]
Fred Drake62364ff2003-03-20 18:17:16 +0000640Class objects are created by class definitions (see
641section~\ref{class}, ``Class definitions'').
Guido van Rossum83b2f8a1998-07-23 17:12:46 +0000642A class has a namespace implemented by a dictionary object.
643Class attribute references are translated to
644lookups in this dictionary,
Fred Drake82385871998-10-01 20:40:43 +0000645e.g., \samp{C.x} is translated to \samp{C.__dict__["x"]}.
Guido van Rossum83b2f8a1998-07-23 17:12:46 +0000646When the attribute name is not found
Fred Drakef6669171998-05-06 19:52:49 +0000647there, the attribute search continues in the base classes. The search
Guido van Rossum83b2f8a1998-07-23 17:12:46 +0000648is depth-first, left-to-right in the order of occurrence in the
Fred Drakef6669171998-05-06 19:52:49 +0000649base class list.
Guido van Rossum83b2f8a1998-07-23 17:12:46 +0000650When a class attribute reference would yield a user-defined function
651object, it is transformed into an unbound user-defined method object
Fred Drake82385871998-10-01 20:40:43 +0000652(see above). The \member{im_class} attribute of this method object is the
Guido van Rossum83b2f8a1998-07-23 17:12:46 +0000653class for which the attribute reference was initiated.
Fred Drakef6669171998-05-06 19:52:49 +0000654\obindex{class}
655\obindex{class instance}
656\obindex{instance}
657\indexii{class object}{call}
658\index{container}
659\obindex{dictionary}
660\indexii{class}{attribute}
661
662Class attribute assignments update the class's dictionary, never the
663dictionary of a base class.
664\indexiii{class}{attribute}{assignment}
665
Guido van Rossum83b2f8a1998-07-23 17:12:46 +0000666A class object can be called (see above) to yield a class instance (see
667below).
Fred Drakef6669171998-05-06 19:52:49 +0000668\indexii{class object}{call}
669
Guido van Rossum83b2f8a1998-07-23 17:12:46 +0000670Special attributes: \member{__name__} is the class name;
671\member{__module__} is the module name in which the class was defined;
Guido van Rossumdfb658c1998-07-23 17:54:36 +0000672\member{__dict__} is the dictionary containing the class's namespace;
Guido van Rossum83b2f8a1998-07-23 17:12:46 +0000673\member{__bases__} is a tuple (possibly empty or a singleton)
674containing the base classes, in the order of their occurrence in the
Fred Drake82385871998-10-01 20:40:43 +0000675base class list; \member{__doc__} is the class's documentation string,
Guido van Rossum83b2f8a1998-07-23 17:12:46 +0000676or None if undefined.
Fred Drake4856d011999-01-12 04:15:20 +0000677\withsubitem{(class attribute)}{
678 \ttindex{__name__}
679 \ttindex{__module__}
680 \ttindex{__dict__}
681 \ttindex{__bases__}
Fred Drake1e42d8a1998-11-25 17:58:50 +0000682 \ttindex{__doc__}}
Fred Drakef6669171998-05-06 19:52:49 +0000683
684\item[Class instances]
Guido van Rossum83b2f8a1998-07-23 17:12:46 +0000685A class instance is created by calling a class object (see above).
686A class instance has a namespace implemented as a dictionary which
687is the first place in which
Fred Drakef6669171998-05-06 19:52:49 +0000688attribute references are searched. When an attribute is not found
Guido van Rossum83b2f8a1998-07-23 17:12:46 +0000689there, and the instance's class has an attribute by that name,
690the search continues with the class attributes. If a class attribute
691is found that is a user-defined function object (and in no other
692case), it is transformed into an unbound user-defined method object
Fred Drake82385871998-10-01 20:40:43 +0000693(see above). The \member{im_class} attribute of this method object is
Guido van Rossumb62f0e12001-12-07 22:03:18 +0000694the
Guido van Rossum83b2f8a1998-07-23 17:12:46 +0000695class of the instance for which the attribute reference was initiated.
696If no class attribute is found, and the object's class has a
Fred Drake82385871998-10-01 20:40:43 +0000697\method{__getattr__()} method, that is called to satisfy the lookup.
Fred Drakef6669171998-05-06 19:52:49 +0000698\obindex{class instance}
699\obindex{instance}
700\indexii{class}{instance}
701\indexii{class instance}{attribute}
702
Guido van Rossum83b2f8a1998-07-23 17:12:46 +0000703Attribute assignments and deletions update the instance's dictionary,
Fred Drake82385871998-10-01 20:40:43 +0000704never a class's dictionary. If the class has a \method{__setattr__()} or
705\method{__delattr__()} method, this is called instead of updating the
Guido van Rossum83b2f8a1998-07-23 17:12:46 +0000706instance dictionary directly.
Fred Drakef6669171998-05-06 19:52:49 +0000707\indexiii{class instance}{attribute}{assignment}
708
709Class instances can pretend to be numbers, sequences, or mappings if
Guido van Rossum83b2f8a1998-07-23 17:12:46 +0000710they have methods with certain special names. See
Fred Drake62364ff2003-03-20 18:17:16 +0000711section~\ref{specialnames}, ``Special method names.''
Fred Drakee15956b2000-04-03 04:51:13 +0000712\obindex{numeric}
Fred Drakef6669171998-05-06 19:52:49 +0000713\obindex{sequence}
714\obindex{mapping}
715
Guido van Rossum83b2f8a1998-07-23 17:12:46 +0000716Special attributes: \member{__dict__} is the attribute
717dictionary; \member{__class__} is the instance's class.
Fred Drake4856d011999-01-12 04:15:20 +0000718\withsubitem{(instance attribute)}{
719 \ttindex{__dict__}
Fred Drake1e42d8a1998-11-25 17:58:50 +0000720 \ttindex{__class__}}
Fred Drakef6669171998-05-06 19:52:49 +0000721
722\item[Files]
Fred Drakee15eb351999-11-10 16:13:25 +0000723A file\obindex{file} object represents an open file. File objects are
724created by the \function{open()}\bifuncindex{open} built-in function,
725and also by
726\withsubitem{(in module os)}{\ttindex{popen()}}\function{os.popen()},
727\function{os.fdopen()}, and the
728\method{makefile()}\withsubitem{(socket method)}{\ttindex{makefile()}}
729method of socket objects (and perhaps by other functions or methods
730provided by extension modules). The objects
731\ttindex{sys.stdin}\code{sys.stdin},
732\ttindex{sys.stdout}\code{sys.stdout} and
733\ttindex{sys.stderr}\code{sys.stderr} are initialized to file objects
734corresponding to the interpreter's standard\index{stdio} input, output
735and error streams. See the \citetitle[../lib/lib.html]{Python Library
736Reference} for complete documentation of file objects.
Fred Drake4856d011999-01-12 04:15:20 +0000737\withsubitem{(in module sys)}{
738 \ttindex{stdin}
739 \ttindex{stdout}
Fred Drake1e42d8a1998-11-25 17:58:50 +0000740 \ttindex{stderr}}
Fred Drakee15eb351999-11-10 16:13:25 +0000741
Fred Drakef6669171998-05-06 19:52:49 +0000742
743\item[Internal types]
744A few types used internally by the interpreter are exposed to the user.
Guido van Rossum83b2f8a1998-07-23 17:12:46 +0000745Their definitions may change with future versions of the interpreter,
Fred Drakef6669171998-05-06 19:52:49 +0000746but they are mentioned here for completeness.
747\index{internal type}
748\index{types, internal}
749
750\begin{description}
751
752\item[Code objects]
Guido van Rossum83b2f8a1998-07-23 17:12:46 +0000753Code objects represent \emph{byte-compiled} executable Python code, or
754\emph{bytecode}.
Fred Drakef6669171998-05-06 19:52:49 +0000755The difference between a code
756object and a function object is that the function object contains an
Guido van Rossum83b2f8a1998-07-23 17:12:46 +0000757explicit reference to the function's globals (the module in which it
758was defined), while a code object contains no context;
759also the default argument values are stored in the function object,
760not in the code object (because they represent values calculated at
761run-time). Unlike function objects, code objects are immutable and
762contain no references (directly or indirectly) to mutable objects.
763\index{bytecode}
Fred Drakef6669171998-05-06 19:52:49 +0000764\obindex{code}
765
Fred Drake1e42d8a1998-11-25 17:58:50 +0000766Special read-only attributes: \member{co_name} gives the function
767name; \member{co_argcount} is the number of positional arguments
768(including arguments with default values); \member{co_nlocals} is the
769number of local variables used by the function (including arguments);
770\member{co_varnames} is a tuple containing the names of the local
Jeremy Hyltonaa90adc2001-03-23 17:23:50 +0000771variables (starting with the argument names); \member{co_cellvars} is
772a tuple containing the names of local variables that are referenced by
773nested functions; \member{co_freevars} is a tuple containing the names
Jeremy Hylton8392f362002-04-01 18:53:36 +0000774of free variables; \member{co_code} is a string representing the
775sequence of bytecode instructions;
Fred Drake1e42d8a1998-11-25 17:58:50 +0000776\member{co_consts} is a tuple containing the literals used by the
777bytecode; \member{co_names} is a tuple containing the names used by
778the bytecode; \member{co_filename} is the filename from which the code
779was compiled; \member{co_firstlineno} is the first line number of the
780function; \member{co_lnotab} is a string encoding the mapping from
Thomas Woutersf9b526d2000-07-16 19:05:38 +0000781byte code offsets to line numbers (for details see the source code of
Fred Drake1e42d8a1998-11-25 17:58:50 +0000782the interpreter); \member{co_stacksize} is the required stack size
783(including local variables); \member{co_flags} is an integer encoding
784a number of flags for the interpreter.
Jeremy Hyltonaa90adc2001-03-23 17:23:50 +0000785
Fred Drake4856d011999-01-12 04:15:20 +0000786\withsubitem{(code object attribute)}{
787 \ttindex{co_argcount}
788 \ttindex{co_code}
789 \ttindex{co_consts}
790 \ttindex{co_filename}
791 \ttindex{co_firstlineno}
792 \ttindex{co_flags}
793 \ttindex{co_lnotab}
794 \ttindex{co_name}
795 \ttindex{co_names}
796 \ttindex{co_nlocals}
797 \ttindex{co_stacksize}
Jeremy Hyltonaa90adc2001-03-23 17:23:50 +0000798 \ttindex{co_varnames}
799 \ttindex{co_cellvars}
800 \ttindex{co_freevars}}
Guido van Rossum83b2f8a1998-07-23 17:12:46 +0000801
Fred Drakee15956b2000-04-03 04:51:13 +0000802The following flag bits are defined for \member{co_flags}: bit
803\code{0x04} is set if the function uses the \samp{*arguments} syntax
804to accept an arbitrary number of positional arguments; bit
805\code{0x08} is set if the function uses the \samp{**keywords} syntax
Jeremy Hylton8392f362002-04-01 18:53:36 +0000806to accept arbitrary keyword arguments; bit \code{0x20} is set if the
Brett Cannon9e6fedd2003-06-15 22:57:44 +0000807function is a generator.
808\obindex{generator}
Jeremy Hylton8392f362002-04-01 18:53:36 +0000809
810Future feature declarations (\samp{from __future__ import division})
811also use bits in \member{co_flags} to indicate whether a code object
812was compiled with a particular feature enabled: bit \code{0x2000} is
813set if the function was compiled with future division enabled; bits
814\code{0x10} and \code{0x1000} were used in earlier versions of Python.
815
816Other bits in \member{co_flags} are reserved for internal use.
817
818If\index{documentation string} a code object represents a function,
819the first item in
Jeremy Hyltonaa90adc2001-03-23 17:23:50 +0000820\member{co_consts} is the documentation string of the function, or
821\code{None} if undefined.
Fred Drakef6669171998-05-06 19:52:49 +0000822
823\item[Frame objects]
824Frame objects represent execution frames. They may occur in traceback
825objects (see below).
826\obindex{frame}
827
828Special read-only attributes: \member{f_back} is to the previous
829stack frame (towards the caller), or \code{None} if this is the bottom
830stack frame; \member{f_code} is the code object being executed in this
Guido van Rossum83b2f8a1998-07-23 17:12:46 +0000831frame; \member{f_locals} is the dictionary used to look up local
832variables; \member{f_globals} is used for global variables;
Fred Drake82385871998-10-01 20:40:43 +0000833\member{f_builtins} is used for built-in (intrinsic) names;
834\member{f_restricted} is a flag indicating whether the function is
Michael W. Hudsoncfd38842002-12-17 16:15:34 +0000835executing in restricted execution mode; \member{f_lasti} gives the
Guido van Rossum83b2f8a1998-07-23 17:12:46 +0000836precise instruction (this is an index into the bytecode string of
Fred Drakef6669171998-05-06 19:52:49 +0000837the code object).
Fred Drake4856d011999-01-12 04:15:20 +0000838\withsubitem{(frame attribute)}{
839 \ttindex{f_back}
840 \ttindex{f_code}
841 \ttindex{f_globals}
842 \ttindex{f_locals}
Fred Drake4856d011999-01-12 04:15:20 +0000843 \ttindex{f_lasti}
844 \ttindex{f_builtins}
Fred Drake1e42d8a1998-11-25 17:58:50 +0000845 \ttindex{f_restricted}}
Guido van Rossum83b2f8a1998-07-23 17:12:46 +0000846
Fred Drake82385871998-10-01 20:40:43 +0000847Special writable attributes: \member{f_trace}, if not \code{None}, is a
Guido van Rossum83b2f8a1998-07-23 17:12:46 +0000848function called at the start of each source code line (this is used by
Fred Drake82385871998-10-01 20:40:43 +0000849the debugger); \member{f_exc_type}, \member{f_exc_value},
850\member{f_exc_traceback} represent the most recent exception caught in
Michael W. Hudsoncfd38842002-12-17 16:15:34 +0000851this frame; \member{f_lineno} is the current line number of the frame
852--- writing to this from within a trace function jumps to the given line
853(only for the bottom-most frame). A debugger can implement a Jump
854command (aka Set Next Statement) by writing to f_lineno.
Fred Drake4856d011999-01-12 04:15:20 +0000855\withsubitem{(frame attribute)}{
856 \ttindex{f_trace}
857 \ttindex{f_exc_type}
858 \ttindex{f_exc_value}
Michael W. Hudsoncfd38842002-12-17 16:15:34 +0000859 \ttindex{f_exc_traceback}
860 \ttindex{f_lineno}}
Fred Drakef6669171998-05-06 19:52:49 +0000861
862\item[Traceback objects] \label{traceback}
863Traceback objects represent a stack trace of an exception. A
864traceback object is created when an exception occurs. When the search
865for an exception handler unwinds the execution stack, at each unwound
866level a traceback object is inserted in front of the current
Guido van Rossum83b2f8a1998-07-23 17:12:46 +0000867traceback. When an exception handler is entered, the stack trace is
868made available to the program.
Fred Drake62364ff2003-03-20 18:17:16 +0000869(See section~\ref{try}, ``The \code{try} statement.'')
Guido van Rossum83b2f8a1998-07-23 17:12:46 +0000870It is accessible as \code{sys.exc_traceback}, and also as the third
871item of the tuple returned by \code{sys.exc_info()}. The latter is
872the preferred interface, since it works correctly when the program is
873using multiple threads.
874When the program contains no suitable handler, the stack trace is written
Fred Drakef6669171998-05-06 19:52:49 +0000875(nicely formatted) to the standard error stream; if the interpreter is
876interactive, it is also made available to the user as
877\code{sys.last_traceback}.
878\obindex{traceback}
879\indexii{stack}{trace}
880\indexii{exception}{handler}
881\indexii{execution}{stack}
Fred Drake4856d011999-01-12 04:15:20 +0000882\withsubitem{(in module sys)}{
883 \ttindex{exc_info}
884 \ttindex{exc_traceback}
Fred Drake1e42d8a1998-11-25 17:58:50 +0000885 \ttindex{last_traceback}}
Guido van Rossum83b2f8a1998-07-23 17:12:46 +0000886\ttindex{sys.exc_info}
Fred Drakef6669171998-05-06 19:52:49 +0000887\ttindex{sys.exc_traceback}
888\ttindex{sys.last_traceback}
889
890Special read-only attributes: \member{tb_next} is the next level in the
891stack trace (towards the frame where the exception occurred), or
892\code{None} if there is no next level; \member{tb_frame} points to the
893execution frame of the current level; \member{tb_lineno} gives the line
894number where the exception occurred; \member{tb_lasti} indicates the
895precise instruction. The line number and last instruction in the
896traceback may differ from the line number of its frame object if the
897exception occurred in a \keyword{try} statement with no matching
898except clause or with a finally clause.
Fred Drake4856d011999-01-12 04:15:20 +0000899\withsubitem{(traceback attribute)}{
900 \ttindex{tb_next}
901 \ttindex{tb_frame}
902 \ttindex{tb_lineno}
Fred Drake1e42d8a1998-11-25 17:58:50 +0000903 \ttindex{tb_lasti}}
Fred Drakef6669171998-05-06 19:52:49 +0000904\stindex{try}
905
Guido van Rossum83b2f8a1998-07-23 17:12:46 +0000906\item[Slice objects]
907Slice objects are used to represent slices when \emph{extended slice
908syntax} is used. This is a slice using two colons, or multiple slices
909or ellipses separated by commas, e.g., \code{a[i:j:step]}, \code{a[i:j,
Raymond Hettinger03ec6d52003-06-25 18:29:36 +0000910k:l]}, or \code{a[..., i:j]}. They are also created by the built-in
Fred Drake1e42d8a1998-11-25 17:58:50 +0000911\function{slice()}\bifuncindex{slice} function.
Guido van Rossum83b2f8a1998-07-23 17:12:46 +0000912
Thomas Woutersf9b526d2000-07-16 19:05:38 +0000913Special read-only attributes: \member{start} is the lower bound;
914\member{stop} is the upper bound; \member{step} is the step value; each is
Guido van Rossum83b2f8a1998-07-23 17:12:46 +0000915\code{None} if omitted. These attributes can have any type.
Fred Drake4856d011999-01-12 04:15:20 +0000916\withsubitem{(slice object attribute)}{
917 \ttindex{start}
918 \ttindex{stop}
Fred Drake1e42d8a1998-11-25 17:58:50 +0000919 \ttindex{step}}
Guido van Rossum83b2f8a1998-07-23 17:12:46 +0000920
Fred Drake5ec22f22002-09-24 21:09:13 +0000921Slice objects support one method:
922
923\begin{methoddesc}[slice]{indices}{self, length}
924This method takes a single integer argument \var{length} and computes
925information about the extended slice that the slice object would
926describe if applied to a sequence of \var{length} items. It returns a
927tuple of three integers; respectively these are the \var{start} and
928\var{stop} indices and the \var{step} or stride length of the slice.
929Missing or out-of-bounds indices are handled in a manner consistent
930with regular slices.
Michael W. Hudsonf0d777c2002-07-19 15:47:06 +0000931\versionadded{2.3}
Fred Drake5ec22f22002-09-24 21:09:13 +0000932\end{methoddesc}
Michael W. Hudsonf0d777c2002-07-19 15:47:06 +0000933
Fred Drakef6669171998-05-06 19:52:49 +0000934\end{description} % Internal types
935
936\end{description} % Types
937
938
Fred Drake61c77281998-07-28 19:34:22 +0000939\section{Special method names\label{specialnames}}
Fred Drakef6669171998-05-06 19:52:49 +0000940
941A class can implement certain operations that are invoked by special
Fred Draked82575d1998-08-28 20:03:12 +0000942syntax (such as arithmetic operations or subscripting and slicing) by
Fred Drake7af9f4d2003-05-12 13:50:11 +0000943defining methods with special names.\indexii{operator}{overloading}
944This is Python's approach to \dfn{operator overloading}, allowing
945classes to define their own behavior with respect to language
946operators. For instance, if a class defines
Fred Draked82575d1998-08-28 20:03:12 +0000947a method named \method{__getitem__()}, and \code{x} is an instance of
948this class, then \code{x[i]} is equivalent to
Raymond Hettinger94153092002-05-12 03:09:25 +0000949\code{x.__getitem__(i)}. Except where mentioned, attempts to execute
950an operation raise an exception when no appropriate method is defined.
Fred Drake1e42d8a1998-11-25 17:58:50 +0000951\withsubitem{(mapping object method)}{\ttindex{__getitem__()}}
Fred Drakef6669171998-05-06 19:52:49 +0000952
Fred Drake0c475592000-12-07 04:49:34 +0000953When implementing a class that emulates any built-in type, it is
954important that the emulation only be implemented to the degree that it
955makes sense for the object being modelled. For example, some
956sequences may work well with retrieval of individual elements, but
957extracting a slice may not make sense. (One example of this is the
958\class{NodeList} interface in the W3C's Document Object Model.)
959
Fred Drakef6669171998-05-06 19:52:49 +0000960
Fred Drake61c77281998-07-28 19:34:22 +0000961\subsection{Basic customization\label{customization}}
Fred Drakef6669171998-05-06 19:52:49 +0000962
Fred Drake044bb4d2001-08-02 15:53:05 +0000963\begin{methoddesc}[object]{__init__}{self\optional{, \moreargs}}
964Called\indexii{class}{constructor} when the instance is created. The
965arguments are those passed to the class constructor expression. If a
Raymond Hettingere701dcb2003-01-19 13:08:18 +0000966base class has an \method{__init__()} method, the derived class's
967\method{__init__()} method, if any, must explicitly call it to ensure proper
Fred Drake044bb4d2001-08-02 15:53:05 +0000968initialization of the base class part of the instance; for example:
969\samp{BaseClass.__init__(\var{self}, [\var{args}...])}. As a special
970contraint on constructors, no value may be returned; doing so will
971cause a \exception{TypeError} to be raised at runtime.
Fred Drake1e42d8a1998-11-25 17:58:50 +0000972\end{methoddesc}
Fred Drakef6669171998-05-06 19:52:49 +0000973
974
Fred Drake1e42d8a1998-11-25 17:58:50 +0000975\begin{methoddesc}[object]{__del__}{self}
Guido van Rossum7c0240f1998-07-24 15:36:43 +0000976Called when the instance is about to be destroyed. This is also
977called a destructor\index{destructor}. If a base class
Raymond Hettingere701dcb2003-01-19 13:08:18 +0000978has a \method{__del__()} method, the derived class's \method{__del__()}
979method, if any,
Fred Drakef6669171998-05-06 19:52:49 +0000980must explicitly call it to ensure proper deletion of the base class
Guido van Rossum83b2f8a1998-07-23 17:12:46 +0000981part of the instance. Note that it is possible (though not recommended!)
982for the \method{__del__()}
Fred Drakef6669171998-05-06 19:52:49 +0000983method to postpone destruction of the instance by creating a new
984reference to it. It may then be called at a later time when this new
985reference is deleted. It is not guaranteed that
986\method{__del__()} methods are called for objects that still exist when
987the interpreter exits.
Fred Drakef6669171998-05-06 19:52:49 +0000988\stindex{del}
989
Fred Drake591dd8f2001-12-14 22:52:41 +0000990\begin{notice}
991\samp{del x} doesn't directly call
Guido van Rossum83b2f8a1998-07-23 17:12:46 +0000992\code{x.__del__()} --- the former decrements the reference count for
Raymond Hettingere701dcb2003-01-19 13:08:18 +0000993\code{x} by one, and the latter is only called when \code{x}'s reference
Guido van Rossum83b2f8a1998-07-23 17:12:46 +0000994count reaches zero. Some common situations that may prevent the
Raymond Hettingere701dcb2003-01-19 13:08:18 +0000995reference count of an object from going to zero include: circular
Guido van Rossum83b2f8a1998-07-23 17:12:46 +0000996references between objects (e.g., a doubly-linked list or a tree data
997structure with parent and child pointers); a reference to the object
998on the stack frame of a function that caught an exception (the
999traceback stored in \code{sys.exc_traceback} keeps the stack frame
1000alive); or a reference to the object on the stack frame that raised an
1001unhandled exception in interactive mode (the traceback stored in
1002\code{sys.last_traceback} keeps the stack frame alive). The first
1003situation can only be remedied by explicitly breaking the cycles; the
Fred Drake591dd8f2001-12-14 22:52:41 +00001004latter two situations can be resolved by storing \code{None} in
1005\code{sys.exc_traceback} or \code{sys.last_traceback}. Circular
1006references which are garbage are detected when the option cycle
1007detector is enabled (it's on by default), but can only be cleaned up
1008if there are no Python-level \method{__del__()} methods involved.
1009Refer to the documentation for the \ulink{\module{gc}
1010module}{../lib/module-gc.html} for more information about how
1011\method{__del__()} methods are handled by the cycle detector,
1012particularly the description of the \code{garbage} value.
1013\end{notice}
Fred Drakef6669171998-05-06 19:52:49 +00001014
Fred Drake591dd8f2001-12-14 22:52:41 +00001015\begin{notice}[warning]
1016Due to the precarious circumstances under which
Fred Draked82575d1998-08-28 20:03:12 +00001017\method{__del__()} methods are invoked, exceptions that occur during their
Guido van Rossum83b2f8a1998-07-23 17:12:46 +00001018execution are ignored, and a warning is printed to \code{sys.stderr}
Fred Drake591dd8f2001-12-14 22:52:41 +00001019instead. Also, when \method{__del__()} is invoked in response to a module
Guido van Rossum83b2f8a1998-07-23 17:12:46 +00001020being deleted (e.g., when execution of the program is done), other
Fred Draked82575d1998-08-28 20:03:12 +00001021globals referenced by the \method{__del__()} method may already have been
1022deleted. For this reason, \method{__del__()} methods should do the
Raymond Hettingera0e4d6c2002-09-08 21:10:54 +00001023absolute minimum needed to maintain external invariants. Starting with
1024version 1.5, Python guarantees that globals whose name begins with a single
1025underscore are deleted from their module before other globals are deleted;
1026if no other references to such globals exist, this may help in assuring that
Guido van Rossum83b2f8a1998-07-23 17:12:46 +00001027imported modules are still available at the time when the
Fred Drake591dd8f2001-12-14 22:52:41 +00001028\method{__del__()} method is called.
1029\end{notice}
Fred Drake1e42d8a1998-11-25 17:58:50 +00001030\end{methoddesc}
Fred Drakef6669171998-05-06 19:52:49 +00001031
Fred Drake1e42d8a1998-11-25 17:58:50 +00001032\begin{methoddesc}[object]{__repr__}{self}
Fred Drake82385871998-10-01 20:40:43 +00001033Called by the \function{repr()}\bifuncindex{repr} built-in function
1034and by string conversions (reverse quotes) to compute the ``official''
Andrew M. Kuchling68abe832000-12-19 14:09:21 +00001035string representation of an object. If at all possible, this should
Guido van Rossum035f7e82000-12-19 04:18:13 +00001036look like a valid Python expression that could be used to recreate an
1037object with the same value (given an appropriate environment). If
1038this is not possible, a string of the form \samp{<\var{...some useful
1039description...}>} should be returned. The return value must be a
1040string object.
Raymond Hettingere701dcb2003-01-19 13:08:18 +00001041If a class defines \method{__repr__()} but not \method{__str__()},
1042then \method{__repr__()} is also used when an ``informal'' string
1043representation of instances of that class is required.
Guido van Rossum035f7e82000-12-19 04:18:13 +00001044
1045This is typically used for debugging, so it is important that the
1046representation is information-rich and unambiguous.
Fred Drakef6669171998-05-06 19:52:49 +00001047\indexii{string}{conversion}
1048\indexii{reverse}{quotes}
1049\indexii{backward}{quotes}
1050\index{back-quotes}
Fred Drake1e42d8a1998-11-25 17:58:50 +00001051\end{methoddesc}
Fred Drakef6669171998-05-06 19:52:49 +00001052
Fred Drake1e42d8a1998-11-25 17:58:50 +00001053\begin{methoddesc}[object]{__str__}{self}
Fred Draked82575d1998-08-28 20:03:12 +00001054Called by the \function{str()}\bifuncindex{str} built-in function and
1055by the \keyword{print}\stindex{print} statement to compute the
Fred Drake82385871998-10-01 20:40:43 +00001056``informal'' string representation of an object. This differs from
1057\method{__repr__()} in that it does not have to be a valid Python
1058expression: a more convenient or concise representation may be used
Guido van Rossum035f7e82000-12-19 04:18:13 +00001059instead. The return value must be a string object.
Fred Drake1e42d8a1998-11-25 17:58:50 +00001060\end{methoddesc}
Fred Drakef6669171998-05-06 19:52:49 +00001061
Guido van Rossumab782dd2001-01-18 15:17:06 +00001062\begin{methoddesc}[object]{__lt__}{self, other}
1063\methodline[object]{__le__}{self, other}
1064\methodline[object]{__eq__}{self, other}
1065\methodline[object]{__ne__}{self, other}
1066\methodline[object]{__gt__}{self, other}
1067\methodline[object]{__ge__}{self, other}
1068\versionadded{2.1}
1069These are the so-called ``rich comparison'' methods, and are called
1070for comparison operators in preference to \method{__cmp__()} below.
1071The correspondence between operator symbols and method names is as
1072follows:
1073\code{\var{x}<\var{y}} calls \code{\var{x}.__lt__(\var{y})},
1074\code{\var{x}<=\var{y}} calls \code{\var{x}.__le__(\var{y})},
1075\code{\var{x}==\var{y}} calls \code{\var{x}.__eq__(\var{y})},
1076\code{\var{x}!=\var{y}} and \code{\var{x}<>\var{y}} call
1077\code{\var{x}.__ne__(\var{y})},
1078\code{\var{x}>\var{y}} calls \code{\var{x}.__gt__(\var{y})}, and
1079\code{\var{x}>=\var{y}} calls \code{\var{x}.__ge__(\var{y})}.
1080These methods can return any value, but if the comparison operator is
1081used in a Boolean context, the return value should be interpretable as
1082a Boolean value, else a \exception{TypeError} will be raised.
Raymond Hettingere701dcb2003-01-19 13:08:18 +00001083By convention, \code{False} is used for false and \code{True} for true.
Guido van Rossumab782dd2001-01-18 15:17:06 +00001084
1085There are no reflected (swapped-argument) versions of these methods
1086(to be used when the left argument does not support the operation but
1087the right argument does); rather, \method{__lt__()} and
1088\method{__gt__()} are each other's reflection, \method{__le__()} and
1089\method{__ge__()} are each other's reflection, and \method{__eq__()}
1090and \method{__ne__()} are their own reflection.
1091
1092Arguments to rich comparison methods are never coerced. A rich
1093comparison method may return \code{NotImplemented} if it does not
1094implement the operation for a given pair of arguments.
1095\end{methoddesc}
1096
Fred Drake1e42d8a1998-11-25 17:58:50 +00001097\begin{methoddesc}[object]{__cmp__}{self, other}
Guido van Rossumab782dd2001-01-18 15:17:06 +00001098Called by comparison operations if rich comparison (see above) is not
Fred Drake597bc1d2001-05-29 16:02:35 +00001099defined. Should return a negative integer if \code{self < other},
1100zero if \code{self == other}, a positive integer if \code{self >
1101other}. If no \method{__cmp__()}, \method{__eq__()} or
1102\method{__ne__()} operation is defined, class instances are compared
1103by object identity (``address''). See also the description of
1104\method{__hash__()} for some important notes on creating objects which
1105support custom comparison operations and are usable as dictionary
1106keys.
Guido van Rossum83b2f8a1998-07-23 17:12:46 +00001107(Note: the restriction that exceptions are not propagated by
Raymond Hettingere701dcb2003-01-19 13:08:18 +00001108\method{__cmp__()} has been removed since Python 1.5.)
Fred Drakef6669171998-05-06 19:52:49 +00001109\bifuncindex{cmp}
1110\index{comparisons}
Fred Drake1e42d8a1998-11-25 17:58:50 +00001111\end{methoddesc}
Fred Drakef6669171998-05-06 19:52:49 +00001112
Fred Drakee57a1142000-06-15 20:07:25 +00001113\begin{methoddesc}[object]{__rcmp__}{self, other}
Fred Drake445f8322001-01-04 15:11:48 +00001114 \versionchanged[No longer supported]{2.1}
Fred Drakee57a1142000-06-15 20:07:25 +00001115\end{methoddesc}
1116
Fred Drake1e42d8a1998-11-25 17:58:50 +00001117\begin{methoddesc}[object]{__hash__}{self}
Fred Draked82575d1998-08-28 20:03:12 +00001118Called for the key object for dictionary\obindex{dictionary}
1119operations, and by the built-in function
Fred Drakef6669171998-05-06 19:52:49 +00001120\function{hash()}\bifuncindex{hash}. Should return a 32-bit integer
1121usable as a hash value
1122for dictionary operations. The only required property is that objects
1123which compare equal have the same hash value; it is advised to somehow
Guido van Rossum83b2f8a1998-07-23 17:12:46 +00001124mix together (e.g., using exclusive or) the hash values for the
Fred Drakef6669171998-05-06 19:52:49 +00001125components of the object that also play a part in comparison of
1126objects. If a class does not define a \method{__cmp__()} method it should
1127not define a \method{__hash__()} operation either; if it defines
Fred Drake597bc1d2001-05-29 16:02:35 +00001128\method{__cmp__()} or \method{__eq__()} but not \method{__hash__()},
1129its instances will not be usable as dictionary keys. If a class
1130defines mutable objects and implements a \method{__cmp__()} or
1131\method{__eq__()} method, it should not implement \method{__hash__()},
1132since the dictionary implementation requires that a key's hash value
1133is immutable (if the object's hash value changes, it will be in the
1134wrong hash bucket).
Fred Drake1e42d8a1998-11-25 17:58:50 +00001135\withsubitem{(object method)}{\ttindex{__cmp__()}}
1136\end{methoddesc}
Fred Drakef6669171998-05-06 19:52:49 +00001137
Fred Drake1e42d8a1998-11-25 17:58:50 +00001138\begin{methoddesc}[object]{__nonzero__}{self}
Guido van Rossum77f6a652002-04-03 22:41:51 +00001139Called to implement truth value testing, and the built-in operation
1140\code{bool()}; should return \code{False} or \code{True}, or their
1141integer equivalents \code{0} or \code{1}.
1142When this method is not defined, \method{__len__()} is
Fred Draked82575d1998-08-28 20:03:12 +00001143called, if it is defined (see below). If a class defines neither
1144\method{__len__()} nor \method{__nonzero__()}, all its instances are
1145considered true.
Fred Drake1e42d8a1998-11-25 17:58:50 +00001146\withsubitem{(mapping object method)}{\ttindex{__len__()}}
1147\end{methoddesc}
Fred Drakef6669171998-05-06 19:52:49 +00001148
Martin v. Löwis2a519f82002-04-11 12:39:35 +00001149\begin{methoddesc}[object]{__unicode__}{self}
1150Called to implement \function{unicode()}\bifuncindex{unicode} builtin;
1151should return a Unicode object. When this method is not defined, string
1152conversion is attempted, and the result of string conversion is converted
1153to Unicode using the system default encoding.
1154\end{methoddesc}
1155
Fred Drakef6669171998-05-06 19:52:49 +00001156
Fred Drake61c77281998-07-28 19:34:22 +00001157\subsection{Customizing attribute access\label{attribute-access}}
Fred Drakef6669171998-05-06 19:52:49 +00001158
Guido van Rossum83b2f8a1998-07-23 17:12:46 +00001159The following methods can be defined to customize the meaning of
1160attribute access (use of, assignment to, or deletion of \code{x.name})
1161for class instances.
Fred Drakef6669171998-05-06 19:52:49 +00001162
Fred Drake1e42d8a1998-11-25 17:58:50 +00001163\begin{methoddesc}[object]{__getattr__}{self, name}
Fred Drakef6669171998-05-06 19:52:49 +00001164Called when an attribute lookup has not found the attribute in the
1165usual places (i.e. it is not an instance attribute nor is it found in
1166the class tree for \code{self}). \code{name} is the attribute name.
Guido van Rossum83b2f8a1998-07-23 17:12:46 +00001167This method should return the (computed) attribute value or raise an
Fred Draked82575d1998-08-28 20:03:12 +00001168\exception{AttributeError} exception.
Fred Drakef6669171998-05-06 19:52:49 +00001169
1170Note that if the attribute is found through the normal mechanism,
Fred Draked82575d1998-08-28 20:03:12 +00001171\method{__getattr__()} is not called. (This is an intentional
1172asymmetry between \method{__getattr__()} and \method{__setattr__()}.)
Fred Drakef6669171998-05-06 19:52:49 +00001173This is done both for efficiency reasons and because otherwise
Fred Draked82575d1998-08-28 20:03:12 +00001174\method{__setattr__()} would have no way to access other attributes of
Guido van Rossumd41eea02003-02-28 14:11:45 +00001175the instance. Note that at least for instance variables, you can fake
1176total control by not inserting any values in the instance attribute
1177dictionary (but instead inserting them in another object). See the
1178\method{__getattribute__()} method below for a way to actually get
1179total control in new-style classes.
Fred Drake1e42d8a1998-11-25 17:58:50 +00001180\withsubitem{(object method)}{\ttindex{__setattr__()}}
1181\end{methoddesc}
Fred Drakef6669171998-05-06 19:52:49 +00001182
Fred Drake1e42d8a1998-11-25 17:58:50 +00001183\begin{methoddesc}[object]{__setattr__}{self, name, value}
Fred Drakef6669171998-05-06 19:52:49 +00001184Called when an attribute assignment is attempted. This is called
Fred Draked82575d1998-08-28 20:03:12 +00001185instead of the normal mechanism (i.e.\ store the value in the instance
1186dictionary). \var{name} is the attribute name, \var{value} is the
Fred Drakef6669171998-05-06 19:52:49 +00001187value to be assigned to it.
Fred Drakef6669171998-05-06 19:52:49 +00001188
Fred Draked82575d1998-08-28 20:03:12 +00001189If \method{__setattr__()} wants to assign to an instance attribute, it
1190should not simply execute \samp{self.\var{name} = value} --- this
1191would cause a recursive call to itself. Instead, it should insert the
1192value in the dictionary of instance attributes, e.g.,
Guido van Rossumd41eea02003-02-28 14:11:45 +00001193\samp{self.__dict__[\var{name}] = value}. For new-style classes,
1194rather than accessing the instance dictionary, it should call the base
1195class method with the same name, for example,
1196\samp{object.__setattr__(self, name, value)}.
Fred Drake1e42d8a1998-11-25 17:58:50 +00001197\withsubitem{(instance attribute)}{\ttindex{__dict__}}
1198\end{methoddesc}
Fred Drakef6669171998-05-06 19:52:49 +00001199
Fred Drake1e42d8a1998-11-25 17:58:50 +00001200\begin{methoddesc}[object]{__delattr__}{self, name}
Fred Draked82575d1998-08-28 20:03:12 +00001201Like \method{__setattr__()} but for attribute deletion instead of
Fred Drake1e42d8a1998-11-25 17:58:50 +00001202assignment. This should only be implemented if \samp{del
1203obj.\var{name}} is meaningful for the object.
1204\end{methoddesc}
Fred Drakef6669171998-05-06 19:52:49 +00001205
Michael W. Hudson2ab1d082003-03-05 14:20:58 +00001206\subsubsection{More attribute access for new-style classes \label{new-style-attribute-access}}
Guido van Rossumd41eea02003-02-28 14:11:45 +00001207
1208The following methods only apply to new-style classes.
1209
1210\begin{methoddesc}[object]{__getattribute__}{self, name}
1211Called unconditionally to implement attribute accesses for instances
1212of the class. If the class also defines \method{__getattr__}, it will
1213never be called (unless called explicitly).
1214This method should return the (computed) attribute
1215value or raise an \exception{AttributeError} exception.
1216In order to avoid infinite recursion in this method, its
1217implementation should always call the base class method with the same
Fred Drake62364ff2003-03-20 18:17:16 +00001218name to access any attributes it needs, for example,
Guido van Rossumd41eea02003-02-28 14:11:45 +00001219\samp{object.__getattribute__(self, name)}.
1220\end{methoddesc}
1221
Michael W. Hudson2ab1d082003-03-05 14:20:58 +00001222\subsubsection{Implementing Descriptors \label{descriptors}}
Guido van Rossumd41eea02003-02-28 14:11:45 +00001223
1224The following methods only apply when an instance of the class
Fred Drake62364ff2003-03-20 18:17:16 +00001225containing the method (a so-called \emph{descriptor} class) appears in
Guido van Rossumd41eea02003-02-28 14:11:45 +00001226the class dictionary of another new-style class, known as the
1227\emph{owner} class. In the examples below, ``the attribute'' refers to
Fred Drake62364ff2003-03-20 18:17:16 +00001228the attribute whose name is the key of the property in the owner
Guido van Rossumd41eea02003-02-28 14:11:45 +00001229class' \code{__dict__}.
1230
1231\begin{methoddesc}[object]{__get__}{self, instance, owner}
Fred Drake62364ff2003-03-20 18:17:16 +00001232Called to get the attribute of the owner class (class attribute access)
Guido van Rossumd41eea02003-02-28 14:11:45 +00001233or of an instance of that class (instance attribute acces).
1234\var{owner} is always the owner class, while \var{instance} is the
1235instance that the attribute was accessed through, or \code{None} when
1236the attribute is accessed through the \var{owner}. This method should
1237return the (computed) attribute value or raise an
1238\exception{AttributeError} exception.
1239\end{methoddesc}
1240
1241\begin{methoddesc}[object]{__set__}{self, instance, value}
Michael W. Hudson2ab1d082003-03-05 14:20:58 +00001242Called to set the attribute on an instance \var{instance} of the owner
Guido van Rossumd41eea02003-02-28 14:11:45 +00001243class to a new value, \var{value}.
1244\end{methoddesc}
1245
1246\begin{methoddesc}[object]{__delete__}{self, instance}
Michael W. Hudson2ab1d082003-03-05 14:20:58 +00001247Called to delete the attribute on an instance \var{instance} of the
1248owner class.
Guido van Rossumd41eea02003-02-28 14:11:45 +00001249\end{methoddesc}
1250
Fred Drakef6669171998-05-06 19:52:49 +00001251
Fred Drake4db36612003-06-26 03:11:20 +00001252\subsubsection{Invoking Descriptors \label{descriptor-invocation}}
Raymond Hettinger03ec6d52003-06-25 18:29:36 +00001253
1254In general, a descriptor is an object attribute with ``binding behavior'',
1255one whose attribute access has been overridden by methods in the descriptor
Raymond Hettingerdf9eff02003-06-27 06:57:56 +00001256protocol: \method{__get__()}, \method{__set__()}, and \method{__delete__()}.
Raymond Hettinger03ec6d52003-06-25 18:29:36 +00001257If any of those methods are defined for an object, it is said to be a
1258descriptor.
1259
1260The default behavior for attribute access is to get, set, or delete the
1261attribute from an object's dictionary. For instance, \code{a.x} has a
1262lookup chain starting with \code{a.__dict__['x']}, then
1263\code{type(a).__dict__['x']}, and continuing
1264through the base classes of \code{type(a)} excluding metaclasses.
1265
1266However, if the looked-up value is an object defining one of the descriptor
1267methods, then Python may override the default behavior and invoke the
1268descriptor method instead. Where this occurs in the precedence chain depends
1269on which descriptor methods were defined and how they were called. Note that
1270descriptors are only invoked for new style objects or classes
Raymond Hettingerdf9eff02003-06-27 06:57:56 +00001271(ones that subclass \class{object()} or \class{type()}).
Raymond Hettinger03ec6d52003-06-25 18:29:36 +00001272
1273The starting point for descriptor invocation is a binding, \code{a.x}.
1274How the arguments are assembled depends on \code{a}:
1275
1276\begin{itemize}
1277
1278 \item[Direct Call] The simplest and least common call is when user code
1279 directly invokes a descriptor method: \code{x.__get__(a)}.
1280
1281 \item[Instance Binding] If binding to a new-style object instance,
1282 \code{a.x} is transformed into the call:
1283 \code{type(a).__dict__['x'].__get__(a, type(a))}.
1284
1285 \item[Class Binding] If binding to a new-style class, \code{A.x}
1286 is transformed into the call: \code{A.__dict__['x'].__get__(None, A)}.
1287
1288 \item[Super Binding] If \code{a} is an instance of \class{super},
1289 then the binding \code{super(B, obj).m()} searches
1290 \code{obj.__class__.__mro__} for the base class \code{A} immediately
1291 preceding \code{B} and then invokes the descriptor with the call:
1292 \code{A.__dict__['m'].__get__(obj, A)}.
1293
1294\end{itemize}
1295
1296For instance bindings, the precedence of descriptor invocation depends
1297on the which descriptor methods are defined. Data descriptors define
Raymond Hettingerdf9eff02003-06-27 06:57:56 +00001298both \method{__get__()} and \method{__set__()}. Non-data descriptors have
1299just the \method{__get__()} method. Data descriptors always override
Raymond Hettinger03ec6d52003-06-25 18:29:36 +00001300a redefinition in an instance dictionary. In contrast, non-data
1301descriptors can be overridden by instances.
1302
Raymond Hettingerdf9eff02003-06-27 06:57:56 +00001303Python methods (including \function{staticmethod()} and \function{classmethod()})
Raymond Hettinger03ec6d52003-06-25 18:29:36 +00001304are implemented as non-data descriptors. Accordingly, instances can
1305redefine and override methods. This allows individual instances to acquire
1306behaviors that differ from other instances of the same class.
1307
Raymond Hettingerdf9eff02003-06-27 06:57:56 +00001308The \function{property()} function is implemented as a data descriptor.
1309Accordingly, instances cannot override the behavior of a property.
1310
1311
1312\subsubsection{__slots__\label{slots}}
1313
1314By default, instances of both old and new-style classes have a dictionary
1315for attribute storage. This wastes space for objects having very few instance
1316variables. The space consumption can become acute when creating large numbers
1317of instances.
1318
1319The default can be overridden by defining \var{__slots__} in a new-style class
1320definition. The \var{__slots__} declaration takes a sequence of instance
1321variables and reserves just enough space in each instance to hold a value
1322for each variable. Space is saved because \var{__dict__} is not created for
1323each instance.
1324
1325\begin{datadesc}{__slots__}
1326This class variable can be assigned a string, iterable, or sequence of strings
1327with variable names used by instances. If defined in a new-style class
1328definition, \var{__slots__} reserves space for the declared variables
1329and prevents the automatic creation of \var{__dict__} and \var{__weakref__}
1330for each instance.
1331\versionadded{2.2}
1332\end{datadesc}
1333
1334\noindent
1335Notes on Using \var{__slots__}
1336
1337\begin{itemize}
1338
1339\item Without a \var{__dict__} variable, instances cannot be assigned new
1340variables not listed in the \var{__slots__} definition. Attempts to assign
1341to an unlisted variable name raises \exception{AttributeError}. If dynamic
1342assignment of new variables is desired, then add \code{'__dict__'} to the
1343sequence of strings in the \var{__slots__} declaration.
1344\versionchanged[Previously, adding \code{'__dict__'} to the \var{__slots__}
1345declaration would not enable the assignment of new attributes not
1346specifically listed in the sequence of instance variable names]{2.3}
1347
1348\item Without a \var{__weakref__} variable for each instance, classes
1349defining \var{__slots__} do not support weak references to its instances.
1350If weak reference support is needed, then add \code{'__weakref__'} to the
1351sequence of strings in the \var{__slots__} declaration.
1352\versionchanged[Previously, adding \code{__weakref__} to the \var{__slots__}
1353declaration would not enable support for weak references]{2.3}
1354
1355\item \var{__slots__} are implemented at the class level by creating
1356descriptors (\ref{descriptors}) for each variable name. As a result,
1357class attributes cannot be used to set default values for instance
1358variables defined by \var{__slots__}; otherwise, the class attribute would
1359overwrite the descriptor assignment.
1360
1361\item If a class defines a slot also defined in a base class, the instance
1362variable defined by the base class slot is inaccessible (except by retrieving
1363its descriptor directly from the base class). This renders the meaning of the
1364program undefined. In the future, a check may be added to prevent this.
1365
1366\item The action of a \var{__slots__} declaration is limited to the class
1367where it is defined. As a result, subclasses will have a \var{__dict__}
1368unless they also define \var{__slots__}.
1369
1370\item \var{__slots__} do not work for classes derived from ``variable-length''
1371built-in types such as \class{long}, \class{str} and \class{tuple}.
1372
1373\item Any non-string iterable may be assigned \var{__slots__}.
1374Mappings may also be used; however, in the future, special meaning may
1375be assigned to the values corresponding to each key.
1376
1377\end{itemize}
1378
1379
1380\subsection{Customizing class creation\label{metaclasses}}
1381
1382By default, new-style classes are constructed using \function{type()}.
1383A class definition is read into a separate namespace and the value
1384of class name is bound to the result of \code{type(name, bases, dict)}.
1385
1386When the class definition is read, if \var{__metaclass__} is defined
1387then the callable assigned to it will be called instead of \function{type()}.
1388The allows classes or functions to be written which monitor or alter the class
1389creation process:
1390
1391\begin{itemize}
1392\item Modifying the class dictionary prior to the class being created.
1393\item Returning an instance of another class -- essentially performing
1394the role of a factory function.
1395\end{itemize}
1396
1397\begin{datadesc}{__metaclass__}
1398This variable can be any callable accepting arguments for \code{name},
1399\code{bases}, and \code{dict}. Upon class creation, the callable is
1400used instead of the built-in \function{type()}.
1401\versionadded{2.2}
1402\end{datadesc}
1403
1404The appropriate metaclass is determined by the following precedence rules:
1405
1406\begin{itemize}
1407
1408\item If \code{dict['__metaclass__']} exists, it is used.
1409
1410\item Otherwise, if there is at least one base class, its metaclass is used
1411(this looks for a \var{__class__} attribute first and if not found, uses its
1412type).
1413
1414\item Otherwise, if a global variable named __metaclass__ exists, it is used.
1415
1416\item Otherwise, the old-style, classic metaclass (types.ClassType) is used.
1417
1418\end{itemize}
1419
1420The potential uses for metaclasses are boundless. Some ideas that have
1421been explored including logging, interface checking, automatic delegation,
1422automatic property creation, proxies, frameworks, and automatic resource
1423locking/synchronization.
Raymond Hettinger03ec6d52003-06-25 18:29:36 +00001424
1425
Fred Drake61c77281998-07-28 19:34:22 +00001426\subsection{Emulating callable objects\label{callable-types}}
Guido van Rossum83b2f8a1998-07-23 17:12:46 +00001427
Fred Drake1e42d8a1998-11-25 17:58:50 +00001428\begin{methoddesc}[object]{__call__}{self\optional{, args...}}
Guido van Rossum83b2f8a1998-07-23 17:12:46 +00001429Called when the instance is ``called'' as a function; if this method
Fred Draked82575d1998-08-28 20:03:12 +00001430is defined, \code{\var{x}(arg1, arg2, ...)} is a shorthand for
1431\code{\var{x}.__call__(arg1, arg2, ...)}.
Guido van Rossum83b2f8a1998-07-23 17:12:46 +00001432\indexii{call}{instance}
Fred Drake1e42d8a1998-11-25 17:58:50 +00001433\end{methoddesc}
Guido van Rossum83b2f8a1998-07-23 17:12:46 +00001434
1435
Fred Drake73921b02001-10-01 16:32:13 +00001436\subsection{Emulating container types\label{sequence-types}}
Guido van Rossum83b2f8a1998-07-23 17:12:46 +00001437
Fred Drake73921b02001-10-01 16:32:13 +00001438The following methods can be defined to implement container
1439objects. Containers usually are sequences (such as lists or tuples)
1440or mappings (like dictionaries), but can represent other containers as
1441well. The first set of methods is used either to emulate a
Guido van Rossum83b2f8a1998-07-23 17:12:46 +00001442sequence or to emulate a mapping; the difference is that for a
1443sequence, the allowable keys should be the integers \var{k} for which
1444\code{0 <= \var{k} < \var{N}} where \var{N} is the length of the
Thomas Wouters1d75a792000-08-17 22:37:32 +00001445sequence, or slice objects, which define a range of items. (For backwards
1446compatibility, the method \method{__getslice__()} (see below) can also be
1447defined to handle simple, but not extended slices.) It is also recommended
Fred Drakea0073822000-08-18 02:42:14 +00001448that mappings provide the methods \method{keys()}, \method{values()},
Thomas Wouters1d75a792000-08-17 22:37:32 +00001449\method{items()}, \method{has_key()}, \method{get()}, \method{clear()},
Raymond Hettingere701dcb2003-01-19 13:08:18 +00001450\method{setdefault()}, \method{iterkeys()}, \method{itervalues()},
Raymond Hettingerf4ca5a22003-01-19 14:57:12 +00001451\method{iteritems()}, \method{pop()}, \method{popitem()},
Thomas Wouters1d75a792000-08-17 22:37:32 +00001452\method{copy()}, and \method{update()} behaving similar to those for
Raymond Hettingere701dcb2003-01-19 13:08:18 +00001453Python's standard dictionary objects. The \module{UserDict} module
1454provides a \class{DictMixin} class to help create those methods
1455from a base set of \method{__getitem__()}, \method{__setitem__()},
1456\method{__delitem__()}, and \method{keys()}.
1457Mutable sequences should provide
Guido van Rossum83b2f8a1998-07-23 17:12:46 +00001458methods \method{append()}, \method{count()}, \method{index()},
Raymond Hettingere701dcb2003-01-19 13:08:18 +00001459\method{extend()},
Guido van Rossum83b2f8a1998-07-23 17:12:46 +00001460\method{insert()}, \method{pop()}, \method{remove()}, \method{reverse()}
1461and \method{sort()}, like Python standard list objects. Finally,
1462sequence types should implement addition (meaning concatenation) and
1463multiplication (meaning repetition) by defining the methods
Thomas Wouters12bba852000-08-24 20:06:04 +00001464\method{__add__()}, \method{__radd__()}, \method{__iadd__()},
1465\method{__mul__()}, \method{__rmul__()} and \method{__imul__()} described
1466below; they should not define \method{__coerce__()} or other numerical
Guido van Rossum0dbb4fb2001-04-20 16:50:40 +00001467operators. It is recommended that both mappings and sequences
Fred Drake18d8d5a2001-09-18 17:58:20 +00001468implement the \method{__contains__()} method to allow efficient use of
1469the \code{in} operator; for mappings, \code{in} should be equivalent
1470of \method{has_key()}; for sequences, it should search through the
Raymond Hettingere701dcb2003-01-19 13:08:18 +00001471values. It is further recommended that both mappings and sequences
1472implement the \method{__iter__()} method to allow efficient iteration
1473through the container; for mappings, \method{__iter__()} should be
1474the same as \method{iterkeys()}; for sequences, it should iterate
1475through the values.
Fred Drake4856d011999-01-12 04:15:20 +00001476\withsubitem{(mapping object method)}{
1477 \ttindex{keys()}
1478 \ttindex{values()}
1479 \ttindex{items()}
Raymond Hettingere701dcb2003-01-19 13:08:18 +00001480 \ttindex{iterkeys()}
1481 \ttindex{itervalues()}
1482 \ttindex{iteritems()}
Fred Drake4856d011999-01-12 04:15:20 +00001483 \ttindex{has_key()}
1484 \ttindex{get()}
Raymond Hettingere701dcb2003-01-19 13:08:18 +00001485 \ttindex{setdefault()}
1486 \ttindex{pop()}
1487 \ttindex{popitem()}
Fred Drake4856d011999-01-12 04:15:20 +00001488 \ttindex{clear()}
1489 \ttindex{copy()}
Guido van Rossum0dbb4fb2001-04-20 16:50:40 +00001490 \ttindex{update()}
1491 \ttindex{__contains__()}}
Fred Drake4856d011999-01-12 04:15:20 +00001492\withsubitem{(sequence object method)}{
1493 \ttindex{append()}
1494 \ttindex{count()}
Raymond Hettingere701dcb2003-01-19 13:08:18 +00001495 \ttindex{extend()}
Fred Drake4856d011999-01-12 04:15:20 +00001496 \ttindex{index()}
1497 \ttindex{insert()}
1498 \ttindex{pop()}
1499 \ttindex{remove()}
1500 \ttindex{reverse()}
1501 \ttindex{sort()}
1502 \ttindex{__add__()}
1503 \ttindex{__radd__()}
Thomas Wouters12bba852000-08-24 20:06:04 +00001504 \ttindex{__iadd__()}
Fred Drake4856d011999-01-12 04:15:20 +00001505 \ttindex{__mul__()}
Thomas Wouters12bba852000-08-24 20:06:04 +00001506 \ttindex{__rmul__()}
Guido van Rossum0dbb4fb2001-04-20 16:50:40 +00001507 \ttindex{__imul__()}
Raymond Hettingere701dcb2003-01-19 13:08:18 +00001508 \ttindex{__contains__()}
1509 \ttindex{__iter__()}}
Fred Drakeae3e5741999-01-28 23:21:49 +00001510\withsubitem{(numeric object method)}{\ttindex{__coerce__()}}
Fred Drakef6669171998-05-06 19:52:49 +00001511
Fred Drake73921b02001-10-01 16:32:13 +00001512\begin{methoddesc}[container object]{__len__}{self}
Fred Draked82575d1998-08-28 20:03:12 +00001513Called to implement the built-in function
1514\function{len()}\bifuncindex{len}. Should return the length of the
1515object, an integer \code{>=} 0. Also, an object that doesn't define a
1516\method{__nonzero__()} method and whose \method{__len__()} method
1517returns zero is considered to be false in a Boolean context.
Fred Drake1e42d8a1998-11-25 17:58:50 +00001518\withsubitem{(object method)}{\ttindex{__nonzero__()}}
1519\end{methoddesc}
Fred Drakef6669171998-05-06 19:52:49 +00001520
Fred Drake73921b02001-10-01 16:32:13 +00001521\begin{methoddesc}[container object]{__getitem__}{self, key}
Fred Draked82575d1998-08-28 20:03:12 +00001522Called to implement evaluation of \code{\var{self}[\var{key}]}.
Fred Drake31575ce2000-09-21 05:28:26 +00001523For sequence types, the accepted keys should be integers and slice
1524objects.\obindex{slice} Note that
1525the special interpretation of negative indexes (if the class wishes to
Fred Drakef6669171998-05-06 19:52:49 +00001526emulate a sequence type) is up to the \method{__getitem__()} method.
Fred Drake91826ed2000-07-13 04:57:58 +00001527If \var{key} is of an inappropriate type, \exception{TypeError} may be
1528raised; if of a value outside the set of indexes for the sequence
1529(after any special interpretation of negative values),
1530\exception{IndexError} should be raised.
Fred Drake0aa811c2001-10-20 04:24:09 +00001531\note{\keyword{for} loops expect that an
Fred Drake91826ed2000-07-13 04:57:58 +00001532\exception{IndexError} will be raised for illegal indexes to allow
Fred Drake0aa811c2001-10-20 04:24:09 +00001533proper detection of the end of the sequence.}
Fred Drake1e42d8a1998-11-25 17:58:50 +00001534\end{methoddesc}
Fred Drakef6669171998-05-06 19:52:49 +00001535
Fred Drake73921b02001-10-01 16:32:13 +00001536\begin{methoddesc}[container object]{__setitem__}{self, key, value}
Fred Draked82575d1998-08-28 20:03:12 +00001537Called to implement assignment to \code{\var{self}[\var{key}]}. Same
Fred Drake1e42d8a1998-11-25 17:58:50 +00001538note as for \method{__getitem__()}. This should only be implemented
1539for mappings if the objects support changes to the values for keys, or
1540if new keys can be added, or for sequences if elements can be
Fred Drake91826ed2000-07-13 04:57:58 +00001541replaced. The same exceptions should be raised for improper
1542\var{key} values as for the \method{__getitem__()} method.
Fred Drake1e42d8a1998-11-25 17:58:50 +00001543\end{methoddesc}
Fred Drakef6669171998-05-06 19:52:49 +00001544
Fred Drake73921b02001-10-01 16:32:13 +00001545\begin{methoddesc}[container object]{__delitem__}{self, key}
Fred Draked82575d1998-08-28 20:03:12 +00001546Called to implement deletion of \code{\var{self}[\var{key}]}. Same
Fred Drake1e42d8a1998-11-25 17:58:50 +00001547note as for \method{__getitem__()}. This should only be implemented
1548for mappings if the objects support removal of keys, or for sequences
Fred Drake91826ed2000-07-13 04:57:58 +00001549if elements can be removed from the sequence. The same exceptions
1550should be raised for improper \var{key} values as for the
1551\method{__getitem__()} method.
Fred Drake1e42d8a1998-11-25 17:58:50 +00001552\end{methoddesc}
Fred Drakef6669171998-05-06 19:52:49 +00001553
Fred Drake73921b02001-10-01 16:32:13 +00001554\begin{methoddesc}[container object]{__iter__}{self}
1555This method is called when an iterator is required for a container.
1556This method should return a new iterator object that can iterate over
1557all the objects in the container. For mappings, it should iterate
1558over the keys of the container, and should also be made available as
1559the method \method{iterkeys()}.
1560
1561Iterator objects also need to implement this method; they are required
1562to return themselves. For more information on iterator objects, see
1563``\ulink{Iterator Types}{../lib/typeiter.html}'' in the
1564\citetitle[../lib/lib.html]{Python Library Reference}.
1565\end{methoddesc}
1566
1567The membership test operators (\keyword{in} and \keyword{not in}) are
1568normally implemented as an iteration through a sequence. However,
1569container objects can supply the following special method with a more
1570efficient implementation, which also does not require the object be a
1571sequence.
1572
1573\begin{methoddesc}[container object]{__contains__}{self, item}
1574Called to implement membership test operators. Should return true if
1575\var{item} is in \var{self}, false otherwise. For mapping objects,
1576this should consider the keys of the mapping rather than the values or
1577the key-item pairs.
1578\end{methoddesc}
1579
Fred Drakef6669171998-05-06 19:52:49 +00001580
Fred Drake3041b071998-10-21 00:25:32 +00001581\subsection{Additional methods for emulation of sequence types
Fred Drake61c77281998-07-28 19:34:22 +00001582 \label{sequence-methods}}
Guido van Rossum83b2f8a1998-07-23 17:12:46 +00001583
Raymond Hettingere701dcb2003-01-19 13:08:18 +00001584The following optional methods can be defined to further emulate sequence
1585objects. Immutable sequences methods should at most only define
1586\method{__getslice__()}; mutable sequences might define all three
Guido van Rossum83b2f8a1998-07-23 17:12:46 +00001587three methods.
Fred Drakef6669171998-05-06 19:52:49 +00001588
Fred Drake1e42d8a1998-11-25 17:58:50 +00001589\begin{methoddesc}[sequence object]{__getslice__}{self, i, j}
Fred Drakea0073822000-08-18 02:42:14 +00001590\deprecated{2.0}{Support slice objects as parameters to the
1591\method{__getitem__()} method.}
Fred Draked82575d1998-08-28 20:03:12 +00001592Called to implement evaluation of \code{\var{self}[\var{i}:\var{j}]}.
1593The returned object should be of the same type as \var{self}. Note
1594that missing \var{i} or \var{j} in the slice expression are replaced
Fred Drakee15956b2000-04-03 04:51:13 +00001595by zero or \code{sys.maxint}, respectively. If negative indexes are
1596used in the slice, the length of the sequence is added to that index.
1597If the instance does not implement the \method{__len__()} method, an
1598\exception{AttributeError} is raised.
1599No guarantee is made that indexes adjusted this way are not still
1600negative. Indexes which are greater than the length of the sequence
1601are not modified.
Fred Drakea0073822000-08-18 02:42:14 +00001602If no \method{__getslice__()} is found, a slice
Thomas Wouters1d75a792000-08-17 22:37:32 +00001603object is created instead, and passed to \method{__getitem__()} instead.
Fred Drake1e42d8a1998-11-25 17:58:50 +00001604\end{methoddesc}
Fred Drakef6669171998-05-06 19:52:49 +00001605
Fred Drake1e42d8a1998-11-25 17:58:50 +00001606\begin{methoddesc}[sequence object]{__setslice__}{self, i, j, sequence}
Fred Draked82575d1998-08-28 20:03:12 +00001607Called to implement assignment to \code{\var{self}[\var{i}:\var{j}]}.
1608Same notes for \var{i} and \var{j} as for \method{__getslice__()}.
Thomas Wouters1d75a792000-08-17 22:37:32 +00001609
Raymond Hettingere701dcb2003-01-19 13:08:18 +00001610This method is deprecated. If no \method{__setslice__()} is found,
1611or for extended slicing of the form
1612\code{\var{self}[\var{i}:\var{j}:\var{k}]}, a
1613slice object is created, and passed to \method{__setitem__()},
1614instead of \method{__setslice__()} being called.
Fred Drake1e42d8a1998-11-25 17:58:50 +00001615\end{methoddesc}
Fred Drakef6669171998-05-06 19:52:49 +00001616
Fred Drake1e42d8a1998-11-25 17:58:50 +00001617\begin{methoddesc}[sequence object]{__delslice__}{self, i, j}
Fred Draked82575d1998-08-28 20:03:12 +00001618Called to implement deletion of \code{\var{self}[\var{i}:\var{j}]}.
1619Same notes for \var{i} and \var{j} as for \method{__getslice__()}.
Raymond Hettingere701dcb2003-01-19 13:08:18 +00001620This method is deprecated. If no \method{__delslice__()} is found,
1621or for extended slicing of the form
1622\code{\var{self}[\var{i}:\var{j}:\var{k}]}, a
1623slice object is created, and passed to \method{__delitem__()},
1624instead of \method{__delslice__()} being called.
Fred Drake1e42d8a1998-11-25 17:58:50 +00001625\end{methoddesc}
Fred Drakef6669171998-05-06 19:52:49 +00001626
Fred Drakefb8ffe62001-04-13 15:54:41 +00001627Notice that these methods are only invoked when a single slice with a
1628single colon is used, and the slice method is available. For slice
1629operations involving extended slice notation, or in absence of the
1630slice methods, \method{__getitem__()}, \method{__setitem__()} or
1631\method{__delitem__()} is called with a slice object as argument.
Fred Drakef6669171998-05-06 19:52:49 +00001632
Fred Drakef89259782000-09-21 22:27:16 +00001633The following example demonstrate how to make your program or module
1634compatible with earlier versions of Python (assuming that methods
1635\method{__getitem__()}, \method{__setitem__()} and \method{__delitem__()}
1636support slice objects as arguments):
1637
1638\begin{verbatim}
1639class MyClass:
1640 ...
1641 def __getitem__(self, index):
1642 ...
1643 def __setitem__(self, index, value):
1644 ...
1645 def __delitem__(self, index):
1646 ...
1647
1648 if sys.version_info < (2, 0):
1649 # They won't be defined if version is at least 2.0 final
1650
1651 def __getslice__(self, i, j):
1652 return self[max(0, i):max(0, j):]
1653 def __setslice__(self, i, j, seq):
1654 self[max(0, i):max(0, j):] = seq
1655 def __delslice__(self, i, j):
1656 del self[max(0, i):max(0, j):]
1657 ...
1658\end{verbatim}
1659
Raymond Hettingere701dcb2003-01-19 13:08:18 +00001660Note the calls to \function{max()}; these are necessary because of
1661the handling of negative indices before the
Fred Drakef89259782000-09-21 22:27:16 +00001662\method{__*slice__()} methods are called. When negative indexes are
1663used, the \method{__*item__()} methods receive them as provided, but
1664the \method{__*slice__()} methods get a ``cooked'' form of the index
1665values. For each negative index value, the length of the sequence is
1666added to the index before calling the method (which may still result
1667in a negative index); this is the customary handling of negative
1668indexes by the built-in sequence types, and the \method{__*item__()}
1669methods are expected to do this as well. However, since they should
1670already be doing that, negative indexes cannot be passed in; they must
1671be be constrained to the bounds of the sequence before being passed to
1672the \method{__*item__()} methods.
1673Calling \code{max(0, i)} conveniently returns the proper value.
1674
Fred Drake15988fd1999-02-12 18:14:57 +00001675
Fred Drake61c77281998-07-28 19:34:22 +00001676\subsection{Emulating numeric types\label{numeric-types}}
Guido van Rossum83b2f8a1998-07-23 17:12:46 +00001677
1678The following methods can be defined to emulate numeric objects.
1679Methods corresponding to operations that are not supported by the
1680particular kind of number implemented (e.g., bitwise operations for
1681non-integral numbers) should be left undefined.
Fred Drakef6669171998-05-06 19:52:49 +00001682
Fred Drakeb8943701999-05-10 13:43:22 +00001683\begin{methoddesc}[numeric object]{__add__}{self, other}
1684\methodline[numeric object]{__sub__}{self, other}
1685\methodline[numeric object]{__mul__}{self, other}
Fred Drake3e2aca42001-08-14 20:28:08 +00001686\methodline[numeric object]{__floordiv__}{self, other}
Fred Drakeb8943701999-05-10 13:43:22 +00001687\methodline[numeric object]{__mod__}{self, other}
1688\methodline[numeric object]{__divmod__}{self, other}
1689\methodline[numeric object]{__pow__}{self, other\optional{, modulo}}
1690\methodline[numeric object]{__lshift__}{self, other}
1691\methodline[numeric object]{__rshift__}{self, other}
1692\methodline[numeric object]{__and__}{self, other}
1693\methodline[numeric object]{__xor__}{self, other}
1694\methodline[numeric object]{__or__}{self, other}
Fred Drake3e2aca42001-08-14 20:28:08 +00001695These methods are
Guido van Rossum83b2f8a1998-07-23 17:12:46 +00001696called to implement the binary arithmetic operations (\code{+},
Fred Drake3e2aca42001-08-14 20:28:08 +00001697\code{-}, \code{*}, \code{//}, \code{\%},
Fred Draked82575d1998-08-28 20:03:12 +00001698\function{divmod()}\bifuncindex{divmod},
Fred Drakefb8ffe62001-04-13 15:54:41 +00001699\function{pow()}\bifuncindex{pow}, \code{**}, \code{<}\code{<},
1700\code{>}\code{>}, \code{\&}, \code{\^}, \code{|}). For instance, to
1701evaluate the expression \var{x}\code{+}\var{y}, where \var{x} is an
1702instance of a class that has an \method{__add__()} method,
Fred Drake3e2aca42001-08-14 20:28:08 +00001703\code{\var{x}.__add__(\var{y})} is called. The \method{__divmod__()}
1704method should be the equivalent to using \method{__floordiv__()} and
1705\method{__mod__()}; it should not be related to \method{__truediv__()}
1706(described below). Note that
Fred Draked82575d1998-08-28 20:03:12 +00001707\method{__pow__()} should be defined to accept an optional third
1708argument if the ternary version of the built-in
1709\function{pow()}\bifuncindex{pow} function is to be supported.
Fred Drake1e42d8a1998-11-25 17:58:50 +00001710\end{methoddesc}
Guido van Rossum83b2f8a1998-07-23 17:12:46 +00001711
Fred Drake3e2aca42001-08-14 20:28:08 +00001712\begin{methoddesc}[numeric object]{__div__}{self, other}
1713\methodline[numeric object]{__truediv__}{self, other}
1714The division operator (\code{/}) is implemented by these methods. The
1715\method{__truediv__()} method is used when \code{__future__.division}
1716is in effect, otherwise \method{__div__()} is used. If only one of
1717these two methods is defined, the object will not support division in
1718the alternate context; \exception{TypeError} will be raised instead.
1719\end{methoddesc}
1720
Fred Drakeb8943701999-05-10 13:43:22 +00001721\begin{methoddesc}[numeric object]{__radd__}{self, other}
1722\methodline[numeric object]{__rsub__}{self, other}
1723\methodline[numeric object]{__rmul__}{self, other}
1724\methodline[numeric object]{__rdiv__}{self, other}
Raymond Hettinger10cbe8d2002-06-20 06:12:37 +00001725\methodline[numeric object]{__rtruediv__}{self, other}
1726\methodline[numeric object]{__rfloordiv__}{self, other}
Fred Drakeb8943701999-05-10 13:43:22 +00001727\methodline[numeric object]{__rmod__}{self, other}
1728\methodline[numeric object]{__rdivmod__}{self, other}
1729\methodline[numeric object]{__rpow__}{self, other}
1730\methodline[numeric object]{__rlshift__}{self, other}
1731\methodline[numeric object]{__rrshift__}{self, other}
1732\methodline[numeric object]{__rand__}{self, other}
1733\methodline[numeric object]{__rxor__}{self, other}
1734\methodline[numeric object]{__ror__}{self, other}
Fred Drake3e2aca42001-08-14 20:28:08 +00001735These methods are
Guido van Rossum83b2f8a1998-07-23 17:12:46 +00001736called to implement the binary arithmetic operations (\code{+},
Fred Draked82575d1998-08-28 20:03:12 +00001737\code{-}, \code{*}, \code{/}, \code{\%},
1738\function{divmod()}\bifuncindex{divmod},
Fred Drakefb8ffe62001-04-13 15:54:41 +00001739\function{pow()}\bifuncindex{pow}, \code{**}, \code{<}\code{<},
1740\code{>}\code{>}, \code{\&}, \code{\^}, \code{|}) with reflected
1741(swapped) operands. These functions are only called if the left
1742operand does not support the corresponding operation. For instance,
1743to evaluate the expression \var{x}\code{-}\var{y}, where \var{y} is an
1744instance of a class that has an \method{__rsub__()} method,
1745\code{\var{y}.__rsub__(\var{x})} is called. Note that ternary
1746\function{pow()}\bifuncindex{pow} will not try calling
1747\method{__rpow__()} (the coercion rules would become too
Guido van Rossum83b2f8a1998-07-23 17:12:46 +00001748complicated).
Fred Drake1e42d8a1998-11-25 17:58:50 +00001749\end{methoddesc}
Fred Drakef6669171998-05-06 19:52:49 +00001750
Thomas Woutersdc90cc22000-12-11 23:11:51 +00001751\begin{methoddesc}[numeric object]{__iadd__}{self, other}
1752\methodline[numeric object]{__isub__}{self, other}
1753\methodline[numeric object]{__imul__}{self, other}
1754\methodline[numeric object]{__idiv__}{self, other}
Raymond Hettinger10cbe8d2002-06-20 06:12:37 +00001755\methodline[numeric object]{__itruediv__}{self, other}
1756\methodline[numeric object]{__ifloordiv__}{self, other}
1757\methodline[numeric object]{__imod__}{self, other}
Thomas Woutersdc90cc22000-12-11 23:11:51 +00001758\methodline[numeric object]{__ipow__}{self, other\optional{, modulo}}
1759\methodline[numeric object]{__ilshift__}{self, other}
1760\methodline[numeric object]{__irshift__}{self, other}
1761\methodline[numeric object]{__iand__}{self, other}
1762\methodline[numeric object]{__ixor__}{self, other}
1763\methodline[numeric object]{__ior__}{self, other}
Fred Drakefb8ffe62001-04-13 15:54:41 +00001764These methods are called to implement the augmented arithmetic
1765operations (\code{+=}, \code{-=}, \code{*=}, \code{/=}, \code{\%=},
1766\code{**=}, \code{<}\code{<=}, \code{>}\code{>=}, \code{\&=},
1767\code{\^=}, \code{|=}). These methods should attempt to do the
1768operation in-place (modifying \var{self}) and return the result (which
1769could be, but does not have to be, \var{self}). If a specific method
1770is not defined, the augmented operation falls back to the normal
1771methods. For instance, to evaluate the expression
1772\var{x}\code{+=}\var{y}, where \var{x} is an instance of a class that
1773has an \method{__iadd__()} method, \code{\var{x}.__iadd__(\var{y})} is
1774called. If \var{x} is an instance of a class that does not define a
1775\method{__iadd()} method, \code{\var{x}.__add__(\var{y})} and
1776\code{\var{y}.__radd__(\var{x})} are considered, as with the
1777evaluation of \var{x}\code{+}\var{y}.
Thomas Woutersdc90cc22000-12-11 23:11:51 +00001778\end{methoddesc}
1779
Fred Drakeb8943701999-05-10 13:43:22 +00001780\begin{methoddesc}[numeric object]{__neg__}{self}
1781\methodline[numeric object]{__pos__}{self}
1782\methodline[numeric object]{__abs__}{self}
1783\methodline[numeric object]{__invert__}{self}
Fred Drakefb8ffe62001-04-13 15:54:41 +00001784Called to implement the unary arithmetic operations (\code{-},
1785\code{+}, \function{abs()}\bifuncindex{abs} and \code{\~{}}).
Fred Drake1e42d8a1998-11-25 17:58:50 +00001786\end{methoddesc}
Fred Drakef6669171998-05-06 19:52:49 +00001787
Fred Drakeb8943701999-05-10 13:43:22 +00001788\begin{methoddesc}[numeric object]{__complex__}{self}
1789\methodline[numeric object]{__int__}{self}
1790\methodline[numeric object]{__long__}{self}
1791\methodline[numeric object]{__float__}{self}
Fred Draked82575d1998-08-28 20:03:12 +00001792Called to implement the built-in functions
Fred Drake15988fd1999-02-12 18:14:57 +00001793\function{complex()}\bifuncindex{complex},
1794\function{int()}\bifuncindex{int}, \function{long()}\bifuncindex{long},
Fred Draked82575d1998-08-28 20:03:12 +00001795and \function{float()}\bifuncindex{float}. Should return a value of
1796the appropriate type.
Fred Drake1e42d8a1998-11-25 17:58:50 +00001797\end{methoddesc}
Fred Drakef6669171998-05-06 19:52:49 +00001798
Fred Drakeb8943701999-05-10 13:43:22 +00001799\begin{methoddesc}[numeric object]{__oct__}{self}
1800\methodline[numeric object]{__hex__}{self}
Fred Draked82575d1998-08-28 20:03:12 +00001801Called to implement the built-in functions
1802\function{oct()}\bifuncindex{oct} and
1803\function{hex()}\bifuncindex{hex}. Should return a string value.
Fred Drake1e42d8a1998-11-25 17:58:50 +00001804\end{methoddesc}
Fred Drakef6669171998-05-06 19:52:49 +00001805
Fred Drakeb8943701999-05-10 13:43:22 +00001806\begin{methoddesc}[numeric object]{__coerce__}{self, other}
Guido van Rossum83b2f8a1998-07-23 17:12:46 +00001807Called to implement ``mixed-mode'' numeric arithmetic. Should either
Fred Draked82575d1998-08-28 20:03:12 +00001808return a 2-tuple containing \var{self} and \var{other} converted to
Fred Drakeb8943701999-05-10 13:43:22 +00001809a common numeric type, or \code{None} if conversion is impossible. When
Guido van Rossum83b2f8a1998-07-23 17:12:46 +00001810the common type would be the type of \code{other}, it is sufficient to
1811return \code{None}, since the interpreter will also ask the other
1812object to attempt a coercion (but sometimes, if the implementation of
1813the other type cannot be changed, it is useful to do the conversion to
Guido van Rossum92cf95f2002-06-03 19:06:41 +00001814the other type here). A return value of \code{NotImplemented} is
1815equivalent to returning \code{None}.
Fred Drake1e42d8a1998-11-25 17:58:50 +00001816\end{methoddesc}
Guido van Rossum83b2f8a1998-07-23 17:12:46 +00001817
Guido van Rossum92cf95f2002-06-03 19:06:41 +00001818\subsection{Coercion rules\label{coercion-rules}}
1819
1820This section used to document the rules for coercion. As the language
1821has evolved, the coercion rules have become hard to document
1822precisely; documenting what one version of one particular
1823implementation does is undesirable. Instead, here are some informal
1824guidelines regarding coercion. In Python 3.0, coercion will not be
1825supported.
Guido van Rossum83b2f8a1998-07-23 17:12:46 +00001826
1827\begin{itemize}
1828
Guido van Rossum92cf95f2002-06-03 19:06:41 +00001829\item
Guido van Rossum83b2f8a1998-07-23 17:12:46 +00001830
Guido van Rossum92cf95f2002-06-03 19:06:41 +00001831If the left operand of a \% operator is a string or Unicode object, no
1832coercion takes place and the string formatting operation is invoked
1833instead.
Guido van Rossum83b2f8a1998-07-23 17:12:46 +00001834
Guido van Rossum92cf95f2002-06-03 19:06:41 +00001835\item
Guido van Rossum83b2f8a1998-07-23 17:12:46 +00001836
Guido van Rossum92cf95f2002-06-03 19:06:41 +00001837It is no longer recommended to define a coercion operation.
1838Mixed-mode operations on types that don't define coercion pass the
1839original arguments to the operation.
Guido van Rossum83b2f8a1998-07-23 17:12:46 +00001840
Guido van Rossum92cf95f2002-06-03 19:06:41 +00001841\item
Guido van Rossum83b2f8a1998-07-23 17:12:46 +00001842
Fred Drake293dd4b2002-06-04 16:25:57 +00001843New-style classes (those derived from \class{object}) never invoke the
1844\method{__coerce__()} method in response to a binary operator; the only
1845time \method{__coerce__()} is invoked is when the built-in function
1846\function{coerce()} is called.
Guido van Rossum83b2f8a1998-07-23 17:12:46 +00001847
Guido van Rossum92cf95f2002-06-03 19:06:41 +00001848\item
Guido van Rossum83b2f8a1998-07-23 17:12:46 +00001849
Guido van Rossum92cf95f2002-06-03 19:06:41 +00001850For most intents and purposes, an operator that returns
1851\code{NotImplemented} is treated the same as one that is not
1852implemented at all.
Guido van Rossum83b2f8a1998-07-23 17:12:46 +00001853
Guido van Rossum92cf95f2002-06-03 19:06:41 +00001854\item
Guido van Rossum83b2f8a1998-07-23 17:12:46 +00001855
Guido van Rossum92cf95f2002-06-03 19:06:41 +00001856Below, \method{__op__()} and \method{__rop__()} are used to signify
1857the generic method names corresponding to an operator;
1858\method{__iop__} is used for the corresponding in-place operator. For
1859example, for the operator `\code{+}', \method{__add__()} and
1860\method{__radd__()} are used for the left and right variant of the
1861binary operator, and \method{__iadd__} for the in-place variant.
Guido van Rossum83b2f8a1998-07-23 17:12:46 +00001862
Guido van Rossum92cf95f2002-06-03 19:06:41 +00001863\item
Guido van Rossum83b2f8a1998-07-23 17:12:46 +00001864
Guido van Rossum92cf95f2002-06-03 19:06:41 +00001865For objects \var{x} and \var{y}, first \code{\var{x}.__op__(\var{y})}
1866is tried. If this is not implemented or returns \code{NotImplemented},
1867\code{\var{y}.__rop__(\var{x})} is tried. If this is also not
Fred Drake293dd4b2002-06-04 16:25:57 +00001868implemented or returns \code{NotImplemented}, a \exception{TypeError}
Guido van Rossum92cf95f2002-06-03 19:06:41 +00001869exception is raised. But see the following exception:
Guido van Rossum83b2f8a1998-07-23 17:12:46 +00001870
Guido van Rossum92cf95f2002-06-03 19:06:41 +00001871\item
Guido van Rossum83b2f8a1998-07-23 17:12:46 +00001872
Guido van Rossum92cf95f2002-06-03 19:06:41 +00001873Exception to the previous item: if the left operand is an instance of
1874a built-in type or a new-style class, and the right operand is an
1875instance of a proper subclass of that type or class, the right
Fred Drake293dd4b2002-06-04 16:25:57 +00001876operand's \method{__rop__()} method is tried \emph{before} the left
1877operand's \method{__op__()} method. This is done so that a subclass can
Guido van Rossum92cf95f2002-06-03 19:06:41 +00001878completely override binary operators. Otherwise, the left operand's
1879__op__ method would always accept the right operand: when an instance
1880of a given class is expected, an instance of a subclass of that class
1881is always acceptable.
Guido van Rossum83b2f8a1998-07-23 17:12:46 +00001882
Guido van Rossum92cf95f2002-06-03 19:06:41 +00001883\item
Guido van Rossum83b2f8a1998-07-23 17:12:46 +00001884
Guido van Rossum92cf95f2002-06-03 19:06:41 +00001885When either operand type defines a coercion, this coercion is called
Fred Drake293dd4b2002-06-04 16:25:57 +00001886before that type's \method{__op__()} or \method{__rop__()} method is
1887called, but no sooner. If the coercion returns an object of a
1888different type for the operand whose coercion is invoked, part of the
1889process is redone using the new object.
Guido van Rossum83b2f8a1998-07-23 17:12:46 +00001890
Guido van Rossum92cf95f2002-06-03 19:06:41 +00001891\item
Guido van Rossum83b2f8a1998-07-23 17:12:46 +00001892
Guido van Rossum92cf95f2002-06-03 19:06:41 +00001893When an in-place operator (like `\code{+=}') is used, if the left
Fred Drake293dd4b2002-06-04 16:25:57 +00001894operand implements \method{__iop__()}, it is invoked without any
1895coercion. When the operation falls back to \method{__op__()} and/or
1896\method{__rop__()}, the normal coercion rules apply.
Guido van Rossum83b2f8a1998-07-23 17:12:46 +00001897
Guido van Rossum92cf95f2002-06-03 19:06:41 +00001898\item
1899
1900In \var{x}\code{+}\var{y}, if \var{x} is a sequence that implements
1901sequence concatenation, sequence concatenation is invoked.
1902
1903\item
1904
1905In \var{x}\code{*}\var{y}, if one operator is a sequence that
1906implements sequence repetition, and the other is an integer
Fred Drake293dd4b2002-06-04 16:25:57 +00001907(\class{int} or \class{long}), sequence repetition is invoked.
Guido van Rossum92cf95f2002-06-03 19:06:41 +00001908
1909\item
1910
Fred Drake293dd4b2002-06-04 16:25:57 +00001911Rich comparisons (implemented by methods \method{__eq__()} and so on)
Guido van Rossum92cf95f2002-06-03 19:06:41 +00001912never use coercion. Three-way comparison (implemented by
Fred Drake293dd4b2002-06-04 16:25:57 +00001913\method{__cmp__()}) does use coercion under the same conditions as
Guido van Rossum92cf95f2002-06-03 19:06:41 +00001914other binary operations use it.
1915
1916\item
1917
Fred Drake293dd4b2002-06-04 16:25:57 +00001918In the current implementation, the built-in numeric types \class{int},
1919\class{long} and \class{float} do not use coercion; the type
1920\class{complex} however does use it. The difference can become
Guido van Rossum92cf95f2002-06-03 19:06:41 +00001921apparent when subclassing these types. Over time, the type
Fred Drake293dd4b2002-06-04 16:25:57 +00001922\class{complex} may be fixed to avoid coercion. All these types
1923implement a \method{__coerce__()} method, for use by the built-in
1924\function{coerce()} function.
Guido van Rossum83b2f8a1998-07-23 17:12:46 +00001925
1926\end{itemize}