universal-wasm-loader 1.0.0__py3-none-any.whl

universal_wasm_loader/__init__.py

@@ -0,0 +1,3 @@
+from ._loader import InstancePool, create_singleton, wasm_import
+
+__all__ = ["wasm_import", "create_singleton", "InstancePool"]

universal_wasm_loader/_abi.py

@@ -0,0 +1,124 @@
+from __future__ import annotations
+
+from typing import Any, Callable
+
+import wasmtime
+
+
+def _decode_string(memory: wasmtime.Memory, store: wasmtime.Store, ptr: int, length: int) -> str:
+    return bytes(memory.read(store, ptr, ptr + length)).decode("utf-8")
+
+
+def _read_i32_le(memory: wasmtime.Memory, store: wasmtime.Store, addr: int) -> int:
+    return int.from_bytes(bytes(memory.read(store, addr, addr + 4)), "little", signed=True)
+
+
+def _encode_string(
+    memory: wasmtime.Memory,
+    store: wasmtime.Store,
+    realloc: wasmtime.Func,
+    text: str,
+) -> tuple[int, int]:
+    data = text.encode("utf-8")
+    ptr: int = realloc(store, 0, 0, 1, len(data))  # type: ignore[assignment]
+    memory.write(store, data, ptr)
+    return ptr, len(data)
+
+
+def build_component_import_env(
+    imports: list[dict],  # type: ignore[type-arg]
+    callbacks: dict[str, Callable] | None,  # type: ignore[type-arg]
+    memory_ref: list[wasmtime.Memory | None],
+    store: wasmtime.Store,
+) -> dict[str, Callable]:  # type: ignore[type-arg]
+    callbacks = callbacks or {}
+
+    def make_wrapper(fd: dict, cb: Callable | None) -> Callable:  # type: ignore[type-arg]
+        has_str = any(p["type"] == "string" for p in fd["params"])
+
+        def wrapper(*raw_args: Any) -> Any:
+            memory = memory_ref[0]
+            converted: list[Any] = []
+            idx = 0
+            for p in fd["params"]:
+                val = raw_args[idx]
+                idx += 1
+                if p["type"] == "bool":
+                    converted.append(bool(val))
+                elif p["type"] == "string" and has_str and memory is not None:
+                    length = int(raw_args[idx])
+                    idx += 1
+                    converted.append(_decode_string(memory, store, int(val), length))
+                else:
+                    converted.append(val)
+            if cb is None:
+                return None if not fd["return_type"] else 0
+            result = cb(*converted)
+            if result is None:
+                return 0
+            return int(result) if isinstance(result, bool) else result
+
+        return wrapper
+
+    env: dict[str, Callable] = {}  # type: ignore[type-arg]
+    for func_def in imports:
+        cb = callbacks.get(func_def["camel_name"]) or callbacks.get(func_def["name"])
+        env[func_def["wasm_key"]] = make_wrapper(func_def, cb)
+    return env
+
+
+def build_component_export_proxy(
+    raw_exports: dict[str, Any],
+    wit_exports: list[dict],  # type: ignore[type-arg]
+    memory_ref: list[wasmtime.Memory | None],
+    store: wasmtime.Store,
+    cabi_realloc_ref: list[wasmtime.Func | None],
+) -> dict[str, Callable]:  # type: ignore[type-arg]
+    def make_proxy(fd: dict, raw_fn: wasmtime.Func) -> Callable:  # type: ignore[type-arg]
+        # SPEC 3.0.0: a string/aggregate-returning export returns a single i32
+        # pointer to a callee-allocated [ptr, len] pair. After reading it, the
+        # host calls the paired cabi_post_<name>(retArea) export (if present) to
+        # let the callee free that memory. <name> is the camelCase export name.
+        cabi_post = raw_exports.get(f"cabi_post_{fd['camel_name']}")
+        if not isinstance(cabi_post, wasmtime.Func):
+            cabi_post = None
+
+        def call(*args: Any) -> Any:
+            memory = memory_ref[0]
+            realloc = cabi_realloc_ref[0]
+            wasm_args: list[Any] = []
+            for p, val in zip(fd["params"], args):
+                if p["type"] == "bool":
+                    wasm_args.append(int(bool(val)))
+                elif p["type"] == "string" and memory is not None and realloc is not None:
+                    ptr, length = _encode_string(memory, store, realloc, str(val))
+                    wasm_args.extend([ptr, length])
+                else:
+                    wasm_args.append(val)
+            result = raw_fn(store, *wasm_args)
+            rt = fd.get("return_type")
+            if rt == "bool":
+                return bool(result)
+            if rt == "string" and memory is not None:
+                # The export returns a single i32 pointing at the 8-byte
+                # [ptr, len] return area (callee-allocated).
+                ret_area = int(result)
+                str_ptr = _read_i32_le(memory, store, ret_area)
+                str_len = _read_i32_le(memory, store, ret_area + 4)
+                decoded = _decode_string(memory, store, str_ptr, str_len)
+                if cabi_post is not None:
+                    cabi_post(store, ret_area)
+                return decoded
+            return result
+
+        return call
+
+    proxy: dict[str, Callable] = {}  # type: ignore[type-arg]
+    for func_def in wit_exports:
+        # wasmtk emits camelCase export names (e.g. WIT `str-len` -> `strLen`),
+        # matching the reference loader's lookup by camelCase tsName. Fall back
+        # to the underscore form for tolerance.
+        raw_fn = raw_exports.get(func_def["camel_name"]) or raw_exports.get(func_def["wasm_key"])
+        if raw_fn is not None and isinstance(raw_fn, wasmtime.Func):
+            proxy[func_def["camel_name"]] = make_proxy(func_def, raw_fn)
+    return proxy

universal_wasm_loader/_loader.py

@@ -0,0 +1,195 @@
+from __future__ import annotations
+
+import asyncio
+import re
+from pathlib import Path
+from typing import Any, Callable
+
+import wasmtime
+from wasmtime import Engine, FuncType, Linker, Module, Store
+
+from ._abi import build_component_export_proxy, build_component_import_env
+from ._wit_parser import parse_wit
+
+
+def _parse_version_suffix(path: str) -> tuple[str, int | None]:
+    m = re.search(r"@(\d+)$", path)
+    return (path[: m.start()], int(m.group(1))) if m else (path, None)
+
+
+def _collect_raw_exports(
+    module: Module, instance: wasmtime.Instance, store: Store
+) -> dict[str, Any]:
+    exports_obj = instance.exports(store)
+    result: dict[str, Any] = {}
+    for exp in module.exports:
+        val = exports_obj[exp.name]
+        if val is not None:
+            result[exp.name] = val
+    return result
+
+
+def _make_noop(n_results: int) -> Callable[..., Any]:
+    if n_results == 0:
+        return lambda *_: None
+    if n_results == 1:
+        return lambda *_: 0
+    return lambda *_, n=n_results: [0] * n
+
+
+def _assert_version(raw: dict[str, Any], store: Store, expected: int, path: str) -> None:
+    g = raw.get("version")
+    if not isinstance(g, wasmtime.Global):
+        raise RuntimeError(f"{path!r}: no exported 'version' global")
+    actual = g.value(store)
+    if actual != expected:
+        raise RuntimeError(f"{path!r}: version mismatch — expected {expected}, got {actual}")
+
+
+def _wrap_for_user(raw: dict[str, Any], store: Store) -> dict[str, Any]:
+    result: dict[str, Any] = {}
+    for name, val in raw.items():
+        if isinstance(val, wasmtime.Func):
+            fn = val
+            result[name] = lambda *args, f=fn: f(store, *args)
+        elif isinstance(val, wasmtime.Global):
+            result[name] = val.value(store)
+        else:
+            result[name] = val
+    return result
+
+
+async def wasm_import(
+    wasm_path: str | Path,
+    host_callbacks: dict[str, Callable[..., Any]] | None = None,
+) -> dict[str, Any]:
+    path_str = str(wasm_path)
+    cleaned, requested_version = _parse_version_suffix(path_str)
+    path = Path(cleaned)
+
+    wit: dict[str, Any] | None = None
+    wit_path = path.with_suffix(".wit")
+    if wit_path.exists():
+        try:
+            wit = parse_wit(wit_path.read_text(encoding="utf-8"))
+        except Exception:
+            wit = None
+
+    wasm_bytes = await asyncio.to_thread(path.read_bytes)
+    engine = Engine()
+    module = Module(engine, wasm_bytes)
+    store = Store(engine)
+
+    memory_ref: list[wasmtime.Memory | None] = [None]
+    cabi_realloc_ref: list[wasmtime.Func | None] = [None]
+
+    import_env: dict[str, Callable[..., Any]] = {}
+    if wit:
+        import_env = build_component_import_env(wit["imports"], host_callbacks, memory_ref, store)
+
+    linker = Linker(engine)
+    for imp in module.imports:
+        if not isinstance(imp.type, FuncType):
+            continue
+        ft: FuncType = imp.type
+        imp_name = imp.name
+        if imp_name in import_env:
+            linker.define_func(imp.module, imp_name, ft, import_env[imp_name])
+        elif host_callbacks and imp_name in host_callbacks:
+            cb = host_callbacks[imp_name]
+            linker.define_func(imp.module, imp_name, ft, lambda *a, fn=cb: fn(*a))
+        else:
+            linker.define_func(imp.module, imp_name, ft, _make_noop(len(ft.results)))
+
+    instance = linker.instantiate(store, module)
+    raw = _collect_raw_exports(module, instance, store)
+
+    mem = raw.get("memory")
+    if isinstance(mem, wasmtime.Memory):
+        memory_ref[0] = mem
+    realloc = raw.get("cabi_realloc")
+    if isinstance(realloc, wasmtime.Func):
+        cabi_realloc_ref[0] = realloc
+
+    if requested_version is not None:
+        _assert_version(raw, store, requested_version, cleaned)
+
+    if wit:
+        proxy = build_component_export_proxy(
+            raw, wit["exports"], memory_ref, store, cabi_realloc_ref
+        )
+        for name, val in raw.items():
+            if name not in proxy:
+                if isinstance(val, wasmtime.Func):
+                    fn = val
+                    proxy[name] = lambda *args, f=fn: f(store, *args)
+                elif isinstance(val, wasmtime.Global):
+                    proxy[name] = val.value(store)
+        return proxy
+
+    return _wrap_for_user(raw, store)
+
+
+def create_singleton(
+    wasm_path: str | Path,
+    host_callbacks: dict[str, Callable[..., Any]] | None = None,
+) -> Callable[[], Any]:
+    _cache: dict[str, Any] | None = None
+    _lock: asyncio.Lock | None = None
+
+    async def get() -> dict[str, Any]:
+        nonlocal _cache, _lock
+        if _lock is None:
+            _lock = asyncio.Lock()
+        async with _lock:
+            if _cache is None:
+                _cache = await wasm_import(wasm_path, host_callbacks)
+        return _cache
+
+    return get
+
+
+class InstancePool:
+    def __init__(
+        self,
+        wasm_path: str | Path,
+        host_callbacks: dict[str, Callable[..., Any]] | None = None,
+        size: int = 2,
+    ) -> None:
+        self._path = wasm_path
+        self._callbacks = host_callbacks
+        self._size = size
+        self._pool: asyncio.Queue[dict[str, Any]] | None = None
+        self._lock: asyncio.Lock | None = None
+
+    async def _ensure_ready(self) -> None:
+        if self._lock is None:
+            self._lock = asyncio.Lock()
+        async with self._lock:
+            if self._pool is not None:
+                return
+            q: asyncio.Queue[dict[str, Any]] = asyncio.Queue()
+            for inst in await asyncio.gather(
+                *[wasm_import(self._path, self._callbacks) for _ in range(self._size)]
+            ):
+                q.put_nowait(inst)
+            self._pool = q
+
+    async def acquire(self) -> dict[str, Any]:
+        await self._ensure_ready()
+        assert self._pool is not None
+        return await self._pool.get()
+
+    async def release(self, instance: dict[str, Any]) -> None:
+        if self._pool is not None:
+            await self._pool.put(instance)
+
+    async def run(self, fn: Callable[[dict[str, Any]], Any]) -> Any:
+        instance = await self.acquire()
+        try:
+            result = fn(instance)
+            if asyncio.iscoroutine(result):
+                return await result
+            return result
+        finally:
+            await self.release(instance)

universal_wasm_loader/_wit_parser.py

@@ -0,0 +1,64 @@
+from __future__ import annotations
+
+import re
+
+_PRIMITIVE_TYPES = frozenset({"s32", "s64", "f32", "f64", "bool", "string"})
+
+
+def kebab_to_camel(name: str) -> str:
+    parts = name.split("-")
+    return parts[0] + "".join(p.capitalize() for p in parts[1:])
+
+
+def kebab_to_wasm_key(name: str) -> str:
+    return name.replace("-", "_")
+
+
+def parse_wit_type(raw: str) -> str:
+    t = raw.strip()
+    return t if t in _PRIMITIVE_TYPES else "s32"
+
+
+def parse_wit_params(raw: str) -> list[dict[str, str]]:
+    if not raw.strip():
+        return []
+    result: list[dict[str, str]] = []
+    for part in raw.split(","):
+        part = part.strip()
+        if ":" not in part:
+            continue
+        name_raw, type_raw = part.split(":", 1)
+        result.append({"name": kebab_to_camel(name_raw.strip()), "type": parse_wit_type(type_raw)})
+    return result
+
+
+def parse_wit_funcs(body: str, keyword: str) -> list[dict]:  # type: ignore[type-arg]
+    pattern = re.compile(
+        rf"\b{keyword}\s+([\w-]+)\s*:\s*func\s*\(([^)]*)\)\s*(?:->\s*([\w-]+))?",
+        re.MULTILINE,
+    )
+    funcs: list[dict] = []  # type: ignore[type-arg]
+    for m in pattern.finditer(body):
+        name = m.group(1)
+        funcs.append(
+            {
+                "name": name,
+                "camel_name": kebab_to_camel(name),
+                "wasm_key": kebab_to_wasm_key(name),
+                "params": parse_wit_params(m.group(2) or ""),
+                "return_type": parse_wit_type(m.group(3)) if m.group(3) else None,
+            }
+        )
+    return funcs
+
+
+def parse_wit(src: str) -> dict:  # type: ignore[type-arg]
+    pkg_match = re.search(r"package\s+([\w:@.\-/]+)\s*;", src)
+    world_match = re.search(r"world\s+([\w-]+)\s*\{([^}]*)\}", src, re.DOTALL)
+    body = world_match.group(2) if world_match else src
+    return {
+        "package": pkg_match.group(1) if pkg_match else "",
+        "world": world_match.group(1) if world_match else "",
+        "imports": parse_wit_funcs(body, "import"),
+        "exports": parse_wit_funcs(body, "export"),
+    }

universal_wasm_loader-1.0.0.dist-info/METADATA

@@ -0,0 +1,121 @@
+Metadata-Version: 2.4
+Name: universal-wasm-loader
+Version: 1.0.0
+Summary: Universal WASM loader for Python
+Project-URL: Homepage, https://github.com/jrmarcum/universalWasmLoader-py
+Project-URL: Repository, https://github.com/jrmarcum/universalWasmLoader-py
+Author-email: Jon Marcum <jrmarcum.se@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: canonical-abi,loader,wasm,webassembly,wit
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.11
+Requires-Dist: wasmtime>=26.0.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.9.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# universalWasmLoader-py
+
+Universal WASM loader for Python — the Python port of
+[universalWasmLoader-js](https://github.com/jrmarcum/universalWasmLoader-js). Loads and
+instantiates WebAssembly modules and, when a companion `.wit` file is present, applies the
+Canonical ABI so you call WIT exports with idiomatic Python values (`int`/`float`, `bool`,
+`str`) instead of raw i32/pointer pairs.
+
+- **PyPI package:** `universal-wasm-loader`
+- **WASM runtime:** [`wasmtime`](https://pypi.org/project/wasmtime/) ≥ 26.0.0
+- **License:** MIT
+
+## Install
+
+```sh
+pip install universal-wasm-loader
+```
+
+## Usage
+
+```python
+from universal_wasm_loader import wasm_import, create_singleton, InstancePool
+
+exports = await wasm_import("./math.wasm")
+result = exports["calculate"](1, 2)          # 3
+```
+
+See [`CLAUDE.md`](CLAUDE.md) / [`cmem/overview.md`](cmem/overview.md) for the full API surface.
+
+## Develop
+
+```sh
+pixi run test        # pytest tests/ -v
+pixi run lint        # ruff check src/ tests/
+pixi run typecheck   # mypy src/
+```
+
+## Release / publish to PyPI
+
+The version lives in **`pyproject.toml`** `[project] version` — the single source of truth
+(`pixi.toml` mirrors it). Three scripts key off it, each shipped in **two equivalent forms**: a
+Bash `.sh` and a cross-platform Nushell `.nu` (Nushell ≥ 0.113; runs on Windows/macOS/Linux
+without Git Bash). Use whichever your machine has — they have identical flags and behavior.
+
+**Tagging/releasing and publishing are deliberately decoupled:** `release` tags + pushes +
+creates the GitHub Release; `publish` is a separate, auth-gated, confirmation-guarded step that
+actually uploads to PyPI (irreversible). All three support `--dry-run`.
+
+```sh
+# 1) Bump the version (commits the isolated change)
+bash scripts/bump-version.sh patch     #  1.0.0 -> 1.0.1   (or minor | major | X.Y.Z)
+nu   scripts/bump-version.nu patch      #  …equivalent
+
+# 2) Tag v<version>, push branch + tag, create the GitHub Release (NO PyPI upload)
+bash scripts/release.sh                 #  --no-release / --no-build / --remote / --dry-run
+nu   scripts/release.nu
+
+# 3) Publish to PyPI — separate, deliberate, irreversible
+bash scripts/publish.sh                 #  prompts; --yes / --dry-run / --allow-dirty / --skip-tag-check
+nu   scripts/publish.nu
+```
+
+`publish` reads the version from `pyproject.toml`, requires the matching `v<version>` tag to
+exist locally **and** on the remote, refuses to run without a PyPI token, and is idempotent (if
+that version is already on PyPI it reports success and uploads nothing).
+
+### Required setup for `publish` (one-time)
+
+1. **PyPI project owned/registered.** The name `universal-wasm-loader` must exist on PyPI under
+   an account you control (do the first upload, or pre-register the name).
+2. **A PyPI API token in the environment** (project-scoped is best):
+
+   ```sh
+   export TWINE_USERNAME=__token__
+   export TWINE_PASSWORD=pypi-XXXXXXXX     # your token; or a [pypi] entry in ~/.pypirc
+   ```
+
+### Publishing from CI instead (optional, token-free)
+
+`.github/workflows/publish.yml` can also build + upload, but it is **manual-only**
+(`workflow_dispatch`) — it does **not** fire on a tag push, so it never double-publishes
+alongside `release`. Run it from the Actions tab against the release tag.
+
+It authenticates with **PyPI Trusted Publishing over short-lived OIDC — no long-lived PyPI token
+is stored in repo secrets**, so there's nothing to leak. One-time setup: register a Trusted
+Publisher on PyPI (a *pending publisher* before the project's first upload) with Owner
+`jrmarcum`, Repository `universalWasmLoader-py`, Workflow `publish.yml`.
+
+> **`run:`-only workflow.** This org's GitHub Actions policy permits only `jrmarcum`-owned
+> actions; any third-party `uses:` step (including `actions/checkout` and
+> `pypa/gh-action-pypi-publish`) causes a `startup_failure`. The workflow therefore uses plain
+> `run:` steps throughout — including the OIDC exchange (`ACTIONS_ID_TOKEN_REQUEST_*` →
+> `https://pypi.org/_/oidc/mint-token` → `twine upload` with the ephemeral token), done by hand
+> rather than via the pypa publish action.

universal_wasm_loader-1.0.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+universal_wasm_loader/__init__.py,sha256=q5AOLOEAXByTBokNJ7hyg_yGCCOMiWsyyAeyf6dX_zo,128
+universal_wasm_loader/_abi.py,sha256=SBT1Y4gSY7PIirh9QuzBytvImo6WrI72xPoT6pvyk-M,5135
+universal_wasm_loader/_loader.py,sha256=XRaKB-ekLnm0DsdICr8undl-NVQl5IQo8jtnFFpGZKw,6296
+universal_wasm_loader/_wit_parser.py,sha256=MWRk9945y2hlhVvTY4pwSBumFJggIotFoZ5Ddv1L02Y,2056
+universal_wasm_loader-1.0.0.dist-info/METADATA,sha256=gnS-XcB9xyhnr-VlKk58U6L-VNqtxwQOmcCeWVFlIWU,5235
+universal_wasm_loader-1.0.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+universal_wasm_loader-1.0.0.dist-info/licenses/LICENSE,sha256=17R5bZy3t1u5tfIaqG1sbGOZHj8paOibgt3_eaoeSHY,1067
+universal_wasm_loader-1.0.0.dist-info/RECORD,,

universal_wasm_loader-1.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

universal_wasm_loader-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jon Marcum
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.