osbot-utils 2.11.0__py3-none-any.whl → 2.12.0__py3-none-any.whl

osbot_utils/type_safe/shared/Type_Safe__Cache.py

@@ -0,0 +1,143 @@
+import inspect
+from weakref                                                    import WeakKeyDictionary
+from osbot_utils.type_safe.shared.Type_Safe__Not_Cached         import type_safe_not_cached
+from osbot_utils.type_safe.shared.Type_Safe__Shared__Variables  import IMMUTABLE_TYPES
+
+
+class Type_Safe__Cache:
+
+    _cls__annotations_cache  : WeakKeyDictionary
+    _cls__immutable_vars     : WeakKeyDictionary
+    _cls__kwargs_cache       : WeakKeyDictionary
+    _obj__annotations_cache  : WeakKeyDictionary
+    _type__get_origin_cache  : WeakKeyDictionary
+    _mro_cache               : WeakKeyDictionary
+    _valid_vars_cache        : WeakKeyDictionary
+
+    cache__miss__cls__annotations   : int = 0
+    cache__miss__cls__kwargs        : int = 0
+    cache__miss__cls__immutable_vars: int = 0
+    cache__miss__obj__annotations   : int = 0
+    cache__miss__type__get_origin   : int = 0
+    cache__miss__mro                : int = 0
+    cache__miss__valid_vars         : int = 0
+
+    cache__hit__cls__annotations    : int  = 0
+    cache__hit__cls__kwargs         : int  = 0
+    cache__hit__cls__immutable_vars : int  = 0
+    cache__hit__obj__annotations    : int  = 0
+    cache__hit__type__get_origin    : int  = 0
+    cache__hit__mro                 : int  = 0
+    cache__hit__valid_vars          : int  = 0
+    skip_cache                      : bool = False
+
+
+    # Caching system for Type_Safe methods
+    def __init__(self):
+        self._cls__annotations_cache  = WeakKeyDictionary()                                        # Cache for class annotations
+        self._cls__immutable_vars     = WeakKeyDictionary()                                        # Cache for class immutable vars
+        self._cls__kwargs_cache       = WeakKeyDictionary()                                        # Cache for class kwargs
+        self._obj__annotations_cache  = WeakKeyDictionary()                                        # Cache for object annotations
+        self._type__get_origin_cache  = WeakKeyDictionary()                                        # Cache for tp (type) get_origin results
+        self._mro_cache               = WeakKeyDictionary()                                        # Cache for Method Resolution Order
+        self._valid_vars_cache        = WeakKeyDictionary()
+
+    def get_cls_kwargs(self, cls):
+        cls_kwargs = self._cls__kwargs_cache.get(cls)
+
+        if cls_kwargs is None:
+            self.cache__miss__cls__kwargs += 1
+        else:
+            self.cache__hit__cls__kwargs += 1
+        return cls_kwargs
+
+    def get_obj_annotations(self, target):
+        if target is None:
+            return {}
+        annotations_key = target.__class__
+        annotations = self._obj__annotations_cache.get(annotations_key)                          # this is a more efficient cache retrieval pattern (we only get the data from the dict once)
+        if self.skip_cache or annotations is None:
+            annotations = dict(type_safe_not_cached.all_annotations(target).items())
+            self._obj__annotations_cache[annotations_key] = annotations
+            self.cache__miss__obj__annotations += 1
+        else:
+            self.cache__hit__obj__annotations += 1
+        return annotations
+
+    def get_class_annotations(self, cls):
+        annotations = self._cls__annotations_cache.get(cls)                          # this is a more efficient cache retrieval pattern (we only get the data from the dict once)
+        if self.skip_cache or annotations is None:                                                     # todo: apply this to the other cache getters
+            annotations = type_safe_not_cached.all_annotations__in_class(cls).items()
+            self._cls__annotations_cache[cls] = annotations
+            self.cache__miss__cls__annotations +=1
+        else:
+            self.cache__hit__cls__annotations += 1
+        return annotations
+
+    def get_class_immutable_vars(self, cls):
+        immutable_vars = self._cls__immutable_vars.get(cls)
+        if self.skip_cache or immutable_vars is None:
+            annotations                            = self.get_class_annotations(cls)
+            immutable_vars                         = {key: value for key, value in annotations if value in IMMUTABLE_TYPES}
+            self._cls__immutable_vars[cls]         = immutable_vars
+            self.cache__miss__cls__immutable_vars += 1
+        else:
+            self.cache__hit__cls__immutable_vars   += 1
+        return immutable_vars
+
+    def get_class_mro(self, cls):
+        if self.skip_cache or cls not in self._mro_cache:
+            self._mro_cache[cls]   = inspect.getmro(cls)
+            self.cache__miss__mro += 1
+        else:
+            self.cache__hit__mro   += 1
+        return self._mro_cache[cls]
+
+
+    def get_origin(self, var_type):                                                             # Cache expensive get_origin calls
+        if self.skip_cache or var_type not in self._type__get_origin_cache:
+            origin = type_safe_not_cached.get_origin(var_type)
+            try:                                                                                # this is needed for the edge case when we can't create a key from the var_type in WeakKeyDictionary (see test test__regression__type_safe_is_not_enforced_on_dict_and_Dict for an example)
+                self._type__get_origin_cache[var_type] = origin
+            except TypeError:
+                pass
+            self.cache__miss__type__get_origin    += 1
+        else:
+            origin = self._type__get_origin_cache[var_type]
+            self.cache__hit__type__get_origin      += 1
+        return origin
+
+    # todo: see if we have cache misses and invalid hits based on the validator (we might need more validator specific methods)
+    def get_valid_class_variables(self, cls, validator):
+        if self.skip_cache or cls not in self._valid_vars_cache:
+            valid_variables = {}
+            for name, value in vars(cls).items():
+                if not validator(name, value):
+                    valid_variables[name] = value
+            self._valid_vars_cache[cls]   = valid_variables
+            self.cache__miss__valid_vars += 1
+        else:
+            self.cache__hit__valid_vars  += 1
+        return self._valid_vars_cache[cls]
+
+    def set_cache__cls_kwargs(self, cls, kwargs):
+        if self.skip_cache is False:
+            self._cls__kwargs_cache[cls] = kwargs
+        return kwargs
+
+    def print_cache_hits(self):
+        print()
+        print("###### Type_Safe_Cache Hits ########")
+        print()
+        print( "  cache name          | hits   | miss  |  size |")
+        print( "----------------------|--------|-------|-------|")
+        print(f"  annotations         | {self.cache__hit__cls__annotations   :5}  | {self.cache__miss__cls__annotations    :5} | {len(self._obj__annotations_cache) :5} |")
+        print(f"  cls__kwargs         | {self.cache__hit__cls__kwargs        :5}  | {self.cache__miss__cls__kwargs         :5} | {len(self._cls__kwargs_cache     ) :5} |")
+        print(f"  cls__immutable_vars | {self.cache__hit__cls__immutable_vars:5}  | {self.cache__miss__cls__immutable_vars :5} | {len(self._cls__immutable_vars   ) :5} |")
+        print(f"  obj__annotations    | {self.cache__hit__obj__annotations   :5}  | {self.cache__miss__obj__annotations    :5} | {len(self._obj__annotations_cache) :5} |")
+        print(f"  type__get_origin    | {self.cache__hit__type__get_origin   :5}  | {self.cache__miss__type__get_origin    :5} | {len(self._type__get_origin_cache) :5} |")
+        print(f"  mro                 | {self.cache__hit__mro                :5}  | { self.cache__miss__mro                :5} | {len(self._mro_cache             ) :5} |")
+        print(f"  valid_vars          | {self.cache__hit__valid_vars         :5}  | {self.cache__miss__valid_vars          :5} | {len(self._valid_vars_cache      ) :5} |")
+
+type_safe_cache = Type_Safe__Cache()
+

osbot_utils/type_safe/shared/Type_Safe__Convert.py

@@ -0,0 +1,46 @@
+from osbot_utils.type_safe.shared.Type_Safe__Cache import type_safe_cache
+from osbot_utils.utils.Objects                     import base_classes_names
+
+
+class Type_Safe__Convert:
+    def convert_dict_to_value_from_obj_annotation(self, target, attr_name, value):                    # todo: refactor this with code from convert_str_to_value_from_obj_annotation since it is mostly the same
+        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 convert_to_value_from_obj_annotation(self, target, attr_name, value):                             # todo: see the side effects of doing this for all ints and floats
+
+        from osbot_utils.helpers.Guid           import Guid
+        from osbot_utils.helpers.Timestamp_Now  import Timestamp_Now
+        from osbot_utils.helpers.Random_Guid    import Random_Guid
+        from osbot_utils.helpers.Safe_Id        import Safe_Id
+        from osbot_utils.helpers.Str_ASCII      import Str_ASCII
+
+        TYPE_SAFE__CONVERT_VALUE__SUPPORTED_TYPES = [Guid, Random_Guid, Safe_Id, Str_ASCII, Timestamp_Now]
+
+        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 attribute_annotation:
+                        origin = type_safe_cache.get_origin(attribute_annotation)                               # Add handling for Type[T] annotations
+                        if origin is type and isinstance(value, str):
+                            try:                                                                # Convert string path to actual type
+                                if len(value.rsplit('.', 1)) > 1:
+                                    module_name, class_name = value.rsplit('.', 1)
+                                    module = __import__(module_name, fromlist=[class_name])
+                                    return getattr(module, class_name)
+                            except (ValueError, ImportError, AttributeError) as e:
+                                raise ValueError(f"Could not convert '{value}' to type: {str(e)}")
+
+                        if attribute_annotation in TYPE_SAFE__CONVERT_VALUE__SUPPORTED_TYPES:          # for now hard-coding this to just these types until we understand the side effects
+                            return attribute_annotation(value)
+        return value
+
+type_safe_convert = Type_Safe__Convert()

osbot_utils/type_safe/shared/Type_Safe__Not_Cached.py

@@ -0,0 +1,24 @@
+from typing import get_origin
+
+class Type_Safe__Not_Cached:
+
+    def all_annotations(self, target):
+        annotations = {}
+        if hasattr(target.__class__, '__mro__'):
+            for base in reversed(target.__class__.__mro__):
+                if hasattr(base, '__annotations__'):
+                    annotations.update(base.__annotations__)
+        return annotations
+
+    def all_annotations__in_class(self, target):
+        annotations = {}
+        if hasattr(target, '__mro__'):
+            for base in reversed(target.__mro__):
+                if hasattr(base, '__annotations__'):
+                    annotations.update(base.__annotations__)
+        return annotations
+
+    def get_origin(self, var_type):
+        return get_origin(var_type)
+
+type_safe_not_cached = Type_Safe__Not_Cached()

osbot_utils/type_safe/shared/Type_Safe__Raise_Exception.py

@@ -0,0 +1,14 @@
+from osbot_utils.type_safe.shared.Type_Safe__Shared__Variables import IMMUTABLE_TYPES
+
+
+class Type_Safe__Raise_Exception:
+
+    def type_mismatch_error(self, var_name: str, expected_type: type, actual_type: type) -> None:                               # Raises formatted error for type validation failures
+        exception_message = f"Invalid type for attribute '{var_name}'. Expected '{expected_type}' but got '{actual_type}'"
+        raise ValueError(exception_message)
+
+    def immutable_type_error(self, var_name, var_type):
+        exception_message = f"variable '{var_name}' is defined as type '{var_type}' which is not supported by Type_Safe, with only the following immutable types being supported: '{IMMUTABLE_TYPES}'"
+        raise ValueError(exception_message)
+
+type_safe_raise_exception = Type_Safe__Raise_Exception()

osbot_utils/type_safe/shared/Type_Safe__Shared__Variables.py

@@ -0,0 +1,4 @@
+import types
+from enum import EnumMeta
+
+IMMUTABLE_TYPES = (bool, int, float, complex, str, bytes, types.NoneType, EnumMeta, type)

osbot_utils/type_safe/shared/Type_Safe__Validation.py

@@ -0,0 +1,246 @@
+import types
+import typing
+from enum                                                           import EnumMeta
+from typing                                                         import Any, Annotated, Optional, get_args, get_origin, ForwardRef, Type, Dict, _GenericAlias
+from osbot_utils.type_safe.shared.Type_Safe__Annotations            import type_safe_annotations
+from osbot_utils.type_safe.shared.Type_Safe__Cache                  import type_safe_cache
+from osbot_utils.type_safe.shared.Type_Safe__Shared__Variables      import IMMUTABLE_TYPES
+from osbot_utils.type_safe.shared.Type_Safe__Raise_Exception        import type_safe_raise_exception
+
+
+class Type_Safe__Validation:
+
+    def are_types_compatible_for_assigment(self, source_type, target_type):
+        import types
+        import typing
+
+        if isinstance(target_type, str):                                    # If the "target_type" is a forward reference (string), handle it here.
+            if target_type == source_type.__name__:                         # Simple check: does the string match the actual class name
+                return True
+        if source_type is target_type:
+            return True
+        if source_type is int and target_type is float:
+            return True
+        if target_type in source_type.__mro__:                              # this means that the source_type has the target_type has of its base types
+            return True
+        if target_type is callable:                                         # handle case where callable was used as the target type
+            if source_type is types.MethodType:                             #     and a method or function was used as the source type
+                return True
+            if source_type is types.FunctionType:
+                return True
+            if source_type is staticmethod:
+                return True
+        if target_type is typing.Any:
+            return True
+        return False
+
+    def are_types_magic_mock(self, source_type, target_type):
+        from unittest.mock import MagicMock
+        if isinstance(source_type, MagicMock):
+            return True
+        if isinstance(target_type, MagicMock):
+            return True
+        if source_type is MagicMock:
+            return True
+        if target_type is MagicMock:
+            return True
+        # if class_full_name(source_type) == 'unittest.mock.MagicMock':
+        #     return True
+        # if class_full_name(target_type) == 'unittest.mock.MagicMock':
+        #     return True
+        return False
+
+    def obj_is_type_union_compatible(self, var_type, compatible_types):
+        from typing import Union
+
+        origin = get_origin(var_type)
+        if isinstance(var_type, _GenericAlias) and origin is type:              # Add handling for Type[T]
+            return type in compatible_types                                     # Allow if 'type' is in compatible types
+        if origin is Union:                                                     # For Union types, including Optionals
+            args = get_args(var_type)                                           # Get the argument types
+            for arg in args:                                                    # Iterate through each argument in the Union
+                if not (arg in compatible_types or arg is type(None)):          # Check if the argument is either in the compatible_types or is type(None)
+                    return False                                                # If any arg doesn't meet the criteria, return False immediately
+            return True                                                         # If all args are compatible, return True
+        return var_type in compatible_types or var_type is type(None)           # Check for direct compatibility or type(None) for non-Union types
+
+
+    def check_if__type_matches__obj_annotation__for_union_and_annotated(self, target   : Any    ,    # Target object to check
+                                                                             attr_name : str    ,    # Attribute name
+                                                                             value     : Any    )\
+                                                                     -> Optional[bool]:          # Returns None if no match
+
+        from osbot_utils.helpers.python_compatibility.python_3_8 import Annotated
+        from typing                                              import Union, get_origin, get_args
+
+        value_type           = type(value)
+        attribute_annotation = type_safe_annotations.obj_attribute_annotation(target, attr_name)
+        origin               = get_origin(attribute_annotation)
+
+        if origin is Union:
+            return self.check_if__type_matches__union_type(attribute_annotation, value_type)
+
+        if origin is Annotated:
+            return self.check_if__type_matches__annotated_type(attribute_annotation, value)
+
+        return None
+
+    def check_if__value_is__special_generic_alias(self, value):
+        from typing import _SpecialGenericAlias                                     # todo see if there is a better way to do this since typing is showing as not having _SpecialGenericAlias (this is to handle case like List, Dict, etc...)
+        return value is not None and type(value) is not _SpecialGenericAlias
+
+    def check_if__type_matches__union_type(self, annotation : Any,                                      # Union type annotation
+                                                 value_type : Type
+                                           )               -> bool:                                     # True if type matches
+        from typing import get_args
+        args = get_args(annotation)
+        return value_type in args
+
+    def check_if__type_matches__annotated_type(self, annotation : Any,                                  # Annotated type annotation
+                                                     value      : Any                                   # Value to check
+                                               )               -> bool:                                 # True if type matches
+        from typing import get_args, get_origin
+        from typing import List, Dict, Tuple
+
+        args        = get_args(annotation)
+        base_type   = args[0]                                                        # First argument is base type
+        base_origin = get_origin(base_type)
+
+        if base_origin is None:                                                      # Handle non-container types
+            return isinstance(value, base_type)
+
+        if base_origin in (list, List):                                             # Handle List types
+            return self.check_if__type_matches__list_type(value, base_type)
+
+        if base_origin in (tuple, Tuple):                                           # Handle Tuple types
+            return self.check_if__type_matches__tuple_type(value, base_type)
+
+        if base_origin in (dict, Dict):                                             # Handle Dict types
+            return self.check_if__type_matches_dict_type(value, base_type)
+
+        return False
+
+    def check_if__type_matches__list_type(self, value     : Any,                                    # Value to check
+                                                base_type : Any                                     # List base type
+                                          )              -> bool:                                   # True if valid list type
+        if not isinstance(value, list):
+            return False
+
+        item_type = get_args(base_type)[0]
+        return all(isinstance(item, item_type) for item in value)
+
+    def check_if__type_matches__tuple_type(self, value     : Any,                                    # Value to check
+                                                 base_type : Any                                     # Tuple base type
+                                           )               -> bool:                                  # True if valid tuple type
+        if not isinstance(value, tuple):
+            return False
+
+        item_types = get_args(base_type)
+        return len(value) == len(item_types) and all(
+            isinstance(item, item_type)
+            for item, item_type in zip(value, item_types)
+        )
+
+    def check_if__type_matches_dict_type(self, value    : Any,  # Value to check
+                                               base_type : Any  # Dict base type
+                                         )              -> bool:                                   # True if valid dict type
+        if not isinstance(value, dict):
+            return False
+
+        key_type, value_type = get_args(base_type)
+        return all(isinstance(k, key_type) and isinstance(v, value_type)
+                  for k, v in value.items())                                                        # if it is not a Union or Annotated types just return None (to give an indication to the caller that the comparison was not made)
+
+    def check_if__type_matches__obj_annotation__for_attr(self, target,
+                                                               attr_name,
+                                                               value
+                                                         )              -> Optional[bool]:
+        annotations = type_safe_cache.get_obj_annotations(target)
+        attr_type   = annotations.get(attr_name)
+        if attr_type:
+            origin_attr_type = get_origin(attr_type)                                    # to handle when type definition contains a generic
+            if origin_attr_type is type:                                                # Add handling for Type[T]
+                type_arg = get_args(attr_type)[0]                                       # Get T from Type[T]
+                if type_arg == value:
+                    return True
+                if isinstance(type_arg, (str, ForwardRef)):                             # Handle forward reference
+                    type_arg = target.__class__                                         # If it's a forward reference, the target class should be the containing class
+                return isinstance(value, type) and issubclass(value, type_arg)          # Check that value is a type and is subclass of type_arg
+
+            if origin_attr_type is Annotated:                                           # if the type is Annotated
+                args             = get_args(attr_type)
+                origin_attr_type = args[0]
+
+            elif origin_attr_type is typing.Union:
+                args = get_args(attr_type)
+                if len(args)==2 and args[1] is type(None):          # todo: find a better way to do this, since this is handling an edge case when origin_attr_type is Optional (which is an shorthand for Union[X, None] )
+                    attr_type = args[0]
+                    origin_attr_type = get_origin(attr_type)
+
+            if origin_attr_type:
+                attr_type = origin_attr_type
+            value_type = type(value)
+            if type_safe_validation.are_types_compatible_for_assigment(source_type=value_type, target_type=attr_type):
+                return True
+            if type_safe_validation.are_types_magic_mock(source_type=value_type, target_type=attr_type):
+                return True
+            return value_type is attr_type
+        return None
+
+    # todo: add cache support to this method
+    def should_skip_type_check(self, var_type):                                                         # Determine if type checking should be skipped
+        origin = type_safe_cache.get_origin(var_type)                                                   # Use cached get_origin
+        return (origin is Annotated or
+                origin is type        )
+
+    def should_skip_var(self, var_name: str, var_value: Any) -> bool:                                   # Determines if variable should be skipped during MRO processing
+        if var_name.startswith('__'):                                                                   # skip internal variables
+            return True
+        if isinstance(var_value, types.FunctionType):                                                   # skip instance functions
+            return True
+        if isinstance(var_value, classmethod):                                                          # skip class methods
+            return True
+        if isinstance(var_value, property):                                                             # skip property descriptors
+            return True
+        return False
+
+    def validate_if_value_has_been_set(self, _self, annotations, name, value):
+        if hasattr(_self, name) and 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)}'")
+
+    def validate_if__types_are_compatible_for_assigment(self, name, current_type, expected_type):
+        if not type_safe_validation.are_types_compatible_for_assigment(current_type, expected_type):
+            type_safe_raise_exception.type_mismatch_error(name, expected_type, current_type)
+
+    def validate_type_compatibility(self, target      : Any             ,             # Target object to validate
+                                          annotations : Dict[str, Any]  ,             # Type annotations
+                                          name        : str             ,             # Attribute name
+                                          value       : Any                           # Value to validate
+                                   )                 -> None:                                           # Raises ValueError if invalid
+
+        direct_type_match = type_safe_validation.check_if__type_matches__obj_annotation__for_attr(target, name, value)
+        union_type_match = type_safe_validation.check_if__type_matches__obj_annotation__for_union_and_annotated(target, name, value)
+
+        is_invalid = (direct_type_match is False and union_type_match is None) or \
+                    (direct_type_match is None and union_type_match is False) or \
+                    (direct_type_match is False and union_type_match is False)
+
+        if is_invalid:
+            expected_type = annotations.get(name)
+            actual_type = type(value)
+            raise ValueError(f"Invalid type for attribute '{name}'. Expected '{expected_type}' but got '{actual_type}'")
+
+    # todo: see if need to add cache support to this method     (it looks like this method is not called very often)
+    def validate_type_immutability(self, var_name: str, var_type: Any) -> None:                         # Validates that type is immutable or in supported format
+        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
+            if self.obj_is_type_union_compatible(var_type, IMMUTABLE_TYPES) is False:                        # if var_type is not something like Optional[Union[int, str]]
+                if var_type not in IMMUTABLE_TYPES or type(var_type) not in IMMUTABLE_TYPES:
+                    if not isinstance(var_type, EnumMeta):
+                        type_safe_raise_exception.immutable_type_error(var_name, var_type)
+
+    def validate_variable_type(self, var_name, var_type, var_value):                                # Validate type compatibility
+        if var_type and not isinstance(var_value, var_type):
+            type_safe_raise_exception.type_mismatch_error(var_name, var_type, type(var_value))
+
+type_safe_validation = Type_Safe__Validation()

osbot_utils/type_safe/steps/Type_Safe__Step__Class_Kwargs.py

@@ -0,0 +1,110 @@
+from typing                                                          import Dict, Any, Type
+from osbot_utils.helpers.Random_Guid                                 import Random_Guid
+from osbot_utils.type_safe.shared.Type_Safe__Cache                   import Type_Safe__Cache, type_safe_cache
+from osbot_utils.type_safe.shared.Type_Safe__Shared__Variables       import IMMUTABLE_TYPES
+from osbot_utils.type_safe.shared.Type_Safe__Validation              import type_safe_validation
+from osbot_utils.type_safe.steps.Type_Safe__Step__Default_Value      import type_safe_step_default_value
+
+
+
+class Type_Safe__Step__Class_Kwargs:                                                     # Handles class-level keyword arguments processing
+
+    type_safe_cache : Type_Safe__Cache                                                   # Cache component reference
+
+    def __init__(self):
+        self.type_safe_cache = type_safe_cache                                           # Initialize with singleton cache
+
+    def get_cls_kwargs(self, cls                  : Type )\
+                    -> Dict[str, Any]:                                                   # Main entry point for getting class kwargs, returns dict of class kwargs
+
+        if not hasattr(cls, '__mro__'):                                                  # Handle non-class inputs
+            return {}
+
+        kwargs  = type_safe_cache.get_cls_kwargs(cls)                                    # see if we have cached data for this class
+
+        if kwargs is not None:
+            return kwargs
+        else:
+            kwargs = {}
+
+        base_classes = type_safe_cache.get_class_mro(cls)
+        for base_cls in base_classes:
+            self.process_mro_class  (base_cls, kwargs)                                  # Handle each class in MRO
+            self.process_annotations(cls, base_cls, kwargs)                             # Process its annotations
+
+        if self.is_kwargs_cacheable(cls, kwargs):                                            # if we can cache it (i.e. only IMMUTABLE_TYPES vars)
+            type_safe_cache.set_cache__cls_kwargs(cls, kwargs)                          #   cache it
+        # else:
+        #     pass                                                  # todo:: see how we can cache more the cases when the data is clean (i.e. default values)
+        return kwargs
+
+    def is_kwargs_cacheable(self, cls, kwargs: Dict[str, Any]) -> bool:
+        annotations = type_safe_cache.get_class_annotations(cls)
+        match      = all(isinstance(value, IMMUTABLE_TYPES) for value in kwargs.values())
+
+        if match:                                                                       # check for special cases that we can't cache (like Random_Guid)
+            if Random_Guid in list(dict(annotations).values()):                         # todo: need to add the other special cases (like Timestamp_Now)
+
+                return False
+        return match
+
+
+    def handle_undefined_var(self, cls      : Type            ,                         # Handle undefined class variables
+                                   kwargs   : Dict[str, Any] ,
+                                   var_name : str            ,
+                                   var_type : Type           )\
+                          -> None:
+        if var_name in kwargs:                                                          # Skip if already defined
+            return
+        var_value        = type_safe_step_default_value.default_value(cls, var_type)    # Get default value
+        kwargs[var_name] = var_value                                                    # Store in kwargs
+
+    def handle_defined_var(self, base_cls : Type ,                                      # Handle defined class variables
+                                 var_name : str  ,
+                                 var_type : Type )\
+                        -> None:
+        var_value = getattr(base_cls, var_name)                                         # Get current value
+        if var_value is None:                                                           # Allow None assignments
+            return
+
+        if type_safe_validation.should_skip_type_check(var_type):                       # Skip validation if needed
+            return
+
+        type_safe_validation.validate_variable_type    (var_name, var_type, var_value)  # Validate type
+        type_safe_validation.validate_type_immutability(var_name, var_type)             # Validate immutability
+
+    def process_annotation(self, cls      : Type           ,                            # Process single annotation
+                                 base_cls : Type           ,
+                                 kwargs   : Dict[str, Any] ,
+                                 var_name : str            ,
+                                 var_type : Type           )\
+                       -> None:
+        if not hasattr(base_cls, var_name):                                             # Handle undefined variables
+            self.handle_undefined_var(cls, kwargs, var_name, var_type)
+        else:                                                                           # Handle defined variables
+            self.handle_defined_var(base_cls, var_name, var_type)
+
+    def process_annotations(self, cls      : Type           ,                           # Process all annotations
+                                  base_cls : Type           ,
+                                  kwargs   : Dict[str, Any] )\
+                         -> None:
+        if hasattr(base_cls, '__annotations__'):                                        # Process if annotations exist
+            for var_name, var_type in type_safe_cache.get_class_annotations(base_cls):
+                self.process_annotation(cls, base_cls, kwargs, var_name, var_type)
+
+    def process_mro_class(self, base_cls : Type           ,                             # Process class in MRO chain
+                                kwargs   : Dict[str, Any] )\
+                       -> None:
+        if base_cls is object:                                                                              # Skip object class
+            return
+
+        class_variables = type_safe_cache.get_valid_class_variables(base_cls                            ,
+                                                                    type_safe_validation.should_skip_var)   # Get valid class variables
+
+        for name, value in class_variables.items():                                                         # Add non-existing variables
+            if name not in kwargs:
+                kwargs[name] = value
+
+
+# Create singleton instance
+type_safe_step_class_kwargs = Type_Safe__Step__Class_Kwargs()

osbot_utils/type_safe/steps/Type_Safe__Step__Default_Kwargs.py

@@ -0,0 +1,42 @@
+import types
+import inspect
+
+class Type_Safe__Step__Default_Kwargs:
+
+    def default_kwargs(self, _self):
+        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, _self):
+        kwargs = {}
+        for key, value in self.default_kwargs(_self).items():                      # Update with instance-specific values
+            kwargs[key] = _self.__getattribute__(key)
+        return kwargs
+
+    def locals(self, _self):
+        """Return a dictionary of the current instance's attribute values."""
+        kwargs = self.kwargs(_self)
+
+        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
+
+type_safe_step_default_kwargs = Type_Safe__Step__Default_Kwargs()
+