From b0f437285c7f11a55ec7de5231378293bdddbd7e Mon Sep 17 00:00:00 2001 From: Bregy Malpartida Date: Sun, 4 Oct 2026 18:50:37 -0500 Subject: [PATCH 1/3] Document uv project setup and desktop viewer quick start --- README.md | 39 ++++++++++++++++++++++++------- crates/hyper-viz-python/README.md | 22 +++++++++++++++-- docs/DESKTOP_PACKAGE.md | 15 +++++++++++- 3 files changed, 65 insertions(+), 11 deletions(-) diff --git a/README.md b/README.md index 6bb1900..2207154 100644 --- a/README.md +++ b/README.md @@ -31,23 +31,43 @@ legacy exports. The model is domain-agnostic: vertices, hyperedges, and membersh ## Python and scientific interoperability -Install the **`hypergraph-viz`** Python distribution with **CPython 3.10+**: +Start with [uv](https://docs.astral.sh/uv/getting-started/installation/) to manage +Python and the project environment: ```bash -python -m pip install hypergraph-viz +uv init --python 3.12 hyper-example +cd hyper-example +uv add "hypergraph-viz[viewer]" +uv run hyper ``` -The import name is `hyper_viz`. Wheels cover Linux x86_64, macOS arm64/x86_64, -and Windows x86_64; a compatible wheel requires no Rust compiler. Install the native desktop viewer through the optional extra: +This opens the built-in coauthorship demo. To view your own HIF dataset: + +```bash +uv run hyper dataset.hif.json --projection bipartite +``` + +`uv add` records dependencies in `pyproject.toml`, creates `.venv`, and locks +versions in `uv.lock`; `uv run` uses that environment without activation. +uv can download Python 3.12 if needed, avoiding older system or Xcode Python. +See the [uv project guide](https://docs.astral.sh/uv/guides/projects/). +For interchange alone, use `uv add hypergraph-viz` without the viewer extra. + +The distribution is **`hypergraph-viz`**; the import name is **`hyper_viz`**. +Requires **CPython 3.10+**. Wheels cover Linux x86_64, macOS arm64/x86_64, +and Windows x86_64; a compatible wheel requires no Rust compiler. +The viewer needs a desktop session and graphics driver. Linux desktop wheels +require glibc 2.28+; macOS targets 11.0+. + +If you prefer pip, use a virtual environment with Python 3.10+: ```bash python -m pip install --upgrade "hypergraph-viz[viewer]" ``` -Use `--upgrade` when the core package is already installed so pip selects the -release that provides the viewer extra. The viewer needs a desktop session and -graphics driver. Linux desktop wheels -require glibc 2.28+; macOS targets 11.0+. Rust is needed only for source builds. +Use `python -m pip install hypergraph-viz` for interchange alone. Upgrading pip +does not upgrade Python; check `python --version` if no matching distribution is found. +Rust is needed only for source builds. For a Python development build from this checkout with **Rust 1.89+**: ```bash @@ -71,6 +91,9 @@ viewer = hyper_viz.show(document, projection="bipartite") exit_code = viewer.wait() # or viewer.close() to terminate ``` +Save the Python example as `explore.py` alongside `dataset.hif.json`, then run +`uv run explore.py` in your project. + Pass `executable="/path/to/hyper"` to select a viewer explicitly. Otherwise the launcher finds the matching companion package, then `hyper` on PATH. The launcher validates compatibility, starts the process asynchronously without a shell, and diff --git a/crates/hyper-viz-python/README.md b/crates/hyper-viz-python/README.md index fab45ad..0848e4f 100644 --- a/crates/hyper-viz-python/README.md +++ b/crates/hyper-viz-python/README.md @@ -7,10 +7,21 @@ The package includes generated extension type stubs, typed Python wrappers, and ## Installation +With [uv](https://docs.astral.sh/uv/getting-started/installation/), create a project +with a supported Python version and add the package: + ```sh -python -m pip install hypergraph-viz +uv init --python 3.12 hyper-example +cd hyper-example +uv add hypergraph-viz ``` +uv manages `.venv` and `uv.lock`, and can download Python 3.12 if needed. +Save your Python code as `explore.py` and run it with `uv run explore.py`. +In an existing uv project, run only `uv add hypergraph-viz`. +Alternatively, use `python -m pip install hypergraph-viz` in a Python 3.10+ +virtual environment. Upgrading pip does not upgrade Python. + 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. @@ -42,10 +53,17 @@ not preserved. Install the matching prebuilt desktop viewer with the optional extra: +From your uv project: + ```sh -python -m pip install --upgrade "hypergraph-viz[viewer]" +uv add "hypergraph-viz[viewer]" +uv run hyper ``` +`uv run hyper` opens the built-in demo; use +`uv run hyper dataset.hif.json --projection bipartite` for your own dataset. +For pip, use `python -m pip install --upgrade "hypergraph-viz[viewer]"`. + Wheels cover Linux x86_64, macOS arm64/x86_64, and Windows x86_64. No Rust compiler or repository checkout is needed on these platforms. A desktop session and graphics driver are required. Linux viewer wheels require glibc 2.28+; diff --git a/docs/DESKTOP_PACKAGE.md b/docs/DESKTOP_PACKAGE.md index 15bad5b..0767f0c 100644 --- a/docs/DESKTOP_PACKAGE.md +++ b/docs/DESKTOP_PACKAGE.md @@ -3,10 +3,23 @@ Prebuilt native viewer for [hypergraph-viz](https://pypi.org/project/hypergraph-viz/). Install the Python API and matching viewer together: +With [uv](https://docs.astral.sh/uv/getting-started/installation/): + ```sh -python -m pip install --upgrade "hypergraph-viz[viewer]" +uv init --python 3.12 hyper-example +cd hyper-example +uv add "hypergraph-viz[viewer]" +uv run hyper ``` +This opens the built-in demo. In an existing uv project, start with `uv add`. +Use `uv run hyper dataset.hif.json` to open your own dataset, or save the Python +example below as `explore.py` and run `uv run explore.py`. No environment +activation is needed. uv can download a compatible Python when necessary. + +For pip, use `python -m pip install --upgrade "hypergraph-viz[viewer]"` in a +Python 3.10+ virtual environment. + ```python import hyper_viz From f6b40d6c936abf261fe8249c1542369a6f771632 Mon Sep 17 00:00:00 2001 From: Bregy Malpartida Date: Sun, 4 Oct 2026 19:10:52 -0500 Subject: [PATCH 2/3] Document uvx launch using the viewer distribution --- README.md | 13 +++++++++++++ crates/hyper-viz-python/README.md | 13 +++++++++++++ docs/DESKTOP_PACKAGE.md | 13 +++++++++++++ 3 files changed, 39 insertions(+) diff --git a/README.md b/README.md index 2207154..834f44a 100644 --- a/README.md +++ b/README.md @@ -47,6 +47,19 @@ This opens the built-in coauthorship demo. To view your own HIF dataset: uv run hyper dataset.hif.json --projection bipartite ``` +To launch only the desktop viewer without creating a project: + +```sh +uvx --python 3.12 --from hypergraph-viz-viewer hyper +# Open your dataset: +uvx --python 3.12 --from hypergraph-viz-viewer hyper dataset.hif.json +``` + +`--from` selects the distribution that supplies the `hyper` executable. +`hypergraph-viz` supplies the Python API and has no executable of its own; +use `uv add "hypergraph-viz[viewer]"` for Python integration in a project. +See [uv's tool guide](https://docs.astral.sh/uv/guides/tools/). + `uv add` records dependencies in `pyproject.toml`, creates `.venv`, and locks versions in `uv.lock`; `uv run` uses that environment without activation. uv can download Python 3.12 if needed, avoiding older system or Xcode Python. diff --git a/crates/hyper-viz-python/README.md b/crates/hyper-viz-python/README.md index 0848e4f..673a35d 100644 --- a/crates/hyper-viz-python/README.md +++ b/crates/hyper-viz-python/README.md @@ -64,6 +64,19 @@ uv run hyper `uv run hyper dataset.hif.json --projection bipartite` for your own dataset. For pip, use `python -m pip install --upgrade "hypergraph-viz[viewer]"`. +To launch only the desktop viewer without creating a project: + +```sh +uvx --python 3.12 --from hypergraph-viz-viewer hyper +# Open your dataset: +uvx --python 3.12 --from hypergraph-viz-viewer hyper dataset.hif.json +``` + +`--from` selects the distribution that supplies the `hyper` executable. +`hypergraph-viz` supplies the Python API and has no executable of its own; +use `uv add "hypergraph-viz[viewer]"` for Python integration in a project. +See [uv's tool guide](https://docs.astral.sh/uv/guides/tools/). + Wheels cover Linux x86_64, macOS arm64/x86_64, and Windows x86_64. No Rust compiler or repository checkout is needed on these platforms. A desktop session and graphics driver are required. Linux viewer wheels require glibc 2.28+; diff --git a/docs/DESKTOP_PACKAGE.md b/docs/DESKTOP_PACKAGE.md index 0767f0c..ad6fdd1 100644 --- a/docs/DESKTOP_PACKAGE.md +++ b/docs/DESKTOP_PACKAGE.md @@ -17,6 +17,19 @@ Use `uv run hyper dataset.hif.json` to open your own dataset, or save the Python example below as `explore.py` and run `uv run explore.py`. No environment activation is needed. uv can download a compatible Python when necessary. +To launch only the desktop viewer without creating a project: + +```sh +uvx --python 3.12 --from hypergraph-viz-viewer hyper +# Open your dataset: +uvx --python 3.12 --from hypergraph-viz-viewer hyper dataset.hif.json +``` + +`--from` selects the distribution that supplies the `hyper` executable. +`hypergraph-viz` supplies the Python API and has no executable of its own; +use `uv add "hypergraph-viz[viewer]"` for Python integration in a project. +See [uv's tool guide](https://docs.astral.sh/uv/guides/tools/). + For pip, use `python -m pip install --upgrade "hypergraph-viz[viewer]"` in a Python 3.10+ virtual environment. From faab136b76e53e5eea20fb8ee93b4110eb3b673a Mon Sep 17 00:00:00 2001 From: Bregy Malpartida Date: Sun, 4 Oct 2026 19:30:12 -0500 Subject: [PATCH 3/3] Clarify standalone and Python README quick starts --- README.md | 130 ++++++++++++++++++++---------- crates/hyper-viz-python/README.md | 10 ++- docs/DESKTOP_PACKAGE.md | 37 ++++----- 3 files changed, 111 insertions(+), 66 deletions(-) diff --git a/README.md b/README.md index 834f44a..d3be2ac 100644 --- a/README.md +++ b/README.md @@ -29,59 +29,111 @@ the workload and rendering limits. Inputs include scientific **HIF**, native **`hypergraph.v1`** JSON, and supported legacy exports. The model is domain-agnostic: vertices, hyperedges, and memberships. -## Python and scientific interoperability +## Quick start: desktop viewer -Start with [uv](https://docs.astral.sh/uv/getting-started/installation/) to manage -Python and the project environment: +Install [uv](https://docs.astral.sh/uv/getting-started/installation/), then open +the built-in coauthorship demo with one command: + +```bash +uvx --python 3.12 --from hypergraph-viz-viewer hyper +``` + +To open your own HIF or native Hyper JSON file: + +```bash +uvx --python 3.12 --from hypergraph-viz-viewer hyper dataset.hif.json --projection bipartite +``` + +No project, repository checkout, or Rust compiler is needed. `--from` selects +**`hypergraph-viz-viewer`**, the package containing the **`hyper`** executable. +See [uv's tool guide](https://docs.astral.sh/uv/guides/tools/). + +Desktop wheels support Linux x86_64 (glibc 2.28+), macOS arm64/x86_64 (11.0+), +and Windows x86_64. A desktop session and working graphics driver are required. +The viewer opens on the machine running the command; it does not embed in a notebook. + +## Use Hyper from Python + +Create a project with Python 3.12 and install the API plus matching desktop viewer: ```bash uv init --python 3.12 hyper-example cd hyper-example uv add "hypergraph-viz[viewer]" -uv run hyper ``` -This opens the built-in coauthorship demo. To view your own HIF dataset: +In an existing uv project using Python 3.10+, run just the `uv add` command. +uv manages `.venv` and `uv.lock` and can download Python 3.12 if needed. +`uv run` uses the project environment without activation. +See the [uv project guide](https://docs.astral.sh/uv/guides/projects/). -```bash -uv run hyper dataset.hif.json --projection bipartite +Save this complete example as `explore.py`: + +```python +import json +import hyper_viz + +document = hyper_viz.HifDocument.from_json(json.dumps({ + "network-type": "undirected", + "nodes": [{"node": "alice"}, {"node": "bob"}, {"node": "carol"}], + "edges": [{"edge": "team"}], + "incidences": [ + {"node": "alice", "edge": "team"}, + {"node": "bob", "edge": "team"}, + {"node": "carol", "edge": "team"}, + ], +})) +document.save("team.hif.json") + +viewer = hyper_viz.show(document, projection="bipartite") +exit_code = viewer.wait() # Or viewer.close() to terminate and clean up. ``` -To launch only the desktop viewer without creating a project: +Run it: -```sh -uvx --python 3.12 --from hypergraph-viz-viewer hyper -# Open your dataset: -uvx --python 3.12 --from hypergraph-viz-viewer hyper dataset.hif.json +```bash +uv run explore.py ``` -`--from` selects the distribution that supplies the `hyper` executable. -`hypergraph-viz` supplies the Python API and has no executable of its own; -use `uv add "hypergraph-viz[viewer]"` for Python integration in a project. -See [uv's tool guide](https://docs.astral.sh/uv/guides/tools/). +For an existing dataset, replace the constructor with +`document = hyper_viz.HifDocument.load("dataset.hif.json")`. +You can also open the exported example directly with `uv run hyper team.hif.json`. -`uv add` records dependencies in `pyproject.toml`, creates `.venv`, and locks -versions in `uv.lock`; `uv run` uses that environment without activation. -uv can download Python 3.12 if needed, avoiding older system or Xcode Python. -See the [uv project guide](https://docs.astral.sh/uv/guides/projects/). -For interchange alone, use `uv add hypergraph-viz` without the viewer extra. +| What you need | Package / command | +|---|---| +| Standalone desktop viewer | `uvx --python 3.12 --from hypergraph-viz-viewer hyper` | +| Python API and desktop viewer | `uv add "hypergraph-viz[viewer]"` | +| HIF validation and interchange only | `uv add hypergraph-viz` | +| Python import | `import hyper_viz` | + +The API requires CPython 3.10+. `hypergraph-viz` has no executable of its own, +so `uvx hypergraph-viz` cannot launch the viewer. For interchange alone, omit +`show()` from your script; the core package has no Bevy dependency. -The distribution is **`hypergraph-viz`**; the import name is **`hyper_viz`**. -Requires **CPython 3.10+**. Wheels cover Linux x86_64, macOS arm64/x86_64, -and Windows x86_64; a compatible wheel requires no Rust compiler. -The viewer needs a desktop session and graphics driver. Linux desktop wheels -require glibc 2.28+; macOS targets 11.0+. +
+Install with pip instead -If you prefer pip, use a virtual environment with Python 3.10+: +Use a Python 3.10+ virtual environment. For example, with Python 3.12 installed: ```bash +python3.12 -m venv .venv +source .venv/bin/activate python -m pip install --upgrade "hypergraph-viz[viewer]" +python explore.py ``` -Use `python -m pip install hypergraph-viz` for interchange alone. Upgrading pip -does not upgrade Python; check `python --version` if no matching distribution is found. -Rust is needed only for source builds. -For a Python development build from this checkout with **Rust 1.89+**: +On Windows, create the environment with `py -3.12 -m venv .venv` and activate +it in PowerShell with `.venv\Scripts\Activate.ps1`. +For interchange alone, use `python -m pip install hypergraph-viz`. +If pip reports no matching distribution, check `python --version`: upgrading +pip does not upgrade Python, and Xcode's Python 3.9 is too old. + +
+ +
+Build the Python extension from this checkout + +Source builds require Rust 1.89+ and CPython 3.10+: ```bash python -m venv .venv @@ -92,20 +144,10 @@ maturin develop --locked cd ../.. ``` -```python -import hyper_viz - -document = hyper_viz.HifDocument.load("dataset.hif.json") -document.save("roundtrip.hif.json") -print(document.to_json()) - -# Install hypergraph-viz[viewer] first. -viewer = hyper_viz.show(document, projection="bipartite") -exit_code = viewer.wait() # or viewer.close() to terminate -``` +This builds the core extension. Install the viewer extra separately if you want +prebuilt desktop launching, or build the native viewer with Cargo. -Save the Python example as `explore.py` alongside `dataset.hif.json`, then run -`uv run explore.py` in your project. +
Pass `executable="/path/to/hyper"` to select a viewer explicitly. Otherwise the launcher finds the matching companion package, then `hyper` on PATH. The launcher diff --git a/crates/hyper-viz-python/README.md b/crates/hyper-viz-python/README.md index 673a35d..1ca2292 100644 --- a/crates/hyper-viz-python/README.md +++ b/crates/hyper-viz-python/README.md @@ -51,9 +51,7 @@ not preserved. ## Launch the native viewer -Install the matching prebuilt desktop viewer with the optional extra: - -From your uv project: +From your uv project, install the matching prebuilt desktop viewer: ```sh uv add "hypergraph-viz[viewer]" @@ -84,9 +82,13 @@ macOS wheels target 11.0+. Notebook kernels on remote machines cannot open a window on your laptop; see the [notebook prototype roadmap](https://github.com/atomicstrata/hyper/blob/python-v0.1.2/docs/NOTEBOOK_ROADMAP.md). -Then launch it from Python: +Save the following as `explore.py` alongside `dataset.hif.json`, then run +`uv run explore.py`: ```python +import hyper_viz + +document = hyper_viz.HifDocument.load("dataset.hif.json") viewer = hyper_viz.show(document, projection="bipartite") exit_code = viewer.wait() # Or viewer.close() to terminate and clean up. diff --git a/docs/DESKTOP_PACKAGE.md b/docs/DESKTOP_PACKAGE.md index ad6fdd1..941543d 100644 --- a/docs/DESKTOP_PACKAGE.md +++ b/docs/DESKTOP_PACKAGE.md @@ -1,35 +1,36 @@ # Hyper desktop viewer Prebuilt native viewer for [hypergraph-viz](https://pypi.org/project/hypergraph-viz/). -Install the Python API and matching viewer together: - -With [uv](https://docs.astral.sh/uv/getting-started/installation/): +Launch the built-in demo with [uv](https://docs.astral.sh/uv/getting-started/installation/): ```sh -uv init --python 3.12 hyper-example -cd hyper-example -uv add "hypergraph-viz[viewer]" -uv run hyper +uvx --python 3.12 --from hypergraph-viz-viewer hyper ``` -This opens the built-in demo. In an existing uv project, start with `uv add`. -Use `uv run hyper dataset.hif.json` to open your own dataset, or save the Python -example below as `explore.py` and run `uv run explore.py`. No environment -activation is needed. uv can download a compatible Python when necessary. - -To launch only the desktop viewer without creating a project: +Open your own dataset: ```sh -uvx --python 3.12 --from hypergraph-viz-viewer hyper -# Open your dataset: uvx --python 3.12 --from hypergraph-viz-viewer hyper dataset.hif.json ``` -`--from` selects the distribution that supplies the `hyper` executable. -`hypergraph-viz` supplies the Python API and has no executable of its own; -use `uv add "hypergraph-viz[viewer]"` for Python integration in a project. +`--from` selects this package, which supplies the `hyper` executable. See [uv's tool guide](https://docs.astral.sh/uv/guides/tools/). +For Python integration, install the API and matching viewer in a project: + +```sh +uv init --python 3.12 hyper-example +cd hyper-example +uv add "hypergraph-viz[viewer]" +``` + +In an existing uv project using Python 3.10+, run only `uv add`. +Save the Python example below as `explore.py` alongside `dataset.hif.json`, +then run `uv run explore.py`. No environment activation is needed. +uv can download Python 3.12 when necessary. +`hypergraph-viz` provides the Python API and has no executable of its own; +`uvx hypergraph-viz` cannot launch the viewer. + For pip, use `python -m pip install --upgrade "hypergraph-viz[viewer]"` in a Python 3.10+ virtual environment.