Hyper for Python

hypergraph-viz provides Rust-backed Hypergraph Interchange Format (HIF) validation and interchange, plus a launcher for Hyper's native 3D viewer. Use it to exchange scientific datasets while retaining metadata and explicit group identities. The package includes generated extension type stubs, typed Python wrappers, and py.typed.

Installation

python -m pip install hypergraph-viz

Requires standard CPython 3.10 or newer. Platform wheels cover Linux x86_64, macOS arm64/x86_64, and Windows x86_64; installing a compatible wheel requires no Rust compiler. Building from source requires Rust 1.89 or newer and maturin. The Python extension has no Bevy dependency.

Exchange datasets

import hyper_viz

document = hyper_viz.HifDocument.load("dataset.hif.json")
document.save("roundtrip.hif.json")
print(document.to_json())

# Explicitly check compatibility and convert to Hyper's native JSON.
native_json = document.to_hypergraph_json()

HifDocument.from_json(raw) accepts HIF JSON; from_hypergraph_json(raw) accepts native Hyper JSON. Validation uses a pinned schema bundled with the package and never fetches resources at runtime.

Keep the original document for scientific export. It preserves JSON values, record order, optional field presence, integer/string IDs, isolated nodes, empty edges, metadata, and incidence properties. Whitespace and object-key order are not preserved.

Launch the native viewer

Install Hyper's viewer separately from the Hyper repository. From its checkout:

cargo install --path . --locked

Then launch it from Python:

viewer = hyper_viz.show(document, projection="bipartite")
exit_code = viewer.wait()
# Or viewer.close() to terminate and clean up.

Pass executable="/path/to/hyper" to select a binary explicitly; otherwise the launcher finds hyper on PATH. It launches asynchronously without a shell, retains an owned temporary snapshot, and cleans up after exit. It does not download a viewer.

Compatibility and errors

Full-document interchange supports more semantics than viewer conversion. The viewer supports undirected memberships. Directed and simplicial semantics, incidence direction/weights/attributes, and duplicate declarations or incidence pairs produce HifCompatibilityError. Node/edge weights round to finite f32 for viewing; original values remain in the document. Arbitrary attributes are retained but not exposed by the stock viewer inspector.

Malformed HIF raises HifValidationError. Both exceptions carry location and reason; file failures raise OSError. Direct scientific object adapters, notebook embedding, headless layout bindings, and live Python updates are deferred.

See the integration guide and XGI example. Hyper is licensed under MIT OR Apache-2.0; the bundled HIF schema is MIT-licensed.