diff options
Diffstat (limited to 'Doc/ref/ref3.tex')
| -rw-r--r-- | Doc/ref/ref3.tex | 2230 |
1 files changed, 0 insertions, 2230 deletions
diff --git a/Doc/ref/ref3.tex b/Doc/ref/ref3.tex deleted file mode 100644 index 14b259461c..0000000000 --- a/Doc/ref/ref3.tex +++ /dev/null @@ -1,2230 +0,0 @@ -\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.\footnote{Since Python 2.2, a gradual merging of -types and classes has been started that makes this and a few other -assertions made in this manual not 100\% accurate and complete: -for example, it \emph{is} now possible in some cases to change an -object's type, under certain controlled conditions. Until this manual -undergoes extensive revision, it must now be taken as authoritative -only regarding ``classic classes'', that are still the default, for -compatibility purposes, in Python 2.2 and 2.3. For more information, -see \url{http://www.python.org/doc/newstyle.html}.} -An object's type determines the operations that the 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 -cyclically 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, Java, or other languages, depending on -the implementation) 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. -\obindex{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. -\obindex{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 integers -(positive and negative). -\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 -result is normally returned as a long integer (in some cases, the -exception \exception{OverflowError} is raised instead). -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. Any operation except left shift, -if it yields a result in the plain integer domain without causing -overflow, 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 or Java 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} -\indexii{Java}{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 parts of a complex -number \code{z} can be retrieved through the read-only 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 intrinsic 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[Set types] -These represent unordered, finite sets of unique, immutable objects. -As such, they cannot be indexed by any subscript. However, they can be -iterated over, and the built-in function \function{len()} returns the -number of items in a set. Common uses for sets are -fast membership testing, removing duplicates from a sequence, and -computing mathematical operations such as intersection, union, difference, -and symmetric difference. -\bifuncindex{len} -\obindex{set type} - -For set elements, the same immutability rules apply as for dictionary -keys. Note that numeric types obey the normal rules for numeric -comparison: if two numbers compare equal (e.g., \code{1} and -\code{1.0}), only one of them can be contained in a set. - -There are currently two intrinsic set types: - -\begin{description} - -\item[Sets] -These\obindex{set} represent a mutable set. They are created by the -built-in \function{set()} constructor and can be modified afterwards -by several methods, such as \method{add()}. - -\item[Frozen sets] -These\obindex{frozenset} represent an immutable set. They are created by -the built-in \function{frozenset()} constructor. As a frozenset is -immutable and hashable, it can be used again as an element of another set, -or as a dictionary key. - -\end{description} % Set types - - -\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 can be created by the -\code{\{...\}} notation (see section~\ref{dict}, ``Dictionary -Displays''). - -The extension modules \module{dbm}\refstmodindex{dbm}, -\module{gdbm}\refstmodindex{gdbm}, and -\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: - -\begin{tableiii}{lll}{member}{Attribute}{Meaning}{} - \lineiii{func_doc}{The function's documentation string, or - \code{None} if unavailable}{Writable} - - \lineiii{__doc__}{Another way of spelling - \member{func_doc}}{Writable} - - \lineiii{func_name}{The function's name}{Writable} - - \lineiii{__name__}{Another way of spelling - \member{func_name}}{Writable} - - \lineiii{__module__}{The name of the module the function was defined - in, or \code{None} if unavailable.}{Writable} - - \lineiii{func_defaults}{A tuple containing default argument values - for those arguments that have defaults, or \code{None} if no - arguments have a default value}{Writable} - - \lineiii{func_code}{The code object representing the compiled - function body.}{Writable} - - \lineiii{func_globals}{A reference to the dictionary that holds the - function's global variables --- the global namespace of the module - in which the function was defined.}{Read-only} - - \lineiii{func_dict}{The namespace supporting arbitrary function - attributes.}{Writable} - - \lineiii{func_closure}{\code{None} or a tuple of cells that contain - bindings for the function's free variables.}{Read-only} -\end{tableiii} - -Most of the attributes labelled ``Writable'' check the type of the -assigned value. - -\versionchanged[\code{func_name} is now writable]{2.4} - -Function objects also support getting and setting arbitrary -attributes, which can be used, for example, to attach metadata to -functions. Regular attribute dot-notation is used to get and set such -attributes. \emph{Note that the current implementation only supports -function attributes on user-defined functions. Function attributes on -built-in functions may be supported in the future.} - -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{__module__} - \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__}); \member{__module__} is the name of the -module the method was defined in, or \code{None} if unavailable. -\versionchanged[\member{im_self} used to refer to the class that - defined the method]{2.2} -\withsubitem{(method attribute)}{ - \ttindex{__doc__} - \ttindex{__name__} - \ttindex{__module__} - \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 may be created when getting an attribute -of a class (perhaps via an instance of that class), if that attribute -is a user-defined function object, an unbound user-defined method object, -or a class method object. -When the attribute is a user-defined method object, a new -method object is only created if the class from which it is being -retrieved is the same as, or a derived class of, the class stored -in the original method object; otherwise, the original method object -is used as it is. - -When a user-defined method object is created by retrieving -a user-defined function object from a class, its \member{im_self} -attribute is \code{None} and the method object is said to be unbound. -When one is created by retrieving a user-defined function object -from a class via one of its instances, its \member{im_self} attribute -is the instance, and the method object is said to be bound. -In either case, the new method's \member{im_class} attribute -is the class from which the retrieval takes place, and -its \member{im_func} attribute is the original function object. -\withsubitem{(method attribute)}{ - \ttindex{im_class}\ttindex{im_func}\ttindex{im_self}} - -When a user-defined method object is created by retrieving another -method object from a class or instance, the behaviour is the same -as for a function object, except that the \member{im_func} attribute -of the new instance is not the original method object but its -\member{im_func} attribute. -\withsubitem{(method attribute)}{ - \ttindex{im_func}} - -When a user-defined method object is created by retrieving a -class method object from a class or instance, its \member{im_self} -attribute is the class itself (the same as the \member{im_class} -attribute), and its \member{im_func} attribute is the function -object underlying the class method. -\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)}. - -When a user-defined method object is derived from a class method object, -the ``class instance'' stored in \member{im_self} will actually be the -class itself, so that calling either \code{x.f(1)} or \code{C.f(1)} is -equivalent to calling \code{f(C,1)} where \code{f} is the underlying -function. - -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); \member{__module__} is the name of the module the -function was defined in or \code{None} if unavailable. -\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{alist}.append()}, assuming -\var{alist} 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[Class Types] -Class types, or ``new-style classes,'' are callable. These objects -normally act as factories for new instances of themselves, but -variations are possible for class types that override -\method{__new__()}. The arguments of the call are passed to -\method{__new__()} and, in the typical case, to \method{__init__()} to -initialize the new instance. - -\item[Classic 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'').% -\stindex{import}\obindex{module} -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). - -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 (for class \class{C}, say) -would yield a user-defined function object or -an unbound user-defined method object whose associated class is either -\class{C} or one of its base classes, it is transformed into an unbound -user-defined method object whose \member{im_class} attribute is~\class{C}. -When it would yield a class method object, it is transformed into -a bound user-defined method object whose \member{im_class} and -\member{im_self} attributes are both~\class{C}. When it would yield -a static method object, it is transformed into the object wrapped -by the static method object. See section~\ref{descriptors} for another -way in which attributes retrieved from a class may differ from those -actually contained in its \member{__dict__}. -\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 or an unbound -user-defined method object whose associated class is the class -(call it~\class{C}) of the instance for which the attribute reference -was initiated or one of its bases, -it is transformed into a bound user-defined method object whose -\member{im_class} attribute is~\class{C} and whose \member{im_self} attribute -is the instance. Static method and class method objects are also -transformed, as if they had been retrieved from class~\class{C}; -see above under ``Classes''. See section~\ref{descriptors} for -another way in which attributes of a class retrieved via its -instances may differ from the objects actually stored in the -class's \member{__dict__}. -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 generator. -\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_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_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 last exception raised in the -parent frame provided another exception was ever raised in the current -frame (in all other cases they are None); \member{f_lineno} is the -current line number of the frame --- writing to this from within a -trace function jumps to the given line (only for the bottom-most -frame). A debugger can implement a Jump command (aka Set Next -Statement) by writing to f_lineno. -\withsubitem{(frame attribute)}{ - \ttindex{f_trace} - \ttindex{f_exc_type} - \ttindex{f_exc_value} - \ttindex{f_exc_traceback} - \ttindex{f_lineno}} - -\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} - -\item[Static method objects] -Static method objects provide a way of defeating the transformation -of function objects to method objects described above. A static method -object is a wrapper around any other object, usually a user-defined -method object. When a static method object is retrieved from a class -or a class instance, the object actually returned is the wrapped object, -which is not subject to any further transformation. Static method -objects are not themselves callable, although the objects they -wrap usually are. Static method objects are created by the built-in -\function{staticmethod()} constructor. - -\item[Class method objects] -A class method object, like a static method object, is a wrapper -around another object that alters the way in which that object -is retrieved from classes and class instances. The behaviour of -class method objects upon such retrieval is described above, -under ``User-defined methods''. Class method objects are created -by the built-in \function{classmethod()} constructor. - -\end{description} % Internal types - -\end{description} % Types - -%========================================================================= -\section{New-style and classic classes} - -Classes and instances come in two flavors: old-style or classic, and new-style. - -Up to Python 2.1, old-style classes were the only flavour available to the -user. The concept of (old-style) class is unrelated to the concept of type: if -\var{x} is an instance of an old-style class, then \code{x.__class__} -designates the class of \var{x}, but \code{type(x)} is always \code{<type -'instance'>}. This reflects the fact that all old-style instances, -independently of their class, are implemented with a single built-in type, -called \code{instance}. - -New-style classes were introduced in Python 2.2 to unify classes and types. A -new-style class neither more nor less than a user-defined type. If \var{x} is -an instance of a new-style class, then \code{type(x)} is the same as -\code{x.__class__}. - -The major motivation for introducing new-style classes is to provide a unified -object model with a full meta-model. It also has a number of immediate -benefits, like the ability to subclass most built-in types, or the introduction -of "descriptors", which enable computed properties. - -For compatibility reasons, classes are still old-style by default. New-style -classes are created by specifying another new-style class (i.e.\ a type) as a -parent class, or the "top-level type" \class{object} if no other parent is -needed. The behaviour of new-style classes differs from that of old-style -classes in a number of important details in addition to what \function{type} -returns. Some of these changes are fundamental to the new object model, like -the way special methods are invoked. Others are "fixes" that could not be -implemented before for compatibility concerns, like the method resolution order -in case of multiple inheritance. - -This manual is not up-to-date with respect to new-style classes. For now, -please see \url{http://www.python.org/doc/newstyle.html} for more information. - -The plan is to eventually drop old-style classes, leaving only the semantics of -new-style classes. This change will probably only be feasible in Python 3.0. -\index{class}{new-style} -\index{class}{classic} -\index{class}{old-style} - -%========================================================================= -\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.\indexii{operator}{overloading} -This is Python's approach to \dfn{operator overloading}, allowing -classes to define their own behavior with respect to language -operators. 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\footnote{This, and other -statements, are only roughly true for instances of new-style -classes.} 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]{__new__}{cls\optional{, \moreargs}} -Called to create a new instance of class \var{cls}. \method{__new__()} -is a static method (special-cased so you need not declare it as such) -that takes the class of which an instance was requested as its first -argument. The remaining arguments are those passed to the object -constructor expression (the call to the class). The return value of -\method{__new__()} should be the new object instance (usually an -instance of \var{cls}). - -Typical implementations create a new instance of the class by invoking -the superclass's \method{__new__()} method using -\samp{super(\var{currentclass}, \var{cls}).__new__(\var{cls}[, ...])} -with appropriate arguments and then modifying the newly-created instance -as necessary before returning it. - -If \method{__new__()} returns an instance of \var{cls}, then the new -instance's \method{__init__()} method will be invoked like -\samp{__init__(\var{self}[, ...])}, where \var{self} is the new instance -and the remaining arguments are the same as were passed to -\method{__new__()}. - -If \method{__new__()} does not return an instance of \var{cls}, then the -new instance's \method{__init__()} method will not be invoked. - -\method{__new__()} is intended mainly to allow subclasses of -immutable types (like int, str, or tuple) to customize instance -creation. -\end{methoddesc} - -\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, if any, 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 -constraint 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, if any, -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 \code{x}'s reference -count reaches zero. Some common situations that may prevent the -reference count of an object from going 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. -If a class defines \method{__repr__()} but not \method{__str__()}, -then \method{__repr__()} is also used when an ``informal'' string -representation of instances of that class is required. - -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})}. - -A rich comparison method may return the singleton \code{NotImplemented} if it -does not implement the operation for a given pair of arguments. -By convention, \code{False} and \code{True} are returned for a successful -comparison. However, these methods can return any value, so if the -comparison operator is used in a Boolean context (e.g., in the condition -of an \code{if} statement), Python will call \function{bool()} on the -value to determine if the result is true or false. - -There are no implied relationships among the comparison operators. -The truth of \code{\var{x}==\var{y}} does not imply that \code{\var{x}!=\var{y}} -is false. Accordingly, when defining \method{__eq__()}, one should also -define \method{__ne__()} so that the operators will behave as expected. - -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. -\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 since 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). - -\versionchanged[\method{__hash__()} may now also return a long -integer object; the 32-bit integer is then derived from the hash -of that object]{2.5} - -\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. - -\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). See the -\method{__getattribute__()} method below for a way to actually get -total control in new-style classes. -\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}. For new-style classes, -rather than accessing the instance dictionary, it should call the base -class method with the same name, for example, -\samp{object.__setattr__(self, 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} - -\subsubsection{More attribute access for new-style classes \label{new-style-attribute-access}} - -The following methods only apply to new-style classes. - -\begin{methoddesc}[object]{__getattribute__}{self, name} -Called unconditionally to implement attribute accesses for instances -of the class. If the class also defines \method{__getattr__()}, the latter -will not be called unless \method{__getattribute__()} either calls it -explicitly or raises an \exception{AttributeError}. -This method should return the (computed) attribute -value or raise an \exception{AttributeError} exception. -In order to avoid infinite recursion in this method, its -implementation should always call the base class method with the same -name to access any attributes it needs, for example, -\samp{object.__getattribute__(self, name)}. -\end{methoddesc} - -\subsubsection{Implementing Descriptors \label{descriptors}} - -The following methods only apply when an instance of the class -containing the method (a so-called \emph{descriptor} class) appears in -the class dictionary of another new-style class, known as the -\emph{owner} class. In the examples below, ``the attribute'' refers to -the attribute whose name is the key of the property in the owner -class' \code{__dict__}. Descriptors can only be implemented as -new-style classes themselves. - -\begin{methoddesc}[object]{__get__}{self, instance, owner} -Called to get the attribute of the owner class (class attribute access) -or of an instance of that class (instance attribute access). -\var{owner} is always the owner class, while \var{instance} is the -instance that the attribute was accessed through, or \code{None} when -the attribute is accessed through the \var{owner}. This method should -return the (computed) attribute value or raise an -\exception{AttributeError} exception. -\end{methoddesc} - -\begin{methoddesc}[object]{__set__}{self, instance, value} -Called to set the attribute on an instance \var{instance} of the owner -class to a new value, \var{value}. -\end{methoddesc} - -\begin{methoddesc}[object]{__delete__}{self, instance} -Called to delete the attribute on an instance \var{instance} of the -owner class. -\end{methoddesc} - - -\subsubsection{Invoking Descriptors \label{descriptor-invocation}} - -In general, a descriptor is an object attribute with ``binding behavior'', -one whose attribute access has been overridden by methods in the descriptor -protocol: \method{__get__()}, \method{__set__()}, and \method{__delete__()}. -If any of those methods are defined for an object, it is said to be a -descriptor. - -The default behavior for attribute access is to get, set, or delete the -attribute from an object's dictionary. For instance, \code{a.x} has a -lookup chain starting with \code{a.__dict__['x']}, then -\code{type(a).__dict__['x']}, and continuing -through the base classes of \code{type(a)} excluding metaclasses. - -However, if the looked-up value is an object defining one of the descriptor -methods, then Python may override the default behavior and invoke the -descriptor method instead. Where this occurs in the precedence chain depends -on which descriptor methods were defined and how they were called. Note that -descriptors are only invoked for new style objects or classes -(ones that subclass \class{object()} or \class{type()}). - -The starting point for descriptor invocation is a binding, \code{a.x}. -How the arguments are assembled depends on \code{a}: - -\begin{itemize} - - \item[Direct Call] The simplest and least common call is when user code - directly invokes a descriptor method: \code{x.__get__(a)}. - - \item[Instance Binding] If binding to a new-style object instance, - \code{a.x} is transformed into the call: - \code{type(a).__dict__['x'].__get__(a, type(a))}. - - \item[Class Binding] If binding to a new-style class, \code{A.x} - is transformed into the call: \code{A.__dict__['x'].__get__(None, A)}. - - \item[Super Binding] If \code{a} is an instance of \class{super}, - then the binding \code{super(B, obj).m()} searches - \code{obj.__class__.__mro__} for the base class \code{A} immediately - preceding \code{B} and then invokes the descriptor with the call: - \code{A.__dict__['m'].__get__(obj, A)}. - -\end{itemize} - -For instance bindings, the precedence of descriptor invocation depends -on the which descriptor methods are defined. Data descriptors define -both \method{__get__()} and \method{__set__()}. Non-data descriptors have -just the \method{__get__()} method. Data descriptors always override -a redefinition in an instance dictionary. In contrast, non-data -descriptors can be overridden by instances. - -Python methods (including \function{staticmethod()} and \function{classmethod()}) -are implemented as non-data descriptors. Accordingly, instances can -redefine and override methods. This allows individual instances to acquire -behaviors that differ from other instances of the same class. - -The \function{property()} function is implemented as a data descriptor. -Accordingly, instances cannot override the behavior of a property. - - -\subsubsection{__slots__\label{slots}} - -By default, instances of both old and new-style classes have a dictionary -for attribute storage. This wastes space for objects having very few instance -variables. The space consumption can become acute when creating large numbers -of instances. - -The default can be overridden by defining \var{__slots__} in a new-style class -definition. The \var{__slots__} declaration takes a sequence of instance -variables and reserves just enough space in each instance to hold a value -for each variable. Space is saved because \var{__dict__} is not created for -each instance. - -\begin{datadesc}{__slots__} -This class variable can be assigned a string, iterable, or sequence of strings -with variable names used by instances. If defined in a new-style class, -\var{__slots__} reserves space for the declared variables -and prevents the automatic creation of \var{__dict__} and \var{__weakref__} -for each instance. -\versionadded{2.2} -\end{datadesc} - -\noindent -Notes on using \var{__slots__} - -\begin{itemize} - -\item Without a \var{__dict__} variable, instances cannot be assigned new -variables not listed in the \var{__slots__} definition. Attempts to assign -to an unlisted variable name raises \exception{AttributeError}. If dynamic -assignment of new variables is desired, then add \code{'__dict__'} to the -sequence of strings in the \var{__slots__} declaration. -\versionchanged[Previously, adding \code{'__dict__'} to the \var{__slots__} -declaration would not enable the assignment of new attributes not -specifically listed in the sequence of instance variable names]{2.3} - -\item Without a \var{__weakref__} variable for each instance, classes -defining \var{__slots__} do not support weak references to its instances. -If weak reference support is needed, then add \code{'__weakref__'} to the -sequence of strings in the \var{__slots__} declaration. -\versionchanged[Previously, adding \code{'__weakref__'} to the \var{__slots__} -declaration would not enable support for weak references]{2.3} - -\item \var{__slots__} are implemented at the class level by creating -descriptors (\ref{descriptors}) for each variable name. As a result, -class attributes cannot be used to set default values for instance -variables defined by \var{__slots__}; otherwise, the class attribute would -overwrite the descriptor assignment. - -\item If a class defines a slot also defined in a base class, the instance -variable defined by the base class slot is inaccessible (except by retrieving -its descriptor directly from the base class). This renders the meaning of the -program undefined. In the future, a check may be added to prevent this. - -\item The action of a \var{__slots__} declaration is limited to the class -where it is defined. As a result, subclasses will have a \var{__dict__} -unless they also define \var{__slots__}. - -\item \var{__slots__} do not work for classes derived from ``variable-length'' -built-in types such as \class{long}, \class{str} and \class{tuple}. - -\item Any non-string iterable may be assigned to \var{__slots__}. -Mappings may also be used; however, in the future, special meaning may -be assigned to the values corresponding to each key. - -\item \var{__class__} assignment works only if both classes have the -same \var{__slots__}. -\versionchanged[Previously, \var{__class__} assignment raised an error -if either new or old class had \var{__slots__}]{2.6} - -\end{itemize} - - -\subsection{Customizing class creation\label{metaclasses}} - -By default, new-style classes are constructed using \function{type()}. -A class definition is read into a separate namespace and the value -of class name is bound to the result of \code{type(name, bases, dict)}. - -When the class definition is read, if \var{__metaclass__} is defined -then the callable assigned to it will be called instead of \function{type()}. -The allows classes or functions to be written which monitor or alter the class -creation process: - -\begin{itemize} -\item Modifying the class dictionary prior to the class being created. -\item Returning an instance of another class -- essentially performing -the role of a factory function. -\end{itemize} - -\begin{datadesc}{__metaclass__} -This variable can be any callable accepting arguments for \code{name}, -\code{bases}, and \code{dict}. Upon class creation, the callable is -used instead of the built-in \function{type()}. -\versionadded{2.2} -\end{datadesc} - -The appropriate metaclass is determined by the following precedence rules: - -\begin{itemize} - -\item If \code{dict['__metaclass__']} exists, it is used. - -\item Otherwise, if there is at least one base class, its metaclass is used -(this looks for a \var{__class__} attribute first and if not found, uses its -type). - -\item Otherwise, if a global variable named __metaclass__ exists, it is used. - -\item Otherwise, the old-style, classic metaclass (types.ClassType) is used. - -\end{itemize} - -The potential uses for metaclasses are boundless. Some ideas that have -been explored including logging, interface checking, automatic delegation, -automatic property creation, proxies, frameworks, and automatic resource -locking/synchronization. - - -\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{setdefault()}, \method{iterkeys()}, \method{itervalues()}, -\method{iteritems()}, \method{pop()}, \method{popitem()}, -\method{copy()}, and \method{update()} behaving similar to those for -Python's standard dictionary objects. The \module{UserDict} module -provides a \class{DictMixin} class to help create those methods -from a base set of \method{__getitem__()}, \method{__setitem__()}, -\method{__delitem__()}, and \method{keys()}. -Mutable sequences should provide -methods \method{append()}, \method{count()}, \method{index()}, -\method{extend()}, -\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. It is further recommended that both mappings and sequences -implement the \method{__iter__()} method to allow efficient iteration -through the container; for mappings, \method{__iter__()} should be -the same as \method{iterkeys()}; for sequences, it should iterate -through the values. -\withsubitem{(mapping object method)}{ - \ttindex{keys()} - \ttindex{values()} - \ttindex{items()} - \ttindex{iterkeys()} - \ttindex{itervalues()} - \ttindex{iteritems()} - \ttindex{has_key()} - \ttindex{get()} - \ttindex{setdefault()} - \ttindex{pop()} - \ttindex{popitem()} - \ttindex{clear()} - \ttindex{copy()} - \ttindex{update()} - \ttindex{__contains__()}} -\withsubitem{(sequence object method)}{ - \ttindex{append()} - \ttindex{count()} - \ttindex{extend()} - \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__()} - \ttindex{__iter__()}} -\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. -For mapping types, if \var{key} is missing (not in the container), -\exception{KeyError} 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 optional methods can be defined to further emulate sequence -objects. Immutable sequences methods should at most only define -\method{__getslice__()}; mutable sequences might define all 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, -or for extended slicing of the form -\code{\var{self}[\var{i}:\var{j}:\var{k}]}, a -slice object is created, and passed to \method{__setitem__()}, -instead of \method{__setslice__()} being called. -\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, -or for extended slicing of the form -\code{\var{self}[\var{i}:\var{j}:\var{k}]}, a -slice object is created, and passed to \method{__delitem__()}, -instead of \method{__delslice__()} being called. -\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 necessary because of -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 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{|}). 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. - -If one of those methods does not support the operation with the -supplied arguments, it should return \code{NotImplemented}. -\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{|}) with reflected -(swapped) operands. These functions are only called if the left -operand does not support the corresponding operation and the -operands are of different types.\footnote{ - For operands of the same type, it is assumed that if the - non-reflected method (such as \method{__add__()}) fails the - operation is not supported, which is why the reflected method - is not called.} -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 if \code{\var{x}.__sub__(\var{y})} returns -\var{NotImplemented}. - -Note that ternary -\function{pow()}\bifuncindex{pow} will not try calling -\method{__rpow__()} (the coercion rules would become too -complicated). - -\note{If the right operand's type is a subclass of the left operand's - type and that subclass provides the reflected method for the - operation, this method will be called before the left operand's - non-reflected method. This behavior allows subclasses to - override their ancestors' operations.} -\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{\textasciicircum=}, \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]{__index__}{self} -Called to implement \function{operator.index()}. Also called whenever -Python needs an integer object (such as in slicing). Must return an -integer (int or long). -\versionadded{2.5} -\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 and overrides the base's -\method{__rop__()} method, 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 \method{__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} - -\subsection{With Statement Context Managers\label{context-managers}} - -\versionadded{2.5} - -A \dfn{context manager} is an object that defines the runtime -context to be established when executing a \keyword{with} -statement. The context manager handles the entry into, -and the exit from, the desired runtime context for the execution -of the block of code. Context managers are normally invoked using -the \keyword{with} statement (described in section~\ref{with}), but -can also be used by directly invoking their methods. - -\stindex{with} -\index{context manager} - -Typical uses of context managers include saving and -restoring various kinds of global state, locking and unlocking -resources, closing opened files, etc. - -For more information on context managers, see -``\ulink{Context Types}{../lib/typecontextmanager.html}'' in the -\citetitle[../lib/lib.html]{Python Library Reference}. - -\begin{methoddesc}[context manager]{__enter__}{self} -Enter the runtime context related to this object. The \keyword{with} -statement will bind this method's return value to the target(s) -specified in the \keyword{as} clause of the statement, if any. -\end{methoddesc} - -\begin{methoddesc}[context manager]{__exit__} -{self, exc_type, exc_value, traceback} -Exit the runtime context related to this object. The parameters -describe the exception that caused the context to be exited. If -the context was exited without an exception, all three arguments -will be \constant{None}. - -If an exception is supplied, and the method wishes to suppress the -exception (i.e., prevent it from being propagated), it should return a -true value. Otherwise, the exception will be processed normally upon -exit from this method. - -Note that \method{__exit__} methods should not reraise the passed-in -exception; this is the caller's responsibility. -\end{methoddesc} - -\begin{seealso} - \seepep{0343}{The "with" statement} - {The specification, background, and examples for the - Python \keyword{with} statement.} -\end{seealso} - |