batutils 2.0.0__py3-none-any.whl

batutils/tpu/insp/_insp_old.py

@@ -0,0 +1,347 @@
+__all__ = [
+    'is_methfunc',
+    'is_callable',
+    'get_argspec',
+    'fits_callable_profile',
+    'get_any_name',
+    'get_first_attr',
+    'resolve_attr',
+    'resolve_first',
+]
+
+from batutils.tpu.structs import empty
+import inspect
+from typing import *
+
+_NOT_SUPPLIED = object()
+
+
+def is_methfunc(function_or_method):
+    """Checks if the given parameter is a function/method or not.
+
+    This simply joins python's inspect.isfunction and inspect.ismethod in one
+    call.
+
+    A function is:
+        - Anything declared via def on the top level of a module (or inside
+          another function or method)
+        - Anything created with lambda
+        - Any method defined in a class with the @staticmethod decorator
+    A method is:
+        - Anything declared via def inside a class definition (except those
+          that have the @staticmethod decorator)
+
+    :param function_or_method: The thing to check
+    :type function_or_method: function or method or any
+    :return: True if the given parameter is a function or a method, false if not
+    :rtype: bool
+    """
+    return inspect.isfunction(function_or_method) or inspect.ismethod(function_or_method)
+
+
+def is_callable(something):
+    """Checks if the given parameter is callable or not.
+
+    Callable means a function, method or object of a class that implements the
+    __call__ method and can therefor be called like a function.
+
+    See is_methfunc() for more details.
+
+    :param something: The thing to check
+    :type something: function or method or object or any
+    :return: True if the given parameter is callable, false if not
+    :rtype: bool
+    """
+    if is_methfunc(something):
+        return True
+    else:
+        call_func = getattr(something, '__call__', None)
+        if call_func:
+            return is_methfunc(call_func)
+    return False
+
+
+def get_argspec(somecallable):
+    """Gets the argument specifications of a callable.
+
+    This simply extends the inspect.getargspec function to also work for
+    objects of classes that implement the __call__ method.
+
+    Returns None if the given parameter isn't callable.
+
+    :param somecallable: The thing to fetch the argument spec for
+    :type somecallable: function or method or object or any
+    :return: The argspecs or None if the given parameter wasn't callable
+    :rtype: inspect.ArgSpec or collections.namedtuple or None
+    """
+    if is_methfunc(somecallable):
+        return inspect.getfullargspec(somecallable)
+    else:
+        call_func = getattr(somecallable, '__call__', None)
+        if call_func:
+            if is_methfunc(call_func):
+                return inspect.getfullargspec(call_func)
+    return None
+
+
+def fits_callable_profile(somecallable, required_arg_count=None,
+                          total_arg_count=None, default_count=None,
+                          has_varargs=None, has_kwargs=None, arg_names=None,
+                          raise_error=False):
+    """Checks if a callable (function, method or object with __call__) fits
+    the given argument profile.
+
+    Returns False if the given parameter to check is not callable.
+
+    All check parameters default to None which skips that particular check.
+
+    Required arguments means total number of arguments minus the number of
+    arguments with default values.
+
+    If the arg_names parameter is a list (NOT a tuple), this will only check
+    if the argument names there in are present regardless of order.
+
+    If the arg_names parameter is a tuple (NOT a list), this will check if the
+    order pf the argument names there in are present and in the same order
+    although you can use '*' in the tuple to skip the check for the argument
+    in that place (e.g. if you don't care what the "self" parameter in a bound
+    method is called but you need a certain argument set to be present in order
+    after that). The arg_names tuple can be shorter than the number of
+    arguments in the callable though without that failing (use the argument
+    count checks if that is needed).
+
+    :param somecallable: The thing to check
+    :type somecallable: function or method or object or any
+    :param required_arg_count: The number of required arguments (if given),
+                               either the exact number or a 2-tuple with
+                               the minimum and maximum allowed number.
+    :type required_arg_count: int or (int, int) or None
+    :param total_arg_count: The total number of arguments (if given), either
+                            the exact number or a 2-tuple with the minimum
+                            and maximum allowed number.
+    :type total_arg_count: int or (int, int) or None
+    :param default_count: The number of arguments with default values (if
+                          given), either the exact number or a 2-tuple with
+                          the minimum and maximum allowed number.
+    :type default_count: int or (int, int) or None
+    :param has_varargs: Should the callable accept a variable number of
+                        arguments (*args)? If this is a string, then
+                       the args argument must be called that to pass.
+    :type has_varargs: bool or str or None
+    :param has_kwargs: Should the callable accept a variable number of
+                       named arguments (**kwargs)? If this is a string, then
+                       the kwargs argument must be called that to pass.
+    :type has_kwargs: bool or str or None
+    :param arg_names: A list of argument names the callable should have or a
+                      tuple of argument names the callable should have in that
+                      exact order (using "*" to skip individual name checks).
+    :type arg_names: list[str] or tuple[str] or None
+    :param raise_error: Should an ValueError be raised if a check fails
+                        (with the details)?
+    :type raise_error: bool
+    :return: True if the given callable fits all the given profile checks,
+             False if not.
+    :rtype: bool
+    """
+    # TODO(thordurm@ccpgames.com) 2024-03-20: This could probably use a "modern"
+    #  overhaul and to include type annotations and such!... I think this was
+    #  written for Python 2.7 :D
+    specs = get_argspec(somecallable)
+    if not specs:
+        if raise_error:
+            raise ValueError('Not a callable!')
+        return False
+    def_count = 0
+    if specs.defaults:
+        def_count = len(specs.defaults)
+    arg_count = 0
+    if specs.args:
+        arg_count = len(specs.args)
+    req_args = arg_count - def_count
+
+    if required_arg_count is not None:
+        if isinstance(required_arg_count, (list, tuple)):
+            mi = required_arg_count[0]
+            ma = required_arg_count[1]
+        else:
+            mi = required_arg_count
+            ma = required_arg_count
+        if not mi <= req_args <= ma:
+            if raise_error:
+                raise ValueError('Required arguments check fail: min=%s >= count=%s >= max=%s' % (mi, req_args, ma))
+            return False  # Required argument count fail! :(
+
+    if total_arg_count is not None:
+        if isinstance(total_arg_count, (list, tuple)):
+            mi = total_arg_count[0]
+            ma = total_arg_count[1]
+        else:
+            mi = total_arg_count
+            ma = total_arg_count
+        if not mi <= arg_count <= ma:
+            if raise_error:
+                raise ValueError('Arguments count check fail: min=%s >= count=%s >= max=%s' % (mi, arg_count, ma))
+            return False  # Total argument count fail! :(
+
+    if default_count is not None:
+        if isinstance(default_count, (list, tuple)):
+            mi = default_count[0]
+            ma = default_count[1]
+        else:
+            mi = default_count
+            ma = default_count
+        if not mi <= def_count <= ma:
+            if raise_error:
+                raise ValueError('Default argument check fail: min=%s >= count=%s >= max=%s' % (mi, def_count, ma))
+            return False  # Default argument count fail! :(
+
+    if has_varargs is not None:
+        if isinstance(has_varargs, str):
+            if has_varargs != specs.varargs:
+                if raise_error:
+                    raise ValueError('Variable arguments name fail: is=%s, should be=%s' % (specs.varargs, has_varargs))
+                return False  # Has variable arguments fail! :(
+        if bool(has_varargs) != bool(specs.varargs):
+            if raise_error:
+                raise ValueError('Variable arguments fail: is=%s, should be=%s' % (bool(specs.varargs), bool(has_varargs)))
+            return False  # Has variable arguments fail! :(
+
+    if has_kwargs is not None:
+        kwarg_name = specs.varkw
+        if isinstance(has_kwargs, str):
+            # if has_kwargs != specs.keywords:
+            if has_kwargs != kwarg_name:
+                if raise_error:
+                    raise ValueError('Keyword arguments name fail: is=%s, should be=%s' % (kwarg_name, has_kwargs))
+                return False  # Has variable keyword arguments fail! :(
+        # if bool(has_kwargs) != bool(specs.keywords):
+        if bool(has_kwargs) != bool(kwarg_name):
+            if raise_error:
+                raise ValueError('Keyword arguments fail: is=%s, should be=%s' % (bool(kwarg_name), bool(has_kwargs)))
+            return False  # Has variable keyword arguments fail! :(
+
+    if arg_names:
+        if not specs.args:
+            if raise_error:
+                raise ValueError('Named arguments fail: No named arguments found')
+            return False  # Has argument name fail! :(
+        if isinstance(arg_names, list):  # Order doesn't matter!
+            for arg_name in arg_names:
+                if arg_name not in specs.args:
+                    if raise_error:
+                        raise ValueError('Named arguments fail: Argument "%s" not found' % arg_name)
+                    return False  # Missing required argument! :(
+        elif isinstance(arg_names, tuple):
+            for i, arg_name in enumerate(arg_names):
+                if specs.args[i] != arg_name and arg_name != '*':
+                    if raise_error:
+                        raise ValueError('Named arguments fail: Argument "%s" not found in correct order' % arg_name)
+                    return False  # Missing required argument in order! :(
+        else:
+            if raise_error:
+                raise ValueError('Named arguments fail: arg_names must be a list or tuple')
+            return False
+
+    return True  # Looks good! :D
+
+
+def get_any_name(anything: Any) -> str:
+    if anything is None:
+        return 'None'
+
+    if anything is empty.Empty:
+        return f'{get_any_name(empty)}.Empty'
+
+    if inspect.ismodule(anything):
+        return getattr(anything, '__name__', f'?m:{anything!r}?')
+
+    if isinstance(anything, property):
+        anything = anything.fget
+
+    if inspect.isfunction(anything) or inspect.ismethod(anything):
+        module = getattr(anything, '__module__', None)
+        if module and module != 'builtins':
+            return f"{module}.{getattr(anything, '__qualname__', getattr(anything, '__name__', '?f1:noname?'))}"
+        else:
+            return f"{getattr(anything, '__qualname__', getattr(anything, '__name__', '?f1:noname?'))}"
+
+    cls = None
+    module = None
+    if isinstance(anything, Type):  # noqa
+        # Got a class/type/metaclass etc.
+        cls = anything
+
+    else:
+        cls = getattr(anything, '__class__', None)
+
+    if not cls:
+        return f'?{anything!r}?'  # Worth a shot!
+
+    name = getattr(cls, '__name__', None)
+    if not name:
+        name = f'??{cls!r}??'
+
+    module = getattr(cls, '__module__', None)
+    if module == 'builtins':
+        module = ''
+
+    if module is None:
+        module = '?nomodule?'
+
+    if module:
+        return f'{module}.{name}'
+
+    else:
+        return f'{name}'
+
+
+def get_first_attr(obj: Any, list_of_attributes: Union[str, List[str]], default: Any = None,
+                   skip_nones: bool = False) -> Any:
+    """Gets the first attribute of an object found from the given list of
+    attribute names.
+
+    This is similar to looping through a list using `getattr` although this will
+    also work on dicts and dict like mapping objects.
+    """
+    from batutils.tpu.iters import any_getter
+    for attr_name in list_of_attributes:
+        attr = any_getter(obj, attr_name, _NOT_SUPPLIED)
+        if attr != _NOT_SUPPLIED:
+            if skip_nones and attr is None:
+                continue
+            else:
+                return attr
+
+    return default
+
+
+def resolve_attr(attr: Union[Callable, property, Any]) -> Any:
+    """Resolves an attribute that may be a property or something callable to
+    it's post-call value and returns.
+
+    If the attr given is not a property or a callable entity, it's assumed to
+    be a proper value to begin with and is returned unchanged.
+    """
+    if isinstance(attr, property):
+        attr = attr.fget
+
+    if callable(attr):
+        return attr()
+
+    return attr
+
+
+def resolve_first(obj: Any, list_of_attributes: Union[str, List[str]], default: Any = None,
+                  skip_nones: bool = False) -> Any:
+    """Resolves the first attribute of an object found from the given list of
+    attribute names that may be a property or something callable to it's
+    post-call value and returns.
+
+    Basically just a shortcut for using `get_first_attr` and `resolve_attr` at
+    once.
+    """
+    attr = get_first_attr(obj, list_of_attributes, _NOT_SUPPLIED, skip_nones=skip_nones)
+    if attr == _NOT_SUPPLIED:
+        return default
+    else:
+        return resolve_attr(attr)

batutils/tpu/insp/_typecheck.py

@@ -0,0 +1,89 @@
+__all__ = [
+    'check_type',
+]
+from typing import *
+import typing
+import sys
+import logging
+log = logging.getLogger(__name__)
+
+_POST_39 = sys.version_info >= (3, 9)
+
+
+def check_type(val: Any, type_or_annotation: Any) -> bool:
+    def _is_special(toa: Any) -> bool:
+        if _POST_39:
+            if isinstance(toa, typing._SpecialGenericAlias):  # noqa
+                return True
+        else:
+            return toa._special  # noqa
+
+    if val is None and type_or_annotation is None:
+        return True
+
+    m = getattr(type_or_annotation, '__module__', None)
+    if m == 'typing':
+        if type_or_annotation == Any:
+            return True
+        if isinstance(type_or_annotation, typing._GenericAlias):  # noqa
+            if _is_special(type_or_annotation):  # noqa Not subscripted
+                return isinstance(val, type_or_annotation.__origin__)
+
+            else:
+                if type_or_annotation.__origin__ == Union:
+                    if not type_or_annotation.__args__:
+                        return True
+                    if Any in type_or_annotation.__args__:
+                        return True
+                    return isinstance(val, type_or_annotation.__args__)
+
+                elif type_or_annotation.__origin__ in (list, set):  # Check list and set
+                    if not isinstance(val, type_or_annotation.__origin__):
+                        return False
+                    if not type_or_annotation.__args__ or Any in type_or_annotation.__args__:
+                        return True
+                    for sub_val in val:
+                        if not check_type(sub_val, Union[type_or_annotation.__args__]):
+                            return False
+                    return True  # Should be good now! :)
+
+                elif type_or_annotation.__origin__ == tuple:  # Check tuple!
+                    if not isinstance(val, tuple):
+                        return False
+                    if not type_or_annotation.__args__:
+                        return True
+
+                    if type_or_annotation.__args__[-1] is ... and len(type_or_annotation.__args__) == 2:
+                        for sub_val in val:
+                            if not check_type(sub_val, Union[type_or_annotation.__args__[0]]):
+                                return False
+                        return True  # Should be good now! :)
+
+                    if len(type_or_annotation.__args__) != len(val):
+                        return False
+
+                    for i, sub_val in enumerate(val):
+                        if not check_type(sub_val, Union[type_or_annotation.__args__[i]]):
+                            return False
+
+                    return True  # Should be good now! :)
+
+                elif issubclass(type_or_annotation.__origin__, Mapping):
+                    if not isinstance(val, type_or_annotation.__origin__):
+                        return False
+                    if not type_or_annotation.__args__ or type_or_annotation.__args__ == (Any, Any):
+                        return True
+
+                    for k, v in val.items():
+                        if not (check_type(k, Union[type_or_annotation.__args__[0]]) and check_type(v, Union[type_or_annotation.__args__[1]])):
+                            return False
+                    return True
+                else:
+                    log.warning('I do not know how to check type %r of typing module:(', type_or_annotation)
+
+        if isinstance(type_or_annotation, TypeVar):
+            # TODO(thordurm@ccpgames.com>): Not really tested and supported yet officially...
+            # TODO(thordurm@ccpgames.com>): Main issue is nested types (if they don't flatten)
+            return check_type(val, Union[type_or_annotation.__constraints__])
+
+    return isinstance(val, type_or_annotation)

batutils/tpu/iters/__init__.py

@@ -0,0 +1,4 @@
+from ._lists import *
+from ._dicts import *
+from ._attrs import *
+from ._group import *

batutils/tpu/iters/_attrs.py

@@ -0,0 +1,84 @@
+__all__ = [
+    'any_getter',
+    'any_setter',
+    'nested_get',
+    'nested_set',
+]
+from batutils.tpu.structs import *
+
+
+def any_getter(obj: Any, key: Union[str, int], default: Any = None, eval_call: bool = False) -> Optional[Any]:
+    if isinstance(key, int):
+        try:
+            val = obj[key]
+        except (IndexError, KeyError):
+            return default
+    else:
+        if isinstance(obj, Mapping):
+            val = obj.get(key, default)
+        else:
+            val = getattr(obj, key, default)
+    if eval_call:
+        if val and isinstance(val, Callable):
+            val = val()
+    return val
+
+
+def any_setter(obj: Any, key: Union[str, int], value: Any):
+    if isinstance(obj, MutableSequence):
+        obj[key] = value
+
+    elif isinstance(obj, MutableMapping):
+        obj[key] = value
+
+    elif isinstance(key, int):
+        obj[key] = value
+
+    else:
+        setattr(obj, key, value)
+
+
+def nested_get(obj: Union[Mapping, Sequence],
+               key_list: Sequence[Union[str, int]],
+               default: Any = None) -> Any:
+    """Given a nested Mapping, Sequence or any indexable/subscriptable object of
+    other such, and a Sequence of keys and/or indexes, fetches the object at the
+    end of the Sequence of keys.
+
+    Returns the given default value if any key/index isn't found (defaults to
+    None if nothing is given).
+
+    Example:
+    >>> nested_get({'a': {7: {'c': ['apple', 'banana', 'cantaloupe']}, 5: 'other'}}, ('a', 7, 'c', -2))
+    'banana'
+    """
+    next_obj = obj
+    for key in key_list:
+        next_obj = any_getter(next_obj, key, None)
+        if next_obj is None:
+            return default
+    return next_obj
+
+
+def nested_set(obj: Union[Mapping, Sequence],
+               key_list: Sequence[Union[str, int]],
+               value: Any):
+    """Given a nested Mapping, Sequence or any indexable/subscriptable object of
+    other such, and a Sequence of keys and/or indexes, sets the value the those
+    keys/indexes point to.
+
+    If any key/index doesn't exist, it will be created/set if possible
+
+    """
+    next_obj = obj
+    last = key_list[-1]
+    path = key_list[:-1]
+    for key in path:
+        next_next_obj = any_getter(next_obj, key, None)
+        if next_next_obj is None:
+            next_next_obj = {}
+            any_setter(next_obj, key, next_next_obj)
+        next_obj = next_next_obj
+
+    any_setter(next_obj, last, value)
+

batutils/tpu/iters/_dicts.py

@@ -0,0 +1,130 @@
+__all__ = [
+    'nested_dict_update',
+    'nest_dict',
+    'str_nest_dict',
+    'flatten_dict',
+    'str_flatten_dict',
+]
+
+from batutils.tpu.structs import *
+
+
+def nested_dict_update(base_map: Dict[Any, Any], update_map: Dict[Any, Any]):
+    """Updates a nested dicts. This means that if the `base_map` and
+    `update_map` contain the same key that is a dict in both, that nested dict
+    will be updated the same way `base_map.update(update_map)` works, i.e. it
+    will preserve any pre-existing keys in `base_map` and only update the values
+    of keys in the `update_map` (again, in a nested way).
+
+    Example of normal update:
+    >>> a = {'foo': 1, 'bar': {'alpha': 2, 'beta': 3}, 'oof': 4}
+    >>> b = {'foo': 101, 'bar': {'beta': 103}}
+    >>> a.update(b)
+    >>> print(a)
+    {'foo': 101, 'bar': {'beta': 103}, 'oof': 4}
+
+    Example of nested update:
+    >>> a = {'foo': 1, 'bar': {'alpha': 2, 'beta': 3}, 'oof': 4}
+    >>> b = {'foo': 101, 'bar': {'beta': 103}}
+    >>> nested_dict_update(a, b)
+    >>> print(a)
+    {'foo': 101, 'bar': {'alpha': 2, 'beta': 103}, 'oof': 4}
+
+    Note that if a key (or nested key) who's value is a dict in `base_map` is
+    NOT a dict in `update_map`, that dict value will be overwritten completely
+    with the new value and type.
+    """
+    for k, v in update_map.items():
+        if k in base_map:
+            base_val = base_map[k]
+            if isinstance(base_val, dict) and isinstance(v, dict):
+                nested_dict_update(base_val, v)
+                base_map[k] = base_val
+            else:
+                base_map[k] = v
+        else:
+            base_map[k] = v
+
+
+def nest_dict(key_list: List[Any], value: Any = None) -> Dict[Any, Any]:
+    """Creates a nested dict using a list of keys to construct an ever deepening
+    dict of a dict of a dict etc.
+
+    Example:
+    >>> nest_dict(['a', 'b', 'c'], 'value')
+    {'a': {'b': {'c': 'value'}}}
+    """
+    if not key_list:
+        return value
+    k = key_list.pop(0)
+    return {k: nest_dict(key_list, value)}
+
+
+def str_nest_dict(nested_key_string: str, value: Any = None, key_seperator: str = '.') -> Dict[str, Any]:
+    """Creates a nested dict using a string with some separator symbol to split
+    it into a list of keys to construct an ever deepening dict of a dict of a
+    dict etc.
+
+    Example:
+    >>> str_nest_dict('a.b.c', 'value')
+    {'a': {'b': {'c': 'value'}}}
+    """
+    return nest_dict(nested_key_string.split(key_seperator), value)
+
+
+def _denest_dict(some_dict: Dict[Any, Any]) -> List[Tuple[List[Any], Any]]:
+    """Takes a potentially nested dict and returns a list of Tuple pairs
+    containing all "leaf" values (values that aren't dicts) as each Tuples
+    second value while the first value will be a list of the "key-path" through
+    the nested dict to that value.
+
+    Example:
+    >>> _denest_dict({'a': {7: {'c': 'value'}, 5: 'other'}})
+    [(['a', 7, 'c'], 'value'), (['a', 5], 'other')]
+    """
+    buff = []
+    for k, v in some_dict.items():
+        if isinstance(v, dict):
+            for nk, nv in _denest_dict(v):
+                buff.append(([k]+nk, nv))
+        else:
+            buff.append(([k], v))
+    return buff
+
+
+def flatten_dict(some_dict: Dict[Any, Any]) -> Dict[Tuple, Any]:
+    """Takes a dict that may (or may not) be nested (contain other dicts) and
+    flattens it out by keys, returning a single dict with one value entry per
+    "leaf" value (any value in the nested dict tree that is NOT another dict)
+    where they key for each value is a tuple of the key "path" to it in the
+    original dict.
+
+    >>> flatten_dict({'a': {7: {'c': 'value'}, 5: 'other'}})
+    {('a', 7, 'c'): 'value', ('a', 5): 'other'}
+    """
+    buff = {}
+    for k, v in _denest_dict(some_dict):
+        buff[tuple(k)] = v
+    return buff
+
+
+def str_flatten_dict(some_dict: Dict[str, Any], joiner: str = '.', caster: Callable = str) -> Dict[str, Any]:
+    """Does the same as `flatten_dict` except instead of keys of tuples, keys
+    are converted to str and joined with a dot character (by default).
+
+    Both the joining character (or string) and how each value in the key tuple
+    is converted to a str is customizable.
+
+    This can be especially useful if keys contain objects who's hash values
+    differ but who's str representations are the same, e.g. the int 1 and the
+    string '1' in {1: 'a', '1': 'b'}. That dict will turn into {'1': 'b'}.
+
+    :type some_dict: dict
+    :type joiner: str
+    :type caster: function
+    :rtype: dict[str,Any]
+    """
+    buff = {}
+    for k, v in _denest_dict(some_dict):
+        buff[joiner.join([caster(ki) for ki in k])] = v
+    return buff