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

qnty/utils/error_handling/handlers.py

@@ -0,0 +1,171 @@
+"""
+Error handlers and logging functionality for the Qnty library.
+
+This module provides centralized error handling with consistent logging
+and context management.
+"""
+
+import logging
+from typing import Any
+
+from .context import ErrorContext, create_context, get_dimension_string
+from .exceptions import (
+    DimensionalError,
+    DivisionByZeroError,
+    EquationSolvingError,
+    ExpressionEvaluationError,
+    QntyError,
+    UnitConversionError,
+    VariableNotFoundError,
+)
+
+
+class ErrorHandler:
+    """
+    Centralized error handling with consistent logging and context management.
+
+    Provides methods for handling common error patterns across the library.
+    """
+
+    def __init__(self, logger: logging.Logger | None = None):
+        """Initialize error handler with optional custom logger."""
+        self.logger = logger or logging.getLogger(__name__)
+
+    def handle_dimensional_error(self, operation: str, left: Any, right: Any, context: ErrorContext | None = None) -> None:
+        """Handle dimensional compatibility errors."""
+        left_dim = get_dimension_string(left)
+        right_dim = get_dimension_string(right)
+
+        error_context = context.to_dict() if context else {}
+
+        self.logger.error(f"Dimensional error in {operation}: {left_dim} vs {right_dim}", extra=error_context)
+        raise DimensionalError(operation, left_dim, right_dim, error_context)
+
+    def handle_unit_conversion_error(self, from_unit: str, to_unit: str, reason: str = "", context: ErrorContext | None = None) -> None:
+        """Handle unit conversion errors."""
+        error_context = context.to_dict() if context else {}
+
+        self.logger.error(f"Unit conversion failed: {from_unit} -> {to_unit} ({reason})", extra=error_context)
+        raise UnitConversionError(from_unit, to_unit, reason, error_context)
+
+    def handle_variable_not_found(self, variable_name: str, available_vars: list[str] | None = None, context: ErrorContext | None = None) -> None:
+        """Handle variable not found errors."""
+        error_context = context.to_dict() if context else {}
+        available_list = available_vars or []
+
+        self.logger.error(f"Variable not found: {variable_name} (available: {available_list})", extra=error_context)
+        raise VariableNotFoundError(variable_name, available_list, error_context)
+
+    def handle_equation_solving_error(self, equation_name: str, target_var: str, reason: str = "", context: ErrorContext | None = None) -> None:
+        """Handle equation solving errors."""
+        error_context = context.to_dict() if context else {}
+
+        self.logger.error(f"Equation solving failed: {equation_name} for {target_var} ({reason})", extra=error_context)
+        raise EquationSolvingError(equation_name, target_var, reason, error_context)
+
+    def handle_expression_evaluation_error(self, expression: str, reason: str = "", context: ErrorContext | None = None) -> None:
+        """Handle expression evaluation errors."""
+        error_context = context.to_dict() if context else {}
+
+        self.logger.error(f"Expression evaluation failed: {expression} ({reason})", extra=error_context)
+        raise ExpressionEvaluationError(expression, reason, error_context)
+
+    def handle_division_by_zero(self, dividend: Any, context: ErrorContext | None = None) -> None:
+        """Handle division by zero errors."""
+        error_context = context.to_dict() if context else {}
+        dividend_str = str(dividend)
+
+        self.logger.error(f"Division by zero: {dividend_str}", extra=error_context)
+        raise DivisionByZeroError(dividend_str, error_context)
+
+    def handle_unexpected_error(self, original_error: Exception, operation: str, context: ErrorContext | None = None) -> None:
+        """Handle unexpected errors with proper context and chaining."""
+        error_context = context.to_dict() if context else {}
+
+        self.logger.error(f"Unexpected error in {operation}: {original_error}", extra=error_context, exc_info=True)
+
+        # Re-raise as QntyError with context
+        raise QntyError(f"Unexpected error in {operation}: {original_error}", error_context) from original_error
+
+    @staticmethod
+    def create_context(module: str, function: str, operation: str, **kwargs) -> ErrorContext:
+        """Create error context for consistent error reporting."""
+        return create_context(module, function, operation, **kwargs)
+
+
+class ErrorHandlerMixin:
+    """
+    Mixin class that provides error handling methods to any class.
+
+    Usage:
+        class MyClass(ErrorHandlerMixin):
+            def some_method(self):
+                try:
+                    # risky operation
+                    pass
+                except Exception as e:
+                    self.handle_error(e, "some_operation")
+    """
+
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        self._error_handler = ErrorHandler(logging.getLogger(self.__class__.__module__))
+
+    def handle_error(self, error: Exception, operation: str, **context_kwargs) -> None:
+        """Handle errors with automatic context creation."""
+        context = ErrorContext(module=self.__class__.__module__, function=operation, operation=operation, additional_info=context_kwargs)
+        self._error_handler.handle_unexpected_error(error, operation, context)
+
+    def require_variable(self, var_name: str, variables: dict[str, Any]) -> Any:
+        """Require a variable to exist, raising consistent error if not found."""
+        if var_name not in variables:
+            context = self._error_handler.create_context(self.__class__.__module__, "require_variable", "variable_lookup", requested_variable=var_name)
+            self._error_handler.handle_variable_not_found(var_name, list(variables.keys()), context)
+        return variables[var_name]
+
+    def ensure_dimensional_compatibility(self, left: Any, right: Any, operation: str) -> None:
+        """Ensure two quantities have compatible dimensions for the given operation."""
+        if hasattr(left, "_dimension_sig") and hasattr(right, "_dimension_sig"):
+            if left._dimension_sig != right._dimension_sig:
+                context = self._error_handler.create_context(self.__class__.__module__, "ensure_dimensional_compatibility", operation)
+                self._error_handler.handle_dimensional_error(operation, left, right, context)
+
+
+# Global error handler instance
+_default_error_handler = ErrorHandler()
+
+
+def get_error_handler() -> ErrorHandler:
+    """Get the global error handler instance."""
+    return _default_error_handler
+
+
+def set_error_handler(handler: ErrorHandler) -> None:
+    """Set a custom global error handler."""
+    global _default_error_handler
+    _default_error_handler = handler
+
+
+# Convenience functions for common error patterns
+def require_variable(var_name: str, variables: dict[str, Any], context: ErrorContext | None = None) -> Any:
+    """Require a variable to exist, raising consistent error if not found."""
+    if var_name not in variables:
+        _default_error_handler.handle_variable_not_found(var_name, list(variables.keys()), context)
+    return variables[var_name]
+
+
+def ensure_not_zero(value: Any, context: ErrorContext | None = None) -> None:
+    """Ensure a value is not zero for division operations."""
+    if hasattr(value, "value") and abs(value.value) < 1e-15:
+        _default_error_handler.handle_division_by_zero(value, context)
+    elif isinstance(value, int | float) and abs(value) < 1e-15:
+        _default_error_handler.handle_division_by_zero(value, context)
+
+
+def safe_evaluate(expression: Any, variables: dict[str, Any], context: ErrorContext | None = None) -> Any:
+    """Safely evaluate an expression with consistent error handling."""
+    try:
+        return expression.evaluate(variables)
+    except Exception as e:
+        error_context = context or ErrorContext("unknown", "safe_evaluate", "expression_evaluation")
+        _default_error_handler.handle_expression_evaluation_error(str(expression), str(e), error_context)

qnty/utils/logging.py

@@ -0,0 +1,40 @@
+import logging
+import os
+
+_LOGGER: logging.Logger | None = None
+
+
+def get_logger(name: str = "qnty") -> logging.Logger:
+    """Return a module-level configured logger.
+
+    Log level resolves in order:
+    1. Explicit environment variable QNTY_LOG_LEVEL
+    2. Existing logger level if already configured
+    3. Defaults to INFO
+    """
+    global _LOGGER
+    if _LOGGER is not None:
+        return _LOGGER
+
+    logger = logging.getLogger(name)
+    if not logger.handlers:
+        # Basic handler (stdout)
+        handler = logging.StreamHandler()
+        fmt = os.getenv("QNTY_LOG_FORMAT", "%(asctime)s | %(levelname)s | %(name)s | %(message)s")
+        handler.setFormatter(logging.Formatter(fmt))
+        logger.addHandler(handler)
+
+    # Resolve level
+    level_str = os.getenv("QNTY_LOG_LEVEL", "INFO").upper()
+    level = getattr(logging, level_str, logging.INFO)
+    logger.setLevel(level)
+    logger.propagate = False
+
+    _LOGGER = logger
+    return logger
+
+
+def set_log_level(level: str):
+    """Dynamically adjust log level at runtime."""
+    logger = get_logger()
+    logger.setLevel(getattr(logging, level.upper(), logging.INFO))

qnty/utils/protocols.py

@@ -0,0 +1,164 @@
+"""
+Performance-Optimized Protocols for Qnty
+=========================================
+
+Type protocols and registration system to avoid duck typing and circular imports
+while maintaining maximum performance.
+"""
+
+from abc import abstractmethod
+from typing import Protocol, runtime_checkable
+
+
+@runtime_checkable
+class ExpressionProtocol(Protocol):
+    """
+    Protocol for objects that can be evaluated as expressions.
+
+    This avoids the need to import the actual Expression class,
+    preventing circular imports while maintaining type safety.
+    """
+
+    @abstractmethod
+    def get_variables(self) -> set[str]:
+        """Get all variable symbols used in this expression."""
+        ...
+
+    @abstractmethod
+    def evaluate(self, variable_values: dict) -> object:
+        """Evaluate the expression given variable values."""
+        ...
+
+
+@runtime_checkable
+class VariableProtocol(Protocol):
+    """
+    Protocol for variable objects that can be discovered in scope.
+
+    This defines the interface that the scope discovery service expects
+    without importing the actual variable classes.
+    """
+
+    @property
+    @abstractmethod
+    def name(self) -> str:
+        """Variable name."""
+        ...
+
+    @property
+    @abstractmethod
+    def symbol(self) -> str | None:
+        """Variable symbol (preferred over name for equations)."""
+        ...
+
+    @property
+    @abstractmethod
+    def quantity(self) -> object | None:
+        """The underlying quantity object."""
+        ...
+
+
+class TypeRegistry:
+    """
+    High-performance type registry using class caching.
+
+    This eliminates the need for duck typing by maintaining a cache
+    of known types and their capabilities.
+    """
+
+    # Class-level caches for maximum performance
+    _expression_types: set[type] = set()
+    _variable_types: set[type] = set()
+    _type_cache: dict[type, tuple[bool, bool]] = {}  # (is_expression, is_variable)
+
+    @classmethod
+    def register_expression_type(cls, expression_type: type) -> None:
+        """Register a type as an expression type."""
+        cls._expression_types.add(expression_type)
+        cls._invalidate_cache_for_type(expression_type)
+
+    @classmethod
+    def register_variable_type(cls, variable_type: type) -> None:
+        """Register a type as a variable type."""
+        cls._variable_types.add(variable_type)
+        cls._invalidate_cache_for_type(variable_type)
+
+    @classmethod
+    def is_expression(cls, obj: object) -> bool:
+        """
+        Check if object is an expression with maximum performance.
+
+        Uses cached type checking to avoid repeated isinstance calls.
+        """
+        obj_type = type(obj)
+
+        if obj_type not in cls._type_cache:
+            # Check if this type is registered as an expression type
+            is_expr = any(isinstance(obj, expr_type) for expr_type in cls._expression_types)
+
+            # Also check protocol compliance as fallback
+            if not is_expr:
+                is_expr = isinstance(obj, ExpressionProtocol)
+
+            # Check if it's a variable too (for dual-purpose cache entry)
+            is_var = any(isinstance(obj, var_type) for var_type in cls._variable_types)
+            if not is_var:
+                is_var = isinstance(obj, VariableProtocol)
+
+            cls._type_cache[obj_type] = (is_expr, is_var)
+
+        return cls._type_cache[obj_type][0]
+
+    @classmethod
+    def is_variable(cls, obj: object) -> bool:
+        """
+        Check if object is a variable with maximum performance.
+
+        Uses cached type checking to avoid repeated isinstance calls.
+        """
+        obj_type = type(obj)
+
+        if obj_type not in cls._type_cache:
+            # This will populate the cache for both expression and variable
+            cls.is_expression(obj)
+
+        return cls._type_cache[obj_type][1]
+
+    @classmethod
+    def _invalidate_cache_for_type(cls, type_to_invalidate: type) -> None:
+        """Invalidate cache entries for a specific type."""
+        # Remove any cached entries that might be affected
+        keys_to_remove = [k for k in cls._type_cache.keys() if issubclass(k, type_to_invalidate)]
+        for key in keys_to_remove:
+            del cls._type_cache[key]
+
+    @classmethod
+    def clear_cache(cls) -> None:
+        """Clear all caches (for testing)."""
+        cls._type_cache.clear()
+
+    @classmethod
+    def get_cache_stats(cls) -> dict[str, int]:
+        """Get cache statistics for monitoring."""
+        return {"expression_types_registered": len(cls._expression_types), "variable_types_registered": len(cls._variable_types), "cached_types": len(cls._type_cache)}
+
+
+# Convenience functions for backwards compatibility
+def register_expression_type(expression_type: type) -> None:
+    """Register a type as an expression type."""
+    TypeRegistry.register_expression_type(expression_type)
+
+
+def register_variable_type(variable_type: type) -> None:
+    """Register a type as a variable type."""
+    TypeRegistry.register_variable_type(variable_type)
+
+
+def is_expression(obj: object) -> bool:
+    """Check if object is an expression."""
+    return TypeRegistry.is_expression(obj)
+
+
+def is_variable(obj: object) -> bool:
+    """Check if object is a variable."""
+    return TypeRegistry.is_variable(obj)