raise PintExceptionGroup containers instead (#329)

* change the error formatting to return a exception group

* rename the exception group

* more renaming, and reset the group traceback

* expect the group in conversion tests

* make the group a subclass of `ValueError` for backwards compat

* add `cytoolz` to the test deps

* expect the exception group in `test_convert_units`

* adapt the indexer conversion tests

* also expect the exception group in the accessor code

* ignore test files in coverage

* install the optional deps as a separate feature

* bump the lockfile

* document the exception group

* changelog

* docstring for the exception

Author: keewis

docs/api.rst

@@ -72,6 +72,13 @@ Wrapping quantity-unaware functions
 
    pint_xarray.expects
 
+Exceptions
+----------
+.. autosummary::
+   :toctree: generated/
+
+   pint_xarray.errors.PintExceptionGroup
+
 Testing
 -------
 

docs/whats-new.rst

@@ -24,6 +24,8 @@ What's new
   By `Justus Magin <https://github.com/keewis>`_.
 - Add units to the inline ``repr`` and define a custom ``repr`` (:issue:`308`, :pull:`325`)
   By `Justus Magin <https://github.com/keewis>`_.
+- Collect multiple errors into a specific exception group (:pull:`329`)
+  By `Justus Magin <https://github.com/keewis>`_.
 
 0.5.1 (10 Aug 2025)
 -------------------

pint_xarray/accessors.py

@@ -8,7 +8,7 @@
 
 from pint_xarray import conversion
 from pint_xarray.conversion import no_unit_values
-from pint_xarray.errors import format_error_message
+from pint_xarray.errors import create_exception_group
 
 _default = object()
 
@@ -355,7 +355,7 @@ def quantify(self, units=_default, unit_registry=None, **unit_kwargs):
                     invalid_units[name] = (reported_unit, type, e)
 
         if invalid_units:
-            raise ValueError(format_error_message(invalid_units, "parse"))
+            raise create_exception_group(invalid_units, "parse")
 
         existing_units = {
             name: unit
@@ -380,7 +380,7 @@ def quantify(self, units=_default, unit_registry=None, **unit_kwargs):
                 )
                 for name, (old, new) in overwritten_units.items()
             }
-            raise ValueError(format_error_message(errors, "attach"))
+            raise create_exception_group(errors, "attach")
 
         return self.da.pipe(conversion.strip_unit_attributes).pipe(
             conversion.attach_units, new_units
@@ -1091,7 +1091,7 @@ def quantify(self, units=_default, unit_registry=None, **unit_kwargs):
                     invalid_units[name] = (reported_unit, type, e)
 
         if invalid_units:
-            raise ValueError(format_error_message(invalid_units, "parse"))
+            raise create_exception_group(invalid_units, "parse")
 
         existing_units = {
             name: unit
@@ -1116,7 +1116,7 @@ def quantify(self, units=_default, unit_registry=None, **unit_kwargs):
                 )
                 for name, (old, new) in overwritten_units.items()
             }
-            raise ValueError(format_error_message(errors, "attach"))
+            raise create_exception_group(errors, "attach")
 
         return self.ds.pipe(conversion.strip_unit_attributes).pipe(
             conversion.attach_units, new_units

pint_xarray/conversion.py

@@ -5,7 +5,7 @@
 from xarray import Coordinates, DataArray, Dataset, IndexVariable, Variable
 
 from pint_xarray.compat import call_on_dataset
-from pint_xarray.errors import format_error_message
+from pint_xarray.errors import create_exception_group
 from pint_xarray.index import PintIndex
 
 no_unit_values = ("none", None)
@@ -198,7 +198,7 @@ def attach_units(obj, units):
         if temporary_name in rejected_vars:
             rejected_vars[obj.name] = rejected_vars.pop(temporary_name)
 
-        raise ValueError(format_error_message(rejected_vars, "attach")) from e
+        raise create_exception_group(rejected_vars, "attach") from None
 
     return new_obj
 
@@ -328,7 +328,7 @@ def convert_units(obj, units):
         if temporary_name in failed:
             failed[obj.name] = failed.pop(temporary_name)
 
-        raise ValueError(format_error_message(failed, "convert")) from e
+        raise create_exception_group(failed, "convert") from None
 
     return new_obj
 
@@ -482,7 +482,7 @@ def convert(indexer, units):
             invalid[name] = e
 
     if invalid:
-        raise ValueError(format_error_message(invalid, "convert_indexers"))
+        raise create_exception_group(invalid, "convert_indexers")
 
     return converted
 

pint_xarray/errors.py

@@ -1,42 +1,49 @@
-def format_error_message(mapping, op):
-    sep = "\n    " if len(mapping) == 1 else "\n -- "
-    if op == "attach":
-        message = "Cannot attach units:"
-        message = sep.join(
-            [message]
-            + [
-                f"cannot attach units to variable {key!r}: {unit} (reason: {str(e)})"
+from collections.abc import Hashable
+from typing import Any
+
+
+class PintExceptionGroup(ExceptionGroup, ValueError):
+    """Exception group for errors related to unit operations
+
+    Raised whenever there's the possibility of multiple errors.
+    """
+
+    pass
+
+
+def _add_note(e: Exception, note: str) -> Exception:
+    e.add_note(note)
+
+    return e
+
+
+def create_exception_group(mapping: dict[Hashable, Any], op: str) -> ExceptionGroup:
+    match op:
+        case "attach":
+            message = "Cannot attach units"
+            errors = [
+                _add_note(e, f"cannot attach units to variable {key!r}: {unit}")
                 for key, (unit, e) in mapping.items()
             ]
-        )
-    elif op == "parse":
-        message = "Cannot parse units:"
-        message = sep.join(
-            [message]
-            + [
-                f"invalid units for variable {key!r}: {unit} ({type}) (reason: {str(e)})"
+        case "parse":
+            message = "Cannot parse units"
+            errors = [
+                _add_note(e, f"invalid units for variable {key!r}: {unit} ({type})")
                 for key, (unit, type, e) in mapping.items()
             ]
-        )
-    elif op == "convert":
-        message = "Cannot convert variables:"
-        message = sep.join(
-            [message]
-            + [
-                f"incompatible units for variable {key!r}: {error}"
-                for key, error in mapping.items()
+        case "convert":
+            message = "Cannot convert variables"
+            errors = [
+                _add_note(e, f"incompatible units for variable {key!r}")
+                for key, e in mapping.items()
             ]
-        )
-    elif op == "convert_indexers":
-        message = "Cannot convert indexers:"
-        message = sep.join(
-            [message]
-            + [
-                f"incompatible units for indexer for {key!r}: {error}"
-                for key, error in mapping.items()
+        case "convert_indexers":
+            message = "Cannot convert indexers"
+            errors = [
+                _add_note(e, f"incompatible units for indexer for {key!r}")
+                for key, e in mapping.items()
             ]
-        )
-    else:
-        raise ValueError("invalid op")
+        case _:  # pragma: no cover
+            raise ValueError("invalid op")
 
-    return message
+    return PintExceptionGroup(message, errors)

pint_xarray/tests/test_accessors.py

@@ -7,6 +7,7 @@
 from pint import Unit, UnitRegistry
 
 from pint_xarray import accessors, conversion
+from pint_xarray.errors import PintExceptionGroup
 from pint_xarray.index import PintIndex
 from pint_xarray.tests.utils import (
     assert_equal,
@@ -114,7 +115,11 @@ def test_override_units(self, example_unitless_da, no_unit_value):
 
     def test_error_when_changing_units(self, example_quantity_da):
         da = example_quantity_da
-        with pytest.raises(ValueError, match="already has units"):
+        with pytest.RaisesGroup(
+            pytest.RaisesExc(ValueError, match="already has units"),
+            match="Cannot attach units",
+            check=lambda eg: isinstance(eg, PintExceptionGroup),
+        ):
             da.pint.quantify("s")
 
     def test_attach_no_units(self):
@@ -141,7 +146,11 @@ def test_error_when_changing_units_dimension_coordinates(self):
             dims="x",
             coords={"x": ("x", [-1, 0, 1], {"units": unit_registry.Unit("m")})},
         )
-        with pytest.raises(ValueError, match="already has units"):
+        with pytest.RaisesGroup(
+            pytest.RaisesExc(ValueError, match="already has units"),
+            match="Cannot attach units",
+            check=lambda eg: isinstance(eg, PintExceptionGroup),
+        ):
             arr.pint.quantify({"x": "s"})
 
     def test_dimension_coordinate_array(self):
@@ -157,7 +166,11 @@ def test_dimension_coordinate_array_already_quantified(self):
         ds = xr.Dataset(coords={"x": ("x", [10], {"units": unit_registry.Unit("m")})})
         arr = ds.x
 
-        with pytest.raises(ValueError):
+        with pytest.RaisesGroup(
+            pytest.RaisesExc(ValueError, match="already has units"),
+            match="Cannot attach units",
+            check=lambda eg: isinstance(eg, PintExceptionGroup),
+        ):
             arr.pint.quantify({"x": "s"})
 
     def test_dimension_coordinate_array_already_quantified_same_units(self):
@@ -181,14 +194,24 @@ def test_dimension_coordinate_array_already_quantified_same_units(self):
 
     def test_error_on_nonsense_units(self, example_unitless_da):
         da = example_unitless_da
-        with pytest.raises(ValueError, match=str(da.name)):
+        with pytest.RaisesGroup(
+            pytest.RaisesExc(
+                pint.UndefinedUnitError, match=rf"{da.name}: .+ \(parameter\)"
+            ),
+            match="Cannot parse units",
+            check=lambda eg: isinstance(eg, PintExceptionGroup),
+        ):
             da.pint.quantify(units="aecjhbav")
 
     def test_error_on_nonsense_units_attrs(self, example_unitless_da):
         da = example_unitless_da
         da.attrs["units"] = "aecjhbav"
-        with pytest.raises(
-            ValueError, match=rf"{da.name}: {da.attrs['units']} \(attribute\)"
+        with pytest.RaisesGroup(
+            pytest.RaisesExc(
+                pint.UndefinedUnitError, match=rf"{da.name}: .+ \(attribute\)"
+            ),
+            match="Cannot parse units",
+            check=lambda eg: isinstance(eg, PintExceptionGroup),
         ):
             da.pint.quantify()
 
@@ -355,7 +378,11 @@ def test_override_units(self, example_unitless_ds, no_unit_value):
         )
 
     def test_error_when_already_units(self, example_quantity_ds):
-        with pytest.raises(ValueError, match="already has units"):
+        with pytest.RaisesGroup(
+            pytest.RaisesExc(ValueError, match="already has units"),
+            match="Cannot attach units",
+            check=lambda eg: isinstance(eg, PintExceptionGroup),
+        ):
             example_quantity_ds.pint.quantify({"funds": "kg"})
 
     def test_attach_no_units(self):
@@ -382,25 +409,45 @@ def test_error_when_changing_units_dimension_coordinates(self):
         ds = xr.Dataset(
             coords={"x": ("x", [-1, 0, 1], {"units": unit_registry.Unit("m")})},
         )
-        with pytest.raises(ValueError, match="already has units"):
+        with pytest.RaisesGroup(
+            pytest.RaisesExc(ValueError, match="already has units"),
+            match="Cannot attach units",
+            check=lambda eg: isinstance(eg, PintExceptionGroup),
+        ):
             ds.pint.quantify({"x": "s"})
 
     def test_error_on_nonsense_units(self, example_unitless_ds):
         ds = example_unitless_ds
-        with pytest.raises(ValueError):
+        with pytest.RaisesGroup(
+            pytest.RaisesExc(
+                pint.UndefinedUnitError, match=r"'users': .+ \(parameter\)"
+            ),
+            match="Cannot parse units",
+            check=lambda eg: isinstance(eg, PintExceptionGroup),
+        ):
             ds.pint.quantify(units={"users": "aecjhbav"})
 
     def test_error_on_nonsense_units_attrs(self, example_unitless_ds):
         ds = example_unitless_ds
         ds.users.attrs["units"] = "aecjhbav"
-        with pytest.raises(
-            ValueError, match=rf"'users': {ds.users.attrs['units']} \(attribute\)"
+        with pytest.RaisesGroup(
+            pytest.RaisesExc(
+                pint.UndefinedUnitError, match=r"'users': .+ \(attribute\)"
+            ),
+            match="Cannot parse units",
+            check=lambda eg: isinstance(eg, PintExceptionGroup),
         ):
             ds.pint.quantify()
 
     def test_error_indicates_problematic_variable(self, example_unitless_ds):
         ds = example_unitless_ds
-        with pytest.raises(ValueError, match="'users'"):
+        with pytest.RaisesGroup(
+            pytest.RaisesExc(
+                pint.UndefinedUnitError, match=r"'users': aecjhbav \(parameter\)"
+            ),
+            match="Cannot parse units",
+            check=lambda eg: isinstance(eg, PintExceptionGroup),
+        ):
             ds.pint.quantify(units={"users": "aecjhbav"})
 
     def test_existing_units(self, example_quantity_ds):