Minor readability improvements. Also note performance impact of __slots__. (GH-24456)

1 files changed, 11 insertions, 8 deletions

diff --git a/Doc/howto/descriptor.rst b/Doc/howto/descriptor.rst
index 5455d914dce..94a8b4e6b40 100644
--- a/Doc/howto/descriptor.rst
+++ b/Doc/howto/descriptor.rst
@@ -42,8 +42,8 @@ add new capabilities one by one.
 Simple example: A descriptor that returns a constant
 ----------------------------------------------------
 
-The :class:`Ten` class is a descriptor that always returns the constant ``10``
-from its :meth:`__get__` method:
+The :class:`Ten` class is a descriptor whose :meth:`__get__` method always
+returns the constant ``10``:
 
 .. testcode::
 
@@ -70,10 +70,10 @@ and descriptor lookup:
     >>> a.y                         # Descriptor lookup
     10
 
-In the ``a.x`` attribute lookup, the dot operator finds the key ``x`` and the
-value ``5`` in the class dictionary.  In the ``a.y`` lookup, the dot operator
-finds a descriptor instance, recognized by its ``__get__`` method, and calls
-that method which returns ``10``.
+In the ``a.x`` attribute lookup, the dot operator finds ``'x': 5``
+in the class dictionary.  In the ``a.y`` lookup, the dot operator
+finds a descriptor instance, recognized by its ``__get__`` method.
+Calling that method returns ``10``.
 
 Note that the value ``10`` is not stored in either the class dictionary or the
 instance dictionary.  Instead, the value ``10`` is computed on demand.
@@ -300,7 +300,7 @@ used in cases where a descriptor needs to know either the class where it was
 created or the name of class variable it was assigned to.  (This method, if
 present, is called even if the class is not a descriptor.)
 
-Descriptors get invoked by the dot "operator" during attribute lookup.  If a
+Descriptors get invoked by the dot operator during attribute lookup.  If a
 descriptor is accessed indirectly with ``vars(some_class)[descriptor_name]``,
 the descriptor instance is returned without invoking it.
 
@@ -1380,7 +1380,10 @@ takes 48 bytes with ``__slots__`` and 152 bytes without.  This `flyweight
 design pattern <https://en.wikipedia.org/wiki/Flyweight_pattern>`_ likely only
 matters when a large number of instances are going to be created.
 
-4. Blocks tools like :func:`functools.cached_property` which require an
+4. Improves speed.  Reading instance variables is 35% faster with
+``__slots__`` (as measured with Python 3.10 on an Apple M1 processor).
+
+5. Blocks tools like :func:`functools.cached_property` which require an
 instance dictionary to function correctly:
 
 .. testcode::