1998-07-28 19:34:22 +00:00
|
|
|
\chapter{Data model\label{datamodel}}
|
1998-05-06 19:52:49 +00:00
|
|
|
|
1998-07-28 19:34:22 +00:00
|
|
|
\section{Objects, values and types\label{objects}}
|
1998-05-06 19:52:49 +00:00
|
|
|
|
|
|
|
\dfn{Objects} are Python's abstraction for data. All data in a Python
|
|
|
|
program is represented by objects or by relations between objects.
|
|
|
|
(In a sense, and in conformance to Von Neumann's model of a
|
1998-07-23 17:12:46 +00:00
|
|
|
``stored program computer,'' code is also represented by objects.)
|
1998-05-06 19:52:49 +00:00
|
|
|
\index{object}
|
|
|
|
\index{data}
|
|
|
|
|
|
|
|
Every object has an identity, a type and a value. An object's
|
|
|
|
\emph{identity} never changes once it has been created; you may think
|
1998-07-23 17:12:46 +00:00
|
|
|
of it as the object's address in memory. The `\code{is}' operator
|
1998-10-01 20:40:43 +00:00
|
|
|
compares the identity of two objects; the
|
|
|
|
\function{id()}\bifuncindex{id} function returns an integer
|
|
|
|
representing its identity (currently implemented as its address).
|
1998-07-23 17:12:46 +00:00
|
|
|
An object's \dfn{type} is
|
1998-05-06 19:52:49 +00:00
|
|
|
also unchangeable. It determines the operations that an object
|
1998-07-23 17:12:46 +00:00
|
|
|
supports (e.g., ``does it have a length?'') and also defines the
|
1998-10-01 20:40:43 +00:00
|
|
|
possible values for objects of that type. The
|
|
|
|
\function{type()}\bifuncindex{type} function returns an object's type
|
|
|
|
(which is an object itself). The \emph{value} of some
|
1998-05-06 19:52:49 +00:00
|
|
|
objects can change. Objects whose value can change are said to be
|
|
|
|
\emph{mutable}; objects whose value is unchangeable once they are
|
1998-07-23 17:12:46 +00:00
|
|
|
created are called \emph{immutable}.
|
1999-02-23 16:40:55 +00:00
|
|
|
(The value of an immutable container object that contains a reference
|
|
|
|
to a mutable object can change when the latter's value is changed;
|
|
|
|
however the container is still considered immutable, because the
|
|
|
|
collection of objects it contains cannot be changed. So, immutability
|
|
|
|
is not strictly the same as having an unchangeable value, it is more
|
|
|
|
subtle.)
|
1998-07-23 17:12:46 +00:00
|
|
|
An object's mutability is determined by its type; for instance,
|
|
|
|
numbers, strings and tuples are immutable, while dictionaries and
|
|
|
|
lists are mutable.
|
1998-05-06 19:52:49 +00:00
|
|
|
\index{identity of an object}
|
|
|
|
\index{value of an object}
|
|
|
|
\index{type of an object}
|
|
|
|
\index{mutable object}
|
|
|
|
\index{immutable object}
|
|
|
|
|
|
|
|
Objects are never explicitly destroyed; however, when they become
|
|
|
|
unreachable they may be garbage-collected. An implementation is
|
1998-08-07 16:33:51 +00:00
|
|
|
allowed to postpone garbage collection or omit it altogether --- it is
|
|
|
|
a matter of implementation quality how garbage collection is
|
1998-05-06 19:52:49 +00:00
|
|
|
implemented, as long as no objects are collected that are still
|
|
|
|
reachable. (Implementation note: the current implementation uses a
|
|
|
|
reference-counting scheme which collects most objects as soon as they
|
|
|
|
become unreachable, but never collects garbage containing circular
|
|
|
|
references.)
|
|
|
|
\index{garbage collection}
|
|
|
|
\index{reference counting}
|
|
|
|
\index{unreachable object}
|
|
|
|
|
|
|
|
Note that the use of the implementation's tracing or debugging
|
|
|
|
facilities may keep objects alive that would normally be collectable.
|
1998-07-23 17:12:46 +00:00
|
|
|
Also note that catching an exception with a
|
1999-01-12 04:15:20 +00:00
|
|
|
`\keyword{try}...\keyword{except}' statement may keep objects alive.
|
1998-05-06 19:52:49 +00:00
|
|
|
|
|
|
|
Some objects contain references to ``external'' resources such as open
|
|
|
|
files or windows. It is understood that these resources are freed
|
|
|
|
when the object is garbage-collected, but since garbage collection is
|
|
|
|
not guaranteed to happen, such objects also provide an explicit way to
|
|
|
|
release the external resource, usually a \method{close()} method.
|
1998-07-23 17:12:46 +00:00
|
|
|
Programs are strongly recommended to explicitly close such
|
1999-01-12 04:15:20 +00:00
|
|
|
objects. The `\keyword{try}...\keyword{finally}' statement provides
|
|
|
|
a convenient way to do this.
|
1998-05-06 19:52:49 +00:00
|
|
|
|
|
|
|
Some objects contain references to other objects; these are called
|
|
|
|
\emph{containers}. Examples of containers are tuples, lists and
|
|
|
|
dictionaries. The references are part of a container's value. In
|
|
|
|
most cases, when we talk about the value of a container, we imply the
|
|
|
|
values, not the identities of the contained objects; however, when we
|
1998-07-23 17:12:46 +00:00
|
|
|
talk about the mutability of a container, only the identities of
|
|
|
|
the immediately contained objects are implied. So, if an immutable
|
|
|
|
container (like a tuple)
|
|
|
|
contains a reference to a mutable object, its value changes
|
|
|
|
if that mutable object is changed.
|
1998-05-06 19:52:49 +00:00
|
|
|
\index{container}
|
|
|
|
|
1998-07-23 17:12:46 +00:00
|
|
|
Types affect almost all aspects of object behavior. Even the importance
|
1998-05-06 19:52:49 +00:00
|
|
|
of object identity is affected in some sense: for immutable types,
|
|
|
|
operations that compute new values may actually return a reference to
|
|
|
|
any existing object with the same type and value, while for mutable
|
1998-07-23 17:12:46 +00:00
|
|
|
objects this is not allowed. E.g., after
|
1998-10-01 20:40:43 +00:00
|
|
|
\samp{a = 1; b = 1},
|
1998-05-06 19:52:49 +00:00
|
|
|
\code{a} and \code{b} may or may not refer to the same object with the
|
1998-07-23 17:12:46 +00:00
|
|
|
value one, depending on the implementation, but after
|
1998-10-01 20:40:43 +00:00
|
|
|
\samp{c = []; d = []}, \code{c} and \code{d}
|
1998-05-06 19:52:49 +00:00
|
|
|
are guaranteed to refer to two different, unique, newly created empty
|
|
|
|
lists.
|
1998-10-01 20:40:43 +00:00
|
|
|
(Note that \samp{c = d = []} assigns the same object to both
|
1998-07-23 17:12:46 +00:00
|
|
|
\code{c} and \code{d}.)
|
1998-05-06 19:52:49 +00:00
|
|
|
|
1998-07-28 19:34:22 +00:00
|
|
|
\section{The standard type hierarchy\label{types}}
|
1998-05-06 19:52:49 +00:00
|
|
|
|
|
|
|
Below is a list of the types that are built into Python. Extension
|
1998-07-23 17:12:46 +00:00
|
|
|
modules written in \C{} can define additional types. Future versions of
|
|
|
|
Python may add types to the type hierarchy (e.g., rational
|
1998-05-06 19:52:49 +00:00
|
|
|
numbers, efficiently stored arrays of integers, etc.).
|
|
|
|
\index{type}
|
|
|
|
\indexii{data}{type}
|
|
|
|
\indexii{type}{hierarchy}
|
|
|
|
\indexii{extension}{module}
|
|
|
|
\indexii{C}{language}
|
|
|
|
|
|
|
|
Some of the type descriptions below contain a paragraph listing
|
1998-07-23 17:12:46 +00:00
|
|
|
`special attributes.' These are attributes that provide access to the
|
1998-05-06 19:52:49 +00:00
|
|
|
implementation and are not intended for general use. Their definition
|
|
|
|
may change in the future. There are also some `generic' special
|
|
|
|
attributes, not listed with the individual objects: \member{__methods__}
|
|
|
|
is a list of the method names of a built-in object, if it has any;
|
|
|
|
\member{__members__} is a list of the data attribute names of a built-in
|
|
|
|
object, if it has any.
|
|
|
|
\index{attribute}
|
|
|
|
\indexii{special}{attribute}
|
|
|
|
\indexiii{generic}{special}{attribute}
|
1999-01-12 04:15:20 +00:00
|
|
|
\withsubitem{(built-in object attribute)}{
|
1998-11-25 17:58:50 +00:00
|
|
|
\ttindex{__methods__}
|
|
|
|
\ttindex{__members__}}
|
1998-05-06 19:52:49 +00:00
|
|
|
|
|
|
|
\begin{description}
|
|
|
|
|
|
|
|
\item[None]
|
|
|
|
This type has a single value. There is a single object with this value.
|
|
|
|
This object is accessed through the built-in name \code{None}.
|
1998-07-23 17:12:46 +00:00
|
|
|
It is used to signify the absence of a value in many situations, e.g.,
|
|
|
|
it is returned from functions that don't explicitly return anything.
|
|
|
|
Its truth value is false.
|
1998-05-06 19:52:49 +00:00
|
|
|
\ttindex{None}
|
1998-11-25 19:09:24 +00:00
|
|
|
\obindex{None@{\texttt{None}}}
|
1998-05-06 19:52:49 +00:00
|
|
|
|
1998-07-23 17:12:46 +00:00
|
|
|
\item[Ellipsis]
|
|
|
|
This type has a single value. There is a single object with this value.
|
|
|
|
This object is accessed through the built-in name \code{Ellipsis}.
|
1998-10-01 20:40:43 +00:00
|
|
|
It is used to indicate the presence of the \samp{...} syntax in a
|
1998-07-23 17:12:46 +00:00
|
|
|
slice. Its truth value is true.
|
|
|
|
\ttindex{Ellipsis}
|
1998-11-25 19:09:24 +00:00
|
|
|
\obindex{Ellipsis@{\texttt{Ellipsis}}}
|
1998-07-23 17:12:46 +00:00
|
|
|
|
1998-05-06 19:52:49 +00:00
|
|
|
\item[Numbers]
|
|
|
|
These are created by numeric literals and returned as results by
|
|
|
|
arithmetic operators and arithmetic built-in functions. Numeric
|
|
|
|
objects are immutable; once created their value never changes. Python
|
|
|
|
numbers are of course strongly related to mathematical numbers, but
|
|
|
|
subject to the limitations of numerical representation in computers.
|
|
|
|
\obindex{numeric}
|
|
|
|
|
|
|
|
Python distinguishes between integers and floating point numbers:
|
|
|
|
|
|
|
|
\begin{description}
|
|
|
|
\item[Integers]
|
|
|
|
These represent elements from the mathematical set of whole numbers.
|
|
|
|
\obindex{integer}
|
|
|
|
|
|
|
|
There are two types of integers:
|
|
|
|
|
|
|
|
\begin{description}
|
|
|
|
|
|
|
|
\item[Plain integers]
|
|
|
|
These represent numbers in the range -2147483648 through 2147483647.
|
|
|
|
(The range may be larger on machines with a larger natural word
|
|
|
|
size, but not smaller.)
|
2000-04-03 04:51:13 +00:00
|
|
|
When the result of an operation would fall outside this range, the
|
1998-05-06 19:52:49 +00:00
|
|
|
exception \exception{OverflowError} is raised.
|
|
|
|
For the purpose of shift and mask operations, integers are assumed to
|
|
|
|
have a binary, 2's complement notation using 32 or more bits, and
|
|
|
|
hiding no bits from the user (i.e., all 4294967296 different bit
|
|
|
|
patterns correspond to different values).
|
|
|
|
\obindex{plain integer}
|
|
|
|
\withsubitem{(built-in exception)}{\ttindex{OverflowError}}
|
|
|
|
|
|
|
|
\item[Long integers]
|
|
|
|
These represent numbers in an unlimited range, subject to available
|
|
|
|
(virtual) memory only. For the purpose of shift and mask operations,
|
|
|
|
a binary representation is assumed, and negative numbers are
|
|
|
|
represented in a variant of 2's complement which gives the illusion of
|
|
|
|
an infinite string of sign bits extending to the left.
|
|
|
|
\obindex{long integer}
|
|
|
|
|
|
|
|
\end{description} % Integers
|
|
|
|
|
|
|
|
The rules for integer representation are intended to give the most
|
|
|
|
meaningful interpretation of shift and mask operations involving
|
|
|
|
negative integers and the least surprises when switching between the
|
|
|
|
plain and long integer domains. For any operation except left shift,
|
|
|
|
if it yields a result in the plain integer domain without causing
|
|
|
|
overflow, it will yield the same result in the long integer domain or
|
|
|
|
when using mixed operands.
|
|
|
|
\indexii{integer}{representation}
|
|
|
|
|
|
|
|
\item[Floating point numbers]
|
|
|
|
These represent machine-level double precision floating point numbers.
|
|
|
|
You are at the mercy of the underlying machine architecture and
|
1998-07-23 17:12:46 +00:00
|
|
|
\C{} implementation for the accepted range and handling of overflow.
|
|
|
|
Python does not support single-precision floating point numbers; the
|
|
|
|
savings in CPU and memory usage that are usually the reason for using
|
|
|
|
these is dwarfed by the overhead of using objects in Python, so there
|
|
|
|
is no reason to complicate the language with two kinds of floating
|
|
|
|
point numbers.
|
1998-05-06 19:52:49 +00:00
|
|
|
\obindex{floating point}
|
|
|
|
\indexii{floating point}{number}
|
|
|
|
\indexii{C}{language}
|
|
|
|
|
1998-07-23 17:12:46 +00:00
|
|
|
\item[Complex numbers]
|
|
|
|
These represent complex numbers as a pair of machine-level double
|
|
|
|
precision floating point numbers. The same caveats apply as for
|
|
|
|
floating point numbers. The real and imaginary value of a complex
|
|
|
|
number \code{z} can be retrieved through the attributes \code{z.real}
|
|
|
|
and \code{z.imag}.
|
|
|
|
\obindex{complex}
|
|
|
|
\indexii{complex}{number}
|
|
|
|
|
1998-05-06 19:52:49 +00:00
|
|
|
\end{description} % Numbers
|
|
|
|
|
|
|
|
\item[Sequences]
|
|
|
|
These represent finite ordered sets indexed by natural numbers.
|
|
|
|
The built-in function \function{len()}\bifuncindex{len} returns the
|
1998-07-23 17:12:46 +00:00
|
|
|
number of items of a sequence.
|
2000-07-16 19:05:38 +00:00
|
|
|
When the length of a sequence is \var{n}, the
|
1998-07-23 17:12:46 +00:00
|
|
|
index set contains the numbers 0, 1, \ldots, \var{n}-1. Item
|
1998-05-06 19:52:49 +00:00
|
|
|
\var{i} of sequence \var{a} is selected by \code{\var{a}[\var{i}]}.
|
2000-04-03 04:51:13 +00:00
|
|
|
\obindex{sequence}
|
1998-05-06 19:52:49 +00:00
|
|
|
\index{index operation}
|
|
|
|
\index{item selection}
|
|
|
|
\index{subscription}
|
|
|
|
|
|
|
|
Sequences also support slicing: \code{\var{a}[\var{i}:\var{j}]}
|
1998-07-23 17:12:46 +00:00
|
|
|
selects all items with index \var{k} such that \var{i} \code{<=}
|
1998-05-06 19:52:49 +00:00
|
|
|
\var{k} \code{<} \var{j}. When used as an expression, a slice is a
|
1998-07-23 17:12:46 +00:00
|
|
|
sequence of the same type. This implies that the index set is
|
|
|
|
renumbered so that it starts at 0.
|
1998-05-06 19:52:49 +00:00
|
|
|
\index{slicing}
|
|
|
|
|
|
|
|
Sequences are distinguished according to their mutability:
|
|
|
|
|
|
|
|
\begin{description}
|
1999-01-12 04:15:20 +00:00
|
|
|
|
1998-05-06 19:52:49 +00:00
|
|
|
\item[Immutable sequences]
|
|
|
|
An object of an immutable sequence type cannot change once it is
|
|
|
|
created. (If the object contains references to other objects,
|
1998-07-23 17:12:46 +00:00
|
|
|
these other objects may be mutable and may be changed; however,
|
1998-05-06 19:52:49 +00:00
|
|
|
the collection of objects directly referenced by an immutable object
|
|
|
|
cannot change.)
|
|
|
|
\obindex{immutable sequence}
|
|
|
|
\obindex{immutable}
|
|
|
|
|
|
|
|
The following types are immutable sequences:
|
|
|
|
|
|
|
|
\begin{description}
|
|
|
|
|
|
|
|
\item[Strings]
|
1998-07-23 17:12:46 +00:00
|
|
|
The items of a string are characters. There is no separate
|
|
|
|
character type; a character is represented by a string of one item.
|
1998-05-06 19:52:49 +00:00
|
|
|
Characters represent (at least) 8-bit bytes. The built-in
|
|
|
|
functions \function{chr()}\bifuncindex{chr} and
|
|
|
|
\function{ord()}\bifuncindex{ord} convert between characters and
|
|
|
|
nonnegative integers representing the byte values. Bytes with the
|
1998-07-23 17:12:46 +00:00
|
|
|
values 0-127 usually represent the corresponding \ASCII{} values, but
|
|
|
|
the interpretation of values is up to the program. The string
|
|
|
|
data type is also used to represent arrays of bytes, e.g., to hold data
|
1998-05-06 19:52:49 +00:00
|
|
|
read from a file.
|
|
|
|
\obindex{string}
|
|
|
|
\index{character}
|
|
|
|
\index{byte}
|
1998-05-14 19:37:06 +00:00
|
|
|
\index{ASCII@\ASCII{}}
|
1998-05-06 19:52:49 +00:00
|
|
|
|
|
|
|
(On systems whose native character set is not \ASCII{}, strings may use
|
|
|
|
EBCDIC in their internal representation, provided the functions
|
|
|
|
\function{chr()} and \function{ord()} implement a mapping between \ASCII{} and
|
|
|
|
EBCDIC, and string comparison preserves the \ASCII{} order.
|
|
|
|
Or perhaps someone can propose a better rule?)
|
1998-05-14 19:37:06 +00:00
|
|
|
\index{ASCII@\ASCII{}}
|
1998-05-06 19:52:49 +00:00
|
|
|
\index{EBCDIC}
|
|
|
|
\index{character set}
|
|
|
|
\indexii{string}{comparison}
|
|
|
|
\bifuncindex{chr}
|
|
|
|
\bifuncindex{ord}
|
|
|
|
|
2000-04-06 13:57:21 +00:00
|
|
|
\item[Unicode]
|
|
|
|
The items of a Unicode object are Unicode characters. A Unicode
|
|
|
|
character is represented by a Unicode object of one item and can hold
|
|
|
|
a 16-bit value representing a Unicode ordinal. The built-in functions
|
|
|
|
\function{unichr()}\bifuncindex{unichr} and
|
|
|
|
\function{ord()}\bifuncindex{ord} convert between characters and
|
|
|
|
nonnegative integers representing the Unicode ordinals as defined in
|
|
|
|
the Unicode Standard 3.0. Conversion from and to other encodings are
|
|
|
|
possible through the Unicode method \method{encode} and the built-in
|
|
|
|
function \function{unicode()}\bifuncindex{unicode}.
|
|
|
|
\obindex{unicode}
|
|
|
|
\index{character}
|
|
|
|
\index{integer}
|
2000-04-06 14:00:14 +00:00
|
|
|
\index{Unicode}
|
2000-04-06 13:57:21 +00:00
|
|
|
|
1998-05-06 19:52:49 +00:00
|
|
|
\item[Tuples]
|
1998-07-23 17:12:46 +00:00
|
|
|
The items of a tuple are arbitrary Python objects.
|
|
|
|
Tuples of two or more items are formed by comma-separated lists
|
|
|
|
of expressions. A tuple of one item (a `singleton') can be formed
|
1998-05-06 19:52:49 +00:00
|
|
|
by affixing a comma to an expression (an expression by itself does
|
|
|
|
not create a tuple, since parentheses must be usable for grouping of
|
1998-07-23 17:12:46 +00:00
|
|
|
expressions). An empty tuple can be formed by an empty pair of
|
1998-05-06 19:52:49 +00:00
|
|
|
parentheses.
|
|
|
|
\obindex{tuple}
|
|
|
|
\indexii{singleton}{tuple}
|
|
|
|
\indexii{empty}{tuple}
|
|
|
|
|
|
|
|
\end{description} % Immutable sequences
|
|
|
|
|
|
|
|
\item[Mutable sequences]
|
|
|
|
Mutable sequences can be changed after they are created. The
|
|
|
|
subscription and slicing notations can be used as the target of
|
|
|
|
assignment and \keyword{del} (delete) statements.
|
2000-07-16 19:05:38 +00:00
|
|
|
\obindex{mutable sequence}
|
1998-05-06 19:52:49 +00:00
|
|
|
\obindex{mutable}
|
|
|
|
\indexii{assignment}{statement}
|
|
|
|
\index{delete}
|
|
|
|
\stindex{del}
|
|
|
|
\index{subscription}
|
|
|
|
\index{slicing}
|
|
|
|
|
|
|
|
There is currently a single mutable sequence type:
|
|
|
|
|
|
|
|
\begin{description}
|
|
|
|
|
|
|
|
\item[Lists]
|
1998-07-23 17:12:46 +00:00
|
|
|
The items of a list are arbitrary Python objects. Lists are formed
|
1998-05-06 19:52:49 +00:00
|
|
|
by placing a comma-separated list of expressions in square brackets.
|
|
|
|
(Note that there are no special cases needed to form lists of length 0
|
|
|
|
or 1.)
|
|
|
|
\obindex{list}
|
|
|
|
|
|
|
|
\end{description} % Mutable sequences
|
|
|
|
|
1998-07-23 17:12:46 +00:00
|
|
|
The extension module \module{array}\refstmodindex{array} provides an
|
|
|
|
additional example of a mutable sequence type.
|
|
|
|
|
|
|
|
|
1998-05-06 19:52:49 +00:00
|
|
|
\end{description} % Sequences
|
|
|
|
|
1998-07-23 17:12:46 +00:00
|
|
|
\item[Mappings]
|
1998-05-06 19:52:49 +00:00
|
|
|
These represent finite sets of objects indexed by arbitrary index sets.
|
1998-07-23 17:12:46 +00:00
|
|
|
The subscript notation \code{a[k]} selects the item indexed
|
1998-05-06 19:52:49 +00:00
|
|
|
by \code{k} from the mapping \code{a}; this can be used in
|
|
|
|
expressions and as the target of assignments or \keyword{del} statements.
|
1998-07-23 17:12:46 +00:00
|
|
|
The built-in function \function{len()} returns the number of items
|
1998-05-06 19:52:49 +00:00
|
|
|
in a mapping.
|
|
|
|
\bifuncindex{len}
|
|
|
|
\index{subscription}
|
|
|
|
\obindex{mapping}
|
|
|
|
|
1998-07-23 17:12:46 +00:00
|
|
|
There is currently a single intrinsic mapping type:
|
1998-05-06 19:52:49 +00:00
|
|
|
|
|
|
|
\begin{description}
|
|
|
|
|
|
|
|
\item[Dictionaries]
|
1999-02-23 18:50:38 +00:00
|
|
|
These\obindex{dictionary} represent finite sets of objects indexed by
|
|
|
|
nearly arbitrary values. The only types of values not acceptable as
|
|
|
|
keys are values containing lists or dictionaries or other mutable
|
|
|
|
types that are compared by value rather than by object identity, the
|
|
|
|
reason being that the efficient implementation of dictionaries
|
|
|
|
requires a key's hash value to remain constant.
|
1998-05-06 19:52:49 +00:00
|
|
|
Numeric types used for keys obey the normal rules for numeric
|
1998-07-23 17:12:46 +00:00
|
|
|
comparison: if two numbers compare equal (e.g., \code{1} and
|
1998-05-06 19:52:49 +00:00
|
|
|
\code{1.0}) then they can be used interchangeably to index the same
|
|
|
|
dictionary entry.
|
|
|
|
|
1999-02-23 18:50:38 +00:00
|
|
|
Dictionaries are \obindex{mutable}mutable; they are created by the
|
|
|
|
\code{\{...\}} notation (see section \ref{dict}, ``Dictionary
|
|
|
|
Displays'').
|
1998-05-06 19:52:49 +00:00
|
|
|
|
1998-07-23 17:12:46 +00:00
|
|
|
The extension modules \module{dbm}\refstmodindex{dbm},
|
|
|
|
\module{gdbm}\refstmodindex{gdbm}, \module{bsddb}\refstmodindex{bsddb}
|
|
|
|
provide additional examples of mapping types.
|
|
|
|
|
1998-05-06 19:52:49 +00:00
|
|
|
\end{description} % Mapping types
|
|
|
|
|
|
|
|
\item[Callable types]
|
1999-02-23 18:50:38 +00:00
|
|
|
These\obindex{callable} are the types to which the function call
|
|
|
|
operation (see section \ref{calls}, ``Calls'') can be applied:
|
1998-05-06 19:52:49 +00:00
|
|
|
\indexii{function}{call}
|
|
|
|
\index{invocation}
|
|
|
|
\indexii{function}{argument}
|
|
|
|
|
|
|
|
\begin{description}
|
|
|
|
|
|
|
|
\item[User-defined functions]
|
|
|
|
A user-defined function object is created by a function definition
|
1998-07-23 17:12:46 +00:00
|
|
|
(see section \ref{function}, ``Function definitions''). It should be
|
|
|
|
called with an argument
|
1998-05-06 19:52:49 +00:00
|
|
|
list containing the same number of items as the function's formal
|
|
|
|
parameter list.
|
|
|
|
\indexii{user-defined}{function}
|
|
|
|
\obindex{function}
|
|
|
|
\obindex{user-defined function}
|
|
|
|
|
1999-02-23 16:40:55 +00:00
|
|
|
Special attributes: \member{func_doc} or \member{__doc__} is the
|
1998-07-23 17:12:46 +00:00
|
|
|
function's documentation string, or None if unavailable;
|
1998-10-01 20:40:43 +00:00
|
|
|
\member{func_name} or \member{__name__} is the function's name;
|
|
|
|
\member{func_defaults} is a tuple containing default argument values for
|
1998-07-23 17:12:46 +00:00
|
|
|
those arguments that have defaults, or \code{None} if no arguments
|
1998-10-01 20:40:43 +00:00
|
|
|
have a default value; \member{func_code} is the code object representing
|
|
|
|
the compiled function body; \member{func_globals} is (a reference to)
|
1998-07-23 17:12:46 +00:00
|
|
|
the dictionary that holds the function's global variables --- it
|
1998-07-23 17:54:36 +00:00
|
|
|
defines the global namespace of the module in which the function was
|
1999-02-23 16:40:55 +00:00
|
|
|
defined.
|
|
|
|
Of these, \member{func_code}, \member{func_defaults} and
|
|
|
|
\member{func_doc} (and this \member{__doc__}) may be writable; the
|
|
|
|
others can never be changed.
|
|
|
|
Additional information about a function's definition can be
|
1998-07-23 17:12:46 +00:00
|
|
|
retrieved from its code object; see the description of internal types
|
|
|
|
below.
|
1999-01-12 04:15:20 +00:00
|
|
|
\withsubitem{(function attribute)}{
|
|
|
|
\ttindex{func_doc}
|
|
|
|
\ttindex{__doc__}
|
|
|
|
\ttindex{__name__}
|
|
|
|
\ttindex{func_defaults}
|
|
|
|
\ttindex{func_code}
|
1998-11-25 17:58:50 +00:00
|
|
|
\ttindex{func_globals}}
|
1998-07-23 17:54:36 +00:00
|
|
|
\indexii{global}{namespace}
|
1998-05-06 19:52:49 +00:00
|
|
|
|
|
|
|
\item[User-defined methods]
|
1998-07-23 17:12:46 +00:00
|
|
|
A user-defined method object combines a class, a class instance (or
|
|
|
|
\code{None}) and a user-defined function.
|
1998-05-06 19:52:49 +00:00
|
|
|
\obindex{method}
|
|
|
|
\obindex{user-defined method}
|
|
|
|
\indexii{user-defined}{method}
|
|
|
|
|
|
|
|
Special read-only attributes: \member{im_self} is the class instance
|
1998-07-23 17:12:46 +00:00
|
|
|
object, \member{im_func} is the function object;
|
1998-10-01 20:40:43 +00:00
|
|
|
\member{im_class} is the class that defined the method (which may be a
|
|
|
|
base class of the class of which \member{im_self} is an instance);
|
|
|
|
\member{__doc__} is the method's documentation (same as
|
|
|
|
\code{im_func.__doc__}); \member{__name__} is the method name (same as
|
1998-07-23 17:12:46 +00:00
|
|
|
\code{im_func.__name__}).
|
1999-01-12 04:15:20 +00:00
|
|
|
\withsubitem{(method attribute)}{
|
|
|
|
\ttindex{im_func}
|
1998-11-25 17:58:50 +00:00
|
|
|
\ttindex{im_self}}
|
1998-07-23 17:12:46 +00:00
|
|
|
|
|
|
|
User-defined method objects are created in two ways: when getting an
|
|
|
|
attribute of a class that is a user-defined function object, or when
|
2000-06-28 20:15:47 +00:00
|
|
|
getting an attribute of a class instance that is a user-defined
|
|
|
|
function object defined by the class of the instance. In the former
|
|
|
|
case (class attribute), the \member{im_self} attribute is \code{None},
|
|
|
|
and the method object is said to be unbound; in the latter case
|
|
|
|
(instance attribute), \method{im_self} is the instance, and the method
|
|
|
|
object is said to be bound. For
|
1998-10-01 20:40:43 +00:00
|
|
|
instance, when \class{C} is a class which contains a definition for a
|
|
|
|
function \method{f()}, \code{C.f} does not yield the function object
|
1998-07-23 17:12:46 +00:00
|
|
|
\code{f}; rather, it yields an unbound method object \code{m} where
|
1998-10-01 20:40:43 +00:00
|
|
|
\code{m.im_class} is \class{C}, \code{m.im_func} is \method{f()}, and
|
|
|
|
\code{m.im_self} is \code{None}. When \code{x} is a \class{C}
|
1998-07-23 17:12:46 +00:00
|
|
|
instance, \code{x.f} yields a bound method object \code{m} where
|
1998-10-01 20:40:43 +00:00
|
|
|
\code{m.im_class} is \code{C}, \code{m.im_func} is \method{f()}, and
|
1998-07-23 17:12:46 +00:00
|
|
|
\code{m.im_self} is \code{x}.
|
1999-01-12 04:15:20 +00:00
|
|
|
\withsubitem{(method attribute)}{
|
2000-06-28 20:15:47 +00:00
|
|
|
\ttindex{im_class}\ttindex{im_func}\ttindex{im_self}}
|
1998-07-23 17:12:46 +00:00
|
|
|
|
|
|
|
When an unbound user-defined method object is called, the underlying
|
1998-10-01 20:40:43 +00:00
|
|
|
function (\member{im_func}) is called, with the restriction that the
|
1998-07-23 17:12:46 +00:00
|
|
|
first argument must be an instance of the proper class
|
1998-10-01 20:40:43 +00:00
|
|
|
(\member{im_class}) or of a derived class thereof.
|
1998-07-23 17:12:46 +00:00
|
|
|
|
|
|
|
When a bound user-defined method object is called, the underlying
|
1998-10-01 20:40:43 +00:00
|
|
|
function (\member{im_func}) is called, inserting the class instance
|
|
|
|
(\member{im_self}) in front of the argument list. For instance, when
|
|
|
|
\class{C} is a class which contains a definition for a function
|
|
|
|
\method{f()}, and \code{x} is an instance of \class{C}, calling
|
1998-07-23 17:12:46 +00:00
|
|
|
\code{x.f(1)} is equivalent to calling \code{C.f(x, 1)}.
|
|
|
|
|
|
|
|
Note that the transformation from function object to (unbound or
|
|
|
|
bound) method object happens each time the attribute is retrieved from
|
|
|
|
the class or instance. In some cases, a fruitful optimization is to
|
|
|
|
assign the attribute to a local variable and call that local variable.
|
|
|
|
Also notice that this transformation only happens for user-defined
|
|
|
|
functions; other callable objects (and all non-callable objects) are
|
2000-06-28 20:15:47 +00:00
|
|
|
retrieved without transformation. It is also important to note that
|
|
|
|
user-defined functions which are attributes of a class instance are
|
|
|
|
not converted to bound methods; this \emph{only} happens when the
|
|
|
|
function is an attribute of the class.
|
1998-07-23 17:12:46 +00:00
|
|
|
|
1998-05-06 19:52:49 +00:00
|
|
|
\item[Built-in functions]
|
1998-07-23 17:12:46 +00:00
|
|
|
A built-in function object is a wrapper around a \C{} function. Examples
|
|
|
|
of built-in functions are \function{len()} and \function{math.sin()}
|
|
|
|
(\module{math} is a standard built-in module).
|
|
|
|
The number and type of the arguments are
|
1998-05-06 19:52:49 +00:00
|
|
|
determined by the C function.
|
1998-10-01 20:40:43 +00:00
|
|
|
Special read-only attributes: \member{__doc__} is the function's
|
|
|
|
documentation string, or \code{None} if unavailable; \member{__name__}
|
|
|
|
is the function's name; \member{__self__} is set to \code{None} (but see
|
1998-07-23 17:12:46 +00:00
|
|
|
the next item).
|
1998-05-06 19:52:49 +00:00
|
|
|
\obindex{built-in function}
|
|
|
|
\obindex{function}
|
|
|
|
\indexii{C}{language}
|
|
|
|
|
|
|
|
\item[Built-in methods]
|
|
|
|
This is really a different disguise of a built-in function, this time
|
|
|
|
containing an object passed to the \C{} function as an implicit extra
|
1998-07-23 17:12:46 +00:00
|
|
|
argument. An example of a built-in method is
|
|
|
|
\code{\var{list}.append()}, assuming
|
1998-05-06 19:52:49 +00:00
|
|
|
\var{list} is a list object.
|
1998-10-01 20:40:43 +00:00
|
|
|
In this case, the special read-only attribute \member{__self__} is set
|
1998-07-23 17:12:46 +00:00
|
|
|
to the object denoted by \code{list}.
|
1998-05-06 19:52:49 +00:00
|
|
|
\obindex{built-in method}
|
|
|
|
\obindex{method}
|
|
|
|
\indexii{built-in}{method}
|
|
|
|
|
|
|
|
\item[Classes]
|
1998-07-23 17:12:46 +00:00
|
|
|
Class objects are described below. When a class object is called,
|
|
|
|
a new class instance (also described below) is created and
|
1998-05-06 19:52:49 +00:00
|
|
|
returned. This implies a call to the class's \method{__init__()} method
|
|
|
|
if it has one. Any arguments are passed on to the \method{__init__()}
|
1998-07-23 17:12:46 +00:00
|
|
|
method. If there is no \method{__init__()} method, the class must be called
|
1998-05-06 19:52:49 +00:00
|
|
|
without arguments.
|
1998-11-25 17:58:50 +00:00
|
|
|
\withsubitem{(object method)}{\ttindex{__init__()}}
|
1998-05-06 19:52:49 +00:00
|
|
|
\obindex{class}
|
|
|
|
\obindex{class instance}
|
|
|
|
\obindex{instance}
|
|
|
|
\indexii{class object}{call}
|
|
|
|
|
1998-07-23 17:12:46 +00:00
|
|
|
\item[Class instances]
|
|
|
|
Class instances are described below. Class instances are callable
|
1998-10-01 20:40:43 +00:00
|
|
|
only when the class has a \method{__call__()} method; \code{x(arguments)}
|
1998-07-23 17:12:46 +00:00
|
|
|
is a shorthand for \code{x.__call__(arguments)}.
|
|
|
|
|
1998-05-06 19:52:49 +00:00
|
|
|
\end{description}
|
|
|
|
|
|
|
|
\item[Modules]
|
|
|
|
Modules are imported by the \keyword{import} statement (see section
|
1998-07-23 17:12:46 +00:00
|
|
|
\ref{import}, ``The \keyword{import} statement'').
|
1998-07-23 17:54:36 +00:00
|
|
|
A module object has a namespace implemented by a dictionary object
|
1998-07-23 17:12:46 +00:00
|
|
|
(this is the dictionary referenced by the func_globals attribute of
|
|
|
|
functions defined in the module). Attribute references are translated
|
|
|
|
to lookups in this dictionary, e.g., \code{m.x} is equivalent to
|
|
|
|
\code{m.__dict__["x"]}.
|
|
|
|
A module object does not contain the code object used to
|
1998-05-06 19:52:49 +00:00
|
|
|
initialize the module (since it isn't needed once the initialization
|
|
|
|
is done).
|
|
|
|
\stindex{import}
|
|
|
|
\obindex{module}
|
|
|
|
|
1998-07-23 17:54:36 +00:00
|
|
|
Attribute assignment updates the module's namespace dictionary,
|
1998-10-01 20:40:43 +00:00
|
|
|
e.g., \samp{m.x = 1} is equivalent to \samp{m.__dict__["x"] = 1}.
|
1998-05-06 19:52:49 +00:00
|
|
|
|
1998-07-23 17:54:36 +00:00
|
|
|
Special read-only attribute: \member{__dict__} is the module's
|
|
|
|
namespace as a dictionary object.
|
1998-11-25 17:58:50 +00:00
|
|
|
\withsubitem{(module attribute)}{\ttindex{__dict__}}
|
1998-07-23 17:12:46 +00:00
|
|
|
|
|
|
|
Predefined (writable) attributes: \member{__name__}
|
|
|
|
is the module's name; \member{__doc__} is the
|
|
|
|
module's documentation string, or
|
1998-10-01 20:40:43 +00:00
|
|
|
\code{None} if unavailable; \member{__file__} is the pathname of the
|
1998-07-23 17:12:46 +00:00
|
|
|
file from which the module was loaded, if it was loaded from a file.
|
1998-10-01 20:40:43 +00:00
|
|
|
The \member{__file__} attribute is not present for C{} modules that are
|
1998-07-23 17:12:46 +00:00
|
|
|
statically linked into the interpreter; for extension modules loaded
|
|
|
|
dynamically from a shared library, it is the pathname of the shared
|
|
|
|
library file.
|
1999-01-12 04:15:20 +00:00
|
|
|
\withsubitem{(module attribute)}{
|
|
|
|
\ttindex{__name__}
|
|
|
|
\ttindex{__doc__}
|
1998-11-25 17:58:50 +00:00
|
|
|
\ttindex{__file__}}
|
1998-07-23 17:54:36 +00:00
|
|
|
\indexii{module}{namespace}
|
1998-05-06 19:52:49 +00:00
|
|
|
|
|
|
|
\item[Classes]
|
|
|
|
Class objects are created by class definitions (see section
|
1998-07-23 17:12:46 +00:00
|
|
|
\ref{class}, ``Class definitions'').
|
|
|
|
A class has a namespace implemented by a dictionary object.
|
|
|
|
Class attribute references are translated to
|
|
|
|
lookups in this dictionary,
|
1998-10-01 20:40:43 +00:00
|
|
|
e.g., \samp{C.x} is translated to \samp{C.__dict__["x"]}.
|
1998-07-23 17:12:46 +00:00
|
|
|
When the attribute name is not found
|
1998-05-06 19:52:49 +00:00
|
|
|
there, the attribute search continues in the base classes. The search
|
1998-07-23 17:12:46 +00:00
|
|
|
is depth-first, left-to-right in the order of occurrence in the
|
1998-05-06 19:52:49 +00:00
|
|
|
base class list.
|
1998-07-23 17:12:46 +00:00
|
|
|
When a class attribute reference would yield a user-defined function
|
|
|
|
object, it is transformed into an unbound user-defined method object
|
1998-10-01 20:40:43 +00:00
|
|
|
(see above). The \member{im_class} attribute of this method object is the
|
1998-07-23 17:12:46 +00:00
|
|
|
class in which the function object was found, not necessarily the
|
|
|
|
class for which the attribute reference was initiated.
|
1998-05-06 19:52:49 +00:00
|
|
|
\obindex{class}
|
|
|
|
\obindex{class instance}
|
|
|
|
\obindex{instance}
|
|
|
|
\indexii{class object}{call}
|
|
|
|
\index{container}
|
|
|
|
\obindex{dictionary}
|
|
|
|
\indexii{class}{attribute}
|
|
|
|
|
|
|
|
Class attribute assignments update the class's dictionary, never the
|
|
|
|
dictionary of a base class.
|
|
|
|
\indexiii{class}{attribute}{assignment}
|
|
|
|
|
1998-07-23 17:12:46 +00:00
|
|
|
A class object can be called (see above) to yield a class instance (see
|
|
|
|
below).
|
1998-05-06 19:52:49 +00:00
|
|
|
\indexii{class object}{call}
|
|
|
|
|
1998-07-23 17:12:46 +00:00
|
|
|
Special attributes: \member{__name__} is the class name;
|
|
|
|
\member{__module__} is the module name in which the class was defined;
|
1998-07-23 17:54:36 +00:00
|
|
|
\member{__dict__} is the dictionary containing the class's namespace;
|
1998-07-23 17:12:46 +00:00
|
|
|
\member{__bases__} is a tuple (possibly empty or a singleton)
|
|
|
|
containing the base classes, in the order of their occurrence in the
|
1998-10-01 20:40:43 +00:00
|
|
|
base class list; \member{__doc__} is the class's documentation string,
|
1998-07-23 17:12:46 +00:00
|
|
|
or None if undefined.
|
1999-01-12 04:15:20 +00:00
|
|
|
\withsubitem{(class attribute)}{
|
|
|
|
\ttindex{__name__}
|
|
|
|
\ttindex{__module__}
|
|
|
|
\ttindex{__dict__}
|
|
|
|
\ttindex{__bases__}
|
1998-11-25 17:58:50 +00:00
|
|
|
\ttindex{__doc__}}
|
1998-05-06 19:52:49 +00:00
|
|
|
|
|
|
|
\item[Class instances]
|
1998-07-23 17:12:46 +00:00
|
|
|
A class instance is created by calling a class object (see above).
|
|
|
|
A class instance has a namespace implemented as a dictionary which
|
|
|
|
is the first place in which
|
1998-05-06 19:52:49 +00:00
|
|
|
attribute references are searched. When an attribute is not found
|
1998-07-23 17:12:46 +00:00
|
|
|
there, and the instance's class has an attribute by that name,
|
|
|
|
the search continues with the class attributes. If a class attribute
|
|
|
|
is found that is a user-defined function object (and in no other
|
|
|
|
case), it is transformed into an unbound user-defined method object
|
1998-10-01 20:40:43 +00:00
|
|
|
(see above). The \member{im_class} attribute of this method object is
|
1998-07-23 17:12:46 +00:00
|
|
|
the class in which the function object was found, not necessarily the
|
|
|
|
class of the instance for which the attribute reference was initiated.
|
|
|
|
If no class attribute is found, and the object's class has a
|
1998-10-01 20:40:43 +00:00
|
|
|
\method{__getattr__()} method, that is called to satisfy the lookup.
|
1998-05-06 19:52:49 +00:00
|
|
|
\obindex{class instance}
|
|
|
|
\obindex{instance}
|
|
|
|
\indexii{class}{instance}
|
|
|
|
\indexii{class instance}{attribute}
|
|
|
|
|
1998-07-23 17:12:46 +00:00
|
|
|
Attribute assignments and deletions update the instance's dictionary,
|
1998-10-01 20:40:43 +00:00
|
|
|
never a class's dictionary. If the class has a \method{__setattr__()} or
|
|
|
|
\method{__delattr__()} method, this is called instead of updating the
|
1998-07-23 17:12:46 +00:00
|
|
|
instance dictionary directly.
|
1998-05-06 19:52:49 +00:00
|
|
|
\indexiii{class instance}{attribute}{assignment}
|
|
|
|
|
|
|
|
Class instances can pretend to be numbers, sequences, or mappings if
|
1998-07-23 17:12:46 +00:00
|
|
|
they have methods with certain special names. See
|
|
|
|
section \ref{specialnames}, ``Special method names.''
|
2000-04-03 04:51:13 +00:00
|
|
|
\obindex{numeric}
|
1998-05-06 19:52:49 +00:00
|
|
|
\obindex{sequence}
|
|
|
|
\obindex{mapping}
|
|
|
|
|
1998-07-23 17:12:46 +00:00
|
|
|
Special attributes: \member{__dict__} is the attribute
|
|
|
|
dictionary; \member{__class__} is the instance's class.
|
1999-01-12 04:15:20 +00:00
|
|
|
\withsubitem{(instance attribute)}{
|
|
|
|
\ttindex{__dict__}
|
1998-11-25 17:58:50 +00:00
|
|
|
\ttindex{__class__}}
|
1998-05-06 19:52:49 +00:00
|
|
|
|
|
|
|
\item[Files]
|
1999-11-10 16:13:25 +00:00
|
|
|
A file\obindex{file} object represents an open file. File objects are
|
|
|
|
created by the \function{open()}\bifuncindex{open} built-in function,
|
|
|
|
and also by
|
|
|
|
\withsubitem{(in module os)}{\ttindex{popen()}}\function{os.popen()},
|
|
|
|
\function{os.fdopen()}, and the
|
|
|
|
\method{makefile()}\withsubitem{(socket method)}{\ttindex{makefile()}}
|
|
|
|
method of socket objects (and perhaps by other functions or methods
|
|
|
|
provided by extension modules). The objects
|
|
|
|
\ttindex{sys.stdin}\code{sys.stdin},
|
|
|
|
\ttindex{sys.stdout}\code{sys.stdout} and
|
|
|
|
\ttindex{sys.stderr}\code{sys.stderr} are initialized to file objects
|
|
|
|
corresponding to the interpreter's standard\index{stdio} input, output
|
|
|
|
and error streams. See the \citetitle[../lib/lib.html]{Python Library
|
|
|
|
Reference} for complete documentation of file objects.
|
1999-01-12 04:15:20 +00:00
|
|
|
\withsubitem{(in module sys)}{
|
|
|
|
\ttindex{stdin}
|
|
|
|
\ttindex{stdout}
|
1998-11-25 17:58:50 +00:00
|
|
|
\ttindex{stderr}}
|
1999-11-10 16:13:25 +00:00
|
|
|
|
1998-05-06 19:52:49 +00:00
|
|
|
|
|
|
|
\item[Internal types]
|
|
|
|
A few types used internally by the interpreter are exposed to the user.
|
1998-07-23 17:12:46 +00:00
|
|
|
Their definitions may change with future versions of the interpreter,
|
1998-05-06 19:52:49 +00:00
|
|
|
but they are mentioned here for completeness.
|
|
|
|
\index{internal type}
|
|
|
|
\index{types, internal}
|
|
|
|
|
|
|
|
\begin{description}
|
|
|
|
|
|
|
|
\item[Code objects]
|
1998-07-23 17:12:46 +00:00
|
|
|
Code objects represent \emph{byte-compiled} executable Python code, or
|
|
|
|
\emph{bytecode}.
|
1998-05-06 19:52:49 +00:00
|
|
|
The difference between a code
|
|
|
|
object and a function object is that the function object contains an
|
1998-07-23 17:12:46 +00:00
|
|
|
explicit reference to the function's globals (the module in which it
|
|
|
|
was defined), while a code object contains no context;
|
|
|
|
also the default argument values are stored in the function object,
|
|
|
|
not in the code object (because they represent values calculated at
|
|
|
|
run-time). Unlike function objects, code objects are immutable and
|
|
|
|
contain no references (directly or indirectly) to mutable objects.
|
|
|
|
\index{bytecode}
|
1998-05-06 19:52:49 +00:00
|
|
|
\obindex{code}
|
|
|
|
|
1998-11-25 17:58:50 +00:00
|
|
|
Special read-only attributes: \member{co_name} gives the function
|
|
|
|
name; \member{co_argcount} is the number of positional arguments
|
|
|
|
(including arguments with default values); \member{co_nlocals} is the
|
|
|
|
number of local variables used by the function (including arguments);
|
|
|
|
\member{co_varnames} is a tuple containing the names of the local
|
|
|
|
variables (starting with the argument names); \member{co_code} is a
|
|
|
|
string representing the sequence of bytecode instructions;
|
|
|
|
\member{co_consts} is a tuple containing the literals used by the
|
|
|
|
bytecode; \member{co_names} is a tuple containing the names used by
|
|
|
|
the bytecode; \member{co_filename} is the filename from which the code
|
|
|
|
was compiled; \member{co_firstlineno} is the first line number of the
|
|
|
|
function; \member{co_lnotab} is a string encoding the mapping from
|
2000-07-16 19:05:38 +00:00
|
|
|
byte code offsets to line numbers (for details see the source code of
|
1998-11-25 17:58:50 +00:00
|
|
|
the interpreter); \member{co_stacksize} is the required stack size
|
|
|
|
(including local variables); \member{co_flags} is an integer encoding
|
|
|
|
a number of flags for the interpreter.
|
1999-01-12 04:15:20 +00:00
|
|
|
\withsubitem{(code object attribute)}{
|
|
|
|
\ttindex{co_argcount}
|
|
|
|
\ttindex{co_code}
|
|
|
|
\ttindex{co_consts}
|
|
|
|
\ttindex{co_filename}
|
|
|
|
\ttindex{co_firstlineno}
|
|
|
|
\ttindex{co_flags}
|
|
|
|
\ttindex{co_lnotab}
|
|
|
|
\ttindex{co_name}
|
|
|
|
\ttindex{co_names}
|
|
|
|
\ttindex{co_nlocals}
|
|
|
|
\ttindex{co_stacksize}
|
1998-11-25 17:58:50 +00:00
|
|
|
\ttindex{co_varnames}}
|
1998-07-23 17:12:46 +00:00
|
|
|
|
2000-04-03 04:51:13 +00:00
|
|
|
The following flag bits are defined for \member{co_flags}: bit
|
|
|
|
\code{0x04} is set if the function uses the \samp{*arguments} syntax
|
|
|
|
to accept an arbitrary number of positional arguments; bit
|
|
|
|
\code{0x08} is set if the function uses the \samp{**keywords} syntax
|
|
|
|
to accept arbitrary keyword arguments; other bits are used internally
|
|
|
|
or reserved for future use. If\index{documentation string} a code
|
|
|
|
object represents a function, the first item in \member{co_consts} is
|
|
|
|
the documentation string of the function, or \code{None} if undefined.
|
1998-05-06 19:52:49 +00:00
|
|
|
|
|
|
|
\item[Frame objects]
|
|
|
|
Frame objects represent execution frames. They may occur in traceback
|
|
|
|
objects (see below).
|
|
|
|
\obindex{frame}
|
|
|
|
|
|
|
|
Special read-only attributes: \member{f_back} is to the previous
|
|
|
|
stack frame (towards the caller), or \code{None} if this is the bottom
|
|
|
|
stack frame; \member{f_code} is the code object being executed in this
|
1998-07-23 17:12:46 +00:00
|
|
|
frame; \member{f_locals} is the dictionary used to look up local
|
|
|
|
variables; \member{f_globals} is used for global variables;
|
1998-10-01 20:40:43 +00:00
|
|
|
\member{f_builtins} is used for built-in (intrinsic) names;
|
|
|
|
\member{f_restricted} is a flag indicating whether the function is
|
1998-07-23 17:12:46 +00:00
|
|
|
executing in restricted execution mode;
|
1998-05-06 19:52:49 +00:00
|
|
|
\member{f_lineno} gives the line number and \member{f_lasti} gives the
|
1998-07-23 17:12:46 +00:00
|
|
|
precise instruction (this is an index into the bytecode string of
|
1998-05-06 19:52:49 +00:00
|
|
|
the code object).
|
1999-01-12 04:15:20 +00:00
|
|
|
\withsubitem{(frame attribute)}{
|
|
|
|
\ttindex{f_back}
|
|
|
|
\ttindex{f_code}
|
|
|
|
\ttindex{f_globals}
|
|
|
|
\ttindex{f_locals}
|
|
|
|
\ttindex{f_lineno}
|
|
|
|
\ttindex{f_lasti}
|
|
|
|
\ttindex{f_builtins}
|
1998-11-25 17:58:50 +00:00
|
|
|
\ttindex{f_restricted}}
|
1998-07-23 17:12:46 +00:00
|
|
|
|
1998-10-01 20:40:43 +00:00
|
|
|
Special writable attributes: \member{f_trace}, if not \code{None}, is a
|
1998-07-23 17:12:46 +00:00
|
|
|
function called at the start of each source code line (this is used by
|
1998-10-01 20:40:43 +00:00
|
|
|
the debugger); \member{f_exc_type}, \member{f_exc_value},
|
|
|
|
\member{f_exc_traceback} represent the most recent exception caught in
|
1998-07-23 17:12:46 +00:00
|
|
|
this frame.
|
1999-01-12 04:15:20 +00:00
|
|
|
\withsubitem{(frame attribute)}{
|
|
|
|
\ttindex{f_trace}
|
|
|
|
\ttindex{f_exc_type}
|
|
|
|
\ttindex{f_exc_value}
|
1998-11-25 17:58:50 +00:00
|
|
|
\ttindex{f_exc_traceback}}
|
1998-05-06 19:52:49 +00:00
|
|
|
|
|
|
|
\item[Traceback objects] \label{traceback}
|
|
|
|
Traceback objects represent a stack trace of an exception. A
|
|
|
|
traceback object is created when an exception occurs. When the search
|
|
|
|
for an exception handler unwinds the execution stack, at each unwound
|
|
|
|
level a traceback object is inserted in front of the current
|
1998-07-23 17:12:46 +00:00
|
|
|
traceback. When an exception handler is entered, the stack trace is
|
|
|
|
made available to the program.
|
|
|
|
(See section \ref{try}, ``The \code{try} statement.'')
|
|
|
|
It is accessible as \code{sys.exc_traceback}, and also as the third
|
|
|
|
item of the tuple returned by \code{sys.exc_info()}. The latter is
|
|
|
|
the preferred interface, since it works correctly when the program is
|
|
|
|
using multiple threads.
|
|
|
|
When the program contains no suitable handler, the stack trace is written
|
1998-05-06 19:52:49 +00:00
|
|
|
(nicely formatted) to the standard error stream; if the interpreter is
|
|
|
|
interactive, it is also made available to the user as
|
|
|
|
\code{sys.last_traceback}.
|
|
|
|
\obindex{traceback}
|
|
|
|
\indexii{stack}{trace}
|
|
|
|
\indexii{exception}{handler}
|
|
|
|
\indexii{execution}{stack}
|
1999-01-12 04:15:20 +00:00
|
|
|
\withsubitem{(in module sys)}{
|
|
|
|
\ttindex{exc_info}
|
|
|
|
\ttindex{exc_traceback}
|
1998-11-25 17:58:50 +00:00
|
|
|
\ttindex{last_traceback}}
|
1998-07-23 17:12:46 +00:00
|
|
|
\ttindex{sys.exc_info}
|
1998-05-06 19:52:49 +00:00
|
|
|
\ttindex{sys.exc_traceback}
|
|
|
|
\ttindex{sys.last_traceback}
|
|
|
|
|
|
|
|
Special read-only attributes: \member{tb_next} is the next level in the
|
|
|
|
stack trace (towards the frame where the exception occurred), or
|
|
|
|
\code{None} if there is no next level; \member{tb_frame} points to the
|
|
|
|
execution frame of the current level; \member{tb_lineno} gives the line
|
|
|
|
number where the exception occurred; \member{tb_lasti} indicates the
|
|
|
|
precise instruction. The line number and last instruction in the
|
|
|
|
traceback may differ from the line number of its frame object if the
|
|
|
|
exception occurred in a \keyword{try} statement with no matching
|
|
|
|
except clause or with a finally clause.
|
1999-01-12 04:15:20 +00:00
|
|
|
\withsubitem{(traceback attribute)}{
|
|
|
|
\ttindex{tb_next}
|
|
|
|
\ttindex{tb_frame}
|
|
|
|
\ttindex{tb_lineno}
|
1998-11-25 17:58:50 +00:00
|
|
|
\ttindex{tb_lasti}}
|
1998-05-06 19:52:49 +00:00
|
|
|
\stindex{try}
|
|
|
|
|
1998-07-23 17:12:46 +00:00
|
|
|
\item[Slice objects]
|
|
|
|
Slice objects are used to represent slices when \emph{extended slice
|
|
|
|
syntax} is used. This is a slice using two colons, or multiple slices
|
|
|
|
or ellipses separated by commas, e.g., \code{a[i:j:step]}, \code{a[i:j,
|
|
|
|
k:l]}, or \code{a[..., i:j])}. They are also created by the built-in
|
1998-11-25 17:58:50 +00:00
|
|
|
\function{slice()}\bifuncindex{slice} function.
|
1998-07-23 17:12:46 +00:00
|
|
|
|
2000-07-16 19:05:38 +00:00
|
|
|
Special read-only attributes: \member{start} is the lower bound;
|
|
|
|
\member{stop} is the upper bound; \member{step} is the step value; each is
|
1998-07-23 17:12:46 +00:00
|
|
|
\code{None} if omitted. These attributes can have any type.
|
1999-01-12 04:15:20 +00:00
|
|
|
\withsubitem{(slice object attribute)}{
|
|
|
|
\ttindex{start}
|
|
|
|
\ttindex{stop}
|
1998-11-25 17:58:50 +00:00
|
|
|
\ttindex{step}}
|
1998-07-23 17:12:46 +00:00
|
|
|
|
1998-05-06 19:52:49 +00:00
|
|
|
\end{description} % Internal types
|
|
|
|
|
|
|
|
\end{description} % Types
|
|
|
|
|
|
|
|
|
1998-07-28 19:34:22 +00:00
|
|
|
\section{Special method names\label{specialnames}}
|
1998-05-06 19:52:49 +00:00
|
|
|
|
|
|
|
A class can implement certain operations that are invoked by special
|
1998-08-28 20:03:12 +00:00
|
|
|
syntax (such as arithmetic operations or subscripting and slicing) by
|
|
|
|
defining methods with special names. For instance, if a class defines
|
|
|
|
a method named \method{__getitem__()}, and \code{x} is an instance of
|
|
|
|
this class, then \code{x[i]} is equivalent to
|
|
|
|
\code{x.__getitem__(i)}. (The reverse is not true --- if \code{x} is
|
|
|
|
a list object, \code{x.__getitem__(i)} is not equivalent to
|
|
|
|
\code{x[i]}.) Except where mentioned, attempts to execute an
|
1998-05-06 19:52:49 +00:00
|
|
|
operation raise an exception when no appropriate method is defined.
|
1998-11-25 17:58:50 +00:00
|
|
|
\withsubitem{(mapping object method)}{\ttindex{__getitem__()}}
|
1998-05-06 19:52:49 +00:00
|
|
|
|
|
|
|
|
1998-07-28 19:34:22 +00:00
|
|
|
\subsection{Basic customization\label{customization}}
|
1998-05-06 19:52:49 +00:00
|
|
|
|
1998-11-25 17:58:50 +00:00
|
|
|
\begin{methoddesc}[object]{__init__}{self\optional{, args...}}
|
1998-05-06 19:52:49 +00:00
|
|
|
Called when the instance is created. The arguments are those passed
|
|
|
|
to the class constructor expression. If a base class has an
|
1998-10-01 20:40:43 +00:00
|
|
|
\method{__init__()} method the derived class's \method{__init__()} method must
|
1998-05-06 19:52:49 +00:00
|
|
|
explicitly call it to ensure proper initialization of the base class
|
1998-08-28 20:03:12 +00:00
|
|
|
part of the instance, e.g., \samp{BaseClass.__init__(\var{self},
|
|
|
|
[\var{args}...])}.
|
1998-05-06 19:52:49 +00:00
|
|
|
\indexii{class}{constructor}
|
1998-11-25 17:58:50 +00:00
|
|
|
\end{methoddesc}
|
1998-05-06 19:52:49 +00:00
|
|
|
|
|
|
|
|
1998-11-25 17:58:50 +00:00
|
|
|
\begin{methoddesc}[object]{__del__}{self}
|
1998-07-24 15:36:43 +00:00
|
|
|
Called when the instance is about to be destroyed. This is also
|
|
|
|
called a destructor\index{destructor}. If a base class
|
1998-07-23 17:12:46 +00:00
|
|
|
has a \method{__del__()} method, the derived class's \method{__del__()} method
|
1998-05-06 19:52:49 +00:00
|
|
|
must explicitly call it to ensure proper deletion of the base class
|
1998-07-23 17:12:46 +00:00
|
|
|
part of the instance. Note that it is possible (though not recommended!)
|
|
|
|
for the \method{__del__()}
|
1998-05-06 19:52:49 +00:00
|
|
|
method to postpone destruction of the instance by creating a new
|
|
|
|
reference to it. It may then be called at a later time when this new
|
|
|
|
reference is deleted. It is not guaranteed that
|
|
|
|
\method{__del__()} methods are called for objects that still exist when
|
|
|
|
the interpreter exits.
|
|
|
|
\stindex{del}
|
|
|
|
|
1998-10-01 20:40:43 +00:00
|
|
|
\strong{Programmer's note:} \samp{del x} doesn't directly call
|
1998-07-23 17:12:46 +00:00
|
|
|
\code{x.__del__()} --- the former decrements the reference count for
|
|
|
|
\code{x} by one, and the latter is only called when its reference
|
|
|
|
count reaches zero. Some common situations that may prevent the
|
|
|
|
reference count of an object to go to zero include: circular
|
|
|
|
references between objects (e.g., a doubly-linked list or a tree data
|
|
|
|
structure with parent and child pointers); a reference to the object
|
|
|
|
on the stack frame of a function that caught an exception (the
|
|
|
|
traceback stored in \code{sys.exc_traceback} keeps the stack frame
|
|
|
|
alive); or a reference to the object on the stack frame that raised an
|
|
|
|
unhandled exception in interactive mode (the traceback stored in
|
|
|
|
\code{sys.last_traceback} keeps the stack frame alive). The first
|
|
|
|
situation can only be remedied by explicitly breaking the cycles; the
|
|
|
|
latter two situations can be resolved by storing None in
|
|
|
|
\code{sys.exc_traceback} or \code{sys.last_traceback}.
|
1998-05-06 19:52:49 +00:00
|
|
|
|
|
|
|
\strong{Warning:} due to the precarious circumstances under which
|
1998-08-28 20:03:12 +00:00
|
|
|
\method{__del__()} methods are invoked, exceptions that occur during their
|
1998-07-23 17:12:46 +00:00
|
|
|
execution are ignored, and a warning is printed to \code{sys.stderr}
|
1998-08-28 20:03:12 +00:00
|
|
|
instead. Also, when \method{__del__()} is invoked is response to a module
|
1998-07-23 17:12:46 +00:00
|
|
|
being deleted (e.g., when execution of the program is done), other
|
1998-08-28 20:03:12 +00:00
|
|
|
globals referenced by the \method{__del__()} method may already have been
|
|
|
|
deleted. For this reason, \method{__del__()} methods should do the
|
1998-07-23 17:12:46 +00:00
|
|
|
absolute minimum needed to maintain external invariants. Python 1.5
|
|
|
|
guarantees that globals whose name begins with a single underscore are
|
|
|
|
deleted from their module before other globals are deleted; if no
|
|
|
|
other references to such globals exist, this may help in assuring that
|
|
|
|
imported modules are still available at the time when the
|
1998-08-28 20:03:12 +00:00
|
|
|
\method{__del__()} method is called.
|
1998-11-25 17:58:50 +00:00
|
|
|
\end{methoddesc}
|
1998-05-06 19:52:49 +00:00
|
|
|
|
1998-11-25 17:58:50 +00:00
|
|
|
\begin{methoddesc}[object]{__repr__}{self}
|
1998-10-01 20:40:43 +00:00
|
|
|
Called by the \function{repr()}\bifuncindex{repr} built-in function
|
|
|
|
and by string conversions (reverse quotes) to compute the ``official''
|
|
|
|
string representation of an object. This should normally look like a
|
|
|
|
valid Python expression that can be used to recreate an object with
|
|
|
|
the same value. By convention, objects which cannot be trivially
|
|
|
|
converted to strings which can be used to create a similar object
|
|
|
|
produce a string of the form \samp{<\var{...some useful
|
|
|
|
description...}>}.
|
1998-05-06 19:52:49 +00:00
|
|
|
\indexii{string}{conversion}
|
|
|
|
\indexii{reverse}{quotes}
|
|
|
|
\indexii{backward}{quotes}
|
|
|
|
\index{back-quotes}
|
1998-11-25 17:58:50 +00:00
|
|
|
\end{methoddesc}
|
1998-05-06 19:52:49 +00:00
|
|
|
|
1998-11-25 17:58:50 +00:00
|
|
|
\begin{methoddesc}[object]{__str__}{self}
|
1998-08-28 20:03:12 +00:00
|
|
|
Called by the \function{str()}\bifuncindex{str} built-in function and
|
|
|
|
by the \keyword{print}\stindex{print} statement to compute the
|
1998-10-01 20:40:43 +00:00
|
|
|
``informal'' string representation of an object. This differs from
|
|
|
|
\method{__repr__()} in that it does not have to be a valid Python
|
|
|
|
expression: a more convenient or concise representation may be used
|
|
|
|
instead.
|
1998-11-25 17:58:50 +00:00
|
|
|
\end{methoddesc}
|
1998-05-06 19:52:49 +00:00
|
|
|
|
1998-11-25 17:58:50 +00:00
|
|
|
\begin{methoddesc}[object]{__cmp__}{self, other}
|
1998-07-23 17:12:46 +00:00
|
|
|
Called by all comparison operations. Should return a negative integer if
|
|
|
|
\code{self < other}, zero if \code{self == other}, a positive integer if
|
1998-05-06 19:52:49 +00:00
|
|
|
\code{self > other}. If no \method{__cmp__()} operation is defined, class
|
|
|
|
instances are compared by object identity (``address'').
|
1998-07-23 17:12:46 +00:00
|
|
|
(Note: the restriction that exceptions are not propagated by
|
1998-10-01 20:40:43 +00:00
|
|
|
\method{__cmp__()} has been removed in Python 1.5.)
|
1998-05-06 19:52:49 +00:00
|
|
|
\bifuncindex{cmp}
|
|
|
|
\index{comparisons}
|
1998-11-25 17:58:50 +00:00
|
|
|
\end{methoddesc}
|
1998-05-06 19:52:49 +00:00
|
|
|
|
2000-06-15 20:07:25 +00:00
|
|
|
\begin{methoddesc}[object]{__rcmp__}{self, other}
|
|
|
|
Called by all comparison operations. Should return a negative integer if
|
|
|
|
\code{self < other}, zero if \code{self == other}, a positive integer if
|
|
|
|
\code{self > other}. If no \method{__cmp__()} operation is defined, class
|
|
|
|
instances are compared by object identity (``address'').
|
|
|
|
(Note: the restriction that exceptions are not propagated by
|
|
|
|
\method{__cmp__()} has been removed in Python 1.5.)
|
|
|
|
\bifuncindex{cmp}
|
|
|
|
\index{comparisons}
|
|
|
|
\end{methoddesc}
|
|
|
|
|
1998-11-25 17:58:50 +00:00
|
|
|
\begin{methoddesc}[object]{__hash__}{self}
|
1998-08-28 20:03:12 +00:00
|
|
|
Called for the key object for dictionary\obindex{dictionary}
|
|
|
|
operations, and by the built-in function
|
1998-05-06 19:52:49 +00:00
|
|
|
\function{hash()}\bifuncindex{hash}. Should return a 32-bit integer
|
|
|
|
usable as a hash value
|
|
|
|
for dictionary operations. The only required property is that objects
|
|
|
|
which compare equal have the same hash value; it is advised to somehow
|
1998-07-23 17:12:46 +00:00
|
|
|
mix together (e.g., using exclusive or) the hash values for the
|
1998-05-06 19:52:49 +00:00
|
|
|
components of the object that also play a part in comparison of
|
|
|
|
objects. If a class does not define a \method{__cmp__()} method it should
|
|
|
|
not define a \method{__hash__()} operation either; if it defines
|
|
|
|
\method{__cmp__()} but not \method{__hash__()} its instances will not be
|
|
|
|
usable as dictionary keys. If a class defines mutable objects and
|
|
|
|
implements a \method{__cmp__()} method it should not implement
|
1998-07-23 17:12:46 +00:00
|
|
|
\method{__hash__()}, since the dictionary implementation requires that
|
|
|
|
a key's hash value is immutable (if the object's hash value changes, it
|
|
|
|
will be in the wrong hash bucket).
|
1998-11-25 17:58:50 +00:00
|
|
|
\withsubitem{(object method)}{\ttindex{__cmp__()}}
|
|
|
|
\end{methoddesc}
|
1998-08-28 20:03:12 +00:00
|
|
|
|
1998-11-25 17:58:50 +00:00
|
|
|
\begin{methoddesc}[object]{__nonzero__}{self}
|
1998-08-28 20:03:12 +00:00
|
|
|
Called to implement truth value testing; should return \code{0} or
|
|
|
|
\code{1}. When this method is not defined, \method{__len__()} is
|
|
|
|
called, if it is defined (see below). If a class defines neither
|
|
|
|
\method{__len__()} nor \method{__nonzero__()}, all its instances are
|
|
|
|
considered true.
|
1998-11-25 17:58:50 +00:00
|
|
|
\withsubitem{(mapping object method)}{\ttindex{__len__()}}
|
|
|
|
\end{methoddesc}
|
1998-05-06 19:52:49 +00:00
|
|
|
|
|
|
|
|
1998-07-28 19:34:22 +00:00
|
|
|
\subsection{Customizing attribute access\label{attribute-access}}
|
1998-05-06 19:52:49 +00:00
|
|
|
|
1998-07-23 17:12:46 +00:00
|
|
|
The following methods can be defined to customize the meaning of
|
|
|
|
attribute access (use of, assignment to, or deletion of \code{x.name})
|
|
|
|
for class instances.
|
|
|
|
For performance reasons, these methods are cached in the class object
|
|
|
|
at class definition time; therefore, they cannot be changed after the
|
|
|
|
class definition is executed.
|
1998-05-06 19:52:49 +00:00
|
|
|
|
1998-11-25 17:58:50 +00:00
|
|
|
\begin{methoddesc}[object]{__getattr__}{self, name}
|
1998-05-06 19:52:49 +00:00
|
|
|
Called when an attribute lookup has not found the attribute in the
|
|
|
|
usual places (i.e. it is not an instance attribute nor is it found in
|
|
|
|
the class tree for \code{self}). \code{name} is the attribute name.
|
1998-07-23 17:12:46 +00:00
|
|
|
This method should return the (computed) attribute value or raise an
|
1998-08-28 20:03:12 +00:00
|
|
|
\exception{AttributeError} exception.
|
1998-05-06 19:52:49 +00:00
|
|
|
|
|
|
|
Note that if the attribute is found through the normal mechanism,
|
1998-08-28 20:03:12 +00:00
|
|
|
\method{__getattr__()} is not called. (This is an intentional
|
|
|
|
asymmetry between \method{__getattr__()} and \method{__setattr__()}.)
|
1998-05-06 19:52:49 +00:00
|
|
|
This is done both for efficiency reasons and because otherwise
|
1998-08-28 20:03:12 +00:00
|
|
|
\method{__setattr__()} would have no way to access other attributes of
|
|
|
|
the instance.
|
1998-07-23 17:12:46 +00:00
|
|
|
Note that at least for instance variables, you can fake
|
|
|
|
total control by not inserting any values in the instance
|
|
|
|
attribute dictionary (but instead inserting them in another object).
|
1998-11-25 17:58:50 +00:00
|
|
|
\withsubitem{(object method)}{\ttindex{__setattr__()}}
|
|
|
|
\end{methoddesc}
|
1998-05-06 19:52:49 +00:00
|
|
|
|
1998-11-25 17:58:50 +00:00
|
|
|
\begin{methoddesc}[object]{__setattr__}{self, name, value}
|
1998-05-06 19:52:49 +00:00
|
|
|
Called when an attribute assignment is attempted. This is called
|
1998-08-28 20:03:12 +00:00
|
|
|
instead of the normal mechanism (i.e.\ store the value in the instance
|
|
|
|
dictionary). \var{name} is the attribute name, \var{value} is the
|
1998-05-06 19:52:49 +00:00
|
|
|
value to be assigned to it.
|
|
|
|
|
1998-08-28 20:03:12 +00:00
|
|
|
If \method{__setattr__()} wants to assign to an instance attribute, it
|
|
|
|
should not simply execute \samp{self.\var{name} = value} --- this
|
|
|
|
would cause a recursive call to itself. Instead, it should insert the
|
|
|
|
value in the dictionary of instance attributes, e.g.,
|
|
|
|
\samp{self.__dict__[\var{name}] = value}.
|
1998-11-25 17:58:50 +00:00
|
|
|
\withsubitem{(instance attribute)}{\ttindex{__dict__}}
|
|
|
|
\end{methoddesc}
|
1998-05-06 19:52:49 +00:00
|
|
|
|
1998-11-25 17:58:50 +00:00
|
|
|
\begin{methoddesc}[object]{__delattr__}{self, name}
|
1998-08-28 20:03:12 +00:00
|
|
|
Like \method{__setattr__()} but for attribute deletion instead of
|
1998-11-25 17:58:50 +00:00
|
|
|
assignment. This should only be implemented if \samp{del
|
|
|
|
obj.\var{name}} is meaningful for the object.
|
|
|
|
\end{methoddesc}
|
1998-05-06 19:52:49 +00:00
|
|
|
|
|
|
|
|
1998-07-28 19:34:22 +00:00
|
|
|
\subsection{Emulating callable objects\label{callable-types}}
|
1998-07-23 17:12:46 +00:00
|
|
|
|
1998-11-25 17:58:50 +00:00
|
|
|
\begin{methoddesc}[object]{__call__}{self\optional{, args...}}
|
1998-07-23 17:12:46 +00:00
|
|
|
Called when the instance is ``called'' as a function; if this method
|
1998-08-28 20:03:12 +00:00
|
|
|
is defined, \code{\var{x}(arg1, arg2, ...)} is a shorthand for
|
|
|
|
\code{\var{x}.__call__(arg1, arg2, ...)}.
|
1998-07-23 17:12:46 +00:00
|
|
|
\indexii{call}{instance}
|
1998-11-25 17:58:50 +00:00
|
|
|
\end{methoddesc}
|
1998-07-23 17:12:46 +00:00
|
|
|
|
|
|
|
|
1998-07-28 19:34:22 +00:00
|
|
|
\subsection{Emulating sequence and mapping types\label{sequence-types}}
|
1998-07-23 17:12:46 +00:00
|
|
|
|
|
|
|
The following methods can be defined to emulate sequence or mapping
|
|
|
|
objects. The first set of methods is used either to emulate a
|
|
|
|
sequence or to emulate a mapping; the difference is that for a
|
|
|
|
sequence, the allowable keys should be the integers \var{k} for which
|
|
|
|
\code{0 <= \var{k} < \var{N}} where \var{N} is the length of the
|
2000-08-17 22:37:32 +00:00
|
|
|
sequence, or slice objects, which define a range of items. (For backwards
|
|
|
|
compatibility, the method \method{__getslice__()} (see below) can also be
|
|
|
|
defined to handle simple, but not extended slices.) It is also recommended
|
2000-08-18 02:42:14 +00:00
|
|
|
that mappings provide the methods \method{keys()}, \method{values()},
|
2000-08-17 22:37:32 +00:00
|
|
|
\method{items()}, \method{has_key()}, \method{get()}, \method{clear()},
|
|
|
|
\method{copy()}, and \method{update()} behaving similar to those for
|
1998-07-23 17:12:46 +00:00
|
|
|
Python's standard dictionary objects; mutable sequences should provide
|
|
|
|
methods \method{append()}, \method{count()}, \method{index()},
|
|
|
|
\method{insert()}, \method{pop()}, \method{remove()}, \method{reverse()}
|
|
|
|
and \method{sort()}, like Python standard list objects. Finally,
|
|
|
|
sequence types should implement addition (meaning concatenation) and
|
|
|
|
multiplication (meaning repetition) by defining the methods
|
2000-08-24 20:06:04 +00:00
|
|
|
\method{__add__()}, \method{__radd__()}, \method{__iadd__()},
|
|
|
|
\method{__mul__()}, \method{__rmul__()} and \method{__imul__()} described
|
|
|
|
below; they should not define \method{__coerce__()} or other numerical
|
|
|
|
operators.
|
1999-01-12 04:15:20 +00:00
|
|
|
\withsubitem{(mapping object method)}{
|
|
|
|
\ttindex{keys()}
|
|
|
|
\ttindex{values()}
|
|
|
|
\ttindex{items()}
|
|
|
|
\ttindex{has_key()}
|
|
|
|
\ttindex{get()}
|
|
|
|
\ttindex{clear()}
|
|
|
|
\ttindex{copy()}
|
1998-11-25 17:58:50 +00:00
|
|
|
\ttindex{update()}}
|
1999-01-12 04:15:20 +00:00
|
|
|
\withsubitem{(sequence object method)}{
|
|
|
|
\ttindex{append()}
|
|
|
|
\ttindex{count()}
|
|
|
|
\ttindex{index()}
|
|
|
|
\ttindex{insert()}
|
|
|
|
\ttindex{pop()}
|
|
|
|
\ttindex{remove()}
|
|
|
|
\ttindex{reverse()}
|
|
|
|
\ttindex{sort()}
|
|
|
|
\ttindex{__add__()}
|
|
|
|
\ttindex{__radd__()}
|
2000-08-24 20:06:04 +00:00
|
|
|
\ttindex{__iadd__()}
|
1999-01-12 04:15:20 +00:00
|
|
|
\ttindex{__mul__()}
|
2000-08-24 20:06:04 +00:00
|
|
|
\ttindex{__rmul__()}
|
|
|
|
\ttindex{__imul__()}}
|
1999-01-28 23:21:49 +00:00
|
|
|
\withsubitem{(numeric object method)}{\ttindex{__coerce__()}}
|
1998-11-25 17:58:50 +00:00
|
|
|
|
|
|
|
\begin{methoddesc}[mapping object]{__len__}{self}
|
1998-08-28 20:03:12 +00:00
|
|
|
Called to implement the built-in function
|
|
|
|
\function{len()}\bifuncindex{len}. Should return the length of the
|
|
|
|
object, an integer \code{>=} 0. Also, an object that doesn't define a
|
|
|
|
\method{__nonzero__()} method and whose \method{__len__()} method
|
|
|
|
returns zero is considered to be false in a Boolean context.
|
1998-11-25 17:58:50 +00:00
|
|
|
\withsubitem{(object method)}{\ttindex{__nonzero__()}}
|
|
|
|
\end{methoddesc}
|
1998-05-06 19:52:49 +00:00
|
|
|
|
1998-11-25 17:58:50 +00:00
|
|
|
\begin{methoddesc}[mapping object]{__getitem__}{self, key}
|
1998-08-28 20:03:12 +00:00
|
|
|
Called to implement evaluation of \code{\var{self}[\var{key}]}.
|
2000-07-13 04:57:58 +00:00
|
|
|
For a sequence types, the accepted keys should be integers. Note that
|
|
|
|
the special interpretation of negative indices (if the class wishes to
|
1998-05-06 19:52:49 +00:00
|
|
|
emulate a sequence type) is up to the \method{__getitem__()} method.
|
2000-07-13 04:57:58 +00:00
|
|
|
If \var{key} is of an inappropriate type, \exception{TypeError} may be
|
|
|
|
raised; if of a value outside the set of indexes for the sequence
|
|
|
|
(after any special interpretation of negative values),
|
|
|
|
\exception{IndexError} should be raised.
|
|
|
|
\strong{Note:} \keyword{for} loops expect that an
|
|
|
|
\exception{IndexError} will be raised for illegal indexes to allow
|
|
|
|
proper detection of the end of the sequence.
|
1998-11-25 17:58:50 +00:00
|
|
|
\end{methoddesc}
|
1998-05-06 19:52:49 +00:00
|
|
|
|
1998-11-25 17:58:50 +00:00
|
|
|
\begin{methoddesc}[mapping object]{__setitem__}{self, key, value}
|
1998-08-28 20:03:12 +00:00
|
|
|
Called to implement assignment to \code{\var{self}[\var{key}]}. Same
|
1998-11-25 17:58:50 +00:00
|
|
|
note as for \method{__getitem__()}. This should only be implemented
|
|
|
|
for mappings if the objects support changes to the values for keys, or
|
|
|
|
if new keys can be added, or for sequences if elements can be
|
2000-07-13 04:57:58 +00:00
|
|
|
replaced. The same exceptions should be raised for improper
|
|
|
|
\var{key} values as for the \method{__getitem__()} method.
|
1998-11-25 17:58:50 +00:00
|
|
|
\end{methoddesc}
|
1998-05-06 19:52:49 +00:00
|
|
|
|
1998-11-25 17:58:50 +00:00
|
|
|
\begin{methoddesc}[mapping object]{__delitem__}{self, key}
|
1998-08-28 20:03:12 +00:00
|
|
|
Called to implement deletion of \code{\var{self}[\var{key}]}. Same
|
1998-11-25 17:58:50 +00:00
|
|
|
note as for \method{__getitem__()}. This should only be implemented
|
|
|
|
for mappings if the objects support removal of keys, or for sequences
|
2000-07-13 04:57:58 +00:00
|
|
|
if elements can be removed from the sequence. The same exceptions
|
|
|
|
should be raised for improper \var{key} values as for the
|
|
|
|
\method{__getitem__()} method.
|
1998-11-25 17:58:50 +00:00
|
|
|
\end{methoddesc}
|
1998-05-06 19:52:49 +00:00
|
|
|
|
|
|
|
|
1998-10-21 00:25:32 +00:00
|
|
|
\subsection{Additional methods for emulation of sequence types
|
1998-07-28 19:34:22 +00:00
|
|
|
\label{sequence-methods}}
|
1998-07-23 17:12:46 +00:00
|
|
|
|
|
|
|
The following methods can be defined to further emulate sequence
|
|
|
|
objects. Immutable sequences methods should only define
|
|
|
|
\method{__getslice__()}; mutable sequences, should define all three
|
|
|
|
three methods.
|
1998-05-06 19:52:49 +00:00
|
|
|
|
1998-11-25 17:58:50 +00:00
|
|
|
\begin{methoddesc}[sequence object]{__getslice__}{self, i, j}
|
2000-08-18 02:42:14 +00:00
|
|
|
\deprecated{2.0}{Support slice objects as parameters to the
|
|
|
|
\method{__getitem__()} method.}
|
1998-08-28 20:03:12 +00:00
|
|
|
Called to implement evaluation of \code{\var{self}[\var{i}:\var{j}]}.
|
|
|
|
The returned object should be of the same type as \var{self}. Note
|
|
|
|
that missing \var{i} or \var{j} in the slice expression are replaced
|
2000-04-03 04:51:13 +00:00
|
|
|
by zero or \code{sys.maxint}, respectively. If negative indexes are
|
|
|
|
used in the slice, the length of the sequence is added to that index.
|
|
|
|
If the instance does not implement the \method{__len__()} method, an
|
|
|
|
\exception{AttributeError} is raised.
|
|
|
|
No guarantee is made that indexes adjusted this way are not still
|
|
|
|
negative. Indexes which are greater than the length of the sequence
|
|
|
|
are not modified.
|
2000-08-18 02:42:14 +00:00
|
|
|
If no \method{__getslice__()} is found, a slice
|
2000-08-17 22:37:32 +00:00
|
|
|
object is created instead, and passed to \method{__getitem__()} instead.
|
1998-11-25 17:58:50 +00:00
|
|
|
\end{methoddesc}
|
1998-05-06 19:52:49 +00:00
|
|
|
|
1998-11-25 17:58:50 +00:00
|
|
|
\begin{methoddesc}[sequence object]{__setslice__}{self, i, j, sequence}
|
1998-08-28 20:03:12 +00:00
|
|
|
Called to implement assignment to \code{\var{self}[\var{i}:\var{j}]}.
|
|
|
|
Same notes for \var{i} and \var{j} as for \method{__getslice__()}.
|
2000-08-17 22:37:32 +00:00
|
|
|
|
|
|
|
This method is deprecated. If no \method{__setslice__()} is found, a slice
|
|
|
|
object is created instead, and passed to \method{__setitem__()} instead.
|
1998-11-25 17:58:50 +00:00
|
|
|
\end{methoddesc}
|
1998-05-06 19:52:49 +00:00
|
|
|
|
1998-11-25 17:58:50 +00:00
|
|
|
\begin{methoddesc}[sequence object]{__delslice__}{self, i, j}
|
1998-08-28 20:03:12 +00:00
|
|
|
Called to implement deletion of \code{\var{self}[\var{i}:\var{j}]}.
|
|
|
|
Same notes for \var{i} and \var{j} as for \method{__getslice__()}.
|
2000-08-17 22:37:32 +00:00
|
|
|
This method is deprecated. If no \method{__delslice__()} is found, a slice
|
|
|
|
object is created instead, and passed to \method{__delitem__()} instead.
|
1998-11-25 17:58:50 +00:00
|
|
|
\end{methoddesc}
|
1998-05-06 19:52:49 +00:00
|
|
|
|
2000-08-17 22:37:32 +00:00
|
|
|
Notice that these methods are only invoked when a single slice with a single
|
|
|
|
colon is used, and the slice method is available. For slice operations
|
|
|
|
involving extended slice notation, or in absence of the slice methods,
|
|
|
|
\method{__getitem__()}, \method{__setitem__()} or \method{__delitem__()} is
|
|
|
|
called with a slice object as argument.
|
1998-05-06 19:52:49 +00:00
|
|
|
|
1999-02-12 18:14:57 +00:00
|
|
|
|
1998-07-28 19:34:22 +00:00
|
|
|
\subsection{Emulating numeric types\label{numeric-types}}
|
1998-07-23 17:12:46 +00:00
|
|
|
|
|
|
|
The following methods can be defined to emulate numeric objects.
|
|
|
|
Methods corresponding to operations that are not supported by the
|
|
|
|
particular kind of number implemented (e.g., bitwise operations for
|
|
|
|
non-integral numbers) should be left undefined.
|
1998-05-06 19:52:49 +00:00
|
|
|
|
1999-05-10 13:43:22 +00:00
|
|
|
\begin{methoddesc}[numeric object]{__add__}{self, other}
|
|
|
|
\methodline[numeric object]{__sub__}{self, other}
|
|
|
|
\methodline[numeric object]{__mul__}{self, other}
|
|
|
|
\methodline[numeric object]{__div__}{self, other}
|
|
|
|
\methodline[numeric object]{__mod__}{self, other}
|
|
|
|
\methodline[numeric object]{__divmod__}{self, other}
|
|
|
|
\methodline[numeric object]{__pow__}{self, other\optional{, modulo}}
|
|
|
|
\methodline[numeric object]{__lshift__}{self, other}
|
|
|
|
\methodline[numeric object]{__rshift__}{self, other}
|
|
|
|
\methodline[numeric object]{__and__}{self, other}
|
|
|
|
\methodline[numeric object]{__xor__}{self, other}
|
|
|
|
\methodline[numeric object]{__or__}{self, other}
|
1998-07-23 17:12:46 +00:00
|
|
|
These functions are
|
|
|
|
called to implement the binary arithmetic operations (\code{+},
|
1998-08-28 20:03:12 +00:00
|
|
|
\code{-}, \code{*}, \code{/}, \code{\%},
|
|
|
|
\function{divmod()}\bifuncindex{divmod},
|
|
|
|
\function{pow()}\bifuncindex{pow}, \code{**}, \code{<<}, \code{>>},
|
|
|
|
\code{\&}, \code{\^}, \code{|}). For instance, to evaluate the
|
|
|
|
expression \var{x}\code{+}\var{y}, where \var{x} is an instance of a
|
|
|
|
class that has an \method{__add__()} method,
|
|
|
|
\code{\var{x}.__add__(\var{y})} is called. Note that
|
|
|
|
\method{__pow__()} should be defined to accept an optional third
|
|
|
|
argument if the ternary version of the built-in
|
|
|
|
\function{pow()}\bifuncindex{pow} function is to be supported.
|
1998-11-25 17:58:50 +00:00
|
|
|
\end{methoddesc}
|
|
|
|
|
1999-05-10 13:43:22 +00:00
|
|
|
\begin{methoddesc}[numeric object]{__radd__}{self, other}
|
|
|
|
\methodline[numeric object]{__rsub__}{self, other}
|
|
|
|
\methodline[numeric object]{__rmul__}{self, other}
|
|
|
|
\methodline[numeric object]{__rdiv__}{self, other}
|
|
|
|
\methodline[numeric object]{__rmod__}{self, other}
|
|
|
|
\methodline[numeric object]{__rdivmod__}{self, other}
|
|
|
|
\methodline[numeric object]{__rpow__}{self, other}
|
|
|
|
\methodline[numeric object]{__rlshift__}{self, other}
|
|
|
|
\methodline[numeric object]{__rrshift__}{self, other}
|
|
|
|
\methodline[numeric object]{__rand__}{self, other}
|
|
|
|
\methodline[numeric object]{__rxor__}{self, other}
|
|
|
|
\methodline[numeric object]{__ror__}{self, other}
|
1998-07-23 17:12:46 +00:00
|
|
|
These functions are
|
|
|
|
called to implement the binary arithmetic operations (\code{+},
|
1998-08-28 20:03:12 +00:00
|
|
|
\code{-}, \code{*}, \code{/}, \code{\%},
|
|
|
|
\function{divmod()}\bifuncindex{divmod},
|
|
|
|
\function{pow()}\bifuncindex{pow}, \code{**}, \code{<<}, \code{>>},
|
|
|
|
\code{\&}, \code{\^}, \code{|}) with reversed operands. These
|
|
|
|
functions are only called if the left operand does not support the
|
|
|
|
corresponding operation. For instance, to evaluate the expression
|
|
|
|
\var{x}\code{-}\var{y}, where \var{y} is an instance of a class that
|
|
|
|
has an \method{__rsub__()} method, \code{\var{y}.__rsub__(\var{x})} is
|
|
|
|
called. Note that ternary \function{pow()}\bifuncindex{pow} will not
|
|
|
|
try calling \method{__rpow__()} (the coercion rules would become too
|
1998-07-23 17:12:46 +00:00
|
|
|
complicated).
|
1998-11-25 17:58:50 +00:00
|
|
|
\end{methoddesc}
|
|
|
|
|
1999-05-10 13:43:22 +00:00
|
|
|
\begin{methoddesc}[numeric object]{__neg__}{self}
|
|
|
|
\methodline[numeric object]{__pos__}{self}
|
|
|
|
\methodline[numeric object]{__abs__}{self}
|
|
|
|
\methodline[numeric object]{__invert__}{self}
|
1998-05-06 19:52:49 +00:00
|
|
|
Called to implement the unary arithmetic operations (\code{-}, \code{+},
|
2000-06-15 20:07:25 +00:00
|
|
|
\function{abs()}\bifuncindex{abs} and \code{\~{}}).
|
1998-11-25 17:58:50 +00:00
|
|
|
\end{methoddesc}
|
1998-08-28 20:03:12 +00:00
|
|
|
|
1999-05-10 13:43:22 +00:00
|
|
|
\begin{methoddesc}[numeric object]{__complex__}{self}
|
|
|
|
\methodline[numeric object]{__int__}{self}
|
|
|
|
\methodline[numeric object]{__long__}{self}
|
|
|
|
\methodline[numeric object]{__float__}{self}
|
1998-08-28 20:03:12 +00:00
|
|
|
Called to implement the built-in functions
|
1999-02-12 18:14:57 +00:00
|
|
|
\function{complex()}\bifuncindex{complex},
|
|
|
|
\function{int()}\bifuncindex{int}, \function{long()}\bifuncindex{long},
|
1998-08-28 20:03:12 +00:00
|
|
|
and \function{float()}\bifuncindex{float}. Should return a value of
|
|
|
|
the appropriate type.
|
1998-11-25 17:58:50 +00:00
|
|
|
\end{methoddesc}
|
1998-05-06 19:52:49 +00:00
|
|
|
|
1999-05-10 13:43:22 +00:00
|
|
|
\begin{methoddesc}[numeric object]{__oct__}{self}
|
|
|
|
\methodline[numeric object]{__hex__}{self}
|
1998-08-28 20:03:12 +00:00
|
|
|
Called to implement the built-in functions
|
|
|
|
\function{oct()}\bifuncindex{oct} and
|
|
|
|
\function{hex()}\bifuncindex{hex}. Should return a string value.
|
1998-11-25 17:58:50 +00:00
|
|
|
\end{methoddesc}
|
1998-05-06 19:52:49 +00:00
|
|
|
|
1999-05-10 13:43:22 +00:00
|
|
|
\begin{methoddesc}[numeric object]{__coerce__}{self, other}
|
1998-07-23 17:12:46 +00:00
|
|
|
Called to implement ``mixed-mode'' numeric arithmetic. Should either
|
1998-08-28 20:03:12 +00:00
|
|
|
return a 2-tuple containing \var{self} and \var{other} converted to
|
1999-05-10 13:43:22 +00:00
|
|
|
a common numeric type, or \code{None} if conversion is impossible. When
|
1998-07-23 17:12:46 +00:00
|
|
|
the common type would be the type of \code{other}, it is sufficient to
|
|
|
|
return \code{None}, since the interpreter will also ask the other
|
|
|
|
object to attempt a coercion (but sometimes, if the implementation of
|
|
|
|
the other type cannot be changed, it is useful to do the conversion to
|
|
|
|
the other type here).
|
1998-11-25 17:58:50 +00:00
|
|
|
\end{methoddesc}
|
1998-07-23 17:12:46 +00:00
|
|
|
|
|
|
|
\strong{Coercion rules}: to evaluate \var{x} \var{op} \var{y}, the
|
|
|
|
following steps are taken (where \method{__op__()} and
|
|
|
|
\method{__rop__()} are the method names corresponding to \var{op},
|
1998-07-24 15:36:43 +00:00
|
|
|
e.g., if var{op} is `\code{+}', \method{__add__()} and
|
1998-07-23 17:12:46 +00:00
|
|
|
\method{__radd__()} are used). If an exception occurs at any point,
|
|
|
|
the evaluation is abandoned and exception handling takes over.
|
|
|
|
|
|
|
|
\begin{itemize}
|
|
|
|
|
|
|
|
\item[0.] If \var{x} is a string object and op is the modulo operator (\%),
|
|
|
|
the string formatting operation is invoked and the remaining steps are
|
|
|
|
skipped.
|
|
|
|
|
|
|
|
\item[1.] If \var{x} is a class instance:
|
|
|
|
|
|
|
|
\begin{itemize}
|
|
|
|
|
|
|
|
\item[1a.] If \var{x} has a \method{__coerce__()} method:
|
|
|
|
replace \var{x} and \var{y} with the 2-tuple returned by
|
|
|
|
\code{\var{x}.__coerce__(\var{y})}; skip to step 2 if the
|
|
|
|
coercion returns \code{None}.
|
|
|
|
|
|
|
|
\item[1b.] If neither \var{x} nor \var{y} is a class instance
|
|
|
|
after coercion, go to step 3.
|
|
|
|
|
|
|
|
\item[1c.] If \var{x} has a method \method{__op__()}, return
|
|
|
|
\code{\var{x}.__op__(\var{y})}; otherwise, restore \var{x} and
|
|
|
|
\var{y} to their value before step 1a.
|
|
|
|
|
|
|
|
\end{itemize}
|
|
|
|
|
|
|
|
\item[2.] If \var{y} is a class instance:
|
|
|
|
|
|
|
|
\begin{itemize}
|
|
|
|
|
|
|
|
\item[2a.] If \var{y} has a \method{__coerce__()} method:
|
|
|
|
replace \var{y} and \var{x} with the 2-tuple returned by
|
|
|
|
\code{\var{y}.__coerce__(\var{x})}; skip to step 3 if the
|
|
|
|
coercion returns \code{None}.
|
|
|
|
|
|
|
|
\item[2b.] If neither \var{x} nor \var{y} is a class instance
|
|
|
|
after coercion, go to step 3.
|
|
|
|
|
|
|
|
\item[2b.] If \var{y} has a method \method{__rop__()}, return
|
|
|
|
\code{\var{y}.__rop__(\var{x})}; otherwise, restore \var{x}
|
|
|
|
and \var{y} to their value before step 2a.
|
|
|
|
|
|
|
|
\end{itemize}
|
|
|
|
|
|
|
|
\item[3.] We only get here if neither \var{x} nor \var{y} is a class
|
|
|
|
instance.
|
|
|
|
|
|
|
|
\begin{itemize}
|
|
|
|
|
|
|
|
\item[3a.] If op is `\code{+}' and \var{x} is a sequence,
|
|
|
|
sequence concatenation is invoked.
|
|
|
|
|
|
|
|
\item[3b.] If op is `\code{*}' and one operand is a sequence
|
|
|
|
and the other an integer, sequence repetition is invoked.
|
|
|
|
|
|
|
|
\item[3c.] Otherwise, both operands must be numbers; they are
|
|
|
|
coerced to a common type if possible, and the numeric
|
|
|
|
operation is invoked for that type.
|
|
|
|
|
|
|
|
\end{itemize}
|
|
|
|
|
|
|
|
\end{itemize}
|