- improve the description of how user-defined method
objects get made - improve the description of attribute retrieval from classes and class instances - add brief documentation of static method and class method objects.
This commit is contained in:
parent
38d7c1bb78
commit
ea690c4b25
110
Doc/ref/ref3.tex
110
Doc/ref/ref3.tex
|
@ -499,22 +499,41 @@ module the method was defined in, or \code{None} if unavailable.
|
|||
Methods also support accessing (but not setting) the arbitrary
|
||||
function attributes on the underlying function object.
|
||||
|
||||
User-defined method objects are created in two ways: when getting an
|
||||
attribute of a class that is a user-defined function object, or when
|
||||
getting an attribute of a class instance that is a user-defined
|
||||
function object defined by the class of the instance. In the former
|
||||
case (class attribute), the \member{im_self} attribute is \code{None},
|
||||
and the method object is said to be unbound; in the latter case
|
||||
(instance attribute), \method{im_self} is the instance, and the method
|
||||
object is said to be bound. For
|
||||
instance, when \class{C} is a class which has a method
|
||||
\method{f()}, \code{C.f} does not yield the function object
|
||||
\code{f}; rather, it yields an unbound method object \code{m} where
|
||||
\code{m.im_class} is \class{C}, \code{m.im_func} is \method{f()}, and
|
||||
\code{m.im_self} is \code{None}. When \code{x} is a \class{C}
|
||||
instance, \code{x.f} yields a bound method object \code{m} where
|
||||
\code{m.im_class} is \code{C}, \code{m.im_func} is \method{f()}, and
|
||||
\code{m.im_self} is \code{x}.
|
||||
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}}
|
||||
|
||||
|
@ -530,6 +549,12 @@ function (\member{im_func}) is called, inserting the class instance
|
|||
\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
|
||||
|
@ -654,10 +679,19 @@ When the attribute name is not found
|
|||
there, the attribute search continues in the base classes. The search
|
||||
is depth-first, left-to-right in the order of occurrence in the
|
||||
base class list.
|
||||
When a class attribute reference would yield a user-defined function
|
||||
object, it is transformed into an unbound user-defined method object
|
||||
(see above). The \member{im_class} attribute of this method object is the
|
||||
class for which the attribute reference was initiated.
|
||||
|
||||
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}
|
||||
|
@ -695,11 +729,18 @@ is the first place in which
|
|||
attribute references are searched. When an attribute is not found
|
||||
there, and the instance's class has an attribute by that name,
|
||||
the search continues with the class attributes. If a class attribute
|
||||
is found that is a user-defined function object (and in no other
|
||||
case), it is transformed into an unbound user-defined method object
|
||||
(see above). The \member{im_class} attribute of this method object is
|
||||
the
|
||||
class of the instance for which the attribute reference was initiated.
|
||||
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} 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}
|
||||
|
@ -938,6 +979,25 @@ 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
|
||||
|
|
Loading…
Reference in New Issue