diff --git a/RELEASE_NOTES.md b/RELEASE_NOTES.md index a0a4029..a337ba4 100644 --- a/RELEASE_NOTES.md +++ b/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. diff --git a/src/frequenz/quantities/__init__.py b/src/frequenz/quantities/__init__.py index e4dcd2f..6f30032 100644 --- a/src/frequenz/quantities/__init__.py +++ b/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,6 +99,7 @@ from ._voltage import Voltage __all__ = [ + "ApparentPower", "Current", "Energy", "Frequency", @@ -100,7 +107,6 @@ "Power", "Quantity", "ReactivePower", - "ApparentPower", "Temperature", "Voltage", ] diff --git a/src/frequenz/quantities/experimental/__init__.py b/src/frequenz/quantities/experimental/__init__.py new file mode 100644 index 0000000..089cf8e --- /dev/null +++ b/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. +""" diff --git a/src/frequenz/quantities/marshmallow.py b/src/frequenz/quantities/experimental/marshmallow.py similarity index 89% rename from src/frequenz/quantities/marshmallow.py rename to src/frequenz/quantities/experimental/marshmallow.py index 4f06de8..ed0dc74 100644 --- a/src/frequenz/quantities/marshmallow.py +++ b/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 diff --git a/tests/test_marshmallow.py b/tests/experimental/test_marshmallow.py similarity index 99% rename from tests/test_marshmallow.py rename to tests/experimental/test_marshmallow.py index 28f3ab3..d67eabf 100644 --- a/tests/test_marshmallow.py +++ b/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