triangulum 0.40.2__tar.gz

triangulum-0.40.2/.gitignore

@@ -0,0 +1,10 @@
+# Bundled JS entrypoints, built by `python tasks.py entrypoints`
+/src/triangulum/js/*.js
+# Bun binaries, downloaded by `python tasks.py download`
+/vendor/
+# Build output
+/dist/
+*.egg-info/
+__pycache__/
+.pytest_cache/
+.venv/

triangulum-0.40.2/PKG-INFO

@@ -0,0 +1,87 @@
+Metadata-Version: 2.5
+Name: triangulum
+Version: 0.40.2
+Summary: Triangulum is the CodeZero validation layer
+Project-URL: Homepage, https://github.com/code0-tech/triangulum
+Project-URL: Changelog, https://github.com/code0-tech/triangulum/releases
+Author: CodeZero
+License-Expression: MIT
+Requires-Python: >=3.10
+Requires-Dist: tucana>=0.0.83
+Description-Content-Type: text/markdown
+
+# Triangulum Python Package
+
+Python bindings for the [Triangulum](https://github.com/code0-tech/triangulum) validation layer. This package wraps the TypeScript library and a bundled [Bun](https://bun.sh) runtime to validate flows using the TypeScript compiler.
+
+## Installation
+
+```bash
+pip install triangulum   # or: uv add triangulum
+```
+
+Platform specific wheels with a bundled bun binary are published for:
+
+- `macosx_11_0_arm64` (macOS Apple Silicon)
+- `macosx_10_12_x86_64` (macOS Intel)
+- `manylinux_2_17_x86_64` (Linux x64)
+- `musllinux_1_2_x86_64` (Linux x64 musl)
+- `manylinux_2_17_aarch64` (Linux ARM64)
+- `musllinux_1_2_aarch64` (Linux ARM64 musl)
+
+For any other platform pip falls back to the pure python wheel, which requires `bun` on `PATH`.
+
+## Usage
+
+```python
+from triangulum import Validation
+
+result = Validation(flow, function_definitions, data_types).validate()
+
+result.is_valid      # => True / False
+result.return_type   # => "void"
+result.diagnostics   # => [Diagnostic, ...]
+```
+
+The arguments are [Tucana](https://github.com/code0-tech/tucana) protobuf messages:
+
+- `flow` — `tucana.generated.shared.flow_pb2.ValidationFlow`
+- `function_definitions` — `list[tucana.generated.shared.function_pb2.FunctionDefinition]`
+- `data_types` — `list[tucana.generated.shared.data_type_pb2.DefinitionDataType]`
+
+### Diagnostics
+
+Each diagnostic contains:
+
+| Field | Description |
+|---|---|
+| `message` | Human-readable error description |
+| `code` | TypeScript diagnostic code |
+| `severity` | `"error"` or `"warning"` |
+| `node_id` | ID of the node that caused the error |
+| `parameter_index` | Index of the parameter that caused the error |
+
+## Development
+
+Prerequisites: [Bun](https://bun.sh) installed locally, and the TypeScript package built in the repository root (`npm ci && npm run build`, plus `npm ci` in `entrypoint/`).
+
+```bash
+cd python
+uv sync
+uv run python tasks.py entrypoints  # bundles the TypeScript entrypoint into JS
+uv run pytest
+```
+
+### Building wheels
+
+```bash
+uv run python tasks.py wheels
+```
+
+This bundles the entrypoint, downloads the bun binaries (with SHA256 checksum verification) for all supported platforms and writes the sdist, the pure python wheel and one wheel per platform to `dist/`.
+
+Bun's version and checksums live in [`bun.json`](../bun.json) in the repository root, shared with the ruby gem.
+
+## License
+
+See [LICENSE](../LICENSE).

triangulum-0.40.2/README.md

@@ -0,0 +1,75 @@
+# Triangulum Python Package
+
+Python bindings for the [Triangulum](https://github.com/code0-tech/triangulum) validation layer. This package wraps the TypeScript library and a bundled [Bun](https://bun.sh) runtime to validate flows using the TypeScript compiler.
+
+## Installation
+
+```bash
+pip install triangulum   # or: uv add triangulum
+```
+
+Platform specific wheels with a bundled bun binary are published for:
+
+- `macosx_11_0_arm64` (macOS Apple Silicon)
+- `macosx_10_12_x86_64` (macOS Intel)
+- `manylinux_2_17_x86_64` (Linux x64)
+- `musllinux_1_2_x86_64` (Linux x64 musl)
+- `manylinux_2_17_aarch64` (Linux ARM64)
+- `musllinux_1_2_aarch64` (Linux ARM64 musl)
+
+For any other platform pip falls back to the pure python wheel, which requires `bun` on `PATH`.
+
+## Usage
+
+```python
+from triangulum import Validation
+
+result = Validation(flow, function_definitions, data_types).validate()
+
+result.is_valid      # => True / False
+result.return_type   # => "void"
+result.diagnostics   # => [Diagnostic, ...]
+```
+
+The arguments are [Tucana](https://github.com/code0-tech/tucana) protobuf messages:
+
+- `flow` — `tucana.generated.shared.flow_pb2.ValidationFlow`
+- `function_definitions` — `list[tucana.generated.shared.function_pb2.FunctionDefinition]`
+- `data_types` — `list[tucana.generated.shared.data_type_pb2.DefinitionDataType]`
+
+### Diagnostics
+
+Each diagnostic contains:
+
+| Field | Description |
+|---|---|
+| `message` | Human-readable error description |
+| `code` | TypeScript diagnostic code |
+| `severity` | `"error"` or `"warning"` |
+| `node_id` | ID of the node that caused the error |
+| `parameter_index` | Index of the parameter that caused the error |
+
+## Development
+
+Prerequisites: [Bun](https://bun.sh) installed locally, and the TypeScript package built in the repository root (`npm ci && npm run build`, plus `npm ci` in `entrypoint/`).
+
+```bash
+cd python
+uv sync
+uv run python tasks.py entrypoints  # bundles the TypeScript entrypoint into JS
+uv run pytest
+```
+
+### Building wheels
+
+```bash
+uv run python tasks.py wheels
+```
+
+This bundles the entrypoint, downloads the bun binaries (with SHA256 checksum verification) for all supported platforms and writes the sdist, the pure python wheel and one wheel per platform to `dist/`.
+
+Bun's version and checksums live in [`bun.json`](../bun.json) in the repository root, shared with the ruby gem.
+
+## License
+
+See [LICENSE](../LICENSE).

triangulum-0.40.2/hatch_build.py

@@ -0,0 +1,134 @@
+"""Wheel build hook that bundles a platform specific bun binary.
+
+The pure python wheel built without ``TRIANGULUM_WHEEL_PLATFORM`` expects ``bun``
+on ``PATH``. Setting the variable to one of the keys of :data:`BUN_PLATFORMS`
+produces a platform specific wheel with the matching bun binary embedded at
+``triangulum/exe/bun``, which mirrors the platform gems built by ``gem/``.
+
+Binaries are not downloaded during the build; run ``python tasks.py download``
+first (``tasks.py wheels`` does both).
+"""
+
+import hashlib
+import json
+import os
+import shutil
+import stat
+import urllib.request
+import zipfile
+from pathlib import Path
+
+from hatchling.builders.hooks.plugin.interface import BuildHookInterface
+
+HERE = Path(__file__).parent
+
+# Bun release metadata is shared with the ruby gem, see <repo root>/bun.json.
+# It only exists in a repository checkout, not in the published sdist, so the
+# metadata is loaded lazily and only platform wheels depend on it.
+BUN_METADATA_PATH = HERE.parent / "bun.json"
+
+VENDOR_DIR = HERE / "vendor" / "exe"
+
+ENTRYPOINTS = ("single-validation",)
+
+
+def _load_metadata():
+    if not BUN_METADATA_PATH.is_file():
+        raise RuntimeError(
+            f"{BUN_METADATA_PATH} not found. Platform wheels can only be built "
+            f"from a triangulum repository checkout."
+        )
+    return json.loads(BUN_METADATA_PATH.read_text())
+
+
+def bun_version():
+    return _load_metadata()["version"]
+
+
+def bun_platforms():
+    """wheel platform tag => (bun release zip filename, sha256 checksum)"""
+    return {p["wheel"]: (p["zip"], p["sha256"]) for p in _load_metadata()["platforms"]}
+
+
+def bun_download_url(filename):
+    return f"https://github.com/oven-sh/bun/releases/download/bun-{bun_version()}/{filename}"
+
+
+def bun_path(platform):
+    return VENDOR_DIR / platform / "bun"
+
+
+def download_bun(platform):
+    """Download and extract the bun binary for ``platform``, verifying its checksum."""
+    zip_filename, expected_checksum = bun_platforms()[platform]
+    destination = bun_path(platform)
+
+    if destination.is_file():
+        return destination
+
+    url = bun_download_url(zip_filename)
+    print(f"Downloading {destination} from {url} ...")
+
+    with urllib.request.urlopen(url) as response:
+        zip_data = response.read()
+
+    actual_checksum = hashlib.sha256(zip_data).hexdigest()
+    if actual_checksum != expected_checksum:
+        raise RuntimeError(
+            f"Checksum mismatch for {zip_filename}: "
+            f"expected {expected_checksum}, got {actual_checksum}"
+        )
+
+    destination.parent.mkdir(parents=True, exist_ok=True)
+    tmp_zip = destination.with_suffix(".zip")
+    tmp_zip.write_bytes(zip_data)
+    try:
+        with zipfile.ZipFile(tmp_zip) as archive:
+            entry = next(
+                (e for e in archive.namelist() if Path(e).name == "bun"),
+                None,
+            )
+            if entry is None:
+                raise RuntimeError(f"bun binary not found in {zip_filename}")
+
+            with archive.open(entry) as source, destination.open("wb") as target:
+                shutil.copyfileobj(source, target)
+    finally:
+        tmp_zip.unlink()
+
+    destination.chmod(destination.stat().st_mode | stat.S_IXUSR | stat.S_IXGRP | stat.S_IXOTH)
+
+    return destination
+
+
+class CustomBuildHook(BuildHookInterface):
+    def initialize(self, version, build_data):
+        # An editable install is used for development, where the entrypoints are
+        # bundled separately via `python tasks.py entrypoints`.
+        for entrypoint in ENTRYPOINTS if version != "editable" else ():
+            bundle = HERE / "src" / "triangulum" / "js" / f"{entrypoint}.js"
+            if not bundle.is_file():
+                raise RuntimeError(
+                    f"{bundle} is missing. Run `python tasks.py entrypoints` before building."
+                )
+
+        platform = os.environ.get("TRIANGULUM_WHEEL_PLATFORM")
+        if not platform:
+            return
+
+        platforms = bun_platforms()
+        if platform not in platforms:
+            raise RuntimeError(
+                f"Unknown TRIANGULUM_WHEEL_PLATFORM {platform!r}, "
+                f"expected one of {', '.join(sorted(platforms))}"
+            )
+
+        binary = bun_path(platform)
+        if not binary.is_file():
+            raise RuntimeError(
+                f"{binary} is missing. Run `python tasks.py download` before building."
+            )
+
+        build_data["pure_python"] = False
+        build_data["tag"] = f"py3-none-{platform}"
+        build_data["force_include"][str(binary)] = "triangulum/exe/bun"

triangulum-0.40.2/pyproject.toml

@@ -0,0 +1,45 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "triangulum"
+version = "0.40.2"
+description = "Triangulum is the CodeZero validation layer"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [{ name = "CodeZero" }]
+dependencies = [
+    "tucana>=0.0.83",
+]
+
+[project.urls]
+Homepage = "https://github.com/code0-tech/triangulum"
+Changelog = "https://github.com/code0-tech/triangulum/releases"
+
+[dependency-groups]
+dev = [
+    "build>=1.2",
+    "hatchling>=1.27",
+    "pytest>=8.0",
+]
+
+[tool.hatch.build]
+# The bundled JS entrypoints are gitignored build artifacts, but belong into the
+# sdist and every wheel.
+artifacts = ["src/triangulum/js/*.js"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/triangulum"]
+
+[tool.hatch.build.targets.wheel.hooks.custom]
+path = "hatch_build.py"
+
+[tool.hatch.build.targets.sdist]
+include = ["src/triangulum", "tests", "hatch_build.py", "tasks.py", "README.md"]
+
+[tool.pytest.ini_options]
+# Project root on sys.path so ``import tests.factories`` resolves.
+pythonpath = ["."]
+testpaths = ["tests"]

triangulum-0.40.2/src/triangulum/__init__.py

@@ -0,0 +1,13 @@
+"""Python bindings for the Triangulum validation layer."""
+
+from triangulum.errors import BunNotFound, Error, TriangulumFailed
+from triangulum.validation import Diagnostic, Result, Validation
+
+__all__ = [
+    "BunNotFound",
+    "Diagnostic",
+    "Error",
+    "Result",
+    "TriangulumFailed",
+    "Validation",
+]

triangulum-0.40.2/src/triangulum/errors.py

@@ -0,0 +1,13 @@
+"""Exceptions raised by triangulum."""
+
+
+class Error(Exception):
+    """Base class for every triangulum error."""
+
+
+class TriangulumFailed(Error):
+    """The bun subprocess exited with a failure."""
+
+
+class BunNotFound(Error):
+    """No bun executable is available to run the entrypoints with."""

triangulum-0.40.2/src/triangulum/executor.py

@@ -0,0 +1,73 @@
+"""Runs the bundled TypeScript entrypoints through bun."""
+
+import base64
+import shutil
+import subprocess
+from pathlib import Path
+
+from triangulum.errors import BunNotFound, TriangulumFailed
+
+JS_DIR = Path(__file__).parent / "js"
+
+# Platform wheels embed the matching bun binary here, see hatch_build.py. The
+# pure python wheel does not, and falls back to bun on PATH.
+BUNDLED_BUN = Path(__file__).parent / "exe" / "bun"
+
+
+def bun():
+    """Path to the bun executable to run the entrypoints with."""
+    if BUNDLED_BUN.is_file():
+        return str(BUNDLED_BUN)
+
+    found = shutil.which("bun")
+    if found is None:
+        raise BunNotFound(
+            "No bundled bun binary found and no 'bun' on PATH. Install bun "
+            "(https://bun.sh) or use a platform specific triangulum wheel."
+        )
+
+    return found
+
+
+def run_ts_triangulum(entrypoint, payload):
+    """Run ``entrypoint`` with ``payload`` on stdin and return its stdout."""
+    process = subprocess.run(
+        [bun(), "run", str(entrypoint)],
+        input=payload,
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+
+    if process.returncode != 0:
+        if process.returncode < 0:
+            status_info = f"SIGNAL: {-process.returncode}"
+        else:
+            status_info = f"STATUS: {process.returncode}"
+
+        raise TriangulumFailed(
+            f"{status_info}\n\nOUT:\n{process.stdout}\n\nERR:\n{process.stderr}"
+        )
+
+    return process.stdout
+
+
+def _encode(message):
+    return base64.b64encode(message.SerializeToString()).decode("ascii")
+
+
+def serialize_input(flow, function_definitions, data_types):
+    """Serialize the protobuf messages into the entrypoint's stdin format.
+
+    One base64 encoded message per line, the three groups separated by an empty
+    line. Mirrors ``Triangulum::Validation#serialize_input`` in the ruby gem.
+    """
+    lines = [_encode(flow), ""]
+
+    lines += [_encode(fd) for fd in function_definitions]
+    lines.append("")
+
+    lines += [_encode(dt) for dt in data_types]
+    lines.append("")
+
+    return "\n".join(lines)