From 2e0b7557b19293223cfd4f5f21ae5d80ccc55bbd Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Tue, 27 Nov 2007 12:43:08 +0000 Subject: [PATCH] Futher update docs after unbound method removal. --- Doc/c-api/concrete.rst | 3 +- Doc/distutils/apiref.rst | 6 +- Doc/library/new.rst | 2 + Doc/library/operator.rst | 2 +- Doc/library/stdtypes.rst | 28 ++--- Doc/library/weakref.rst | 8 +- Doc/reference/datamodel.rst | 159 ++++++++++-------------- Tools/bgen/bgen/bgenObjectDefinition.py | 4 +- 8 files changed, 93 insertions(+), 119 deletions(-) diff --git a/Doc/c-api/concrete.rst b/Doc/c-api/concrete.rst index d2bedc2e300..50ab005ddf2 100644 --- a/Doc/c-api/concrete.rst +++ b/Doc/c-api/concrete.rst @@ -2600,8 +2600,9 @@ There are some useful functions that are useful for working with method objects. function that will be called when the method is called. If this method should be bound to an instance, *self* should be the instance and *class* should be the class of *self*, otherwise *self* should be *NULL* and *class* should be the - class which provides the unbound method.. + class which provides the unbound method. + .. XXX no unbound methods anymore... .. cfunction:: PyObject* PyMethod_Class(PyObject *meth) diff --git a/Doc/distutils/apiref.rst b/Doc/distutils/apiref.rst index 57e7ea89c16..6c2be3e9f0f 100644 --- a/Doc/distutils/apiref.rst +++ b/Doc/distutils/apiref.rst @@ -1965,12 +1965,12 @@ Subclasses of :class:`Command` must define the following methods. as the parent with sub-commands ``install_lib``, ``install_headers``, etc. The parent of a family of commands defines *sub_commands* as a class attribute; it's a list of 2-tuples ``(command_name, predicate)``, with *command_name* a string -and *predicate* an unbound method, a string or None. *predicate* is a method of +and *predicate* a function, a string or None. *predicate* is a method of the parent command that determines whether the corresponding command is applicable in the current situation. (Eg. we ``install_headers`` is only applicable if we have any C header files to install.) If *predicate* is None, that command is always applicable. *sub_commands* is usually defined at the \*end\* of a class, because predicates -can be unbound methods, so they must already have been defined. The canonical -example is the :command:`install` command. +can be methods of the class, so they must already have been defined. The +canonical example is the :command:`install` command. diff --git a/Doc/library/new.rst b/Doc/library/new.rst index 6c5a4bf8176..832dca6614f 100644 --- a/Doc/library/new.rst +++ b/Doc/library/new.rst @@ -22,6 +22,8 @@ The :mod:`new` module defines the following functions: This function will return a method object, bound to *instance*. *function* must be callable. + .. XXX no unbound methods anymore + .. function:: function(code, globals[, name[, argdefs[, closure]]]) diff --git a/Doc/library/operator.rst b/Doc/library/operator.rst index 40acc6b7b42..cb89a7f8607 100644 --- a/Doc/library/operator.rst +++ b/Doc/library/operator.rst @@ -390,7 +390,7 @@ objects. Use the :func:`callable` built-in function instead. Returns true if the object *obj* can be called like a function, otherwise it - returns false. True is returned for functions, bound and unbound methods, class + returns false. True is returned for functions, instance methods, class objects, and instance objects which support the :meth:`__call__` method. diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst index 1e81ed935f9..5c69ed6e680 100644 --- a/Doc/library/stdtypes.rst +++ b/Doc/library/stdtypes.rst @@ -2215,23 +2215,19 @@ two flavors: built-in methods (such as :meth:`append` on lists) and class instance methods. Built-in methods are described with the types that support them. -The implementation adds two special read-only attributes to class instance -methods: ``m.__self__`` is the object on which the method operates, and -``m.__func__`` is the function implementing the method. Calling ``m(arg-1, -arg-2, ..., arg-n)`` is completely equivalent to calling ``m.__func__( -m.__self__, arg-1, arg-2, ..., arg-n)``. +If you access a method (a function defined in a class namespace) through an +instance, you get a special object: a :dfn:`bound method` (also called +:dfn:`instance method`) object. When called, it will add the ``self`` argument +to the argument list. Bound methods have two special read-only attributes: +``m.__self__`` is the object on which the method operates, and ``m.__func__`` is +the function implementing the method. Calling ``m(arg-1, arg-2, ..., arg-n)`` +is completely equivalent to calling ``m.__func__(m.__self__, arg-1, arg-2, ..., +arg-n)``. -Class instance methods are either *bound* or *unbound*, referring to whether the -method was accessed through an instance or a class, respectively. When a method -is unbound, its ``__self__`` attribute will be ``None`` and if called, an -explicit ``self`` object must be passed as the first argument. In this case, -``self`` must be an instance of the unbound method's class (or a subclass of -that class), otherwise a :exc:`TypeError` is raised. - -Like function objects, methods objects support getting arbitrary attributes. -However, since method attributes are actually stored on the underlying function -object (``meth.__func__``), setting method attributes on either bound or unbound -methods is disallowed. Attempting to set a method attribute results in a +Like function objects, bound method objects support getting arbitrary +attributes. However, since method attributes are actually stored on the +underlying function object (``meth.__func__``), setting method attributes on +bound methods is disallowed. Attempting to set a method attribute results in a :exc:`TypeError` being raised. In order to set a method attribute, you need to explicitly set it on the underlying function object:: diff --git a/Doc/library/weakref.rst b/Doc/library/weakref.rst index 3adf3182bd1..9a1e0769647 100644 --- a/Doc/library/weakref.rst +++ b/Doc/library/weakref.rst @@ -50,10 +50,10 @@ directly. The low-level machinery used by the weak dictionary implementations is exposed by the :mod:`weakref` module for the benefit of advanced uses. Not all objects can be weakly referenced; those objects which can include class -instances, functions written in Python (but not in C), methods (both bound and -unbound), sets, frozensets, file objects, :term:`generator`\s, type objects, -:class:`DBcursor` objects from the :mod:`bsddb` module, sockets, arrays, deques, -and regular expression pattern objects. +instances, functions written in Python (but not in C), instance methods, sets, +frozensets, file objects, :term:`generator`\s, type objects, :class:`DBcursor` +objects from the :mod:`bsddb` module, sockets, arrays, deques, and regular +expression pattern objects. Several builtin types such as :class:`list` and :class:`dict` do not directly support weak references but can add support through subclassing:: diff --git a/Doc/reference/datamodel.rst b/Doc/reference/datamodel.rst index 75cb52f5d3e..68e9f104727 100644 --- a/Doc/reference/datamodel.rst +++ b/Doc/reference/datamodel.rst @@ -529,14 +529,21 @@ Callable types single: __kwdefaults__ (function attribute) pair: global; namespace - User-defined methods + Instance methods .. index:: object: method object: user-defined method pair: user-defined; method - A user-defined method object combines a class, a class instance (or ``None``) - and any callable object (normally a user-defined function). + An instance method object combines a class, a class instance and any + callable object (normally a user-defined function). + + .. index:: + single: __func__ (method attribute) + single: __self__ (method attribute) + single: __doc__ (method attribute) + single: __name__ (method attribute) + single: __module__ (method attribute) Special read-only attributes: :attr:`__self__` is the class instance object, :attr:`__func__` is the function object; :attr:`__doc__` is the method's @@ -544,77 +551,52 @@ Callable types method name (same as ``__func__.__name__``); :attr:`__module__` is the name of the module the method was defined in, or ``None`` if unavailable. - .. index:: - single: __doc__ (method attribute) - single: __name__ (method attribute) - single: __module__ (method attribute) - single: __func__ (method attribute) - single: __self__ (method attribute) - 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. + 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 or a class method object. + + When an instance method object is created by retrieving a user-defined + function object from a class via one of its instances, its + :attr:`__self__` attribute is the instance, and the method object is said + to be bound. The new method's :attr:`__func__` attribute is the original + function object. - .. index:: - single: __func__ (method attribute) - single: __self__ (method attribute) + 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 :attr:`__func__` attribute of the new + instance is not the original method object but its :attr:`__func__` + attribute. - When a user-defined method object is created by retrieving a user-defined - function object from a class, its :attr:`__self__` attribute is ``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 :attr:`__self__` attribute is the instance, and the method - object is said to be bound. Its :attr:`__func__` attribute is the - original function object. + When an instance method object is created by retrieving a class method + object from a class or instance, its :attr:`__self__` attribute is the + class itself, and its :attr:`__func__` attribute is the function object + underlying the class method. - .. index:: single: __func__ (method attribute) + When an instance method object is called, the underlying function + (:attr:`__func__`) is called, inserting the class instance + (:attr:`__self__`) in front of the argument list. For instance, when + :class:`C` is a class which contains a definition for a function + :meth:`f`, and ``x`` is an instance of :class:`C`, calling ``x.f(1)`` is + equivalent to calling ``C.f(x, 1)``. - 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 :attr:`__func__` attribute of the new instance is not the - original method object but its :attr:`__func__` attribute. + When an instance method object is derived from a class method object, the + "class instance" stored in :attr:`__self__` will actually be the class + itself, so that calling either ``x.f(1)`` or ``C.f(1)`` is equivalent to + calling ``f(C,1)`` where ``f`` is the underlying function. - .. index:: - single: __func__ (method attribute) - single: __self__ (method attribute) - - When a user-defined method object is created by retrieving a class method object - from a class or instance, its :attr:`__self__` attribute is the class itself (the - same as the :attr:`im_class` attribute), and its :attr:`__func__` attribute is - the function object underlying the class method. - - When an unbound user-defined method object is called, the underlying function - (:attr:`__func__`) is called, with the restriction that the first argument must - be an instance of the proper class (:attr:`im_class`) or of a derived class - thereof. - - When a bound user-defined method object is called, the underlying function - (:attr:`__func__`) is called, inserting the class instance (:attr:`__self__`) in - front of the argument list. For instance, when :class:`C` is a class which - contains a definition for a function :meth:`f`, and ``x`` is an instance of - :class:`C`, calling ``x.f(1)`` is equivalent to calling ``C.f(x, 1)``. - - When a user-defined method object is derived from a class method object, the - "class instance" stored in :attr:`__self__` will actually be the class itself, so - that calling either ``x.f(1)`` or ``C.f(1)`` is equivalent to calling ``f(C,1)`` - where ``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 *only* happens when the function is an - attribute of the class. + Note that the transformation from function object to instance method + object happens each time the attribute is retrieved from the 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 *only* happens when the function is an attribute of the + class. Generator functions .. index:: @@ -731,16 +713,12 @@ Custom classes pair: class; attribute 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 :attr:`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 :attr:`im_class` - and :attr:`__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 :attr:`__dict__`. + class method object, it is transformed into an instance method object whose + :attr:`__self__` attributes is :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 + :attr:`__dict__`. .. index:: triple: class; attribute; assignment @@ -772,22 +750,19 @@ Class instances pair: class; instance pair: class instance; attribute - 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 :attr:`im_class` attribute is :class:`C` and - whose :attr:`__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 :attr:`__dict__`. If no - class attribute is found, and the object's class has a :meth:`__getattr__` - method, that is called to satisfy the lookup. + 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, it is transformed into an instance method + object whose :attr:`__self__` attribute is the instance. Static method and + class method objects are also transformed; 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 :attr:`__dict__`. If no class attribute is found, and the + object's class has a :meth:`__getattr__` method, that is called to satisfy + the lookup. .. index:: triple: class instance; attribute; assignment diff --git a/Tools/bgen/bgen/bgenObjectDefinition.py b/Tools/bgen/bgen/bgenObjectDefinition.py index 6f9bd5300ed..d926283fca4 100644 --- a/Tools/bgen/bgen/bgenObjectDefinition.py +++ b/Tools/bgen/bgen/bgenObjectDefinition.py @@ -236,8 +236,8 @@ class PEP252Mixin: def assertions(self): # Check that various things aren't overridden. If they are it could # signify a bgen-client that has been partially converted to PEP252. - assert self.outputGetattr.im_func == PEP252Mixin.outputGetattr.im_func - assert self.outputSetattr.im_func == PEP252Mixin.outputSetattr.im_func + assert self.outputGetattr.__func__ == PEP252Mixin.outputGetattr.__func__ + assert self.outputSetattr.__func__ == PEP252Mixin.outputSetattr.__func__ assert self.outputGetattrBody == None assert self.outputGetattrHook == None assert self.basechain == "NULL"