diff options
| -rw-r--r-- | Doc/reference/datamodel.rst | 190 |
1 files changed, 147 insertions, 43 deletions
diff --git a/Doc/reference/datamodel.rst b/Doc/reference/datamodel.rst index 9e28fe9..0e9cf61 100644 --- a/Doc/reference/datamodel.rst +++ b/Doc/reference/datamodel.rst @@ -742,12 +742,23 @@ Modules of the shared library file. Classes - Class objects are created by class definitions (see section :ref:`class`). A - class has a namespace implemented by a dictionary object. Class attribute - references are translated to lookups in this dictionary, e.g., ``C.x`` is - translated to ``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. + Both class types (new-style classes) and class objects (old-style/classic + classes) are typically created by class definitions (see section + :ref:`class`). A class has a namespace implemented by a dictionary object. + Class attribute references are translated to lookups in this dictionary, e.g., + ``C.x`` is translated to ``C.__dict__["x"]`` (although for new-style classes + in particular there are a number of hooks which allow for other means of + locating attributes). When the attribute name is not found there, the + attribute search continues in the base classes. For old-style classes, the + search is depth-first, left-to-right in the order of occurrence in the base + class list. New-style classes use the more complex C3 method resolution + order which behaves correctly even in the presence of 'diamond' + inheritance structures where there are multiple inheritance paths + leading back to a common ancestor. Additional details on the C3 MRO used by + new-style classes can be found in the documentation accompanying the + 2.3 release at http://www.python.org/download/releases/2.3/mro/. + + .. XXX: Could we add that MRO doc as an appendix to the language ref? .. index:: object: class @@ -768,7 +779,7 @@ Classes 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 :attr:`__dict__`. + its :attr:`__dict__` (note that only new-style classes support descriptors). .. index:: triple: class; attribute; assignment @@ -1075,7 +1086,7 @@ Internal types New-style and classic classes ============================= -Classes and instances come in two flavors: old-style or classic, and new-style. +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 *x* is @@ -1086,10 +1097,12 @@ a single built-in type, called ``instance``. New-style classes were introduced in Python 2.2 to unify classes and types. A new-style class is neither more nor less than a user-defined type. If *x* is an -instance of a new-style class, then ``type(x)`` is the same as ``x.__class__``. +instance of a new-style class, then ``type(x)`` is typically the same as +``x.__class__`` (although this is not guaranteed - a new-style class instance is +permitted to override the value returned for ``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 +object model with a full meta-model. It also has a number of practical benefits, like the ability to subclass most built-in types, or the introduction of "descriptors", which enable computed properties. @@ -1103,16 +1116,18 @@ 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 http://www.python.org/doc/newstyle/ for more information. +While this manual aims to provide comprehensive coverage of Python's class +mechanics, it may still be lacking in some areas when it comes to its coverage +of new-style classes. Please see http://www.python.org/doc/newstyle/ for +sources of additional information. .. index:: single: class; new-style single: class; classic single: class; old-style -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. +Old-style classes are removed in Python 3.0, leaving only the semantics of +new-style classes. .. _specialnames: @@ -1129,24 +1144,11 @@ A class can implement certain operations that are invoked by special syntax with special names. 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 :meth:`__getitem__`, -and ``x`` is an instance of this class, then ``x[i]`` is equivalent [#]_ to -``x.__getitem__(i)``. Except where mentioned, attempts to execute an operation -raise an exception when no appropriate method is defined. - -For new-style classes, special methods are only guaranteed to work if defined in -an object's class, not in the object's instance dictionary. That explains why -this won't work:: - - >>> class C: - ... pass - ... - >>> c = C() - >>> c.__len__ = lambda: 5 - >>> len(c) - Traceback (most recent call last): - File "<stdin>", line 1, in <module> - TypeError: object of type 'C' has no len() - +and ``x`` is an instance of this class, then ``x[i]`` is roughly equivalent +to ``x.__getitem__(i)`` for old-style classes and ``type(x).__getitem__(x, i)`` +for new-style classes. Except where mentioned, attempts to execute an +operation raise an exception when no appropriate method is defined (typically +:exc:`AttributeError` or :exc:`TypeError`). 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 @@ -1479,6 +1481,12 @@ The following methods only apply to new-style classes. method with the same name to access any attributes it needs, for example, ``object.__getattribute__(self, name)``. + .. note:: + + This method may still be bypassed when looking up special methods as the + result of implicit invocation via language syntax or builtin functions. + See :ref:`new-style-special-lookup`. + .. _descriptors: @@ -2274,19 +2282,115 @@ For more information on context managers, see :ref:`typecontextmanager`. The specification, background, and examples for the Python :keyword:`with` statement. + +.. _old-style-special-lookup: + +Special method lookup for old-style classes +------------------------------------------- + +For old-style classes, special methods are always looked up in exactly the +same way as any other method or attribute. This is the case regardless of +whether the method is being looked up explicitly as in ``x.__getitem__(i)`` +or implicitly as in ``x[i]``. + +This behaviour means that special methods may exhibit different behaviour +for different instances of a single old-style class if the appropriate +special attributes are set differently:: + + >>> class C: + ... pass + ... + >>> c1 = C() + >>> c2 = C() + >>> c1.__len__ = lambda: 5 + >>> c2.__len__ = lambda: 9 + >>> len(c1) + 5 + >>> len(c2) + 9 + + +.. _new-style-special-lookup: + +Special method lookup for new-style classes +------------------------------------------- + +For new-style classes, implicit invocations of special methods are only guaranteed +to work correctly if defined on an object's type, not in the object's instance +dictionary. That behaviour is the reason why the following code raises an +exception (unlike the equivalent example with old-style classes):: + + >>> class C(object): + ... pass + ... + >>> c = C() + >>> c.__len__ = lambda: 5 + >>> len(c) + Traceback (most recent call last): + File "<stdin>", line 1, in <module> + TypeError: object of type 'C' has no len() + +The rationale behind this behaviour lies with a number of special methods such +as :meth:`__hash__` and :meth:`__repr__` that are implemented by all objects, +including type objects. If the implicit lookup of these methods used the +conventional lookup process, they would fail when invoked on the type object +itself:: + + >>> 1 .__hash__() == hash(1) + True + >>> int.__hash__() == hash(int) + Traceback (most recent call last): + File "<stdin>", line 1, in <module> + TypeError: descriptor '__hash__' of 'int' object needs an argument + +Incorrectly attempting to invoke an unbound method of a class in this way is +sometimes referred to as 'metaclass confusion', and is avoided by bypassing +the instance when looking up special methods:: + + >>> type(1).__hash__(1) == hash(1) + True + >>> type(int).__hash__(int) == hash(int) + True + +In addition to bypassing any instance attributes in the interest of +correctness, implicit special method lookup may also bypass the +:meth:`__getattribute__` method even of the object's metaclass:: + + >>> class Meta(type): + ... def __getattribute__(*args): + ... print "Metaclass getattribute invoked" + ... return type.__getattribute__(*args) + ... + >>> class C(object): + ... __metaclass__ = Meta + ... def __len__(self): + ... return 10 + ... def __getattribute__(*args): + ... print "Class getattribute invoked" + ... return object.__getattribute__(*args) + ... + >>> c = C() + >>> c.__len__() # Explicit lookup via instance + Class getattribute invoked + 10 + >>> type(c).__len__(c) # Explicit lookup via type + Metaclass getattribute invoked + 10 + >>> len(c) # Implicit lookup + 10 + +Bypassing the :meth:`__getattribute__` machinery in this fashion +provides significant scope for speed optimisations within the +interpreter, at the cost of some flexibility in the handling of +special methods (the special method *must* be set on the class +object itself in order to be consistently invoked by the interpreter). + + .. rubric:: Footnotes -.. [#] 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 *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 - http://www.python.org/doc/newstyle/. - -.. [#] This, and other statements, are only roughly true for instances of new-style - classes. +.. [#] It *is* possible in some cases to change an object's type, under certain + controlled conditions. It generally isn't a good idea though, since it can + lead to some very strange behaviour if it is handled incorrectly. .. [#] A descriptor can define any combination of :meth:`__get__`, :meth:`__set__` and :meth:`__delete__`. If it does not define :meth:`__get__`, |