Use frequenz-quantities library

RELEASE_NOTES.md

@@ -6,7 +6,11 @@
 
 ## Upgrading
 
-<!-- Here goes notes on how to upgrade from previous versions, including deprecations and what they should be replaced with -->
+- Replace `Quantity` and its sub-classes (`Power`, `Current`, etc.) in the `frequenz.sdk.timeseries` module with the external
+[`frequenz-quantities`](https://pypi.org/project/frequenz-quantities/) package. Please add the new library as a dependency
+and adapt your imports if you are using these types.
+- The `QuantityT` has been moved to the `frequenz.sdk.timeseries._base_types` module.
+- The `QuantityT` doesn't include itself (`QuantityT`) anymore.
 
 ## New Features
 

benchmarks/power_distribution/power_distributor.py

@@ -13,6 +13,7 @@
 
 from frequenz.channels import Broadcast
 from frequenz.client.microgrid import Component, ComponentCategory
+from frequenz.quantities import Power
 
 from frequenz.sdk import microgrid
 from frequenz.sdk.actor import ResamplerConfig
@@ -27,7 +28,6 @@
     Result,
     Success,
 )
-from frequenz.sdk.timeseries._quantities import Power
 
 HOST = "microgrid.sandbox.api.frequenz.io"
 PORT = 62060

benchmarks/timeseries/periodic_feature_extractor.py

@@ -20,11 +20,11 @@
 
 import numpy as np
 from frequenz.channels import Broadcast
+from frequenz.quantities import Quantity
 from numpy.random import default_rng
 from numpy.typing import NDArray
 
 from frequenz.sdk.timeseries import MovingWindow, PeriodicFeatureExtractor, Sample
-from frequenz.sdk.timeseries._quantities import Quantity
 
 
 @contextlib.asynccontextmanager

benchmarks/timeseries/resampling.py

@@ -7,8 +7,9 @@
 from datetime import datetime, timedelta, timezone
 from timeit import timeit
 
+from frequenz.quantities import Quantity
+
 from frequenz.sdk.timeseries import Sample
-from frequenz.sdk.timeseries._quantities import Quantity
 from frequenz.sdk.timeseries._resampling import (
     ResamplerConfig,
     SourceProperties,

benchmarks/timeseries/ringbuffer_memusage.py

@@ -9,9 +9,9 @@
 from datetime import datetime, timedelta, timezone
 
 import numpy as np
+from frequenz.quantities import Quantity
 
 from frequenz.sdk.timeseries import Sample
-from frequenz.sdk.timeseries._quantities import Quantity
 from frequenz.sdk.timeseries._ringbuffer import OrderedRingBuffer
 
 FIVE_MINUTES = timedelta(minutes=5)

benchmarks/timeseries/ringbuffer_serialization.py

@@ -11,10 +11,10 @@
 from typing import Any
 
 import numpy as np
+from frequenz.quantities import Quantity
 
 import frequenz.sdk.timeseries._ringbuffer as rb
 from frequenz.sdk.timeseries import Sample
-from frequenz.sdk.timeseries._quantities import Quantity
 
 FILE_NAME = "ringbuffer.pkl"
 FIVE_MINUTES = timedelta(minutes=5)

pyproject.toml

@@ -31,6 +31,7 @@ dependencies = [
   # (plugins.mkdocstrings.handlers.python.import)
   "frequenz-client-microgrid >= 0.5.1, < 0.6.0",
   "frequenz-channels >= 1.2.0, < 2.0.0",
+  "frequenz-quantities == 1.0.0rc1",
   "networkx >= 2.8, < 4",
   "numpy >= 1.26.4, < 2",
   "typing_extensions >= 4.6.1, < 5",

src/frequenz/sdk/microgrid/_data_sourcing/microgrid_api_source.py

@@ -17,12 +17,12 @@
     InverterData,
     MeterData,
 )
+from frequenz.quantities import Quantity
 
 from ..._internal._asyncio import run_forever
 from ..._internal._channels import ChannelRegistry
 from ...microgrid import connection_manager
 from ...timeseries import Sample
-from ...timeseries._quantities import Quantity
 from ._component_metric_request import ComponentMetricRequest
 
 _logger = logging.getLogger(__name__)

src/frequenz/sdk/microgrid/_power_distributing/_component_managers/_battery_manager.py

@@ -18,10 +18,10 @@
     InverterData,
     OperationOutOfRange,
 )
+from frequenz.quantities import Power
 from typing_extensions import override
 
 from ...._internal._math import is_close_to_zero
-from ....timeseries._quantities import Power
 from ... import connection_manager
 from .._component_pool_status_tracker import ComponentPoolStatusTracker
 from .._component_status import BatteryStatusTracker, ComponentPoolStatus

src/frequenz/sdk/microgrid/_power_distributing/_component_managers/_ev_charger_manager/_config.py

@@ -7,7 +7,7 @@
 from dataclasses import dataclass, field
 from datetime import timedelta
 
-from .....timeseries import Current
+from frequenz.quantities import Current
 
 
 @dataclass(frozen=True)

src/frequenz/sdk/microgrid/_power_distributing/_component_managers/_ev_charger_manager/_ev_charger_manager.py

@@ -22,11 +22,12 @@
     ComponentCategory,
     EVChargerData,
 )
+from frequenz.quantities import Power, Voltage
 from typing_extensions import override
 
 from ....._internal._asyncio import run_forever
 from ....._internal._math import is_close_to_zero
-from .....timeseries import Power, Sample3Phase, Voltage
+from .....timeseries import Sample3Phase
 from .... import _data_pipeline, connection_manager
 from ..._component_pool_status_tracker import ComponentPoolStatusTracker
 from ..._component_status import ComponentPoolStatus, EVChargerStatusTracker

src/frequenz/sdk/microgrid/_power_distributing/_component_managers/_ev_charger_manager/_states.py

@@ -9,8 +9,7 @@
 from typing import Iterable
 
 from frequenz.client.microgrid import EVChargerData
-
-from .....timeseries import Power
+from frequenz.quantities import Power
 
 
 @dataclass

src/frequenz/sdk/microgrid/_power_distributing/_component_managers/_pv_inverter_manager/_pv_inverter_manager.py

@@ -15,10 +15,10 @@
     InverterData,
     InverterType,
 )
+from frequenz.quantities import Power
 from typing_extensions import override
 
 from ....._internal._math import is_close_to_zero
-from .....timeseries import Power
 from .... import connection_manager
 from ..._component_pool_status_tracker import ComponentPoolStatusTracker
 from ..._component_status import ComponentPoolStatus, PVInverterStatusTracker

src/frequenz/sdk/microgrid/_power_distributing/request.py

@@ -6,7 +6,7 @@
 import dataclasses
 from collections import abc
 
-from ...timeseries._quantities import Power
+from frequenz.quantities import Power
 
 
 @dataclasses.dataclass

src/frequenz/sdk/microgrid/_power_distributing/result.py

@@ -7,7 +7,7 @@
 import dataclasses
 from collections import abc
 
-from frequenz.sdk.timeseries._quantities import Power
+from frequenz.quantities import Power
 
 from .request import Request
 
@@ -117,7 +117,7 @@ class OutOfBounds(_BaseResultMixin):
     )
     from frequenz.sdk.actor.power_distributing.request import Request
     from frequenz.sdk.actor.power_distributing.result import PowerBounds
-    from frequenz.sdk.timeseries._quantities import Power
+    from frequenz.quantities import Power
 
     def handle_power_request_result(result: Result) -> None:
         match result:

src/frequenz/sdk/microgrid/_power_managing/_base_classes.py

@@ -10,8 +10,9 @@
 import enum
 import typing
 
+from frequenz.quantities import Power
+
 from ... import timeseries
-from ...timeseries import Power
 from . import _bounds
 
 if typing.TYPE_CHECKING:

src/frequenz/sdk/microgrid/_power_managing/_bounds.py

@@ -3,7 +3,9 @@
 
 """Utilities for checking and clamping bounds and power values to exclusion bounds."""
 
-from ...timeseries import Bounds, Power
+from frequenz.quantities import Power
+
+from ...timeseries import Bounds
 
 
 def check_exclusion_bounds_overlap(

src/frequenz/sdk/microgrid/_power_managing/_matryoshka.py

@@ -23,10 +23,10 @@
 import typing
 from datetime import timedelta
 
+from frequenz.quantities import Power
 from typing_extensions import override
 
 from ... import timeseries
-from ...timeseries import Power
 from . import _bounds
 from ._base_classes import BaseAlgorithm, Proposal, _Report
 

src/frequenz/sdk/microgrid/_power_managing/_power_managing_actor.py

@@ -13,12 +13,12 @@
 from frequenz.channels import Receiver, Sender, select, selected_from
 from frequenz.channels.timer import SkipMissedAndDrift, Timer
 from frequenz.client.microgrid import ComponentCategory, ComponentType, InverterType
+from frequenz.quantities import Power
 from typing_extensions import override
 
 from ..._internal._asyncio import run_forever
 from ..._internal._channels import ChannelRegistry
 from ...actor import Actor
-from ...timeseries import Power
 from ...timeseries._base_types import Bounds, SystemBounds
 from .. import _data_pipeline, _power_distributing
 from ._base_classes import Algorithm, BaseAlgorithm, Proposal, ReportRequest, _Report

src/frequenz/sdk/microgrid/_resampling.py

@@ -9,12 +9,12 @@
 import logging
 
 from frequenz.channels import Receiver, Sender
+from frequenz.quantities import Quantity
 
 from .._internal._asyncio import cancel_and_await
 from .._internal._channels import ChannelRegistry
 from ..actor import Actor
 from ..timeseries import Sample
-from ..timeseries._quantities import Quantity
 from ..timeseries._resampling import Resampler, ResamplerConfig, ResamplingError
 from ._data_sourcing import ComponentMetricRequest
 

src/frequenz/sdk/timeseries/__init__.py

@@ -40,16 +40,6 @@
 from ._fuse import Fuse
 from ._moving_window import MovingWindow
 from ._periodic_feature_extractor import PeriodicFeatureExtractor
-from ._quantities import (
-    Current,
-    Energy,
-    Frequency,
-    Percentage,
-    Power,
-    Quantity,
-    Temperature,
-    Voltage,
-)
 from ._resampling import ResamplerConfig
 
 __all__ = [
@@ -62,15 +52,4 @@
     "Sample",
     "Sample3Phase",
     "UNIX_EPOCH",
-    #
-    # Quantities
-    #
-    "Quantity",
-    "Current",
-    "Energy",
-    "Power",
-    "Temperature",
-    "Voltage",
-    "Frequency",
-    "Percentage",
 ]

src/frequenz/sdk/timeseries/_base_types.py

@@ -10,11 +10,14 @@
 from datetime import datetime, timezone
 from typing import Any, Generic, Protocol, Self, TypeVar, cast, overload
 
-from ._quantities import Power, QuantityT
+from frequenz.quantities import Power, Quantity
 
 UNIX_EPOCH = datetime.fromtimestamp(0.0, tz=timezone.utc)
 """The UNIX epoch (in UTC)."""
 
+QuantityT = TypeVar("QuantityT", bound=Quantity)
+"""Type variable for representing various quantity types."""
+
 
 @dataclass(frozen=True, order=True)
 class Sample(Generic[QuantityT]):

src/frequenz/sdk/timeseries/_fuse.py

@@ -5,11 +5,8 @@
 from __future__ import annotations
 
 from dataclasses import dataclass
-from typing import TYPE_CHECKING
 
-if TYPE_CHECKING:
-    # Break circular import
-    from . import Current
+from frequenz.quantities import Current
 
 
 @dataclass(frozen=True)

src/frequenz/sdk/timeseries/_grid_frequency.py

@@ -10,12 +10,12 @@
 
 from frequenz.channels import Receiver, Sender
 from frequenz.client.microgrid import Component, ComponentCategory, ComponentMetricId
+from frequenz.quantities import Frequency, Quantity
 
 from .._internal._channels import ChannelRegistry
 from ..microgrid import connection_manager
 from ..microgrid._data_sourcing import ComponentMetricRequest
 from ..timeseries._base_types import Sample
-from ..timeseries._quantities import Frequency, Quantity
 
 _logger = logging.getLogger(__name__)
 

src/frequenz/sdk/timeseries/_moving_window.py

@@ -13,11 +13,11 @@
 
 import numpy as np
 from frequenz.channels import Broadcast, Receiver, Sender
+from frequenz.quantities import Quantity
 from numpy.typing import ArrayLike
 
 from ..actor._background_service import BackgroundService
 from ._base_types import UNIX_EPOCH, Sample
-from ._quantities import Quantity
 from ._resampling import Resampler, ResamplerConfig
 from ._ringbuffer import OrderedRingBuffer