From e9208f0e74d8c37542a750476ff272143fa8f67c Mon Sep 17 00:00:00 2001 From: Raymond Hettinger Date: Sun, 1 Nov 2020 20:15:50 -0800 Subject: [PATCH] Minor formatting edits to the descriptor howto guide (GH-23092) --- Doc/howto/descriptor.rst | 39 ++++++++++++++++++++------------------- 1 file changed, 20 insertions(+), 19 deletions(-) diff --git a/Doc/howto/descriptor.rst b/Doc/howto/descriptor.rst index 5373025e5407de..fedf8a8c09eac4 100644 --- a/Doc/howto/descriptor.rst +++ b/Doc/howto/descriptor.rst @@ -27,8 +27,9 @@ This guide has four major sections: 4) The last section has pure Python equivalents for built-in descriptors that are written in C. Read this if you're curious about how functions turn - into bound methods or about how to implement common tools like - :func:`classmethod`, :func:`staticmethod`, and :func:`property`. + into bound methods or about the implementation of common tools like + :func:`classmethod`, :func:`staticmethod`, :func:`property`, and + :term:`__slots__`. Primer @@ -188,7 +189,7 @@ logged attribute and that its name is unchangeable. In the next example, we'll fix that problem. -Customized Names +Customized names ---------------- When a class uses descriptors, it can inform each descriptor about what @@ -438,7 +439,7 @@ creates a deeper understanding of how Python works and an appreciation for the elegance of its design. -Definition and Introduction +Definition and introduction --------------------------- In general, a descriptor is an object attribute with "binding behavior", one @@ -463,7 +464,7 @@ simplify the underlying C code and offer a flexible set of new tools for everyday Python programs. -Descriptor Protocol +Descriptor protocol ------------------- ``descr.__get__(self, obj, type=None) -> value`` @@ -493,7 +494,7 @@ called. Defining the :meth:`__set__` method with an exception raising placeholder is enough to make it a data descriptor. -Overview of Descriptor Invocation +Overview of descriptor invocation --------------------------------- A descriptor can be called directly with ``desc.__get__(obj)`` or @@ -510,7 +511,7 @@ The details of invocation depend on whether ``obj`` is an object, class, or instance of super. -Invocation from an Instance +Invocation from an instance --------------------------- Instance lookup scans through a chain of namespaces giving data descriptors @@ -549,7 +550,7 @@ The :exc:`TypeError` exception handler is needed because the instance dictionary doesn't exist when its class defines :term:`__slots__`. -Invocation from a Class +Invocation from a class ----------------------- The logic for a dotted lookup such as ``A.x`` is in @@ -563,7 +564,7 @@ The full C implementation can be found in :c:func:`type_getattro()` and :c:func:`_PyType_Lookup()` in :source:`Objects/typeobject.c`. -Invocation from Super +Invocation from super --------------------- The logic for super's dotted lookup is in the :meth:`__getattribute__` method for @@ -580,7 +581,7 @@ The full C implementation can be found in :c:func:`super_getattro()` in `_. -Summary of Invocation Logic +Summary of invocation logic --------------------------- The mechanism for descriptors is embedded in the :meth:`__getattribute__()` @@ -606,7 +607,7 @@ The important points to remember are: * Non-data descriptors may be overridden by instance dictionaries. -Automatic Name Notification +Automatic name notification --------------------------- Sometimes it is desirable for a descriptor to know what class variable name it @@ -624,7 +625,7 @@ place at the time of class creation. If descriptors are added to the class afterwards, :meth:`__set_name__` will need to be called manually. -ORM Example +ORM example ----------- The following code is simplified skeleton showing how data descriptors could @@ -694,8 +695,8 @@ Pure Python Equivalents The descriptor protocol is simple and offers exciting possibilities. Several use cases are so common that they have been prepackaged into built-in tools. -Properties, bound methods, static methods, and class methods are all based on -the descriptor protocol. +Properties, bound methods, static methods, class methods, and \_\_slots\_\_ are +all based on the descriptor protocol. Properties @@ -774,7 +775,7 @@ to wrap access to the value attribute in a property data descriptor:: return self._value -Functions and Methods +Functions and methods --------------------- Python's object oriented features are built upon a function based environment. @@ -858,7 +859,7 @@ If you have ever wondered where *self* comes from in regular methods or where *cls* comes from in class methods, this is it! -Static Methods +Static methods -------------- Non-data descriptors provide a simple mechanism for variations on the usual @@ -926,7 +927,7 @@ Using the non-data descriptor protocol, a pure Python version of return self.f -Class Methods +Class methods ------------- Unlike static methods, class methods prepend the class reference to the @@ -991,8 +992,8 @@ For example, a classmethod and property could be chained together:: def __doc__(cls): return f'A doc for {cls.__name__!r}' -Member Objects --------------- +Member objects and __slots__ +---------------------------- When a class defines ``__slots__``, it replaces instance dictionaries with a fixed-length array of slot values. From a user point of view that has