rusttorch 0.2.0

Eager PyTorch-style neural networks and graph execution for Rust, backed by LibTorch
Documentation
#!/usr/bin/env python3
"""Validate RustTorch's locked Python tooling before creating an environment."""

from __future__ import annotations

import argparse
import re
import sys
import tomllib
from pathlib import Path, PurePosixPath
from typing import Any, Iterator
from urllib.parse import unquote, urlsplit


REPOSITORY_ROOT = Path(__file__).resolve().parents[1]
PYPI_REGISTRY = "https://pypi.org/simple"
PYPI_ARTIFACT_HOST = "files.pythonhosted.org"
PYTORCH_CPU_INDEX = "https://download.pytorch.org/whl/cpu"
PYTORCH_ARTIFACT_HOST = "download-r2.pytorch.org"
PYTHON_DEPENDENCIES = [
    "numpy==2.5.2",
    "safetensors==0.8.0",
    "torch==2.13.0",
]
EXPECTED_PACKAGES = [
    ("filelock", "3.32.4"),
    ("fsspec", "2026.7.0"),
    ("jinja2", "3.1.6"),
    ("markupsafe", "3.0.3"),
    ("mpmath", "1.3.0"),
    ("networkx", "3.6.1"),
    ("numpy", "2.5.2"),
    ("rusttorch-tooling", "0.0.0"),
    ("safetensors", "0.8.0"),
    ("setuptools", "84.0.0"),
    ("sympy", "1.14.0"),
    ("torch", "2.13.0"),
    ("torch", "2.13.0+cpu"),
    ("typing-extensions", "4.16.0"),
]
EXPECTED_DEPENDENCIES = {
    "jinja2": ["markupsafe"],
    "sympy": ["mpmath"],
    "torch": [
        "filelock",
        "fsspec",
        "jinja2",
        "networkx",
        "setuptools",
        "sympy",
        "typing-extensions",
    ],
}
EXPECTED_TORCH_WHEEL_BASENAMES = {
    "2.13.0": {
        "torch-2.13.0-cp314-cp314-macosx_14_0_arm64.whl",
        "torch-2.13.0-cp314-cp314t-macosx_14_0_arm64.whl",
    },
    "2.13.0+cpu": {
        "torch-2.13.0+cpu-cp314-cp314-linux_s390x.whl",
        "torch-2.13.0+cpu-cp314-cp314-manylinux_2_28_aarch64.whl",
        "torch-2.13.0+cpu-cp314-cp314-manylinux_2_28_x86_64.whl",
        "torch-2.13.0+cpu-cp314-cp314-win_amd64.whl",
        "torch-2.13.0+cpu-cp314-cp314t-linux_s390x.whl",
        "torch-2.13.0+cpu-cp314-cp314t-manylinux_2_28_aarch64.whl",
        "torch-2.13.0+cpu-cp314-cp314t-manylinux_2_28_x86_64.whl",
        "torch-2.13.0+cpu-cp314-cp314t-win_amd64.whl",
    },
}
SHA256 = re.compile(r"sha256:[0-9a-f]{64}")


class PythonLockError(ValueError):
    """Raised when the Python tooling manifest or lock is unsafe."""


def parse_args(argv: list[str] | None = None) -> argparse.Namespace:
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument("--root", type=Path)
    parser.add_argument("--pyproject", type=Path)
    parser.add_argument("--lock", type=Path)
    return parser.parse_args(argv)


def select_inputs(args: argparse.Namespace) -> tuple[Path, Path]:
    explicit_paths = args.pyproject is not None or args.lock is not None
    if args.root is not None and explicit_paths:
        raise PythonLockError("--root cannot be combined with --pyproject or --lock")
    if (args.pyproject is None) != (args.lock is None):
        raise PythonLockError("--pyproject and --lock must be provided together")
    if explicit_paths:
        return args.pyproject.resolve(), args.lock.resolve()
    root = REPOSITORY_ROOT if args.root is None else args.root.resolve()
    return root / "pyproject.toml", root / "uv.lock"


def load_toml(path: Path) -> dict[str, object]:
    with path.open("rb") as source:
        value = tomllib.load(source)
    if not isinstance(value, dict):
        raise PythonLockError(f"{path} must contain a TOML table")
    return value


def require_table(value: object, context: str) -> dict[str, Any]:
    if not isinstance(value, dict):
        raise PythonLockError(f"{context} must be a table")
    return value


def require_list(value: object, context: str) -> list[Any]:
    if not isinstance(value, list):
        raise PythonLockError(f"{context} must be an array")
    return value


def values_match(actual: object, expected: object) -> bool:
    if type(actual) is not type(expected):
        return False
    if isinstance(actual, dict) and isinstance(expected, dict):
        return set(actual) == set(expected) and all(
            values_match(actual[key], expected[key]) for key in actual
        )
    if isinstance(actual, (list, tuple)) and isinstance(expected, (list, tuple)):
        return len(actual) == len(expected) and all(
            values_match(actual_value, expected_value)
            for actual_value, expected_value in zip(actual, expected)
        )
    return actual == expected


def require_equal(actual: object, expected: object, context: str) -> None:
    if not values_match(actual, expected):
        raise PythonLockError(f"{context} does not match the locked policy")


def require_keys(table: dict[str, Any], expected: set[str], context: str) -> None:
    require_equal(set(table), expected, f"{context} fields")


def validate_manifest(pyproject: dict[str, object]) -> None:
    require_keys(pyproject, {"project", "tool"}, "pyproject")
    project = require_table(pyproject["project"], "project")
    require_keys(
        project,
        {"name", "version", "requires-python", "dependencies"},
        "project",
    )
    require_equal(project["name"], "rusttorch-tooling", "project name")
    require_equal(project["version"], "0.0.0", "project version")
    require_equal(
        project["requires-python"], ">=3.14,<3.15", "project Python range"
    )
    require_equal(project["dependencies"], PYTHON_DEPENDENCIES, "project dependencies")

    tool = require_table(pyproject["tool"], "tool")
    require_keys(tool, {"uv"}, "tool")
    uv = require_table(tool["uv"], "tool.uv")
    require_keys(uv, {"package", "sources", "index"}, "tool.uv")
    require_equal(uv["package"], False, "tool.uv package mode")
    require_equal(
        uv["sources"], {"torch": {"index": "pytorch-cpu"}}, "tool.uv sources"
    )
    require_equal(
        uv["index"],
        [{"name": "pytorch-cpu", "url": PYTORCH_CPU_INDEX, "explicit": True}],
        "tool.uv index",
    )


def iter_artifact_records(
    value: object, context: str
) -> Iterator[tuple[str, dict[str, Any]]]:
    if isinstance(value, dict):
        if "url" in value or "hash" in value:
            yield context, value
            return
        for key, nested in value.items():
            yield from iter_artifact_records(nested, f"{context}.{key}")
    elif isinstance(value, list):
        for index, nested in enumerate(value):
            yield from iter_artifact_records(nested, f"{context}[{index}]")


def validate_artifact(
    artifact: dict[str, Any], context: str, expected_host: str
) -> None:
    allowed_fields = {"url", "hash", "size", "upload-time"}
    if not {"url", "hash"}.issubset(artifact) or not set(artifact).issubset(
        allowed_fields
    ):
        raise PythonLockError(f"{context} must contain only a URL, hash, and metadata")
    url = artifact["url"]
    digest = artifact["hash"]
    if not isinstance(url, str) or not isinstance(digest, str):
        raise PythonLockError(f"{context} URL and hash must be strings")
    try:
        parsed_url = urlsplit(url)
    except ValueError as error:
        raise PythonLockError(f"{context} has an invalid URL") from error
    if (
        parsed_url.scheme != "https"
        or parsed_url.netloc != expected_host
        or parsed_url.query
        or parsed_url.fragment
    ):
        raise PythonLockError(f"{context} must use HTTPS from {expected_host}")
    if SHA256.fullmatch(digest) is None:
        raise PythonLockError(f"{context} must use a lowercase SHA-256 digest")
    if "size" in artifact and (
        type(artifact["size"]) is not int or artifact["size"] <= 0
    ):
        raise PythonLockError(f"{context} size must be a positive integer")
    if "upload-time" in artifact and (
        not isinstance(artifact["upload-time"], str) or not artifact["upload-time"]
    ):
        raise PythonLockError(f"{context} upload time must be a nonempty string")


def validate_dependency_names(
    package: dict[str, Any], name: str, context: str
) -> None:
    expected_names = EXPECTED_DEPENDENCIES.get(name)
    if expected_names is None:
        if "dependencies" in package:
            raise PythonLockError(f"{context} has unexpected dependencies")
        return
    dependencies = require_list(package["dependencies"], f"{context} dependencies")
    normalized = []
    for index, dependency_value in enumerate(dependencies):
        dependency = require_table(
            dependency_value, f"{context} dependency {index}"
        )
        require_keys(dependency, {"name"}, f"{context} dependency {index}")
        normalized.append(dependency["name"])
    require_equal(normalized, expected_names, f"{context} dependencies")


def validate_tooling_package(package: dict[str, Any]) -> None:
    context = "rusttorch-tooling package"
    require_keys(
        package,
        {"name", "version", "source", "dependencies", "metadata"},
        context,
    )
    require_equal(package["source"], {"virtual": "."}, f"{context} source")
    require_equal(
        package["dependencies"],
        [
            {"name": "numpy"},
            {"name": "safetensors"},
            {
                "name": "torch",
                "version": "2.13.0",
                "source": {"registry": PYTORCH_CPU_INDEX},
                "marker": "sys_platform == 'darwin'",
            },
            {
                "name": "torch",
                "version": "2.13.0+cpu",
                "source": {"registry": PYTORCH_CPU_INDEX},
                "marker": "sys_platform != 'darwin'",
            },
        ],
        f"{context} dependencies",
    )
    require_equal(
        package["metadata"],
        {
            "requires-dist": [
                {"name": "numpy", "specifier": "==2.5.2"},
                {"name": "safetensors", "specifier": "==0.8.0"},
                {
                    "name": "torch",
                    "specifier": "==2.13.0",
                    "index": PYTORCH_CPU_INDEX,
                },
            ]
        },
        f"{context} metadata",
    )
    if list(iter_artifact_records(package, context)):
        raise PythonLockError(f"{context} cannot contain downloadable artifacts")


def validate_registry_package(package: dict[str, Any], name: str, version: str) -> None:
    context = f"{name} {version} package"
    is_torch = name == "torch"
    fields = {"name", "version", "source", "wheels"}
    if is_torch:
        fields.update({"resolution-markers", "dependencies"})
    else:
        fields.add("sdist")
        if name in EXPECTED_DEPENDENCIES:
            fields.add("dependencies")
    require_keys(package, fields, context)
    expected_source = {
        "registry": PYTORCH_CPU_INDEX if is_torch else PYPI_REGISTRY
    }
    require_equal(package["source"], expected_source, f"{context} source")
    validate_dependency_names(package, name, context)

    wheels = require_list(package["wheels"], f"{context} wheels")
    if not wheels:
        raise PythonLockError(f"{context} must contain wheels")
    if is_torch:
        expected_marker = (
            ["sys_platform == 'darwin'"]
            if version == "2.13.0"
            else ["sys_platform != 'darwin'"]
        )
        require_equal(
            package["resolution-markers"], expected_marker, f"{context} markers"
        )

    artifacts = list(iter_artifact_records(package, context))
    expected_artifact_count = len(wheels) if is_torch else len(wheels) + 1
    require_equal(
        len(artifacts), expected_artifact_count, f"{context} artifact count"
    )
    expected_host = PYTORCH_ARTIFACT_HOST if is_torch else PYPI_ARTIFACT_HOST
    for artifact_context, artifact in artifacts:
        validate_artifact(artifact, artifact_context, expected_host)

    if is_torch:
        wheel_basenames = []
        for index, wheel_value in enumerate(wheels):
            wheel = require_table(wheel_value, f"{context} wheel {index}")
            url = wheel.get("url")
            if not isinstance(url, str):
                raise PythonLockError(f"{context} wheel {index} URL must be a string")
            parsed_url = urlsplit(url)
            path = PurePosixPath(parsed_url.path)
            basename = unquote(path.name)
            if path.parent.as_posix() != "/whl/cpu":
                raise PythonLockError(f"{context} wheels must use the CPU path")
            wheel_basenames.append(basename)
        expected_basenames = EXPECTED_TORCH_WHEEL_BASENAMES[version]
        if len(wheel_basenames) != len(expected_basenames) or set(
            wheel_basenames
        ) != expected_basenames:
            raise PythonLockError(f"{context} wheel platforms do not match policy")


def validate_lock(lock: dict[str, object]) -> None:
    require_keys(
        lock,
        {"version", "revision", "requires-python", "resolution-markers", "package"},
        "uv.lock",
    )
    require_equal(lock["version"], 1, "uv.lock version")
    require_equal(lock["revision"], 3, "uv.lock revision")
    require_equal(lock["requires-python"], "==3.14.*", "uv.lock Python range")
    require_equal(
        lock["resolution-markers"],
        ["sys_platform != 'darwin'", "sys_platform == 'darwin'"],
        "uv.lock resolution markers",
    )
    package_values = require_list(lock["package"], "uv.lock packages")
    packages = [
        require_table(value, f"uv.lock package {index}")
        for index, value in enumerate(package_values)
    ]
    package_versions = [(package.get("name"), package.get("version")) for package in packages]
    require_equal(package_versions, EXPECTED_PACKAGES, "uv.lock package versions")
    for package, (name, version) in zip(packages, EXPECTED_PACKAGES):
        if name == "rusttorch-tooling":
            validate_tooling_package(package)
        else:
            validate_registry_package(package, name, version)


def validate_python_lock(pyproject_path: Path, lock_path: Path) -> None:
    uv_config = pyproject_path.parent / "uv.toml"
    if uv_config.exists():
        raise PythonLockError(f"alternate UV configuration is forbidden: {uv_config}")
    validate_manifest(load_toml(pyproject_path))
    validate_lock(load_toml(lock_path))


def main(argv: list[str] | None = None) -> int:
    args = parse_args(argv)
    try:
        pyproject_path, lock_path = select_inputs(args)
        validate_python_lock(pyproject_path, lock_path)
    except (OSError, PythonLockError, tomllib.TOMLDecodeError) as error:
        print(f"error: {error}", file=sys.stderr)
        return 1
    return 0


if __name__ == "__main__":
    raise SystemExit(main())