type_enforced.utils

  1import types, re, copy
  2from functools import update_wrapper
  3from typing import Union
  4
  5
  6class Partial:
  7    """
  8    A special class wrapper to allow for easy partial function wrappings and calls.
  9    """
 10
 11    __slots__ = (
 12        "__fn__",
 13        "__args__",
 14        "__kwargs__",
 15        "__fnArity__",
 16        "__arity__",
 17        "__fn_var_keys__",
 18        "__fn_arg_keys__",
 19        "__fn_arg_default_keys__",
 20        "__wrapped__",
 21        "__name__",
 22        "__qualname__",
 23        "__dict__",
 24    )
 25
 26    def __init__(
 27        self,
 28        __fn__,
 29        *__args__,
 30        **__kwargs__,
 31    ):
 32        update_wrapper(self, __fn__)
 33        self.__fn__ = __fn__
 34        self.__args__ = __args__
 35        self.__kwargs__ = __kwargs__
 36        self.__fnArity__ = self.__getFnArity__()
 37        self.__arity__ = self.__getArity__(__args__, __kwargs__)
 38        self.__get_fn_arg_default_keys__()
 39
 40    def __exception__(self, message):
 41        pre_message = (
 42            f"({self.__fn__.__module__}.{self.__fn__.__qualname__}_partial): "
 43        )
 44        raise Exception(pre_message + message)
 45
 46    def __call__(self, *args, **kwargs):
 47        new_args = self.__args__ + args
 48        new_kwargs = {**self.__kwargs__, **kwargs}
 49        # Create a comprehensive set of assigned variable names to determine arity
 50        assigned_vars = set(self.__fn_arg_default_keys__)
 51        assigned_vars.update(self.__fn_arg_keys__[: len(new_args)])
 52        assigned_vars.update(new_kwargs)
 53        arity = self.__fnArity__ - len(assigned_vars)
 54        if arity < 0:
 55            self.__exception__("Too many arguments were supplied")
 56        if arity == 0:
 57            return self.__fn__(*new_args, **new_kwargs)
 58        return Partial(
 59            self.__fn__,
 60            *new_args,
 61            **new_kwargs,
 62        )
 63
 64    def __get_fn_arg_default_keys__(self):
 65        """
 66        Get the default values of the passed function or method and store them in `self.__fn_defaults__`.
 67        """
 68        co = self.__fn__.__code__
 69        self.__fn_var_keys__ = co.co_varnames
 70        self.__fn_arg_keys__ = co.co_varnames[: co.co_argcount]
 71        if self.__fn__.__defaults__ is not None:
 72            self.__fn_arg_default_keys__ = list(
 73                self.__fn_arg_keys__[-len(self.__fn__.__defaults__) :]
 74            )
 75        else:
 76            self.__fn_arg_default_keys__ = []
 77        if self.__fn__.__kwdefaults__ is not None:
 78            self.__fn_arg_default_keys__.extend(self.__fn__.__kwdefaults__)
 79
 80    def __get__(self, instance, owner):
 81        def bind(*args, **kwargs):
 82            if instance is not None and self.__arity__ == self.__fnArity__:
 83                return self.__call__(instance, *args, **kwargs)
 84            else:
 85                return self.__call__(*args, **kwargs)
 86
 87        return bind
 88
 89    def __repr__(self):
 90        return f"<Partial {self.__fn__.__module__}.{self.__fn__.__qualname__} object at {hex(id(self))}>"
 91
 92    def __getArity__(self, args, kwargs):
 93        return self.__fnArity__ - (len(args) + len(kwargs))
 94
 95    def __getFnArity__(self):
 96        if not isinstance(self.__fn__, (types.MethodType, types.FunctionType)):
 97            self.__exception__(
 98                "A non function was passed as a function and does not have any arity. See the stack trace above for more information."
 99            )
100        extra_method_input_count = (
101            1 if isinstance(self.__fn__, types.MethodType) else 0
102        )
103        return self.__fn__.__code__.co_argcount - extra_method_input_count
104
105
106class GenericConstraint:
107    def __init__(self, constraints: dict):
108        """
109        Creates a generic constraint object that can be used to validate a value against a set of constraints.
110
111        Required Arguments:
112
113        - `constraints`:
114            - What: A dictionary of constraint names and their associated functions.
115            - Type: dict
116            - Note: All values in the dictionary must be functions that take a single argument and return a boolean.
117            - Note: The dictionary keys will be used to identify the failed constraints in the error messages.
118        """
119        assert all(
120            hasattr(v, "__call__") for v in constraints.values()
121        ), "All constraints must be functions."
122        self.__constraint_checks__ = constraints
123
124    def __validate__(self, varname, value):
125        for check_name, check_func in self.__constraint_checks__.items():
126            try:
127                if not check_func(value):
128                    return f"Constraint `{check_name}` not met with the provided value `{value}`"
129            except Exception as e:
130                return f"An exception was raised when checking the constraint `{check_name}` with the provided value `{value}`. Error: {e}"
131        return True
132
133    def __ror__(self, other):
134        """
135        Allows the use of | operator to combine GenericConstraints via a union.
136        """
137        return Union[other, self]
138
139
140class Constraint(GenericConstraint):
141    def __init__(
142        self,
143        pattern: str | None = None,
144        includes: list | tuple | set | None = None,
145        excludes: list | tuple | set | None = None,
146        gt: float | int | None = None,
147        lt: float | int | None = None,
148        ge: float | int | None = None,
149        le: float | int | None = None,
150        eq: float | int | None = None,
151        ne: float | int | None = None,
152    ):
153        """
154        Creates a constraint object that can be used to validate a value against a set of constraints.
155
156        Optional Arguments:
157
158        - `pattern`:
159            - What: A regex pattern that the value must match.
160            - Type: str or None
161            - Default: None
162        - `includes`:
163            - What: A list of values that the value must be in.
164            - Type: list, tuple, set or None
165            - Default: None
166        - `excludes`:
167            - What: A list of values that the value must not be in.
168            - Type: list, tuple, set or None
169            - Default: None
170        - `gt`:
171            - What: The value must be greater than this value.
172            - Type: float, int or None
173            - Default: None
174        - `lt`:
175            - What: The value must be less than this value.
176            - Type: float, int or None
177            - Default: None
178        - `ge`:
179            - What: The value must be greater than or equal to this value.
180            - Type: float, int or None
181            - Default: None
182        - `le`:
183            - What: The value must be less than or equal to this value.
184            - Type: float, int or None
185            - Default: None
186        - `eq`:
187            - What: The value must be equal to this value.
188            - Type: float, int or None
189            - Default: None
190        - `ne`:
191            - What: The value must not be equal to this value.
192            - Type: float, int or None
193            - Default: None
194        """
195        assert any(
196            v is not None
197            for v in [pattern, gt, lt, ge, le, eq, ne, includes, excludes]
198        ), "At least one constraint must be provided."
199        assert isinstance(
200            includes, (list, tuple, set, type(None))
201        ), "Includes must be a list, tuple, set or None."
202        assert isinstance(
203            excludes, (list, tuple, set, type(None))
204        ), "Excludes must be a list, tuple, set or None."
205        assert isinstance(
206            pattern, (str, type(None))
207        ), "Pattern must be a string or None."
208        assert isinstance(
209            gt, (float, int, type(None))
210        ), "Greater than constraint must be a float, int or None."
211        assert isinstance(
212            lt, (float, int, type(None))
213        ), "Less than constraint must be a float, int or None."
214        assert isinstance(
215            ge, (float, int, type(None))
216        ), "Greater or equal to constraint must be a float, int or None."
217        assert isinstance(
218            le, (float, int, type(None))
219        ), "Less than or equal to constraint must be a float, int or None."
220        assert isinstance(
221            eq, (float, int, type(None))
222        ), "Equal to constraint must be a float, int or None."
223        assert isinstance(
224            ne, (float, int, type(None))
225        ), "Not equal to constraint must be a float, int or None."
226        self.__constraint_checks__ = {}
227        if pattern is not None:
228            self.__constraint_checks__["be a string"] = lambda x: isinstance(
229                x, str
230            )
231            self.__constraint_checks__["Regex Pattern Match"] = lambda x: bool(
232                re.search(pattern, x)
233            )
234        if includes is not None:
235            self.__constraint_checks__[f"Includes"] = lambda x: x in includes
236        if excludes is not None:
237            self.__constraint_checks__["Excludes"] = lambda x: x not in excludes
238        if gt is not None:
239            self.__constraint_checks__[f"Greater Than ({gt})"] = (
240                lambda x: x > gt
241            )
242        if lt is not None:
243            self.__constraint_checks__[f"Less Than ({lt})"] = lambda x: x < lt
244        if ge is not None:
245            self.__constraint_checks__[f"Greater Than Or Equal To ({ge})"] = (
246                lambda x: x >= ge
247            )
248        if le is not None:
249            self.__constraint_checks__[f"Less Than Or Equal To ({le})"] = (
250                lambda x: x <= le
251            )
252        if eq is not None:
253            self.__constraint_checks__[f"Equal To ({eq})"] = lambda x: x == eq
254        if ne is not None:
255            self.__constraint_checks__[f"Not Equal To ({ne})"] = (
256                lambda x: x != ne
257            )
258
259
260iterable_types = frozenset({list, tuple, set, dict})
261
262
263def merge_type_dicts(target, source):
264    """Merge source type dict into target in-place.
265
266    Preserves multiple schema variants for collection types (list, tuple, dict, set)
267    when distinct collection schemas are united.
268    """
269    for key, value in source.items():
270        if key not in target:
271            target[key] = value
272        elif key == "__extra__":
273            if isinstance(target[key], dict) and isinstance(value, dict):
274                for ek, ev in value.items():
275                    if ek not in target[key]:
276                        target[key][ek] = ev
277                    elif isinstance(target[key][ek], list) and isinstance(
278                        ev, list
279                    ):
280                        target[key][ek] = list(
281                            dict.fromkeys(target[key][ek] + ev)
282                        )
283        elif target[key] == value:
284            continue
285        elif key in iterable_types:
286            if isinstance(target[key], list):
287                if isinstance(value, list):
288                    for v in value:
289                        if v not in target[key]:
290                            target[key].append(v)
291                else:
292                    if value not in target[key]:
293                        target[key].append(value)
294            else:
295                if isinstance(value, list):
296                    new_list = [target[key]]
297                    for v in value:
298                        if v not in new_list:
299                            new_list.append(v)
300                    target[key] = new_list
301                else:
302                    target[key] = [target[key], value]
303        elif isinstance(target[key], dict) and isinstance(value, dict):
304            merge_type_dicts(target[key], value)
305        else:
306            target[key] = value
307
308
309def DeepMerge(original: dict, update: dict):
310    """
311    Merge two dictionaries together, recursively merging any nested dictionaries and preserving collection variant schemas.
312
313    Required Arguments:
314
315    - `original`:
316        - What: The original dictionary to merge the update into.
317        - Type: dict
318    - `update`:
319        - What: The dictionary to merge into the original dictionary.
320        - Type: dict
321    """
322    original = copy.deepcopy(original)
323    merge_type_dicts(original, update)
324    return original
325
326
327def WithSubclasses(cls):
328    """
329    A utility class to preserve backwards compatibility
330    with the older versions of type_enforced.
331
332    By default subclasses of all classes are now enforced by type_enforced.
333
334    It is slated to be removed in the next major version.
335    """
336    # TODO: Remove this in the next major version of type_enforced
337    return cls
338
339
340def has_cpp():
341    try:
342        from type_enforced.cpp import create_validator  # noqa: F401
343
344        return True
345    except ImportError:
346        return False
347
348
349def cpp_check():
350    try:
351        from type_enforced.cpp import create_validator  # noqa: F401
352
353        print("Using C++ & Python implementation of type_enforced.")
354    except ImportError:
355        print("Using Pure Python implementation of type_enforced.")