Add the data validators complete practical example.

python · rhettinger · Oct 23, 2020 · Oct 22, 2020 · Oct 23, 2020 · Oct 23, 2020
commit 36247316f2279e372bbfe9035fb3ba468879af75
diff --git a/Doc/howto/descriptor.rst b/Doc/howto/descriptor.rst
@@ -213,7 +213,112 @@ The two *Person* instances contain only the private names::
 Complete Practical Example
 ^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-XXX: Add the validators example
+In this example, we create a practical and powerful tool for locating notoriously hard to find data corruption bugs.
+
+A validator is a descriptor for managed attribute access.  Prior to storing any data, it verifies that the new value meets various type and range restrictions.  If those restrictions aren't met, it raises an exception and prevents data corruption at its source.
+
+This :class:`Validator` class is both an :term:`abstract base class` and a managed attribute descriptor::
+
+    from abc import ABC, abstractmethod
+
+    class Validator(ABC):
+
+        def __set_name__(self, owner, name):
+            self.private_name = f'_{name}'
+
+        def __get__(self, obj, objtype=None):
+            return getattr(obj, self.private_name)
+
+        def __set__(self, obj, value):
+            self.validate(value)
+            setattr(obj, self.private_name, value)
+
+        @abstractmethod
+        def validate(self, value):
+            pass
+
+Custom validators need to subclass from :class:`Validator` and supply a :meth:`validate` method to test various restrictions as needed.
+
+Here are three practical data validation utilities:
+
+1) :class:`OneOf` verifies that a value is one of a restricted set of options.
+
+2) :class:`Number` verifies that a value is either an :class:`int` or :class:`float`.  Optionally, it verifies that a value is between a given minimum or maximum.
+
+3) :class:`String` verifies that a value is a :class:`str`.  Optionally, it validates a given minimum or maximum length.  Optionally, it can test for another predicate as well.
+
+::
+
+    class OneOf(Validator):
+
+        def __init__(self, *options):
+            self.options = set(options)
+
+        def validate(self, value):
+            if value not in self.options:
+                raise ValueError(f'Expected {value!r} to be one of {self.options!r}')
+
+    class Number(Validator):
+
+        def __init__(self, minvalue=None, maxvalue=None):
+            self.minvalue = minvalue
+            self.maxvalue = maxvalue
+
+        def validate(self, value):
+            if not isinstance(value, (int, float)):
+                raise TypeError(f'Expected {value!r} to be an int or float')
+            if self.minvalue is not None and value < self.minvalue:
+                raise ValueError(
+                    f'Expected {value!r} to be at least {self.minvalue!r}'
+                )
+            if self.maxvalue is not None and value > self.maxvalue:
+                raise ValueError
+                    (f'Expected {value!r} to be no more than {self.maxvalue!r}'
+                )
+
+    class String(Validator):
+
+        def __init__(self, minsize=None, maxsize=None, predicate=None):
+            self.minsize = minsize
+            self.maxsize = maxsize
+            self.predicate = predicate
+
+        def validate(self, value):
+            if not isinstance(value, str):
+                raise TypeError(f'Expected {value!r} to be an str')
+            if self.minsize is not None and len(value) < self.minsize:
+                raise ValueError(
+                    f'Expected {value!r} to be no smaller than {self.minsize!r}'
+                )
+            if self.maxsize is not None and len(value) > self.maxsize:
+                raise ValueError(
+                    f'Expected {value!r} to be no bigger than {self.maxsize!r}'
+                )
+            if self.predicate is not None and not self.predicate(value):
+                raise ValueError(
+                    f'Expected {self.predicate} to be true for {value!r}'
+                )
+
+Here's how the data validators can be used in a real class::
+
+    class Component:
+
+        name = String(minsize=3, maxsize=10, predicate=str.upper)
+        kind = OneOf('plastic', 'metal')
+        quantity = Number(minvalue=0)
+
+        def __init__(self, name, kind, quantity):
+            self.name = name
+            self.kind = kind
+            self.quantity = quantity
+
+The descriptors invalid instances from being created::
+
+    Component('WIDGET', 'metal', 5)     # Allowed.
+    Component('Widget', 'metal', 5)     # Blocked: 'Widget' is not all uppercase
+    Component('WIDGET', 'metle', 5)     # Blocked: 'metle' is misspelled
+    Component('WIDGET', 'metal', -5)    # Blocked: -5 is negative
+    Component('WIDGET', 'metal', 'V')   # Blocked: 'V' isn't a number
 
 
 Technical Tutorial