formulon 0.9.0__py3-none-any.whl

formulon/__init__.py

@@ -0,0 +1,84 @@
+# Copyright 2026 libraz. Licensed under the Apache License, Version 2.0.
+"""Formulon -- Excel 365 calculation engine, Python binding.
+
+Public API:
+  * :func:`eval_formula` -- one-shot formula evaluation.
+  * :func:`library_version` -- query the underlying ``libformulon`` build.
+  * :class:`Workbook` -- full workbook lifecycle.
+  * :class:`Value`, :class:`ValueKind` -- cell value POD.
+  * :class:`FormulonError` -- host-side failure exception.
+
+Cell-level Excel errors (``#DIV/0!`` and friends) surface as ``Value``
+instances with ``kind == ValueKind.ERROR``; only host-side failures
+(NULL handle, parse errors during ``Workbook.load``, OOM) raise
+:class:`FormulonError`.
+"""
+
+from __future__ import annotations
+
+from ._c import LIB, ValueKind, decode_cstr
+from .workbook import (
+    Cell,
+    DefinedName,
+    FormulonError,
+    PassthroughPart,
+    Table,
+    Value,
+    Workbook,
+)
+
+# IMPORTANT: keep this in sync with the [project] version in
+# packages/python/pyproject.toml. There is no portable way to read the
+# wheel metadata at runtime without `importlib.metadata`, which is fine
+# for installed packages but breaks for source-tree imports.
+__version__ = "0.9.0"
+
+__all__ = [
+    "Cell",
+    "DefinedName",
+    "FormulonError",
+    "PassthroughPart",
+    "Table",
+    "Value",
+    "ValueKind",
+    "Workbook",
+    "__version__",
+    "eval_formula",
+    "library_version",
+    "version_string",
+]
+
+
+def library_version() -> str:
+    """Return the version string baked into the loaded WASM module.
+
+    Returns:
+      The result of ``fm_version_string()``. Always non-empty.
+    """
+    return decode_cstr(LIB.fm_version_string())
+
+
+# Backward-compat alias mirroring the npm binding's ``versionString`` name.
+version_string = library_version
+
+
+def eval_formula(formula: str) -> Value:
+    """Evaluate a single formula against a fresh, default workbook.
+
+    The formula is written to ``Sheet1!A1``, the workbook is recalculated,
+    and the resulting cell value is returned.
+
+    Cell-level Excel errors (``#DIV/0!``, ``#VALUE!``, etc.) surface as a
+    :class:`Value` with ``kind == ValueKind.ERROR``; only host-side
+    failures (parser crash, OOM, NULL handle) raise :class:`FormulonError`.
+
+    Args:
+      formula: the formula text, with or without a leading ``=``.
+
+    Returns:
+      The :class:`Value` cached at ``Sheet1!A1`` after recalc.
+    """
+    with Workbook.create_default() as wb:
+        wb.set_formula(0, 0, 0, formula)
+        wb.recalc()
+        return wb.get_value(0, 0, 0)

formulon/__init__.pyi

@@ -0,0 +1,79 @@
+# Copyright 2026 libraz. Licensed under the Apache License, Version 2.0.
+# Hand-rolled type stubs for the Formulon public surface.
+# IDEs and type-checkers consume this rather than the runtime module.
+
+from typing import Iterator, NamedTuple, Optional, Union
+
+from ._c import ValueKind as ValueKind
+
+__version__: str
+
+class Value:
+    kind: ValueKind
+    number: Optional[float]
+    boolean: Optional[bool]
+    text: Optional[str]
+    error_code: Optional[int]
+    def to_python(self) -> Union[None, float, bool, str, "Value"]: ...
+
+class Cell(NamedTuple):
+    row: int
+    col: int
+    formula: Optional[str]
+    value: Value
+
+class DefinedName(NamedTuple):
+    name: str
+    formula: str
+
+class Table(NamedTuple):
+    name: str
+    display_name: str
+    ref: str
+    sheet_index: int
+
+class PassthroughPart(NamedTuple):
+    path: str
+
+class FormulonError(Exception):
+    status: int
+    status_name: str
+    message: str
+    context: str
+    def __init__(self, status: int, *, op: str = ...) -> None: ...
+
+class Workbook:
+    def __init__(self) -> None: ...
+    @classmethod
+    def create_default(cls) -> "Workbook": ...
+    @classmethod
+    def create_empty(cls) -> "Workbook": ...
+    @classmethod
+    def load(cls, data: Union[bytes, bytearray, memoryview]) -> "Workbook": ...
+    def __enter__(self) -> "Workbook": ...
+    def __exit__(self, exc_type: object, exc: object, tb: object) -> None: ...
+    def close(self) -> None: ...
+    @property
+    def is_valid(self) -> bool: ...
+    def sheet_count(self) -> int: ...
+    def sheet_name(self, index: int) -> str: ...
+    def add_sheet(self, name: str) -> None: ...
+    def set_number(self, sheet: int, row: int, col: int, value: float) -> None: ...
+    def set_bool(self, sheet: int, row: int, col: int, value: bool) -> None: ...
+    def set_text(self, sheet: int, row: int, col: int, value: str) -> None: ...
+    def set_blank(self, sheet: int, row: int, col: int) -> None: ...
+    def set_formula(self, sheet: int, row: int, col: int, formula: str) -> None: ...
+    def get_value(self, sheet: int, row: int, col: int) -> Value: ...
+    def recalc(self) -> None: ...
+    def set_iterative(
+        self, enabled: bool, max_iterations: int, max_change: float
+    ) -> None: ...
+    def save(self) -> bytes: ...
+    def iter_cells(self, sheet: int) -> Iterator[Cell]: ...
+    def iter_defined_names(self) -> Iterator[DefinedName]: ...
+    def iter_tables(self) -> Iterator[Table]: ...
+    def iter_passthrough(self) -> Iterator[PassthroughPart]: ...
+
+def library_version() -> str: ...
+def version_string() -> str: ...
+def eval_formula(formula: str) -> Value: ...

formulon/_c.py

@@ -0,0 +1,335 @@
+# Copyright 2026 libraz. Licensed under the Apache License, Version 2.0.
+"""Low-level WASM binding for the Formulon C ABI.
+
+Public users should import the ``Workbook`` / ``Value`` / ``FormulonError``
+symbols re-exported by the top-level :mod:`formulon` package instead.
+
+Architecture
+------------
+
+The binding loads ``formulon_capi.wasm`` (a standalone reactor-style
+WebAssembly module that exports the ``fm_*`` C ABI from
+``src/c_api/formulon_c.h``) via the ``wasmtime`` runtime. A single
+module instance is created lazily at first use and shared across every
+:class:`formulon.Workbook` in the process; each ``Workbook`` instance
+owns an opaque ``fm_workbook_t*`` (i32 in WASM) handle.
+
+Pointers are 32-bit offsets into the WASM linear memory. Strings cross
+the boundary as ``malloc``-allocated UTF-8 NUL-terminated buffers in
+that memory; the caller is responsible for ``free``-ing them after the
+WASM function returns. Borrowed return pointers (e.g. text from
+``fm_workbook_get_value``) are read directly from WASM memory and
+decoded eagerly into Python ``str`` so the result outlives any
+subsequent WASM mutation.
+
+The ``fm_value_t`` POD has the wasm32 layout::
+
+    offset 0: int32  kind
+    offset 4: int32  (padding for 8-byte alignment of the union)
+    offset 8: union  { double number ; int32 boolean ; int32 error_code ; ptr text }
+    total: 16 bytes
+
+The union member is selected by ``kind``; reading any other member is
+undefined per the C ABI contract.
+"""
+
+from __future__ import annotations
+
+import struct
+import threading
+from enum import IntEnum
+from pathlib import Path
+from typing import Optional, Tuple
+
+import wasmtime
+
+__all__ = [
+    "LIB",
+    "ValueKind",
+    "decode_cstr",
+    "fm_value_t_size",
+]
+
+# fm_value_t layout: int32 kind + 4 pad + 8 union = 16 bytes.
+fm_value_t_size = 16
+
+
+# ---------------------------------------------------------------------------
+# ValueKind enum (matches fm_value_kind_t)
+# ---------------------------------------------------------------------------
+
+
+class ValueKind(IntEnum):
+    """Mirror of ``fm_value_kind_t`` in ``formulon_c.h``."""
+
+    BLANK = 0
+    NUMBER = 1
+    BOOL = 2
+    TEXT = 3
+    ERROR = 4
+    ARRAY = 5
+    REF = 6
+    LAMBDA = 7
+
+
+# ---------------------------------------------------------------------------
+# WASM module location
+# ---------------------------------------------------------------------------
+
+
+def _locate_wasm() -> Path:
+    """Return the on-disk path to ``formulon_capi.wasm``.
+
+    Search order:
+      1. ``packages/python/formulon/_wasm/formulon_capi.wasm`` -- the
+         package-data location populated by ``make python-package``
+         and shipped inside the wheel.
+      2. ``$FORMULON_WASM_PATH`` -- explicit override for development.
+
+    Raises:
+      FileNotFoundError: when the WASM is not on disk in either
+        location. The error message names both candidates.
+    """
+    here = Path(__file__).resolve().parent
+    bundled = here / "_wasm" / "formulon_capi.wasm"
+    if bundled.is_file():
+        return bundled
+
+    import os
+
+    override = os.environ.get("FORMULON_WASM_PATH")
+    if override:
+        p = Path(override)
+        if p.is_file():
+            return p
+
+    raise FileNotFoundError(
+        "formulon: failed to locate formulon_capi.wasm. "
+        f"Tried: {bundled}. "
+        "Run `make python-package` to stage the artifact, or install a "
+        "wheel that ships it under formulon/_wasm/."
+    )
+
+
+# ---------------------------------------------------------------------------
+# WASM module / store wrapper
+# ---------------------------------------------------------------------------
+
+
+class _WasmInstance:
+    """Owns a single ``wasmtime`` engine, store, and module instance.
+
+    The instance is created lazily on first attribute access; subsequent
+    Workbook creations reuse it. This trades cold-start latency for
+    repeat-call speed and keeps the engine cache around for the life of
+    the Python process.
+
+    The store is `not` thread-safe (per the wasmtime-py docs); a single
+    process-wide ``_call_lock`` serialises every WASM invocation. The
+    underlying calculation engine is already safe for one outstanding
+    recalc per ``Workbook`` handle, so the additional lock only prevents
+    cross-handle reentry on the wasmtime store itself.
+    """
+
+    def __init__(self) -> None:
+        self._engine: Optional[wasmtime.Engine] = None
+        self._store: Optional[wasmtime.Store] = None
+        self._instance: Optional[wasmtime.Instance] = None
+        self._memory: Optional[wasmtime.Memory] = None
+        self._exports: dict = {}
+        self._init_lock = threading.Lock()
+        self._call_lock = threading.RLock()
+
+    def _ensure(self) -> None:
+        if self._instance is not None:
+            return
+        with self._init_lock:
+            if self._instance is not None:
+                return
+            engine = wasmtime.Engine()
+            store = wasmtime.Store(engine)
+
+            # WASI: provide a minimal config. The engine never reads
+            # files or stdin; stdout/stderr inherit so any diagnostic
+            # libc calls (e.g. trap reasons) surface to the host.
+            wasi = wasmtime.WasiConfig()
+            wasi.inherit_stdout()
+            wasi.inherit_stderr()
+            store.set_wasi(wasi)
+
+            wasm_path = _locate_wasm()
+            module = wasmtime.Module.from_file(engine, str(wasm_path))
+
+            linker = wasmtime.Linker(engine)
+            linker.define_wasi()
+
+            # Stub for env.emscripten_notify_memory_growth. emcc emits
+            # this import even under STANDALONE_WASM; it is called on
+            # memory.grow but the host has nothing useful to do with it.
+            ty = wasmtime.FuncType([wasmtime.ValType.i32()], [])
+            linker.define(
+                store,
+                "env",
+                "emscripten_notify_memory_growth",
+                wasmtime.Func(store, ty, lambda _i: None),
+            )
+
+            instance = linker.instantiate(store, module)
+            exports = dict(instance.exports(store).items())
+
+            # Reactor init must run before any export is callable.
+            init_fn = exports.get("_initialize")
+            if init_fn is not None:
+                init_fn(store)
+
+            self._engine = engine
+            self._store = store
+            self._instance = instance
+            self._memory = exports["memory"]
+            self._exports = exports
+
+    # ----- raw export accessor --------------------------------------------
+    def __getattr__(self, name: str):
+        self._ensure()
+        fn = self._exports.get(name)
+        if fn is None:
+            raise AttributeError(f"WASM export '{name}' not found")
+        store = self._store
+        lock = self._call_lock
+
+        # Wrap so the caller can use a ctypes-like call syntax.
+        def _wrapped(*args):
+            with lock:
+                return fn(store, *args)
+
+        return _wrapped
+
+    # ----- memory primitives ----------------------------------------------
+    @property
+    def store(self) -> wasmtime.Store:
+        self._ensure()
+        assert self._store is not None
+        return self._store
+
+    @property
+    def memory(self) -> wasmtime.Memory:
+        self._ensure()
+        assert self._memory is not None
+        return self._memory
+
+    @property
+    def call_lock(self) -> threading.RLock:
+        return self._call_lock
+
+    def read_bytes(self, ptr: int, length: int) -> bytes:
+        """Copy ``length`` bytes from WASM memory starting at ``ptr``."""
+        self._ensure()
+        assert self._memory is not None
+        return bytes(self._memory.read(self._store, ptr, ptr + length))
+
+    def write_bytes(self, ptr: int, data: bytes) -> None:
+        """Write ``data`` into WASM memory starting at ``ptr``."""
+        self._ensure()
+        assert self._memory is not None
+        self._memory.write(self._store, data, ptr)
+
+    def read_u32(self, ptr: int) -> int:
+        return struct.unpack("<I", self.read_bytes(ptr, 4))[0]
+
+    def read_i32(self, ptr: int) -> int:
+        return struct.unpack("<i", self.read_bytes(ptr, 4))[0]
+
+    def read_f64(self, ptr: int) -> float:
+        return struct.unpack("<d", self.read_bytes(ptr, 8))[0]
+
+    def read_cstr(self, ptr: int) -> str:
+        """Decode a NUL-terminated UTF-8 C string from ``ptr``.
+
+        Returns the empty string when ``ptr`` is 0.
+        """
+        if ptr == 0:
+            return ""
+        self._ensure()
+        assert self._memory is not None
+        # Stream a chunk at a time to avoid copying the whole memory.
+        chunks: list[bytes] = []
+        offset = ptr
+        chunk_size = 256
+        mem_len = self._memory.data_len(self._store)
+        while offset < mem_len:
+            end = min(offset + chunk_size, mem_len)
+            buf = bytes(self._memory.read(self._store, offset, end))
+            nul = buf.find(b"\x00")
+            if nul >= 0:
+                chunks.append(buf[:nul])
+                break
+            chunks.append(buf)
+            offset = end
+        return b"".join(chunks).decode("utf-8", errors="replace")
+
+    def alloc(self, size: int) -> int:
+        """Allocate ``size`` bytes in WASM memory; return the pointer.
+
+        Raises:
+          MemoryError: when the WASM-side allocator returns NULL.
+        """
+        if size <= 0:
+            return 0
+        self._ensure()
+        with self._call_lock:
+            ptr = self._exports["malloc"](self._store, size)
+        if ptr == 0:
+            raise MemoryError(f"formulon: WASM malloc({size}) returned NULL")
+        return ptr
+
+    def free(self, ptr: int) -> None:
+        if ptr == 0:
+            return
+        self._ensure()
+        with self._call_lock:
+            self._exports["free"](self._store, ptr)
+
+    def alloc_utf8(self, s: str) -> Tuple[int, int]:
+        """Encode ``s`` as UTF-8 and copy it into WASM memory.
+
+        Returns ``(ptr, length_with_nul)``. The caller MUST free ``ptr``
+        with :meth:`free` once the call that consumed it returns.
+        """
+        if not isinstance(s, str):
+            raise TypeError(f"expected str, got {type(s).__name__}")
+        buf = s.encode("utf-8") + b"\x00"
+        ptr = self.alloc(len(buf))
+        self.write_bytes(ptr, buf)
+        return ptr, len(buf)
+
+    def alloc_bytes(self, data: bytes) -> int:
+        """Copy ``data`` into WASM memory; return the pointer."""
+        if len(data) == 0:
+            return 0
+        ptr = self.alloc(len(data))
+        self.write_bytes(ptr, data)
+        return ptr
+
+
+# ---------------------------------------------------------------------------
+# Module-level singleton + thin compatibility shim
+# ---------------------------------------------------------------------------
+
+
+LIB = _WasmInstance()
+
+
+def decode_cstr(ptr_or_bytes) -> str:
+    """Backwards-compat shim for :class:`formulon.workbook.FormulonError`.
+
+    Accepts either an int WASM pointer (decoded via :class:`LIB`) or a
+    bytes object (legacy ctypes path). Returns the empty string when
+    the input is ``None``, ``0``, or empty.
+    """
+    if ptr_or_bytes is None:
+        return ""
+    if isinstance(ptr_or_bytes, bytes):
+        return ptr_or_bytes.decode("utf-8", errors="replace")
+    if isinstance(ptr_or_bytes, int):
+        return LIB.read_cstr(ptr_or_bytes)
+    raise TypeError(f"decode_cstr: unexpected type {type(ptr_or_bytes).__name__}")

formulon/_wasm/__init__.py

@@ -0,0 +1,2 @@
+# Auto-generated by packages/python/scripts/stage.py.
+# This package only ships a single .wasm asset.