osbot-utils 1.30.0__py3-none-any.whl → 1.32.0__py3-none-any.whl

osbot_utils/base_classes/Kwargs_To_Self.py

@@ -1,304 +1,4 @@
-# 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 sys
-import types
-import typing
-from decimal                                    import Decimal
-from enum                                       import Enum, EnumMeta
-from typing                                     import List
-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
+from osbot_utils.base_classes.Type_Safe import Type_Safe
 
-# Backport implementations of get_origin and get_args for Python 3.7
-if sys.version_info < (3, 8):
-    def get_origin(tp):
-        if isinstance(tp, typing._GenericAlias):
-            return tp.__origin__
-        elif tp is typing.Generic:
-            return typing.Generic
-        else:
-            return None
-
-    def get_args(tp):
-        if isinstance(tp, typing._GenericAlias):
-            return tp.__args__
-        else:
-            return ()
-else:
-    from typing import get_origin, get_args
-
-if sys.version_info >= (3, 10):
-    NoneType = types.NoneType
-else:
-    NoneType = type(None)
-
-immutable_types = (bool, int, float, complex, str, tuple, frozenset, bytes, 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:
-
-    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 not hasattr(self, '__annotations__'):                    # can't do type safety checks if the class does not have annotations
-            return super().__setattr__(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
-
-            if hasattr(base_cls,'__annotations__'):  # can only do type safety checks if the class does not have annotations
-                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 var_type is typing.Set:                              # todo: refactor the dict, set and list logic, since they are 90% the same
-            return set()
-        if get_origin(var_type) is set:
-            return set()                                        # todo: add Type_Safe__Set
-
-        if var_type is typing.Dict:
-            return {}
-        if get_origin(var_type) is dict:
-            return {}                                           # todo: add Type_Safe__Dict
-
-        if var_type is typing.List:
-            return []  # handle case when List was used with no type information provided
-        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
-            if hasattr(base_cls,'__annotations__'):  # can only do type safety checks if the class does not have 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):
-        if hasattr(cls,'__annotations__'):  # can only do type safety checks if the class does not have annotations
-            return cls.__annotations__
-        return {}
-
-    # 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 hasattr(self,'__annotations__'):  # can only do type safety checks if the class does not have annotations
-                    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 hasattr(self, '__annotations__'):  # can only do type safety checks if the class does not have annotations
-                    if obj_is_attribute_annotation_of_type(self, key, EnumMeta):            # 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) or 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")
+# todo: refactor all of Kwargs_To_Self to use Type_Safe
+Kwargs_To_Self = Type_Safe

osbot_utils/base_classes/Type_Safe.py

@@ -1,6 +1,301 @@
-from osbot_utils.base_classes.Kwargs_To_Self import Kwargs_To_Self
+# 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 sys
+import types
+import typing
+from decimal                                    import Decimal
+from enum                                       import Enum, EnumMeta
+from typing                                     import List
+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, \
+    convert_dict_to_value_from_obj_annotation
 
-# todo: refactor all of Kwargs_To_Self into this class (in a way to minimize the side effects, since
-#        Kwargs_To_Self is used in many places in the codebase)
+# Backport implementations of get_origin and get_args for Python 3.7
+if sys.version_info < (3, 8):
+    def get_origin(tp):
+        if isinstance(tp, typing._GenericAlias):
+            return tp.__origin__
+        elif tp is typing.Generic:
+            return typing.Generic
+        else:
+            return None
 
-Type_Safe = Kwargs_To_Self
+    def get_args(tp):
+        if isinstance(tp, typing._GenericAlias):
+            return tp.__args__
+        else:
+            return ()
+else:
+    from typing import get_origin, get_args
+
+if sys.version_info >= (3, 10):
+    NoneType = types.NoneType
+else:
+    NoneType = type(None)
+
+immutable_types = (bool, int, float, complex, str, tuple, frozenset, bytes, 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 Type_Safe:
+
+    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 ValueError(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 not hasattr(self, '__annotations__'):                    # can't do type safety checks if the class does not have annotations
+            return super().__setattr__(name, value)
+
+        if value is not None:
+            if type(value) is dict:
+                value = convert_dict_to_value_from_obj_annotation(self, name, value)
+            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 ValueError(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 ValueError(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
+
+            if hasattr(base_cls,'__annotations__'):  # can only do type safety checks if the class does not have annotations
+                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 ValueError(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 ValueError(exception_message)
+            if include_base_classes is False:
+                break
+        return kwargs
+
+    @classmethod
+    def __default__value__(cls, var_type):
+        if var_type is typing.Set:                              # todo: refactor the dict, set and list logic, since they are 90% the same
+            return set()
+        if get_origin(var_type) is set:
+            return set()                                        # todo: add Type_Safe__Set
+
+        if var_type is typing.Dict:
+            return {}
+        if get_origin(var_type) is dict:
+            return {}                                           # todo: add Type_Safe__Dict
+
+        if var_type is typing.List:
+            return []  # handle case when List was used with no type information provided
+        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
+            if hasattr(base_cls,'__annotations__'):  # can only do type safety checks if the class does not have 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):
+        if hasattr(cls,'__annotations__'):  # can only do type safety checks if the class does not have annotations
+            return cls.__annotations__
+        return {}
+
+    # 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 hasattr(self,'__annotations__'):  # can only do type safety checks if the class does not have annotations
+                    if value_type_matches_obj_annotation_for_attr(self, key, value) is False:
+                        raise ValueError(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), Type_Safe):
+                getattr(self, key).deserialize_from_dict(value)                         # Recursive call for complex nested objects
+            else:
+                if hasattr(self, '__annotations__'):  # can only do type safety checks if the class does not have annotations
+                    if obj_is_attribute_annotation_of_type(self, key, EnumMeta):            # 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) or 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/testing/Catch.py

@@ -42,7 +42,7 @@ class Catch:
         if self.expected_error:
             self.assert_error_is(self.expected_error)
         if self.expect_exception and exception_type is None:
-            raise Exception(f'Expected exception: {self.expected_error} but no exception was raised')
+            raise ValueError(f'Expected exception: {self.expected_error} but no exception was raised')
         if self.catch_exception:
             return True     # returning true here will prevent the exception to be propagated (which is the objective of this class :) )
         return False

osbot_utils/utils/Env.py

@@ -6,14 +6,28 @@ from osbot_utils.utils.Files    import all_parent_folders, file_exists
 from osbot_utils.utils.Misc     import list_set
 from osbot_utils.utils.Str      import strip_quotes
 
-def env__home_root():                           # todo: this should be refatored to be env__home__is__root
+
+def env__home():
+    return get_env('HOME', '')
+
+def env__home__is__root():
     return os.getenv('HOME') == '/root'
 
-def env__terminal_xterm():                      # todo: this should be refatored to be env__terminal__is__xterm
+def env__old_pwd():
+    return get_env('OLDPWD', '')
+
+def env__pwd():
+    return get_env('PWD', '')
+
+def env__old_pwd__remove(value):
+    return value.replace(env__old_pwd(), '')
+
+def env__terminal__is__xterm():
     return os.getenv('TERM') == 'xterm'
 
-def env__not_terminal_xterm():
-    return not env__terminal_xterm()
+def env__terminal__is_not__xterm():
+    return not env__terminal__is__xterm()
+
 
 def platform_darwin():
     return platform == 'darwin'
@@ -21,6 +35,10 @@ def platform_darwin():
 def env_value(var_name):
     return env_vars().get(var_name, None)
 
+def env_var_set(var_name):
+    value = os.getenv(var_name)
+    return value is not None and value != ''
+
 def env_vars_list():
     return list_set(env_vars())
 
@@ -109,6 +127,6 @@ def unload_dotenv(dotenv_path=None):
                 env_unload_from_file(env_path)                      # Process it
                 break                                               # Stop after unloading the first .env file
 
-
-env_load = load_dotenv
-get_env  = os.getenv
+is_env_var_set = env_var_set
+env_load       = load_dotenv
+get_env        = os.getenv

osbot_utils/utils/Files.py

@@ -340,6 +340,8 @@ class Files:
     def parent_folder_combine(file, path):
         return Files.path_combine(os.path.dirname(file),path)
 
+
+
     @staticmethod
     def pickle_save_to_file(object_to_save, path=None):
         path = path or temp_file(extension=".pickle")
@@ -491,12 +493,26 @@ def folders_names_in_folder(target):
     folders = folders_in_folder(target)
     return folders_names(folders)
 
+def path_combine_safe(base_path, file_location, raise_exception=False):                                  # handle possible directory transversal attacks
+    full_path            = os.path.join(base_path, file_location)                                       # Combine and normalize paths
+    normalised_base_path = os.path.normpath(base_path)
+    normalised_full_path = os.path.normpath(full_path)
+
+    if os.path.commonpath([normalised_base_path, normalised_full_path]) == normalised_base_path:        # Check for directory traversal
+        return normalised_full_path
+    if raise_exception:
+        raise ValueError("Invalid file location: directory traversal attempt detected.")
+    return None
+
 def parent_folder_create(target):
     return folder_create(parent_folder(target))
 
 def parent_folder_exists(target):
     return folder_exists(parent_folder(target))
 
+def parent_folder_name(target):
+    return folder_name(parent_folder(target))
+
 def parent_folder_not_exists(target):
     return parent_folder_exists(target) is False
 

osbot_utils/utils/Http.py

@@ -22,6 +22,13 @@ def current_host_online(url_to_use=URL_CHECK_HOST_ONLINE):
 def dns_ip_address(host):
     return socket.gethostbyname(host)
 
+def is_url_online(target):
+    try:
+        http_request(target, method='HEAD')
+        return True
+    except:
+        return False
+
 def is_port_open(host, port, timeout=0.5):
     return port_is_open(host=host, port=port, timeout=timeout)
 

osbot_utils/utils/Objects.py

@@ -69,6 +69,9 @@ def base_classes(cls):
         target = type(cls)
     return type_base_classes(target)
 
+def base_classes_names(cls):
+    return [cls.__name__ for cls in base_classes(cls)]
+
 def class_functions_names(target):
     return list_set(class_functions(target))
 
@@ -89,6 +92,17 @@ def class_full_name(target):
         type_name   = type_target.__name__
         return f'{type_module}.{type_name}'
 
+def convert_dict_to_value_from_obj_annotation(target, attr_name, value):
+    if target is not None and attr_name is not None:
+        if hasattr(target, '__annotations__'):
+            obj_annotations  = target.__annotations__
+            if hasattr(obj_annotations,'get'):
+                attribute_annotation = obj_annotations.get(attr_name)
+                if 'Type_Safe' in base_classes_names(attribute_annotation):
+                    return attribute_annotation(**value)
+    return value
+
+
 def default_value(target : type):
     try:
         return target()                 #  try to create the object using the default constructor

osbot_utils/version

@@ -1 +1 @@
-v1.30.0
+v1.32.0

{osbot_utils-1.30.0.dist-info → osbot_utils-1.32.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: osbot_utils
-Version: 1.30.0
+Version: 1.32.0
 Summary: OWASP Security Bot - Utils
 Home-page: https://github.com/owasp-sbot/OSBot-Utils
 License: MIT
@@ -22,7 +22,7 @@ Description-Content-Type: text/markdown
 
 Powerful Python util methods and classes that simplify common apis and tasks.
 
-![Current Release](https://img.shields.io/badge/release-v1.30.0-blue)
+![Current Release](https://img.shields.io/badge/release-v1.32.0-blue)
 [![codecov](https://codecov.io/gh/owasp-sbot/OSBot-Utils/graph/badge.svg?token=GNVW0COX1N)](https://codecov.io/gh/owasp-sbot/OSBot-Utils)
 
 

{osbot_utils-1.30.0.dist-info → osbot_utils-1.32.0.dist-info}/RECORD

@@ -1,8 +1,8 @@
 osbot_utils/__init__.py,sha256=DdJDmQc9zbQUlPVyTJOww6Ixrn9n4bD3ami5ItQfzJI,16
 osbot_utils/base_classes/Cache_Pickle.py,sha256=kPCwrgUbf_dEdxUz7vW1GuvIPwlNXxuRhb-H3AbSpII,5884
 osbot_utils/base_classes/Kwargs_To_Disk.py,sha256=HHoy05NC_w35WcT-OnSKoSIV_cLqaU9rdjH0_KNTM0E,1096
-osbot_utils/base_classes/Kwargs_To_Self.py,sha256=zahQ344JF13t4UO7xfnaSrcWPTXn052rMsjTFLpDunE,17450
-osbot_utils/base_classes/Type_Safe.py,sha256=PHBIXCRumEnXGognc1qKDJzcAK_vAsylEWfREG5nvjY,260
+osbot_utils/base_classes/Kwargs_To_Self.py,sha256=weFNsBfBNV9W_qBkN-IdBD4yYcJV_zgTxBRO-ZlcPS4,141
+osbot_utils/base_classes/Type_Safe.py,sha256=62eV2AnIAN-7VshhOpvWw0v_DZHJucLq10VQHjgCfX8,17089
 osbot_utils/base_classes/Type_Safe__List.py,sha256=-80C9OhsK6iDR2dAG8yNLAZV0qg5x3faqvSUigFCMJw,517
 osbot_utils/base_classes/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 osbot_utils/context_managers/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
@@ -240,7 +240,7 @@ osbot_utils/helpers/trace/Trace_Call__Stats.py,sha256=gmiotIrOXe2ssxodzQQ56t8eGT
 osbot_utils/helpers/trace/Trace_Call__View_Model.py,sha256=a40nn6agCEMd2ecsJ93n8vXij0omh0D69QilqwmN_ao,4545
 osbot_utils/helpers/trace/Trace_Files.py,sha256=SNpAmuBlSUS9NyVocgZ5vevzqVaIqoh622yZge3a53A,978
 osbot_utils/helpers/trace/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-osbot_utils/testing/Catch.py,sha256=r8aBtJYpZljEJGsthqchavHNPNhusqc-U4ljojvBO7I,2228
+osbot_utils/testing/Catch.py,sha256=HdNoKnrPBjvVj87XYN-Wa1zpo5z3oByURT6TKbd5QpQ,2229
 osbot_utils/testing/Duration.py,sha256=iBrczAuw6j3jXtG7ZPraT0PXbCILEcCplJbqei96deA,2217
 osbot_utils/testing/Hook_Method.py,sha256=A1t6WQzeR9hv5ddaz7ILtvKyJpRrRBRnftB-zgcIQpA,4126
 osbot_utils/testing/Log_To_Queue.py,sha256=pZQ7I1ne-H365a4WLS60oAD-B16pxIZO4suvCdaTW8U,1703
@@ -265,17 +265,17 @@ osbot_utils/utils/Assert.py,sha256=u9XLgYn91QvNWZGyPi29SjPJSXRHlm9andIn3NJEVog,1
 osbot_utils/utils/Call_Stack.py,sha256=MAq_0vMxnbeLfCe9qQz7GwJYaOuXpt3qtQwN6wiXsU0,6595
 osbot_utils/utils/Csv.py,sha256=oHLVpjRJqrLMz9lubMCNEoThXWju5rNTprcwHc1zq2c,1012
 osbot_utils/utils/Dev.py,sha256=HibpQutYy_iG8gGV8g1GztxNN4l29E4Bi7UZaVL6-L8,1203
-osbot_utils/utils/Env.py,sha256=Pbel6npitij9zag6SsWdPVH2j1BTZjxnwOR1vLiIyMo,5248
+osbot_utils/utils/Env.py,sha256=243O6ENzaRjHXp8DIHUuv4Wfk-zHTE18KZr0cU8uWyo,5474
 osbot_utils/utils/Exceptions.py,sha256=KyOUHkXQ_6jDTq04Xm261dbEZuRidtsM4dgzNwSG8-8,389
-osbot_utils/utils/Files.py,sha256=bZFvjyC4TAmFH6RSp3Xvj_xBxfybCT2cE7x2qNTQmeE,20834
+osbot_utils/utils/Files.py,sha256=RHbxq8AVdGT9S-OrxEWhNEOhbIrHDRU1UbGB1O05Ga8,21615
 osbot_utils/utils/Functions.py,sha256=0E6alPJ0fJpBiJgFOWooCOi265wSRyxxXAJ5CELBnso,3498
-osbot_utils/utils/Http.py,sha256=Z8V149M2HDrKBoXkDD5EXgqTGx6vQoUqXugXK__wcuw,4572
+osbot_utils/utils/Http.py,sha256=WlXEfgT_NaiDVD7vCDUxy_nOm5Qf8x_L0A3zd8B5tX8,4706
 osbot_utils/utils/Int.py,sha256=PmlUdU4lSwf4gJdmTVdqclulkEp7KPCVUDO6AcISMF4,116
 osbot_utils/utils/Json.py,sha256=UNaBazuH1R40fsHjpjuK8kmAANmUHoK9Q0PUeYmgPeY,6254
 osbot_utils/utils/Json_Cache.py,sha256=mLPkkDZN-3ZVJiDvV1KBJXILtKkTZ4OepzOsDoBPhWg,2006
 osbot_utils/utils/Lists.py,sha256=CLEjgZwAixJAFlubWEKjnUUhUN85oqvR7UqExVW7rdY,5502
 osbot_utils/utils/Misc.py,sha256=ljscBemI5wOhfkl1BVpsqshacTOCKkOisV4er9xPCWM,16640
-osbot_utils/utils/Objects.py,sha256=WFH3oeXR1CU03oyzXfcIlktcoXQuKw9cIJn8xTs02AE,14654
+osbot_utils/utils/Objects.py,sha256=qAWNLISL-gYTl1Ihj4fBSZ9I6n-p-YPUhRZu9YQwqWQ,15235
 osbot_utils/utils/Png.py,sha256=V1juGp6wkpPigMJ8HcxrPDIP4bSwu51oNkLI8YqP76Y,1172
 osbot_utils/utils/Process.py,sha256=lr3CTiEkN3EiBx3ZmzYmTKlQoPdkgZBRjPulMxG-zdo,2357
 osbot_utils/utils/Python_Logger.py,sha256=tx8N6wRKL3RDHboDRKZn8SirSJdSAE9cACyJkxrThZ8,12792
@@ -286,8 +286,8 @@ osbot_utils/utils/Toml.py,sha256=dqiegndCJF7V1YT1Tc-b0-Bl6QWyL5q30urmQwMXfMQ,140
 osbot_utils/utils/Version.py,sha256=Ww6ChwTxqp1QAcxOnztkTicShlcx6fbNsWX5xausHrg,422
 osbot_utils/utils/Zip.py,sha256=t9txUxJzLBEHot6WJwF0iTTUQ1Gf_V2pVwsWzAqw_NU,12163
 osbot_utils/utils/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-osbot_utils/version,sha256=rySeFYh2TX0iwzR0MwppiJ1yllnTK1JQxMRPUGe8DS0,8
-osbot_utils-1.30.0.dist-info/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
-osbot_utils-1.30.0.dist-info/METADATA,sha256=XspSKWOcbtP6-hGL3r9N7NmMZn7n91lK68mf8vPxetI,1266
-osbot_utils-1.30.0.dist-info/WHEEL,sha256=sP946D7jFCHeNz5Iq4fL4Lu-PrWrFsgfLXbbkciIZwg,88
-osbot_utils-1.30.0.dist-info/RECORD,,
+osbot_utils/version,sha256=bXbruCHeH-hb0hIQlj3n7tV2_vXn3ypQsk6TaP1y0Zk,8
+osbot_utils-1.32.0.dist-info/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
+osbot_utils-1.32.0.dist-info/METADATA,sha256=B4r-4DcyCbnaGO-x7uJIrie537cYmE8Ux4hGFen0Wtc,1266
+osbot_utils-1.32.0.dist-info/WHEEL,sha256=sP946D7jFCHeNz5Iq4fL4Lu-PrWrFsgfLXbbkciIZwg,88
+osbot_utils-1.32.0.dist-info/RECORD,,