diff --git a/.gitattributes b/.gitattributes new file mode 100644 index 0000000..45097cd --- /dev/null +++ b/.gitattributes @@ -0,0 +1,2 @@ +* text=auto eol=lf +tests/*.json -text diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml new file mode 100644 index 0000000..8d04e7b --- /dev/null +++ b/.github/workflows/ci.yml @@ -0,0 +1,76 @@ +name: Python installed wheels +on: + push: + branches: [main] + pull_request: + workflow_dispatch: +permissions: + contents: read +concurrency: + group: python-ci-${{ github.workflow }}-${{ github.ref }} + cancel-in-progress: true +jobs: + native: + name: Native stage (${{ matrix.os }}) + runs-on: ${{ matrix.os }} + timeout-minutes: 30 + strategy: + fail-fast: false + matrix: + os: [ubuntu-latest] + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-python@v5 + with: + python-version: '3.12' + - uses: dtolnay/rust-toolchain@stable + with: + toolchain: '1.95.0' + - name: Build the pinned public native library once + run: python scripts/ci.py build-native + - uses: actions/upload-artifact@v4 + with: + name: native-${{ matrix.os }} + include-hidden-files: true + path: .native/* + if-no-files-found: error + retention-days: 3 + - uses: actions/upload-artifact@v4 + if: always() + with: + name: native-evidence-${{ matrix.os }} + path: .ci-evidence/* + include-hidden-files: true + if-no-files-found: warn + retention-days: 3 + installed: + name: Installed wheel (${{ matrix.os }}, Python ${{ matrix.python }}) + needs: native + runs-on: ${{ matrix.os }} + timeout-minutes: 20 + strategy: + fail-fast: false + matrix: + os: [ubuntu-latest] + python: ['3.10', '3.11', '3.12', '3.13', '3.14', '3.15'] + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-python@v5 + with: + python-version: ${{ matrix.python }} + - uses: actions/download-artifact@v4 + with: + name: native-${{ matrix.os }} + path: .native + - name: Build the wheel and install it in a fresh environment + run: python scripts/ci.py install-wheel + - name: Test every repository fixture against the installed wheel + run: python scripts/ci.py test-installed + - uses: actions/upload-artifact@v4 + if: always() + with: + name: evidence-${{ matrix.os }}-${{ matrix.python }} + include-hidden-files: true + path: .ci-evidence/* + if-no-files-found: warn + retention-days: 7 diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..a95ed1e --- /dev/null +++ b/.gitignore @@ -0,0 +1,11 @@ +/build/ +/dist/ +*.egg-info/ +__pycache__/ +# CI working folders +.ci-evidence/ +.ci-venv/ +.ci-build-venv/ +.native/ +.native-src/ +dist/ diff --git a/LICENSE.md b/LICENSE.md new file mode 100644 index 0000000..82520bb --- /dev/null +++ b/LICENSE.md @@ -0,0 +1,33 @@ +Licenses & Copyright +==================== + +This license file adheres to the formatting guidelines of +[readable-licenses](https://github.com/nevir/readable-licenses). + + +Ribose's BSD 2-Clause License +----------------------------- + +Copyright (c) 2021-2025, [Ribose Inc](https://www.ribose.com). +All rights reserved. + +Redistribution and use in source and binary forms, with or without modification, +are permitted provided that the following conditions are met: + +1. Redistributions of source code must retain the above copyright notice, + this list of conditions and the following disclaimer. + +2. Redistributions in binary form must reproduce the above copyright notice, + this list of conditions and the following disclaimer in the documentation + and/or other materials provided with the distribution. + +THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND +ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED +WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE +DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE +FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR +SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER +CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, +OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. diff --git a/README.md b/README.md index c2c498c..0289609 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,26 @@ -# unitsml-python +# UnitsML for Python -UnitsML unit models, rendering and conversion library. +`unitsml.evaluate(request)` evaluates exact string magnitudes and unit +operands. The structural request accepts a producer model or terms +containing unit identifiers, optional prefixes and exact powers. For an +`expression` operand, the installed AsciiUnits package supplies that same +structural model. Both packages use their native libraries. -Implementation is being prepared on a separate task branch. +```python +import unitsml + +result = unitsml.evaluate({ + "op": "convert", + "left": {"value": "1", "expression": "km"}, + "right": {"expression": "m"}, +}) +print(result["magnitude"]) +``` + +The native result preserves exact rational text and quantity metadata. +`evaluate_wire` accepts JSON text or UTF-8 bytes and exposes the full +ABI outcome. `evaluate` raises typed errors carrying the outcome class, +native code and detail. AsciiUnits refusals preserve their byte offsets. + +Install the matching AsciiUnits and UnitsML host wheels together. The +UnitsML wheel verifies its native payload digest on load. diff --git a/ci/native-source.json b/ci/native-source.json new file mode 100644 index 0000000..7f3bc99 --- /dev/null +++ b/ci/native-source.json @@ -0,0 +1,44 @@ +{ + "package": "unitsml", + "planned_repository": "unitsml/unitsml-python", + "qualified_source_head": "f10d4aaf87345680108394367570ddf179bfa72c", + "rust_toolchain": "1.95.0", + "native": { + "kind": "prebuilt-library", + "repository": "unitsml/unitsml-rs", + "local": "workspace/units-native/unitsml-rs", + "revision": "fd3b3cbdd3bb91f732e5c8f2d76ff86a8168ec49", + "public": true, + "deps": { + "unitsdb_rs": { + "repository": "unitsml/unitsdb-rs", + "revision": "c631488e03f58c5cfd0ada369948b946a23a4f42", + "public": true, + "checkout_as": "unitsdb-rs" + }, + "asciiunits_python": { + "repository": "unitsml/asciiunits-python", + "revision": "2e85f6c9320199cbcba1e91556b6722723ef5d8d", + "public": true, + "build_wheel": true, + "note": "merged unitsml/asciiunits-python main; carries the qualified 5c185e27 sources plus delivery CI" + }, + "f40_corpus": { + "repository": "unitsml/unitsml-testsuite", + "revision": "877530fd9a04ed8c9026dafc2ee5127215e2bd00", + "public": true + } + }, + "library_stem": "unitsml_rs", + "binary_policy": "CI builds the pinned clean source with scripts/build-native-receipt.py; build-wheel.py --build-receipt validates commit, Cargo.lock, platform, metadata and the actual library hash. Without a receipt the fixed library_sha256 pin is enforced." + }, + "data": null, + "tests": [ + "tests/test_installed.py" + ], + "python_runtime": { + "repository": "parsanol/parsanol-python", + "revision": "7bb1e554ec29dcd82ee7a2c467bc46309170ceeb", + "note": "only for packages that load Parsanol at runtime; none of these five does (native stages are self-contained)" + } +} diff --git a/native-source.json b/native-source.json new file mode 100644 index 0000000..307066d --- /dev/null +++ b/native-source.json @@ -0,0 +1,13 @@ +{ + "native_source_commit": "fd3b3cbdd3bb91f732e5c8f2d76ff86a8168ec49", + "library_sha256": "b27039135260c41d801f49064f0d066bb8e4ba7636c6af8cac2d75b63b4baa9a", + "cargo_lock_sha256": "26c4f9e73ce68a99d08dc2bfb69b8f268cc0fb8aa3b3928d7cc03ecaccdd33d1", + "unitsdb_commit": "c631488e03f58c5cfd0ada369948b946a23a4f42", + "unitsdb_data_sha256": "660b471fd895d99a74849adaf1cfb0ec4570cd5dbcd9ebf695970af0dc0b3c97", + "asciiunits_python_commit": "5c185e271220604648da2a036b4dc94c729fa952", + "asciiunits_wheel_sha256": "0f83d4cb6c9a9897a9ce317f5442c961ccc0d8bb781d4caa893d0eab48471de9", + "f40_corpus_commit": "877530fd9a04ed8c9026dafc2ee5127215e2bd00", + "f40_payload_sha256": "2cacb0b5b3c66f7c8a960b73e638b892afb86dd44ee4838371f132c2c5b60218", + "target": "x86_64-unknown-linux-gnu", + "platform_tag": "linux_x86_64" +} diff --git a/pyproject.toml b/pyproject.toml new file mode 100644 index 0000000..3bbbab1 --- /dev/null +++ b/pyproject.toml @@ -0,0 +1,15 @@ +[build-system] +requires = ["setuptools>=69", "wheel>=0.43"] +build-backend = "setuptools.build_meta" + +[project] +name = "unitsml" +version = "0.1.0" +description = "Exact native UnitsML quantity operations" +requires-python = ">=3.9" +license = {file = "LICENSE.md"} +readme = "README.md" +dependencies = ["asciiunits==0.1.0"] + +[tool.setuptools.packages.find] +where = ["src"] diff --git a/scripts/build-native-receipt.py b/scripts/build-native-receipt.py new file mode 100644 index 0000000..2999480 --- /dev/null +++ b/scripts/build-native-receipt.py @@ -0,0 +1,85 @@ +"""Build the pinned native library from a clean pinned checkout and write a build receipt. + +The receipt records what CI actually built: source commit, Cargo.lock hash, target and +platform, compiler and Cargo versions, the exact build invocation, and the resulting +library hash. scripts/build-wheel.py --build-receipt validates this receipt against +the repository pins and the actual binary before packing. It does not replace the pinned +library_sha256 path, which stays the default. +""" + +import argparse +from hashlib import sha256 +import json +import os +from pathlib import Path +import shutil +import subprocess +import sys +import sysconfig + +ROOT = Path(__file__).resolve().parents[1] + + +def digest(path): + return sha256(Path(path).read_bytes()).hexdigest() + + +def main(): + cli = argparse.ArgumentParser(description=__doc__) + cli.add_argument("--rust-source", required=True, type=Path) + cli.add_argument("--target-dir", required=True, type=Path) + cli.add_argument("--out-dir", required=True, type=Path) + cli.add_argument("--pins", type=Path, default=ROOT / "native-source.json") + cli.add_argument("--library-name", required=True, help="cdylib file name, e.g. libomml.so") + args = cli.parse_args() + source = args.rust_source.resolve() + pins = json.loads(args.pins.read_bytes()) + revision = subprocess.check_output(["git", "rev-parse", "HEAD"], cwd=source, text=True).strip() + if revision != pins["native_source_commit"]: + raise SystemExit(f"refusing to build: checkout is {revision}, pinned {pins['native_source_commit']}") + if subprocess.check_output(["git", "status", "--porcelain", "--untracked-files=all"], cwd=source): + raise SystemExit("refusing to build: native checkout is not clean") + lock = digest(source / "Cargo.lock") + if lock != pins["cargo_lock_sha256"]: + raise SystemExit(f"refusing to build: Cargo.lock {lock} differs from pinned {pins['cargo_lock_sha256']}") + library_name = args.library_name + rustc = subprocess.check_output(["rustc", "-vV"], text=True) + host = next(l.removeprefix("host: ") for l in rustc.splitlines() if l.startswith("host: ")) + cargo = subprocess.check_output(["cargo", "-V"], text=True).strip() + target = args.target_dir.resolve() + invocation = ["cargo", "build", "--locked", "--release", "--lib"] + for feature in pins.get("features", []): + invocation += ["--features", feature] + env = dict(os.environ, CARGO_TARGET_DIR=str(target)) + subprocess.run(invocation, cwd=source, env=env, check=True) + built = target / "release" / library_name + if not built.is_file(): + raise SystemExit(f"cargo did not produce {library_name}") + out = args.out_dir.resolve() + out.mkdir(parents=True, exist_ok=True) + library = out / library_name + shutil.copy2(built, library) + metadata = out / "cargo-metadata.json" + metadata.write_bytes(subprocess.check_output( + ["cargo", "metadata", "--locked", "--format-version", "1", "--filter-platform", host], cwd=source, env=env)) + receipt = { + "kind": "native-build-receipt/v1", + "native_source_commit": revision, + "cargo_lock_sha256": lock, + "platform_tag": sysconfig.get_platform().replace("-", "_").replace(".", "_"), + "target": host, + "rustc": rustc.strip().splitlines()[0], + "rustc_verbose": rustc.strip(), + "cargo": cargo, + "invocation": invocation, + "profile": "release", + "library": library_name, + "library_sha256": digest(library), + "cargo_metadata_sha256": digest(metadata), + } + (out / "build-receipt.json").write_text(json.dumps(receipt, indent=2) + "\n") + print(json.dumps({k: receipt[k] for k in ("native_source_commit", "platform_tag", "library", "library_sha256")})) + + +if __name__ == "__main__": + sys.exit(main()) diff --git a/scripts/build-wheel.py b/scripts/build-wheel.py new file mode 100644 index 0000000..d7ec118 --- /dev/null +++ b/scripts/build-wheel.py @@ -0,0 +1,112 @@ +"""Package the pinned native UnitsML build in a host-platform wheel.""" + +import argparse +from hashlib import sha256 +import json +import os +from pathlib import Path +import shutil +import subprocess +import sys +import sysconfig +from tempfile import TemporaryDirectory + +ROOT = Path(__file__).resolve().parents[1] + + +def digest(path): + return sha256(path.read_bytes()).hexdigest() + + +def validated_receipt(path, pins, binary, metadata_path, platform_tag): + """CI-produced artifact path: every receipt field must agree with the pins, the host + platform and the actual files. Nothing is skipped or rewritten.""" + receipt = json.loads(Path(path).read_bytes()) + if receipt.get("kind") != "native-build-receipt/v1": + raise RuntimeError("Build receipt has an unknown kind") + if receipt["native_source_commit"] != pins["native_source_commit"]: + raise RuntimeError("Build receipt source commit differs from the pinned native source") + if receipt["cargo_lock_sha256"] != pins["cargo_lock_sha256"]: + raise RuntimeError("Build receipt Cargo.lock differs from the pinned lockfile") + if receipt["platform_tag"] != pins["platform_tag"] or receipt["platform_tag"] != platform_tag: + raise RuntimeError("Build receipt platform differs from the pinned wheel platform") + if receipt["library"] != binary.name: + raise RuntimeError("Build receipt names a different library") + if digest(binary) != receipt["library_sha256"]: + raise RuntimeError("Library differs from the binary recorded in the build receipt") + if digest(metadata_path) != receipt["cargo_metadata_sha256"]: + raise RuntimeError("Cargo metadata differs from the build receipt") + return receipt + + +def main(): + cli = argparse.ArgumentParser(description=__doc__) + cli.add_argument("--rust-source", required=True, type=Path) + cli.add_argument("--library", required=True, type=Path) + cli.add_argument("--cargo-metadata", required=True, type=Path) + cli.add_argument("--wheel-dir", required=True, type=Path) + cli.add_argument("--build-receipt", type=Path, help="CI build receipt from scripts/build-native-receipt.py; replaces only the fixed library_sha256 comparison, after validating the receipt") + args = cli.parse_args() + source = args.rust_source.resolve() + pins = json.loads((ROOT / "native-source.json").read_bytes()) + revision = subprocess.check_output(["git", "rev-parse", "HEAD"], cwd=source, text=True).strip() + if revision != pins["native_source_commit"]: + raise RuntimeError("Rust checkout is at a different revision") + if subprocess.check_output(["git", "status", "--porcelain"], cwd=source): + raise RuntimeError("Rust checkout must be clean") + if digest(source / "Cargo.lock") != pins["cargo_lock_sha256"]: + raise RuntimeError("Cargo.lock differs from the pinned bytes") + binary = args.library.resolve() + platform_tag = sysconfig.get_platform().replace("-", "_").replace(".", "_") + if platform_tag != pins["platform_tag"] or binary.name != "libunitsml_rs.so": + raise RuntimeError("Native library does not target this wheel platform") + build_receipt = None + if args.build_receipt: + build_receipt = validated_receipt(args.build_receipt, pins, binary, args.cargo_metadata, platform_tag) + elif digest(binary) != pins["library_sha256"]: + raise RuntimeError("Library differs from the pinned native build") + metadata = json.loads(args.cargo_metadata.read_bytes()) + if Path(metadata["workspace_root"]).resolve() != source: + raise RuntimeError("Cargo metadata belongs to a different checkout") + env = os.environ.copy() + with TemporaryDirectory(prefix="unitsml-wheel-") as temporary: + staging = Path(temporary) + notices = staging / "licenses" + notices.mkdir() + dependencies = [] + for package in metadata["packages"]: + base = Path(package["manifest_path"]).parent + name_version = f"{package['name']}-{package['version']}" + files = {path for path in base.iterdir() if path.is_file() and + path.name.upper().startswith(("LICENSE", "COPYING", "NOTICE"))} + if package.get("license_file"): + files.add(base / package["license_file"]) + recorded = {} + for path in sorted(files): + destination = notices / name_version / path.name + destination.parent.mkdir(exist_ok=True) + shutil.copyfile(path, destination) + recorded[str(destination.relative_to(notices))] = digest(destination) + dependencies.append({ + "name": package["name"], "version": package["version"], + "license": package.get("license"), "notices": recorded, + }) + (notices / "manifest.json").write_text(json.dumps(dependencies, indent=2) + "\n") + receipt = staging / "build-info.json" + receipt.write_text(json.dumps({ + **pins, "library": binary.name, "sha256": digest(binary), "abi_version": 1, + "binary_provenance": "ci-build-receipt" if build_receipt else "pinned-binary", + "build_receipt": build_receipt, + "cargo_metadata_sha256": digest(args.cargo_metadata), + }, indent=2) + "\n") + env["UNITSML_NATIVE"] = str(binary) + env["UNITSML_NATIVE_RECEIPT"] = str(receipt) + subprocess.run( + [sys.executable, "-m", "pip", "wheel", "--no-build-isolation", "--no-deps", + "--wheel-dir", str(args.wheel_dir.resolve()), "."], + cwd=ROOT, env=env, check=True, + ) + + +if __name__ == "__main__": + main() diff --git a/scripts/ci.py b/scripts/ci.py new file mode 100644 index 0000000..050e1e7 --- /dev/null +++ b/scripts/ci.py @@ -0,0 +1,216 @@ +"""Repository-native CI: pinned public native build, wheel, fresh install, installed tests. + +Configuration lives in ci/native-source.json. Native sources are fetched from their +public GitHub repositories at the pinned revision. For local qualification before +those repositories exist, set CI_LOCAL_SOURCES to a JSON object mapping repository +names ("owner/name") to local clones that contain the pinned revision. +""" +from __future__ import annotations +import argparse, hashlib, json, os, shutil, subprocess, sys, tempfile, time, venv +from pathlib import Path + +ROOT = Path(__file__).resolve().parents[1] +CONFIG = json.loads((ROOT / "ci/native-source.json").read_text(encoding="utf-8")) +PACKAGE = CONFIG["package"] +NATIVE = CONFIG.get("native") +EVIDENCE = ROOT / ".ci-evidence" +STAGING = ROOT / ".native" +SOURCES = ROOT / ".native-src" +LOCAL = json.loads(os.environ.get("CI_LOCAL_SOURCES", "{}")) + + +def digest(path): + return hashlib.sha256(Path(path).read_bytes()).hexdigest() + + +def run(command, label, cwd=ROOT, env=None, timeout=3600): + EVIDENCE.mkdir(exist_ok=True) + start = time.monotonic() + result = subprocess.run([str(c) for c in command], cwd=cwd, env=env, text=True, + stdout=subprocess.PIPE, stderr=subprocess.STDOUT, timeout=timeout) + (EVIDENCE / f"{label}.log").write_text(result.stdout, encoding="utf-8") + (EVIDENCE / f"{label}.json").write_text(json.dumps({ + "command": [str(c) for c in command], "exit_code": result.returncode, + "seconds": round(time.monotonic() - start, 3)}, indent=2) + "\n", encoding="utf-8") + if result.returncode: + print(result.stdout[-6000:]) + raise SystemExit(f"{label} exited {result.returncode}; full output in .ci-evidence") + return result.stdout + + +def checkout(pin, name): + """Clone repository@revision into .native-src/ (public URL, or a local override).""" + repository, revision = pin["repository"], pin["revision"] + target = SOURCES / name + if (target / ".git").exists(): + current = subprocess.check_output(["git", "rev-parse", "HEAD"], cwd=target, text=True).strip() + if current == revision: + return target + shutil.rmtree(target) + target.mkdir(parents=True) + origin = LOCAL.get(repository) or f"https://github.com/{repository}.git" + run(["git", "init", "-q", target], f"clone-{name}-init") + run(["git", "-C", target, "fetch", "-q", "--depth", "1", origin, revision], f"clone-{name}-fetch") + run(["git", "-C", target, "checkout", "-q", "FETCH_HEAD"], f"clone-{name}-checkout") + got = subprocess.check_output(["git", "rev-parse", "HEAD"], cwd=target, text=True).strip() + if got != revision: + raise SystemExit(f"{repository}: expected {revision}, fetched {got}") + return target + + +def native_dir(): + return ROOT / "src" / PACKAGE / "_native" + + +def library_file(stem): + if sys.platform == "win32": + return f"{stem}.dll" + return f"lib{stem}." + ("dylib" if sys.platform == "darwin" else "so") + + +def sibling_checkouts(): + """Path dependencies (e.g. ../unitsdb-rs) are checked out next to the main source at their pins.""" + for dep in (NATIVE.get("deps") or {}).values(): + if dep.get("checkout_as"): + checkout(dep, dep["checkout_as"]) + + +def build_sibling_wheels(): + """Runtime Python dependencies that are themselves native packages (unitsml needs asciiunits) + are built here from their public pinned repository with that repository's own scripts/ci.py, + and shipped to the installed-wheel jobs as staged wheels (the install uses --no-index).""" + for name, dep in (NATIVE.get("deps") or {}).items(): + if not dep.get("build_wheel"): + continue + source = checkout(dep, name) + run([sys.executable, source / "scripts/ci.py", "build-native"], f"{name}-build-native", cwd=source) + run([sys.executable, source / "scripts/ci.py", "install-wheel"], f"{name}-install-wheel", cwd=source) + extra = STAGING / "extra" + extra.mkdir(parents=True, exist_ok=True) + for wheel in sorted((source / "dist").glob("*.whl")): + shutil.copy2(wheel, extra / wheel.name) + + +def build_native(): + STAGING.mkdir(exist_ok=True) + kind = NATIVE["kind"] + sibling_checkouts() + rust = checkout(NATIVE, "rust") + if kind == "mml-dual": + framework = checkout(NATIVE["framework"], "framework") + run([sys.executable, ROOT / "build_native.py", "--framework-source", framework, + "--rust-source", rust, "--target-dir", SOURCES / "target"], "build-native") + shutil.copytree(native_dir(), STAGING / "_native", dirs_exist_ok=True) + elif kind == "prebuilt-library": + # The CI producer builds the pinned clean source and records a build receipt; + # scripts/build-wheel.py validates it against the pins and the actual binary. + run([sys.executable, ROOT / "scripts/build-native-receipt.py", "--rust-source", rust, + "--target-dir", SOURCES / "target", "--out-dir", STAGING, + "--library-name", library_file(NATIVE["library_stem"])], "build-native") + elif kind == "cargo-build": + pass # the package's own wheel builder runs cargo itself + else: + raise SystemExit(f"unknown native kind {kind}") + build_sibling_wheels() + (STAGING / "receipt.json").write_text(json.dumps({ + "rust_revision": NATIVE["revision"], "files": {p.name: digest(p) for p in STAGING.rglob("*") if p.is_file()}}, + indent=2) + "\n") + + +def build_python(): + """Isolated build environment: Python 3.12+ runners ship without setuptools, and the + package builders call pip with --no-build-isolation.""" + env_dir = ROOT / ".ci-build-venv" + python = env_dir / ("Scripts/python.exe" if sys.platform == "win32" else "bin/python") + if not python.exists(): + venv.EnvBuilder(with_pip=True, clear=True).create(env_dir) + run([python, "-m", "pip", "install", "--quiet", "setuptools>=61", "wheel"], "build-env") + return python + + +def build_wheel(dist): + dist.mkdir(parents=True, exist_ok=True) + py = build_python() + if NATIVE is None: + run([py, "-m", "pip", "wheel", "--no-deps", "--no-build-isolation", "-w", dist, ROOT], "wheel") + return + kind = NATIVE["kind"] + sibling_checkouts() + rust = checkout(NATIVE, "rust") + # The native and wheel jobs use different runners. Restore the exact locked + # dependency sources needed to package their notices; no native rebuild. + run(["cargo", "fetch", "--locked"], "fetch-wheel-notice-sources", cwd=rust) + if kind == "mml-dual": + shutil.copytree(STAGING / "_native", native_dir(), dirs_exist_ok=True) + run([py, "-m", "pip", "wheel", "--no-deps", "--no-build-isolation", "-w", dist, ROOT], "wheel") + elif kind == "prebuilt-library": + library = STAGING / library_file(NATIVE["library_stem"]) + run([py, ROOT / "scripts/build-wheel.py", "--rust-source", rust, "--library", library, + "--cargo-metadata", STAGING / "cargo-metadata.json", "--build-receipt", STAGING / "build-receipt.json", + "--wheel-dir", dist], "wheel") + elif kind == "cargo-build": + run([py, ROOT / "scripts/build-wheel.py", "--rust-source", rust, + "--target-dir", SOURCES / "target", "--wheel-dir", dist], "wheel") + + +def environment(): + return ROOT / ".ci-venv" + + +def install_wheel(): + dist = ROOT / "dist" + if dist.exists(): + shutil.rmtree(dist) + build_wheel(dist) + wheels = sorted(dist.glob("*.whl")) + if len(wheels) != 1: + raise SystemExit(f"expected one wheel, found {[w.name for w in wheels]}") + if environment().exists(): + shutil.rmtree(environment()) + venv.EnvBuilder(with_pip=True, clear=True).create(environment()) + python = environment() / ("Scripts/python.exe" if sys.platform == "win32" else "bin/python") + extra = json.loads(os.environ.get("CI_EXTRA_WHEELS", "[]")) # e.g. unitsml needs the asciiunits wheel + extra += [str(w) for w in sorted((STAGING / "extra").glob("*.whl"))] + run([python, "-m", "pip", "install", "--no-index", *extra, wheels[0]], "install") + (EVIDENCE / "wheel.json").write_text(json.dumps({"wheel": wheels[0].name, "sha256": digest(wheels[0])}, indent=2) + "\n") + + +def test_installed(): + python = environment() / ("Scripts/python.exe" if sys.platform == "win32" else "bin/python") + with tempfile.TemporaryDirectory(prefix=f"{PACKAGE}-installed-") as work: + tests = Path(work) / "tests" + if (ROOT / "tests").exists(): + shutil.copytree(ROOT / "tests", tests) + location = run([python, "-c", f"import {PACKAGE}, pathlib; print(pathlib.Path({PACKAGE}.__file__).resolve())"], + "import-location", cwd=work).strip() + if Path(location).is_relative_to(ROOT / "src"): + raise SystemExit(f"{PACKAGE} imported from the source tree, not the installed wheel: {location}") + if CONFIG["tests"]: + names = [Path(t).stem for t in CONFIG["tests"]] + run([python, "-m", "unittest", "-v", *names], "test-installed", cwd=tests) + else: + run([python, "-c", SEAL_CHECK], "test-installed", cwd=work) + + +SEAL_CHECK = """ +import hashlib, json, importlib.resources as r +data = r.files('unitsdb') / 'data' +manifest = json.loads((data / 'manifest.json').read_text()) +text = json.dumps(manifest) +for name in ('unitsdb.json', 'lookup-index.json'): + sha = hashlib.sha256((data / name).read_bytes()).hexdigest() + assert sha in text, (name, sha) + print(name, sha) +print('seals ok') +""" + + +def main(): + cli = argparse.ArgumentParser(description=__doc__) + cli.add_argument("step", choices=("build-native", "install-wheel", "test-installed")) + step = cli.parse_args().step + {"build-native": build_native, "install-wheel": install_wheel, "test-installed": test_installed}[step]() + + +if __name__ == "__main__": + main() diff --git a/setup.py b/setup.py new file mode 100644 index 0000000..bf6ff55 --- /dev/null +++ b/setup.py @@ -0,0 +1,47 @@ +from hashlib import sha256 +import json +import os +from pathlib import Path +import shutil +import sysconfig + +from setuptools import Distribution, setup +from setuptools.command.build_py import build_py +from wheel.bdist_wheel import bdist_wheel + + +class NativeDistribution(Distribution): + def has_ext_modules(self): + return True + + +class NativeWheel(bdist_wheel): + def get_tag(self): + return "py3", "none", sysconfig.get_platform().replace("-", "_").replace(".", "_") + + +class BuildNative(build_py): + def run(self): + super().run() + try: + binary = Path(os.environ["UNITSML_NATIVE"]) + receipt = Path(os.environ["UNITSML_NATIVE_RECEIPT"]) + except KeyError as error: + raise RuntimeError("Supply the pinned unitsml-rs library and its native receipt") from error + info = json.loads(receipt.read_bytes()) + if binary.name != info["library"] or sha256(binary.read_bytes()).hexdigest() != info["sha256"]: + raise RuntimeError("Native library disagrees with its receipt") + platform = sysconfig.get_platform().replace("-", "_").replace(".", "_") + if info["platform_tag"] != platform: + raise RuntimeError("Native library receipt targets another platform") + native = Path(self.build_lib) / "unitsml" / "_native" + native.mkdir(parents=True, exist_ok=True) + shutil.copyfile(binary, native / binary.name) + shutil.copyfile(receipt, native / "build-info.json") + notices = receipt.parent / "licenses" + if not notices.is_dir(): + raise RuntimeError("Native dependency licenses are required") + shutil.copytree(notices, native / "licenses", dirs_exist_ok=True) + + +setup(distclass=NativeDistribution, cmdclass={"build_py": BuildNative, "bdist_wheel": NativeWheel}) diff --git a/src/unitsml/__init__.py b/src/unitsml/__init__.py new file mode 100644 index 0000000..537e0c9 --- /dev/null +++ b/src/unitsml/__init__.py @@ -0,0 +1,138 @@ +"""Exact UnitsML quantities backed by the native C ABI.""" + +from collections.abc import Mapping +from ctypes import CDLL, c_char_p, c_size_t, c_uint32, c_void_p, string_at +from functools import lru_cache +from hashlib import sha256 +import json +import os +from pathlib import Path + +__all__ = [ + "UnitsMLError", "EvaluationError", "IndeterminateError", "ResourceLimitError", + "NativeRuntimeError", "evaluate", "evaluate_wire", +] + + +class UnitsMLError(Exception): + """Base exception carrying an ABI outcome class and the native error.""" + + def __init__(self, outcome_class, error): + self.outcome_class = outcome_class + self.error = error + self.code = error["code"] + self.detail = error.get("detail") + super().__init__(self.detail or self.code) + + +class EvaluationError(UnitsMLError): + """Typed refusal of the requested operation.""" + + +class IndeterminateError(UnitsMLError): + """The requested result is indeterminate, for example division by zero.""" + + +class ResourceLimitError(EvaluationError): + """The native arithmetic budget was reached.""" + + +class NativeRuntimeError(UnitsMLError): + """The native library or its reply could not be used.""" + + +def _runtime_error(message): + return NativeRuntimeError("error", {"code": "native_runtime", "detail": message}) + + +@lru_cache(maxsize=1) +def _library(): + override = os.environ.get("UNITSML_CDYLIB") + try: + if override: + path = Path(override).resolve(strict=True) + else: + native = Path(__file__).parent / "_native" + info = json.loads((native / "build-info.json").read_bytes()) + path = native / info["library"] + if sha256(path.read_bytes()).hexdigest() != info["sha256"]: + raise _runtime_error("Packaged UnitsML library failed checksum verification") + library = CDLL(str(path)) + library.unitsml_abi_version.argtypes = [] + library.unitsml_abi_version.restype = c_uint32 + if library.unitsml_abi_version() != 1: + raise _runtime_error("Unsupported UnitsML C ABI version") + library.unitsml_evaluate_json_v1.argtypes = [c_char_p, c_size_t] + library.unitsml_evaluate_json_v1.restype = c_void_p + library.unitsml_free_json_v1.argtypes = [c_void_p] + library.unitsml_free_json_v1.restype = None + return library + except (OSError, AttributeError, KeyError, ValueError) as error: + raise _runtime_error(f"Could not load UnitsML runtime: {error}") from error + + +def evaluate_wire(request): + """Send UTF-8 JSON to the ABI and return its complete outcome envelope.""" + if isinstance(request, str): + request = request.encode("utf-8") + if not isinstance(request, bytes): + raise TypeError("UnitsML wire request must be str or bytes") + library = _library() + pointer = library.unitsml_evaluate_json_v1(request, len(request)) + if not pointer: + raise _runtime_error("UnitsML returned a null response") + try: + reply = json.loads(string_at(pointer)) + except (UnicodeError, ValueError) as error: + raise _runtime_error("UnitsML returned invalid JSON") from error + finally: + library.unitsml_free_json_v1(pointer) + if not isinstance(reply, dict) or reply.get("abi_version") != 1: + raise _runtime_error("UnitsML returned an invalid ABI envelope") + outcome = reply.get("class") + if outcome == "value" and "value" in reply: + return reply + error = reply.get("error") + if outcome in ("error", "indeterminate") and isinstance(error, dict) and isinstance(error.get("code"), str): + return reply + raise _runtime_error("UnitsML returned an invalid outcome envelope") + + +def _structural_request(request): + if not isinstance(request, Mapping): + raise TypeError("UnitsML request must be a mapping") + result = dict(request) + for side in ("left", "right"): + operand = result.get(side) + if not isinstance(operand, Mapping) or "expression" not in operand: + continue + operand = dict(operand) + expression = operand.pop("expression") + if "model" in operand or "terms" in operand: + raise EvaluationError("error", { + "code": "unsupported_operand", + "detail": "expression, model and terms are mutually exclusive", + }) + from asciiunits import parse + operand["model"] = parse(expression) + result[side] = operand + return result + + +def evaluate(request): + """Evaluate exact string operands and raise typed native refusals. + + Textual operands use the installed AsciiUnits parser. Structural + operands may supply a model or resolved terms directly. + """ + source = json.dumps(_structural_request(request), allow_nan=False, ensure_ascii=False) + reply = evaluate_wire(source) + outcome = reply["class"] + if outcome == "value": + return reply["value"] + error = reply["error"] + if outcome == "indeterminate": + raise IndeterminateError(outcome, error) + if error["code"] == "resource_limit": + raise ResourceLimitError(outcome, error) + raise EvaluationError(outcome, error) diff --git a/tests/CORPUS-LICENSE.md b/tests/CORPUS-LICENSE.md new file mode 100644 index 0000000..82520bb --- /dev/null +++ b/tests/CORPUS-LICENSE.md @@ -0,0 +1,33 @@ +Licenses & Copyright +==================== + +This license file adheres to the formatting guidelines of +[readable-licenses](https://github.com/nevir/readable-licenses). + + +Ribose's BSD 2-Clause License +----------------------------- + +Copyright (c) 2021-2025, [Ribose Inc](https://www.ribose.com). +All rights reserved. + +Redistribution and use in source and binary forms, with or without modification, +are permitted provided that the following conditions are met: + +1. Redistributions of source code must retain the above copyright notice, + this list of conditions and the following disclaimer. + +2. Redistributions in binary form must reproduce the above copyright notice, + this list of conditions and the following disclaimer in the documentation + and/or other materials provided with the distribution. + +THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND +ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED +WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE +DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE +FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR +SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER +CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, +OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. diff --git a/tests/f40-quantities.json b/tests/f40-quantities.json new file mode 100644 index 0000000..6166492 --- /dev/null +++ b/tests/f40-quantities.json @@ -0,0 +1,853 @@ +{ + "schema": "f40-unitsml-feature-vectors/1", + "producer": "unitsml-ruby", + "cases": [ + { + "id": "conv-mile-to-m", + "kind": "convert", + "input": { + "value": "1", + "unit": "mi", + "target": "m" + }, + "outcome": "ok", + "result": { + "value": { + "rational": "201168/125", + "decimal": "1609.344" + }, + "unit": "m", + "dimension_id": "NISTd1", + "dimension_vector": { + "Length": 1 + }, + "scale": "ratio" + } + }, + { + "id": "conv-km-to-m", + "kind": "convert", + "input": { + "value": "1", + "unit": "km", + "target": "m" + }, + "outcome": "ok", + "result": { + "value": { + "rational": "1000/1", + "decimal": "1000" + }, + "unit": "m", + "dimension_id": "NISTd1", + "dimension_vector": { + "Length": 1 + }, + "scale": "ratio" + } + }, + { + "id": "conv-bar-to-pa", + "kind": "convert", + "input": { + "value": "2", + "unit": "bar", + "target": "Pa" + }, + "outcome": "ok", + "result": { + "value": { + "rational": "200000/1", + "decimal": "200000" + }, + "unit": "Pa", + "dimension_id": "NISTd14", + "dimension_vector": { + "Length": -1, + "Mass": 1, + "Time": -2 + }, + "scale": "ratio" + } + }, + { + "id": "conv-kwh-to-j", + "kind": "convert", + "input": { + "value": "1", + "unit": "kW*h", + "target": "J" + }, + "outcome": "ok", + "result": { + "value": { + "rational": "3600000/1", + "decimal": "3600000" + }, + "unit": "J", + "dimension_id": "NISTd15", + "dimension_vector": { + "Length": 2, + "Mass": 1, + "Time": -2 + }, + "scale": "ratio" + } + }, + { + "id": "conv-mph-to-mps", + "kind": "convert", + "input": { + "value": "1", + "unit": "mi/h", + "target": "m/s" + }, + "outcome": "ok", + "result": { + "value": { + "rational": "1397/3125", + "decimal": "0.44704" + }, + "unit": "m/s", + "dimension_id": "NISTd11", + "dimension_vector": { + "Length": 1, + "Time": -1 + }, + "scale": "ratio" + } + }, + { + "id": "conv-km2-to-m2", + "kind": "convert", + "input": { + "value": "1", + "unit": "km^2", + "target": "m^2" + }, + "outcome": "ok", + "result": { + "value": { + "rational": "1000000/1", + "decimal": "1000000" + }, + "unit": "m^2", + "dimension_id": "NISTd8", + "dimension_vector": { + "Length": 2 + }, + "scale": "ratio" + } + }, + { + "id": "conv-in2-to-m2", + "kind": "convert", + "input": { + "value": "1", + "unit": "in^2", + "target": "m^2" + }, + "outcome": "ok", + "result": { + "value": { + "rational": "16129/25000000", + "decimal": "0.00064516" + }, + "unit": "m^2", + "dimension_id": "NISTd8", + "dimension_vector": { + "Length": 2 + }, + "scale": "ratio" + } + }, + { + "id": "conv-cm3-to-m3", + "kind": "convert", + "input": { + "value": "1", + "unit": "cm^3", + "target": "m^3" + }, + "outcome": "ok", + "result": { + "value": { + "rational": "1/1000000", + "decimal": "0.000001" + }, + "unit": "m^3", + "dimension_id": "NISTd10", + "dimension_vector": { + "Length": 3 + }, + "scale": "ratio" + } + }, + { + "id": "conv-degc-to-k", + "kind": "convert", + "input": { + "value": "100", + "unit": "degC", + "target": "K" + }, + "outcome": "ok", + "result": { + "value": { + "rational": "7463/20", + "decimal": "373.15" + }, + "unit": "K", + "dimension_id": "NISTd5", + "dimension_vector": { + "ThermodynamicTemperature": 1 + }, + "scale": "ratio" + } + }, + { + "id": "conv-k-to-degc", + "kind": "convert", + "input": { + "value": "0", + "unit": "K", + "target": "degC" + }, + "outcome": "ok", + "result": { + "value": { + "rational": "-5463/20", + "decimal": "-273.15" + }, + "unit": "degC", + "dimension_id": "NISTd5", + "dimension_vector": { + "ThermodynamicTemperature": 1 + }, + "scale": "interval" + } + }, + { + "id": "conv-kva-to-w", + "kind": "convert", + "input": { + "value": "1", + "unit": "kV*A", + "target": "W" + }, + "outcome": "ok", + "result": { + "value": { + "rational": "1000/1", + "decimal": "1000" + }, + "unit": "W", + "dimension_id": "NISTd16", + "dimension_vector": { + "Length": 2, + "Mass": 1, + "Time": -3 + }, + "scale": "ratio" + } + }, + { + "id": "conv-kva-to-kw", + "kind": "convert", + "input": { + "value": "1", + "unit": "kV*A", + "target": "kW" + }, + "outcome": "ok", + "result": { + "value": { + "rational": "1/1", + "decimal": "1" + }, + "unit": "kW", + "dimension_id": "NISTd16", + "dimension_vector": { + "Length": 2, + "Mass": 1, + "Time": -3 + }, + "scale": "ratio" + } + }, + { + "id": "conv-w-to-kva", + "kind": "convert", + "input": { + "value": "1500", + "unit": "W", + "target": "kV*A" + }, + "outcome": "ok", + "result": { + "value": { + "rational": "3/2", + "decimal": "1.5" + }, + "unit": "kV*A", + "dimension_id": "NISTd16", + "dimension_vector": { + "Length": 2, + "Mass": 1, + "Time": -3 + }, + "scale": "ratio" + } + }, + { + "id": "dim-V", + "kind": "dimension", + "input": { + "unit": "V" + }, + "outcome": "ok", + "result": { + "value": { + "rational": "1/1", + "decimal": "1" + }, + "unit": "V", + "dimension_id": "NISTd18", + "dimension_vector": { + "ElectricCurrent": -1, + "Length": 2, + "Mass": 1, + "Time": -3 + }, + "scale": "ratio" + } + }, + { + "id": "dim-A", + "kind": "dimension", + "input": { + "unit": "A" + }, + "outcome": "ok", + "result": { + "value": { + "rational": "1/1", + "decimal": "1" + }, + "unit": "A", + "dimension_id": "NISTd4", + "dimension_vector": { + "ElectricCurrent": 1 + }, + "scale": "ratio" + } + }, + { + "id": "dim-W", + "kind": "dimension", + "input": { + "unit": "W" + }, + "outcome": "ok", + "result": { + "value": { + "rational": "1/1", + "decimal": "1" + }, + "unit": "W", + "dimension_id": "NISTd16", + "dimension_vector": { + "Length": 2, + "Mass": 1, + "Time": -3 + }, + "scale": "ratio" + } + }, + { + "id": "dim-kVxA", + "kind": "dimension", + "input": { + "unit": "kV*A" + }, + "outcome": "ok", + "result": { + "value": { + "rational": "1/1", + "decimal": "1" + }, + "unit": "kV*A", + "dimension_id": "NISTd16", + "dimension_vector": { + "Length": 2, + "Mass": 1, + "Time": -3 + }, + "scale": "ratio" + } + }, + { + "id": "dim-mps", + "kind": "dimension", + "input": { + "unit": "m/s" + }, + "outcome": "ok", + "result": { + "value": { + "rational": "1/1", + "decimal": "1" + }, + "unit": "m/s", + "dimension_id": "NISTd11", + "dimension_vector": { + "Length": 1, + "Time": -1 + }, + "scale": "ratio" + } + }, + { + "id": "dim-N", + "kind": "dimension", + "input": { + "unit": "N" + }, + "outcome": "ok", + "result": { + "value": { + "rational": "1/1", + "decimal": "1" + }, + "unit": "N", + "dimension_id": "NISTd12", + "dimension_vector": { + "Length": 1, + "Mass": 1, + "Time": -2 + }, + "scale": "ratio" + } + }, + { + "id": "dim-degC", + "kind": "dimension", + "input": { + "unit": "degC" + }, + "outcome": "ok", + "result": { + "value": { + "rational": "1/1", + "decimal": "1" + }, + "unit": "degC", + "dimension_id": "NISTd5", + "dimension_vector": { + "ThermodynamicTemperature": 1 + }, + "scale": "interval" + } + }, + { + "id": "dim-K", + "kind": "dimension", + "input": { + "unit": "K" + }, + "outcome": "ok", + "result": { + "value": { + "rational": "1/1", + "decimal": "1" + }, + "unit": "K", + "dimension_id": "NISTd5", + "dimension_vector": { + "ThermodynamicTemperature": 1 + }, + "scale": "ratio" + } + }, + { + "id": "dim-Pa", + "kind": "dimension", + "input": { + "unit": "Pa" + }, + "outcome": "ok", + "result": { + "value": { + "rational": "1/1", + "decimal": "1" + }, + "unit": "Pa", + "dimension_id": "NISTd14", + "dimension_vector": { + "Length": -1, + "Mass": 1, + "Time": -2 + }, + "scale": "ratio" + } + }, + { + "id": "dim-J", + "kind": "dimension", + "input": { + "unit": "J" + }, + "outcome": "ok", + "result": { + "value": { + "rational": "1/1", + "decimal": "1" + }, + "unit": "J", + "dimension_id": "NISTd15", + "dimension_vector": { + "Length": 2, + "Mass": 1, + "Time": -2 + }, + "scale": "ratio" + } + }, + { + "id": "dim-me2", + "kind": "dimension", + "input": { + "unit": "m^2" + }, + "outcome": "ok", + "result": { + "value": { + "rational": "1/1", + "decimal": "1" + }, + "unit": "m^2", + "dimension_id": "NISTd8", + "dimension_vector": { + "Length": 2 + }, + "scale": "ratio" + } + }, + { + "id": "dim-1", + "kind": "dimension", + "input": { + "unit": "1" + }, + "outcome": "error", + "error_class": "NoMethodError", + "error_ancestors": [ + "NoMethodError", + "DidYouMean::Correctable", + "ErrorHighlight::CoreExt", + "NameError" + ], + "error_message": "undefined method '[]' for nil" + }, + { + "id": "kva-product", + "kind": "product", + "input": { + "left": [ + "10", + "kV" + ], + "right": [ + "5", + "A" + ] + }, + "outcome": "ok", + "result": { + "product": { + "value": { + "rational": "50/1", + "decimal": "50" + }, + "unit": "kV*A", + "dimension_id": "NISTd16", + "dimension_vector": { + "Length": 2, + "Mass": 1, + "Time": -3 + }, + "scale": "ratio" + }, + "equals_50000_W": false, + "equals_50_kW": true, + "to_W": { + "value": { + "rational": "50000/1", + "decimal": "50000" + }, + "unit": "W", + "dimension_id": "NISTd16", + "dimension_vector": { + "Length": 2, + "Mass": 1, + "Time": -3 + }, + "scale": "ratio" + }, + "to_kW": { + "value": { + "rational": "50/1", + "decimal": "50" + }, + "unit": "kW", + "dimension_id": "NISTd16", + "dimension_vector": { + "Length": 2, + "Mass": 1, + "Time": -3 + }, + "scale": "ratio" + } + } + }, + { + "id": "difference-degc", + "kind": "difference", + "input": { + "high": [ + "20", + "degC" + ], + "low": [ + "15", + "degC" + ], + "target": "K" + }, + "outcome": "ok", + "result": { + "value": { + "rational": "5/1", + "decimal": "5" + }, + "unit": "K", + "dimension_id": "NISTd5", + "dimension_vector": { + "ThermodynamicTemperature": 1 + }, + "scale": "ratio" + } + }, + { + "id": "pure-number", + "kind": "dimension", + "input": { + "value": "3", + "unit": null + }, + "outcome": "ok", + "result": { + "value": { + "rational": "3/1", + "decimal": "3" + }, + "unit": "3", + "dimension_id": null, + "dimension_vector": {}, + "scale": "ratio" + } + }, + { + "id": "kva-equals-50-W-upstream-spec", + "kind": "equality", + "input": { + "left": "10 kV * 5 A", + "right": "50 W" + }, + "outcome": "ok", + "result": { + "equal": true + } + }, + { + "id": "refuse-degc2-to-k2", + "kind": "refusal", + "input": { + "source": "refuse-degc2-to-k2" + }, + "outcome": "error", + "error_class": "Unitsml::Errors::ConversionError", + "error_ancestors": [ + "Unitsml::Errors::ConversionError", + "Unitsml::Errors::QuantityOperationError", + "Unitsml::Errors::BaseError" + ], + "error_message": "affine unit raised to power 2/1" + }, + { + "id": "refuse-m-to-s", + "kind": "refusal", + "input": { + "source": "refuse-m-to-s" + }, + "outcome": "error", + "error_class": "Unitsml::Errors::DimensionMismatchError", + "error_ancestors": [ + "Unitsml::Errors::DimensionMismatchError", + "Unitsml::Errors::QuantityOperationError", + "Unitsml::Errors::BaseError" + ], + "error_message": "dimension mismatch: {\"Length\" => 1} vs {\"Time\" => 1}" + }, + { + "id": "refuse-degc-to-k2", + "kind": "refusal", + "input": { + "source": "refuse-degc-to-k2" + }, + "outcome": "error", + "error_class": "Unitsml::Errors::DimensionMismatchError", + "error_ancestors": [ + "Unitsml::Errors::DimensionMismatchError", + "Unitsml::Errors::QuantityOperationError", + "Unitsml::Errors::BaseError" + ], + "error_message": "dimension mismatch: {\"ThermodynamicTemperature\" => 1} vs {\"ThermodynamicTemperature\" => 2}" + }, + { + "id": "refuse-v-plus-s", + "kind": "refusal", + "input": { + "source": "refuse-v-plus-s" + }, + "outcome": "error", + "error_class": "Unitsml::Errors::DimensionMismatchError", + "error_ancestors": [ + "Unitsml::Errors::DimensionMismatchError", + "Unitsml::Errors::QuantityOperationError", + "Unitsml::Errors::BaseError" + ], + "error_message": "dimension mismatch: {\"Length\" => 2, \"Mass\" => 1, \"Time\" => -3, \"ElectricCurrent\" => -1} vs {\"Time\" => 1}" + }, + { + "id": "refuse-degc-times-2", + "kind": "refusal", + "input": { + "source": "refuse-degc-times-2" + }, + "outcome": "error", + "error_class": "Unitsml::Errors::ScaleOperationError", + "error_ancestors": [ + "Unitsml::Errors::ScaleOperationError", + "Unitsml::Errors::QuantityOperationError", + "Unitsml::Errors::BaseError" + ], + "error_message": "scaling is not legal on a interval scale quantity" + }, + { + "id": "refuse-degc-times-degc", + "kind": "refusal", + "input": { + "source": "refuse-degc-times-degc" + }, + "outcome": "error", + "error_class": "Unitsml::Errors::ScaleOperationError", + "error_ancestors": [ + "Unitsml::Errors::ScaleOperationError", + "Unitsml::Errors::QuantityOperationError", + "Unitsml::Errors::BaseError" + ], + "error_message": "multiplication is not legal between interval and interval scale quantities" + }, + { + "id": "refuse-div-zero-quantity", + "kind": "refusal", + "input": { + "source": "refuse-div-zero-quantity" + }, + "outcome": "error", + "error_class": "Unitsml::Errors::IndeterminateResultError", + "error_ancestors": [ + "Unitsml::Errors::IndeterminateResultError", + "Unitsml::Errors::QuantityOperationError", + "Unitsml::Errors::BaseError" + ], + "error_message": "division by a zero quantity is indeterminate" + }, + { + "id": "refuse-div-zero-scalar", + "kind": "refusal", + "input": { + "source": "refuse-div-zero-scalar" + }, + "outcome": "error", + "error_class": "Unitsml::Errors::IndeterminateResultError", + "error_ancestors": [ + "Unitsml::Errors::IndeterminateResultError", + "Unitsml::Errors::QuantityOperationError", + "Unitsml::Errors::BaseError" + ], + "error_message": "division by a zero quantity is indeterminate" + }, + { + "id": "refuse-unknown-unit", + "kind": "refusal", + "input": { + "source": "refuse-unknown-unit" + }, + "outcome": "error", + "error_class": "Unitsml::Errors::ParseError", + "error_ancestors": [ + "Unitsml::Errors::ParseError", + "Unitsml::Errors::BaseError" + ], + "error_message": "[unitsml] Error: cannot parse \"notaunit_xyz\" as a UnitsML expression." + }, + { + "id": "refuse-both-keywords", + "kind": "refusal", + "input": { + "source": "refuse-both-keywords" + }, + "outcome": "error", + "error_class": "ArgumentError", + "error_ancestors": [ + "ErrorHighlight::CoreExt", + "ArgumentError" + ], + "error_message": "give only one of unit: or unit_expression:" + } + ], + "producer_source": { + "repository": "unitsml/unitsml-ruby", + "commit": "92b0f3481cd90e8a7b50ba9bd729363bec150a21", + "tree": "16b4620b43a538f5d9cbc0fddd030dfb181f95fb", + "ref": "origin/main", + "version": "0.6.14", + "unitsdb_gem": "2.2.13", + "unitsdb_data_seal": { + "sha256": "11daf72a52488bbdb7b48a1037dd1b00678c436f3f075f33939824b4e023fbe2", + "files": 14, + "method": "sha256 over sorted relpath NUL sha256 LF" + }, + "gemfile_lock_sha256": "2d777d00103f74c948a45cde5e5068ea299a566c2fadae4eccc94f66b004cec7", + "ruby": "ruby 3.4.8 (2025-12-17 revision 995b59f666) +PRISM [x64-mingw-ucrt]" + }, + "counts": { + "cases": 39, + "kinds": { + "convert": 13, + "dimension": 13, + "product": 1, + "difference": 1, + "equality": 1, + "refusal": 10 + }, + "ok": 28 + }, + "source_semantics_findings": [ + "Quantity#== compares raw value and dimension vector only: 10 kV * 5 A == 50 W is true (upstream quantity_spec asserts it) and 50 kV*A == 50000 W is false", + "Quantity.new(value: 3, unit: nil) reports dimension_id nil although the source comment says \"1\" for pure numbers", + "Quantity.new(value: 1, unit_expression: \"1\") raises untyped NoMethodError" + ] +} diff --git a/tests/test_installed.py b/tests/test_installed.py new file mode 100644 index 0000000..7133f15 --- /dev/null +++ b/tests/test_installed.py @@ -0,0 +1,162 @@ +from hashlib import sha256 +import json +from pathlib import Path +import unittest + +import asciiunits +import unitsml + +FIXTURE = Path(__file__).with_name("f40-quantities.json") + + +def operand(value=None, expression=None, **fields): + if value is not None: + fields["value"] = value + if expression is not None: + fields["expression"] = expression + return fields + + +def run(op, left, right=None, **fields): + request = {"op": op, "left": left, **fields} + if right is not None: + request["right"] = right + return unitsml.evaluate(request) + + +def exact_ratio(text): + return text if "/" in text else text + "/1" + + +def result_operand(value): + return operand(value["magnitude"], terms=value["terms"], difference=value["scale"] == "difference") + + +class InstalledQuantityTests(unittest.TestCase): + def assert_quantity(self, result, expected, unit=None, scale=None): + self.assertEqual(exact_ratio(result["magnitude"]), expected["value"]["rational"]) + self.assertEqual(result["dimension_id"], expected["dimension_id"]) + self.assertEqual(result["dimensions"], { + key: str(power) for key, power in (expected["dimension_vector"] or {}).items() + }) + self.assertEqual(result["scale"], scale or expected["scale"]) + if unit is None: + self.assertEqual(result["terms"], []) + else: + target = run("resolve", operand("1", unit)) + self.assertEqual(result["terms"], target["terms"]) + + def test_f40_source_cases(self): + data = FIXTURE.read_bytes() + self.assertEqual(sha256(data).hexdigest(), "2cacb0b5b3c66f7c8a960b73e638b892afb86dd44ee4838371f132c2c5b60218") + cases = json.loads(data)["cases"] + self.assertEqual(len(cases), 39) + for row in cases: + with self.subTest(case=row["id"]): + self.replay(row) + + def replay(self, row): + identity, kind, given = row["id"], row["kind"], row["input"] + expected = row.get("result") + if kind == "convert": + result = run("convert", operand(given["value"], given["unit"]), + operand(expression=given["target"])) + self.assert_quantity(result, expected, unit=given["target"]) + elif kind == "dimension": + result = run("resolve", operand(given.get("value", "1"), given["unit"])) + if identity == "dim-1": + # The historical Ruby call crashed; the structural profile has a dimensionless unit. + self.assertEqual(row["error_class"], "NoMethodError") + self.assertEqual(result, { + "magnitude": "1", "canonical_magnitude": "1", "dimension_id": None, + "dimensions": {}, "scale": "ratio", + "terms": [{"unit": "NISTu61", "prefix": None, "power": "1"}], + }) + else: + self.assert_quantity(result, expected, unit=given["unit"]) + elif kind == "difference": + result = run("subtract", operand(*given["high"]), operand(*given["low"])) + converted = run("convert", result_operand(result), operand(expression=given["target"])) + # The source records lost scale typing; preserve the exact difference on conversion. + self.assertEqual(expected["scale"], "ratio") + self.assert_quantity(converted, expected, unit=given["target"], scale="difference") + elif kind == "product": + product = run("multiply", operand(*given["left"]), operand(*given["right"])) + self.assert_quantity(product, expected["product"], unit=expected["product"]["unit"]) + for field, unit in (("to_W", "W"), ("to_kW", "kW")): + converted = run("convert", result_operand(product), operand(expression=unit)) + self.assert_quantity(converted, expected[field], unit=unit) + self.assertFalse(expected["equals_50000_W"]) + self.assertTrue(expected["equals_50_kW"]) + # Physical comparison uses the same exact canonical magnitude in both units. + self.assertEqual(run("compare", result_operand(product), operand("50000", "W")), 0) + self.assertEqual(run("compare", result_operand(product), operand("50", "kW")), 0) + elif kind == "equality": + self.assertEqual(given, {"left": "10 kV * 5 A", "right": "50 W"}) + self.assertTrue(expected["equal"]) + product = run("multiply", operand("10", "kV"), operand("5", "A")) + self.assertEqual(run("compare", result_operand(product), operand("50", "W")), 1) + elif kind == "refusal": + self.replay_refusal(identity, row["error_class"]) + else: + self.fail(f"Unsupported F40 case kind {kind}") + + def replay_refusal(self, identity, source_error): + if identity == "refuse-unknown-unit": + self.assertEqual(source_error, "Unitsml::Errors::ParseError") + with self.assertRaises(asciiunits.ParseError): + run("resolve", operand("1", "notaunit_xyz")) + return + choices = { + "refuse-degc2-to-k2": ("convert", operand("1", "degC^2"), operand(expression="K^2"), {}, "affine_composition", "ConversionError"), + "refuse-m-to-s": ("convert", operand("1", "m"), operand(expression="s"), {}, "dimension_mismatch", "DimensionMismatchError"), + "refuse-degc-to-k2": ("convert", operand("1", "degC"), operand(expression="K^2"), {}, "dimension_mismatch", "DimensionMismatchError"), + "refuse-v-plus-s": ("add", operand("1", "V"), operand("1", "s"), {}, "dimension_mismatch", "DimensionMismatchError"), + "refuse-degc-times-2": ("scale", operand("10", "degC"), None, {"scalar": "2"}, "scale_operation", "ScaleOperationError"), + "refuse-degc-times-degc": ("multiply", operand("10", "degC"), operand("2", "degC"), {}, "scale_operation", "ScaleOperationError"), + "refuse-div-zero-quantity": ("divide", operand("1", "m"), operand("0", "s"), {}, "division_by_zero", "IndeterminateResultError"), + "refuse-div-zero-scalar": ("divide_by", operand("1", "m"), None, {"scalar": "0"}, "division_by_zero", "IndeterminateResultError"), + "refuse-both-keywords": ("resolve", operand("1", model={"unitName": "m"}, terms=[]), None, {}, "invalid_request", "ArgumentError"), + } + op, left, right, fields, code, source_suffix = choices[identity] + self.assertEqual(source_error.split("::")[-1], source_suffix) + error_type = unitsml.IndeterminateError if code == "division_by_zero" else unitsml.EvaluationError + with self.assertRaises(error_type) as failure: + run(op, left, right, **fields) + self.assertEqual(failure.exception.code, code) + + def test_resource_and_syntax_reuse(self): + with self.assertRaises(unitsml.ResourceLimitError): + run("resolve", operand("1" * (1024 * 1024))) + with self.assertRaises(asciiunits.ResourceLimitError): + run("resolve", operand("1", "m/" * 256 + "m")) + with self.assertRaises(asciiunits.ParseError) as refusal: + run("resolve", operand("1", "")) + self.assertEqual(refusal.exception.byte_offset, 0) + self.assertEqual(unitsml.evaluate_wire(b"\xff")["error"]["code"], "invalid_request") + self.assertEqual(run("resolve", operand("1", "m"))["magnitude"], "1") + + def test_known_identity_without_conversion(self): + left = operand("2", terms=[{"unit": "NISTu230"}]) + self.assertEqual(run("identify", left), { + "magnitude": "2", + "terms": [{"unit": "NISTu230", "prefix": None, "power": "1"}], + }) + with self.assertRaises(unitsml.EvaluationError) as failure: + run("resolve", left) + self.assertEqual(failure.exception.code, "missing_conversion") + + def test_structural_operands_and_caller_register(self): + model = asciiunits.parse("cm^(1/2)") + by_model = run("resolve", operand("1", model=model)) + by_terms = run("resolve", operand("1", terms=[{"unit": "m", "prefix": "c", "power": "1/2"}])) + self.assertEqual(by_model, by_terms) + self.assertEqual(exact_ratio(by_model["canonical_magnitude"]), "1/10") + for factor, expected in (("50", "100"), ("60", "120")): + register = [{"unit": "NISTu230", "dimensions": {"Mass": "1"}, "factor": factor}] + result = run("resolve", operand("2", terms=[{"unit": "NISTu230"}]), register=register) + self.assertEqual(result["canonical_magnitude"], expected) + + +if __name__ == "__main__": + unittest.main()