feat: return description output to python on error

Author: ss2165

hugr-cli/src/lib.rs

@@ -247,13 +247,35 @@ impl CliArgs {
     ///
     /// The `gen-extensions` and `external` commands don't support byte I/O
     /// and should use the normal `run_cli()` method instead.
-    pub fn run_with_io(self, input: impl std::io::Read) -> Result<Vec<u8>> {
+    pub fn run_with_io(self, input: impl std::io::Read) -> Result<Vec<u8>, RunWithIoError> {
         let mut output = Vec::new();
-        self.command.run_with_io(Some(input), Some(&mut output))?;
-        Ok(output)
+        let is_describe = matches!(self.command, CliCommand::Describe(_));
+        let res = self.command.run_with_io(Some(input), Some(&mut output));
+        match (res, is_describe) {
+            (Ok(()), _) => Ok(output),
+            (Err(e), true) => Err(RunWithIoError::Describe { source: e, output }),
+            (Err(e), false) => Err(RunWithIoError::Other(e)),
+        }
     }
 }
 
+#[derive(Debug, Error)]
+#[non_exhaustive]
+#[error("Error running CLI command with IO.")]
+/// Error type for `run_with_io` method.
+pub enum RunWithIoError {
+    /// Error describing HUGR package.
+    Describe {
+        #[source]
+        /// Error returned from describe command.
+        source: anyhow::Error,
+        /// Describe command output.
+        output: Vec<u8>,
+    },
+    /// Non-describe command error.
+    Other(anyhow::Error),
+}
+
 fn run_external(args: Vec<OsString>) -> Result<()> {
     // External subcommand support: invoke `hugr-<subcommand>`
     if args.is_empty() {

hugr-py/rust/lib.rs

@@ -1,8 +1,41 @@
 //! Supporting Rust library for the hugr Python bindings.
 
-use hugr_cli::CliArgs;
+use hugr_cli::{CliArgs, RunWithIoError};
 use hugr_model::v0::ast;
-use pyo3::{exceptions::PyValueError, prelude::*};
+use pyo3::{create_exception, exceptions::PyException, exceptions::PyValueError, prelude::*};
+
+// Define custom exceptions
+create_exception!(
+    _hugr,
+    HugrCliError,
+    PyException,
+    "Base exception for HUGR CLI errors."
+);
+create_exception!(
+    _hugr,
+    HugrCliDescribeError,
+    HugrCliError,
+    "Exception for HUGR CLI describe command errors with partial output."
+);
+
+/// Helper to convert RunWithIoError to Python exception
+fn cli_error_to_py(err: RunWithIoError) -> PyErr {
+    match err {
+        RunWithIoError::Describe { source, output } => {
+            // Convert output bytes to string, falling back to empty string if invalid UTF-8
+            let output_str = String::from_utf8(output).unwrap_or_else(|e| {
+                format!("<Invalid UTF-8 output: {} bytes>", e.as_bytes().len())
+            });
+
+            HugrCliDescribeError::new_err((format!("{:?}", source), output_str))
+        }
+        RunWithIoError::Other(e) => HugrCliError::new_err(format!("{:?}", e)),
+        _ => {
+            // Catch-all for any future error variants (non_exhaustive enum)
+            HugrCliError::new_err(format!("{:?}", err))
+        }
+    }
+}
 
 macro_rules! syntax_to_and_from_string {
     ($name:ident, $ty:ty) => {
@@ -93,13 +126,18 @@ fn cli_with_io(mut args: Vec<String>, input_bytes: Option<&[u8]>) -> PyResult<Ve
     args.insert(0, String::new());
     let cli_args = CliArgs::new_from_args(args);
     let input = input_bytes.unwrap_or(&[]);
-    cli_args
-        .run_with_io(input)
-        .map_err(|e| PyValueError::new_err(format!("{:?}", e)))
+    cli_args.run_with_io(input).map_err(cli_error_to_py)
 }
 
 #[pymodule]
 fn _hugr(m: &Bound<'_, PyModule>) -> PyResult<()> {
+    // Register custom exceptions
+    m.add("HugrCliError", m.py().get_type::<HugrCliError>())?;
+    m.add(
+        "HugrCliDescribeError",
+        m.py().get_type::<HugrCliDescribeError>(),
+    )?;
+
     m.add_function(wrap_pyfunction!(term_to_string, m)?)?;
     m.add_function(wrap_pyfunction!(string_to_term, m)?)?;
     m.add_function(wrap_pyfunction!(node_to_string, m)?)?;

hugr-py/src/hugr/cli.py

@@ -7,7 +7,7 @@
 
 from pydantic import BaseModel
 
-from hugr._hugr import cli_with_io
+from hugr._hugr import HugrCliDescribeError, HugrCliError, cli_with_io
 
 __all__ = [
     "cli_with_io",
@@ -20,6 +20,8 @@
     "ModuleDesc",
     "ExtensionDesc",
     "EntrypointDesc",
+    "HugrCliError",
+    "HugrCliDescribeError",
 ]
 
 
@@ -50,7 +52,7 @@ def validate(
         extensions: Paths to additional serialised extensions needed to load the HUGR.
 
     Raises:
-        ValueError: On validation failure.
+        HugrCliError: On validation failure or other CLI errors.
     """
     args = _add_input_args(["validate"], no_std, extensions)
     cli_with_io(args, hugr_bytes)
@@ -175,6 +177,10 @@ def describe_str(
 
     Returns:
         Text description of the package.
+
+    Raises:
+        HugrCliDescribeError: On error during package description. The exception
+            contains partial output if available.
     """
     args = ["describe"]
     if _json:
@@ -221,17 +227,24 @@ def describe(
 
     Returns:
         Structured package description as a PackageDesc object.
+
+    Raises:
+        HugrCliDescribeError: On error during package description. The exception
+            contains partial output if available.
     """
-    output = describe_str(
-        hugr_bytes,
-        _json=True,
-        packaged_extensions=packaged_extensions,
-        no_resolved_extensions=no_resolved_extensions,
-        public_symbols=public_symbols,
-        generator_claimed_extensions=generator_claimed_extensions,
-        no_std=no_std,
-        extensions=extensions,
-    )
+    try:
+        output = describe_str(
+            hugr_bytes,
+            _json=True,
+            packaged_extensions=packaged_extensions,
+            no_resolved_extensions=no_resolved_extensions,
+            public_symbols=public_symbols,
+            generator_claimed_extensions=generator_claimed_extensions,
+            no_std=no_std,
+            extensions=extensions,
+        )
+    except HugrCliDescribeError as e:
+        output = e.args[1]
     return PackageDesc.model_validate_json(output)
 
 
@@ -265,6 +278,9 @@ def convert(
 
     Returns:
         Converted package as bytes.
+
+    Raises:
+        HugrCliError: On conversion failure or other CLI errors.
     """
     args = ["convert"]
     if format is not None:
@@ -300,6 +316,9 @@ def mermaid(
 
     Returns:
         Mermaid diagram output as a string.
+
+    Raises:
+        HugrCliError: On mermaid generation failure or other CLI errors.
     """
     args = ["mermaid"]
     if validate:

hugr-py/tests/test_cli.py

@@ -4,8 +4,8 @@
 
 import pytest
 
-from hugr import cli
-from hugr.build import Module
+from hugr import cli, tys
+from hugr.build import Dfg, Module
 from hugr.ext import Extension
 from hugr.package import Package
 
@@ -38,7 +38,7 @@ def test_validate_with_bytes_invalid():
 
     invalid_bytes = b"not a valid hugr package"
 
-    with pytest.raises(ValueError, match="Bad magic number"):
+    with pytest.raises(cli.HugrCliError, match="Bad magic number"):
         cli.cli_with_io(["validate"], invalid_bytes)
 
 
@@ -139,3 +139,31 @@ def test_describe_json_with_packaged_extensions(hugr_with_extension_bytes: bytes
 
     assert desc.uses_extension("ext")
     assert not desc.uses_extension("nonexistent_extension")
+
+
+@pytest.fixture
+def hugr_using_ext() -> bytes:
+    """A simple HUGR package that uses an extension, but doesn't package it."""
+    ext = Extension.from_json(EXAMPLE)
+    u_t = tys.USize()
+    op = ext.get_op("New").instantiate(
+        [u_t.type_arg()], concrete_signature=tys.FunctionType([u_t], [])
+    )
+    h = Dfg(u_t)
+    a = h.inputs()[0]
+    h.add_op(op, a)
+    h.set_outputs()
+
+    package = Package([h.hugr], [])
+
+    return package.to_bytes()
+
+
+def test_failed_describe(hugr_using_ext):
+    """Json description still succeeds, with error field populated"""
+    desc = cli.describe(hugr_using_ext)
+    mod = desc.modules[0]
+    assert mod is not None
+    assert mod.num_nodes == 8  # computed before error
+    assert isinstance(desc.error, str)
+    assert "requires extension ext" in desc.error