osbot-utils 1.7.7__py3-none-any.whl

osbot_utils/decorators/methods/cache_on_function.py

@@ -0,0 +1,56 @@
+import inspect
+from functools import wraps
+
+from osbot_utils.utils.Misc import str_md5
+
+CACHE_ON_SELF_KEY_PREFIX = 'cache_on_function'
+CACHE_ON_SELF_TYPES      = [int, float, bytearray, bytes, bool,
+                            complex, str]
+
+# todo: refactor with cache_on_self (since there is quite a lot of shared code)
+def cache_on_function(function):
+    """
+    Use this for cases where we want the cache to be tied to the function instance or static method
+    """
+    @wraps(function)
+    def wrapper(*args, **kwargs):
+        target = function                                                   # use function as the cache target
+        if 'reload_cache' in kwargs:                                        # if the reload parameter is set to True
+            reload_cache = True                                             # set reload to True
+            del kwargs['reload_cache']                                      # remove the reload parameter from the kwargs
+        else:
+            reload_cache = False                                            # otherwise set reload to False
+        cache_id = cache_on_self__get_cache_in_key(function, args, kwargs)
+        if reload_cache is True or hasattr(target, cache_id) is False:        # check if return_value has been set or if reload is True
+            return_value = function(*args, **kwargs)                        # invoke function and capture the return value
+            setattr(target, cache_id,return_value)                            # set the return value
+        return getattr(target, cache_id)                                      # return the return value
+    return wrapper
+
+def cache_on_self__args_to_str(args):
+    args_values_as_str = ''
+    if args:
+        for arg in args:
+            if type(arg) in CACHE_ON_SELF_TYPES:
+                args_values_as_str += str(arg)
+    return args_values_as_str
+
+def cache_on_self__kwargs_to_str(kwargs):
+    kwargs_values_as_str = ''
+    if kwargs:
+        for key,value in kwargs.items():
+            if type(value) in CACHE_ON_SELF_TYPES:
+                kwargs_values_as_str += f'{key}:{value}|'
+    return kwargs_values_as_str
+
+def cache_on_self__get_cache_in_key(function, args=None, kwargs=None):
+        key_name   = function.__name__
+        args_md5   = ''
+        kwargs_md5 = ''
+        args_values_as_str   = cache_on_self__args_to_str(args)
+        kwargs_values_as_str = cache_on_self__kwargs_to_str(kwargs)
+        if args_values_as_str:
+            args_md5 = str_md5(args_values_as_str)
+        if kwargs_values_as_str:
+            kwargs_md5 = str_md5(kwargs_values_as_str)
+        return f'{CACHE_ON_SELF_KEY_PREFIX}_{key_name}_{args_md5}_{kwargs_md5}'

osbot_utils/decorators/methods/cache_on_self.py

@@ -0,0 +1,78 @@
+import inspect
+from functools import wraps
+
+from osbot_utils.utils.Misc import str_md5
+from typing import Any, Callable, TypeVar
+
+
+CACHE_ON_SELF_KEY_PREFIX = '__cache_on_self__'
+CACHE_ON_SELF_TYPES      = [int, float, bytearray, bytes, bool,
+                            complex, str]
+
+# not supported for now (need to understand side effect, )
+# - set, dict, range,, tuple, list      : cloud have inner objects
+# - memoryview                          : returns unique memory location value
+
+
+
+
+T = TypeVar('T', bound=Callable[..., Any])      # so that we have type hinting when using this class
+
+def cache_on_self(function: T) -> T:
+    """
+    Use this for cases where we want the cache to be tied to the Class instance (i.e. not global for all executions)
+    """
+    @wraps(function)
+    def wrapper(*args, **kwargs):
+        if len(args) == 0 or inspect.isclass(type(args[0])) is False:
+            raise Exception("In Method_Wrappers.cache_on_self could not find self")
+        if 'reload_cache' in kwargs:                                        # if the reload parameter is set to True
+            reload_cache = True                                             # set reload to True
+            del kwargs['reload_cache']                                      # remove the reload parameter from the kwargs
+        else:
+            reload_cache = False                                            # otherwise set reload to False
+        self = args[0]                                                      # get self
+        cache_id = cache_on_self__get_cache_in_key(function, args, kwargs)
+        if reload_cache is True or hasattr(self, cache_id) is False:        # check if return_value has been set or if reload is True
+            return_value = function(*args, **kwargs)                        # invoke function and capture the return value
+            setattr(self, cache_id,return_value)                            # set the return value
+        return getattr(self, cache_id)                                      # return the return value
+    return wrapper
+
+def cache_on_self__args_to_str(args):
+    args_values_as_str = ''
+    if args:
+        for arg in args:
+            if type(arg) in CACHE_ON_SELF_TYPES:
+                args_values_as_str += str(arg)
+    return args_values_as_str
+
+def cache_on_self__kwargs_to_str(kwargs):
+    kwargs_values_as_str = ''
+    if kwargs:
+        for key,value in kwargs.items():
+            if type(value) in CACHE_ON_SELF_TYPES:
+                kwargs_values_as_str += f'{key}:{value}|'
+    return kwargs_values_as_str
+
+def cache_on_self__get_cache_in_key(function, args=None, kwargs=None):
+        key_name   = function.__name__
+        args_md5   = ''
+        kwargs_md5 = ''
+        args_values_as_str   = cache_on_self__args_to_str(args)
+        kwargs_values_as_str = cache_on_self__kwargs_to_str(kwargs)
+        if args_values_as_str:
+            args_md5 = str_md5(args_values_as_str)
+        if kwargs_values_as_str:
+            kwargs_md5 = str_md5(kwargs_values_as_str)
+        return f'{CACHE_ON_SELF_KEY_PREFIX}_{key_name}_{args_md5}_{kwargs_md5}'
+
+        # class_name = self_obj.__class__.__name__
+        #
+        # function_name = function_obj.__name__
+        # if params:
+        #     params_as_string = '_'.join(str(x) for x in params).replace('/',' ')
+        #     params_md5       = str_md5(params_as_string)
+        #     return f'{class_name}_{function_name}_{params_md5}.gz'
+        # else:
+        #     return f'{class_name}_{function_name}.gz'

osbot_utils/decorators/methods/cache_on_tmp.py

@@ -0,0 +1,71 @@
+from osbot_utils.utils.Misc import str_md5
+
+from osbot_utils.utils.Files import temp_folder_current, path_combine, folder_create
+
+from osbot_utils.utils.Json import json_load_file_gz, json_save_file_gz
+
+#todo: add feature to only cache for some time (for example 2 minutes or 2 hours)
+#      this will solve a number of probs with the current usability of this data
+
+class cache_on_tmp:
+    """
+    Caches the return value of the wrapped method in tmp folder
+    Takes into account the request params to create the file name used for caching
+    """
+    def __init__(self, reload_data=False, return_cache_key=False):
+        self.cache_folder_name = "osbot_cache_on_tmp"
+        self.cache_folder      = path_combine(temp_folder_current(), self.cache_folder_name)
+        self.last_cache_path   = None
+        self.return_cache_key  = return_cache_key
+        self.reload_data       = reload_data
+        folder_create(self.cache_folder)
+        #print(self.last_cache_path)
+
+    def __call__(self, function):
+        def wrapper(*args,**kwargs):
+            params     = list(args)
+            if len(params) > 0:
+                self_obj   = params.pop(0)
+            else:
+                self_obj = self                  # has the side effect that the cache key is only locked to the method name
+            cache_path = self.get_cache_in_tmp_path(self_obj, function, params)
+            if self.return_cache_key:
+                return cache_path
+            data       = self.get_cache_in_tmp_data(cache_path)
+            if data and self.reload_data is False:
+               return data
+
+            function_data = function(*args,**kwargs)
+            return self.save_cache_in_tmp_data(cache_path,function_data)
+
+        return wrapper
+
+    def get_cache_in_tmp_key(self, self_obj, function_obj, params):
+        class_name = self_obj.__class__.__name__
+        # if function_obj.__class__.__name__ == 'str':      # todo: check if this is needed
+        #     function_name = function_obj
+        # else:
+        #     function_name = function_obj.__name__
+        function_name = function_obj.__name__
+        if params:
+            params_as_string = '_'.join(str(x) for x in params).replace('/',' ')
+            params_md5       = str_md5(params_as_string)
+            return f'{class_name}_{function_name}_{params_md5}.gz'
+        else:
+            return f'{class_name}_{function_name}.gz'
+
+    def get_cache_in_tmp_path(self, self_obj, function_obj, params):
+        cache_key            = self.get_cache_in_tmp_key(self_obj, function_obj, params)
+        cache_path           = path_combine(self.cache_folder,cache_key)
+        self.last_cache_path = cache_path
+        return cache_path
+        #return '/tmp/cache_in_tmp_{0}.gz'.format(cache_key)
+
+    # todo: refactor to use pickle for data load
+    def get_cache_in_tmp_data(self, cache_path):
+        return json_load_file_gz(path=cache_path)
+
+    # todo: refactor to use pickle for data save
+    def save_cache_in_tmp_data(self, cache_path, data):
+        json_save_file_gz(path=cache_path, python_object=data)
+        return data

osbot_utils/decorators/methods/capture_exception.py

@@ -0,0 +1,37 @@
+import traceback
+from functools import wraps
+from osbot_utils.utils.Dev import pprint
+
+def capture_exception(func):
+    @wraps(func)
+    def wrapper(*args, **kwargs):
+        return_value = None
+        with Capture_Exception() as context:
+            return_value = func(*args, **kwargs)
+        if context.error_occurred:
+            print("\n****** EXCEPTION DETECTED ******")
+            pprint(context.error_details)
+        return return_value
+    return wrapper
+
+class Capture_Exception:
+    error_occurred : bool
+    error_details  : dict
+
+    def __enter__(self):
+        self.error_occurred = False
+        self.error_details = {}
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        if exc_val:
+            self.error_occurred = True
+            last_frame = traceback.extract_tb(exc_tb)[-1]
+            self.error_details = {
+                'exception_type': str(exc_type.__name__),
+                'message'       : str(exc_val),
+                'last_frame'    :  { 'file': last_frame.filename,
+                                    'line': last_frame.lineno  }
+            }
+            return True
+        return False

osbot_utils/decorators/methods/capture_status.py

@@ -0,0 +1,20 @@
+from functools import wraps
+
+def capture_status(method):
+    @wraps(method)
+    def wrapper(*args, **kwargs):
+        try:
+            # Attempt to execute the method
+            result = method(*args, **kwargs)
+            return {'status': 'ok', 'data': result}
+        except Exception as error:
+            # Handle any exceptions that occur
+            return {'status': 'error', 'error': str(error)}
+    return wrapper
+
+
+def apply_capture_status(cls):
+    for attr_name, attr_value in cls.__dict__.items():
+        if callable(attr_value) and not attr_name.startswith("__"):
+            setattr(cls, attr_name, capture_status(attr_value))
+    return cls

osbot_utils/decorators/methods/catch.py

@@ -0,0 +1,13 @@
+from functools import wraps
+
+
+def catch(function):
+    """Catches any errors and returns an object with the error
+    return: { 'status': 'error', 'error': f'{exception}', 'exception': exception }"""
+    @wraps(function)
+    def wrapper(*args,**kwargs):
+        try:
+            return function(*args,**kwargs)
+        except Exception as exception:
+            return {'status': 'error', 'error': f'{exception}', 'exception': exception}         # todo return status_error    (could have some side effect on existing codebase)
+    return wrapper

osbot_utils/decorators/methods/context.py

@@ -0,0 +1,11 @@
+from contextlib import contextmanager
+
+@contextmanager
+def context(target, *args, exec_before=None, exec_after=None, **kwargs):
+    if exec_before:
+        exec_before(*args, **kwargs)
+    try:
+        yield target
+    finally:
+        if exec_after:
+            exec_after(*args, **kwargs)

osbot_utils/decorators/methods/depreciated.py

@@ -0,0 +1,79 @@
+# based on code from https://stackoverflow.com/a/40301488/262379
+import functools
+import inspect
+import warnings
+
+string_types = (type(b''), type(u''))
+
+
+def deprecated(reason):
+    """
+    This is a decorator which can be used to mark functions
+    as deprecated. It will result in a warning being emitted
+    when the function is used.
+    """
+
+    if isinstance(reason, string_types):
+
+        # The @deprecated is used with a 'reason'.
+        #
+        # .. code-block:: python
+        #
+        #    @deprecated("please, use another function")
+        #    def old_function(x, y):
+        #      pass
+
+        def decorator(func1):
+
+            if inspect.isclass(func1):
+                fmt1 = "Call to deprecated class {name} ({reason})."
+            else:
+                fmt1 = "Call to deprecated function {name} ({reason})."
+
+            @functools.wraps(func1)
+            def new_func1(*args, **kwargs):
+                warnings.simplefilter('always', DeprecationWarning)
+                warnings.warn(
+                    fmt1.format(name=func1.__name__, reason=reason),
+                    category=DeprecationWarning,
+                    stacklevel=2
+                )
+                warnings.simplefilter('default', DeprecationWarning)
+                return func1(*args, **kwargs)
+
+            return new_func1
+
+        return decorator
+
+    elif inspect.isclass(reason) or inspect.isfunction(reason):
+
+        # The @deprecated is used without any 'reason'.
+        #
+        # .. code-block:: python
+        #
+        #    @deprecated
+        #    def old_function(x, y):
+        #      pass
+
+        func2 = reason
+
+        if inspect.isclass(func2):
+            fmt2 = "Call to deprecated class {name}."
+        else:
+            fmt2 = "Call to deprecated function {name}."
+
+        @functools.wraps(func2)
+        def new_func2(*args, **kwargs):
+            warnings.simplefilter('always', DeprecationWarning)
+            warnings.warn(
+                fmt2.format(name=func2.__name__),
+                category=DeprecationWarning,
+                stacklevel=2
+            )
+            warnings.simplefilter('default', DeprecationWarning)
+            return func2(*args, **kwargs)
+
+        return new_func2
+
+    else:
+        raise TypeError(repr(type(reason)))

osbot_utils/decorators/methods/function_type_check.py

@@ -0,0 +1,62 @@
+from functools import wraps
+
+# this is an attempt at creating something simpler than
+#  - https://github.com/agronholm/typeguard
+#  - https://github.com/Stewori/pytypes
+
+def is_instance_method(function, args):
+    if args and len(args) >0:
+        first_type    = type(args[0])
+        function_name = function.__name__
+        return hasattr(first_type, function_name)
+    return False
+
+def function_type_check(function):
+
+    @wraps(function)
+    def wrapper(*args,**kwargs):
+        _args       = list(args)
+        annotations = function.__annotations__
+        if is_instance_method(function, args):  # if this a instance method
+            _args.pop(0)                         # remove self (for now)
+        for name, var_type in annotations.items():
+            if name=='return': continue
+            if _args:
+                value = _args.pop(0)
+            else:
+                value = kwargs.get(name)
+                if value is None:
+                    continue
+            #if isinstance(value, var_type) is False:                           # false positive with int and bool
+            if type(value) is not var_type:
+                raise Exception(f'in function "{function.__name__}", the provided param "{value}" was an "{type(value)}" and it was expected to be {var_type}')
+        return_value = function(*args, **kwargs)
+        return_type  = annotations.get('return')
+        if annotations.get('return'):
+            if type(return_value) is not return_type:
+                raise Exception(f'in function "{function.__name__}", the provided return value "{return_value}" was an "{type(return_value)}" and it was expected to be {return_type}')
+        return return_value
+
+    return wrapper
+
+# this was causing lots of site effects (for example not working for static methods and
+# methods would not show on code complete (it was working ok for instances methods, but the lack of code complete was an issue)
+# def class_type_check(Target_Class):                                   #
+#     class Wrapped_Cls(object):
+#         def __init__(self,*args,**kwargs):
+#             self.target_class = Target_Class(*args,**kwargs)          #
+#
+#         def __getattribute__(self,s):
+#             try:
+#                 x = super(Wrapped_Cls,self).__getattribute__(s)
+#             except AttributeError:
+#                 pass
+#             else:
+#                 return x
+#             x = self.target_class.__getattribute__(s)
+#             if type(x) == type(self.__init__):                # it is an instance method
+#                 return function_type_check(x)                 # this is equivalent of just decorating the method with function_type_check
+#             else:
+#                 return x
+#
+#     return Wrapped_Cls

osbot_utils/decorators/methods/obj_as_context.py

@@ -0,0 +1,6 @@
+from contextlib import contextmanager
+
+
+@contextmanager
+def obj_as_context(variable):
+    yield variable

osbot_utils/decorators/methods/remove_return_value.py

@@ -0,0 +1,22 @@
+from functools import wraps
+
+
+class remove_return_value:
+    """
+    removes the field from the return value of the function (if it exists)
+    """
+    def __init__(self, field_name):
+        self.field_name = field_name                                # field to remove
+
+    def __call__(self, function):
+        @wraps(function)                                            # makes __name__ work ok
+        def wrapper(*args,**kwargs):                                # wrapper function
+            data = function(*args,**kwargs)                         # calls wrapped function with original params
+            if data and hasattr(data,'get'):                        # if it is set and has .get method
+                if data.get(self.field_name) is not None:           # check if field_name exists in data
+                    del data[self.field_name]                       # if it does, delete it
+            return data                                             # return data received
+        return wrapper                                              # return wrapper function
+
+#todo: check usages and remove legacy method
+remove      = remove_return_value

osbot_utils/decorators/methods/required_fields.py

@@ -0,0 +1,19 @@
+from functools import wraps
+
+from osbot_utils.utils.Objects import get_missing_fields
+
+
+class required_fields:
+    """checks that required fields are not null in the current object (does not work for for static methods)"""
+    def __init__(self, field_names):
+        self.field_names = field_names
+
+    def __call__(self, function):
+        @wraps(function)
+        def wrapper(*args, **kwargs):
+            target_obj = args[0]                                                        # self of the caller
+            missing_fields = get_missing_fields(target_obj, self.field_names)
+            if len(missing_fields) > 0:
+                raise  Exception(f'missing fields in {function.__name__}: {missing_fields}')
+            return function(*args,**kwargs)
+        return wrapper

osbot_utils/fluent/Fluent_Dict.py

@@ -0,0 +1,19 @@
+from osbot_utils.fluent.Fluent_List import Fluent_List
+
+class Fluent_Dict(dict):
+    def __new__(cls, *args, **kwargs):
+        first_one = args[0]
+        return super().__new__(cls, first_one)
+
+    def __init__(self,*args,**kwargs):
+        self.data = args[0]
+        super().__init__(*args,**kwargs)
+
+    def keys(self):
+        return Fluent_List(sorted(list(self.data.keys())))
+
+    def size(self):
+        return len(self.data)
+
+    def type(self):
+        return type(self)

osbot_utils/fluent/Fluent_List.py

@@ -0,0 +1,44 @@
+class Fluent_List(list):
+    def __new__(cls, *args, **kwargs):
+        return super().__new__(cls, args[0])
+
+    def __init__(self,*args,**kwargs):
+        super().__init__(*args,**kwargs)
+
+    def contains(self, item):
+        return item in self
+
+    def index(self, index):
+        if index < self.size():
+            return self[index]
+
+    def first(self):
+        if self.size() > 0:
+            return self[0]
+
+    def last(self):
+        if self.size() > 0:
+            return self[self.size() -1]
+
+    def pop(self):
+        """
+        normal pop() function with the only variation being that empty lists will return None instead of raising an exception
+        """
+        if self.size() > 0:
+            return super().pop()
+
+    def push(self, value):
+        self.append(value)
+        return self
+
+    def size(self):
+        return len(self)
+
+    def sorted(self):
+        return sorted(self)
+
+    def type(self):                         # todo: find a way to add this kind of methods to all Fluent Classes
+        return type(self)
+
+
+Fluent_List.sort = Fluent_List.sorted

osbot_utils/fluent/__init__.py

@@ -0,0 +1 @@
+

osbot_utils/graphs/mermaid/Mermaid.py

@@ -0,0 +1,75 @@
+from osbot_utils.graphs.mermaid.Mermaid__Renderer   import Mermaid__Renderer
+from osbot_utils.graphs.mermaid.Mermaid__Edge       import Mermaid__Edge
+from osbot_utils.graphs.mermaid.Mermaid__Graph      import Mermaid__Graph
+from osbot_utils.graphs.mermaid.models.Mermaid__Diagram_Direction import Diagram__Direction
+from osbot_utils.graphs.mermaid.models.Mermaid__Diagram__Type import Diagram__Type
+from osbot_utils.utils.Python_Logger            import Python_Logger
+from osbot_utils.base_classes.Kwargs_To_Self    import Kwargs_To_Self
+
+class Mermaid(Kwargs_To_Self):
+    graph             : Mermaid__Graph
+    renderer          : Mermaid__Renderer
+    logger            : Python_Logger
+
+    # todo add support for storing the data in sqlite so that the search for existing nodes is efficient
+    def add_edge(self, from_node_key, to_node_key, label=None,attributes=None):
+        nodes_by_id = self.graph.data().nodes__by_key()
+        from_node   = nodes_by_id.get(from_node_key)
+        to_node     = nodes_by_id.get(to_node_key)
+        if not from_node:
+            from_node = self.add_node(key=from_node_key)
+        if not to_node:
+            to_node = self.add_node(key=to_node_key)
+
+        # todo: add back the protection/detection that we get from MGraph class of allow_circle_edges and allow_duplicate_edges
+        mermaid_edge = Mermaid__Edge(from_node=from_node, to_node=to_node, label=label, attributes=attributes)
+        self.graph.edges.append(mermaid_edge)
+        return mermaid_edge
+
+    def add_directive(self, directive):
+        self.renderer.config.directives.append(directive)
+        return self
+
+    def add_node(self, **kwargs):
+        return self.graph.add_node(**kwargs)
+
+    def code(self):
+        return self.renderer.code(self.nodes(), self.edges())
+
+    def code_markdown(self):
+        #self.code_create()
+        self.code()
+        rendered_lines = self.renderer.mermaid_code
+        markdown = ['#### Mermaid Graph',
+                    "```mermaid"        ,
+                    *rendered_lines     ,
+                    "```"               ]
+
+        return '\n'.join(markdown)
+
+    def edges(self):
+        return self.graph.edges
+
+    def print_code(self):
+        print(self.code())
+
+    def nodes(self):
+        return self.graph.nodes
+
+    def set_direction(self, direction):
+        if isinstance(direction, Diagram__Direction):
+            self.renderer.diagram_direction = direction
+        elif isinstance(direction, str) and direction in Diagram__Direction.__members__:
+            self.renderer.diagram_direction = Diagram__Direction[direction]
+        return self                             # If the value can't be set (not a valid name), do nothing
+
+    def set_diagram_type(self, diagram_type):
+        if isinstance(diagram_type, Diagram__Type):
+            self.renderer.diagram_type = diagram_type
+
+    def save(self, target_file=None):
+        file_path = target_file or '/tmp/mermaid.md'
+
+        with open(file_path, 'w') as file:
+            file.write(self.code_markdown())
+        return file_path