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

qnty/expressions/formatter.py

@@ -0,0 +1,188 @@
+"""
+Expression String Formatting System
+===================================
+
+Centralized formatting logic for mathematical expressions with proper
+operator precedence handling and readable output generation.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from .types import BinaryOperationProtocol, ConditionalExpressionProtocol, ConstantProtocol, ExpressionProtocol, UnaryFunctionProtocol, VariableReferenceProtocol
+
+
+class ExpressionFormatter:
+    """
+    Handles string representation of expressions with proper precedence rules.
+
+    Centralizes complex formatting logic that was previously scattered across
+    expression classes, making it easier to maintain and extend.
+    """
+
+    # Operator precedence levels (higher number = higher precedence)
+    OPERATOR_PRECEDENCE = {
+        # Comparison operators (lowest precedence)
+        "<": 0,
+        "<=": 0,
+        ">": 0,
+        ">=": 0,
+        "==": 0,
+        "!=": 0,
+        # Arithmetic operators
+        "+": 1,
+        "-": 1,  # Addition/subtraction
+        "*": 2,
+        "/": 2,  # Multiplication/division
+        "**": 3,  # Exponentiation (highest precedence)
+    }
+
+    # Right-associative operators (most are left-associative by default)
+    RIGHT_ASSOCIATIVE = {"**"}
+
+    # Left-associative operators that need special parenthesization
+    LEFT_ASSOCIATIVE_SPECIAL = {"-", "/"}
+
+    @staticmethod
+    def format_binary_operation(binary_op: BinaryOperationProtocol, can_auto_evaluate: bool = False, auto_eval_variables: dict[str, Any] | None = None) -> str:
+        """
+        Format binary operation with proper parenthesization.
+
+        Args:
+            binary_op: The binary operation to format
+            can_auto_evaluate: Whether auto-evaluation should be attempted
+            auto_eval_variables: Variables for auto-evaluation
+
+        Returns:
+            Formatted string representation
+        """
+        # Try auto-evaluation first if requested
+        if can_auto_evaluate and auto_eval_variables:
+            evaluation_result = ExpressionFormatter._try_evaluate(binary_op, auto_eval_variables)
+            if evaluation_result is not None:
+                return str(evaluation_result)
+
+        # Get string representations of operands
+        left_str = str(binary_op.left)
+        right_str = str(binary_op.right)
+
+        # Apply parenthesization rules
+        left_str = ExpressionFormatter._maybe_parenthesize_left(binary_op.left, binary_op.operator, left_str)
+        right_str = ExpressionFormatter._maybe_parenthesize_right(binary_op.right, binary_op.operator, right_str)
+
+        return f"{left_str} {binary_op.operator} {right_str}"
+
+    @staticmethod
+    def _maybe_parenthesize_left(left_expr: ExpressionProtocol, operator: str, left_str: str) -> str:
+        """Add parentheses to left operand if needed for precedence."""
+        if not ExpressionFormatter._is_binary_operation(left_expr):
+            return left_str
+
+        left_precedence = ExpressionFormatter._get_expression_precedence(left_expr)
+        current_precedence = ExpressionFormatter.get_operator_precedence(operator)
+
+        # Left side needs parentheses only if its precedence is strictly lower
+        if left_precedence < current_precedence:
+            return f"({left_str})"
+
+        return left_str
+
+    @staticmethod
+    def _maybe_parenthesize_right(right_expr: ExpressionProtocol, operator: str, right_str: str) -> str:
+        """Add parentheses to right operand if needed for precedence and associativity."""
+        if not ExpressionFormatter._is_binary_operation(right_expr):
+            return right_str
+
+        right_precedence = ExpressionFormatter._get_expression_precedence(right_expr)
+        current_precedence = ExpressionFormatter.get_operator_precedence(operator)
+
+        # Right side needs parentheses if:
+        # 1. Its precedence is strictly lower, OR
+        # 2. Same precedence AND current operator is left-associative (-, /)
+        needs_parentheses = right_precedence < current_precedence or (right_precedence == current_precedence and operator in ExpressionFormatter.LEFT_ASSOCIATIVE_SPECIAL)
+
+        if needs_parentheses:
+            return f"({right_str})"
+
+        return right_str
+
+    @staticmethod
+    def format_unary_function(func: UnaryFunctionProtocol) -> str:
+        """Format unary function call."""
+        return f"{func.function_name}({func.operand})"
+
+    @staticmethod
+    def format_conditional_expression(cond_expr: ConditionalExpressionProtocol) -> str:
+        """Format conditional expression in if-then-else form."""
+        return f"if({cond_expr.condition}, {cond_expr.true_expr}, {cond_expr.false_expr})"
+
+    @staticmethod
+    def format_variable_reference(var_ref: VariableReferenceProtocol) -> str:
+        """Format variable reference (just the name)."""
+        return var_ref.name
+
+    @staticmethod
+    def format_constant(constant: ConstantProtocol) -> str:
+        """Format constant value."""
+        return str(constant.value)
+
+    @staticmethod
+    def is_operator_right_associative(operator: str) -> bool:
+        """Check if operator is right-associative."""
+        return operator in ExpressionFormatter.RIGHT_ASSOCIATIVE
+
+    @staticmethod
+    def get_operator_precedence(operator: str) -> int:
+        """Get precedence level for operator."""
+        return ExpressionFormatter.OPERATOR_PRECEDENCE.get(operator, 0)
+
+    @staticmethod
+    def _try_evaluate(expression: ExpressionProtocol, variables: dict[str, Any]) -> Any | None:
+        """
+        Safely attempt to evaluate an expression.
+
+        Args:
+            expression: Expression to evaluate
+            variables: Variable context for evaluation
+
+        Returns:
+            Evaluation result or None if evaluation failed
+        """
+        try:
+            return expression.evaluate(variables)
+        except (KeyError, ValueError, TypeError, ZeroDivisionError, AttributeError):
+            # Catch specific exceptions that are expected during evaluation
+            return None
+
+    @staticmethod
+    def _is_binary_operation(expr: ExpressionProtocol) -> bool:
+        """Check if expression is a binary operation using duck typing."""
+        return hasattr(expr, "operator") and hasattr(expr, "left") and hasattr(expr, "right")
+
+    @staticmethod
+    def _get_expression_precedence(expr: ExpressionProtocol) -> int:
+        """Get precedence of an expression if it's a binary operation."""
+        if ExpressionFormatter._is_binary_operation(expr):
+            # We know it's a binary operation from the check above, so it has an operator
+            binary_op = expr  # type: ignore[assignment]
+            return ExpressionFormatter.get_operator_precedence(binary_op.operator)  # type: ignore[attr-defined]
+        return 0
+
+    @staticmethod
+    def format_expression_with_auto_eval(expr: ExpressionProtocol) -> str:
+        """
+        Format expression, attempting auto-evaluation if possible.
+
+        This is a convenience method that handles the common pattern of
+        trying to auto-evaluate before falling back to symbolic representation.
+        """
+        # Check if auto-evaluation is possible for binary operations
+        if ExpressionFormatter._is_binary_operation(expr) and hasattr(expr, "_can_auto_evaluate"):
+            # We know it's a binary operation with auto-evaluation capability
+            binary_op = expr  # type: ignore[assignment]
+            can_eval, variables = binary_op._can_auto_evaluate()  # type: ignore[attr-defined]
+            return ExpressionFormatter.format_binary_operation(binary_op, can_auto_evaluate=can_eval, auto_eval_variables=variables)  # type: ignore[arg-type]
+        else:
+            # For other expression types, just use their standard string representation
+            return str(expr)

qnty/expressions/functions.py

@@ -5,92 +5,70 @@ Expression Helper Functions
 Convenience functions for creating mathematical expressions.
 """
 
-from typing import TYPE_CHECKING, Union
+from ..quantities import FieldQnty, Quantity
+from .nodes import BinaryOperation, ConditionalExpression, Expression, UnaryFunction, wrap_operand
 
-if TYPE_CHECKING:
-    from ..quantities.quantity import Quantity, TypeSafeVariable
-    from .nodes import BinaryOperation, Expression
+# Type aliases for better maintainability
+ExpressionOperand = Expression | FieldQnty | Quantity | int | float
+ConditionalOperand = Expression | BinaryOperation
 
-from .nodes import ConditionalExpression, Expression, UnaryFunction
 
+def _create_unary_function(name: str, docstring: str):
+    """Factory function for creating unary mathematical functions."""
 
-# Convenience functions for mathematical operations
-def sin(expr: Union['Expression', 'TypeSafeVariable', 'Quantity', int, float]) -> UnaryFunction:
-    """Sine function."""
-    return UnaryFunction('sin', Expression._wrap_operand(expr))
+    def func(expr: ExpressionOperand) -> UnaryFunction:
+        return UnaryFunction(name, wrap_operand(expr))
 
+    func.__name__ = name
+    func.__doc__ = docstring
+    return func
 
-def cos(expr: Union['Expression', 'TypeSafeVariable', 'Quantity', int, float]) -> UnaryFunction:
-    """Cosine function."""
-    return UnaryFunction('cos', Expression._wrap_operand(expr))
-
-
-def tan(expr: Union['Expression', 'TypeSafeVariable', 'Quantity', int, float]) -> UnaryFunction:
-    """Tangent function."""
-    return UnaryFunction('tan', Expression._wrap_operand(expr))
-
-
-def sqrt(expr: Union['Expression', 'TypeSafeVariable', 'Quantity', int, float]) -> UnaryFunction:
-    """Square root function."""
-    return UnaryFunction('sqrt', Expression._wrap_operand(expr))
-
-
-def abs_expr(expr: Union['Expression', 'TypeSafeVariable', 'Quantity', int, float]) -> UnaryFunction:
-    """Absolute value function."""
-    return UnaryFunction('abs', Expression._wrap_operand(expr))
 
+def _create_comparison_expr(expressions: tuple[ExpressionOperand, ...], comparator: str) -> Expression:
+    """Create min/max expression using specified comparator."""
+    if len(expressions) < 2:
+        raise ValueError(f"{comparator}_expr requires at least 2 arguments")
 
-def ln(expr: Union['Expression', 'TypeSafeVariable', 'Quantity', int, float]) -> UnaryFunction:
-    """Natural logarithm function."""
-    return UnaryFunction('ln', Expression._wrap_operand(expr))
+    wrapped_expressions = [wrap_operand(expr) for expr in expressions]
+    result = wrapped_expressions[0]
 
+    for expr in wrapped_expressions[1:]:
+        if comparator == "min":
+            # min(a, b) = if(a < b, a, b)
+            result = cond_expr(result < expr, result, expr)
+        else:  # max
+            # max(a, b) = if(a > b, a, b)
+            result = cond_expr(result > expr, result, expr)
 
-def log10(expr: Union['Expression', 'TypeSafeVariable', 'Quantity', int, float]) -> UnaryFunction:
-    """Base-10 logarithm function."""
-    return UnaryFunction('log10', Expression._wrap_operand(expr))
+    return result
 
 
-def exp(expr: Union['Expression', 'TypeSafeVariable', 'Quantity', int, float]) -> UnaryFunction:
-    """Exponential function."""
-    return UnaryFunction('exp', Expression._wrap_operand(expr))
+# Mathematical functions (generated via factory)
+sin = _create_unary_function("sin", "Sine function.")
+cos = _create_unary_function("cos", "Cosine function.")
+tan = _create_unary_function("tan", "Tangent function.")
+sqrt = _create_unary_function("sqrt", "Square root function.")
+abs_expr = _create_unary_function("abs", "Absolute value function.")
+ln = _create_unary_function("ln", "Natural logarithm function.")
+log10 = _create_unary_function("log10", "Base-10 logarithm function.")
+exp = _create_unary_function("exp", "Exponential function.")
 
 
-def cond_expr(condition: Union['Expression', 'BinaryOperation'],
-              true_expr: Union['Expression', 'TypeSafeVariable', 'Quantity', int, float],
-              false_expr: Union['Expression', 'TypeSafeVariable', 'Quantity', int, float]) -> ConditionalExpression:
+def cond_expr(
+    condition: ConditionalOperand,
+    true_expr: ExpressionOperand,
+    false_expr: ExpressionOperand,
+) -> ConditionalExpression:
     """Conditional expression: if condition then true_expr else false_expr."""
-    return ConditionalExpression(
-        condition if isinstance(condition, Expression) else condition,
-        Expression._wrap_operand(true_expr),
-        Expression._wrap_operand(false_expr)
-    )
+    wrapped_condition = condition if isinstance(condition, Expression) else condition
+    return ConditionalExpression(wrapped_condition, wrap_operand(true_expr), wrap_operand(false_expr))
 
 
-def min_expr(*expressions: Union['Expression', 'TypeSafeVariable', 'Quantity', int, float]) -> 'Expression':
+def min_expr(*expressions: ExpressionOperand) -> Expression:
     """Minimum of multiple expressions."""
-    if len(expressions) < 2:
-        raise ValueError("min_expr requires at least 2 arguments")
-    
-    wrapped_expressions = [Expression._wrap_operand(expr) for expr in expressions]
-    result = wrapped_expressions[0]
-    
-    for expr in wrapped_expressions[1:]:
-        # min(a, b) = if(a < b, a, b)
-        result = cond_expr(result < expr, result, expr)
-    
-    return result
+    return _create_comparison_expr(expressions, "min")
 
 
-def max_expr(*expressions: Union['Expression', 'TypeSafeVariable', 'Quantity', int, float]) -> 'Expression':
+def max_expr(*expressions: ExpressionOperand) -> Expression:
     """Maximum of multiple expressions."""
-    if len(expressions) < 2:
-        raise ValueError("max_expr requires at least 2 arguments")
-    
-    wrapped_expressions = [Expression._wrap_operand(expr) for expr in expressions]
-    result = wrapped_expressions[0]
-    
-    for expr in wrapped_expressions[1:]:
-        # max(a, b) = if(a > b, a, b)
-        result = cond_expr(result > expr, result, expr)
-    
-    return result
+    return _create_comparison_expr(expressions, "max")