from __future__ import annotations
import argparse
import html
import importlib.util
import os
from pathlib import Path, PurePosixPath
import re
import sys
import tempfile
import tomllib
from typing import Any
from urllib.parse import quote
TOP_LEVEL_FIELDS = {
"format_version",
"package",
"crate",
"tch",
"pytorch_reference",
"pytorch_commit",
"api",
}
EXPECTED_METADATA = {
"format_version": 2,
"package": "rusttorch",
"crate": "rusttorch",
"tch": "0.26.0",
"pytorch_reference": "v2.13.0",
"pytorch_commit": "cf30153",
}
ROW_FIELDS = {
"id",
"python_symbols",
"rust_symbols",
"status",
"implementation",
"scope",
"source",
"evidence",
"notes",
}
STATUSES = {"supported", "partial", "python_only", "planned", "not_supported"}
IMPLEMENTATIONS = {"libtorch", "rusttorch", "mixed", "none"}
NO_REQUIRED_RUST_SURFACE = {"python_only", "planned", "not_supported"}
ID_PATTERN = re.compile(r"^[a-z0-9]+(?:[._-][a-z0-9]+)*$")
TEST_NAME_PATTERN = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*$")
GENERATED_NOTICE = "<!-- Generated by scripts/check-compatibility.py. Do not edit directly. -->"
STATUS_SECTIONS = (
("supported", "Supported"),
("partial", "Partial"),
("planned", "Planned"),
("python_only", "Python-only"),
("not_supported", "Not supported"),
)
IMPLEMENTATION_LABELS = {
"libtorch": "Delegated to LibTorch",
"rusttorch": "Implemented by RustTorch",
"mixed": "RustTorch frontend backed by LibTorch",
"none": "Not implemented",
}
def load_ledger(path: Path) -> dict[str, Any]:
with path.open("rb") as ledger_file:
return tomllib.load(ledger_file)
def _unknown_and_missing(
value: dict[str, Any], expected: set[str], context: str
) -> list[str]:
errors = [f"{context}: unknown field '{field}'" for field in sorted(value.keys() - expected)]
errors.extend(
f"{context}: missing required field '{field}'"
for field in sorted(expected - value.keys())
)
return errors
def _string_list(value: Any, context: str, *, allow_empty: bool) -> tuple[list[str], list[str]]:
if not isinstance(value, list):
return [], [f"{context} must be an array of strings"]
errors: list[str] = []
if not allow_empty and not value:
errors.append(f"{context} must not be empty")
if any(not isinstance(item, str) or not item.strip() for item in value):
errors.append(f"{context} must contain only nonempty strings")
strings = [item for item in value if isinstance(item, str)]
if len(strings) != len(set(strings)):
errors.append(f"{context} must not contain duplicates")
return strings, errors
def _safe_relative_path(value: Any) -> bool:
if not isinstance(value, str) or not value or "\\" in value or ":" in value:
return False
path = PurePosixPath(value)
return (
not path.is_absolute()
and all(part not in {"", ".", ".."} for part in path.parts)
and value == path.as_posix()
)
def _declaration_exists(path: Path, test_name: str) -> bool:
contents = path.read_text(encoding="utf-8")
if path.suffix == ".rs":
declaration = re.compile(
rf"(?P<attributes>(?:^[ \t]*#\[[^\n]*\][ \t]*\n)+)"
rf"^[ \t]*(?:(?:pub(?:\([^)]*\))?[ \t]+)?(?:async[ \t]+)?)"
rf"fn[ \t]+{re.escape(test_name)}[ \t]*(?:<[^>]*>[ \t]*)?\(",
re.MULTILINE,
)
return any(
re.search(
r"^[ \t]*#\[[ \t]*test[ \t]*\][ \t]*$",
match.group("attributes"),
re.MULTILINE,
)
for match in declaration.finditer(contents)
)
if path.suffix == ".py" and test_name.startswith("test_"):
declaration = re.compile(
rf"^[ \t]*(?:async[ \t]+)?def[ \t]+{re.escape(test_name)}[ \t]*\(",
re.MULTILINE,
)
return declaration.search(contents) is not None
return False
def _validate_evidence(root: Path, row_id: str, entries: list[str]) -> list[str]:
errors: list[str] = []
for entry in entries:
if entry.count("::") != 1:
errors.append(
f"{row_id}.evidence: '{entry}' must use repo-relative-file::exact_test_name"
)
continue
relative_path, test_name = entry.split("::")
if not _safe_relative_path(relative_path) or not TEST_NAME_PATTERN.fullmatch(test_name):
errors.append(f"{row_id}.evidence: malformed entry '{entry}'")
continue
evidence_path = root / relative_path
if not evidence_path.is_file():
errors.append(f"{row_id}.evidence: file '{relative_path}' does not exist")
continue
if evidence_path.suffix not in {".rs", ".py"}:
errors.append(
f"{row_id}.evidence: unsupported evidence file type "
f"'{evidence_path.suffix or '<none>'}' in '{relative_path}'"
)
continue
if not _declaration_exists(evidence_path, test_name):
errors.append(
f"{row_id}.evidence: test declaration '{test_name}' does not exist "
f"in '{relative_path}'"
)
return errors
def _validate_manifest(root: Path, ledger: dict[str, Any]) -> list[str]:
manifest_path = root / "Cargo.toml"
if not manifest_path.is_file():
return ["Cargo.toml: package, crate, and tch metadata cannot be validated"]
try:
with manifest_path.open("rb") as manifest_file:
manifest = tomllib.load(manifest_file)
except (OSError, tomllib.TOMLDecodeError) as error:
return [f"Cargo.toml: cannot read metadata: {error}"]
errors: list[str] = []
package = manifest.get("package", {})
package_name = package.get("name")
if package_name != ledger.get("package"):
errors.append(
f"package: ledger value {ledger.get('package')!r} does not match Cargo package {package_name!r}"
)
package_version = package.get("version")
if package_version == {"workspace": True}:
workspace = manifest.get("workspace")
workspace_package = workspace.get("package") if isinstance(workspace, dict) else None
package_version = (
workspace_package.get("version")
if isinstance(workspace_package, dict)
else None
)
if not isinstance(package_version, str):
errors.append("Cargo.toml: package version must be a string or valid workspace inheritance")
crate_name = manifest.get("lib", {}).get("name")
if crate_name != ledger.get("crate"):
errors.append(
f"crate: ledger value {ledger.get('crate')!r} does not match Cargo library {crate_name!r}"
)
dependency = manifest.get("dependencies", {}).get("tch")
if dependency == {"workspace": True}:
workspace = manifest.get("workspace")
workspace_dependencies = (
workspace.get("dependencies") if isinstance(workspace, dict) else None
)
workspace_dependency = (
workspace_dependencies.get("tch")
if isinstance(workspace_dependencies, dict)
else None
)
dependency_version = (
workspace_dependency.get("version")
if isinstance(workspace_dependency, dict)
else None
)
elif isinstance(dependency, str):
dependency_version = dependency
elif isinstance(dependency, dict) and "workspace" not in dependency:
dependency_version = dependency.get("version")
else:
dependency_version = None
if dependency_version != "=0.26.0":
errors.append(
"Cargo.toml: tch dependency requirement must be exactly '=0.26.0', "
f"found {dependency_version!r}"
)
elif dependency_version.removeprefix("=") != ledger.get("tch"):
errors.append(
f"tch: ledger value {ledger.get('tch')!r} does not match Cargo dependency "
f"{dependency_version.removeprefix('=')!r}"
)
return errors
def validate_ledger(root: Path, ledger: dict[str, Any]) -> list[str]:
if not isinstance(ledger, dict):
return ["ledger must be a TOML table"]
errors = _unknown_and_missing(ledger, TOP_LEVEL_FIELDS, "ledger")
for field, expected in EXPECTED_METADATA.items():
if field in ledger and ledger[field] != expected:
errors.append(f"{field}: expected {expected!r}, found {ledger[field]!r}")
rows = ledger.get("api")
if not isinstance(rows, list):
errors.append("api must be an array of tables")
rows = []
ids: list[str] = []
for index, row in enumerate(rows):
if not isinstance(row, dict):
errors.append(f"api[{index}] must be a table")
continue
raw_id = row.get("id")
row_id = raw_id if isinstance(raw_id, str) and raw_id else f"api[{index}]"
errors.extend(_unknown_and_missing(row, ROW_FIELDS, row_id))
if not isinstance(raw_id, str) or ID_PATTERN.fullmatch(raw_id) is None:
errors.append(f"{row_id}.id must be a stable lowercase dotted identifier")
else:
ids.append(raw_id)
status = row.get("status")
implementation = row.get("implementation")
if status not in STATUSES:
errors.append(f"{row_id}.status must be one of {sorted(STATUSES)}")
if implementation not in IMPLEMENTATIONS:
errors.append(
f"{row_id}.implementation must be one of {sorted(IMPLEMENTATIONS)}"
)
python_symbols, symbol_errors = _string_list(
row.get("python_symbols"), f"{row_id}.python_symbols", allow_empty=False
)
del python_symbols
errors.extend(symbol_errors)
rust_symbols, symbol_errors = _string_list(
row.get("rust_symbols"), f"{row_id}.rust_symbols", allow_empty=True
)
errors.extend(symbol_errors)
evidence, evidence_errors = _string_list(
row.get("evidence"), f"{row_id}.evidence", allow_empty=True
)
errors.extend(evidence_errors)
for field in ("scope", "notes"):
value = row.get(field)
if not isinstance(value, str) or not value.strip():
errors.append(f"{row_id}.{field} must be a nonempty string")
if not _safe_relative_path(row.get("source")):
errors.append(f"{row_id}.source must be a safe nonempty upstream-relative path")
if status == "supported" and not evidence:
errors.append(f"{row_id}.evidence must not be empty for supported rows")
if status not in NO_REQUIRED_RUST_SURFACE and not rust_symbols:
errors.append(f"{row_id}.rust_symbols must name the supported Rust surface")
if status in NO_REQUIRED_RUST_SURFACE and not rust_symbols and implementation != "none":
errors.append(
f"{row_id}.implementation must be 'none' when no Rust surface is named"
)
if status in NO_REQUIRED_RUST_SURFACE and rust_symbols and implementation == "none":
errors.append(
f"{row_id}.implementation must name how the listed Rust surface is implemented"
)
if status == "python_only" and rust_symbols:
errors.append(f"{row_id}.rust_symbols must be empty for status 'python_only'")
if status in {"supported", "partial"} and implementation == "none":
errors.append(f"{row_id}.implementation cannot be 'none' for status '{status}'")
errors.extend(_validate_evidence(root, row_id, evidence))
duplicate_ids = sorted({row_id for row_id in ids if ids.count(row_id) > 1})
for row_id in duplicate_ids:
errors.append(f"{row_id}.id is duplicate")
if ids != sorted(ids):
first_out_of_order = next(
current for previous, current in zip(ids, ids[1:]) if previous > current
)
errors.append(f"{first_out_of_order}.id is out of order; api IDs must be sorted")
errors.extend(_validate_manifest(root, ledger))
return errors
def _inline_code(value: str) -> str:
longest_run = max((len(run) for run in re.findall(r"`+", value)), default=0)
delimiter = "`" * (longest_run + 1)
padding = " " if value.startswith(("`", " ")) or value.endswith(("`", " ")) else ""
return f"{delimiter}{padding}{value}{padding}{delimiter}"
def _markdown_text(value: str) -> str:
value = value.replace("\r\n", "\n").replace("\r", "\n").replace("\\", "\\\\")
value = html.escape(value, quote=False)
value = re.sub(r"([`*_\[\]|])", r"\\\1", value)
return value.replace("\n", "<br>")
def _source_link(ledger: dict[str, Any], source: str) -> str:
commit = quote(ledger["pytorch_commit"], safe="")
source_url = quote(source, safe="/")
url = f"https://github.com/pytorch/pytorch/blob/{commit}/{source_url}"
return f"[{_inline_code(source)}]({url})"
def _evidence_link(entry: str, relative_root: str) -> str:
relative_path, _ = entry.split("::", 1)
return f"[{_inline_code(entry)}]({relative_root}/{quote(relative_path, safe='/')})"
def render_markdown(
ledger: dict[str, Any],
*,
title: str = "API coverage",
row_prefixes: tuple[str, ...] = (),
relative_root: str = "..",
inventory_counts: dict[str, int] | None = None,
) -> str:
rows = sorted(
(
row
for row in ledger.get("api", [])
if not row_prefixes or row.get("id", "").startswith(row_prefixes)
),
key=lambda row: row.get("id", ""),
)
lines = [
GENERATED_NOTICE,
f"# {title}",
"",
"This page is generated from "
f"[`compat/pytorch_api.toml`]({relative_root}/compat/pytorch_api.toml) against "
f"PyTorch {_inline_code(ledger['pytorch_reference'])} at commit "
f"{_inline_code(ledger['pytorch_commit'])}, through "
f"{_inline_code('tch')} {_inline_code(ledger['tch'])}.",
"Each entry is independently scoped. Supported applies only to its written scope; "
"row counts are not a compatibility score.",
"",
]
for status, heading in STATUS_SECTIONS:
lines.extend((f"## {heading}", ""))
section_rows = [row for row in rows if row["status"] == status]
if not section_rows:
lines.extend(("No entries.", ""))
continue
for row in section_rows:
python_symbols = ", ".join(
_inline_code(symbol) for symbol in row["python_symbols"]
)
rust_symbols = (
", ".join(_inline_code(symbol) for symbol in row["rust_symbols"])
if row["rust_symbols"]
else "—"
)
evidence = (
", ".join(
_evidence_link(entry, relative_root) for entry in row["evidence"]
)
if row["evidence"]
else "—"
)
lines.extend(
(
f"### {_inline_code(row['id'])}",
"",
f"- **PyTorch:** {python_symbols}",
f"- **RustTorch:** {rust_symbols}",
f"- **Implementation:** {IMPLEMENTATION_LABELS[row['implementation']]}",
f"- **Pinned inventory:** {(inventory_counts or {}).get(row['id'], 0)} identities "
f"([exact mapping]({relative_root}/compat/pytorch_inventory_map.toml)); disposition only, not a support claim.",
f"- **Scope:** {_markdown_text(row['scope'])}",
f"- **Pinned source:** {_source_link(ledger, row['source'])}",
f"- **Evidence:** {evidence}",
f"- **Notes:** {_markdown_text(row['notes'])}",
"",
)
)
return "\n".join(lines).rstrip() + "\n"
def load_inventory_counts(root: Path, ledger: dict[str, Any]) -> dict[str, int]:
spec = importlib.util.spec_from_file_location("pytorch_inventory", root / "scripts/sync-pytorch-inventory.py")
assert spec is not None and spec.loader is not None
module = importlib.util.module_from_spec(spec)
spec.loader.exec_module(module)
_, mapping = module.load_snapshot(root, ledger)
return dict(module.inventory_counts(mapping))
def generated_documents(root: Path, ledger: dict[str, Any], inventory_counts: dict[str, int] | None = None) -> dict[Path, str]:
documents = {
root / "docs" / "api-coverage.md": render_markdown(ledger, inventory_counts=inventory_counts),
root / "crates" / "rusttorch-core" / "COMPATIBILITY.md": render_markdown(
ledger,
title="rusttorch-core compatibility",
row_prefixes=("autograd.", "core."),
relative_root="../..",
inventory_counts=inventory_counts,
),
root / "crates" / "rusttorch-data" / "COMPATIBILITY.md": render_markdown(
ledger,
title="rusttorch-data compatibility",
row_prefixes=("data.",),
relative_root="../..",
inventory_counts=inventory_counts,
),
}
for domain, prefixes in {
"vision": ("vision",), "codec": ("codec", "video"),
"audio": ("audio",), "text": ("text",), "tabular": ("tabular",),
}.items():
documents[root / "crates" / f"rusttorch-{domain}" / "COMPATIBILITY.md"] = render_markdown(
ledger, title=f"rusttorch-{domain} compatibility", row_prefixes=prefixes,
relative_root="../..", inventory_counts=inventory_counts,
)
return documents
def _atomic_write(path: Path, contents: str) -> None:
temporary_path: Path | None = None
try:
with tempfile.NamedTemporaryFile(
mode="wb",
dir=path.parent,
prefix=f".{path.name}.",
suffix=".tmp",
delete=False,
) as temporary_file:
temporary_path = Path(temporary_file.name)
temporary_file.write(contents.encode("utf-8"))
temporary_file.flush()
os.fsync(temporary_file.fileno())
os.replace(temporary_path, path)
except BaseException:
if temporary_path is not None:
temporary_path.unlink(missing_ok=True)
raise
def _parser() -> argparse.ArgumentParser:
parser = argparse.ArgumentParser(description=__doc__)
mode = parser.add_mutually_exclusive_group(required=True)
mode.add_argument("--check", action="store_true", help="validate the ledger and generated page")
mode.add_argument("--write", action="store_true", help="write the generated page")
return parser
def main(argv: list[str] | None = None) -> int:
arguments = _parser().parse_args(argv)
root = Path(__file__).resolve().parents[1]
ledger_path = root / "compat" / "pytorch_api.toml"
try:
ledger = load_ledger(ledger_path)
except (OSError, tomllib.TOMLDecodeError) as error:
print(f"error: cannot load {ledger_path.relative_to(root)}: {error}", file=sys.stderr)
return 1
errors = validate_ledger(root, ledger)
if errors:
for error in errors:
print(f"error: {error}", file=sys.stderr)
return 1
try:
counts = load_inventory_counts(root, ledger)
except (OSError, ValueError, KeyError, TypeError) as error:
print(f"error: pinned inventory: {error}", file=sys.stderr)
return 1
documents = generated_documents(root, ledger, counts)
if arguments.write:
for path, expected in documents.items():
relative_path = path.relative_to(root)
try:
_atomic_write(path, expected)
except OSError as error:
print(f"error: cannot write {relative_path}: {error}", file=sys.stderr)
return 1
print(f"generated {relative_path}")
return 0
stale = []
for path, expected in documents.items():
try:
actual = path.read_bytes()
except OSError:
actual = b""
if actual != expected.encode("utf-8"):
stale.append(path.relative_to(root))
if stale:
for path in stale:
print(
f"error: {path} is stale; regenerate it with "
"`python3 scripts/check-compatibility.py --write`",
file=sys.stderr,
)
return 1
print("compatibility ledger and generated documentation are current")
return 0
if __name__ == "__main__":
raise SystemExit(main())