| \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 `\code{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}. |
| 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 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. |
| 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. 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} |
| \withsubitem{(built-in object attribute)}{ |
| \ttindex{__methods__} |
| \ttindex{__members__}} |
| |
| \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[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. |
| \ttindex{Ellipsis} |
| \obindex{Ellipsis@{\texttt{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{number} |
| \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.) |
| When the result of an operation falls 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} |
| |
| \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 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. |
| \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 natural numbers. |
| The built-in function \function{len()}\bifuncindex{len} returns the |
| number of items of a sequence. |
| When the lenth 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{seqence} |
| \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} |
| |
| 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[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 sequece} |
| \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 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''). |
| \obindex{dictionary} |
| \obindex{mutable} |
| |
| 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 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} |
| \obindex{callable} |
| |
| \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 read-only 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. 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{func_defaults} |
| \ttindex{func_code} |
| \ttindex{func_globals}} |
| \indexii{global}{namespace} |
| |
| \item[User-defined methods] |
| A user-defined method object combines a class, a class instance (or |
| \code{None}) and 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 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 |
| \code{im_func.__name__}). |
| \withsubitem{(method attribute)}{ |
| \ttindex{im_func} |
| \ttindex{im_self}} |
| |
| 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 attributes of a class instance that is a user-defined |
| function object. 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 contains a definition for a |
| function \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. |
| |
| \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 \code{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 in which the function object was found, not necessarily 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 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 |
| \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{number} |
| \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 object represents an open file. File objects are created by the |
| \function{open()} built-in function, and also by |
| \function{os.popen()}, \function{os.fdopen()}, and the |
| \method{makefile()} method of socket objects (and perhaps by other |
| functions or methods provided by extension modules). The objects |
| \code{sys.stdin}, \code{sys.stdout} and \code{sys.stderr} are |
| initialized to file objects corresponding to the interpreter's |
| standard input, output and error streams. See the \emph{Python |
| Library Reference} for complete documentation of file objects. |
| \obindex{file} |
| \indexii{C}{language} |
| \index{stdio} |
| \bifuncindex{open} |
| \withsubitem{(in module os)}{\ttindex{popen()}} |
| \withsubitem{(socket method)}{\ttindex{makefile()}} |
| \withsubitem{(in module sys)}{ |
| \ttindex{stdin} |
| \ttindex{stdout} |
| \ttindex{stderr}} |
| \ttindex{sys.stdin} |
| \ttindex{sys.stdout} |
| \ttindex{sys.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_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 detais 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}} |
| |
| The following flag bits are defined for \member{co_flags}: bit 2 is set |
| if the function uses the \samp{*arguments} syntax to accept an |
| arbitrary number of positional arguments; bit 3 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 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. |
| \index{documentation string} |
| |
| \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 lowerbound; |
| \member{stop} is the upperbound; \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}} |
| |
| \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)}. (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 |
| operation raise an exception when no appropriate method is defined. |
| \withsubitem{(mapping object method)}{\ttindex{__getitem__()}} |
| |
| |
| \subsection{Basic customization\label{customization}} |
| |
| \begin{methoddesc}[object]{__init__}{self\optional{, args...}} |
| Called 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, e.g., \samp{BaseClass.__init__(\var{self}, |
| [\var{args}...])}. |
| \indexii{class}{constructor} |
| \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} |
| |
| \strong{Programmer's note:} \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 None in |
| \code{sys.exc_traceback} or \code{sys.last_traceback}. |
| |
| \strong{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 is 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. 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 |
| \method{__del__()} method is called. |
| \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. 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...}>}. |
| \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. |
| \end{methoddesc} |
| |
| \begin{methoddesc}[object]{__cmp__}{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} |
| |
| \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__()} 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 |
| \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; 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. |
| \withsubitem{(mapping object method)}{\ttindex{__len__()}} |
| \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 sequence and mapping types\label{sequence-types}} |
| |
| 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 |
| sequence, and the method \method{__getslice__()} (see below) should be |
| defined. It is also recommended that mappings provide 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{__mul__()} and |
| \method{__rmul__()} described below; they should not define |
| \method{__coerce__()} or other numerical operators. |
| \withsubitem{(mapping object method)}{ |
| \ttindex{keys()} |
| \ttindex{values()} |
| \ttindex{items()} |
| \ttindex{has_key()} |
| \ttindex{get()} |
| \ttindex{clear()} |
| \ttindex{copy()} |
| \ttindex{update()}} |
| \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{__mul__()} |
| \ttindex{__rmul__()}} |
| \withsubitem{(numberic object method)}{\ttindex{__coerce__()}} |
| |
| \begin{methoddesc}[mapping 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}[mapping object]{__getitem__}{self, key} |
| Called to implement evaluation of \code{\var{self}[\var{key}]}. |
| For a sequence types, the accepted keys should be integers. Note that the |
| special interpretation of negative indices (if the class wishes to |
| emulate a sequence type) is up to the \method{__getitem__()} method. |
| \end{methoddesc} |
| |
| \begin{methoddesc}[mapping 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. |
| \end{methoddesc} |
| |
| \begin{methoddesc}[mapping 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. |
| \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} |
| 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, and no further |
| transformations on the indices is performed. The interpretation of |
| negative indices and indices larger than the length of the sequence is |
| up to the method. |
| \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__()}. |
| \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__()}. |
| \end{methoddesc} |
| |
| Notice that these methods are only invoked when a single slice with a |
| single colon is used. For slice operations involving extended slice |
| notation, \method{__getitem__()}, \method{__setitem__()} |
| or\method{__delitem__()} is called. |
| |
| \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}[numberic interface]{__add__}{self, other} |
| \methodline{__sub__}{self, other} |
| \methodline{__mul__}{self, other} |
| \methodline{__div__}{self, other} |
| \methodline{__mod__}{self, other} |
| \methodline{__divmod__}{self, other} |
| \methodline{__pow__}{self, other\optional{, modulo}} |
| \methodline{__lshift__}{self, other} |
| \methodline{__rshift__}{self, other} |
| \methodline{__and__}{self, other} |
| \methodline{__xor__}{self, other} |
| \methodline{__or__}{self, other} |
| These functions 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{|}). 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. |
| \end{methoddesc} |
| |
| \begin{methoddesc}[numeric interface]{__radd__}{self, other} |
| \methodline{__rsub__}{self, other} |
| \methodline{__rmul__}{self, other} |
| \methodline{__rdiv__}{self, other} |
| \methodline{__rmod__}{self, other} |
| \methodline{__rdivmod__}{self, other} |
| \methodline{__rpow__}{self, other} |
| \methodline{__rlshift__}{self, other} |
| \methodline{__rrshift__}{self, other} |
| \methodline{__rand__}{self, other} |
| \methodline{__rxor__}{self, other} |
| \methodline{__ror__}{self, other} |
| These functions 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{|}) 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 |
| complicated). |
| \end{methoddesc} |
| |
| \begin{methoddesc}[numeric interface]{__neg__}{self} |
| \methodline{__pos__}{self} |
| \methodline{__abs__}{self} |
| \methodline{__invert__}{self} |
| Called to implement the unary arithmetic operations (\code{-}, \code{+}, |
| \function{abs()}\bifuncindex{abs} and \code{~}). |
| \end{methoddesc} |
| |
| \begin{methoddesc}[numeric interface]{__int__}{self} |
| \methodlineni{__long__}{self} |
| \methodlineni{__float__}{self} |
| Called to implement the built-in functions |
| \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 interface]{__oct__}{self} |
| \methodlineni{__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 interface]{__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 possible. 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). |
| \end{methoddesc} |
| |
| \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}, |
| e.g., if var{op} is `\code{+}', \method{__add__()} and |
| \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} |