- improve the description of how user-defined method

freddrake · freddrake · commit ea690c4b2540 · 2003-07-17T05:26:53.000Z
objects get made
  - improve the description of attribute retrieval from
    classes and class instances
  - add brief documentation of static method and
    class method objects.
diff --git a/Doc/ref/ref3.tex b/Doc/ref/ref3.tex
@@ -499,22 +499,41 @@ \section{The standard type hierarchy\label{types}}
 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 @@ \section{The standard type hierarchy\label{types}}
 \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 @@ \section{The standard type hierarchy\label{types}}
 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 @@ \section{The standard type hierarchy\label{types}}
 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 @@ \section{The standard type hierarchy\label{types}}
 \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
