python descriptor protocol - simple examples and framework

descriptors.py

# miscellaneous descriptor-protocol classes, implemented mostly as an exercise
#

# The MIT License
#
# Copyright (c) 2022 Neil Webber
#
# Permission is hereby granted, free of charge, to any person obtaining a copy
# of this software and associated documentation files (the "Software"), to deal
# in the Software without restriction, including without limitation the rights
# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
# copies of the Software, and to permit persons to whom the Software is
# furnished to do so, subject to the following conditions:
#
# The above copyright notice and this permission notice shall be included in
# all copies or substantial portions of the Software.
#
# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
# THE SOFTWARE.

class CheckValid(property):
    """Descriptor for values checked by a supplied function."""

    def __init__(self, *, validator=lambda v: True, doc=None):
        """CheckValid(*, validator=lambda v: True, doc=None)

        Thin layer on property(), implementing an attribute with legal
        values determined by the supplied validator function.

        If doc is supplied, it is passed along to property().

        Example:
           def is_even(v):
              return v % 2 == 0

           attr = CheckValid(validator=is_even)

           will limit the values of attr to even numbers.

        For legal values the validator should return True.
        For illegal values, it can either return False or raise an exception.
        """
        self.validator = validator

        super().__init__(self._get, self._set, self._del, doc)

    def __set_name__(self, owner, name):
        # save the managed-attribute name for use in error messages.
        # construct a unique private name from that name.
        self.pubname = name
        self._name = '_' + str(id(self)) + name

    def _get(self, obj):
        try:
            return getattr(obj, self._name)
        except AttributeError:
            raise AttributeError(
                f"'{obj.__class__.__name__}' object " +
                f"has no attribute '{self.pubname}'") from None

    def _set(self, obj, value):
        if not self.validator(value):
            raise ValueError(f"cannot set '{self.pubname}' to {value!r}")
        else:
            setattr(obj, self._name, value)

    def _del(self, obj):
        del obj.__dict__[self._name]


class Within(CheckValid):
    """Descriptor for values within minval to maxval."""

    def __init__(self, *, minval=None, maxval=None, doc=None):
        """Within(minval=None, maxval=None)

        Descriptor implementing range-restricted attribute value.

        Examples:
           To limit an attribute to 0 .. 9
                 attr = Within(minval=0, maxval=9)

           To limit an attribute to be >= 0
                 attr = Within(minval=0)
        """

        if minval is None and maxval is None:
            self.valid = lambda v: True
        elif minval is None:
            self.valid = lambda v: v <= maxval
            self.xfmt = f"{{v}} is not <= {maxval}"
        elif maxval is None:
            self.valid = lambda v: v >= minval
            self.xfmt = f"{{v}} is not >= {minval}"
        else:
            self.valid = lambda v: v >= minval and v <= maxval
            self.xfmt = f"{{v}} not within {minval} to {maxval}"

        super().__init__(validator=self._validator, doc=doc)

    def _validator(self, v):
        try:
            if not self.valid(v):
                raise ValueError(self.xfmt.format(v=v))
        except TypeError:        # catches non-numerics that fail < or >
            m = f"{v!r} incompatible with limits for '{self.pubname}'"
            raise TypeError(m) from None
        else:
            return True

    def __set_name__(self, owner, name):
        super().__set_name__(owner, name)
        self.xfmt = name + ": " + self.xfmt   # improve the ValueError msg


class WithinPlus(Within):
    """Like Within but also accepts specific other values."""

    def __init__(self, *, minval=None, maxval=None, allow=tuple(), doc=None):
        super().__init__(minval=minval, maxval=maxval, doc=doc)

        # FOR CONVENIENCE, and not at all clear this was a good idea,
        # two special cases for 'allow' can be passed as non-tuples:
        #       allow=None            becomes allow=(None,)
        #       allow='any string'    becomes allow=('any string',)
        #
        # Otherwise allow must be an iterable of allowed values.
        if allow is None or isinstance(allow, str):
            self.allow = (allow,)
        else:
            self.allow = tuple(allow)

    def _validator(self, v):
        return v in self.allow or super()._validator(v)


class Choose(CheckValid):
    """Descriptor for values limited to specific choices."""

    def __init__(self, *choices, doc=None):
        """Choose(choice0, choice1, ...)

        Descriptor implementing an attribute limited to the
        given choice values

        Example:
           attr = Choose(42, None, 'bozo')

           will limit the values of attr to 42, None, or 'bozo'
        """

        # If the list of choices gets long, doing this with a frozen
        # set is SUBSTANTIALLY faster (verified w/timeit) than using
        # the choices as passed in. Presumably because hashing is constant
        # time vs lookup in linear time.
        self.choices = frozenset(choices)
        super().__init__(validator=lambda v: v in self.choices, doc=doc)


class InstanceOf(CheckValid):
    """Descriptor for values that must be a specific type (or types)."""

    def __init__(self, *types, doc=None):
        """InstanceOf(type0, type11, ...)

        Descriptor implementing an attribute limited to the given types

        Example:
           attr = InstanceOf(int, float)

           will limit the values of attr to ints and floats
        """

        super().__init__(validator=lambda v: isinstance(v, types), doc=doc)


if __name__ == "__main__":
    import unittest
    import math

    Z9INIT = 0
    A10INIT = 10
    MISC1INIT = 1
    MISC2INIT = 2

    class Bozo:
        z9orNone = WithinPlus(minval=0, maxval=9, allow=None)
        z9orBust = WithinPlus(minval=0, maxval=9, allow='Bust')
        z9orNoneT = WithinPlus(minval=0, maxval=9, allow=(None,))
        z9orBustT = WithinPlus(minval=0, maxval=9, allow=('Bust',))
        atleast10 = Within(minval=10)
        misc1 = Choose(1, 2, 'grape', doc='THIS IS THE GRAPE')
        misc2 = Choose(2, 2, 2, 2, doc='THIS CAN ONLY BE SET TO 2')
        inst = InstanceOf(float)

        def __init__(self):
            self.z9orNone = Z9INIT
            self.atleast10 = A10INIT
            self.misc1 = MISC1INIT
            self.misc2 = MISC2INIT

    class TestMethods(unittest.TestCase):
        def testINIT(self):
            b = Bozo()
            self.assertEqual(b.z9orNone, Z9INIT)
            self.assertEqual(b.atleast10, A10INIT)
            self.assertEqual(b.misc1, MISC1INIT)
            self.assertEqual(b.misc2, MISC2INIT)

        def testChoose(self):
            b = Bozo()
            for v in (1, 2, 'grape'):
                b.misc1 = v
                b.misc2 = MISC2INIT     # making sure they are distinct!
                self.assertEqual(b.misc1, v)
            with self.assertRaises(ValueError):
                b.misc1 = "we all live in a yellow submarine"
            b.misc2 = MISC2INIT
            self.assertEqual(b.misc2, MISC2INIT)
            with self.assertRaises(ValueError):
                b.misc2 = "we all live in a yellow submarine"

        def testWithin(self):
            b = Bozo()
            b.atleast10 = 99
            self.assertEqual(b.atleast10, 99)
            with self.assertRaises(ValueError):
                b.atleast10 = 9
            with self.assertRaises(TypeError):
                b.atleast10 = None

        def testWithinPlus(self):
            b = Bozo()

            for attr in ('z9orNone', 'z9orNoneT'):
                for i in range(0, 10):
                    setattr(b, attr, i)
                    self.assertEqual(getattr(b, attr), i)
                setattr(b, attr, None)
                self.assertEqual(getattr(b, attr), None)
                with self.assertRaises(ValueError):
                    setattr(b, attr, 10)
                with self.assertRaises(ValueError):
                    setattr(b, attr, -1)
                with self.assertRaises(TypeError):
                    setattr(b, attr, tuple())

            for attr in ('z9orBust', 'z9orBustT'):
                setattr(b, attr, 'Bust')
                self.assertEqual(getattr(b, attr), 'Bust')
                with self.assertRaises(TypeError):
                    setattr(b, attr, 'banana')

            class Foo:
                b = WithinPlus(minval=0, allow=('x', 'y', 'z', None))
            f = Foo()
            f.b = 0
            f.b = 'x'
            f.b = 'y'
            f.b = 'z'
            f.b = None
            with self.assertRaises(TypeError):
                f.b = 'w'

        def testInst(self):
            b = Bozo()
            b.inst = 1.0
            b.inst = math.nan
            for bad in (0, "foo", None, tuple()):
                with self.assertRaises(ValueError):
                    b.inst = bad

        def testDelete(self):
            b = Bozo()
            b.misc1 = 1
            del b.misc1
            with self.assertRaises(AttributeError):
                x = b.misc1
            self.assertEqual(b.misc2, MISC2INIT)

    unittest.main()

property() is simple enough to use, but you still end up writing boilerplate get/set functions and you may end up writing multiple copies of similar functions if you have multiple attributes needing similar validations. This is a thin layer on top of property. I wrote it as a demonstration/education project for myself. If you have multiple attributes that need validation rules applied to them this might be useful.