Make the new marshmallow module experimental (#28)

This means we are not yet committing to a stable API between minor or
patch releases.

We also add missing quantities to the module documentation and sort
`__all__`.

Author: llucax

RELEASE_NOTES.md

@@ -9,5 +9,5 @@ This is the initial release, extracted from the [SDK v1.0.0rc601](https://github
 - Added support for `__round__` (`round(quantity)`), `__pos__` (`+quantity`) and `__mod__` (`quantity % quantity`) operators.
 - Add `ReactivePower` quantity.
 - Add `ApparentPower` quantity.
-- Add marshmallow module available when adding `[marshmallow]` to the requirements.
+- Add an **experimental** marshmallow module available when adding `[marshmallow]` to the requirements.
    * Add a QuantitySchema supporting string/float based serialization and deserialization of quantities.

src/frequenz/quantities/__init__.py

@@ -24,18 +24,18 @@
 
 This library provides the following types:
 
+- [ApparentPower][frequenz.quantities.ApparentPower]: A quantity representing apparent
+  power.
 - [Current][frequenz.quantities.Current]: A quantity representing an electric current.
 - [Energy][frequenz.quantities.Energy]: A quantity representing energy.
 - [Frequency][frequenz.quantities.Frequency]: A quantity representing frequency.
 - [Percentage][frequenz.quantities.Percentage]: A quantity representing a percentage.
 - [Power][frequenz.quantities.Power]: A quantity representing power.
+- [ReactivePower][frequenz.quantities.ReactivePower]: A quantity representing reactive
+  power.
 - [Temperature][frequenz.quantities.Temperature]: A quantity representing temperature.
 - [Voltage][frequenz.quantities.Voltage]: A quantity representing electric voltage.
 
-Additionally, for each of those types, there is a corresponding marshmallow
-field that can be used to serialize and deserialize the quantities using the
-[QuantitySchema][frequenz.quantities.marshmallow.QuantitySchema] schema.
-
 There is also the unitless [Quantity][frequenz.quantities.Quantity] class. All
 quantities are subclasses of this class and it can be used as a base to create new
 quantities. Using the `Quantity` class directly is discouraged, as it doesn't provide
@@ -78,6 +78,12 @@
     except TypeError as e:
         print(f"Error: {e}")  # Error: unsupported operand type(s) for +: 'Power' and 'Voltage'
     ```
+
+This library also provides an [**experimental** module with marshmallow fields and
+a base schema][frequenz.quantities.experimental.marshmallow] to serialize and
+deserialize quantities using the marshmallow library. To use it, you need to make sure
+to install this package with the `marshmallow` optional dependencies (e.g.
+`pip install frequenz-quantities[marshmallow]`).
 """
 
 
@@ -93,14 +99,14 @@
 from ._voltage import Voltage
 
 __all__ = [
+    "ApparentPower",
     "Current",
     "Energy",
     "Frequency",
     "Percentage",
     "Power",
     "Quantity",
     "ReactivePower",
-    "ApparentPower",
     "Temperature",
     "Voltage",
 ]

src/frequenz/quantities/experimental/__init__.py

@@ -0,0 +1,11 @@
+# License: All rights reserved
+# Copyright © 2024 Frequenz Energy-as-a-Service GmbH
+
+"""Experimental features for quantities.
+
+Danger:
+    This package contains experimental features for which the API is not yet stable.
+
+    Any module or class in this package may be removed or changed in a future release,
+    even in minor or patch releases.
+"""

src/frequenz/quantities/marshmallow.py …z/quantities/experimental/marshmallow.pysrc/frequenz/quantities/marshmallow.py renamed to src/frequenz/quantities/experimental/marshmallow.py src/frequenz/quantities/marshmallow.py renamed to src/frequenz/quantities/experimental/marshmallow.py

@@ -1,22 +1,33 @@
 # License: All rights reserved
 # Copyright © 2024 Frequenz Energy-as-a-Service GmbH
 
-"""Custom marshmallow fields and schema."""
+"""Custom marshmallow fields and schema.
+
+This module provides custom marshmallow fields for quantities and
+a [QuantitySchema][frequenz.quantities.experimental.marshmallow.QuantitySchema] class to
+be used as base schema for dataclasses containing quantities.
+
+Danger:
+    This module contains experimental features for which the API is not yet stable.
+
+    Any module or class in this package may be removed or changed in a future release,
+    even in minor or patch releases.
+"""
 
 from typing import Any, Type
 
 from marshmallow import Schema, ValidationError, fields
 
-from ._apparent_power import ApparentPower
-from ._current import Current
-from ._energy import Energy
-from ._frequency import Frequency
-from ._percentage import Percentage
-from ._power import Power
-from ._quantity import Quantity
-from ._reactive_power import ReactivePower
-from ._temperature import Temperature
-from ._voltage import Voltage
+from .._apparent_power import ApparentPower
+from .._current import Current
+from .._energy import Energy
+from .._frequency import Frequency
+from .._percentage import Percentage
+from .._power import Power
+from .._quantity import Quantity
+from .._reactive_power import ReactivePower
+from .._temperature import Temperature
+from .._voltage import Voltage
 
 
 class _QuantityField(fields.Field):
@@ -194,7 +205,8 @@ class QuantitySchema(Schema):
     from dataclasses import dataclass, field
     from marshmallow_dataclass import class_schema
     from marshmallow.validate import Range
-    from frequenz.quantities import Percentage, QuantitySchema
+    from frequenz.quantities import Percentage
+    from frequenz.quantities.experimental.marshmallow import QuantitySchema
     from typing import cast
 
     @dataclass

tests/test_marshmallow.py tests/experimental/test_marshmallow.pytests/test_marshmallow.py renamed to tests/experimental/test_marshmallow.py

@@ -18,7 +18,7 @@
     Temperature,
     Voltage,
 )
-from frequenz.quantities.marshmallow import QuantitySchema
+from frequenz.quantities.experimental.marshmallow import QuantitySchema
 
 
 @dataclass