updade from Atlas repo

25-class-metaprog/bulkfood/README.md

@@ -0,0 +1,34 @@
+# Legacy Class Descriptor and Metaclass Examples
+
+Examples from _Fluent Python, First Edition_—Chapter 21, _Class Metaprogramming_,
+that are mentioned in _Fluent Python, Second Edition_—Chapter 25, _Class Metaprogramming_.
+
+These examples were developed with Python 3.4.
+They run correctly in Python 3.9, but now it is easier to fullfill the same requirements
+without resorting to class decorators or metaclasses.
+
+I have preserved them here as examples of class metaprogramming techniques
+that you may find in legacy code, and that can be refactored to simpler code
+using a base class with `__init_subclass__` and decorators implementing `__set_name__`.
+
+## Suggested Exercise
+
+If you'd like to practice the concepts presented in chapters 24 and 25 of
+_Fluent Python, Second Edition_,
+you may to refactor the most advanced example, `model_v8.py` with these changes:
+
+1. Simplify the `AutoStorage` descriptor by implementing `__set_name__`.
+This will allow you to simplify the `EntityMeta` metaclass as well.
+
+2. Rewrite the `Entity` class to use `__init_subclass__` instead of the `EntityMeta` metaclass—which you can then delete.
+
+Nothing should change in the `bulkfood_v8.py` code, and its doctests should still pass.
+
+To run the doctests while refactoring, it's often convenient to pass the `-f` option,
+to exit the test runner on the first failing test.
+
+```
+$ python3 -m doctest -f bulkfood_v8.py
+```
+
+Enjoy!

25-class-metaprog/bulkfood/bulkfood_v6.py

@@ -0,0 +1,84 @@
+"""
+
+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::
+
+# tag::LINEITEM_V6_DEMO[]
+    >>> raisins = LineItem('Golden raisins', 10, 6.95)
+    >>> dir(raisins)[:3]
+    ['_NonBlank#description', '_Quantity#price', '_Quantity#weight']
+    >>> LineItem.description.storage_name
+    '_NonBlank#description'
+    >>> raisins.description
+    'Golden raisins'
+    >>> getattr(raisins, '_NonBlank#description')
+    'Golden raisins'
+
+# end::LINEITEM_V6_DEMO[]
+
+If the descriptor is accessed in the class, the descriptor object is
+returned:
+
+    >>> LineItem.weight  # doctest: +ELLIPSIS
+    <model_v6.Quantity object at 0x...>
+    >>> LineItem.weight.storage_name
+    '_Quantity#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: value cannot be empty or blank
+    >>> void = LineItem('', 1, 1)
+    Traceback (most recent call last):
+        ...
+    ValueError: value cannot be empty or blank
+
+
+"""
+
+# tag::LINEITEM_V6[]
+import model_v6 as model
+
+@model.entity  # <1>
+class LineItem:
+    description = model.NonBlank()
+    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_V6[]

25-class-metaprog/bulkfood/bulkfood_v7.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)[:3]
+    ['_NonBlank#description', '_Quantity#price', '_Quantity#weight']
+    >>> LineItem.description.storage_name
+    '_NonBlank#description'
+    >>> raisins.description
+    'Golden raisins'
+    >>> getattr(raisins, '_NonBlank#description')
+    'Golden raisins'
+
+If the descriptor is accessed in the class, the descriptor object is
+returned:
+
+    >>> LineItem.weight  # doctest: +ELLIPSIS
+    <model_v7.Quantity object at 0x...>
+    >>> LineItem.weight.storage_name
+    '_Quantity#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: value cannot be empty or blank
+    >>> void = LineItem('', 1, 1)
+    Traceback (most recent call last):
+        ...
+    ValueError: value cannot be empty or blank
+
+"""
+
+# tag::LINEITEM_V7[]
+import model_v7 as model
+
+class LineItem(model.Entity):  # <1>
+    description = model.NonBlank()
+    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_V7[]

25-class-metaprog/bulkfood/bulkfood_v8.py

@@ -0,0 +1,86 @@
+"""
+
+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
+
+    >>> raisins = LineItem('Golden raisins', 10, 6.95)
+    >>> dir(raisins)[:3]
+    ['_NonBlank#description', '_Quantity#price', '_Quantity#weight']
+    >>> LineItem.description.storage_name
+    '_NonBlank#description'
+    >>> raisins.description
+    'Golden raisins'
+    >>> getattr(raisins, '_NonBlank#description')
+    'Golden raisins'
+
+If the descriptor is accessed in the class, the descriptor object is
+returned:
+
+    >>> LineItem.weight  # doctest: +ELLIPSIS
+    <model_v8.Quantity object at 0x...>
+    >>> LineItem.weight.storage_name
+    '_Quantity#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: value cannot be empty or blank
+    >>> void = LineItem('', 1, 1)
+    Traceback (most recent call last):
+        ...
+    ValueError: value cannot be empty or blank
+
+
+Fields can be retrieved in the order they were declared:
+
+# tag::LINEITEM_V8_DEMO[]
+    >>> for name in LineItem.field_names():
+    ...     print(name)
+    ...
+    description
+    weight
+    price
+
+# end::LINEITEM_V8_DEMO[]
+
+"""
+
+import model_v8 as model
+
+class LineItem(model.Entity):
+    description = model.NonBlank()
+    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

25-class-metaprog/bulkfood/model_v6.py

@@ -0,0 +1,60 @@
+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"""
+
+
+class Quantity(Validated):
+    """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
+
+# tag::MODEL_V6[]
+def entity(cls):  # <1>
+    for key, attr in cls.__dict__.items():  # <2>
+        if isinstance(attr, Validated):  # <3>
+            type_name = type(attr).__name__
+            attr.storage_name = '_{}#{}'.format(type_name, key)  # <4>
+    return cls  # <5>
+# end::MODEL_V6[]

25-class-metaprog/bulkfood/model_v7.py

@@ -0,0 +1,66 @@
+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"""
+
+
+class Quantity(Validated):
+    """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
+
+# tag::MODEL_V7[]
+class EntityMeta(type):
+    """Metaclass for business entities with validated fields"""
+
+    def __init__(cls, name, bases, attr_dict):
+        super().__init__(name, bases, attr_dict)  # <1>
+        for key, attr in attr_dict.items():  # <2>
+            if isinstance(attr, Validated):
+                type_name = type(attr).__name__
+                attr.storage_name = '_{}#{}'.format(type_name, key)
+
+class Entity(metaclass=EntityMeta):  # <3>
+    """Business entity with validated fields"""
+# end::MODEL_V7[]

25-class-metaprog/bulkfood/model_v8.py

@@ -0,0 +1,80 @@
+import abc
+import collections
+
+
+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"""
+
+
+class Quantity(Validated):
+    """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
+
+# tag::MODEL_V8[]
+class EntityMeta(type):
+    """Metaclass for business entities with validated fields"""
+
+    @classmethod
+    def __prepare__(cls, name, bases):
+        return collections.OrderedDict()  # <1>
+
+    def __init__(cls, name, bases, attr_dict):
+        super().__init__(name, bases, attr_dict)
+        cls._field_names = []  # <2>
+        for key, attr in attr_dict.items():  # <3>
+            if isinstance(attr, Validated):
+                type_name = type(attr).__name__
+                attr.storage_name = '_{}#{}'.format(type_name, key)
+                cls._field_names.append(key)  # <4>
+
+
+class Entity(metaclass=EntityMeta):
+    """Business entity with validated fields"""
+
+    @classmethod
+    def field_names(cls):  # <5>
+        for name in cls._field_names:
+            yield name
+
+# end::MODEL_V8[]