osbot-utils 2.63.0__tar.gz → 2.65.0__tar.gz

{osbot_utils-2.63.0 → osbot_utils-2.65.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: osbot_utils
-Version: 2.63.0
+Version: 2.65.0
 Summary: OWASP Security Bot - Utils
 License: MIT
 Author: Dinis Cruz
@@ -23,7 +23,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-v2.63.0-blue)
+![Current Release](https://img.shields.io/badge/release-v2.65.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-2.63.0 → osbot_utils-2.65.0}/README.md

@@ -2,7 +2,7 @@
 
 Powerful Python util methods and classes that simplify common apis and tasks.
 
-![Current Release](https://img.shields.io/badge/release-v2.63.0-blue)
+![Current Release](https://img.shields.io/badge/release-v2.65.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-2.65.0/osbot_utils/decorators/methods/cache_on_self.py

@@ -0,0 +1,51 @@
+import inspect
+from functools                                         import wraps
+from typing import Any, Callable, TypeVar, Dict
+from weakref import WeakKeyDictionary
+
+from osbot_utils.helpers.cache_on_self.Cache_On_Self   import Cache_On_Self
+
+
+T = TypeVar('T', bound=Callable[..., Any])
+
+# Global registry of cache managers per instance per method
+# Structure: {instance: {method_name: Cache_On_Self}}
+_cache_managers_registry: WeakKeyDictionary[Any, Dict[str, Cache_On_Self]] = WeakKeyDictionary()
+
+
+
+def cache_on_self(function: T) -> T:
+    """
+    Decorator to cache method results on the instance.
+
+    Use this for cases where we want the cache to be tied to the
+    Class instance (i.e. not global for all executions)
+    """
+    function_name = function.__name__
+
+    @wraps(function)
+    def wrapper(*args, **kwargs):
+        # Extract self from args
+        if not args:
+            raise ValueError("cache_on_self could not find self - no arguments provided")
+
+        self = args[0]
+
+        # Get or create cache manager for this instance/method combination
+        if self not in _cache_managers_registry:
+            _cache_managers_registry[self] = {}
+
+        if function_name not in _cache_managers_registry[self]:
+            # Create new cache manager for this instance/method
+            _cache_managers_registry[self][function_name] = Cache_On_Self(function=function)
+
+        cache_manager = _cache_managers_registry[self][function_name]
+
+        # Handle special __return__ parameter
+        if kwargs.get('__return__') == 'cache_on_self':
+            return cache_manager
+
+        # Normal call
+        return cache_manager.handle_call(args, kwargs)
+
+    return wrapper

osbot_utils-2.65.0/osbot_utils/helpers/cache_on_self/Cache_Controller.py

@@ -0,0 +1,28 @@
+import inspect
+from typing import Any, Dict
+
+
+class Cache_Controller:                                                             # Controls cache behavior and reload logic
+
+    def extract_clean_kwargs(self, kwargs: Dict[str, Any]) -> Dict[str, Any]:      # Remove special parameters from kwargs
+        return {k: v for k, v in kwargs.items()
+                if k not in ['reload_cache', '__return__']}
+
+    def should_reload(self, kwargs         : Dict[str, Any] ,
+                            reload_next_flag: bool          ) -> bool:             # Determine if cache should be reloaded
+        if reload_next_flag:
+            return True
+        return kwargs.get('reload_cache', False) is True
+
+    def should_return_cache_manager(self, kwargs: Dict[str, Any]) -> bool:         # Check if should return cache manager
+        return kwargs.get('__return__') == 'cache_on_self'
+
+    def extract_self_from_args(self, args: tuple) -> Any:                          # Validate and extract self from args
+        if len(args) == 0:
+            raise ValueError("cache_on_self could not find self - no arguments provided")
+
+        potential_self = args[0]
+        if not inspect.isclass(type(potential_self)):
+            raise ValueError("cache_on_self could not find self - first argument is not an instance")
+
+        return potential_self

osbot_utils-2.65.0/osbot_utils/helpers/cache_on_self/Cache_Key_Generator.py

@@ -0,0 +1,113 @@
+import json
+from typing import Callable, Dict, List, Tuple, Any, Set, FrozenSet
+from osbot_utils.utils.Misc import str_md5
+
+
+CACHE_ON_SELF_TYPES      = [int, float, bytearray, bytes, bool, complex, str]
+CACHE_ON_SELF_KEY_PREFIX = '__cache_on_self__'
+
+
+class Cache_Key_Generator:                                                          # Handles all cache key generation logic
+
+    def __init__(self, supported_types: List[type] = None):
+        self.supported_types = supported_types or CACHE_ON_SELF_TYPES
+
+    def generate_key(self, function : Callable          ,
+                           args     : Tuple   [Any, ...],
+                           kwargs   : Dict    [str, Any]
+                      ) -> str:                             # Generate cache key from function name and arguments
+        key_name    = function.__name__
+        args_hash   = self.get_args_hash(args)
+        kwargs_hash = self.get_kwargs_hash(kwargs)
+        return f'{CACHE_ON_SELF_KEY_PREFIX}_{key_name}_{args_hash}_{kwargs_hash}'
+
+    def get_args_hash(self, args: Tuple[Any, ...]) -> str:                         # Get hash for args or empty string if no hashable args
+        args_str = self.args_to_str(args)
+        if args_str:
+            return self.compute_hash(args_str)
+        return ''
+
+    def get_kwargs_hash(self, kwargs: Dict[str, Any]) -> str:                      # Get hash for kwargs or empty string if no hashable kwargs
+        kwargs_str = self.kwargs_to_str(kwargs)
+        if kwargs_str:
+            return self.compute_hash(kwargs_str)
+        return ''
+
+    def args_to_str(self, args: Tuple[Any, ...]) -> str:                           # Convert supported args to string representation
+        if not args:
+            return ''
+
+        parts = []
+        for i, arg in enumerate(args):
+            arg_str = self.value_to_cache_str(arg)
+            if arg_str:
+                # Include index to avoid collisions like (1, 23) vs (12, 3)
+                parts.append(f"[{i}]:{arg_str}")
+        return '|'.join(parts)
+
+    def kwargs_to_str(self, kwargs: Dict[str, Any]) -> str:                        # Convert supported kwargs to string representation
+        if not kwargs:
+            return ''
+
+        parts = []
+        for key, value in sorted(kwargs.items()):  # Sort for consistent ordering
+            value_str = self.value_to_cache_str(value)
+            if value_str:
+                parts.append(f'{key}:{value_str}')
+        return '|'.join(parts)
+
+    def value_to_cache_str(self, value: Any) -> str:                              # Convert a value to a cacheable string representation
+        """Convert any value to a string suitable for cache key generation.
+
+        Returns a type-prefixed string for all supported types.
+        Returns empty string ONLY for unsupported types.
+        """
+        if value is None:
+            return '<none>'
+
+        # Handle primitive types with type prefix to avoid any collision
+        value_type = type(value)
+        if value_type in self.supported_types:
+            type_name = value_type.__name__
+            return f"<{type_name}>:{value}"
+
+        # Handle mutable types by converting to a stable string representation
+        try:
+            if isinstance(value, dict):
+                # Sort dict by keys for consistent ordering
+                sorted_items = sorted(value.items())
+                return f"<dict>:{json.dumps(sorted_items, sort_keys=True, separators=(',', ':'))}"
+
+            elif isinstance(value, list):
+                return f"<list>:{json.dumps(value, separators=(',', ':'))}"
+
+            elif isinstance(value, tuple):
+                return f"<tuple>:{json.dumps(value, separators=(',', ':'))}"
+
+            elif isinstance(value, set):
+                # Convert to sorted list for consistent ordering
+                return f"<set>:{json.dumps(sorted(list(value)), separators=(',', ':'))}"
+
+            elif isinstance(value, frozenset):
+                return f"<frozenset>:{json.dumps(sorted(list(value)), separators=(',', ':'))}"
+
+            else:
+                # For other types, try to use repr if it's likely to be stable
+                # This is a fallback - specific types should be handled above
+                if hasattr(value, '__dict__'):
+                    # For objects, we could hash their dict representation
+                    # But this is risky, so we'll skip for now
+                    return ''
+                else:
+                    # For other immutable types, try repr
+                    try:
+                        return f"other:{repr(value)}"
+                    except:
+                        return ''
+
+        except (TypeError, ValueError, RecursionError):
+            # If we can't serialize the value, skip it
+            return ''
+
+    def compute_hash(self, value: str) -> str:                                     # Compute hash of string value
+        return str_md5(value)

osbot_utils-2.65.0/osbot_utils/helpers/cache_on_self/Cache_Metrics.py

@@ -0,0 +1,31 @@
+class Cache_Metrics:                                                                # Track cache performance metrics
+
+    def __init__(self):
+        self.hits                    = 0
+        self.misses                  = 0
+        self.reloads                 = 0
+        self.key_generation_time     = 0.0
+        self.cache_lookup_time       = 0.0
+        self.function_execution_time = 0.0
+
+    @property
+    def hit_rate(self) -> float:                                                    # Calculate cache hit rate
+        total = self.hits + self.misses
+        return self.hits / total if total > 0 else 0.0
+
+    def record_hit(self) -> None:                                                   # Record cache hit
+        self.hits += 1
+
+    def record_miss(self) -> None:                                                  # Record cache miss
+        self.misses += 1
+
+    def record_reload(self) -> None:                                                # Record cache reload
+        self.reloads += 1
+
+    def reset(self) -> None:                                                        # Reset all metrics
+        self.hits                    = 0
+        self.misses                  = 0
+        self.reloads                 = 0
+        self.key_generation_time     = 0.0
+        self.cache_lookup_time       = 0.0
+        self.function_execution_time = 0.0

osbot_utils-2.65.0/osbot_utils/helpers/cache_on_self/Cache_On_Self.py

@@ -0,0 +1,124 @@
+from typing                                                import Any, Callable, Dict, List
+from osbot_utils.type_safe.Type_Safe                       import Type_Safe
+from osbot_utils.helpers.cache_on_self.Cache_Controller    import Cache_Controller
+from osbot_utils.helpers.cache_on_self.Cache_Key_Generator import Cache_Key_Generator, CACHE_ON_SELF_KEY_PREFIX
+from osbot_utils.helpers.cache_on_self.Cache_Metrics       import Cache_Metrics
+from osbot_utils.helpers.cache_on_self.Cache_Storage       import Cache_Storage
+
+
+class Cache_On_Self(Type_Safe):
+    cache_storage       : Cache_Storage                                             # Storage handler instance
+    controller          : Cache_Controller                                          # Controller instance
+    key_generator       : Cache_Key_Generator                                       # Key generator instance
+    metrics             : Cache_Metrics                                             # Metrics tracking
+    function            : Callable                                                  # The wrapped function
+    function_name       : str                                                       # Cached function name
+    no_args_key         : str                                                       # Pre-computed key for no args
+    target_self         : Any                        = None                         # The instance being cached on
+    current_cache_key   : str                        = ''                           # Current cache key
+    current_cache_value : Any                        = None                         # Current cached value
+    reload_next         : bool                       = False                        # Force reload on next call
+    disabled            : bool                       = False                         # cache disable status
+
+    def __init__(self, function       : Callable                   = None ,
+                       supported_types: List[type]                 = None ):
+        super().__init__()
+        self.function       = function
+        self.function_name  = function.__name__ if function else ''
+        self.no_args_key    = f'{CACHE_ON_SELF_KEY_PREFIX}_{self.function_name}__' # Pre-compute for performance
+        self.cache_storage  = Cache_Storage()
+        self.controller     = Cache_Controller()
+        self.key_generator  = Cache_Key_Generator(supported_types)
+        self.metrics        = Cache_Metrics()
+
+    def handle_call(self, args: tuple, kwargs: dict) -> Any:                        # Main entry point for cached calls
+        # Check if caching is disabled
+        if self.disabled:
+            return self.execute(args, kwargs)
+
+        if not kwargs and len(args) == 1:                                           # Fast path for common case: no kwargs, single arg (self)
+            target_self = args[0]
+            cache_key   = self.no_args_key
+
+            if self.cache_storage.has_cached_value(target_self, cache_key):         # Use cache_storage
+                self.metrics.hits += 1                                              # Increment cache Hit
+                return self.cache_storage.get_cached_value(target_self, cache_key)  # Use cache_storage
+
+            self.metrics.misses += 1                                                # Increment cache miss - execute and store (Direct increment)
+            result = self.function(*args)
+            self.cache_storage.set_cached_value(target_self, cache_key, result)    # Use cache_storage instead of setattr
+            return result
+
+        return self.handle_call_full(args, kwargs)
+
+    def handle_call_full(self, args  : tuple,
+                               kwargs: dict
+                          ) -> Any:                                                 # Full logic for complex cases
+        # Check if caching is disabled
+        if self.disabled:
+            clean_kwargs = self.controller.extract_clean_kwargs(kwargs)
+            return self.execute(args, clean_kwargs)
+
+        # Extract values - don't store as instance variables to avoid recursion issues
+        target_self   = self.controller.extract_self_from_args(args)
+        clean_kwargs  = self.controller.extract_clean_kwargs(kwargs)
+        should_reload = self.controller.should_reload(kwargs, self.reload_next)
+        cache_key     = self.key_generator.generate_key(self.function, args, clean_kwargs)
+
+        if should_reload:
+            self.reload_next = False                                                # Reset reload flag
+
+        cached_exists = self.cache_storage.has_cached_value(target_self, cache_key)
+
+        if should_reload or not cached_exists:
+            # Execute and cache, passing the cache key directly
+            result = self.execute_and_cache(args, clean_kwargs, target_self, cache_key, should_reload)
+        else:
+            self.metrics.record_hit()
+            result = self.cache_storage.get_cached_value(target_self, cache_key)
+
+        # Update instance state only for external inspection
+        self.target_self = target_self
+        self.current_cache_key = cache_key
+        self.current_cache_value = result
+
+        return result
+
+    def execute(self, args   : tuple,
+                      kwargs : dict ,
+                 ) -> Any:                                # Execute function
+        return self.function(*args, **kwargs)
+
+    def execute_and_cache(self, args         : tuple,
+                                clean_kwargs : dict,
+                                target_self  : Any,
+                                cache_key    : str,
+                                should_reload: bool) -> Any:                      # Execute function and store result
+        if should_reload:
+            self.metrics.record_reload()
+        else:
+            self.metrics.record_miss()
+
+        result = self.execute(args=args, kwargs=clean_kwargs)
+        self.cache_storage.set_cached_value(target_self, cache_key, result)
+        return result
+
+    def clear(self) -> None:                                                        # Clear current cache entry
+        if self.target_self and self.current_cache_key:
+            self.cache_storage.clear_key(self.target_self, self.current_cache_key)
+
+    def clear_all(self) -> None:                                                    # Clear all cache for current instance
+        if self.target_self:
+            self.cache_storage.clear_all(self.target_self)
+
+    def get_all_keys(self) -> List[str]:                                           # Get all cache keys for current instance
+        if self.target_self:
+            return self.cache_storage.get_all_cache_keys(self.target_self)
+        return []
+
+    def stats(self) -> Dict[str, Any]:                                             # Get cache statistics
+        return { 'hits'      : self.metrics.hits      ,
+                 'misses'    : self.metrics.misses    ,
+                 'reloads'   : self.metrics.reloads   ,
+                 'hit_rate'  : self.metrics.hit_rate  ,
+                 'cache_key' : self.current_cache_key }

osbot_utils-2.65.0/osbot_utils/helpers/cache_on_self/Cache_Storage.py

@@ -0,0 +1,33 @@
+from weakref import WeakKeyDictionary
+from typing import Any, Dict, List
+
+class Cache_Storage:    # Handles all cache storage without polluting instance attributes
+
+    def __init__(self):
+        self.cache_data: WeakKeyDictionary = WeakKeyDictionary()  # Use WeakKeyDictionary so cache is automatically cleaned up when instances are garbage collected , instance -> {cache_key: value}
+
+    def has_cached_value(self, instance: Any, cache_key: str) -> bool:
+        if instance in self.cache_data:
+            return cache_key in self.cache_data[instance]
+        return False
+
+    def get_cached_value(self, instance: Any, cache_key: str) -> Any:
+        return self.cache_data[instance][cache_key]
+
+    def set_cached_value(self, instance: Any, cache_key: str, value: Any) -> None:
+        if instance not in self.cache_data:
+            self.cache_data[instance] = {}
+        self.cache_data[instance][cache_key] = value
+
+    def get_all_cache_keys(self, instance: Any) -> List[str]:
+        if instance in self.cache_data:
+            return list(self.cache_data[instance].keys())
+        return []
+
+    def clear_key(self, instance: Any, cache_key: str) -> None:
+        if instance in self.cache_data:
+            self.cache_data[instance].pop(cache_key, None)
+
+    def clear_all(self, instance: Any) -> None:
+        if instance in self.cache_data:
+            del self.cache_data[instance]

osbot_utils-2.65.0/osbot_utils/helpers/cache_on_self/__init__.py

@@ -0,0 +1,145 @@
+# note 1: this __init__.py file needs to be here (vs inside the /utils/ast/nodes folder)
+#         so that the methods registration happens as soon as somebody uses a method from the /utils/ast folder/package
+# note 2: this is needed due to the circular dependencyes between the Ast_Node and the
+#         clases that use it as a base class
+
+import ast
+from osbot_utils.helpers.Type_Registry                import type_registry
+from osbot_utils.helpers.ast.nodes.Ast_Add            import Ast_Add
+from osbot_utils.helpers.ast.nodes.Ast_Alias          import Ast_Alias
+from osbot_utils.helpers.ast.nodes.Ast_And            import Ast_And
+from osbot_utils.helpers.ast.nodes.Ast_Argument       import Ast_Argument
+from osbot_utils.helpers.ast.nodes.Ast_Arguments      import Ast_Arguments
+from osbot_utils.helpers.ast.nodes.Ast_Assert         import Ast_Assert
+from osbot_utils.helpers.ast.nodes.Ast_Assign         import Ast_Assign
+from osbot_utils.helpers.ast.nodes.Ast_Attribute      import Ast_Attribute
+from osbot_utils.helpers.ast.nodes.Ast_Aug_Assign     import Ast_Aug_Assign
+from osbot_utils.helpers.ast.nodes.Ast_Bin_Op         import Ast_Bin_Op
+from osbot_utils.helpers.ast.nodes.Ast_Bool_Op        import Ast_Bool_Op
+from osbot_utils.helpers.ast.nodes.Ast_Break          import Ast_Break
+from osbot_utils.helpers.ast.nodes.Ast_Call           import Ast_Call
+from osbot_utils.helpers.ast.nodes.Ast_Class_Def      import Ast_Class_Def
+from osbot_utils.helpers.ast.nodes.Ast_Compare        import Ast_Compare
+from osbot_utils.helpers.ast.nodes.Ast_Comprehension  import Ast_Comprehension
+from osbot_utils.helpers.ast.nodes.Ast_Constant       import Ast_Constant
+from osbot_utils.helpers.ast.nodes.Ast_Continue       import Ast_Continue
+from osbot_utils.helpers.ast.nodes.Ast_Dict           import Ast_Dict
+from osbot_utils.helpers.ast.nodes.Ast_Eq             import Ast_Eq
+from osbot_utils.helpers.ast.nodes.Ast_Except_Handler import Ast_Except_Handler
+from osbot_utils.helpers.ast.nodes.Ast_Expr           import Ast_Expr
+from osbot_utils.helpers.ast.nodes.Ast_For            import Ast_For
+from osbot_utils.helpers.ast.nodes.Ast_Function_Def   import Ast_Function_Def
+from osbot_utils.helpers.ast.nodes.Ast_Generator_Exp  import Ast_Generator_Exp
+from osbot_utils.helpers.ast.nodes.Ast_Gt             import Ast_Gt
+from osbot_utils.helpers.ast.nodes.Ast_GtE            import Ast_GtE
+from osbot_utils.helpers.ast.nodes.Ast_If             import Ast_If
+from osbot_utils.helpers.ast.nodes.Ast_If_Exp         import Ast_If_Exp
+from osbot_utils.helpers.ast.nodes.Ast_Import         import Ast_Import
+from osbot_utils.helpers.ast.nodes.Ast_Import_From    import Ast_Import_From
+from osbot_utils.helpers.ast.nodes.Ast_In             import Ast_In
+from osbot_utils.helpers.ast.nodes.Ast_Is             import Ast_Is
+from osbot_utils.helpers.ast.nodes.Ast_Is_Not         import Ast_Is_Not
+from osbot_utils.helpers.ast.nodes.Ast_Keyword        import Ast_Keyword
+from osbot_utils.helpers.ast.nodes.Ast_Lambda         import Ast_Lambda
+from osbot_utils.helpers.ast.nodes.Ast_List           import Ast_List
+from osbot_utils.helpers.ast.nodes.Ast_List_Comp      import Ast_List_Comp
+from osbot_utils.helpers.ast.nodes.Ast_Load           import Ast_Load
+from osbot_utils.helpers.ast.nodes.Ast_Lt             import Ast_Lt
+from osbot_utils.helpers.ast.nodes.Ast_LtE            import Ast_LtE
+from osbot_utils.helpers.ast.nodes.Ast_Mod            import Ast_Mod
+from osbot_utils.helpers.ast.nodes.Ast_Module         import Ast_Module
+from osbot_utils.helpers.ast.nodes.Ast_Mult           import Ast_Mult
+from osbot_utils.helpers.ast.nodes.Ast_Name           import Ast_Name
+from osbot_utils.helpers.ast.nodes.Ast_Not            import Ast_Not
+from osbot_utils.helpers.ast.nodes.Ast_Not_Eq         import Ast_Not_Eq
+from osbot_utils.helpers.ast.nodes.Ast_Not_In         import Ast_Not_In
+from osbot_utils.helpers.ast.nodes.Ast_Or             import Ast_Or
+from osbot_utils.helpers.ast.nodes.Ast_Pass           import Ast_Pass
+from osbot_utils.helpers.ast.nodes.Ast_Pow            import Ast_Pow
+from osbot_utils.helpers.ast.nodes.Ast_Raise          import Ast_Raise
+from osbot_utils.helpers.ast.nodes.Ast_Return         import Ast_Return
+from osbot_utils.helpers.ast.nodes.Ast_Set            import Ast_Set
+from osbot_utils.helpers.ast.nodes.Ast_Slice          import Ast_Slice
+from osbot_utils.helpers.ast.nodes.Ast_Starred        import Ast_Starred
+from osbot_utils.helpers.ast.nodes.Ast_Store          import Ast_Store
+from osbot_utils.helpers.ast.nodes.Ast_Sub            import Ast_Sub
+from osbot_utils.helpers.ast.nodes.Ast_Subscript      import Ast_Subscript
+from osbot_utils.helpers.ast.nodes.Ast_Try            import Ast_Try
+from osbot_utils.helpers.ast.nodes.Ast_Tuple          import Ast_Tuple
+from osbot_utils.helpers.ast.nodes.Ast_Unary_Op       import Ast_Unary_Op
+from osbot_utils.helpers.ast.nodes.Ast_While          import Ast_While
+from osbot_utils.helpers.ast.nodes.Ast_With           import Ast_With
+from osbot_utils.helpers.ast.nodes.Ast_With_Item      import Ast_With_Item
+from osbot_utils.helpers.ast.nodes.Ast_Yield          import Ast_Yield
+
+ast_types = {
+    ast.Add           : Ast_Add           ,
+    ast.alias         : Ast_Alias         ,
+    ast.And           : Ast_And           ,
+    ast.Assert        : Ast_Assert        ,
+    ast.Assign        : Ast_Assign        ,
+    ast.Attribute     : Ast_Attribute     ,
+    ast.arg           : Ast_Argument      ,
+    ast.arguments     : Ast_Arguments     ,
+    ast.AugAssign     : Ast_Aug_Assign    ,
+    ast.BinOp         : Ast_Bin_Op        ,
+    ast.BoolOp        : Ast_Bool_Op       ,
+    ast.Break         : Ast_Break         ,
+    ast.Call          : Ast_Call          ,
+    ast.ClassDef      : Ast_Class_Def     ,
+    ast.Compare       : Ast_Compare       ,
+    ast.Constant      : Ast_Constant      ,
+    ast.Continue      : Ast_Continue      ,
+    ast.comprehension : Ast_Comprehension ,
+    ast.Dict          : Ast_Dict          ,
+    ast.ExceptHandler : Ast_Except_Handler,
+    ast.Expr          : Ast_Expr          ,
+    ast.Eq            : Ast_Eq            ,
+    ast.Gt            : Ast_Gt            ,
+    ast.GtE           : Ast_GtE           ,
+    ast.Import        : Ast_Import        ,
+    ast.ImportFrom    : Ast_Import_From   ,
+    ast.In            : Ast_In            ,
+    ast.For           : Ast_For           ,
+    ast.FunctionDef   : Ast_Function_Def  ,
+    ast.GeneratorExp  : Ast_Generator_Exp ,
+    ast.If            : Ast_If            ,
+    ast.IfExp         : Ast_If_Exp        ,
+    ast.Is            : Ast_Is            ,
+    ast.IsNot         : Ast_Is_Not        ,
+    ast.keyword       : Ast_Keyword       ,
+    ast.Lambda        : Ast_Lambda        ,
+    ast.List          : Ast_List          ,
+    ast.ListComp      : Ast_List_Comp     ,
+    ast.Lt            : Ast_Lt            ,
+    ast.LtE           : Ast_LtE           ,
+    ast.Load          : Ast_Load          ,
+    ast.Mod           : Ast_Mod           ,
+    ast.Module        : Ast_Module        ,
+    ast.Mult          : Ast_Mult          ,
+    ast.Name          : Ast_Name          ,
+    ast.Not           : Ast_Not           ,
+    ast.NotEq         : Ast_Not_Eq        ,
+    ast.NotIn         : Ast_Not_In        ,
+    ast.Or            : Ast_Or            ,
+    ast.Pass          : Ast_Pass          ,
+    ast.Pow           : Ast_Pow           ,
+    ast.Raise         : Ast_Raise         ,
+    ast.Return        : Ast_Return        ,
+    ast.Slice         : Ast_Slice         ,
+    ast.Starred       : Ast_Starred       ,
+    ast.Store         : Ast_Store         ,
+    ast.Set           : Ast_Set           ,
+    ast.Sub           : Ast_Sub           ,
+    ast.Subscript     : Ast_Subscript     ,
+    ast.Try           : Ast_Try           ,
+    ast.Tuple         : Ast_Tuple         ,
+    ast.UnaryOp       : Ast_Unary_Op      ,
+    ast.While         : Ast_While         ,
+    ast.With          : Ast_With          ,
+    ast.withitem      : Ast_With_Item     ,
+    ast.Yield         : Ast_Yield         ,
+}
+
+for key, value in ast_types.items():
+    type_registry.register(key, value)

{osbot_utils-2.63.0 → osbot_utils-2.65.0}/osbot_utils/type_safe/Type_Safe__Method.py

@@ -10,12 +10,13 @@ class Type_Safe__Method:
         self.func         = func                                                          # Store original function
         self.sig          = inspect.signature(func)                                       # Get function signature
         self.annotations  = func.__annotations__                                          # Get function annotations
+        self.params       = list(self.sig.parameters.keys())
 
     def check_for_any_use(self):
         for param_name, type_hint in self.annotations.items():
             if type_hint is any:  # Detect incorrect usage of lowercase any
                 raise ValueError(f"Parameter '{param_name}' uses lowercase 'any' instead of 'Any' from typing module. "
-                              f"Please use 'from typing import Any' and annotate as '{param_name}: Any'")
+                                f"Please use 'from typing import Any' and annotate as '{param_name}: Any'")
 
     def handle_type_safety(self, args: tuple, kwargs: dict):                              # Main method to handle type safety
         self.check_for_any_use()
@@ -80,10 +81,6 @@ class Type_Safe__Method:
             self.validate_union_type(param_name, param_value, expected_type)             # Validate union
             return                                                                       # Exit early
 
-        # if self.try_basic_type_conversion(param_value, expected_type, param_name,        # Try basic type conversion
-        #                                 bound_args):                                     # Pass bound args
-        #    return                                                                       # Exit if conversion successful
-
         self.validate_direct_type(param_name, param_value, expected_type)                # Direct type validation
 
     def is_optional_type(self, type_hint: Any) -> bool:                                  # Check if type is Optional
@@ -108,9 +105,13 @@ class Type_Safe__Method:
         if not isinstance(param_value, list):                                         # Check if value is a list
             raise ValueError(f"Parameter '{param_name}' expected a list but got {type(param_value)}")  # Raise error if not list
 
-        item_type = get_args(expected_type)[0]                                        # Get list item type
-        for i, item in enumerate(param_value):                                        # Check each list item
-            if not isinstance(item, item_type):                                       # Validate item type
+        item_type = get_args(expected_type)[0]                                          # Get list item type
+        if get_origin(item_type) is not None:                                           # Handle the case when item_type is a subscripted type (which is not supported at the moment)
+            raise NotImplementedError(f"Validation for list items with subscripted type"
+                                      f" '{item_type}' is not yet supported "
+                                      f"in parameter '{param_name}'.")                  # todo: add support for checking for subscripted types
+        for i, item in enumerate(param_value):                                          # Check each list item
+            if not isinstance(item, item_type):                                         # Validate item type
                 raise ValueError(f"List item at index {i} expected type {item_type}, but got {type(item)}")  # Raise error for invalid item
 
     def validate_type_parameter(self, param_name: str, param_value: Any, expected_type: Any):           # Validate a Type[T] parameter
@@ -163,6 +164,7 @@ class Type_Safe__Method:
             is_optional = self.is_optional_type(expected_type)                            # Check if type is optional
             has_default = self.has_default_value(param_name)                              # Check if has default value
             self.validate_none_value(param_name, is_optional, has_default)                # Validate None value
+            return True
 
         origin = get_origin(expected_type)
 
@@ -174,11 +176,20 @@ class Type_Safe__Method:
                 if not isinstance(param_value, dict):
                     raise ValueError(f"Parameter '{param_name}' expected dict but got {type(param_value)}")
                 key_type, value_type = get_args(expected_type)
+                if value_type is Any:                                                                       # if value type is Any, we don't need to do any checks since they will all match
+                    return True
                 for k, v in param_value.items():
-                    if not isinstance(k, key_type):
-                        raise ValueError(f"Dict key '{k}' expected type {key_type}, but got {type(k)}")
-                    if not isinstance(v, value_type):
-                        raise ValueError(f"Dict value for key '{k}' expected type {value_type}, but got {type(v)}")
+                    if get_origin(key_type) is None:
+                        if not isinstance(k, key_type):
+                            raise ValueError(f"Dict key '{k}' expected type {key_type}, but got {type(k)}")
+                    else:
+                        raise NotImplementedError(f"Validation for subscripted key type '{key_type}' not yet supported in parameter '{param_name}'")
+
+                    if get_origin(value_type) is None:
+                        if not isinstance(v, value_type):
+                            raise ValueError(f"Dict value for key '{k}' expected type {value_type}, but got {type(v)}")
+                    elif value_type is not Any:
+                        raise NotImplementedError(f"Validation for subscripted value type '{value_type}' not yet supported in parameter '{param_name}'")
                 return True
             base_type = origin
         else:

osbot_utils-2.65.0/osbot_utils/type_safe/decorators/type_safe.py

@@ -0,0 +1,20 @@
+import functools                                                                           # For wrapping functions
+from osbot_utils.type_safe.Type_Safe__Method import Type_Safe__Method
+
+def type_safe(func):                                                                        # Main decorator function
+    type_checker = Type_Safe__Method(func)  # Create type checker instance
+
+    has_only_self    = len(type_checker.params) == 1 and type_checker.params[0] == 'self'   # Check if method has only 'self' parameter or no parameters
+    has_no_params    = len(type_checker.params) == 0
+    direct_execution = has_no_params or has_only_self                                       # these are major performance optimisation where this @type_safe had an overhead of 250x (even on methods with no params) to now having an over head of ~5x
+
+    @functools.wraps(func)                                                                 # Preserve function metadata
+    def wrapper(*args, **kwargs):                                                          # Wrapper function
+        if direct_execution:
+            return func(*args, **kwargs)
+        else:
+            bound_args   = type_checker.handle_type_safety(args, kwargs)                       # Validate type safety
+            return func(**bound_args.arguments)                                                # Call original function
+
+    return wrapper                                                                         # Return wrapped function
+