avada-eval 0.1.0__py3-none-any.whl

avada_eval/__init__.py

@@ -0,0 +1,72 @@
+"""avada_eval: a safe expression evaluator with exact ``decimal.Decimal`` arithmetic.
+
+Drop-in for simpleeval: ``from avada_eval import simple_eval, SimpleEval``.
+The module-level limits (``MAX_POWER``, ``DISALLOW_METHODS`` ...) live in
+``avada_eval.evaluator``; patch them there.
+
+This file only installs the beartype claw hook and re-exports (no function
+definitions: the hook cannot instrument the module that installs it).
+"""
+
+# leaf; deliberately imported before the hook (itself unchecked)
+from avada_eval.core.settings import settings
+
+if settings.beartype_on:
+    from beartype.claw import beartype_this_package
+
+    beartype_this_package()
+
+# ↓ all other package-level imports/exports stay below the hook
+from avada_eval.decimal_ops import format_number
+from avada_eval.evaluator import (
+    BASIC_ALLOWED_ATTRS,
+    DEFAULT_CONTEXT,
+    DEFAULT_FUNCTIONS,
+    DEFAULT_NAMES,
+    DEFAULT_OPERATORS,
+    DecimalLiteral,
+    EvalWithCompoundTypes,
+    ModuleWrapper,
+    SimpleEval,
+    simple_eval,
+)
+from avada_eval.exceptions import (
+    AssignmentAttempted,
+    AttributeDoesNotExist,
+    DivisionByZero,
+    FeatureNotAvailable,
+    FloatNotAllowed,
+    FunctionNotDefined,
+    InvalidExpression,
+    IterableTooLong,
+    MultipleExpressions,
+    NameNotDefined,
+    NumberTooHigh,
+    OperatorNotDefined,
+)
+
+__all__ = [
+    "BASIC_ALLOWED_ATTRS",
+    "DEFAULT_CONTEXT",
+    "DEFAULT_FUNCTIONS",
+    "DEFAULT_NAMES",
+    "DEFAULT_OPERATORS",
+    "AssignmentAttempted",
+    "AttributeDoesNotExist",
+    "DecimalLiteral",
+    "DivisionByZero",
+    "EvalWithCompoundTypes",
+    "FeatureNotAvailable",
+    "FloatNotAllowed",
+    "FunctionNotDefined",
+    "InvalidExpression",
+    "IterableTooLong",
+    "ModuleWrapper",
+    "MultipleExpressions",
+    "NameNotDefined",
+    "NumberTooHigh",
+    "OperatorNotDefined",
+    "SimpleEval",
+    "format_number",
+    "simple_eval",
+]

avada_eval/cli.py

@@ -0,0 +1,102 @@
+"""Command line entry: ``uv run scripts/avada.py "0.1 + 0.2"`` or ``uv run avada ...``.
+
+The result on stdout *is* this command's output contract, so it is written
+with ``sys.stdout.write`` (library code elsewhere never writes to stdout).
+"""
+
+import argparse
+import decimal
+import json
+import sys
+from collections.abc import Sequence
+
+from avada_eval.evaluator import DEFAULT_CONTEXT
+from avada_eval.llm.tool import evaluate_for_llm
+
+_ROUNDING_MODES = [
+    decimal.ROUND_HALF_EVEN,
+    decimal.ROUND_HALF_UP,
+    decimal.ROUND_HALF_DOWN,
+    decimal.ROUND_UP,
+    decimal.ROUND_DOWN,
+    decimal.ROUND_CEILING,
+    decimal.ROUND_FLOOR,
+    decimal.ROUND_05UP,
+]
+
+
+def _parse_variable(item: str) -> tuple[str, object]:
+    name, sep, raw = item.partition("=")
+    if not sep or not name.strip().isidentifier():
+        raise argparse.ArgumentTypeError(f"expected NAME=VALUE, got {item!r}")
+    text = raw.strip()
+    value: object
+    try:
+        value = int(text)
+    except ValueError:
+        try:
+            value = decimal.Decimal(text)
+        except decimal.InvalidOperation:
+            value = raw  # plain string
+    return name.strip(), value
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="avada",
+        description="Evaluate an expression with exact decimal arithmetic.",
+    )
+    parser.add_argument("expression")
+    parser.add_argument(
+        "-v",
+        "--var",
+        action="append",
+        default=[],
+        type=_parse_variable,
+        metavar="NAME=VALUE",
+        help="define a variable (int, exact decimal, or string); repeatable",
+    )
+    parser.add_argument("--prec", type=int, help="significant digits (default 28)")
+    parser.add_argument(
+        "--rounding", choices=_ROUNDING_MODES, help="default ROUND_HALF_EVEN"
+    )
+    parser.add_argument(
+        "--no-thousands", action="store_true", help="disable 1,234 parsing"
+    )
+    parser.add_argument(
+        "--no-percent", action="store_true", help="disable 12.5%% parsing"
+    )
+    parser.add_argument(
+        "--json", action="store_true", help="print the structured result"
+    )
+    return parser
+
+
+def run(argv: Sequence[str] | None = None) -> tuple[int, str]:
+    """Parse ``argv``, evaluate, and return ``(exit_code, text_to_print)``."""
+    args = _build_parser().parse_args(argv)
+    context = DEFAULT_CONTEXT.copy()
+    if args.prec is not None:
+        context.prec = args.prec
+    if args.rounding is not None:
+        context.rounding = args.rounding
+    result = evaluate_for_llm(
+        args.expression,
+        dict(args.var),
+        context=context,
+        thousands=not args.no_thousands,
+        percent=not args.no_percent,
+    )
+    if args.json:
+        text = json.dumps(result.to_dict(), ensure_ascii=False)
+    elif result.ok:
+        text = result.value or ""
+    else:
+        text = f"{result.error_type}: {result.error}"
+    return (0 if result.ok else 1), text
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    code, text = run(argv)
+    sys.stdout.write(text + "\n")
+    return code

avada_eval/core/__init__.py

@@ -0,0 +1,3 @@
+# 必须保持空。
+# 导入 settings(叶子)会先经过本文件;若在此 re-export logging / prompts,
+# 它们会在 beartype claw hook 安装前被导入,从而漏掉运行时类型检查。

avada_eval/core/settings.py

@@ -0,0 +1,39 @@
+"""Package-wide settings: the single source of runtime switches.
+
+beartype leaf: this module must not import any first-party module
+(stdlib only), because the package ``__init__`` imports it *before*
+installing the beartype claw hook.
+
+This is a library that gets imported from arbitrary working directories,
+so -- unlike an application -- it does not locate a project root and reads
+no config files; the only knob is the ``AVADA_BEARTYPE_ON`` environment
+variable (default on; set it to ``false`` to disable runtime type checks).
+"""
+
+import os
+from dataclasses import dataclass
+from functools import lru_cache
+
+_FALSE_VALUES = frozenset({"0", "false", "no", "off"})
+
+
+@dataclass(frozen=True)
+class Settings:
+    beartype_on: bool = True
+
+
+def _env_flag(name: str, *, default: bool) -> bool:
+    raw = os.getenv(name)
+    if raw is None or not raw.strip():
+        return default
+    return raw.strip().lower() not in _FALSE_VALUES
+
+
+@lru_cache(maxsize=1)
+def get_settings() -> Settings:
+    """Runtime accessor; tests may ``get_settings.cache_clear()`` after setenv."""
+    return Settings(beartype_on=_env_flag("AVADA_BEARTYPE_ON", default=True))
+
+
+settings = get_settings()
+"""Import-time singleton, used only by the beartype hook in ``__init__``."""

avada_eval/decimal_ops.py

@@ -0,0 +1,152 @@
+"""Pure ``decimal.Decimal`` helpers used by the evaluator and its default functions.
+
+Everything here runs inside the evaluator's ``localcontext`` (precision and
+rounding come from ``decimal.getcontext()``), and nothing ever calls
+``Decimal(float)``: binary floats are converted through ``str`` (their
+shortest round-trip repr), literals come from the source text.
+"""
+
+import decimal
+from collections.abc import Iterable
+from decimal import Decimal
+from typing import Literal
+
+FloatPolicy = Literal["convert", "error"]
+
+# Plain (non-scientific) notation is used by format_number while the
+# decimal exponent stays inside this window; outside it, str() is kept.
+_PLAIN_MIN_ADJUSTED = -30
+_PLAIN_MAX_ADJUSTED = 60
+
+
+def float_to_decimal(value: float) -> Decimal:
+    """``Decimal(str(x))``: 0.1 -> Decimal('0.1'), never 0.1000000000000000055..."""
+    return Decimal(str(value))
+
+
+def literal_to_decimal(source: str, value: float) -> Decimal:
+    """Exact Decimal for a float literal, from its *source text*.
+
+    ``value`` is what ``ast`` parsed; it is only used to verify that the
+    source segment really is that literal (loud failure instead of a
+    silently wrong number).
+    """
+    result = Decimal(source)
+    if float(source) != value:
+        raise ValueError(f"source segment {source!r} does not match literal {value!r}")
+    return result
+
+
+def to_decimal(value: object) -> Decimal:
+    """Convert int / bool / Decimal / float / numeric string to Decimal exactly."""
+    if isinstance(value, Decimal):
+        return value
+    if isinstance(value, int):
+        return Decimal(int(value))
+    if isinstance(value, float):
+        return float_to_decimal(value)
+    if isinstance(value, str):
+        text = value.strip()
+        try:
+            return Decimal(text)
+        except decimal.InvalidOperation:
+            raise ValueError(
+                f"could not convert string to decimal: {value!r}"
+            ) from None
+    raise TypeError(f"cannot convert {type(value).__name__} to decimal")
+
+
+def coerce_number(value: object) -> object:
+    """Floats become Decimal (via str); everything else is returned unchanged."""
+    if isinstance(value, float):
+        return float_to_decimal(value)
+    return value
+
+
+def floor_divmod(a: Decimal, b: Decimal) -> tuple[Decimal, Decimal]:
+    """``divmod`` with Python's *floor* semantics (Decimal's own truncates).
+
+    ``Decimal(-7) // 2`` is ``-3`` in the decimal module, but ``-7 // 2`` is
+    ``-4`` for int and float; we keep the int/float behaviour so switching
+    a number between int and Decimal never changes ``//`` or ``%``.
+    """
+    q, r = divmod(a, b)
+    if r and (r < 0) != (b < 0):
+        q -= 1
+        r += b
+    return q, r
+
+
+def decimal_round(number: object, ndigits: int | None = None) -> Decimal:
+    """``round()`` returning a Decimal, using the *context's* rounding mode.
+
+    ``round(2.675, 2)`` -> ``Decimal('2.68')`` under ROUND_HALF_UP and
+    ``Decimal('2.68')`` under ROUND_HALF_EVEN too (the literal is exact, so
+    there is no binary-float surprise); ``round(0.125, 2)`` differs between
+    the two modes (0.13 vs 0.12).
+    """
+    if isinstance(number, bool) or not isinstance(number, int | Decimal | float):
+        raise TypeError(f"round() expects a number, got {type(number).__name__}")
+    if ndigits is not None and (
+        isinstance(ndigits, bool) or not isinstance(ndigits, int)
+    ):
+        raise TypeError("round() ndigits must be an integer")
+    value = to_decimal(number)
+    exponent = Decimal(1).scaleb(-(ndigits or 0))
+    return value.quantize(exponent)
+
+
+Number = int | Decimal
+
+
+def _as_number(value: object) -> Number:
+    value = coerce_number(value)
+    if isinstance(value, int | Decimal):
+        return value
+    raise TypeError(f"expected a number, got {type(value).__name__}")
+
+
+def _numbers(args: tuple[object, ...]) -> list[Number]:
+    items: Iterable[object]
+    if (
+        len(args) == 1
+        and isinstance(args[0], Iterable)
+        and not isinstance(args[0], str)
+    ):
+        items = args[0]
+    else:
+        items = args
+    return [_as_number(x) for x in items]
+
+
+def decimal_min(*args: object) -> Number:
+    """``min`` over numbers (one iterable or several args); floats coerced first."""
+    values = _numbers(args)
+    if not values:
+        raise ValueError("min() arg is an empty sequence")
+    return min(values)
+
+
+def decimal_max(*args: object) -> Number:
+    """``max`` over numbers (one iterable or several args); floats coerced first."""
+    values = _numbers(args)
+    if not values:
+        raise ValueError("max() arg is an empty sequence")
+    return max(values)
+
+
+def decimal_sum(iterable: Iterable[object], start: object = 0) -> Number:
+    """``sum`` over numbers with floats coerced to Decimal; additions follow the context."""
+    total = _as_number(start)
+    for item in iterable:
+        total += _as_number(item)
+    return total
+
+
+def format_number(value: object) -> str:
+    """Human/LLM friendly text: plain notation for Decimals of sane magnitude."""
+    if isinstance(value, Decimal) and value.is_finite():
+        adjusted = value.adjusted()
+        if _PLAIN_MIN_ADJUSTED <= adjusted <= _PLAIN_MAX_ADJUSTED:
+            return format(value, "f")
+    return str(value)