renumbering chapters >= 19

23-descriptor/bulkfood/bulkfood_v3.py

@@ -0,0 +1,67 @@
+"""
+
+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: weight must be > 0
+
+Negative or 0 price is not acceptable either::
+
+    >>> truffle = LineItem('White truffle', 100, 0)
+    Traceback (most recent call last):
+        ...
+    ValueError: price must be > 0
+
+No change was made::
+
+    >>> raisins.weight
+    10
+
+"""
+
+
+# tag::LINEITEM_QUANTITY_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:
+            msg = f'{self.storage_name} must be > 0'
+            raise ValueError(msg)
+
+    def __get__(self, instance, owner):  # <5>
+        return instance.__dict__[self.storage_name]
+
+
+# end::LINEITEM_QUANTITY_V3[]
+
+# tag::LINEITEM_V3[]
+class LineItem:
+    weight = Quantity('weight')  # <1>
+    price = Quantity('price')  # <2>
+
+    def __init__(self, description, weight, price):  # <3>
+        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,70 @@
+"""
+
+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: weight must be > 0
+
+No change was made::
+
+    >>> raisins.weight
+    10
+
+Negative or 0 price is not acceptable either::
+
+    >>> truffle = LineItem('White truffle', 100, 0)
+    Traceback (most recent call last):
+        ...
+    ValueError: price must be > 0
+
+If the descriptor is accessed in the class, the descriptor object is
+returned:
+
+    >>> LineItem.weight  # doctest: +ELLIPSIS
+    <bulkfood_v4.Quantity object at 0x...>
+    >>> LineItem.weight.storage_name
+    'weight'
+
+"""
+
+
+# tag::LINEITEM_V4[]
+class Quantity:
+
+    def __set_name__(self, owner, name):  # <1>
+        self.storage_name = name          # <2>
+
+    def __set__(self, instance, value):   # <3>
+        if value > 0:
+            instance.__dict__[self.storage_name] = value
+        else:
+            msg = f'{self.storage_name} must be > 0'
+            raise ValueError(msg)
+
+    # no __get__ needed  # <4>
+
+class LineItem:
+    weight = Quantity()  # <5>
+    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_v4c.py

@@ -0,0 +1,58 @@
+"""
+
+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: weight must be > 0
+
+No change was made::
+
+    >>> raisins.weight
+    10
+
+Negative or 0 price is not acceptable either::
+
+    >>> truffle = LineItem('White truffle', 100, 0)
+    Traceback (most recent call last):
+        ...
+    ValueError: price must be > 0
+
+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
+    'weight'
+
+"""
+
+# tag::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_v5.py

@@ -0,0 +1,72 @@
+"""
+
+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: weight must be > 0
+
+No change was made::
+
+    >>> raisins.weight
+    10
+
+Negative or 0 price is not acceptable either::
+
+    >>> truffle = LineItem('White truffle', 100, 0)
+    Traceback (most recent call last):
+        ...
+    ValueError: price must be > 0
+
+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
+    'weight'
+
+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: description cannot be blank
+    >>> void = LineItem('', 1, 1)
+    Traceback (most recent call last):
+        ...
+    ValueError: description cannot be blank
+
+
+"""
+
+# tag::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/model_v4c.py

@@ -0,0 +1,13 @@
+# BEGIN MODEL_V4
+class Quantity:
+
+    def __set_name__(self, owner, name):  # <1>
+        self.storage_name = name          # <2>
+
+    def __set__(self, instance, value):   # <3>
+        if value > 0:
+            instance.__dict__[self.storage_name] = value
+        else:
+            msg = f'{self.storage_name} must be > 0'
+            raise ValueError(msg)
+# END MODEL_V4

23-descriptor/bulkfood/model_v5.py

@@ -0,0 +1,36 @@
+# tag::MODEL_V5_VALIDATED_ABC[]
+import abc
+
+class Validated(abc.ABC):
+
+    def __set_name__(self, owner, name):
+        self.storage_name = name
+
+    def __set__(self, instance, value):
+        value = self.validate(self.storage_name, value)  # <1>
+        instance.__dict__[self.storage_name] = value  # <2>
+
+    @abc.abstractmethod
+    def validate(self, name, value):  # <3>
+        """return validated value or raise ValueError"""
+# end::MODEL_V5_VALIDATED_ABC[]
+
+# tag::MODEL_V5_VALIDATED_SUB[]
+class Quantity(Validated):
+    """a number greater than zero"""
+
+    def validate(self, name, value):  # <1>
+        if value <= 0:
+            raise ValueError(f'{name} must be > 0')
+        return value
+
+
+class NonBlank(Validated):
+    """a string with at least one non-space character"""
+
+    def validate(self, name, value):
+        value = value.strip()
+        if len(value) == 0:
+            raise ValueError(f'{name} cannot be blank')
+        return value  # <2>
+# end::MODEL_V5_VALIDATED_SUB[]