Fix metadata serialization

In the previous implementation, a Metadata object had two different dict
representations, depending on which conversion route was taken.

The problem has been captured in tests and is now now fixed throught the
conversion hooks.

A minimal reproducing example demonstrating the issue:

```python
from baybe.utils.metadata import Metadata, to_metadata

dct = {"description": "test", "unit": "m", "key": "value"}
metadata = to_metadata(dct)

print("Dict:\n", dct, "\n")
print("Via to_metadata:\n", metadata, "\n")
print("Via from_dict:\n", Metadata.from_dict(dct), "\n")
print("Via to_dict:\n", metadata.to_dict(), "\n")
```

Author: AdrianSosic

baybe/utils/metadata.py

@@ -4,11 +4,13 @@
 
 from typing import Any
 
+import cattrs
 from attrs import define, field, fields
 from attrs.validators import deep_mapping, instance_of
 from attrs.validators import optional as optional_v
 
-from baybe.serialization.mixin import SerialMixin
+from baybe.serialization import SerialMixin, converter
+from baybe.utils.basic import classproperty
 
 
 @define(frozen=True)
@@ -34,6 +36,20 @@ class Metadata(SerialMixin):
     )
     """Additional user-defined metadata."""
 
+    @misc.validator
+    def _validate_misc(self, _, value: dict[str, Any]) -> None:
+        if inv := set(value).intersection(self._explicit_fields):
+            raise ValueError(
+                f"Miscellaneous metadata cannot contain the following fields: {inv}. "
+                f"Use the corresponding attributes instead."
+            )
+
+    @classproperty
+    def _explicit_fields(self) -> set[str]:
+        """The explicit metadata fields."""  # noqa: D401
+        flds = fields(Metadata)
+        return {fld.name for fld in flds if fld.name != flds.misc.name}
+
 
 def to_metadata(value: dict[str, Any] | Metadata, /) -> Metadata:
     """Convert a dictionary to :class:`Metadata` (with :class:`Metadata` passthrough).
@@ -57,10 +73,22 @@ def to_metadata(value: dict[str, Any] | Metadata, /) -> Metadata:
         )
 
     # Separate known fields from unknown ones
-    flds = fields(Metadata)
-    value = value.copy()
-    known_fields = {
-        fld: value.pop(fld, None) for fld in (flds.description.name, flds.unit.name)
-    }
+    return converter.structure(value, Metadata)
+
+
+@converter.register_structure_hook
+def _separate_metadata_fields(dct: dict[str, Any], _: type[Metadata]) -> Metadata:
+    """Separate known fields from miscellaneous metadata."""
+    dct = dct.copy()
+    explicit = {fld: dct.pop(fld, None) for fld in Metadata._explicit_fields}
+    return Metadata(**explicit, misc=dct)
+
 
-    return Metadata(**known_fields, misc=value)
+@converter.register_unstructure_hook
+def _flatten_misc_metadata(metadata: Metadata) -> dict[str, Any]:
+    """Flatten the metadata for serialization."""
+    fn = cattrs.gen.make_dict_unstructure_fn(Metadata, converter)
+    dct = fn(metadata)
+    fld = fields(Metadata).misc.name
+    dct = dct | dct.pop(fld)
+    return dct

tests/validation/test_metadata_validation.py

@@ -7,17 +7,33 @@
 
 
 @pytest.mark.parametrize(
-    ("description", "unit", "misc", "match"),
+    ("description", "unit", "misc", "error", "match"),
     [
-        param(0, None, None, "must be <class 'str'>", id="desc-non-str"),
-        param(None, 0, None, "must be <class 'str'>", id="unit-non-str"),
-        param(None, None, 0, "must be <class 'dict'>", id="misc-non-dict"),
-        param(None, None, {0: 0}, "must be <class 'str'>", id="misc-non-str-keys"),
+        param(0, None, None, TypeError, "must be <class 'str'>", id="desc-non-str"),
+        param(None, 0, None, TypeError, "must be <class 'str'>", id="unit-non-str"),
+        param(None, None, 0, TypeError, "must be <class 'dict'>", id="misc-non-dict"),
+        param(
+            None,
+            None,
+            {0: 0},
+            TypeError,
+            "must be <class 'str'>",
+            id="misc-non-str-keys",
+        ),
+        param(
+            None,
+            None,
+            {"description": 0},
+            ValueError,
+            "fields: {'description'}",
+            id="desc",
+        ),
+        param(None, None, {"unit": 0}, ValueError, "fields: {'unit'}", id="unit"),
     ],
 )
-def test_invalid_arguments(description, unit, misc, match):
+def test_invalid_arguments(description, unit, misc, error, match):
     """Providing invalid arguments raises an error."""
-    with pytest.raises(TypeError, match=match):
+    with pytest.raises(error, match=match):
         Metadata(description, unit, misc)