qnty 0.0.9__py3-none-any.whl → 0.1.0__py3-none-any.whl

qnty/utils/scope_discovery.py

@@ -0,0 +1,420 @@
+"""
+Scope Discovery Service
+=======================
+
+Centralized service for automatically discovering variables from the calling scope.
+Consolidates all scope inspection logic used across expressions, equations, and variable solving.
+
+This module uses protocol-based design to avoid circular imports and duck typing performance issues.
+"""
+
+import inspect
+import logging
+from typing import Any
+
+from .protocols import TypeRegistry
+
+# Setup logging for better debugging
+_logger = logging.getLogger(__name__)
+
+
+class ScopeDiscoveryService:
+    """
+    Centralized service for scope discovery operations.
+
+    Provides optimized variable discovery from calling scopes with caching,
+    depth limits, and consistent error handling.
+    """
+
+    # Class-level optimization settings
+    _scope_cache = {}
+    _frame_cache = {}
+    _variable_name_cache = {}
+    _max_scope_cache_size = 200  # Increased cache size
+    _max_frame_cache_size = 50
+    _max_search_depth = 8
+    _cache_hit_count = 0
+    _cache_miss_count = 0
+
+    @classmethod
+    def discover_variables(cls, required_vars: set[str], enable_caching: bool = True) -> dict[str, Any]:
+        """
+        Discover variables from the calling scope with enhanced caching.
+
+        Args:
+            required_vars: Set of variable names to find
+            enable_caching: Whether to use caching for performance
+
+        Returns:
+            Dictionary mapping variable names to variable instances
+        """
+        if not required_vars:
+            return {}
+
+        # Check cache first if enabled
+        if enable_caching:
+            cache_key = frozenset(required_vars)
+            if cache_key in cls._scope_cache:
+                cls._cache_hit_count += 1
+                _logger.debug(f"Cache hit for variables: {required_vars}")
+                return cls._scope_cache[cache_key]
+
+            cls._cache_miss_count += 1
+
+            # Clean cache if it gets too large (LRU-style)
+            if len(cls._scope_cache) >= cls._max_scope_cache_size:
+                # Remove oldest 25% of entries
+                items_to_remove = len(cls._scope_cache) // 4
+                for _ in range(items_to_remove):
+                    cls._scope_cache.pop(next(iter(cls._scope_cache)))
+                _logger.debug(f"Cleaned {items_to_remove} entries from scope cache")
+
+        # Get the calling frame with caching
+        frame = cls._get_cached_user_frame()
+        if frame is None:
+            _logger.debug("No user frame found")
+            return {}
+
+        try:
+            discovered = cls._search_frame_for_variables(frame, required_vars)
+
+            # Cache the result if caching is enabled and successful
+            if enable_caching and required_vars:
+                cache_key = frozenset(required_vars)
+                cls._scope_cache[cache_key] = discovered
+                _logger.debug(f"Cached discovery result for variables: {required_vars}")
+
+            return discovered
+
+        except Exception as e:
+            _logger.warning(f"Error during variable discovery: {e}")
+            return {}
+
+    @classmethod
+    def can_auto_evaluate(cls, expression: Any) -> tuple[bool, dict[str, Any]]:
+        """
+        Check if expression can be auto-evaluated from scope.
+
+        Args:
+            expression: Expression to check for auto-evaluation
+
+        Returns:
+            Tuple of (can_evaluate, discovered_variables)
+        """
+        try:
+            # Use protocol-based checking instead of duck typing
+            if not TypeRegistry.is_expression(expression):
+                return False, {}
+
+            required_vars = expression.get_variables()
+            if not required_vars:
+                return True, {}  # No variables needed, can evaluate
+
+            discovered = cls.discover_variables(required_vars, enable_caching=True)
+
+            # Check if all required variables are available and have values
+            for var_name in required_vars:
+                if var_name not in discovered:
+                    _logger.debug(f"Variable '{var_name}' not found in scope")
+                    return False, {}
+
+                var = discovered[var_name]
+                if not hasattr(var, "quantity") or var.quantity is None:
+                    _logger.debug(f"Variable '{var_name}' has no quantity")
+                    return False, {}
+
+            _logger.debug(f"Expression can be auto-evaluated with variables: {list(discovered.keys())}")
+            return True, discovered
+
+        except Exception as e:
+            _logger.warning(f"Error during auto-evaluation check: {e}")
+            return False, {}
+
+    @classmethod
+    def find_variables_in_scope(cls, filter_func=None) -> dict[str, Any]:
+        """
+        Find all UnifiedVariable instances in the calling scope.
+
+        Args:
+            filter_func: Optional function to filter variables (var) -> bool
+
+        Returns:
+            Dictionary mapping variable names/symbols to variable instances
+        """
+        frame = inspect.currentframe()
+        if frame is None:
+            _logger.warning("Unable to access current frame")
+            return {}
+
+        try:
+            frame = cls._find_user_frame(frame)
+            if frame is None:
+                return {}
+
+            discovered = {}
+
+            # Search locals first
+            for obj in frame.f_locals.values():
+                if TypeRegistry.is_variable(obj):
+                    if filter_func is None or filter_func(obj):
+                        var_name = cls._get_variable_name(obj)
+                        if var_name:
+                            discovered[var_name] = obj
+
+            # Search globals for remaining variables
+            for obj in frame.f_globals.values():
+                if TypeRegistry.is_variable(obj):
+                    if filter_func is None or filter_func(obj):
+                        var_name = cls._get_variable_name(obj)
+                        if var_name and var_name not in discovered:
+                            discovered[var_name] = obj
+
+            return discovered
+
+        finally:
+            del frame
+
+    @classmethod
+    def _get_cached_user_frame(cls) -> Any | None:
+        """
+        Get user frame with caching to reduce repeated frame traversal.
+
+        Returns:
+            User frame or None if not found
+        """
+        # Get current frame for cache key generation
+        current_frame = inspect.currentframe()
+        if current_frame is None:
+            return None
+
+        try:
+            # Create cache key based on frame signature
+            frame_id = id(current_frame)
+
+            # Check frame cache first
+            if frame_id in cls._frame_cache:
+                cached_frame = cls._frame_cache[frame_id]
+                if cached_frame is not None:
+                    return cached_frame
+
+            # Clean frame cache if too large
+            if len(cls._frame_cache) >= cls._max_frame_cache_size:
+                cls._frame_cache.clear()
+
+            # Find user frame using optimized search
+            user_frame = cls._find_user_frame_optimized(current_frame)
+
+            # Cache the result
+            cls._frame_cache[frame_id] = user_frame
+            return user_frame
+
+        finally:
+            del current_frame
+
+    @classmethod
+    def _find_user_frame_optimized(cls, current_frame: Any) -> Any | None:
+        """
+        Optimized frame search with precompiled patterns.
+
+        Args:
+            current_frame: Starting frame
+
+        Returns:
+            User frame or None if not found within depth limit
+        """
+        frame = current_frame
+        depth = 0
+
+        # Pre-compiled sets for faster lookups
+        internal_file_endings = frozenset(["expression.py", "equation.py", "nodes.py", "scope_discovery.py", "expression_quantity.py", "unified_variable.py", "field_qnty.py"])
+        internal_function_names = frozenset(["__str__", "__repr__", "_can_auto_evaluate", "_discover_variables_from_scope", "solve_from", "evaluate"])
+
+        while frame and depth < cls._max_search_depth:
+            code = frame.f_code
+            filename = code.co_filename
+            function_name = code.co_name
+
+            # Fast check: is this frame internal?
+            is_internal = any(filename.endswith(ending) for ending in internal_file_endings) or function_name in internal_function_names
+
+            if not is_internal:
+                _logger.debug(f"Found user frame at depth {depth}: {filename}:{function_name}")
+                return frame
+
+            frame = frame.f_back
+            depth += 1
+
+        _logger.debug(f"No user frame found within {cls._max_search_depth} levels")
+        return None
+
+    @classmethod
+    def _find_user_frame(cls, current_frame: Any) -> Any | None:
+        """
+        Legacy method for backward compatibility.
+        """
+        return cls._find_user_frame_optimized(current_frame)
+
+    @classmethod
+    def _search_frame_for_variables(cls, frame: Any, required_vars: set[str]) -> dict[str, Any]:
+        """
+        Search a specific frame for required variables.
+
+        Args:
+            frame: Frame to search
+            required_vars: Set of variable names to find
+
+        Returns:
+            Dictionary of found variables
+        """
+        discovered = {}
+
+        # Search locals first (most common case)
+        local_vars = frame.f_locals
+        for var_name in required_vars:
+            # Direct lookup first (fastest)
+            if var_name in local_vars:
+                obj = local_vars[var_name]
+                if TypeRegistry.is_variable(obj):
+                    discovered[var_name] = obj
+                    continue
+
+        # Get globals once for reuse
+        global_vars = frame.f_globals
+
+        # Search globals only for remaining variables
+        if len(discovered) < len(required_vars):
+            remaining_vars = required_vars - discovered.keys()
+            for var_name in remaining_vars:
+                if var_name in global_vars:
+                    obj = global_vars[var_name]
+                    if TypeRegistry.is_variable(obj):
+                        discovered[var_name] = obj
+
+        # Search by symbol/name for remaining variables (optimized)
+        if len(discovered) < len(required_vars):
+            remaining_vars = required_vars - discovered.keys()
+            cls._search_by_symbol_name_optimized(local_vars, global_vars, remaining_vars, discovered)
+
+        _logger.debug(f"Found {len(discovered)} of {len(required_vars)} required variables")
+        return discovered
+
+    @classmethod
+    def _search_by_symbol_name_optimized(cls, local_vars: dict, global_vars: dict, remaining_vars: set[str], discovered: dict[str, Any]) -> None:
+        """Optimized search for variables by their symbol/name attribute."""
+        # Convert to list once to avoid repeated set operations
+        remaining_list = list(remaining_vars)
+
+        # Search locals by symbol/name with early termination
+        for obj in local_vars.values():
+            if not remaining_list:  # Check list instead of set
+                break
+            if TypeRegistry.is_variable(obj):
+                obj_name = cls._get_variable_name(obj)
+                if obj_name in remaining_vars:  # Still check set for O(1) lookup
+                    discovered[obj_name] = obj
+                    remaining_list.remove(obj_name)
+                    remaining_vars.remove(obj_name)
+
+        # Search globals by symbol/name if still needed
+        if remaining_list:
+            for obj in global_vars.values():
+                if not remaining_list:
+                    break
+                if TypeRegistry.is_variable(obj):
+                    obj_name = cls._get_variable_name(obj)
+                    if obj_name in remaining_vars:
+                        discovered[obj_name] = obj
+                        remaining_list.remove(obj_name)
+                        remaining_vars.remove(obj_name)
+
+    @classmethod
+    def _search_by_symbol_name(cls, local_vars: dict, global_vars: dict, remaining_vars: set[str], discovered: dict[str, Any]) -> None:
+        """Legacy method for backward compatibility."""
+        cls._search_by_symbol_name_optimized(local_vars, global_vars, remaining_vars, discovered)
+
+    @classmethod
+    def _get_variable_name(cls, var) -> str | None:
+        """
+        Get the name/symbol to use for a variable with caching.
+
+        Args:
+            var: Variable instance
+
+        Returns:
+            Variable name/symbol or None if not available
+        """
+        var_id = id(var)
+
+        # Check cache first
+        if var_id in cls._variable_name_cache:
+            return cls._variable_name_cache[var_id]
+
+        try:
+            # Prefer symbol over name for equation solving
+            name = var.symbol if var.symbol else var.name
+
+            # Cache the result
+            cls._variable_name_cache[var_id] = name
+            return name
+        except (AttributeError, TypeError):
+            cls._variable_name_cache[var_id] = None
+            return None
+
+    @classmethod
+    def clear_cache(cls) -> None:
+        """Clear all caches for testing or memory management."""
+        cls._scope_cache.clear()
+        cls._frame_cache.clear()
+        cls._variable_name_cache.clear()
+        cls._cache_hit_count = 0
+        cls._cache_miss_count = 0
+        TypeRegistry.clear_cache()
+        _logger.debug("Cleared all scope discovery caches")
+
+    @classmethod
+    def get_cache_stats(cls) -> dict[str, Any]:
+        """Get cache performance statistics."""
+        total_requests = cls._cache_hit_count + cls._cache_miss_count
+        hit_rate = (cls._cache_hit_count / total_requests * 100) if total_requests > 0 else 0
+
+        return {
+            "scope_cache_size": len(cls._scope_cache),
+            "frame_cache_size": len(cls._frame_cache),
+            "variable_name_cache_size": len(cls._variable_name_cache),
+            "cache_hits": cls._cache_hit_count,
+            "cache_misses": cls._cache_miss_count,
+            "hit_rate_percent": round(hit_rate, 2),
+        }
+
+    @classmethod
+    def set_max_depth(cls, depth: int) -> None:
+        """Set maximum search depth for scope discovery."""
+        if depth > 0:
+            cls._max_search_depth = depth
+            _logger.debug(f"Set max search depth to {depth}")
+        else:
+            raise ValueError("Depth must be positive")
+
+    @classmethod
+    def enable_debug_logging(cls) -> None:
+        """Enable debug logging for scope discovery operations."""
+        logging.getLogger(__name__).setLevel(logging.DEBUG)
+
+    @classmethod
+    def disable_debug_logging(cls) -> None:
+        """Disable debug logging for scope discovery operations."""
+        logging.getLogger(__name__).setLevel(logging.WARNING)
+
+
+# Convenience function for backward compatibility
+def discover_variables_from_scope(required_vars: set[str]) -> dict[str, Any]:
+    """
+    Convenience function to discover variables from scope.
+
+    Args:
+        required_vars: Set of variable names to find
+
+    Returns:
+        Dictionary mapping variable names to variable instances
+    """
+    return ScopeDiscoveryService.discover_variables(required_vars)

{qnty-0.0.9.dist-info → qnty-0.1.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: qnty
-Version: 0.0.9
+Version: 0.1.0
 Summary: High-performance unit system library for Python with dimensional safety and fast unit conversions
 License: Apache-2.0
 Keywords: units,dimensional analysis,engineering,physics,quantities,measurements

qnty-0.1.0.dist-info/RECORD

@@ -0,0 +1,60 @@
+qnty/__init__.py,sha256=JlMYdpcYFD8agf9nJrxnBw-MXKzGxcqCO4wFxTICQaA,5564
+qnty/constants/__init__.py,sha256=-ADevTOA1tgi5OebYDFzP5ov8jq7Bwy66BCZqiXmGJk,267
+qnty/constants/numerical.py,sha256=zs1OaSV5NDnxHLELzHz_G3NcetuF7JEO0Lih4BGUz60,679
+qnty/constants/solvers.py,sha256=f9bMxxSu99Bg0laWBnLkWbbD5-N02rHiLqlTmO-VSik,212
+qnty/constants/tests.py,sha256=viGxxGBDIu0uA2nJtK20liJ1_ZjqkC20XghxwDaXRv8,218
+qnty/dimensions/__init__.py,sha256=MtHz9Auvpv2xJ4jxRTT7mL1EFk5fuBLJlhxhSRRfSRc,672
+qnty/dimensions/base.py,sha256=YkEn0fvXKq2Utruh2lGAdIT1mVrhu24QXfDl0CMUEG4,2604
+qnty/dimensions/field_dims.py,sha256=bcPu1xxPhjoNjc7TxyP_B4xKDLHKGdtNne-sCB9hz-8,5300
+qnty/dimensions/field_dims.pyi,sha256=lk3YrH3Ovs3CJCZe5MfX334kdpmsfEql4D3fLKjuYDs,4575
+qnty/dimensions/signature.py,sha256=yk7QGejAV-TEPTqWE1Q5yV2sZA-RWGiK_rHiMT0Q2yU,4173
+qnty/equations/__init__.py,sha256=Ou5H6tTFXgVw16JYan_a4653NxroBxcnTY6YWt380Qo,108
+qnty/equations/equation.py,sha256=6Ot3-XhSFyxdv3hUwJvdTvB2BGZlAoXX46uok_6q-14,9041
+qnty/equations/system.py,sha256=vMoD1iTUrAHnVFVvCUKeyNfSBfMiqpwQbfDx46kN9N8,5155
+qnty/expressions/__init__.py,sha256=DA2s7DBhVCmdUgsYSTJWObsp2DbbpFn492yr1nUTg2g,930
+qnty/expressions/formatter.py,sha256=yLGLwLYjhBvVi2Q6rfkg8pbyH0-a1Ko0AYLsqJTJf50,7806
+qnty/expressions/functions.py,sha256=ek43udfUDpThKo38rVPBYPvKfZNc9Bbs8RuL-CvQc_A,2729
+qnty/expressions/nodes.py,sha256=7JxHzhqZNrNUqShIBsIyuLmHQyeC14m4RxPCwxKvmrE,28431
+qnty/expressions/types.py,sha256=eoM-IqY-k-IypRHAlRwjEtMmB6DiwX7YGot8t_vGw3o,1729
+qnty/extensions/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+qnty/extensions/integration/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+qnty/extensions/plotting/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+qnty/extensions/reporting/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+qnty/problems/__init__.py,sha256=g7zuml2IecoSwgzX6r1zZ5SlmBKFc8qqTR_cao037pc,4808
+qnty/problems/composition.py,sha256=JUOu3IksLRJEJ2OvPyarxkuzvcrnYI9fNeov2Lj7ynk,41937
+qnty/problems/problem.py,sha256=Yh7wLo7RyZcR9fie6niJqcnP81rZhDKtNTgd5KQr1XE,28279
+qnty/problems/rules.py,sha256=NwIStAa8bocVtvzAsnPmRdC_0ENTJWyXLOoYBnkvpPA,5176
+qnty/problems/solving.py,sha256=LTI8F9ujDiSqXE9Aiz8sOgaGJNX9p7oaR5CQIZHpCY8,44315
+qnty/problems/validation.py,sha256=SmFEsgHx5XwRNlR2suOhxO-WNsOwPZhCP8wyVKYo1EE,4826
+qnty/quantities/__init__.py,sha256=K_h5v6X6-OyITSXOhbIZTDAJe6-y_7iMMDEIQ4O3luc,809
+qnty/quantities/base_qnty.py,sha256=QasOR4-a7gwPBvc6cLJ3ooQHmOcWbYexgtNQ9I6bXI8,32516
+qnty/quantities/field_converters.py,sha256=rDWttIE0lwF1doGlLG5RJTcTikYEYruMrRBMlr8fvBI,1008701
+qnty/quantities/field_qnty.py,sha256=9A-KP8DyO5oOfmxw41HKJq48dUF0LP9M_YYqvdbVvRM,42562
+qnty/quantities/field_setter.py,sha256=JCvRom4qvCYvgRNgFLZEuwb1PCmz0qrKzxDv0-h4RMo,449348
+qnty/quantities/field_vars.py,sha256=mo-kh3WFx6h_dfROUIXAyhdDAoEDEgGN_TlaLwu_o1U,264561
+qnty/quantities/field_vars.pyi,sha256=DJtLmxXJ9MrphAqSSOkMYNlLrq7-mAzvclp6bufT4RY,154868
+qnty/solving/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+qnty/solving/manager.py,sha256=LQBMhWD3ajRYMBXkwRpkVzdo7qVEDviBAoHpjAzS-0U,3945
+qnty/solving/order.py,sha256=q1G3fMWamhmBK6vN0L2BuTqWl0aa94ZJPCWusrntcXo,15488
+qnty/solving/solvers/__init__.py,sha256=7hM2Fz4jCS8xf5Kd3qDqkEmvtT1PO72jXguoQA_Fvqo,475
+qnty/solving/solvers/base.py,sha256=UgXRhnx9m331Hn2P3U-0qTfSQIkfOhEw_MfqcLhxxBM,2839
+qnty/solving/solvers/iterative.py,sha256=dZw66VRz0ScnkPsJl2miKgH7VVcGJQw1zq-5wzU0CZU,7557
+qnty/solving/solvers/simultaneous.py,sha256=hLZ8878BqiI5NQd8eeRG5Sy9ztS43BBX4mk3BDMVs_4,21609
+qnty/units/__init__.py,sha256=WgH6t1obC5i2ioEykO8H3z_csoRL6fP6xjzXn2_EB80,27
+qnty/units/field_units.py,sha256=juW8qzt7UaL4lIMl5p_GVcfH6h6gQz7bFuOUOKRX7rY,283034
+qnty/units/field_units.pyi,sha256=1iW_yWF2PWQ8wZ1vSp2SbHk4A6eiG-Hfw-9VdSBf7s0,77949
+qnty/units/prefixes.py,sha256=tSD8CIPjFtCuwl2Og1a1pmqLoTvfeTljxMqPuHBC_dE,6667
+qnty/units/registry.py,sha256=bfnD4kWkaEnX0Vkb7Dxa1K-YGhtjMNQjevLpcMc7KCQ,6728
+qnty/utils/__init__.py,sha256=r9sYK7anOF5KoDqw6rK0O1dCVXV4MKAtt_4gab7PZIk,533
+qnty/utils/caching/__init__.py,sha256=vgR18cUhDnOkB-3Qv-Kcj0l9lSZ_cD48MSfjaAHKjpA,456
+qnty/utils/caching/manager.py,sha256=B9-p9eD57SjBTZwfa8LqfAwK7arhy0zH7faoE_lQt8M,16893
+qnty/utils/error_handling/__init__.py,sha256=6J8a1NdaeQGtGa6r6Rc-x8FcIc5adJZ6ngm21bZXbFI,1571
+qnty/utils/error_handling/context.py,sha256=hTwQst5sFWKo2UrpH6768ERwqcFfbwVQz8aNuO0fveo,1353
+qnty/utils/error_handling/exceptions.py,sha256=8O0gzoTJqz1Gw9h8sdN16DKIf_ZBn2Lzsu9gyLHknXU,3608
+qnty/utils/error_handling/handlers.py,sha256=_q12co-jr4YSktRoCPpGBbh6WXEDw9MbmWxUge0YWU8,8007
+qnty/utils/logging.py,sha256=2H6_gSOQjxdK5024XTY3E1jGIQPE8WdalVhVBFw51OA,1143
+qnty/utils/protocols.py,sha256=c_Ya_epCm7qenAADRMZiwiQ0PdD-Z4T85b1z1YQNXAk,5247
+qnty/utils/scope_discovery.py,sha256=mQc-FHJ5-VNBzqQwiFofV-hqeF3GpLRaLlTjYDRnOqs,15184
+qnty-0.1.0.dist-info/METADATA,sha256=IEWbkj_Ll1dkIkr50avhKUlChVE6rrAnSy5Bv9y4Ma0,6761
+qnty-0.1.0.dist-info/WHEEL,sha256=b4K_helf-jlQoXBBETfwnf4B04YC67LOev0jo4fX5m8,88
+qnty-0.1.0.dist-info/RECORD,,