0 ,ˆl–Ým_JJh¥² ¸È®2ú˜´oÁ „ ®:×_‡I|¥ŠèªÁÀ?÷====================== Descriptor HowTo Guide ====================== :Author: Raymond Hettinger :Contact: .. Contents:: Abstract -------- Defines descriptors, summarizes the protocol, and shows how descriptors are called. Examines a custom descriptor and several built-in python descriptors including functions, properties, static methods, and class methods. Shows how each works by giving a pure Python equivalent and a sample application. Learning about descriptors not only provides access to a larger toolset, it creates a deeper understanding of how Python works and an appreciation for the elegance of its design. Definition and Introduction --------------------------- In general, a descriptor is an object attribute with "binding behavior", one whose attribute access has been overridden by methods in the descriptor protocol. Those methods are :meth:`__get__`, :meth:`__set__`, and :meth:`__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, ``a.x`` has a lookup chain starting with ``a.__dict__['x']``, then ``type(a).__dict__['x']``, and continuing through the base classes of ``type(a)`` excluding metaclasses. 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. Note that descriptors are only invoked for new style objects or classes (a class is new style if it inherits from :class:`object` or :class:`type`). Descriptors are a powerful, general purpose protocol. They are the mechanism behind properties, methods, static methods, class methods, and :func:`super()`. They are used throughout Python itself to implement the new style classes introduced in version 2.2. Descriptors simplify the underlying C-code and offer a flexible set of new tools for everyday Python programs. Descriptor Protocol ------------------- ``descr.__get__(self, obj, type=None) --> value`` ``descr.__set__(self, obj, value) --> None`` ``descr.__delete__(self, obj) --> None`` That is all there is to it. Define any of these methods and an object is considered a descriptor and can override default behavior upon being looked up as an attribute. If an object defines both :meth:`__get__` and :meth:`__set__`, it is considered a data descriptor. Descriptors that only define :meth:`__get__` are called non-data descriptors (they are typically used for methods but other uses are possible). Data and non-data descriptors differ in how overrides are calculated with respect to entries in an instance's dictionary. If an instance's dictionary has an entry with the same name as a data descriptor, the data descriptor takes precedence. If an instance's dictionary has an entry with the same name as a non-data descriptor, the dictionary entry takes precedence. To make a read-only data descriptor, define both :meth:`__get__` and :meth:`__set__` with the :meth:`__set__` raising an :exc:`AttributeError` when called. Defining the :meth:`__set__` method with an exception raising placeholder is enough to make it a data descriptor. Invoking Descriptors -------------------- A descriptor can be called directly by its method name. For example, ``d.__get__(obj)``. Alternatively, it is more common for a descriptor to be invoked automatically upon attribute access. For example, ``obj.d`` looks up ``d`` in the dictionary of ``obj``. If ``d`` defines the method :meth:`__get__`, then ``d.__get__(obj)`` is invoked according to the precedence rules listed below. The details of invocation depend on whether ``obj`` is an object or a class. Either way, descriptors only work for new style objects and classes. A class is new style if it is a subclass of :class:`object`. For objects, the machinery is in :meth:`ob