feat(cli, python): programmatic interface to cli with python bindings #2677

ss2165 · 2025-11-11T18:03:10Z

Closes #2671

Goals

Have hugr cli available in environment when installed via uv (uvx hugr --help)
Allow use of cli functionality from python package without spawning subprocess

Implications

Either ship binary with wheel or bind the function directly - chose the latter as it is more flexible and avoids a bunch of build faff
CLI uses argc + stdin for input and stdout for output (by default), we need a way to do this via binding i/o to avoid subprocess

Primary outcomes

Cli invocation bound via pyo3 to python "package script" with same name as binary, meeting goal 1
hugr-cli refactored to read inputs from a reader and write outputs to a writer when appropriate, satisfying goal 2. Uses an "override" pattern - when i/o is specified it overrides the corresponding cli-arg

Secondary outcomes

CLI main.rs contents moved to lib.rs, allowing use by library dependants
Make tracing a default feature for hugr-cli (not used by hugr-py)
cli module in python to wrap core sub-commands and parameters, with simply typed interfaces
Python test cli use replaced with bound function calls - meaning no need to build cli before running python tests
Model loading in python via conversion to json uses cli convert function rather than dedicated binding
Dedicated cargo profile for python wheel for smaller wheels (very open to critique on this)
Pydantic models to parse describe json output
Remove parallel pytest since it is now faster without it

Possible issues

Versioning: the cli version is pinned to the rust crates, the python package is not. Meaning uvx hugr --version will report a different value to uv --with hugr run python -c "import hugr; print(hugr.__version__)". Are we ok with this?

codecov · 2025-11-11T18:07:19Z

Codecov Report

❌ Patch coverage is 71.86544% with 92 lines in your changes missing coverage. Please review.
✅ Project coverage is 83.41%. Comparing base (5e354b9) to head (2c3aebf).
⚠️ Report is 2 commits behind head on main.

Files with missing lines	Patch %	Lines
hugr-cli/src/mermaid.rs	36.11%	20 Missing and 3 partials ⚠️
hugr-cli/src/describe.rs	75.86%	7 Missing and 14 partials ⚠️
hugr-cli/src/lib.rs	77.27%	20 Missing ⚠️
hugr-cli/src/hugr_io.rs	37.50%	14 Missing and 1 partial ⚠️
hugr-cli/src/convert.rs	57.14%	3 Missing and 3 partials ⚠️
hugr-cli/src/validate.rs	55.55%	4 Missing ⚠️
hugr-py/src/hugr/cli.py	95.45%	3 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #2677      +/-   ##
==========================================
- Coverage   83.46%   83.41%   -0.05%     
==========================================
  Files         262      263       +1     
  Lines       51297    51489     +192     
  Branches    46858    46984     +126     
==========================================
+ Hits        42813    42949     +136     
- Misses       6105     6156      +51     
- Partials     2379     2384       +5

Flag	Coverage Δ
python	`91.52% <95.58%> (+0.05%)`	⬆️
rust	`82.63% <65.63%> (-0.07%)`	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

cqc-alec

Looks good, just a few comments.

hugr-cli/src/lib.rs

hugr-py/src/hugr/cli.py

cqc-alec · 2025-11-12T13:06:34Z

hugr-py/src/hugr/cli.py

+        format: Target format ("json" or "model", default: auto-detect).
+        text: Output as text (default: auto-detect).
+        binary: Output as binary (default: auto-detect).


Not clear what "auto-detect" means for output format. (I think the default is to use the input format, i.e. do no conversion, if not specified?)

cqc-alec · 2025-11-12T13:07:57Z

hugr-py/src/hugr/cli.py

+        text: Output as text (default: auto-detect).
+        binary: Output as binary (default: auto-detect).
+        compress: Compress the output (default: False).
+        compression_level: Compression level 0-9 (default: 6).


Shouldn't this be 1--22? And where does 6 come from?

ah this was the last item on my todo list to fix sorry missed it (is a placeholder)

Co-authored-by: Alec Edgington <[email protected]>

ss2165 · 2025-11-11T18:03:57Z

hugr-cli/src/main.rs

-    }
-}
-
-fn run_external(args: Vec<OsString>) -> Result<()> {


moved unchanged to lib.rs

ss2165 · 2025-11-12T13:44:04Z

hugr-py/src/hugr/cli.py

+        text: Output as text (default: auto-detect).
+        binary: Output as binary (default: auto-detect).
+        compress: Compress the output (default: False).
+        compression_level: Compression level 0-9 (default: 6).


ah this was the last item on my todo list to fix sorry missed it (is a placeholder)

hugr-py/rust/lib.rs

aborgna-q · 2025-11-12T14:48:28Z

hugr-py/rust/lib.rs

+/// Directly invoke the HUGR CLI entrypoint.
+fn run_cli() {


Add that we're invoking the CLI passing std::env::args to the docs

aborgna-q · 2025-11-12T14:52:25Z

hugr-py/src/hugr/cli.py

It may be a bit confusing to call this module cli when including it in the python lib.

From a user standpoint, there's no connection between hugr.cli.describe or hugr.cli.mermaid and a command line interface.

Any suggestions?

I sort of agree, but not sure what else to call it. utils is too broad.

I personally like making it clear that it relies on the cli interface, it makes the idiosyncrasies of the interface easier to understand (e.g. why pass bytes?). The module docstring explains why it is this way.

I was imagining that we would add user level features in future that would wrap around this (e.g. Package.describe() -> PackageDesc) where there is then no reference to the cli.

Ok, let's go with cli for now then

forgot to push...

🤖 I have created a release *beep* *boop* --- ## [0.14.2](hugr-py-v0.14.1...hugr-py-v0.14.2) (2025-11-13) ### Features * **cli, python:** programmatic interface to cli with python bindings ([#2677](#2677)) ([0fd0332](0fd0332)) * ComposablePass protocol and ComposedPass for hugr-py (unstable) ([[#2636](https://github.com/CQCL/hugr/issues/2636)](https://github.com/CQCL/hugr/pull/2636)) ([45dc3fc](45dc3fc)) * return description output to python on error ([#2681](#2681)) ([f483146](f483146)) * track package descriptions when loading ([#2639](#2639)) ([349dd61](349dd61)) ### Documentation * Fix typo in docstring. ([#2656](#2656)) ([a1ce622](a1ce622)) --- This PR was generated with [Release Please](https://github.com/googleapis/release-please). See [documentation](https://github.com/googleapis/release-please#release-please). --------- Co-authored-by: Seyon Sivarajah <[email protected]>

ss2165 added 14 commits November 11, 2025 11:52

feat(cli): move main function to lib

4b85a52

feat(cli): bind cli through python

28b7afd

begin i/o for validate

e71a3cc

add convert

397dc70

add describe and mermaid

8ecd5aa

refactor: reduce match duplicatioN

90e2821

clean-up bindings

ddebc65

feat(py): cli module

29fec22

test: use cli binding for tests

2c02ea0

use cli to do to_json_envelope

64da67f

chore: avoid parallel python tests, now slower

2e4753c

docs: improve docstrings

cb89a10

simplify hugr_io

7a3f4b6

python custom release profile for smaller wheels

499875b

ss2165 requested a review from a team as a code owner November 11, 2025 18:03

ss2165 requested a review from cqc-alec November 11, 2025 18:03

ss2165 added 6 commits November 11, 2025 18:13

refactor(cli): make tracing a default feature

9bb5844

feat: return structured description

94b5a72

test: cleanup cli python tests

205d7ef

cleanup cli tests

7e273a8

better name for run_programmatic

c1aa0c2

no need to build cli for python tests

195070d

ss2165 force-pushed the ss/push-qmnzpxnuzzks branch from 169afd7 to 195070d Compare November 11, 2025 18:14

test: for uses_extension

763ade4

cqc-alec reviewed Nov 12, 2025

View reviewed changes

ss2165 and others added 2 commits November 12, 2025 13:46

Apply suggestions from code review

52cbd98

Co-authored-by: Alec Edgington <[email protected]>

cleanup parameters

2c3aebf

ss2165 commented Nov 12, 2025

View reviewed changes

ss2165 requested a review from cqc-alec November 12, 2025 14:52

aborgna-q reviewed Nov 12, 2025

View reviewed changes

cqc-alec approved these changes Nov 12, 2025

View reviewed changes

ss2165 added this pull request to the merge queue Nov 12, 2025

Merged via the queue into main with commit 0fd0332 Nov 12, 2025
29 of 30 checks passed

ss2165 deleted the ss/push-qmnzpxnuzzks branch November 12, 2025 16:32

This was referenced Nov 12, 2025

chore: release #2674

Draft

chore(main): release hugr-py 0.14.2 #2657

Merged

ss2165 added a commit that referenced this pull request Nov 12, 2025

chore: doc fixes from #2677

f2aa814

github-merge-queue bot pushed a commit that referenced this pull request Nov 12, 2025

chore: doc fixes from #2677 (#2678)

7dc0876

forgot to push...

feat(cli, python): programmatic interface to cli with python bindings #2677

feat(cli, python): programmatic interface to cli with python bindings #2677

Uh oh!

Conversation

ss2165 commented Nov 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Goals

Implications

Primary outcomes

Secondary outcomes

Possible issues

Uh oh!

codecov bot commented Nov 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

cqc-alec left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

aborgna-q Nov 12, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

ss2165 commented Nov 11, 2025 •

edited

Loading

codecov bot commented Nov 11, 2025 •

edited

Loading

aborgna-q Nov 12, 2025 •

edited

Loading