| \chapter{Data model\label{datamodel}} |
| |
| |
| \section{Objects, values and types\label{objects}} |
| |
| \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 |
| ``stored program computer,'' code is also represented by objects.) |
| \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 |
| of it as the object's address in memory. The `\keyword{is}' operator |
| compares the identity of two objects; the |
| \function{id()}\bifuncindex{id} function returns an integer |
| representing its identity (currently implemented as its address). |
| An object's \dfn{type} is |
| also unchangeable. It determines the operations that an object |
| supports (e.g., ``does it have a length?'') and also defines the |
| 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 |
| objects can change. Objects whose value can change are said to be |
| \emph{mutable}; objects whose value is unchangeable once they are |
| created are called \emph{immutable}. |
| (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.) |
| An object's mutability is determined by its type; for instance, |
| numbers, strings and tuples are immutable, while dictionaries and |
| lists are mutable. |
| \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 |
| allowed to postpone garbage collection or omit it altogether --- it is |
| a matter of implementation quality how garbage collection is |
| implemented, as long as no objects are collected that are still |
| reachable. (Implementation note: the current implementation uses a |
| reference-counting scheme with (optional) delayed detection of |
| cyclicly linked garbage, which collects most objects as soon as they |
| become unreachable, but is not guaranteed to collect garbage |
| containing circular references. See the |
| \citetitle[../lib/module-gc.html]{Python Library Reference} for |
| information on controlling the collection of cyclic garbage.) |
| \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. |
| Also note that catching an exception with a |
| `\keyword{try}...\keyword{except}' statement may keep objects alive. |
| |
| 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. |
| Programs are strongly recommended to explicitly close such |
| objects. The `\keyword{try}...\keyword{finally}' statement provides |
| a convenient way to do this. |
| |
| 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 |
| 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. |
| \index{container} |
| |
| Types affect almost all aspects of object behavior. Even the importance |
| 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 |
| objects this is not allowed. E.g., after |
| \samp{a = 1; b = 1}, |
| \code{a} and \code{b} may or may not refer to the same object with the |
| value one, depending on the implementation, but after |
| \samp{c = []; d = []}, \code{c} and \code{d} |
| are guaranteed to refer to two different, unique, newly created empty |
| lists. |
| (Note that \samp{c = d = []} assigns the same object to both |
| \code{c} and \code{d}.) |
| |
| |
| \section{The standard type hierarchy\label{types}} |
| |
| Below is a list of the types that are built into Python. Extension |
| modules written in \C{} can define additional types. Future versions of |
| Python may add types to the type hierarchy (e.g., rational |
| 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 |
| `special attributes.' These are attributes that provide access to the |
| implementation and are not intended for general use. Their definition |
| may change in the future. |
| \index{attribute} |
| \indexii{special}{attribute} |
| \indexiii{generic}{special}{attribute} |
| |
| \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}. |
| 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. |
| \ttindex{None} |
| \obindex{None@{\texttt{None}}} |
| |
| \item[NotImplemented] |
| This type has a single value. There is a single object with this value. |
| This object is accessed through the built-in name \code{NotImplemented}. |
| Numeric methods and rich comparison methods may return this value if |
| they do not implement the operation for the operands provided. (The |
| interpreter will then try the reflected operation, or some other |
| fallback, depending on the operator.) Its truth value is true. |
| \ttindex{NotImplemented} |
| \obindex{NotImplemented@{\texttt{NotImplemented}}} |
| |
| \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}. |
| It is used to indicate the presence of the \samp{...} syntax in a |
| slice. Its truth value is true. |
| \obindex{Ellipsis} |
| |
| \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, floating point numbers, and |
| complex numbers: |
| |
| \begin{description} |
| \item[Integers] |
| These represent elements from the mathematical set of whole numbers. |
| \obindex{integer} |
| |
| There are three 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.) |
| When the result of an operation would fall outside this range, the |
| 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} |
| |
| \item[Booleans] |
| These represent the truth values False and True. The two objects |
| representing the values False and True are the only Boolean objects. |
| The Boolean type is a subtype of plain integers, and Boolean values |
| behave like the values 0 and 1, respectively, in almost all contexts, |
| the exception being that when converted to a string, the strings |
| \code{"False"} or \code{"True"} are returned, respectively. |
| \obindex{Boolean} |
| \ttindex{False} |
| \ttindex{True} |
| |
| \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 |
| \C{} implementation for the accepted range and handling of overflow. |
| Python does not support single-precision floating point numbers; the |
| savings in processor 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. |
| \obindex{floating point} |
| \indexii{floating point}{number} |
| \indexii{C}{language} |
| |
| \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} |
| |
| \end{description} % Numbers |
| |
| |
| \item[Sequences] |
| These represent finite ordered sets indexed by non-negative numbers. |
| The built-in function \function{len()}\bifuncindex{len} returns the |
| number of items of a sequence. |
| When the length of a sequence is \var{n}, the |
| index set contains the numbers 0, 1, \ldots, \var{n}-1. Item |
| \var{i} of sequence \var{a} is selected by \code{\var{a}[\var{i}]}. |
| \obindex{sequence} |
| \index{index operation} |
| \index{item selection} |
| \index{subscription} |
| |
| Sequences also support slicing: \code{\var{a}[\var{i}:\var{j}]} |
| selects all items with index \var{k} such that \var{i} \code{<=} |
| \var{k} \code{<} \var{j}. When used as an expression, a slice is a |
| sequence of the same type. This implies that the index set is |
| renumbered so that it starts at 0. |
| \index{slicing} |
| |
| Some sequences also support ``extended slicing'' with a third ``step'' |
| parameter: \code{\var{a}[\var{i}:\var{j}:\var{k}]} selects all items |
| of \var{a} with index \var{x} where \code{\var{x} = \var{i} + |
| \var{n}*\var{k}}, \var{n} \code{>=} \code{0} and \var{i} \code{<=} |
| \var{x} \code{<} \var{j}. |
| \index{extended slicing} |
| |
| Sequences are distinguished according to their mutability: |
| |
| \begin{description} |
| |
| \item[Immutable sequences] |
| An object of an immutable sequence type cannot change once it is |
| created. (If the object contains references to other objects, |
| these other objects may be mutable and may be changed; however, |
| 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] |
| The items of a string are characters. There is no separate |
| character type; a character is represented by a string of one item. |
| 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 |
| 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 |
| read from a file. |
| \obindex{string} |
| \index{character} |
| \index{byte} |
| \index{ASCII@\ASCII} |
| |
| (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?) |
| \index{ASCII@\ASCII} |
| \index{EBCDIC} |
| \index{character set} |
| \indexii{string}{comparison} |
| \bifuncindex{chr} |
| \bifuncindex{ord} |
| |
| \item[Unicode] |
| The items of a Unicode object are Unicode code units. A Unicode code |
| unit is represented by a Unicode object of one item and can hold |
| either a 16-bit or 32-bit value representing a Unicode ordinal (the |
| maximum value for the ordinal is given in \code{sys.maxunicode}, and |
| depends on how Python is configured at compile time). Surrogate pairs |
| may be present in the Unicode object, and will be reported as two |
| separate items. The built-in functions |
| \function{unichr()}\bifuncindex{unichr} and |
| \function{ord()}\bifuncindex{ord} convert between code units 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} |
| \index{Unicode} |
| |
| \item[Tuples] |
| 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 |
| by affixing a comma to an expression (an expression by itself does |
| not create a tuple, since parentheses must be usable for grouping of |
| expressions). An empty tuple can be formed by an empty pair of |
| 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. |
| \obindex{mutable sequence} |
| \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] |
| The items of a list are arbitrary Python objects. Lists are formed |
| 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 |
| |
| The extension module \module{array}\refstmodindex{array} provides an |
| additional example of a mutable sequence type. |
| |
| |
| \end{description} % Sequences |
| |
| \item[Mappings] |
| These represent finite sets of objects indexed by arbitrary index sets. |
| The subscript notation \code{a[k]} selects the item indexed |
| by \code{k} from the mapping \code{a}; this can be used in |
| expressions and as the target of assignments or \keyword{del} statements. |
| The built-in function \function{len()} returns the number of items |
| in a mapping. |
| \bifuncindex{len} |
| \index{subscription} |
| \obindex{mapping} |
| |
| There is currently a single intrinsic mapping type: |
| |
| \begin{description} |
| |
| \item[Dictionaries] |
| 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. |
| Numeric types used for keys obey the normal rules for numeric |
| comparison: if two numbers compare equal (e.g., \code{1} and |
| \code{1.0}) then they can be used interchangeably to index the same |
| dictionary entry. |
| |
| Dictionaries are mutable; they are created by the |
| \code{\{...\}} notation (see section \ref{dict}, ``Dictionary |
| Displays''). |
| |
| The extension modules \module{dbm}\refstmodindex{dbm}, |
| \module{gdbm}\refstmodindex{gdbm}, \module{bsddb}\refstmodindex{bsddb} |
| provide additional examples of mapping types. |
| |
| \end{description} % Mapping types |
| |
| \item[Callable types] |
| These\obindex{callable} are the types to which the function call |
| operation (see section \ref{calls}, ``Calls'') can be applied: |
| \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 |
| (see section \ref{function}, ``Function definitions''). It should be |
| called with an argument |
| list containing the same number of items as the function's formal |
| parameter list. |
| \indexii{user-defined}{function} |
| \obindex{function} |
| \obindex{user-defined function} |
| |
| Special attributes: \member{func_doc} or \member{__doc__} is the |
| function's documentation string, or None if unavailable; |
| \member{func_name} or \member{__name__} is the function's name; |
| \member{func_defaults} is a tuple containing default argument values for |
| those arguments that have defaults, or \code{None} if no arguments |
| have a default value; \member{func_code} is the code object representing |
| the compiled function body; \member{func_globals} is (a reference to) |
| the dictionary that holds the function's global variables --- it |
| defines the global namespace of the module in which the function was |
| defined; \member{func_dict} or \member{__dict__} contains the |
| namespace supporting arbitrary function attributes; |
| \member{func_closure} is \code{None} or a tuple of cells that contain |
| bindings for the function's free variables. |
| |
| Of these, \member{func_code}, \member{func_defaults}, |
| \member{func_doc}/\member{__doc__}, and |
| \member{func_dict}/\member{__dict__} may be writable; the |
| others can never be changed. Additional information about a |
| function's definition can be retrieved from its code object; see the |
| description of internal types below. |
| |
| \withsubitem{(function attribute)}{ |
| \ttindex{func_doc} |
| \ttindex{__doc__} |
| \ttindex{__name__} |
| \ttindex{__dict__} |
| \ttindex{func_defaults} |
| \ttindex{func_closure} |
| \ttindex{func_code} |
| \ttindex{func_globals} |
| \ttindex{func_dict}} |
| \indexii{global}{namespace} |
| |
| \item[User-defined methods] |
| A user-defined method object combines a class, a class instance (or |
| \code{None}) and any callable object (normally a user-defined |
| function). |
| \obindex{method} |
| \obindex{user-defined method} |
| \indexii{user-defined}{method} |
| |
| Special read-only attributes: \member{im_self} is the class instance |
| object, \member{im_func} is the function object; |
| \member{im_class} is the class of \member{im_self} for bound methods, |
| or the class that asked for the method for unbound methods); |
| \member{__doc__} is the method's documentation (same as |
| \code{im_func.__doc__}); \member{__name__} is the method name (same as |
| \code{im_func.__name__}). |
| \versionchanged[\member{im_self} used to refer to the class that |
| defined the method]{2.2} |
| \withsubitem{(method attribute)}{ |
| \ttindex{im_func} |
| \ttindex{im_self}} |
| |
| Methods also support accessing (but not setting) the arbitrary |
| function attributes on the underlying function object. |
| |
| 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 |
| 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 |
| instance, when \class{C} is a class which has a method |
| \method{f()}, \code{C.f} does not yield the function object |
| \code{f}; rather, it yields an unbound method object \code{m} where |
| \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} |
| instance, \code{x.f} yields a bound method object \code{m} where |
| \code{m.im_class} is \code{C}, \code{m.im_func} is \method{f()}, and |
| \code{m.im_self} is \code{x}. |
| \withsubitem{(method attribute)}{ |
| \ttindex{im_class}\ttindex{im_func}\ttindex{im_self}} |
| |
| When an unbound user-defined method object is called, the underlying |
| function (\member{im_func}) is called, with the restriction that the |
| first argument must be an instance of the proper class |
| (\member{im_class}) or of a derived class thereof. |
| |
| When a bound user-defined method object is called, the underlying |
| 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 |
| \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 |
| 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. |
| |
| \item[Generator functions\index{generator!function}\index{generator!iterator}] |
| A function or method which uses the \keyword{yield} statement (see |
| section~\ref{yield}, ``The \keyword{yield} statement'') is called a |
| \dfn{generator function}. Such a function, when called, always |
| returns an iterator object which can be used to execute the body of |
| the function: calling the iterator's \method{next()} method will |
| cause the function to execute until it provides a value using the |
| \keyword{yield} statement. When the function executes a |
| \keyword{return} statement or falls off the end, a |
| \exception{StopIteration} exception is raised and the iterator will |
| have reached the end of the set of values to be returned. |
| |
| \item[Built-in functions] |
| 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 |
| determined by the C function. |
| 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 |
| the next item). |
| \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 |
| argument. An example of a built-in method is |
| \code{\var{list}.append()}, assuming |
| \var{list} is a list object. |
| In this case, the special read-only attribute \member{__self__} is set |
| to the object denoted by \var{list}. |
| \obindex{built-in method} |
| \obindex{method} |
| \indexii{built-in}{method} |
| |
| \item[Classes] |
| Class objects are described below. When a class object is called, |
| a new class instance (also described below) is created and |
| 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__()} |
| method. If there is no \method{__init__()} method, the class must be called |
| without arguments. |
| \withsubitem{(object method)}{\ttindex{__init__()}} |
| \obindex{class} |
| \obindex{class instance} |
| \obindex{instance} |
| \indexii{class object}{call} |
| |
| \item[Class instances] |
| Class instances are described below. Class instances are callable |
| only when the class has a \method{__call__()} method; \code{x(arguments)} |
| is a shorthand for \code{x.__call__(arguments)}. |
| |
| \end{description} |
| |
| \item[Modules] |
| Modules are imported by the \keyword{import} statement (see section |
| \ref{import}, ``The \keyword{import} statement''). |
| A module object has a namespace implemented by a dictionary object |
| (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 |
| initialize the module (since it isn't needed once the initialization |
| is done). |
| \stindex{import} |
| \obindex{module} |
| |
| Attribute assignment updates the module's namespace dictionary, |
| e.g., \samp{m.x = 1} is equivalent to \samp{m.__dict__["x"] = 1}. |
| |
| Special read-only attribute: \member{__dict__} is the module's |
| namespace as a dictionary object. |
| \withsubitem{(module attribute)}{\ttindex{__dict__}} |
| |
| Predefined (writable) attributes: \member{__name__} |
| is the module's name; \member{__doc__} is the |
| module's documentation string, or |
| \code{None} if unavailable; \member{__file__} is the pathname of the |
| file from which the module was loaded, if it was loaded from a file. |
| The \member{__file__} attribute is not present for C{} modules that are |
| statically linked into the interpreter; for extension modules loaded |
| dynamically from a shared library, it is the pathname of the shared |
| library file. |
| \withsubitem{(module attribute)}{ |
| \ttindex{__name__} |
| \ttindex{__doc__} |
| \ttindex{__file__}} |
| \indexii{module}{namespace} |
| |
| \item[Classes] |
| Class objects are created by class definitions (see section |
| \ref{class}, ``Class definitions''). |
| A class has a namespace implemented by a dictionary object. |
| Class attribute references are translated to |
| lookups in this dictionary, |
| e.g., \samp{C.x} is translated to \samp{C.__dict__["x"]}. |
| When the attribute name is not found |
| there, the attribute search continues in the base classes. The search |
| is depth-first, left-to-right in the order of occurrence in the |
| base class list. |
| When a class attribute reference would yield a user-defined function |
| object, it is transformed into an unbound user-defined method object |
| (see above). The \member{im_class} attribute of this method object is the |
| class for which the attribute reference was initiated. |
| \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} |
| |
| A class object can be called (see above) to yield a class instance (see |
| below). |
| \indexii{class object}{call} |
| |
| Special attributes: \member{__name__} is the class name; |
| \member{__module__} is the module name in which the class was defined; |
| \member{__dict__} is the dictionary containing the class's namespace; |
| \member{__bases__} is a tuple (possibly empty or a singleton) |
| containing the base classes, in the order of their occurrence in the |
| base class list; \member{__doc__} is the class's documentation string, |
| or None if undefined. |
| \withsubitem{(class attribute)}{ |
| \ttindex{__name__} |
| \ttindex{__module__} |
| \ttindex{__dict__} |
| \ttindex{__bases__} |
| \ttindex{__doc__}} |
| |
| \item[Class instances] |
| 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 |
| attribute references are searched. When an attribute is not found |
| 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 |
| (see above). The \member{im_class} attribute of this method object is |
| 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 |
| \method{__getattr__()} method, that is called to satisfy the lookup. |
| \obindex{class instance} |
| \obindex{instance} |
| \indexii{class}{instance} |
| \indexii{class instance}{attribute} |
| |
| Attribute assignments and deletions update the instance's dictionary, |
| never a class's dictionary. If the class has a \method{__setattr__()} or |
| \method{__delattr__()} method, this is called instead of updating the |
| instance dictionary directly. |
| \indexiii{class instance}{attribute}{assignment} |
| |
| Class instances can pretend to be numbers, sequences, or mappings if |
| they have methods with certain special names. See |
| section \ref{specialnames}, ``Special method names.'' |
| \obindex{numeric} |
| \obindex{sequence} |
| \obindex{mapping} |
| |
| Special attributes: \member{__dict__} is the attribute |
| dictionary; \member{__class__} is the instance's class. |
| \withsubitem{(instance attribute)}{ |
| \ttindex{__dict__} |
| \ttindex{__class__}} |
| |
| \item[Files] |
| 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. |
| \withsubitem{(in module sys)}{ |
| \ttindex{stdin} |
| \ttindex{stdout} |
| \ttindex{stderr}} |
| |
| |
| \item[Internal types] |
| A few types used internally by the interpreter are exposed to the user. |
| Their definitions may change with future versions of the interpreter, |
| but they are mentioned here for completeness. |
| \index{internal type} |
| \index{types, internal} |
| |
| \begin{description} |
| |
| \item[Code objects] |
| Code objects represent \emph{byte-compiled} executable Python code, or |
| \emph{bytecode}. |
| The difference between a code |
| object and a function object is that the function object contains an |
| 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} |
| \obindex{code} |
| |
| 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_cellvars} is |
| a tuple containing the names of local variables that are referenced by |
| nested functions; \member{co_freevars} is a tuple containing the names |
| of free variables; \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 |
| byte code offsets to line numbers (for details see the source code of |
| 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. |
| |
| \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} |
| \ttindex{co_varnames} |
| \ttindex{co_cellvars} |
| \ttindex{co_freevars}} |
| |
| 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; bit \code{0x20} is set if the |
| function is a \obindex{generator}. |
| |
| Future feature declarations (\samp{from __future__ import division}) |
| also use bits in \member{co_flags} to indicate whether a code object |
| was compiled with a particular feature enabled: bit \code{0x2000} is |
| set if the function was compiled with future division enabled; bits |
| \code{0x10} and \code{0x1000} were used in earlier versions of Python. |
| |
| Other bits in \member{co_flags} are reserved for internal 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. |
| |
| \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 |
| frame; \member{f_locals} is the dictionary used to look up local |
| variables; \member{f_globals} is used for global variables; |
| \member{f_builtins} is used for built-in (intrinsic) names; |
| \member{f_restricted} is a flag indicating whether the function is |
| executing in restricted execution mode; |
| \member{f_lineno} gives the line number and \member{f_lasti} gives the |
| precise instruction (this is an index into the bytecode string of |
| the code object). |
| \withsubitem{(frame attribute)}{ |
| \ttindex{f_back} |
| \ttindex{f_code} |
| \ttindex{f_globals} |
| \ttindex{f_locals} |
| \ttindex{f_lineno} |
| \ttindex{f_lasti} |
| \ttindex{f_builtins} |
| \ttindex{f_restricted}} |
| |
| Special writable attributes: \member{f_trace}, if not \code{None}, is a |
| function called at the start of each source code line (this is used by |
| the debugger); \member{f_exc_type}, \member{f_exc_value}, |
| \member{f_exc_traceback} represent the most recent exception caught in |
| this frame. |
| \withsubitem{(frame attribute)}{ |
| \ttindex{f_trace} |
| \ttindex{f_exc_type} |
| \ttindex{f_exc_value} |
| \ttindex{f_exc_traceback}} |
| |
| \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 |
| 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 |
| (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} |
| \withsubitem{(in module sys)}{ |
| \ttindex{exc_info} |
| \ttindex{exc_traceback} |
| \ttindex{last_traceback}} |
| \ttindex{sys.exc_info} |
| \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. |
| \withsubitem{(traceback attribute)}{ |
| \ttindex{tb_next} |
| \ttindex{tb_frame} |
| \ttindex{tb_lineno} |
| \ttindex{tb_lasti}} |
| \stindex{try} |
| |
| \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 |
| \function{slice()}\bifuncindex{slice} function. |
| |
| Special read-only attributes: \member{start} is the lower bound; |
| \member{stop} is the upper bound; \member{step} is the step value; each is |
| \code{None} if omitted. These attributes can have any type. |
| \withsubitem{(slice object attribute)}{ |
| \ttindex{start} |
| \ttindex{stop} |
| \ttindex{step}} |
| |
| Slice objects support one method: |
| |
| \begin{methoddesc}[slice]{indices}{self, length} |
| This method takes a single integer argument \var{length} and computes |
| information about the extended slice that the slice object would |
| describe if applied to a sequence of \var{length} items. It returns a |
| tuple of three integers; respectively these are the \var{start} and |
| \var{stop} indices and the \var{step} or stride length of the slice. |
| Missing or out-of-bounds indices are handled in a manner consistent |
| with regular slices. |
| \versionadded{2.3} |
| \end{methoddesc} |
| |
| \end{description} % Internal types |
| |
| \end{description} % Types |
| |
| |
| \section{Special method names\label{specialnames}} |
| |
| A class can implement certain operations that are invoked by special |
| 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)}. Except where mentioned, attempts to execute |
| an operation raise an exception when no appropriate method is defined. |
| \withsubitem{(mapping object method)}{\ttindex{__getitem__()}} |
| |
| When implementing a class that emulates any built-in type, it is |
| important that the emulation only be implemented to the degree that it |
| makes sense for the object being modelled. For example, some |
| sequences may work well with retrieval of individual elements, but |
| extracting a slice may not make sense. (One example of this is the |
| \class{NodeList} interface in the W3C's Document Object Model.) |
| |
| |
| \subsection{Basic customization\label{customization}} |
| |
| \begin{methoddesc}[object]{__init__}{self\optional{, \moreargs}} |
| Called\indexii{class}{constructor} when the instance is created. The |
| arguments are those passed to the class constructor expression. If a |
| base class has an \method{__init__()} method the derived class's |
| \method{__init__()} method must explicitly call it to ensure proper |
| initialization of the base class part of the instance; for example: |
| \samp{BaseClass.__init__(\var{self}, [\var{args}...])}. As a special |
| contraint on constructors, no value may be returned; doing so will |
| cause a \exception{TypeError} to be raised at runtime. |
| \end{methoddesc} |
| |
| |
| \begin{methoddesc}[object]{__del__}{self} |
| Called when the instance is about to be destroyed. This is also |
| called a destructor\index{destructor}. If a base class |
| has a \method{__del__()} method, the derived class's \method{__del__()} method |
| must explicitly call it to ensure proper deletion of the base class |
| part of the instance. Note that it is possible (though not recommended!) |
| for the \method{__del__()} |
| 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} |
| |
| \begin{notice} |
| \samp{del x} doesn't directly call |
| \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 \code{None} in |
| \code{sys.exc_traceback} or \code{sys.last_traceback}. Circular |
| references which are garbage are detected when the option cycle |
| detector is enabled (it's on by default), but can only be cleaned up |
| if there are no Python-level \method{__del__()} methods involved. |
| Refer to the documentation for the \ulink{\module{gc} |
| module}{../lib/module-gc.html} for more information about how |
| \method{__del__()} methods are handled by the cycle detector, |
| particularly the description of the \code{garbage} value. |
| \end{notice} |
| |
| \begin{notice}[warning] |
| Due to the precarious circumstances under which |
| \method{__del__()} methods are invoked, exceptions that occur during their |
| execution are ignored, and a warning is printed to \code{sys.stderr} |
| instead. Also, when \method{__del__()} is invoked in response to a module |
| being deleted (e.g., when execution of the program is done), other |
| globals referenced by the \method{__del__()} method may already have been |
| deleted. For this reason, \method{__del__()} methods should do the |
| absolute minimum needed to maintain external invariants. Starting with |
| version 1.5, Python 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 |
| \method{__del__()} method is called. |
| \end{notice} |
| \end{methoddesc} |
| |
| \begin{methoddesc}[object]{__repr__}{self} |
| 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. If at all possible, this should |
| look like a valid Python expression that could be used to recreate an |
| object with the same value (given an appropriate environment). If |
| this is not possible, a string of the form \samp{<\var{...some useful |
| description...}>} should be returned. The return value must be a |
| string object. |
| |
| This is typically used for debugging, so it is important that the |
| representation is information-rich and unambiguous. |
| \indexii{string}{conversion} |
| \indexii{reverse}{quotes} |
| \indexii{backward}{quotes} |
| \index{back-quotes} |
| \end{methoddesc} |
| |
| \begin{methoddesc}[object]{__str__}{self} |
| Called by the \function{str()}\bifuncindex{str} built-in function and |
| by the \keyword{print}\stindex{print} statement to compute the |
| ``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. The return value must be a string object. |
| \end{methoddesc} |
| |
| \begin{methoddesc}[object]{__lt__}{self, other} |
| \methodline[object]{__le__}{self, other} |
| \methodline[object]{__eq__}{self, other} |
| \methodline[object]{__ne__}{self, other} |
| \methodline[object]{__gt__}{self, other} |
| \methodline[object]{__ge__}{self, other} |
| \versionadded{2.1} |
| These are the so-called ``rich comparison'' methods, and are called |
| for comparison operators in preference to \method{__cmp__()} below. |
| The correspondence between operator symbols and method names is as |
| follows: |
| \code{\var{x}<\var{y}} calls \code{\var{x}.__lt__(\var{y})}, |
| \code{\var{x}<=\var{y}} calls \code{\var{x}.__le__(\var{y})}, |
| \code{\var{x}==\var{y}} calls \code{\var{x}.__eq__(\var{y})}, |
| \code{\var{x}!=\var{y}} and \code{\var{x}<>\var{y}} call |
| \code{\var{x}.__ne__(\var{y})}, |
| \code{\var{x}>\var{y}} calls \code{\var{x}.__gt__(\var{y})}, and |
| \code{\var{x}>=\var{y}} calls \code{\var{x}.__ge__(\var{y})}. |
| These methods can return any value, but if the comparison operator is |
| used in a Boolean context, the return value should be interpretable as |
| a Boolean value, else a \exception{TypeError} will be raised. |
| By convention, \code{0} is used for false and \code{1} for true. |
| |
| There are no reflected (swapped-argument) versions of these methods |
| (to be used when the left argument does not support the operation but |
| the right argument does); rather, \method{__lt__()} and |
| \method{__gt__()} are each other's reflection, \method{__le__()} and |
| \method{__ge__()} are each other's reflection, and \method{__eq__()} |
| and \method{__ne__()} are their own reflection. |
| |
| Arguments to rich comparison methods are never coerced. A rich |
| comparison method may return \code{NotImplemented} if it does not |
| implement the operation for a given pair of arguments. |
| \end{methoddesc} |
| |
| \begin{methoddesc}[object]{__cmp__}{self, other} |
| Called by comparison operations if rich comparison (see above) is not |
| defined. 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__()}, \method{__eq__()} or |
| \method{__ne__()} operation is defined, class instances are compared |
| by object identity (``address''). See also the description of |
| \method{__hash__()} for some important notes on creating objects which |
| support custom comparison operations and are usable as dictionary |
| keys. |
| (Note: the restriction that exceptions are not propagated by |
| \method{__cmp__()} has been removed in Python 1.5.) |
| \bifuncindex{cmp} |
| \index{comparisons} |
| \end{methoddesc} |
| |
| \begin{methoddesc}[object]{__rcmp__}{self, other} |
| \versionchanged[No longer supported]{2.1} |
| \end{methoddesc} |
| |
| \begin{methoddesc}[object]{__hash__}{self} |
| Called for the key object for dictionary\obindex{dictionary} |
| operations, and by the built-in function |
| \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 |
| mix together (e.g., using exclusive or) the hash values for the |
| 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__()} or \method{__eq__()} but not \method{__hash__()}, |
| its instances will not be usable as dictionary keys. If a class |
| defines mutable objects and implements a \method{__cmp__()} or |
| \method{__eq__()} method, it should not implement \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). |
| \withsubitem{(object method)}{\ttindex{__cmp__()}} |
| \end{methoddesc} |
| |
| \begin{methoddesc}[object]{__nonzero__}{self} |
| Called to implement truth value testing, and the built-in operation |
| \code{bool()}; should return \code{False} or \code{True}, or their |
| integer equivalents \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. |
| \withsubitem{(mapping object method)}{\ttindex{__len__()}} |
| \end{methoddesc} |
| |
| \begin{methoddesc}[object]{__unicode__}{self} |
| Called to implement \function{unicode()}\bifuncindex{unicode} builtin; |
| should return a Unicode object. When this method is not defined, string |
| conversion is attempted, and the result of string conversion is converted |
| to Unicode using the system default encoding. |
| \end{methoddesc} |
| |
| |
| \subsection{Customizing attribute access\label{attribute-access}} |
| |
| 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. |
| |
| \begin{methoddesc}[object]{__getattr__}{self, name} |
| 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. |
| This method should return the (computed) attribute value or raise an |
| \exception{AttributeError} exception. |
| |
| Note that if the attribute is found through the normal mechanism, |
| \method{__getattr__()} is not called. (This is an intentional |
| asymmetry between \method{__getattr__()} and \method{__setattr__()}.) |
| This is done both for efficiency reasons and because otherwise |
| \method{__setattr__()} would have no way to access other attributes of |
| the instance. |
| 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). |
| \withsubitem{(object method)}{\ttindex{__setattr__()}} |
| \end{methoddesc} |
| |
| \begin{methoddesc}[object]{__setattr__}{self, name, value} |
| Called when an attribute assignment is attempted. This is called |
| instead of the normal mechanism (i.e.\ store the value in the instance |
| dictionary). \var{name} is the attribute name, \var{value} is the |
| value to be assigned to it. |
| |
| 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}. |
| \withsubitem{(instance attribute)}{\ttindex{__dict__}} |
| \end{methoddesc} |
| |
| \begin{methoddesc}[object]{__delattr__}{self, name} |
| Like \method{__setattr__()} but for attribute deletion instead of |
| assignment. This should only be implemented if \samp{del |
| obj.\var{name}} is meaningful for the object. |
| \end{methoddesc} |
| |
| |
| \subsection{Emulating callable objects\label{callable-types}} |
| |
| \begin{methoddesc}[object]{__call__}{self\optional{, args...}} |
| Called when the instance is ``called'' as a function; if this method |
| is defined, \code{\var{x}(arg1, arg2, ...)} is a shorthand for |
| \code{\var{x}.__call__(arg1, arg2, ...)}. |
| \indexii{call}{instance} |
| \end{methoddesc} |
| |
| |
| \subsection{Emulating container types\label{sequence-types}} |
| |
| The following methods can be defined to implement container |
| objects. Containers usually are sequences (such as lists or tuples) |
| or mappings (like dictionaries), but can represent other containers as |
| well. 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 |
| 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 |
| that mappings provide the methods \method{keys()}, \method{values()}, |
| \method{items()}, \method{has_key()}, \method{get()}, \method{clear()}, |
| \method{copy()}, and \method{update()} behaving similar to those for |
| 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 |
| \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. It is recommended that both mappings and sequences |
| implement the \method{__contains__()} method to allow efficient use of |
| the \code{in} operator; for mappings, \code{in} should be equivalent |
| of \method{has_key()}; for sequences, it should search through the |
| values. |
| \withsubitem{(mapping object method)}{ |
| \ttindex{keys()} |
| \ttindex{values()} |
| \ttindex{items()} |
| \ttindex{has_key()} |
| \ttindex{get()} |
| \ttindex{clear()} |
| \ttindex{copy()} |
| \ttindex{update()} |
| \ttindex{__contains__()}} |
| \withsubitem{(sequence object method)}{ |
| \ttindex{append()} |
| \ttindex{count()} |
| \ttindex{index()} |
| \ttindex{insert()} |
| \ttindex{pop()} |
| \ttindex{remove()} |
| \ttindex{reverse()} |
| \ttindex{sort()} |
| \ttindex{__add__()} |
| \ttindex{__radd__()} |
| \ttindex{__iadd__()} |
| \ttindex{__mul__()} |
| \ttindex{__rmul__()} |
| \ttindex{__imul__()} |
| \ttindex{__contains__()}} |
| \withsubitem{(numeric object method)}{\ttindex{__coerce__()}} |
| |
| \begin{methoddesc}[container object]{__len__}{self} |
| 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. |
| \withsubitem{(object method)}{\ttindex{__nonzero__()}} |
| \end{methoddesc} |
| |
| \begin{methoddesc}[container object]{__getitem__}{self, key} |
| Called to implement evaluation of \code{\var{self}[\var{key}]}. |
| For sequence types, the accepted keys should be integers and slice |
| objects.\obindex{slice} Note that |
| the special interpretation of negative indexes (if the class wishes to |
| emulate a sequence type) is up to the \method{__getitem__()} method. |
| 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. |
| \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.} |
| \end{methoddesc} |
| |
| \begin{methoddesc}[container object]{__setitem__}{self, key, value} |
| Called to implement assignment to \code{\var{self}[\var{key}]}. Same |
| 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 |
| replaced. The same exceptions should be raised for improper |
| \var{key} values as for the \method{__getitem__()} method. |
| \end{methoddesc} |
| |
| \begin{methoddesc}[container object]{__delitem__}{self, key} |
| Called to implement deletion of \code{\var{self}[\var{key}]}. Same |
| note as for \method{__getitem__()}. This should only be implemented |
| for mappings if the objects support removal of keys, or for sequences |
| 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. |
| \end{methoddesc} |
| |
| \begin{methoddesc}[container object]{__iter__}{self} |
| This method is called when an iterator is required for a container. |
| This method should return a new iterator object that can iterate over |
| all the objects in the container. For mappings, it should iterate |
| over the keys of the container, and should also be made available as |
| the method \method{iterkeys()}. |
| |
| Iterator objects also need to implement this method; they are required |
| to return themselves. For more information on iterator objects, see |
| ``\ulink{Iterator Types}{../lib/typeiter.html}'' in the |
| \citetitle[../lib/lib.html]{Python Library Reference}. |
| \end{methoddesc} |
| |
| The membership test operators (\keyword{in} and \keyword{not in}) are |
| normally implemented as an iteration through a sequence. However, |
| container objects can supply the following special method with a more |
| efficient implementation, which also does not require the object be a |
| sequence. |
| |
| \begin{methoddesc}[container object]{__contains__}{self, item} |
| Called to implement membership test operators. Should return true if |
| \var{item} is in \var{self}, false otherwise. For mapping objects, |
| this should consider the keys of the mapping rather than the values or |
| the key-item pairs. |
| \end{methoddesc} |
| |
| |
| \subsection{Additional methods for emulation of sequence types |
| \label{sequence-methods}} |
| |
| 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. |
| |
| \begin{methoddesc}[sequence object]{__getslice__}{self, i, j} |
| \deprecated{2.0}{Support slice objects as parameters to the |
| \method{__getitem__()} method.} |
| 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 |
| 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. |
| If no \method{__getslice__()} is found, a slice |
| object is created instead, and passed to \method{__getitem__()} instead. |
| \end{methoddesc} |
| |
| \begin{methoddesc}[sequence object]{__setslice__}{self, i, j, sequence} |
| Called to implement assignment to \code{\var{self}[\var{i}:\var{j}]}. |
| Same notes for \var{i} and \var{j} as for \method{__getslice__()}. |
| |
| This method is deprecated. If no \method{__setslice__()} is found, a |
| slice object is created instead, and passed to \method{__setitem__()} |
| instead. |
| \end{methoddesc} |
| |
| \begin{methoddesc}[sequence object]{__delslice__}{self, i, j} |
| Called to implement deletion of \code{\var{self}[\var{i}:\var{j}]}. |
| Same notes for \var{i} and \var{j} as for \method{__getslice__()}. |
| This method is deprecated. If no \method{__delslice__()} is found, a |
| slice object is created instead, and passed to \method{__delitem__()} |
| instead. |
| \end{methoddesc} |
| |
| 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. |
| |
| The following example demonstrate how to make your program or module |
| compatible with earlier versions of Python (assuming that methods |
| \method{__getitem__()}, \method{__setitem__()} and \method{__delitem__()} |
| support slice objects as arguments): |
| |
| \begin{verbatim} |
| class MyClass: |
| ... |
| def __getitem__(self, index): |
| ... |
| def __setitem__(self, index, value): |
| ... |
| def __delitem__(self, index): |
| ... |
| |
| if sys.version_info < (2, 0): |
| # They won't be defined if version is at least 2.0 final |
| |
| def __getslice__(self, i, j): |
| return self[max(0, i):max(0, j):] |
| def __setslice__(self, i, j, seq): |
| self[max(0, i):max(0, j):] = seq |
| def __delslice__(self, i, j): |
| del self[max(0, i):max(0, j):] |
| ... |
| \end{verbatim} |
| |
| Note the calls to \function{max()}; these are actually necessary due |
| to the handling of negative indices before the |
| \method{__*slice__()} methods are called. When negative indexes are |
| used, the \method{__*item__()} methods receive them as provided, but |
| the \method{__*slice__()} methods get a ``cooked'' form of the index |
| values. For each negative index value, the length of the sequence is |
| added to the index before calling the method (which may still result |
| in a negative index); this is the customary handling of negative |
| indexes by the built-in sequence types, and the \method{__*item__()} |
| methods are expected to do this as well. However, since they should |
| already be doing that, negative indexes cannot be passed in; they must |
| be be constrained to the bounds of the sequence before being passed to |
| the \method{__*item__()} methods. |
| Calling \code{max(0, i)} conveniently returns the proper value. |
| |
| |
| \subsection{Emulating numeric types\label{numeric-types}} |
| |
| 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. |
| |
| \begin{methoddesc}[numeric object]{__add__}{self, other} |
| \methodline[numeric object]{__sub__}{self, other} |
| \methodline[numeric object]{__mul__}{self, other} |
| \methodline[numeric object]{__floordiv__}{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} |
| These methods are |
| called to implement the binary arithmetic operations (\code{+}, |
| \code{-}, \code{*}, \code{//}, \code{\%}, |
| \function{divmod()}\bifuncindex{divmod}, |
| \function{pow()}\bifuncindex{pow}, \code{**}, \code{<}\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. The \method{__divmod__()} |
| method should be the equivalent to using \method{__floordiv__()} and |
| \method{__mod__()}; it should not be related to \method{__truediv__()} |
| (described below). 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. |
| \end{methoddesc} |
| |
| \begin{methoddesc}[numeric object]{__div__}{self, other} |
| \methodline[numeric object]{__truediv__}{self, other} |
| The division operator (\code{/}) is implemented by these methods. The |
| \method{__truediv__()} method is used when \code{__future__.division} |
| is in effect, otherwise \method{__div__()} is used. If only one of |
| these two methods is defined, the object will not support division in |
| the alternate context; \exception{TypeError} will be raised instead. |
| \end{methoddesc} |
| |
| \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]{__rtruediv__}{self, other} |
| \methodline[numeric object]{__rfloordiv__}{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} |
| These methods are |
| called to implement the binary arithmetic operations (\code{+}, |
| \code{-}, \code{*}, \code{/}, \code{\%}, |
| \function{divmod()}\bifuncindex{divmod}, |
| \function{pow()}\bifuncindex{pow}, \code{**}, \code{<}\code{<}, |
| \code{>}\code{>}, \code{\&}, \code{\^}, \code{|}) with reflected |
| (swapped) 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 |
| complicated). |
| \end{methoddesc} |
| |
| \begin{methoddesc}[numeric object]{__iadd__}{self, other} |
| \methodline[numeric object]{__isub__}{self, other} |
| \methodline[numeric object]{__imul__}{self, other} |
| \methodline[numeric object]{__idiv__}{self, other} |
| \methodline[numeric object]{__itruediv__}{self, other} |
| \methodline[numeric object]{__ifloordiv__}{self, other} |
| \methodline[numeric object]{__imod__}{self, other} |
| \methodline[numeric object]{__ipow__}{self, other\optional{, modulo}} |
| \methodline[numeric object]{__ilshift__}{self, other} |
| \methodline[numeric object]{__irshift__}{self, other} |
| \methodline[numeric object]{__iand__}{self, other} |
| \methodline[numeric object]{__ixor__}{self, other} |
| \methodline[numeric object]{__ior__}{self, other} |
| These methods are called to implement the augmented arithmetic |
| operations (\code{+=}, \code{-=}, \code{*=}, \code{/=}, \code{\%=}, |
| \code{**=}, \code{<}\code{<=}, \code{>}\code{>=}, \code{\&=}, |
| \code{\^=}, \code{|=}). These methods should attempt to do the |
| operation in-place (modifying \var{self}) and return the result (which |
| could be, but does not have to be, \var{self}). If a specific method |
| is not defined, the augmented operation falls back to the normal |
| methods. For instance, to evaluate the expression |
| \var{x}\code{+=}\var{y}, where \var{x} is an instance of a class that |
| has an \method{__iadd__()} method, \code{\var{x}.__iadd__(\var{y})} is |
| called. If \var{x} is an instance of a class that does not define a |
| \method{__iadd()} method, \code{\var{x}.__add__(\var{y})} and |
| \code{\var{y}.__radd__(\var{x})} are considered, as with the |
| evaluation of \var{x}\code{+}\var{y}. |
| \end{methoddesc} |
| |
| \begin{methoddesc}[numeric object]{__neg__}{self} |
| \methodline[numeric object]{__pos__}{self} |
| \methodline[numeric object]{__abs__}{self} |
| \methodline[numeric object]{__invert__}{self} |
| Called to implement the unary arithmetic operations (\code{-}, |
| \code{+}, \function{abs()}\bifuncindex{abs} and \code{\~{}}). |
| \end{methoddesc} |
| |
| \begin{methoddesc}[numeric object]{__complex__}{self} |
| \methodline[numeric object]{__int__}{self} |
| \methodline[numeric object]{__long__}{self} |
| \methodline[numeric object]{__float__}{self} |
| Called to implement the built-in functions |
| \function{complex()}\bifuncindex{complex}, |
| \function{int()}\bifuncindex{int}, \function{long()}\bifuncindex{long}, |
| and \function{float()}\bifuncindex{float}. Should return a value of |
| the appropriate type. |
| \end{methoddesc} |
| |
| \begin{methoddesc}[numeric object]{__oct__}{self} |
| \methodline[numeric object]{__hex__}{self} |
| Called to implement the built-in functions |
| \function{oct()}\bifuncindex{oct} and |
| \function{hex()}\bifuncindex{hex}. Should return a string value. |
| \end{methoddesc} |
| |
| \begin{methoddesc}[numeric object]{__coerce__}{self, other} |
| Called to implement ``mixed-mode'' numeric arithmetic. Should either |
| return a 2-tuple containing \var{self} and \var{other} converted to |
| a common numeric type, or \code{None} if conversion is impossible. When |
| 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). A return value of \code{NotImplemented} is |
| equivalent to returning \code{None}. |
| \end{methoddesc} |
| |
| \subsection{Coercion rules\label{coercion-rules}} |
| |
| This section used to document the rules for coercion. As the language |
| has evolved, the coercion rules have become hard to document |
| precisely; documenting what one version of one particular |
| implementation does is undesirable. Instead, here are some informal |
| guidelines regarding coercion. In Python 3.0, coercion will not be |
| supported. |
| |
| \begin{itemize} |
| |
| \item |
| |
| If the left operand of a \% operator is a string or Unicode object, no |
| coercion takes place and the string formatting operation is invoked |
| instead. |
| |
| \item |
| |
| It is no longer recommended to define a coercion operation. |
| Mixed-mode operations on types that don't define coercion pass the |
| original arguments to the operation. |
| |
| \item |
| |
| New-style classes (those derived from \class{object}) never invoke the |
| \method{__coerce__()} method in response to a binary operator; the only |
| time \method{__coerce__()} is invoked is when the built-in function |
| \function{coerce()} is called. |
| |
| \item |
| |
| For most intents and purposes, an operator that returns |
| \code{NotImplemented} is treated the same as one that is not |
| implemented at all. |
| |
| \item |
| |
| Below, \method{__op__()} and \method{__rop__()} are used to signify |
| the generic method names corresponding to an operator; |
| \method{__iop__} is used for the corresponding in-place operator. For |
| example, for the operator `\code{+}', \method{__add__()} and |
| \method{__radd__()} are used for the left and right variant of the |
| binary operator, and \method{__iadd__} for the in-place variant. |
| |
| \item |
| |
| For objects \var{x} and \var{y}, first \code{\var{x}.__op__(\var{y})} |
| is tried. If this is not implemented or returns \code{NotImplemented}, |
| \code{\var{y}.__rop__(\var{x})} is tried. If this is also not |
| implemented or returns \code{NotImplemented}, a \exception{TypeError} |
| exception is raised. But see the following exception: |
| |
| \item |
| |
| Exception to the previous item: if the left operand is an instance of |
| a built-in type or a new-style class, and the right operand is an |
| instance of a proper subclass of that type or class, the right |
| operand's \method{__rop__()} method is tried \emph{before} the left |
| operand's \method{__op__()} method. This is done so that a subclass can |
| completely override binary operators. Otherwise, the left operand's |
| __op__ method would always accept the right operand: when an instance |
| of a given class is expected, an instance of a subclass of that class |
| is always acceptable. |
| |
| \item |
| |
| When either operand type defines a coercion, this coercion is called |
| before that type's \method{__op__()} or \method{__rop__()} method is |
| called, but no sooner. If the coercion returns an object of a |
| different type for the operand whose coercion is invoked, part of the |
| process is redone using the new object. |
| |
| \item |
| |
| When an in-place operator (like `\code{+=}') is used, if the left |
| operand implements \method{__iop__()}, it is invoked without any |
| coercion. When the operation falls back to \method{__op__()} and/or |
| \method{__rop__()}, the normal coercion rules apply. |
| |
| \item |
| |
| In \var{x}\code{+}\var{y}, if \var{x} is a sequence that implements |
| sequence concatenation, sequence concatenation is invoked. |
| |
| \item |
| |
| In \var{x}\code{*}\var{y}, if one operator is a sequence that |
| implements sequence repetition, and the other is an integer |
| (\class{int} or \class{long}), sequence repetition is invoked. |
| |
| \item |
| |
| Rich comparisons (implemented by methods \method{__eq__()} and so on) |
| never use coercion. Three-way comparison (implemented by |
| \method{__cmp__()}) does use coercion under the same conditions as |
| other binary operations use it. |
| |
| \item |
| |
| In the current implementation, the built-in numeric types \class{int}, |
| \class{long} and \class{float} do not use coercion; the type |
| \class{complex} however does use it. The difference can become |
| apparent when subclassing these types. Over time, the type |
| \class{complex} may be fixed to avoid coercion. All these types |
| implement a \method{__coerce__()} method, for use by the built-in |
| \function{coerce()} function. |
| |
| \end{itemize} |