pyformula 0.1.0__py3-none-any.whl

pyformula/__init__.py

@@ -0,0 +1,26 @@
+from .compiler.compiler import FormulaCompiler
+from .compiler.models import Expression
+from .exceptions import (
+    FormulaAlreadyRegisteredError,
+    FormulaNotFoundError,
+    FormulaNotRegisteredError,
+)
+from .formula import Formula
+from .models import Number, Operator
+from .operator import OperatorFn
+from .registry import VariablesRegistry
+from .variable import variable
+
+__all__ = [
+    "Expression",
+    "Formula",
+    "FormulaAlreadyRegisteredError",
+    "FormulaCompiler",
+    "FormulaNotFoundError",
+    "FormulaNotRegisteredError",
+    "Number",
+    "Operator",
+    "OperatorFn",
+    "VariablesRegistry",
+    "variable",
+]

pyformula/compiler/compiler.py

@@ -0,0 +1,160 @@
+from collections.abc import Callable
+from decimal import Decimal
+from typing import Any, cast
+
+from pyformula import math
+from pyformula.exceptions import FormulaNotFoundError, InvalidExpressionError
+from pyformula.formula import Formula
+from pyformula.operator import OPERATORS
+
+from .models import Expression, FormulaDict, is_formula_dict, is_round_wrapper_dict
+
+WRAPPER_FNS: dict[str, Callable[[Formula[Any]], Formula[Any]]] = {
+    "positive": lambda fm: +fm,
+    "negative": lambda fm: -fm,
+    "absolute": abs,
+    "ceil": math.ceil,
+    "floor": math.floor,
+    "trunc": math.trunc,
+    "sqrt": math.sqrt,
+    "cbrt": math.cbrt,
+    "exp": math.exp,
+    "exp2": math.exp2,
+    "expm1": math.expm1,
+    "log10": math.log10,
+    "log1p": math.log1p,
+    "log2": math.log2,
+    "sin": math.sin,
+    "sinh": math.sinh,
+    "asin": math.asin,
+    "asinh": math.asinh,
+    "cos": math.cos,
+    "cosh": math.cosh,
+    "acos": math.acos,
+    "acosh": math.acosh,
+    "tan": math.tan,
+    "tanh": math.tanh,
+    "atan": math.atan,
+    "atanh": math.atanh,
+    "degrees": math.degrees,
+    "radians": math.radians,
+    "erf": math.erf,
+    "erfc": math.erfc,
+    "gamma": math.gamma,
+    "lgamma": math.lgamma,
+    "fabs": math.fabs,
+    "ulp": math.ulp,
+}
+
+
+class FormulaCompiler[T]:
+    """Compile a structured expression tree into a runtime formula.
+
+    Examples:
+    ```python
+    from dataclasses import dataclass
+    from pyformula import Formula
+
+
+    @dataclass
+    class Rectangular:
+        width: float
+        height: float
+
+
+    def main() -> None:
+        fms: dict[str, Formula[Rectangular]] = {
+            "width": Formula[Rectangular](lambda rectangle: rectangle.width),
+            "height": Formula[Rectangular](lambda rectangle: rectangle.height),
+        }
+
+        compiler = FormulaCompiler[Rectangular](fms)
+
+        perimeter = compiler.compile(
+            {
+                "operator": "multiply",
+                "expressions":[
+                    "operator": "add",
+                    "expressions": [
+                        "width",
+                        "height",
+                    ], 2,
+                ]
+            }
+        )
+
+        area = compiler.compile(
+            {
+                "operator": "multiply",
+                "expressions": [
+                    "width",
+                    "height",
+                ],
+            }
+        )
+
+        print(perimeter(Rectangular(width=10, height=20)))  # 60.0
+        print(area(Rectangular(width=10, height=20)))  # 200.0
+
+        print(perimeter(Rectangular(width=5, height=10)))  # 30.0
+        print(area(Rectangular(width=5, height=10)))  # 50.0
+
+
+    if __name__ == "__main__":
+        main()
+    ```
+
+
+    """
+
+    def __init__(self, fns: dict[str, Formula[T]], /) -> None:
+        self._fns = fns
+
+    def compile(self, expression: Expression) -> Formula[T]:
+        """Compile an expression object into a formula callable for a given model type."""
+        if isinstance(expression, (int, float, Decimal)):
+            return Formula(lambda _: expression)
+
+        if isinstance(expression, str) and expression not in self._fns:
+            raise FormulaNotFoundError(expression)
+
+        if isinstance(expression, str):
+            return self._fns[expression]
+
+        if is_formula_dict(expression):
+            return self._compile_formula(expression)
+
+        if is_round_wrapper_dict(expression) and not isinstance(expression["ndigits"], int):
+            raise InvalidExpressionError(expression)
+
+        if is_round_wrapper_dict(expression):
+            return round(self.compile(expression["round"]), ndigits=expression["ndigits"])
+
+        if not isinstance(expression, dict):
+            raise InvalidExpressionError(expression)
+
+        for fn_name, wrap in WRAPPER_FNS.items():
+            if fn_name in expression and len(expression) == 1:
+                return wrap(self.compile(expression[fn_name]))
+
+        raise InvalidExpressionError(expression)
+
+    def _compile_formula(self, fm_dict: FormulaDict) -> Formula[T]:
+        expressions = fm_dict["expressions"]
+        operator = fm_dict["operator"]
+
+        if (
+            not isinstance(expressions, list)
+            or not expressions
+            or not isinstance(operator, str)
+            or operator not in OPERATORS
+        ):
+            raise InvalidExpressionError(fm_dict)
+
+        formula = self.compile(expressions[0])
+        applier, _ = OPERATORS[operator]
+
+        for expression in expressions[1:]:
+            formula = applier(formula, self.compile(expression))
+
+        return cast("Formula[T]", formula)

pyformula/compiler/models.py

@@ -0,0 +1,330 @@
+from typing import TypeAlias, TypedDict, TypeGuard
+
+from pyformula.models import Number, Operator
+
+# -----------------------
+# basic operators
+# -----------------------
+
+
+class PositiveWrapperDict(TypedDict):
+    """Typed dict for a unary positive wrapper expression."""
+
+    positive: "Expression"
+
+
+class NegativeWrapperDict(TypedDict):
+    """Typed dict for a unary negative wrapper expression."""
+
+    negative: "Expression"
+
+
+class AbsoluteWrapperDict(TypedDict):
+    """Typed dict for an absolute-value wrapper expression."""
+
+    absolute: "Expression"
+
+
+class RoundWrapperDict(TypedDict):
+    """Typed dict for a round wrapper that carries an integer precision."""
+
+    round: "Expression"
+    ndigits: int
+
+
+def is_round_wrapper_dict(obj: object) -> TypeGuard[RoundWrapperDict]:
+    """Return whether the object matches the round-wrapper schema."""
+    return _is_typed_dict(obj, "round", "ndigits")
+
+
+# -----------------------
+# rounding
+# -----------------------
+
+
+class FloorWrapperDict(TypedDict):
+    """Typed dict for a floor wrapper expression."""
+
+    floor: "Expression"
+
+
+class CeilWrapperDict(TypedDict):
+    """Typed dict for a ceil wrapper expression."""
+
+    ceil: "Expression"
+
+
+class TruncWrapperDict(TypedDict):
+    """Typed dict for a trunc wrapper expression."""
+
+    trunc: "Expression"
+
+
+# -----------------------
+# roots and powers
+# -----------------------
+
+
+class SqrtWrapperDict(TypedDict):
+    """Typed dict for a square-root wrapper expression."""
+
+    sqrt: "Expression"
+
+
+class CbrtWrapperDict(TypedDict):
+    """Typed dict for a cube-root wrapper expression."""
+
+    cbrt: "Expression"
+
+
+# ----------------------------------------------
+# exponential and logarithmic
+# ----------------------------------------------
+
+
+class ExpWrapperDict(TypedDict):
+    """Typed dict for an exp wrapper expression."""
+
+    exp: "Expression"
+
+
+class Exp2WrapperDict(TypedDict):
+    """Typed dict for an exp2 wrapper expression."""
+
+    exp2: "Expression"
+
+
+class Expm1WrapperDict(TypedDict):
+    """Typed dict for an expm1 wrapper expression."""
+
+    expm1: "Expression"
+
+
+class Log10WrapperDict(TypedDict):
+    """Typed dict for a log10 wrapper expression."""
+
+    log10: "Expression"
+
+
+class Log1pWrapperDict(TypedDict):
+    """Typed dict for a log1p wrapper expression."""
+
+    log1p: "Expression"
+
+
+class Log2WrapperDict(TypedDict):
+    """Typed dict for a log2 wrapper expression."""
+
+    log2: "Expression"
+
+
+# ----------------------------------------------
+# trigonometry
+# ----------------------------------------------
+
+
+class SinWrapperDict(TypedDict):
+    """Typed dict for a sine wrapper expression."""
+
+    sin: "Expression"
+
+
+class SinhWrapperDict(TypedDict):
+    """Typed dict for a hyperbolic sine wrapper expression."""
+
+    sinh: "Expression"
+
+
+class AsinWrapperDict(TypedDict):
+    """Typed dict for an arc-sine wrapper expression."""
+
+    asin: "Expression"
+
+
+class AsinhWrapperDict(TypedDict):
+    """Typed dict for an inverse hyperbolic sine wrapper expression."""
+
+    asinh: "Expression"
+
+
+class CosWrapperDict(TypedDict):
+    """Typed dict for a cosine wrapper expression."""
+
+    cos: "Expression"
+
+
+class CoshWrapperDict(TypedDict):
+    """Typed dict for a hyperbolic cosine wrapper expression."""
+
+    cosh: "Expression"
+
+
+class AcosWrapperDict(TypedDict):
+    """Typed dict for an arc-cosine wrapper expression."""
+
+    acos: "Expression"
+
+
+class AcoshWrapperDict(TypedDict):
+    """Typed dict for an inverse hyperbolic cosine wrapper expression."""
+
+    acosh: "Expression"
+
+
+class TanWrapperDict(TypedDict):
+    """Typed dict for a tangent wrapper expression."""
+
+    tan: "Expression"
+
+
+class TanhWrapperDict(TypedDict):
+    """Typed dict for a hyperbolic tangent wrapper expression."""
+
+    tanh: "Expression"
+
+
+class AtanWrapperDict(TypedDict):
+    """Typed dict for an arc-tangent wrapper expression."""
+
+    atan: "Expression"
+
+
+class AtanhWrapperDict(TypedDict):
+    """Typed dict for an inverse hyperbolic tangent wrapper expression."""
+
+    atanh: "Expression"
+
+
+# ----------------------------------------------
+# angular conversion
+# ----------------------------------------------
+
+
+class DegreesWrapperDict(TypedDict):
+    """Typed dict for a degrees-conversion wrapper expression."""
+
+    degrees: "Expression"
+
+
+class RadiansWrapperDict(TypedDict):
+    """Typed dict for a radians-conversion wrapper expression."""
+
+    radians: "Expression"
+
+
+# ----------------------------------------------
+# special functions
+# ----------------------------------------------
+
+
+class ErfWrapperDict(TypedDict):
+    """Typed dict for an error-function wrapper expression."""
+
+    erf: "Expression"
+
+
+class ErfcWrapperDict(TypedDict):
+    """Typed dict for a complementary error-function wrapper expression."""
+
+    erfc: "Expression"
+
+
+class GammaWrapperDict(TypedDict):
+    """Typed dict for a gamma-function wrapper expression."""
+
+    gamma: "Expression"
+
+
+class LgammaWrapperDict(TypedDict):
+    """Typed dict for a logarithmic gamma wrapper expression."""
+
+    lgamma: "Expression"
+
+
+class FabsWrapperDict(TypedDict):
+    """Typed dict for a floating-point absolute-value wrapper expression."""
+
+    fabs: "Expression"
+
+
+class UlpWrapperDict(TypedDict):
+    """Typed dict for an ulp wrapper expression."""
+
+    ulp: "Expression"
+
+
+# -----------------------
+# formula
+# -----------------------
+
+
+Expression: TypeAlias = "FormulaDict | WrapperDict | str | Number"
+
+
+WrapperDict: TypeAlias = (
+    # basic operators
+    PositiveWrapperDict
+    | NegativeWrapperDict
+    | AbsoluteWrapperDict
+    | RoundWrapperDict
+    # rounding
+    | FloorWrapperDict
+    | CeilWrapperDict
+    | TruncWrapperDict
+    # roots and powers
+    | SqrtWrapperDict
+    | CbrtWrapperDict
+    # exponential and logarithmic
+    | ExpWrapperDict
+    | Exp2WrapperDict
+    | Expm1WrapperDict
+    | Log10WrapperDict
+    | Log1pWrapperDict
+    | Log2WrapperDict
+    # trigonometry
+    | SinWrapperDict
+    | SinhWrapperDict
+    | AsinWrapperDict
+    | AsinhWrapperDict
+    | CosWrapperDict
+    | CoshWrapperDict
+    | AcosWrapperDict
+    | AcoshWrapperDict
+    | TanWrapperDict
+    | TanhWrapperDict
+    | AtanWrapperDict
+    | AtanhWrapperDict
+    # angular conversion
+    | DegreesWrapperDict
+    | RadiansWrapperDict
+    # special functions
+    | ErfWrapperDict
+    | ErfcWrapperDict
+    | GammaWrapperDict
+    | LgammaWrapperDict
+    | FabsWrapperDict
+    | UlpWrapperDict
+)
+
+
+class FormulaDict(TypedDict):
+    """Typed dict describing a binary operation expression tree."""
+
+    operator: Operator
+    expressions: list["Expression"]
+
+
+def is_formula_dict(obj: object) -> TypeGuard[FormulaDict]:
+    """Return whether the object matches the binary-formula schema."""
+    return _is_typed_dict(obj, "operator", "expressions")
+
+
+# -----------------------
+# helper
+# -----------------------
+
+
+def _is_typed_dict(obj: object, *keys: str) -> bool:
+    return (
+        isinstance(obj, dict) and all(key in obj for key in keys) and len(obj.keys()) == len(keys)
+    )

pyformula/exceptions.py

@@ -0,0 +1,29 @@
+from typing import Any
+
+
+class FormulaAlreadyRegisteredError(Exception):
+    """Raised when attempting to register a formula name that already exists."""
+
+    def __init__(self, name: str) -> None:
+        super().__init__(f"Formula already registered: {name}")
+
+
+class FormulaNotRegisteredError(Exception):
+    """Raised when a requested formula name has not been registered."""
+
+    def __init__(self, name: str) -> None:
+        super().__init__(f"Formula not registered: {name}")
+
+
+class FormulaNotFoundError(Exception):
+    """Raised when a compiled expression references a formula that is not in scope."""
+
+    def __init__(self, name: str) -> None:
+        super().__init__(f"Formula not found: {name}")
+
+
+class InvalidExpressionError(Exception):
+    """Raised when an expression structure does not match the compiler schema."""
+
+    def __init__(self, expression: Any, /) -> None:
+        super().__init__(f"Invalid expression: {expression}")