osbot-utils 1.7.7__py3-none-any.whl

osbot_utils/__init__.py

@@ -0,0 +1 @@
+path=__path__[0]

osbot_utils/base_classes/Cache_Pickle.py

@@ -0,0 +1,129 @@
+import os
+from functools import wraps
+
+from osbot_utils.utils.Files import path_combine, folder_create, temp_folder_current, file_exists, \
+    pickle_load_from_file, pickle_save_to_file, files_list, files_recursive
+from osbot_utils.utils.Misc import str_md5
+from osbot_utils.utils.Python_Logger import logger_info
+
+
+
+class Cache_Pickle:
+
+    _cache__FOLDER_CACHE_ROOT_FOLDER = '_cache_pickle'
+    _cache__SUPPORTED_PARAMS_TYPES   = [int, float, bytearray, bytes, bool, complex, str]
+
+    def __init__(self):
+        self._cache_enabled = True
+        #self.log_info      = logger_info()
+        self._cache_setup()              # make sure the cache folder exists
+
+    def __enter__(self): return self
+    def __exit__ (self, type, value, traceback): pass
+
+    def __getattribute__(self, name):
+        if name.startswith('_cache_') or name.startswith('__'):                 # if the method is a method from Cache_Pickleor a private method
+            return super().__getattribute__(name)                               # just return it's value
+        target = super().__getattribute__(name)                                 # get the target
+        if not callable(target):                                                # if it is not a function
+            return target                                                       # just return it
+        return self._cache_data(target)                                         # if it is a function, create a wrapper around it
+
+    def _cache_clear(self):
+        cache_dir = self._cache_path()
+        for filename in os.listdir(cache_dir):
+            if filename.endswith('.pickle'):
+                os.remove(os.path.join(cache_dir, filename))
+        return self
+
+    def _cache_data(self, func):
+
+        @wraps(func)
+        def wrapper(*args, **kwargs):
+            if type(func.__self__) != type(self):       # if the parent type of the function is not self, then just execute it (this happens if a function is set as a variable)
+                return func(*args, **kwargs)
+
+            # first check the params that are specific for this cache method (and cannot be propagated)
+            if 'reload_cache' in kwargs:                                        # if the reload parameter is set to True
+                reload_cache = kwargs['reload_cache']                           # set reload to the value provided
+                del kwargs['reload_cache']                                      # remove the reload parameter from the kwargs
+            else:
+                reload_cache = False                                            # otherwise set reload to False
+
+            if 'use_cache' in kwargs:                                           # see if we want to disable cache
+                use_cache = kwargs['use_cache']
+                del kwargs['use_cache']
+            else:
+                use_cache = True
+
+            # after processing these extra params we can resolve the file name and check if it exists
+            cache_file_name = self._cache_resolve_file_name(func, args, kwargs)
+
+            # path_file = path_combine(self._cache_path(), f'{caller_name}.pickle')
+            path_file = path_combine(self._cache_path(), cache_file_name)
+
+            if use_cache is True and reload_cache is False and file_exists(path_file):
+                return pickle_load_from_file(path_file)
+            else:
+                data = func(*args, **kwargs)
+                if data and use_cache is True:
+                    caller_name = func.__name__
+                    #print(f"Saving cache file data for: {caller_name}")
+                    pickle_save_to_file(data, path_file)
+                return data
+        return wrapper
+
+    def _cache_disable(self):
+        self._cache_enabled = False
+        return self
+
+    def _cache_path(self):
+        class_name  = self.__class__.__name__
+        module_name = self.__class__.__module__
+        folder_name = f'{self._cache__FOLDER_CACHE_ROOT_FOLDER}/{module_name.replace(".", "/")}'
+        if not module_name.endswith(class_name):
+            folder_name += f'/{class_name}'
+        return path_combine(temp_folder_current(), folder_name)
+
+    def _cache_files(self):
+        return files_recursive(self._cache_path())
+
+    def _cache_setup(self):
+        folder_create(self._cache_path())
+        return self
+
+    def _cache_kwargs_to_str(self, kwargs):
+        kwargs_values_as_str = ''
+        if kwargs:
+            if type(kwargs) is not dict:
+                return str(kwargs)
+            for key, value in kwargs.items():
+                if value and type(value) not in self._cache__SUPPORTED_PARAMS_TYPES:
+                    value = '(...)'
+                kwargs_values_as_str += f'{key}:{value}|'
+        return kwargs_values_as_str
+
+    def _cache_args_to_str(self, args):
+        args_values_as_str = ''
+        if args:
+            if type(args) is not list:
+                return str(args)
+            for arg in args:
+                if not arg or type(arg) in self._cache__SUPPORTED_PARAMS_TYPES:
+                    arg_value = str(arg)
+                else:
+                    arg_value = '(...)'
+                args_values_as_str += f'{arg_value}|'
+        return args_values_as_str
+
+    def _cache_resolve_file_name(self, function, args=None, kwargs=None):
+        key_name               = function.__name__
+        args_md5               = ''
+        kwargs_md5             = ''
+        args_values_as_str     = self._cache_args_to_str(args)
+        kwargs_values_as_str   = self._cache_kwargs_to_str(kwargs)
+        if args_values_as_str  : args_md5   = '_' + str_md5(args_values_as_str  )[:10]
+        if kwargs_values_as_str: kwargs_md5 = '_' + str_md5(kwargs_values_as_str)[:10]
+        cache_file_name        = f'{key_name}{args_md5}{kwargs_md5}'
+        cache_file_name       += '.pickle'
+        return cache_file_name

osbot_utils/base_classes/Kwargs_To_Disk.py

@@ -0,0 +1,27 @@
+from osbot_utils.helpers.Local_Cache import Local_Cache
+
+class Kwargs_To_Disk:
+
+    def __enter__(self): return self
+    def __exit__ (self, exc_type, exc_val, exc_tb): pass
+
+    def __init__(self):
+        self._cache_name  = f'{self.__class__.__module__}___{self.__class__.__name__}'
+        self._local_cache = Local_Cache(cache_name=self._cache_name).setup()
+
+    def __getattr__(self, key):
+        if key.startswith('_'):
+            return super().__getattribute__(key)
+        return self._local_cache.get(key)
+
+    def __setattr__(self, key, value):
+        if key.startswith('_'):
+            super().__setattr__(key, value)
+        else:
+            self._local_cache.set(key, value)
+
+    def _cache_create        (self): return self._local_cache.create         ()
+    def _cache_delete        (self): return self._local_cache.cache_delete   ()
+    def _cache_data          (self): return self._local_cache.data           ()
+    def _cache_exists        (self): return self._local_cache.cache_exists   ()
+    def _cache_path_data_file(self): return self._local_cache.path_cache_file()

osbot_utils/base_classes/Kwargs_To_Self.py

@@ -0,0 +1,308 @@
+# todo: find a way to add these documentations strings to a separate location so that
+#       the code is not polluted with them (like in the example below)
+#       the data is available in IDE's code complete
+import functools
+import inspect
+import types
+from decimal import Decimal
+from enum                                       import Enum, EnumMeta, EnumType
+from typing                                     import get_origin, get_args
+
+from osbot_utils.base_classes.Type_Safe__List   import Type_Safe__List
+from osbot_utils.utils.Dev                      import pprint
+from osbot_utils.utils.Json                     import json_parse
+from osbot_utils.utils.Misc                     import list_set
+from osbot_utils.utils.Objects                  import default_value, value_type_matches_obj_annotation_for_attr, \
+    raise_exception_on_obj_type_annotation_mismatch, obj_is_attribute_annotation_of_type, enum_from_value, \
+    obj_is_type_union_compatible, value_type_matches_obj_annotation_for_union_attr
+
+immutable_types = (bool, int, float, complex, str, tuple, frozenset, bytes, types.NoneType, EnumMeta)
+
+
+#todo: see if we can also add type safety to method execution
+#      for example if we have an method like def add_node(self, title: str, call_index: int):
+#          throw an exception if the type of the value passed in is not the same as the one defined in the method
+
+class Kwargs_To_Self:               # todo: check if the description below is still relevant (since a lot has changed since it was created)
+    """
+    A mixin class to strictly assign keyword arguments to pre-defined instance attributes during initialization.
+
+    This base class provides an __init__ method that assigns values from keyword
+    arguments to instance attributes. If an attribute with the same name as a key
+    from the kwargs is defined in the class, it will be set to the value from kwargs.
+    If the key does not match any predefined attribute names, an exception is raised.
+
+    This behavior enforces strict control over the attributes of instances, ensuring
+    that only predefined attributes can be set at the time of instantiation and avoids
+    silent attribute creation which can lead to bugs in the code.
+
+    Usage:
+        class MyConfigurableClass(Kwargs_To_Self):
+            attribute1 = 'default_value'
+            attribute2 = True
+            attribute3 : str
+            attribute4 : list
+            attribute4 : int = 42
+
+            # Other methods can be added here
+
+        # Correctly override default values by passing keyword arguments
+        instance = MyConfigurableClass(attribute1='new_value', attribute2=False)
+
+        # This will raise an exception as 'attribute3' is not predefined
+        # instance = MyConfigurableClass(attribute3='invalid_attribute')
+
+        this will also assign the default value to any variable that has a type defined.
+        In the example above the default values (mapped by __default__kwargs__ and __locals__) will be:
+            attribute1 = 'default_value'
+            attribute2 = True
+            attribute3 = ''             # default value of str
+            attribute4 = []             # default value of list
+            attribute4 = 42             # defined value in the class
+
+    Note:
+        It is important that all attributes which may be set at instantiation are
+        predefined in the class. Failure to do so will result in an exception being
+        raised.
+
+    Methods:
+        __init__(**kwargs): The initializer that handles the assignment of keyword
+                            arguments to instance attributes. It enforces strict
+                            attribute assignment rules, only allowing attributes
+                            that are already defined in the class to be set.
+    """
+
+    #__lock_attributes__ = False
+    #__type_safety__     = True
+
+    def __init__(self, **kwargs):
+        """
+        Initialize an instance of the derived class, strictly assigning provided keyword
+        arguments to corresponding instance attributes.
+
+        Parameters:
+            **kwargs: Variable length keyword arguments.
+
+        Raises:
+            Exception: If a key from kwargs does not correspond to any attribute
+                       pre-defined in the class, an exception is raised to prevent
+                       setting an undefined attribute.
+
+        """
+        # if 'disable_type_safety' in kwargs:                                 # special case
+        #     self.__type_safety__ = kwargs['disable_type_safety'] is False
+        #     del kwargs['disable_type_safety']
+
+        for (key, value) in self.__cls_kwargs__().items():                  # assign all default values to self
+            if value is not None:                                           # when the value is explicitly set to None on the class static vars, we can't check for type safety
+                raise_exception_on_obj_type_annotation_mismatch(self, key, value)
+            if hasattr(self, key):
+                existing_value = getattr(self, key)
+                if existing_value is not None:
+                    setattr(self, key, existing_value)
+                    continue
+            setattr(self, key, value)
+
+        for (key, value) in kwargs.items():                             # overwrite with values provided in ctor
+            if hasattr(self, key):
+                if value is not None:                                   # prevent None values from overwriting existing values, which is quite common in default constructors
+                    setattr(self, key, value)
+            else:
+                raise Exception(f"{self.__class__.__name__} has no attribute '{key}' and cannot be assigned the value '{value}'. "
+                                f"Use {self.__class__.__name__}.__default_kwargs__() see what attributes are available")
+
+    def __enter__(self): return self
+    def __exit__(self, exc_type, exc_val, exc_tb): pass
+
+    def __setattr__(self, name, value):
+        # if self.__type_safety__:
+        #     if self.__lock_attributes__:
+            # todo: this can't work on all, current hypothesis is that this will work for the values that are explicitly set
+            # if not hasattr(self, name):
+            #     raise AttributeError(f"'[Object Locked] Current object is locked (with __lock_attributes__=True) which prevents new attributes allocations (i.e. setattr calls). In this case  {type(self).__name__}' object has no attribute '{name}'") from None
+
+            if value is not None:
+                check_1 = value_type_matches_obj_annotation_for_attr(self, name, value)
+                check_2 = value_type_matches_obj_annotation_for_union_attr(self, name, value)
+                if (check_1 is False and check_2 is None  or
+                    check_1 is None  and check_2 is False or
+                    check_1 is False and check_2 is False   ):          # fix for type safety assigment on Union vars
+                    raise Exception(f"Invalid type for attribute '{name}'. Expected '{self.__annotations__.get(name)}' but got '{type(value)}'")
+            else:
+                if hasattr(self, name) and self.__annotations__.get(name) :     # don't allow previously set variables to be set to None
+                    if getattr(self, name) is not None:                         # unless it is already set to None
+                        raise Exception(f"Can't set None, to a variable that is already set. Invalid type for attribute '{name}'. Expected '{self.__annotations__.get(name)}' but got '{type(value)}'")
+
+            super().__setattr__(name, value)
+
+    def __attr_names__(self):
+        return list_set(self.__locals__())
+
+    @classmethod
+    def __cls_kwargs__(cls, include_base_classes=True):
+        """Return current class dictionary of class level variables and their values."""
+        kwargs = {}
+
+        for base_cls in inspect.getmro(cls):
+            if base_cls is object:                                                      # Skip the base 'object' class
+                continue
+            for k, v in vars(base_cls).items():
+                # todo: refactor this logic since it is weird to start with a if not..., and then if ... continue (all these should be if ... continue )
+                if not k.startswith('__') and not isinstance(v, types.FunctionType):    # remove instance functions
+                    if isinstance(v, classmethod):                                      # also remove class methods
+                        continue
+                    if type(v) is functools._lru_cache_wrapper:                         # todo, find better way to handle edge cases like this one (which happens when the @cache decorator is used in a instance method that uses Kwargs_To_Self)
+                        continue
+                    if (k in kwargs) is False:                                          # do not set the value is it has already been set
+                        kwargs[k] = v
+
+            for var_name, var_type in base_cls.__annotations__.items():
+                if hasattr(base_cls, var_name) is False:                                # only add if it has not already been defined
+                    if var_name in kwargs:
+                        continue
+                    var_value = cls.__default__value__(var_type)
+                    kwargs[var_name] = var_value
+                else:
+                    var_value = getattr(base_cls, var_name)
+                    if var_value is not None:                                                                   # allow None assignments on ctor since that is a valid use case
+                        if var_type and not isinstance(var_value, var_type):                                    # check type
+                            exception_message = f"variable '{var_name}' is defined as type '{var_type}' but has value '{var_value}' of type '{type(var_value)}'"
+                            raise Exception(exception_message)
+                        if var_type not in immutable_types and var_name.startswith('__') is False:              # if var_type is not one of the immutable_types or is an __ internal
+                            #todo: fix type safety bug that I believe is caused here
+                            if obj_is_type_union_compatible(var_type, immutable_types) is False:                # if var_type is not something like Optional[Union[int, str]]
+                                if type(var_type) not in immutable_types:
+                                    exception_message = f"variable '{var_name}' is defined as type '{var_type}' which is not supported by Kwargs_To_Self, with only the following immutable types being supported: '{immutable_types}'"
+                                    raise Exception(exception_message)
+            if include_base_classes is False:
+                break
+        return kwargs
+
+    @classmethod
+    def __default__value__(cls, var_type):
+        if get_origin(var_type) is list:                        # if we have list defined as list[type]
+            item_type = get_args(var_type)[0]                   #    get the type that was defined
+            return Type_Safe__List(expected_type=item_type)     #    and used it as expected_type in Type_Safe__List
+        else:
+            return default_value(var_type)                      # for all other cases call default_value, which will try to create a default instance
+
+    def __default_kwargs__(self):
+        """Return entire (including base classes) dictionary of class level variables and their values."""
+        kwargs = {}
+        cls = type(self)
+        for base_cls in inspect.getmro(cls):                  # Traverse the inheritance hierarchy and collect class-level attributes
+            if base_cls is object:  # Skip the base 'object' class
+                continue
+            for k, v in vars(base_cls).items():
+                if not k.startswith('__') and not isinstance(v, types.FunctionType):    # remove instance functions
+                    if not isinstance(v, classmethod):
+                        kwargs[k] = v
+            # add the vars defined with the annotations
+            for var_name, var_type in base_cls.__annotations__.items():
+                var_value        = getattr(self, var_name)
+                kwargs[var_name] = var_value
+
+        return kwargs
+
+    def __kwargs__(self):
+        """Return a dictionary of the current instance's attribute values including inherited class defaults."""
+        kwargs = {}
+        # Update with instance-specific values
+        for key, value in self.__default_kwargs__().items():
+            kwargs[key] = self.__getattribute__(key)
+            # if hasattr(self, key):
+            #     kwargs[key] = self.__getattribute__(key)
+            # else:
+            #     kwargs[key] = value                                   # todo: see if this is stil a valid scenario
+        return kwargs
+
+
+    def __locals__(self):
+        """Return a dictionary of the current instance's attribute values."""
+        kwargs = self.__kwargs__()
+
+        if not isinstance(vars(self), types.FunctionType):
+            for k, v in vars(self).items():
+                if not isinstance(v, types.FunctionType) and not isinstance(v,classmethod):
+                    if k.startswith('__') is False:
+                        kwargs[k] = v
+        return kwargs
+
+    @classmethod
+    def __schema__(cls):
+        return cls.__annotations__
+
+    # global methods added to any class that base classes this
+    # todo: see if there should be a prefix on these methods, to make it easier to spot them
+    #       of if these are actually that useful that they should be added like this
+    def json(self):
+        return self.serialize_to_dict()
+
+    def merge_with(self, target):
+        original_attrs = {k: v for k, v in self.__dict__.items() if k not in target.__dict__}       # Store the original attributes of self that should be retained.
+        self.__dict__ = target.__dict__                                                             # Set the target's __dict__ to self, now self and target share the same __dict__.
+        self.__dict__.update(original_attrs)                                                        # Reassign the original attributes back to self.
+        return self
+
+    # def locked(self, value=True):                                   # todo: figure out best way to do this (maybe???)
+    #     self.__lock_attributes__ = value                            #     : update, with the latest changes were we don't show internals on __locals__() this might be a good way to do this
+    #     return self
+
+    def reset(self):
+        for k,v in self.__cls_kwargs__().items():
+            setattr(self, k, v)
+
+    def update_from_kwargs(self, **kwargs):
+        """Update instance attributes with values from provided keyword arguments."""
+        for key, value in kwargs.items():
+            if value is not None:
+                if value_type_matches_obj_annotation_for_attr(self, key, value) is False:
+                    raise Exception(f"Invalid type for attribute '{key}'. Expected '{self.__annotations__.get(key)}' but got '{type(value)}'")
+                setattr(self, key, value)
+        return self
+
+
+    def deserialize_from_dict(self, data):
+        for key, value in data.items():
+            if hasattr(self, key) and isinstance(getattr(self, key), Kwargs_To_Self):
+                getattr(self, key).deserialize_from_dict(value)                         # Recursive call for complex nested objects
+            else:
+                if obj_is_attribute_annotation_of_type(self, key, EnumType):            # handle the case when the value is an Enum
+                    enum_type = getattr(self, '__annotations__').get(key)
+                    if type(value) is not enum_type:                                    # if the value is not already of the target type
+                        value = enum_from_value(enum_type, value)                       # try to resolve the value into the enum
+
+                setattr(self, key, value)                                               # Direct assignment for primitive types and other structures
+        return self
+
+    def serialize_to_dict(self):                        # todo: see if we need this method or if the .json() is enough
+        return serialize_to_dict(self)
+
+    def print(self):
+        pprint(serialize_to_dict(self))
+
+    @classmethod
+    def from_json(cls, json_data):
+        if type(json_data) is str:
+            json_data = json_parse(json_data)
+        if json_data:                                           # if there is no data or is {} then don't create an object (since this could be caused by bad data being provided)
+            return cls().deserialize_from_dict(json_data)
+        return None
+
+# todo: see if it is possible to add recursive protection to this logic
+def serialize_to_dict(obj):
+    if isinstance(obj, (str, int, float, bool, bytes, Decimal)) or obj is None:
+        return obj
+    elif isinstance(obj, Enum):
+        return obj.name
+    elif isinstance(obj, list):
+        return [serialize_to_dict(item) for item in obj]
+    elif isinstance(obj, dict):
+        return {key: serialize_to_dict(value) for key, value in obj.items()}
+    elif hasattr(obj, "__dict__"):
+        data = {}                                           # todo: look at a more advanced version which saved the type of the object, for example with {'__type__': type(obj).__name__}
+        for key, value in obj.__dict__.items():
+            data[key] = serialize_to_dict(value)  # Recursive call for complex types
+        return data
+    else:
+        raise TypeError(f"Type {type(obj)} not serializable")

osbot_utils/base_classes/Type_Safe__List.py

@@ -0,0 +1,14 @@
+class Type_Safe__List(list):
+
+    def __init__(self, expected_type, *args):
+        super().__init__(*args)
+        self.expected_type = expected_type
+
+    def __repr__(self):
+        return f"list[{self.expected_type.__name__}] with {len(self)} elements"
+
+    def append(self, item):
+        if not isinstance(item, self.expected_type):
+            raise TypeError(f"In Type_Safe__List: Invalid type for item: Expected '{self.expected_type.__name__}', but got '{type(item).__name__}'")
+        super().append(item)
+

osbot_utils/context_managers/capture_duration.py

@@ -0,0 +1,33 @@
+from osbot_utils.utils.Misc import timestamp_utc_now
+
+
+class capture_duration():
+    def __init__(self):
+        self.duration        = None
+        self.start_timestamp = None
+        self.end_timestamp   = None
+        self.seconds         = None
+
+    def __enter__(self):
+        self.start_timestamp = timestamp_utc_now()
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        self.end_timestamp  = timestamp_utc_now()
+        self.duration       = self.end_timestamp - self.start_timestamp
+        self.seconds        = round(self.duration / 1000, 3)                # Duration in seconds (rounded to the 3 digits)
+        return False                                                        # ensures that any exceptions that happened are rethrown
+
+    def data(self):
+        return dict(start = self.start_timestamp, end = self.end_timestamp, seconds = self.seconds)
+
+    def print(self):
+        print()
+        print(f'action took: {self.seconds} seconds')
+
+class print_duration(capture_duration):
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        result = super().__exit__(exc_type, exc_val, exc_tb)
+        self.print()
+        return result

osbot_utils/decorators/classes/singleton.py

@@ -0,0 +1,9 @@
+
+def singleton(cls):
+    assert type(cls) == type             # make sure the singleton decorator was added to class/type (vs a function)
+    instances = {}
+    def get_instance(*args, **kwargs):
+        if cls not in instances:
+            instances[cls] = cls(*args, **kwargs)
+        return instances[cls]
+    return get_instance

osbot_utils/decorators/lists/filter_list.py

@@ -0,0 +1,12 @@
+from functools import wraps
+
+def filter_list(function):
+    @wraps(function)
+    def wrapper(*args, **kwargs):
+        only_show = kwargs.pop('only_show', None)                   # Directly extract and remove 'only_show' from kwargs if present
+        values    = function(*args, **kwargs)                       # Call the decorated function
+        if only_show:                                               # Filter the list of dictionaries to only include specified keys
+            return [{key: item[key] for key in only_show if key in item} for item in values]
+        return values
+
+    return wrapper

osbot_utils/decorators/lists/group_by.py

@@ -0,0 +1,21 @@
+#todo: refactor with index_by
+from functools import wraps
+
+
+def group_by(function):                                 # returns the list provided grouped by the key provided in group_by
+    @wraps(function)
+    def wrapper(*args,**kwargs):
+        key = None
+        if 'group_by' in kwargs:
+            key = kwargs.get('group_by')
+            del kwargs['group_by']
+        values = function(*args,**kwargs)
+        if key:
+            results = {}
+            for item in values:
+                value = item.get(key)
+                if results.get(value) is None: results[value] = []
+                results[value].append(item)
+            return results
+        return values
+    return wrapper

osbot_utils/decorators/lists/index_by.py

@@ -0,0 +1,27 @@
+# todo: find way to also allow the used of function().index_by(key) to working
+#     : maybe using Fluent_List
+from functools import wraps
+
+from osbot_utils.fluent.Fluent_Dict import Fluent_Dict
+
+
+def index_by(function):                                 # returns the list provided indexed by the key provided in index_by
+    def apply(key, values):
+        if key:
+            results = {}
+            for item in values:
+                if type(item) is dict:
+                    results[item.get(key)] = item
+            return Fluent_Dict(results)
+        return values
+
+    @wraps(function)
+    def wrapper(*args,**kwargs):
+        key = None
+        if 'index_by' in kwargs:
+            key = kwargs.get('index_by')
+            del kwargs['index_by']
+        values = function(*args,**kwargs)
+
+        return apply(key,values)
+    return wrapper

osbot_utils/decorators/methods/cache.py

@@ -0,0 +1,19 @@
+from functools import wraps
+from typing import Any, Callable, TypeVar
+
+T = TypeVar('T', bound=Callable[..., Any])
+
+def cache(function: T) -> T:
+    """
+    Use this decorator when wanting to cache a value for all executions of the current process and want to preserve the type completion
+    which the one from  "from functools import cache" doesn't
+    note: that this will cache only one value per function (regardless of the values of *args,**kwargs).
+          if you have multiple params that should be cached separately, use the @cache_on_self decorator (or the native @cache from functools)
+    """
+    @wraps(function)
+    def wrapper(*args,**kwargs):
+        cache_id= f'osbot_cache_return_value__{function.__name__}'
+        if hasattr(function, cache_id) is False:                     # check if return_value has been set
+            setattr(function, cache_id,  function(*args,**kwargs))   # invoke function and capture the return value
+        return getattr(function, cache_id)                           # return the return value
+    return wrapper