Add backwards-compatible marshmallow 4.x support

- Add deprecation warning for QuantitySchema(serialize_as_string_default=...)
  constructor parameter, use serialize_as_string_default context variable instead
- Maintain backwards compatibility with old metadata API
- Update RELEASE_NOTES.md with upgrade guide

Signed-off-by: Mathias L. Baumann <mathias.baumann@frequenz.com>

Author: Marenz

RELEASE_NOTES.md

@@ -2,15 +2,52 @@
 
 ## Summary
 
-<!-- Here goes a general summary of what this release is about -->
+This release adds support for marshmallow 4.x. The old API is still supported but deprecated.
 
 ## Upgrading
 
-- `typing-extensions` minimal version was bumped to 4.6.0 to be compatible with Python3.12. You might need to upgrade it in your project too.
+### Marshmallow module API changes
+
+The `frequenz.quantities.experimental.marshmallow` module has been updated to support marshmallow 4.x. The old API is still supported but deprecated and will emit `DeprecationWarning`.
+
+#### `QuantitySchema` constructor parameter `serialize_as_string_default` is deprecated
+
+Old API (deprecated, still works):
+```python
+from marshmallow_dataclass import class_schema
+from frequenz.quantities.experimental.marshmallow import QuantitySchema
+
+schema = class_schema(Config, base_schema=QuantitySchema)(
+    serialize_as_string_default=True
+)
+result = schema.dump(config_obj)
+```
+
+New API (recommended):
+```python
+from marshmallow_dataclass import class_schema
+from frequenz.quantities.experimental.marshmallow import (
+    QuantitySchema,
+    serialize_as_string_default,
+)
+
+serialize_as_string_default.set(True)
+schema = class_schema(Config, base_schema=QuantitySchema)()
+result = schema.dump(config_obj)
+serialize_as_string_default.set(False)  # Reset if needed
+```
+
+### Why this change was necessary
+
+Marshmallow 4.0.0 introduced breaking changes including:
+- `Field` is now a generic type (`Field[T]`)
+- Changes to how schema context is accessed from fields
+
+The previous implementation relied on `self.parent.context` to access the `serialize_as_string_default` setting, which no longer works reliably with marshmallow 4.x. The new implementation uses Python's `contextvars.ContextVar` instead, which is a cleaner and more explicit approach.
 
 ## New Features
 
-<!-- Here goes the main new features and examples or instructions on how to use them -->
+- Support for marshmallow 4.x (in addition to 3.x)
 
 ## Bug Fixes
 

src/frequenz/quantities/experimental/marshmallow.py

@@ -14,6 +14,7 @@
     even in minor or patch releases.
 """
 
+import warnings
 from contextvars import ContextVar
 from typing import Any, Type
 
@@ -76,6 +77,12 @@ def __init__(self, *args: Any, **kwargs: Any) -> None:
         self.serialize_as_string_override = kwargs.pop("serialize_as_string", None)
         super().__init__(*args, **kwargs)
 
+        # Backwards compatibility: also check self.metadata for serialize_as_string
+        # (v1.0.0 API read it from self.metadata directly)
+        if self.serialize_as_string_override is None:
+            if "serialize_as_string" in self.metadata:
+                self.serialize_as_string_override = self.metadata["serialize_as_string"]
+
     def _serialize(
         self, value: Quantity | None, attr: str | None, obj: Any, **kwargs: Any
     ) -> Any:
@@ -292,3 +299,29 @@ class Config:
     """
 
     TYPE_MAPPING: dict[type, type[Field[Any]]] = QUANTITY_FIELD_CLASSES
+
+    def __init__(
+        self, *args: Any, serialize_as_string_default: bool | None = None, **kwargs: Any
+    ) -> None:
+        """Initialize the schema.
+
+        Args:
+            *args: Positional arguments passed to the parent Schema.
+            serialize_as_string_default: Deprecated. Use the
+                `serialize_as_string_default` context variable instead.
+                If provided, sets the context variable for backwards compatibility.
+            **kwargs: Keyword arguments passed to the parent Schema.
+        """
+        super().__init__(*args, **kwargs)
+        if serialize_as_string_default is not None:
+            warnings.warn(
+                "Passing 'serialize_as_string_default' to QuantitySchema constructor is "
+                "deprecated. Use the 'serialize_as_string_default' context variable instead: "
+                "serialize_as_string_default.set(True)",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+            # Import the module-level context variable
+            from . import marshmallow as _module
+
+            _module.serialize_as_string_default.set(serialize_as_string_default)

tests/experimental/test_marshmallow.py

@@ -3,10 +3,11 @@
 
 """Test marshmallow fields and schema."""
 
-
+import warnings
 from dataclasses import dataclass, field
 from typing import Any, Self, cast
 
+import pytest
 from marshmallow_dataclass import class_schema
 
 from frequenz.quantities import (
@@ -246,3 +247,43 @@ def test_config_schema_dump_default_string() -> None:
         "voltage_always_string": "250 kV",
         "temp_never_string": 10.0,
     }
+
+
+def test_deprecated_constructor_api() -> None:
+    """Test that the deprecated constructor API still works but emits a warning."""
+
+    @dataclass
+    class SimpleConfig:
+        pct: Percentage = field(default_factory=lambda: Percentage.from_percent(75.0))
+
+    Schema = class_schema(SimpleConfig, base_schema=QuantitySchema)
+
+    with pytest.warns(
+        DeprecationWarning,
+        match="Passing 'serialize_as_string_default' to QuantitySchema constructor is deprecated",
+    ):
+        schema = Schema(serialize_as_string_default=True)  # type: ignore[call-arg]
+
+    # Verify it still works
+    result = schema.dump(SimpleConfig())
+    assert result["pct"] == "75 %"  # type: ignore[index]
+
+
+def test_deprecated_constructor_api_false() -> None:
+    """Test that the deprecated constructor API works with False value."""
+
+    @dataclass
+    class SimpleConfig:
+        pct: Percentage = field(default_factory=lambda: Percentage.from_percent(75.0))
+
+    Schema = class_schema(SimpleConfig, base_schema=QuantitySchema)
+
+    with pytest.warns(
+        DeprecationWarning,
+        match="Passing 'serialize_as_string_default' to QuantitySchema constructor is deprecated",
+    ):
+        schema = Schema(serialize_as_string_default=False)  # type: ignore[call-arg]
+
+    # Verify it still works
+    result = schema.dump(SimpleConfig())
+    assert result["pct"] == 75.0  # type: ignore[index]