batutils 2.0.0__py3-none-any.whl

batutils/tpu/iters/_group.py

@@ -0,0 +1,50 @@
+__all__ = [
+    'group_by',
+]
+
+from batutils.tpu.structs import *
+
+T_OBJ = TypeVar('T_OBJ')
+
+
+def group_by(list_of_stuff: Iterable[T_OBJ],
+             key_getter: Union[str, int, Callable]) -> Dict[Any, List[T_OBJ]]:
+    """Given a list of stuff and a "key getter", returns a dict with key value
+    pairs of the values given by the "key getter" as the unique keys in that
+    dict and the values a list of the stuffs from the given list who's "key
+    getter" values matched the return dicts key.
+
+    In other words, groups a list of things by the values returned by the "key
+    getter" to a dict.
+
+    The "key getter" can be any of the following, resulting in slightly different
+    functionality based on type:
+     - A str: will try and fetch an attribute with that name from each object in
+     the list of stuff or use the string as a key if the object is a dict like.
+     If that attribute is a method or other callable, it will be called with the
+     expectation that it's the name of an accessor method that will return the
+     relevant key value.
+     - An int: will assume this is an index so it will be used in a indexing
+     getitem call.
+     - Any callable: will assume a method that takes in an object of the type in
+     the list of stuff and returns the required value from the object to use as
+     a key and group the objects by.
+    """
+    group_map: Dict[Hashable, List[T_OBJ]] = {}
+    if isinstance(key_getter, (str, int)):
+        from batutils.tpu.iters import any_getter
+        getter_call = lambda x: any_getter(x, key_getter)
+
+    else:
+        getter_call = key_getter
+
+    for stuff in list_of_stuff:
+        a = getter_call(stuff)
+        if isinstance(a, Callable):
+            a = a()
+
+        if a not in group_map:
+            group_map[a] = []
+        group_map[a].append(stuff)
+
+    return group_map

batutils/tpu/iters/_lists.py

@@ -0,0 +1,178 @@
+__all__ = [
+    'venn',
+    'startswith',
+    'endswith',
+    'has',
+    'has_all',
+    'has_any',
+]
+
+from batutils.tpu.structs import *
+
+
+def venn(left: Union[List, Set, Tuple, Dict], right: Union[List, Set, Tuple, Dict]) -> Tuple[List, List, List]:
+    """Returns the relative complements and intersections of two lists in a
+    three-tuple of lists.
+
+     - The first list contains the relative complements of the right list in
+       the left one (i.e. list of values unique to the left list)
+     - The second list contains the intersection of left and right (i.e. list
+       of values that exist in both left and right)
+     - The third list contains the relative complements of the left list in
+       the right one (i.e. list of values unique to the right list)
+
+    Another way to think of this is to envision the return values as the left,
+    middle and right parts of a Venn diagram made from the left and right input
+    or different joins of two tables, i.e. left outer join on left table where
+    right is null, inner full and right outer join on right table where left
+    is null. :)
+
+    Duplicated values in either input list will be ignored (i.e. repeating
+    values only appear once in the output).
+
+    Using a dict (or dict like iterable object) will only use and return the
+    keys, ignoring the values.
+
+    :param left: Any iterable that can be turned into a set as the left set
+    :type left: list | tuple | set | dict | str | unicode
+    :param right: Any iterable that can be turned into a set as the right set
+    :type right: list | tuple | set | dict | str | unicode
+    :return: A three-tuple of lists (see description)
+    :rtype: (list, list, list)
+    """
+    left = set(left)
+    right = set(right)
+    return list(left.difference(right)), list(left.intersection(right)), list(right.difference(left))
+
+
+def startswith(main_list: Union[Tuple[Any], List[Any]], sub_list: Union[Tuple[Any], List[Any]]) -> bool:
+    """Returns True if the given main_list starts with the same values
+    (in order) as the given sub_list.
+
+    :type sub_list: list | tuple
+    :type main_list: list | tuple
+    :rtype: bool
+    """
+    if not sub_list:
+        return True
+
+    find_len = len(sub_list)
+    search_len = len(main_list)
+
+    if find_len > search_len:
+        return False
+
+    found = True
+    for i in range(find_len):
+        if sub_list[i] != main_list[i]:
+            found = False
+            break
+    return found
+
+
+def endswith(main_list: Union[Tuple[Any], List[Any]], sub_list: Union[Tuple[Any], List[Any]]) -> bool:
+    """Returns True if the given main_list ends with the same values
+    (in order) as the given sub_list.
+
+    :type sub_list: list | tuple
+    :type main_list: list | tuple
+    :rtype: bool
+    """
+    if not sub_list:
+        return True
+
+    find_len = len(sub_list)
+    search_len = len(main_list)
+
+    if find_len > search_len:
+        return False
+
+    found = True
+    for i in range(1, find_len+1):
+        if sub_list[-i] != main_list[-i]:
+            found = False
+            break
+    return found
+
+
+def has(main_list: Union[Tuple[Any], List[Any]], sub_list: Union[Tuple[Any], List[Any]]) -> bool:
+    """Returns True if the given main_list has all the same values as the given
+    sub_list in sequential order (or "is-ordered-subset").
+
+    :param main_list:
+    :type main_list: list | tuple
+    :param sub_list:
+    :type sub_list: list | tuple
+    :return:
+    :rtype:
+    """
+    find_len = len(sub_list)
+    search_len = len(main_list)
+
+    if not sub_list:
+        return True
+
+    if find_len < search_len:
+        first_sym = sub_list[0]
+        if find_len > 1:
+            idx = -1
+            found = False
+            stopdex = search_len - find_len
+            while not found:
+                try:
+                    idx = main_list.index(first_sym, idx + 1)
+                    if idx > stopdex:
+                        return False
+                    found = True
+                    for i in range(1, find_len):
+                        if sub_list[i] != main_list[idx + i]:
+                            found = False
+                            break
+                except ValueError:
+                    break
+            return found
+        else:
+            return first_sym in main_list
+    elif find_len > search_len:
+        return False
+    else:
+        return find_len == search_len
+
+
+def has_all(main_list: Union[Tuple[Any], List[Any]], sub_list: Union[Tuple[Any], List[Any]]) -> bool:
+    """Returns True if the given main_list contains all the values of the given
+    sub_list (in any order).
+
+    :param main_list:
+    :type main_list: list | tuple | set | dict
+    :param sub_list:
+    :type sub_list: list | tuple | set | dict
+    :return:
+    :rtype:
+    """
+    if not sub_list:
+        return True
+    sub_set = set(sub_list)
+    main_set = set(main_list)
+    return sub_set.issubset(main_set)
+
+
+def has_any(main_list: Union[Tuple[Any], List[Any]], sub_list: Union[Tuple[Any], List[Any]]) -> bool:
+    """Returns true if the given main_list contains any of the values in the
+    given sub_list (in any order).
+
+    :param main_list:
+    :type main_list: list | tuple | set | dict
+    :param sub_list:
+    :type sub_list: list | tuple | set | dict
+    :return:
+    :rtype:
+    """
+    if not sub_list:
+        return True
+    sub_set = set(sub_list)
+    main_set = set(main_list)
+    for val in sub_set:
+        if val in main_set:
+            return True
+    return False

batutils/tpu/size/__init__.py

@@ -0,0 +1 @@
+from ._total import *

batutils/tpu/size/_total.py

@@ -0,0 +1,52 @@
+__all__ = [
+    'total_size',
+]
+
+
+import sys
+import itertools
+import collections
+
+
+def total_size(o, handlers=None, verbose=False):
+    """ Returns the approximate memory footprint an object and all of its contents.
+
+    From http://code.activestate.com/recipes/577504/
+
+    Automatically finds the contents of the following builtin containers and
+    their subclasses:  tuple, list, deque, dict, set and frozenset.
+    To search other containers, add handlers to iterate over their contents:
+
+        handlers = {SomeContainerClass: iter,
+                    OtherContainerClass: OtherContainerClass.get_elements}
+
+    """
+    dict_handler = lambda d: itertools.chain.from_iterable(d.items())
+    all_handlers = {tuple: iter,
+                    list: iter,
+                    collections.deque: iter,
+                    dict: dict_handler,
+                    set: iter,
+                    frozenset: iter,
+                   }
+    handlers = handlers or {}
+    all_handlers.update(handlers)     # user handlers take precedence
+    seen = set()                      # track which object id's have already been seen
+    default_size = sys.getsizeof(0)       # estimate sizeof object without __sizeof__
+
+    def sizeof(o):
+        if id(o) in seen:       # do not double count the same object
+            return 0
+        seen.add(id(o))
+        s = sys.getsizeof(o, default_size)
+
+        if verbose:
+            print(s, type(o), repr(o), file=sys.stderr)
+
+        for typ, handler in all_handlers.items():
+            if isinstance(o, typ):
+                s += sum(map(sizeof, handler(o)))
+                break
+        return s
+
+    return sizeof(o)

batutils/tpu/strimp/__init__.py

@@ -0,0 +1 @@
+from ._getters import *

batutils/tpu/strimp/_getters.py

@@ -0,0 +1,285 @@
+__all__ = [
+    'get_any',
+    'get_module',
+    'get_class',
+    'get_callable',
+    'get_methfunc',
+    'get_function',
+]
+
+"""String Importing Utilities.
+
+That is, functions to import and return python stuff via string during runtime.
+"""
+import importlib
+import inspect
+from batutils.tpu import insp
+
+import logging
+log = logging.getLogger(__name__)
+
+
+def get_any(string, default=None, logger=False, reraise=False):
+    """Attempts to import and return anything via the given string.
+
+    Anything here essentially means, module or any module attribute (stuff
+    declared at the top level of a module like classes and functions).
+
+    If the given string is not a string, the given parameter is simply
+    returned back.
+
+    This function is "silent" be default, i.e. it returns the given default (or
+    None) if it fails to find the stuff to import without raising an exception.
+
+    Set the reraise parameter to True in order to have this function raise any
+    Exceptions it encounters.
+
+    The logger parameter is False by default which means nothing is logged on
+    any error but you can set it to True or None in order to log any Exceptions
+    (e.g. ImportError or AttributeError) encountered.
+
+    You can also set the logger parameter to any other logging.Logger in order
+    to log to that logger instead of the module default (tpu.strimp).
+
+    :param string: A string with the module or module attribute to try and
+                   import.
+    :type string: str, unicode or any
+    :param default: The default value to return on failure.
+    :type default: any
+    :param logger: The logger to log errors to (False = No logging,
+                   True/None = module default: batutils.tpu.strimp)
+    :type logger: bool or None or logging.Logger
+    :param reraise: Should exceptions and errors encountered be reraised?
+    :type reraise: bool
+    :return: The module or whatever the given string was referring to or the
+             default value given on failure.
+    :rtype: any
+    """
+    if not isinstance(string, str):
+        return string
+    try:
+        if '.' in string:
+            ridx = string.rindex('.')
+            mod_name = string[:ridx]
+            any_name = string[ridx + 1:]
+            from_module = importlib.import_module(mod_name)
+            if hasattr(from_module, any_name):
+                return getattr(from_module, any_name)
+            else:  # Might be a module...?
+                return importlib.import_module(string)
+        else:  # Must be a module then...?
+            return importlib.import_module(string)
+    except ImportError as ex:
+        if logger is not False:
+            if logger is True or logger is None:
+                logger = log
+            logger.exception(u'ImportError in batutils.tpu.strimp.get_any("%s"): %r', string, ex)
+        if reraise:
+            raise
+    except AttributeError as ex:
+        if logger is not False:
+            if logger is True or logger is None:
+                logger = log
+            logger.exception(u'AttributeError in batutils.tpu.strimp.get_any("%s"): %r', string, ex)
+        if reraise:
+            raise
+    except Exception as ex:
+        if logger is not False:
+            if logger is True or logger is None:
+                logger = log
+            logger.exception(u'Exception in batutils.tpu.strimp.get_any("%s"): %r', string, ex)
+        if reraise:
+            raise
+
+    return default
+
+
+def get_module(string, default=None, logger=False, reraise=False):
+    """Attempts to import and return a python module via the given string.
+
+    This is essentially just a call to get_any with the added check to see if
+    the imported thing is a module, so see the get_any documentation for details.
+
+    :param string: A string with the module to try and import.
+    :type string: str, unicode or any
+    :param default: The default value to return on failure.
+    :type default: any
+    :param logger: The logger to log errors to (False = No logging,
+                   True/None = module default: tpu.strimp)
+    :type logger: bool or None or logging.Logger
+    :param reraise: Should exceptions and errors encountered be reraised?
+    :type reraise: bool
+    :return: The module or whatever the given string was referring to or the
+             default value given on failure.
+    :rtype: module or None
+    """
+    try:
+        something = importlib.import_module(string)
+
+        if inspect.ismodule(something):
+            return something
+        else:
+            raise ValueError(u'Not a module: %s (it is "%s")' % (string, type(something)))
+    except ValueError as ex:
+        if logger is not False:
+            if logger is True or logger is None:
+                logger = log
+            logger.exception(u'Exception in batutils.tpu.strimp.get_module("%s"): %r', string, ex)
+        if reraise:
+            raise
+    except Exception:
+        if reraise:
+            raise
+    return default
+
+
+def get_class(string, default=None, logger=False, reraise=False):
+    """Attempts to import and return a class via the given string.
+
+    This is essentially just a call to get_any with the added check to see if
+    the imported thing is a class, so see the get_any documentation for details.
+
+    :param string: A string with the class to try and import.
+    :type string: str, unicode or any
+    :param default: The default value to return on failure.
+    :type default: any
+    :param logger: The logger to log errors to (False = No logging,
+                   True/None = module default: tpu.strimp)
+    :type logger: bool or None or logging.Logger
+    :param reraise: Should exceptions and errors encountered be reraised?
+    :type reraise: bool
+    :return: The module or whatever the given string was referring to or the
+             default value given on failure.
+    :rtype: class or type or None
+    """
+    try:
+        something = get_any(string, None, logger=logger, reraise=True)
+        if inspect.isclass(something):
+            return something
+        else:
+            raise ValueError(u'Not a class: %s (it is "%s")' % (string, type(something)))
+    except ValueError as ex:
+        if logger is not False:
+            if logger is True or logger is None:
+                logger = log
+            logger.exception(u'Exception in batutils.tpu.strimp.get_class("%s"): %r', string, ex)
+        if reraise:
+            raise
+    except Exception:
+        if reraise:
+            raise
+    return default
+
+
+def get_callable(string, default=None, logger=False, reraise=False):
+    """Attempts to import and return a callable via the given string.
+
+    This is essentially just a call to get_any with the added check to see if
+    the imported thing is a callable via tpu.insp.is_callable.
+
+    :param string: A string with the callable to try and import.
+    :type string: str, unicode or any
+    :param default: The default value to return on failure.
+    :type default: any
+    :param logger: The logger to log errors to (False = No logging,
+                   True/None = module default: tpu.strimp)
+    :type logger: bool or None or logging.Logger
+    :param reraise: Should exceptions and errors encountered be reraised?
+    :type reraise: bool
+    :return: The module or whatever the given string was referring to or the
+             default value given on failure.
+    :rtype: function or method or object or None
+    """
+    try:
+        something = get_any(string, None, logger=logger, reraise=True)
+        if insp.is_callable(something):
+            return something
+        else:
+            raise ValueError(u'Not callable: %s (it is "%s")' % (string, type(something)))
+    except ValueError as ex:
+        if logger is not False:
+            if logger is True or logger is None:
+                logger = log
+            logger.exception(u'Exception in batutils.tpu.strimp.get_callable("%s"): %r', string, ex)
+        if reraise:
+            raise
+    except Exception:
+        if reraise:
+            raise
+    return default
+
+
+def get_methfunc(string, default=None, logger=False, reraise=False):
+    """Attempts to import and return a callable via the given string.
+
+    This is essentially just a call to get_any with the added check to see if
+    the imported thing is a method or function via tpu.insp.is_methfunc.
+
+    :param string: A string with the method or function to try and import.
+    :type string: str, unicode or any
+    :param default: The default value to return on failure.
+    :type default: any
+    :param logger: The logger to log errors to (False = No logging,
+                   True/None = module default: tpu.strimp)
+    :type logger: bool or None or logging.Logger
+    :param reraise: Should exceptions and errors encountered be reraised?
+    :type reraise: bool
+    :return: The module or whatever the given string was referring to or the
+             default value given on failure.
+    :rtype: function or method or None
+    """
+    try:
+        something = get_any(string, None, logger=logger, reraise=True)
+        if insp.is_methfunc(something):
+            return something
+        else:
+            raise ValueError(u'Not a method or function: %s (it is "%s")' % (string, type(something)))
+    except ValueError as ex:
+        if logger is not False:
+            if logger is True or logger is None:
+                logger = log
+            logger.exception(u'Exception in batutils.tpu.strimp.get_methfunc("%s"): %r', string, ex)
+        if reraise:
+            raise
+    except Exception:
+        if reraise:
+            raise
+    return default
+
+
+def get_function(string, default=None, logger=False, reraise=False):
+    """Attempts to import and return a callable via the given string.
+
+    This is essentially just a call to get_any with the added check to see if
+    the imported thing is a method or function via tpu.insp.is_methfunc.
+
+    :param string: A string with the function to try and import.
+    :type string: str, unicode or any
+    :param default: The default value to return on failure.
+    :type default: any
+    :param logger: The logger to log errors to (False = No logging,
+                   True/None = module default: tpu.strimp)
+    :type logger: bool or None or logging.Logger
+    :param reraise: Should exceptions and errors encountered be reraised?
+    :type reraise: bool
+    :return: The module or whatever the given string was referring to or the
+             default value given on failure.
+    :rtype: function or method or None
+    """
+    try:
+        something = get_any(string, None, logger=logger, reraise=True)
+        if inspect.isfunction(something):
+            return something
+        else:
+            raise ValueError(u'Not a function: %s (it is "%s")' % (string, type(something)))
+    except ValueError as ex:
+        if logger is not False:
+            if logger is True or logger is None:
+                logger = log
+            logger.exception(u'Exception in batutils.tpu.strimp.get_function("%s"): %r', string, ex)
+        if reraise:
+            raise
+    except Exception:
+        if reraise:
+            raise
+    return default

batutils/tpu/string/__init__.py

@@ -0,0 +1 @@
+from ._string import *