feat: support constructor conversion from UHI (#1034)

* feat: support constructor conversion from UHI

Signed-off-by: Henry Schreiner <[email protected]>

* fix: rework implementation to not call init recursively

Signed-off-by: Henry Schreiner <[email protected]>

---------

Signed-off-by: Henry Schreiner <[email protected]>

Author: henryiii

src/boost_histogram/histogram.py

@@ -223,10 +223,13 @@ def __init_subclass__(cls, *, family: object | None = None) -> None:
         cls._family = family if family is not None else object()
 
     @typing.overload
-    def __init__(self, *args: Histogram) -> None: ...
+    def __init__(self, arg: Histogram, /, *, metadata: Any = ...) -> None: ...
 
     @typing.overload
-    def __init__(self, *args: CppHistogram, metadata: Any = ...) -> None: ...
+    def __init__(self, arg: dict[str, Any], /, *, metadata: Any = ...) -> None: ...
+
+    @typing.overload
+    def __init__(self, arg: CppHistogram, /, *, metadata: Any = ...) -> None: ...
 
     @typing.overload
     def __init__(
@@ -238,8 +241,8 @@ def __init__(
 
     def __init__(
         self,
-        *axes: Axis | CppAxis | Histogram | CppHistogram,
-        storage: Storage = Double(),  # noqa: B008
+        *axes: Axis | CppAxis | Histogram | CppHistogram | dict[str, Any],
+        storage: Storage | None = None,
         metadata: Any = None,
     ) -> None:
         """
@@ -259,31 +262,44 @@ def __init__(
             Data that is passed along if a new histogram is created
         """
         self._variance_known = True
+        storage_err_msg = "storage= is not allowed with conversion constructor"
 
         # Allow construction from a raw histogram object (internal)
         if len(axes) == 1 and isinstance(axes[0], tuple(_histograms)):
+            if storage is not None:
+                raise TypeError(storage_err_msg)
             cpp_hist: CppHistogram = axes[0]  # type: ignore[assignment]
-            self._from_histogram_cpp(cpp_hist)
-            if metadata is not None:
-                self.metadata = metadata
+            self._from_histogram_cpp(cpp_hist, metadata=None)
             return
 
         # If we construct with another Histogram as the only positional argument,
         # support that too
         if len(axes) == 1 and isinstance(axes[0], Histogram):
-            normal_hist: Histogram = axes[0]
-            self._from_histogram_object(normal_hist)
-            if metadata is not None:
-                self.metadata = metadata
+            if storage is not None:
+                raise TypeError(storage_err_msg)
+            self._from_histogram_object(axes[0], metadata=metadata)
             return
 
         # Support objects that provide a to_boost method, like Uproot
         if len(axes) == 1 and hasattr(axes[0], "_to_boost_histogram_"):
-            self._from_histogram_object(axes[0]._to_boost_histogram_())
+            if storage is not None:
+                raise TypeError(storage_err_msg)
+            self._from_histogram_object(
+                axes[0]._to_boost_histogram_(), metadata=metadata
+            )
+            return
+
+        # Support UHI
+        if len(axes) == 1 and isinstance(axes[0], dict) and "uhi_schema" in axes[0]:
+            if storage is not None:
+                raise TypeError(storage_err_msg)
+            self._from_histogram_object(
+                serialization.from_uhi(axes[0]), metadata=metadata
+            )
             return
 
         if storage is None:
-            storage = Double()  # type: ignore[unreachable]
+            storage = Double()
 
         self.metadata = metadata
 
@@ -356,16 +372,16 @@ def _new_hist(self, _hist: CppHistogram, memo: Any = NOTHING) -> Self:
         """
         return self.__class__._clone(_hist, other=self, memo=memo)
 
-    def _from_histogram_cpp(self, other: CppHistogram) -> None:
+    def _from_histogram_cpp(self, other: CppHistogram, *, metadata: Any = None) -> None:
         """
         Import a Cpp histogram.
         """
         self._variance_known = True
         self._hist = other
-        self.metadata = None
+        self.metadata = metadata
         self.axes = self._generate_axes_()
 
-    def _from_histogram_object(self, other: Histogram) -> None:
+    def _from_histogram_object(self, other: Histogram, *, metadata: Any = None) -> None:
         """
         Convert self into a new histogram object based on another, possibly
         converting from a different subclass.
@@ -375,6 +391,7 @@ def _from_histogram_object(self, other: Histogram) -> None:
         self.axes = self._generate_axes_()
         for ax in self.axes:
             ax.__dict__ = copy.copy(ax._ax.raw_metadata)
+        self.metadata = other.metadata if metadata is None else metadata
 
         # Allow custom behavior on either "from" or "to"
         other._export_bh_(self)

tests/test_serialization_uhi.py

@@ -197,6 +197,16 @@ def test_uhi_wrapper():
     assert repr(from_uhi(data)) == repr(bh.Histogram._from_uhi_(data))
 
 
+def test_uhi_direct_conversion():
+    h = bh.Histogram(
+        bh.axis.IntCategory([1, 2, 3]),
+        storage=bh.storage.Int64(),
+    )
+    uhi_dict = h._to_uhi_()
+    h2 = bh.Histogram(uhi_dict)
+    assert h == h2
+
+
 def test_round_trip_native() -> None:
     h = bh.Histogram(
         bh.axis.Integer(0, 10),