added chapter map to README

23-descriptor/README.rst

@@ -0,0 +1,4 @@
+Sample code for Chapter 20 - "Attribute descriptors"
+
+From the book "Fluent Python" by Luciano Ramalho (O'Reilly, 2015)
+http://shop.oreilly.com/product/0636920032519.do

23-descriptor/bulkfood/bulkfood_v3.py

@@ -0,0 +1,61 @@
+"""
+
+A line item for a bulk food order has description, weight and price fields::
+
+    >>> raisins = LineItem('Golden raisins', 10, 6.95)
+    >>> raisins.weight, raisins.description, raisins.price
+    (10, 'Golden raisins', 6.95)
+
+A ``subtotal`` method gives the total price for that line item::
+
+    >>> raisins.subtotal()
+    69.5
+
+The weight of a ``LineItem`` must be greater than 0::
+
+    >>> raisins.weight = -20
+    Traceback (most recent call last):
+        ...
+    ValueError: value must be > 0
+
+Negative or 0 price is not acceptable either::
+
+    >>> truffle = LineItem('White truffle', 100, 0)
+    Traceback (most recent call last):
+        ...
+    ValueError: value must be > 0
+
+
+No change was made::
+
+    >>> raisins.weight
+    10
+
+"""
+
+
+# BEGIN LINEITEM_V3
+class Quantity:  # <1>
+
+    def __init__(self, storage_name):
+        self.storage_name = storage_name  # <2>
+
+    def __set__(self, instance, value):  # <3>
+        if value > 0:
+            instance.__dict__[self.storage_name] = value  # <4>
+        else:
+            raise ValueError('value must be > 0')
+
+
+class LineItem:
+    weight = Quantity('weight')  # <5>
+    price = Quantity('price')  # <6>
+
+    def __init__(self, description, weight, price):  # <7>
+        self.description = description
+        self.weight = weight
+        self.price = price
+
+    def subtotal(self):
+        return self.weight * self.price
+# END LINEITEM_V3

23-descriptor/bulkfood/bulkfood_v4.py

@@ -0,0 +1,74 @@
+"""
+
+A line item for a bulk food order has description, weight and price fields::
+
+    >>> raisins = LineItem('Golden raisins', 10, 6.95)
+    >>> raisins.weight, raisins.description, raisins.price
+    (10, 'Golden raisins', 6.95)
+
+A ``subtotal`` method gives the total price for that line item::
+
+    >>> raisins.subtotal()
+    69.5
+
+The weight of a ``LineItem`` must be greater than 0::
+
+    >>> raisins.weight = -20
+    Traceback (most recent call last):
+        ...
+    ValueError: value must be > 0
+
+No change was made::
+
+    >>> raisins.weight
+    10
+
+The value of the attributes managed by the descriptors are stored in
+alternate attributes, created by the descriptors in each ``LineItem``
+instance::
+
+    >>> raisins = LineItem('Golden raisins', 10, 6.95)
+    >>> dir(raisins)  # doctest: +ELLIPSIS +NORMALIZE_WHITESPACE
+    ['_Quantity#0', '_Quantity#1', '__class__', ...
+     'description', 'price', 'subtotal', 'weight']
+    >>> getattr(raisins, '_Quantity#0')
+    10
+    >>> getattr(raisins, '_Quantity#1')
+    6.95
+
+"""
+
+
+# BEGIN LINEITEM_V4
+class Quantity:
+    __counter = 0  # <1>
+
+    def __init__(self):
+        cls = self.__class__  # <2>
+        prefix = cls.__name__
+        index = cls.__counter
+        self.storage_name = '_{}#{}'.format(prefix, index)  # <3>
+        cls.__counter += 1  # <4>
+
+    def __get__(self, instance, owner):  # <5>
+        return getattr(instance, self.storage_name)  # <6>
+
+    def __set__(self, instance, value):
+        if value > 0:
+            setattr(instance, self.storage_name, value)  # <7>
+        else:
+            raise ValueError('value must be > 0')
+
+
+class LineItem:
+    weight = Quantity()  # <8>
+    price = Quantity()
+
+    def __init__(self, description, weight, price):
+        self.description = description
+        self.weight = weight
+        self.price = price
+
+    def subtotal(self):
+        return self.weight * self.price
+# END LINEITEM_V4

23-descriptor/bulkfood/bulkfood_v4b.py

@@ -0,0 +1,85 @@
+"""
+
+A line item for a bulk food order has description, weight and price fields::
+
+    >>> raisins = LineItem('Golden raisins', 10, 6.95)
+    >>> raisins.weight, raisins.description, raisins.price
+    (10, 'Golden raisins', 6.95)
+
+A ``subtotal`` method gives the total price for that line item::
+
+    >>> raisins.subtotal()
+    69.5
+
+The weight of a ``LineItem`` must be greater than 0::
+
+    >>> raisins.weight = -20
+    Traceback (most recent call last):
+        ...
+    ValueError: value must be > 0
+
+No change was made::
+
+    >>> raisins.weight
+    10
+
+The value of the attributes managed by the descriptors are stored in
+alternate attributes, created by the descriptors in each ``LineItem``
+instance::
+
+    >>> raisins = LineItem('Golden raisins', 10, 6.95)
+    >>> dir(raisins)  # doctest: +ELLIPSIS +NORMALIZE_WHITESPACE
+    ['_Quantity#0', '_Quantity#1', '__class__', ...
+     'description', 'price', 'subtotal', 'weight']
+    >>> getattr(raisins, '_Quantity#0')
+    10
+    >>> getattr(raisins, '_Quantity#1')
+    6.95
+
+If the descriptor is accessed in the class, the descriptor object is
+returned:
+
+    >>> LineItem.weight  # doctest: +ELLIPSIS
+    <bulkfood_v4b.Quantity object at 0x...>
+    >>> LineItem.weight.storage_name
+    '_Quantity#0'
+
+"""
+
+
+# BEGIN LINEITEM_V4B
+class Quantity:
+    __counter = 0
+
+    def __init__(self):
+        cls = self.__class__
+        prefix = cls.__name__
+        index = cls.__counter
+        self.storage_name = '_{}#{}'.format(prefix, index)
+        cls.__counter += 1
+
+    def __get__(self, instance, owner):
+        if instance is None:
+            return self  # <1>
+        else:
+            return getattr(instance, self.storage_name)  # <2>
+
+    def __set__(self, instance, value):
+        if value > 0:
+            setattr(instance, self.storage_name, value)
+        else:
+            raise ValueError('value must be > 0')
+# END LINEITEM_V4B
+
+
+class LineItem:
+    weight = Quantity()
+    price = Quantity()
+
+    def __init__(self, description, weight, price):
+        self.description = description
+        self.weight = weight
+        self.price = price
+
+    def subtotal(self):
+        return self.weight * self.price

23-descriptor/bulkfood/bulkfood_v4c.py

@@ -0,0 +1,65 @@
+"""
+
+A line item for a bulk food order has description, weight and price fields::
+
+    >>> raisins = LineItem('Golden raisins', 10, 6.95)
+    >>> raisins.weight, raisins.description, raisins.price
+    (10, 'Golden raisins', 6.95)
+
+A ``subtotal`` method gives the total price for that line item::
+
+    >>> raisins.subtotal()
+    69.5
+
+The weight of a ``LineItem`` must be greater than 0::
+
+    >>> raisins.weight = -20
+    Traceback (most recent call last):
+        ...
+    ValueError: value must be > 0
+
+No change was made::
+
+    >>> raisins.weight
+    10
+
+The value of the attributes managed by the descriptors are stored in
+alternate attributes, created by the descriptors in each ``LineItem``
+instance::
+
+    >>> raisins = LineItem('Golden raisins', 10, 6.95)
+    >>> dir(raisins)  # doctest: +ELLIPSIS +NORMALIZE_WHITESPACE
+    ['_Quantity#0', '_Quantity#1', '__class__', ...
+     'description', 'price', 'subtotal', 'weight']
+    >>> getattr(raisins, '_Quantity#0')
+    10
+    >>> getattr(raisins, '_Quantity#1')
+    6.95
+
+If the descriptor is accessed in the class, the descriptor object is
+returned:
+
+    >>> LineItem.weight  # doctest: +ELLIPSIS
+    <model_v4c.Quantity object at 0x...>
+    >>> LineItem.weight.storage_name
+    '_Quantity#0'
+
+
+"""
+
+# BEGIN LINEITEM_V4C
+import model_v4c as model  # <1>
+
+
+class LineItem:
+    weight = model.Quantity()  # <2>
+    price = model.Quantity()
+
+    def __init__(self, description, weight, price):
+        self.description = description
+        self.weight = weight
+        self.price = price
+
+    def subtotal(self):
+        return self.weight * self.price
+# END LINEITEM_V4C

23-descriptor/bulkfood/bulkfood_v4prop.py

@@ -0,0 +1,74 @@
+"""
+
+A line item for a bulk food order has description, weight and price fields::
+
+    >>> raisins = LineItem('Golden raisins', 10, 6.95)
+    >>> raisins.weight, raisins.description, raisins.price
+    (10, 'Golden raisins', 6.95)
+
+A ``subtotal`` method gives the total price for that line item::
+
+    >>> raisins.subtotal()
+    69.5
+
+The weight of a ``LineItem`` must be greater than 0::
+
+    >>> raisins.weight = -20
+    Traceback (most recent call last):
+        ...
+    ValueError: value must be > 0
+
+No change was made::
+
+    >>> raisins.weight
+    10
+
+The value of the attributes managed by the descriptors are stored in
+alternate attributes, created by the descriptors in each ``LineItem``
+instance::
+
+    >>> raisins = LineItem('Golden raisins', 10, 6.95)
+    >>> dir(raisins)  # doctest: +ELLIPSIS +NORMALIZE_WHITESPACE
+    [... '_quantity:0', '_quantity:1', 'description',
+    'price', 'subtotal', 'weight']
+    >>> getattr(raisins, '_quantity:0')
+    10
+    >>> getattr(raisins, '_quantity:1')
+    6.95
+
+"""
+
+
+# BEGIN LINEITEM_V4_PROP
+def quantity():  # <1>
+    try:
+        quantity.counter += 1  # <2>
+    except AttributeError:
+        quantity.counter = 0  # <3>
+
+    storage_name = '_{}:{}'.format('quantity', quantity.counter)  # <4>
+
+    def qty_getter(instance):  # <5>
+        return getattr(instance, storage_name)
+
+    def qty_setter(instance, value):
+        if value > 0:
+            setattr(instance, storage_name, value)
+        else:
+            raise ValueError('value must be > 0')
+
+    return property(qty_getter, qty_setter)
+# END LINEITEM_V4_PROP
+
+class LineItem:
+    weight = quantity()
+    price = quantity()
+
+    def __init__(self, description, weight, price):
+        self.description = description
+        self.weight = weight
+        self.price = price
+
+    def subtotal(self):
+        return self.weight * self.price
+

23-descriptor/bulkfood/bulkfood_v5.py

@@ -0,0 +1,79 @@
+"""
+
+A line item for a bulk food order has description, weight and price fields::
+
+    >>> raisins = LineItem('Golden raisins', 10, 6.95)
+    >>> raisins.weight, raisins.description, raisins.price
+    (10, 'Golden raisins', 6.95)
+
+A ``subtotal`` method gives the total price for that line item::
+
+    >>> raisins.subtotal()
+    69.5
+
+The weight of a ``LineItem`` must be greater than 0::
+
+    >>> raisins.weight = -20
+    Traceback (most recent call last):
+        ...
+    ValueError: value must be > 0
+
+No change was made::
+
+    >>> raisins.weight
+    10
+
+The value of the attributes managed by the descriptors are stored in
+alternate attributes, created by the descriptors in each ``LineItem``
+instance::
+
+    >>> raisins = LineItem('Golden raisins', 10, 6.95)
+    >>> dir(raisins)  # doctest: +ELLIPSIS +NORMALIZE_WHITESPACE
+    ['_NonBlank#0', '_Quantity#0', '_Quantity#1', '__class__', ...
+     'description', 'price', 'subtotal', 'weight']
+    >>> getattr(raisins, '_Quantity#0')
+    10
+    >>> getattr(raisins, '_NonBlank#0')
+    'Golden raisins'
+
+If the descriptor is accessed in the class, the descriptor object is
+returned:
+
+    >>> LineItem.weight  # doctest: +ELLIPSIS
+    <model_v5.Quantity object at 0x...>
+    >>> LineItem.weight.storage_name
+    '_Quantity#0'
+
+The `NonBlank` descriptor prevents empty or blank strings to be used
+for the description:
+
+    >>> br_nuts = LineItem('Brazil Nuts', 10, 34.95)
+    >>> br_nuts.description = ' '
+    Traceback (most recent call last):
+        ...
+    ValueError: value cannot be empty or blank
+    >>> void = LineItem('', 1, 1)
+    Traceback (most recent call last):
+        ...
+    ValueError: value cannot be empty or blank
+
+
+"""
+
+# BEGIN LINEITEM_V5
+import model_v5 as model  # <1>
+
+
+class LineItem:
+    description = model.NonBlank()  # <2>
+    weight = model.Quantity()
+    price = model.Quantity()
+
+    def __init__(self, description, weight, price):
+        self.description = description
+        self.weight = weight
+        self.price = price
+
+    def subtotal(self):
+        return self.weight * self.price
+# END LINEITEM_V5

23-descriptor/bulkfood/bulkfood_v5_check.py

@@ -0,0 +1,85 @@
+"""
+
+A line item for a bulk food order has description, weight and price fields::
+
+    >>> raisins = LineItem('Golden raisins', 10, 6.95)
+    >>> raisins.weight, raisins.description, raisins.price
+    (10, 'Golden raisins', 6.95)
+
+A ``subtotal`` method gives the total price for that line item::
+
+    >>> raisins.subtotal()
+    69.5
+
+The weight of a ``LineItem`` must be greater than 0::
+
+    >>> raisins.weight = -20
+    Traceback (most recent call last):
+        ...
+    ValueError: value must be > 0; -20 is not valid.
+
+No change was made::
+
+    >>> raisins.weight
+    10
+
+The value of the attributes managed by the descriptors are stored in
+alternate attributes, created by the descriptors in each ``LineItem``
+instance::
+
+    >>> raisins = LineItem('Golden raisins', 10, 6.95)
+    >>> dir(raisins)  # doctest: +ELLIPSIS +NORMALIZE_WHITESPACE
+    ['_Check#0', '_Check#1', '_Check#2', '__class__', ...
+     'description', 'price', 'subtotal', 'weight']
+    >>> [getattr(raisins, name) for name in dir(raisins) if name.startswith('_Check#')]
+    ['Golden raisins', 10, 6.95]
+
+If the descriptor is accessed in the class, the descriptor object is
+returned:
+
+    >>> LineItem.weight  # doctest: +ELLIPSIS
+    <model_v5_check.Check object at 0x...>
+    >>> LineItem.weight.storage_name
+    '_Check#1'
+
+The `NonBlank` descriptor prevents empty or blank strings to be used
+for the description:
+
+    >>> br_nuts = LineItem('Brazil Nuts', 10, 34.95)
+    >>> br_nuts.description = ' '
+    Traceback (most recent call last):
+        ...
+    ValueError: ' ' is not valid.
+    >>> void = LineItem('', 1, 1)
+    Traceback (most recent call last):
+        ...
+    ValueError: '' is not valid.
+
+
+
+"""
+
+import model_v5_check as model
+
+def gt_zero(x):
+    '''value must be > 0'''
+    return x if x > 0 else model.INVALID
+
+def non_blank(txt):
+    txt = txt.strip()
+    return txt if txt else model.INVALID
+
+
+class LineItem:
+    description = model.Check(non_blank)
+    weight = model.Check(gt_zero)
+    price = model.Check(gt_zero)
+
+    def __init__(self, description, weight, price):
+        self.description = description
+        self.weight = weight
+        self.price = price
+
+    def subtotal(self):
+        return self.weight * self.price
+

23-descriptor/bulkfood/model_v4c.py

@@ -0,0 +1,23 @@
+# BEGIN MODEL_V4
+class Quantity:
+    __counter = 0
+
+    def __init__(self):
+        cls = self.__class__
+        prefix = cls.__name__
+        index = cls.__counter
+        self.storage_name = '_{}#{}'.format(prefix, index)
+        cls.__counter += 1
+
+    def __get__(self, instance, owner):
+        if instance is None:
+            return self
+        else:
+            return getattr(instance, self.storage_name)
+
+    def __set__(self, instance, value):
+        if value > 0:
+            setattr(instance, self.storage_name, value)
+        else:
+            raise ValueError('value must be > 0')
+# END MODEL_V4

23-descriptor/bulkfood/model_v5.py

@@ -0,0 +1,54 @@
+# BEGIN MODEL_V5
+import abc
+
+
+class AutoStorage:  # <1>
+    __counter = 0
+
+    def __init__(self):
+        cls = self.__class__
+        prefix = cls.__name__
+        index = cls.__counter
+        self.storage_name = '_{}#{}'.format(prefix, index)
+        cls.__counter += 1
+
+    def __get__(self, instance, owner):
+        if instance is None:
+            return self
+        else:
+            return getattr(instance, self.storage_name)
+
+    def __set__(self, instance, value):
+        setattr(instance, self.storage_name, value)  # <2>
+
+
+class Validated(abc.ABC, AutoStorage):  # <3>
+
+    def __set__(self, instance, value):
+        value = self.validate(instance, value)  # <4>
+        super().__set__(instance, value)  # <5>
+
+    @abc.abstractmethod
+    def validate(self, instance, value):  # <6>
+        """return validated value or raise ValueError"""
+
+
+class Quantity(Validated):  # <7>
+    """a number greater than zero"""
+
+    def validate(self, instance, value):
+        if value <= 0:
+            raise ValueError('value must be > 0')
+        return value
+
+
+class NonBlank(Validated):
+    """a string with at least one non-space character"""
+
+    def validate(self, instance, value):
+        value = value.strip()
+        if len(value) == 0:
+            raise ValueError('value cannot be empty or blank')
+        return value  # <8>
+
+# END MODEL_V5

23-descriptor/bulkfood/model_v5_check.py

@@ -0,0 +1,52 @@
+import abc
+
+
+class AutoStorage:
+    __counter = 0
+
+    def __init__(self):
+        cls = self.__class__
+        prefix = cls.__name__
+        index = cls.__counter
+        self.storage_name = '_{}#{}'.format(prefix, index)
+        cls.__counter += 1
+
+    def __get__(self, instance, owner):
+        if instance is None:
+            return self
+        else:
+            return getattr(instance, self.storage_name)
+
+    def __set__(self, instance, value):
+        setattr(instance, self.storage_name, value)
+
+
+class Validated(abc.ABC, AutoStorage):
+
+    def __set__(self, instance, value):
+        value = self.validate(instance, value)
+        super().__set__(instance, value)
+
+    @abc.abstractmethod
+    def validate(self, instance, value):
+        """return validated value or raise ValueError"""
+
+INVALID = object()
+
+class Check(Validated):
+
+    def __init__(self, checker):
+        super().__init__()
+        self.checker = checker
+        if checker.__doc__ is None:
+            doc = ''
+        else:
+            doc = checker.__doc__ + '; '
+        self.message = doc + '{!r} is not valid.'
+
+
+    def validate(self, instance, value):
+        result = self.checker(value)
+        if result is INVALID:
+            raise ValueError(self.message.format(value))
+        return result

23-descriptor/descriptorkinds.py

@@ -0,0 +1,199 @@
+"""
+Overriding descriptor (a.k.a. data descriptor or enforced descriptor):
+
+# BEGIN DESCR_KINDS_DEMO1
+
+    >>> obj = Managed()  # <1>
+    >>> obj.over  # <2>
+    -> Overriding.__get__(<Overriding object>, <Managed object>, <class Managed>)
+    >>> Managed.over  # <3>
+    -> Overriding.__get__(<Overriding object>, None, <class Managed>)
+    >>> obj.over = 7  # <4>
+    -> Overriding.__set__(<Overriding object>, <Managed object>, 7)
+    >>> obj.over  # <5>
+    -> Overriding.__get__(<Overriding object>, <Managed object>, <class Managed>)
+    >>> obj.__dict__['over'] = 8  # <6>
+    >>> vars(obj)  # <7>
+    {'over': 8}
+    >>> obj.over  # <8>
+    -> Overriding.__get__(<Overriding object>, <Managed object>, <class Managed>)
+
+# END DESCR_KINDS_DEMO1
+
+Overriding descriptor without ``__get__``:
+
+(these tests are reproduced below without +ELLIPSIS directives for inclusion in the book;
+look for DESCR_KINDS_DEMO2)
+
+    >>> obj.over_no_get  # doctest: +ELLIPSIS
+    <descriptorkinds.OverridingNoGet object at 0x...>
+    >>> Managed.over_no_get  # doctest: +ELLIPSIS
+    <descriptorkinds.OverridingNoGet object at 0x...>
+    >>> obj.over_no_get = 7
+    -> OverridingNoGet.__set__(<OverridingNoGet object>, <Managed object>, 7)
+    >>> obj.over_no_get  # doctest: +ELLIPSIS
+    <descriptorkinds.OverridingNoGet object at 0x...>
+    >>> obj.__dict__['over_no_get'] = 9
+    >>> obj.over_no_get
+    9
+    >>> obj.over_no_get = 7
+    -> OverridingNoGet.__set__(<OverridingNoGet object>, <Managed object>, 7)
+    >>> obj.over_no_get
+    9
+
+Non-overriding descriptor (a.k.a. non-data descriptor or shadowable descriptor):
+
+# BEGIN DESCR_KINDS_DEMO3
+
+    >>> obj = Managed()
+    >>> obj.non_over  # <1>
+    -> NonOverriding.__get__(<NonOverriding object>, <Managed object>, <class Managed>)
+    >>> obj.non_over = 7  # <2>
+    >>> obj.non_over  # <3>
+    7
+    >>> Managed.non_over  # <4>
+    -> NonOverriding.__get__(<NonOverriding object>, None, <class Managed>)
+    >>> del obj.non_over  # <5>
+    >>> obj.non_over  # <6>
+    -> NonOverriding.__get__(<NonOverriding object>, <Managed object>, <class Managed>)
+
+# END DESCR_KINDS_DEMO3
+
+No descriptor type survives being overwritten on the class itself:
+
+# BEGIN DESCR_KINDS_DEMO4
+
+    >>> obj = Managed()  # <1>
+    >>> Managed.over = 1  # <2>
+    >>> Managed.over_no_get = 2
+    >>> Managed.non_over = 3
+    >>> obj.over, obj.over_no_get, obj.non_over  # <3>
+    (1, 2, 3)
+
+# END DESCR_KINDS_DEMO4
+
+Methods are non-overriding descriptors:
+
+    >>> obj.spam  # doctest: +ELLIPSIS
+    <bound method Managed.spam of <descriptorkinds.Managed object at 0x...>>
+    >>> Managed.spam  # doctest: +ELLIPSIS
+    <function Managed.spam at 0x...>
+    >>> obj.spam()
+    -> Managed.spam(<Managed object>)
+    >>> Managed.spam()
+    Traceback (most recent call last):
+      ...
+    TypeError: spam() missing 1 required positional argument: 'self'
+    >>> Managed.spam(obj)
+    -> Managed.spam(<Managed object>)
+    >>> Managed.spam.__get__(obj)  # doctest: +ELLIPSIS
+    <bound method Managed.spam of <descriptorkinds.Managed object at 0x...>>
+    >>> obj.spam.__func__ is Managed.spam
+    True
+    >>> obj.spam = 7
+    >>> obj.spam
+    7
+
+
+"""
+
+"""
+NOTE: These tests are here because I can't add callouts after +ELLIPSIS
+directives and if doctest runs them without +ELLIPSIS I get test failures.
+
+# BEGIN DESCR_KINDS_DEMO2
+
+    >>> obj.over_no_get  # <1>
+    <__main__.OverridingNoGet object at 0x665bcc>
+    >>> Managed.over_no_get  # <2>
+    <__main__.OverridingNoGet object at 0x665bcc>
+    >>> obj.over_no_get = 7  # <3>
+    -> OverridingNoGet.__set__(<OverridingNoGet object>, <Managed object>, 7)
+    >>> obj.over_no_get  # <4>
+    <__main__.OverridingNoGet object at 0x665bcc>
+    >>> obj.__dict__['over_no_get'] = 9  # <5>
+    >>> obj.over_no_get  # <6>
+    9
+    >>> obj.over_no_get = 7  # <7>
+    -> OverridingNoGet.__set__(<OverridingNoGet object>, <Managed object>, 7)
+    >>> obj.over_no_get  # <8>
+    9
+
+# END DESCR_KINDS_DEMO2
+
+Methods are non-overriding descriptors:
+
+# BEGIN DESCR_KINDS_DEMO5
+
+    >>> obj = Managed()
+    >>> obj.spam  # <1>
+    <bound method Managed.spam of <descriptorkinds.Managed object at 0x74c80c>>
+    >>> Managed.spam  # <2>
+    <function Managed.spam at 0x734734>
+    >>> obj.spam = 7  # <3>
+    >>> obj.spam
+    7
+
+# END DESCR_KINDS_DEMO5
+
+"""
+
+# BEGIN DESCR_KINDS
+
+### auxiliary functions for display only ###
+
+def cls_name(obj_or_cls):
+    cls = type(obj_or_cls)
+    if cls is type:
+        cls = obj_or_cls
+    return cls.__name__.split('.')[-1]
+
+def display(obj):
+    cls = type(obj)
+    if cls is type:
+        return '<class {}>'.format(obj.__name__)
+    elif cls in [type(None), int]:
+        return repr(obj)
+    else:
+        return '<{} object>'.format(cls_name(obj))
+
+def print_args(name, *args):
+    pseudo_args = ', '.join(display(x) for x in args)
+    print('-> {}.__{}__({})'.format(cls_name(args[0]), name, pseudo_args))
+
+
+### essential classes for this example ###
+
+class Overriding:  # <1>
+    """a.k.a. data descriptor or enforced descriptor"""
+
+    def __get__(self, instance, owner):
+        print_args('get', self, instance, owner)  # <2>
+
+    def __set__(self, instance, value):
+        print_args('set', self, instance, value)
+
+
+class OverridingNoGet:  # <3>
+    """an overriding descriptor without ``__get__``"""
+
+    def __set__(self, instance, value):
+        print_args('set', self, instance, value)
+
+
+class NonOverriding:  # <4>
+    """a.k.a. non-data or shadowable descriptor"""
+
+    def __get__(self, instance, owner):
+        print_args('get', self, instance, owner)
+
+
+class Managed:  # <5>
+    over = Overriding()
+    over_no_get = OverridingNoGet()
+    non_over = NonOverriding()
+
+    def spam(self):  # <6>
+        print('-> Managed.spam({})'.format(display(self)))
+
+# END DESCR_KINDS

23-descriptor/descriptorkinds_dump.py

@@ -0,0 +1,169 @@
+
+
+"""
+Overriding descriptor (a.k.a. data descriptor or enforced descriptor):
+
+    >>> obj = Model()
+    >>> obj.over  # doctest: +ELLIPSIS
+    Overriding.__get__() invoked with args:
+        self     = <descriptorkinds.Overriding object at 0x...>
+        instance = <descriptorkinds.Model object at 0x...>
+        owner    = <class 'descriptorkinds.Model'>
+    >>> Model.over  # doctest: +ELLIPSIS
+    Overriding.__get__() invoked with args:
+        self     = <descriptorkinds.Overriding object at 0x...>
+        instance = None
+        owner    = <class 'descriptorkinds.Model'>
+
+
+An overriding descriptor cannot be shadowed by assigning to an instance:
+
+    >>> obj = Model()
+    >>> obj.over = 7  # doctest: +ELLIPSIS
+    Overriding.__set__() invoked with args:
+        self     = <descriptorkinds.Overriding object at 0x...>
+        instance = <descriptorkinds.Model object at 0x...>
+        value    = 7
+    >>> obj.over  # doctest: +ELLIPSIS
+    Overriding.__get__() invoked with args:
+        self     = <descriptorkinds.Overriding object at 0x...>
+        instance = <descriptorkinds.Model object at 0x...>
+        owner    = <class 'descriptorkinds.Model'>
+
+
+Not even by poking the attribute into the instance ``__dict__``:
+
+    >>> obj.__dict__['over'] = 8
+    >>> obj.over  # doctest: +ELLIPSIS
+    Overriding.__get__() invoked with args:
+        self     = <descriptorkinds.Overriding object at 0x...>
+        instance = <descriptorkinds.Model object at 0x...>
+        owner    = <class 'descriptorkinds.Model'>
+    >>> vars(obj)
+    {'over': 8}
+
+Overriding descriptor without ``__get__``:
+
+    >>> obj.over_no_get  # doctest: +ELLIPSIS
+    <descriptorkinds.OverridingNoGet object at 0x...>
+    >>> Model.over_no_get   # doctest: +ELLIPSIS
+    <descriptorkinds.OverridingNoGet object at 0x...>
+    >>> obj.over_no_get = 7  # doctest: +ELLIPSIS
+    OverridingNoGet.__set__() invoked with args:
+        self     = <descriptorkinds.OverridingNoGet object at 0x...>
+        instance = <descriptorkinds.Model object at 0x...>
+        value    = 7
+    >>> obj.over_no_get  # doctest: +ELLIPSIS
+    <descriptorkinds.OverridingNoGet object at 0x...>
+
+
+Poking the attribute into the instance ``__dict__`` means you can read the new
+value for the attribute, but setting it still triggers ``__set__``:
+
+    >>> obj.__dict__['over_no_get'] = 9
+    >>> obj.over_no_get
+    9
+    >>> obj.over_no_get = 7  # doctest: +ELLIPSIS
+    OverridingNoGet.__set__() invoked with args:
+        self     = <descriptorkinds.OverridingNoGet object at 0x...>
+        instance = <descriptorkinds.Model object at 0x...>
+        value    = 7
+    >>> obj.over_no_get
+    9
+
+
+Non-overriding descriptor (a.k.a. non-data descriptor or shadowable descriptor):
+
+    >>> obj = Model()
+    >>> obj.non_over  # doctest: +ELLIPSIS
+    NonOverriding.__get__() invoked with args:
+        self     = <descriptorkinds.NonOverriding object at 0x...>
+        instance = <descriptorkinds.Model object at 0x...>
+        owner    = <class 'descriptorkinds.Model'>
+    >>> Model.non_over  # doctest: +ELLIPSIS
+    NonOverriding.__get__() invoked with args:
+        self     = <descriptorkinds.NonOverriding object at 0x...>
+        instance = None
+        owner    = <class 'descriptorkinds.Model'>
+
+
+A non-overriding descriptor can be shadowed by assigning to an instance:
+
+    >>> obj.non_over = 7
+    >>> obj.non_over
+    7
+
+
+Methods are non-over descriptors:
+
+    >>> obj.spam  # doctest: +ELLIPSIS
+    <bound method Model.spam of <descriptorkinds.Model object at 0x...>>
+    >>> Model.spam  # doctest: +ELLIPSIS
+    <function Model.spam at 0x...>
+    >>> obj.spam()  # doctest: +ELLIPSIS
+    Model.spam() invoked with arg:
+        self = <descriptorkinds.Model object at 0x...>
+    >>> obj.spam = 7
+    >>> obj.spam
+    7
+
+
+No descriptor type survives being overwritten on the class itself:
+
+    >>> Model.over = 1
+    >>> obj.over
+    1
+    >>> Model.over_no_get = 2
+    >>> obj.over_no_get
+    2
+    >>> Model.non_over = 3
+    >>> obj.non_over
+    7
+
+"""
+
+# BEGIN DESCRIPTORKINDS
+def print_args(name, *args):  # <1>
+    cls_name = args[0].__class__.__name__
+    arg_names = ['self', 'instance', 'owner']
+    if name == 'set':
+        arg_names[-1] = 'value'
+    print('{}.__{}__() invoked with args:'.format(cls_name, name))
+    for arg_name, value in zip(arg_names, args):
+        print('    {:8} = {}'.format(arg_name, value))
+
+
+class Overriding:  # <2>
+    """a.k.a. data descriptor or enforced descriptor"""
+
+    def __get__(self, instance, owner):
+        print_args('get', self, instance, owner)  # <3>
+
+    def __set__(self, instance, value):
+        print_args('set', self, instance, value)
+
+
+class OverridingNoGet:  # <4>
+    """an overriding descriptor without ``__get__``"""
+
+    def __set__(self, instance, value):
+        print_args('set', self, instance, value)
+
+
+class NonOverriding:  # <5>
+    """a.k.a. non-data or shadowable descriptor"""
+
+    def __get__(self, instance, owner):
+        print_args('get', self, instance, owner)
+
+
+class Model:  # <6>
+    over = Overriding()
+    over_no_get = OverridingNoGet()
+    non_over = NonOverriding()
+
+    def spam(self):  # <7>
+        print('Model.spam() invoked with arg:')
+        print('    self =', self)
+
+#END DESCRIPTORKINDS

23-descriptor/method_is_descriptor.py

@@ -0,0 +1,41 @@
+"""
+# BEGIN FUNC_DESCRIPTOR_DEMO
+
+    >>> word = Text('forward')
+    >>> word  # <1>
+    Text('forward')
+    >>> word.reverse()  # <2>
+    Text('drawrof')
+    >>> Text.reverse(Text('backward'))  # <3>
+    Text('drawkcab')
+    >>> type(Text.reverse), type(word.reverse)  # <4>
+    (<class 'function'>, <class 'method'>)
+    >>> list(map(Text.reverse, ['repaid', (10, 20, 30), Text('stressed')]))  # <5>
+    ['diaper', (30, 20, 10), Text('desserts')]
+    >>> Text.reverse.__get__(word)  # <6>
+    <bound method Text.reverse of Text('forward')>
+    >>> Text.reverse.__get__(None, Text)  # <7>
+    <function Text.reverse at 0x101244e18>
+    >>> word.reverse  # <8>
+    <bound method Text.reverse of Text('forward')>
+    >>> word.reverse.__self__  # <9>
+    Text('forward')
+    >>> word.reverse.__func__ is Text.reverse  # <10>
+    True
+
+# END FUNC_DESCRIPTOR_DEMO
+"""
+
+# BEGIN FUNC_DESCRIPTOR_EX
+import collections
+
+
+class Text(collections.UserString):
+
+    def __repr__(self):
+        return 'Text({!r})'.format(self.data)
+
+    def reverse(self):
+        return self[::-1]
+
+# END FUNC_DESCRIPTOR_EX