Cleanup public interface (#78)

Do a cleanup of the public interface, exposing only symbols that are
relevant to the user.

Also hide modules and symbols that are:

* Internal
* Scheduled to be deprecated
* Still with a very unstable interface

Actors are also moved to the `frequenz.sdk.actor` package.

Author: llucax

.github/labeler.yml

@@ -16,8 +16,9 @@
   - "src/frequenz/sdk/_internal/**"
 
 "part:data-pipeline":
-  - "src/frequenz/sdk/data_handling/**"
-  - "src/frequenz/sdk/data_ingestion/**"
+  - "src/frequenz/sdk/_data_handling/**"
+  - "src/frequenz/sdk/_data_ingestion/**"
+  - "src/frequenz/sdk/timeseries/**"
 
 "part:docs": 
   - "**/*.md"
@@ -28,7 +29,7 @@
   - "src/frequenz/sdk/microgrid/**"
 
 "part:power-distribution":
-  - "src/frequenz/sdk/power_distribution/**"
+  - "src/frequenz/sdk/power/**"
 
 "part:tests":
   - "tests/**"

RELEASE_NOTES.md

@@ -9,9 +9,12 @@ https://frequenz-floss.github.io/frequenz-sdk-python/
 For now the documentation is pretty scarce but we will be improving it with
 time.
 
-## Upgrading
+The most prominent changes in this release is the cleanup of the public API,
+which is much more concise and clear now and the addition of classes
+implementing the new data flow design, in particular the `DataSourcingActor`
+and the `ComponentMetricsResamplingActor`.
 
-<!-- Here goes notes on how to upgrade from previous versions, including deprecations and what they should be replaced with -->
+## Upgrading
 
 * `EVChargerData`'s `active_power_consumption` has been renamed to `active_power`
 
@@ -27,14 +30,62 @@ time.
   changes](https://github.com/frequenz-floss/frequenz-channels-python/blob/v0.11.0/RELEASE_NOTES.md#upgrading-breaking-changes)
   you should be aware of.
 
-## New Features
+* The public API has been cleaned up, several symbols were moved or exposed in
+  a single module, and some symbols were hidden because they are either
+  schedule for deprecation or not yet stabilized.
+
+  * `frequenz.sdk.actor`: The `decorator` sub-module was hidden and now the
+    `@actor` decorator is exposed directly only in the main module.
+
+  * `frequenz.sdk.configs`: was renamed to `frequenz.sdk.config`, `Config` is
+    only exposed in the main module and the `ConfigManager` was moved to
+    `frequenz.sdk.actor.ConfigManagingActor`.
+
+  * The modules `frequenz.sdk.data_handling` and `frequenz.sdk.data_ingestion`
+    were hidden from the public interface and will probably be removed in the
+    future. They are still available as `frequenz.sdk._data_handling` and
+    `frequenz.sdk._data_ingestion` for users still needing them.
+
+  * The module `frequenz.sdk.power_distribution` was renamed to
+    `frequenz.sdk.power` and the `PowerDistributor` was moved to
+    `frequenz.sdk.actor.power_distributing.PowerDistributingActor` (with the
+    utility classes `Request` and `Result`).
+
+  * The module `frequenz.sdk.microgrid` was simplified.
+
+    * All component-related symbols (`.component`, `.component_data`,
+      `.component_states`) were moved to the sub-module
+      `frequenz.sdk.microgrid.component`.
 
-<!-- Here goes the main new features and examples or instructions on how to use them -->
+    * All API client-related symbols (`.client`, `.connection`, `.retry`) were
+      moved to the sub-module `frequenz.sdk.microgrid.client`.
+
+    * The `ComponentGraph` is exposed directly in the main module (and only
+      there).
+
+    * The `microgrid_api` module is now exposed via the main module directly
+      (and thus indirectly renamed to `microgrid`, so instead of using `from
+      frequenz.sdk.microgrid import microgrid_api; microgrid_api.initialize()`
+      (for example) you should use `from frequenz.sdk.microgrid import
+      microgridi; microgrid.initialize()`.
+
+    * The `MicrogridApi` class was renamed to `Microgrid` to make it clear it
+      is not exclusively about the API.
+
+    * The `Microgrid.microgrid_api_client` attribute was renamed to
+      `Microgrid.api_client` to avoid the redundancy.
+
+## New Features
 
 * `MeterData` objects now expose the AC `frequency` measured by the meter.
+
 * `BatteryData` objects now expose the temperature of the hottest block in the
   battery as `temperature_max`
 
-## Bug Fixes
+* A new `frequenz.sdk.actor.DataSourcingActor` was added.
+
+* A new `frequenz.sdk.actor.ComponentMetricsResamplingActor` was added.
+
+* A new `frequenz.sdk.actor.ChannelRegistry` was added.
 
-<!-- Here goes notable bug fixes that are worth a special mention or explanation -->
+* A new module `frequenz.sdk.timeseries` was added.

benchmarks/data_ingestion/benchmark_microgrid_data.py

@@ -21,14 +21,18 @@
 from frequenz.channels.util import MergeNamed, Select
 from google.protobuf.timestamp_pb2 import Timestamp  # pylint:disable=no-name-in-module
 
-import frequenz.sdk.microgrid.graph as gr
-from frequenz.sdk.data_handling.time_series import TimeSeriesEntry, TimeSeriesFormula
-from frequenz.sdk.data_ingestion.formula_calculator import FormulaCalculator
-from frequenz.sdk.data_ingestion.microgrid_data import MicrogridData
-from frequenz.sdk.microgrid import BatteryData, InverterData, MeterData
-from frequenz.sdk.microgrid.client import MicrogridGrpcClient
-from frequenz.sdk.microgrid.component import Component, ComponentCategory
-from frequenz.sdk.microgrid.connection import Connection
+import frequenz.sdk.microgrid._graph as gr
+from frequenz.sdk._data_handling.time_series import TimeSeriesEntry, TimeSeriesFormula
+from frequenz.sdk._data_ingestion.formula_calculator import FormulaCalculator
+from frequenz.sdk._data_ingestion.microgrid_data import MicrogridData
+from frequenz.sdk.microgrid.client import Connection, MicrogridGrpcClient
+from frequenz.sdk.microgrid.component import (
+    BatteryData,
+    Component,
+    ComponentCategory,
+    InverterData,
+    MeterData,
+)
 
 
 def gen_market_data(component_id: int) -> MeterData:

benchmarks/power_distribution/power_distributor.py

@@ -13,10 +13,15 @@
 import grpc.aio as grpcaio
 from frequenz.channels import Bidirectional
 
+from frequenz.sdk.actor.power_distributing import (
+    PowerDistributingActor,
+    Request,
+    Result,
+)
+from frequenz.sdk.microgrid import ComponentGraph
+from frequenz.sdk.microgrid._graph import _MicrogridComponentGraph
 from frequenz.sdk.microgrid.client import MicrogridApiClient, MicrogridGrpcClient
 from frequenz.sdk.microgrid.component import Component, ComponentCategory
-from frequenz.sdk.microgrid.graph import ComponentGraph, _MicrogridComponentGraph
-from frequenz.sdk.power_distribution import PowerDistributor, Request, Result
 
 HOST = "157.90.243.180"
 PORT = 61060
@@ -31,7 +36,7 @@ class User:
 
 
 async def run_user(user: User, batteries: Set[int], request_num: int) -> List[Result]:
-    """Send requests to the PowerDistributor and wait for the response.
+    """Send requests to the PowerDistributingActor and wait for the response.
 
     Args:
         user: user that should send request
@@ -42,7 +47,7 @@ async def run_user(user: User, batteries: Set[int], request_num: int) -> List[Re
         SystemError: If the channel was closed.
 
     Returns:
-        List of the results from the PowerDistributor.
+        List of the results from the PowerDistributingActor.
     """
     result: List[Result] = []
     for _ in range(request_num):
@@ -101,7 +106,7 @@ async def run_test(  # pylint: disable=too-many-locals
         users_num: Number of users to register
         requests_per_user: How many request user should send.
         batteries: Set of batteries for each request.
-        distributor: PowerDistributor instance.
+        distributor: PowerDistributingActor instance.
 
     Returns:
         Dictionary with statistics.
@@ -117,7 +122,7 @@ async def run_test(  # pylint: disable=too-many-locals
         user_id: channel.service_handle for user_id, channel in channels.items()
     }
 
-    distributor = PowerDistributor(api, graph, service_channels)
+    distributor = PowerDistributingActor(api, graph, service_channels)
 
     tasks: List[Coroutine[Any, Any, List[Result]]] = []
     for user_id, channel in channels.items():

examples/sdk_resampling_example.py

@@ -8,22 +8,22 @@
 from frequenz.channels import Broadcast
 from frequenz.channels.util import MergeNamed
 
-from frequenz.sdk.actor import ChannelRegistry
-from frequenz.sdk.actor.data_sourcing import DataSourcingActor
-from frequenz.sdk.actor.resampling import (
-    ComponentMetricId,
+from frequenz.sdk import microgrid
+from frequenz.sdk.actor import (
+    ChannelRegistry,
     ComponentMetricRequest,
     ComponentMetricsResamplingActor,
+    DataSourcingActor,
 )
-from frequenz.sdk.microgrid import ComponentCategory, microgrid_api
+from frequenz.sdk.microgrid.component import ComponentCategory, ComponentMetricId
 
 HOST = "microgrid.sandbox.api.frequenz.io"
 PORT = 61060
 
 
-async def run() -> None:
+async def run() -> None:  # pylint: disable=too-many-locals
     """Run main functions that initializes and creates everything."""
-    await microgrid_api.initialize(HOST, PORT)
+    await microgrid.initialize(HOST, PORT)
 
     channel_registry = ChannelRegistry(name="Microgrid Channel Registry")
 
@@ -53,7 +53,7 @@ async def run() -> None:
         resampling_period_s=1.0,
     )
 
-    components = await microgrid_api.get().microgrid_api_client.components()
+    components = await microgrid.get().api_client.components()
     battery_ids = [
         comp.component_id
         for comp in components

examples/sdk_usage_example.py

@@ -4,7 +4,7 @@
 """Frequenz Python SDK usage examples.
 
 This example creates two users.
-One user sends request with power to apply in PowerDistributor.
+One user sends request with power to apply in PowerDistributingActor.
 Second user receives requests and set that power.
 """
 
@@ -18,17 +18,17 @@
 
 from frequenz.channels import Bidirectional, Broadcast, Receiver, Sender
 
+from frequenz.sdk import microgrid
+from frequenz.sdk._data_handling import TimeSeriesEntry
+from frequenz.sdk._data_ingestion import MicrogridData
+from frequenz.sdk._data_ingestion.formula_calculator import FormulaCalculator
 from frequenz.sdk.actor import actor
-from frequenz.sdk.data_handling import TimeSeriesEntry
-from frequenz.sdk.data_ingestion import MicrogridData
-from frequenz.sdk.data_ingestion.formula_calculator import FormulaCalculator
-from frequenz.sdk.microgrid import (
-    Component,
-    ComponentCategory,
-    MicrogridApi,
-    microgrid_api,
+from frequenz.sdk.actor.power_distributing import (
+    PowerDistributingActor,
+    Request,
+    Result,
 )
-from frequenz.sdk.power_distribution import PowerDistributor, Request, Result
+from frequenz.sdk.microgrid.component import Component, ComponentCategory
 
 _logger = logging.getLogger(__name__)
 HOST = "microgrid.sandbox.api.frequenz.io"  # it should be the host name.
@@ -92,11 +92,11 @@ async def run(self) -> None:
                 )
             except asyncio.exceptions.TimeoutError:
                 _logger.error(
-                    "Got timeout error when waiting for response from PowerDistributor"
+                    "Got timeout error when waiting for response from PowerDistributingActor"
                 )
                 continue
             if result is None:
-                raise RuntimeError("PowerDistributor channel has been closed.")
+                raise RuntimeError("PowerDistributingActor channel has been closed.")
             if result.status != Result.Status.SUCCESS:
                 _logger.error(
                     "Could not set %d power. Result: %s", power_to_set, str(result)
@@ -153,10 +153,9 @@ async def run() -> None:
     logging.basicConfig(
         level=logging.DEBUG, format="%(asctime)s %(name)s %(levelname)s:%(message)s"
     )
-    await microgrid_api.initialize(HOST, PORT)
+    await microgrid.initialize(HOST, PORT)
 
     # await initialize(HOST, PORT) # in v0.8.0
-    api: MicrogridApi = microgrid_api.get()
 
     # Create MicrogridData
     microgrid_data_channels = {
@@ -165,11 +164,11 @@ async def run() -> None:
         ),
     }
 
-    formula_calculator = FormulaCalculator(api.component_graph)
+    formula_calculator = FormulaCalculator(microgrid.get().component_graph)
     microgrid_data = MicrogridData(
-        microgrid_client=api.microgrid_api_client,
+        microgrid_client=microgrid.get().api_client,
         # microgrid_client=microgrid_api.microgrid_api,  # in v0.8.0
-        component_graph=api.component_graph,
+        component_graph=microgrid.get().component_graph,
         outputs={
             key: channel.new_sender()
             for key, channel in microgrid_data_channels.items()
@@ -181,14 +180,14 @@ async def run() -> None:
     # Bidirectional channel is used for one sender - one receiver communication
     power_distributor_channels = {
         sending_actor_id: Bidirectional[Request, Result](
-            client_id=sending_actor_id, service_id="PowerDistributor"
+            client_id=sending_actor_id, service_id="PowerDistributingActor"
         )
     }
 
-    power_distributor = PowerDistributor(
-        microgrid_api=api.microgrid_api_client,
+    power_distributor = PowerDistributingActor(
+        microgrid_api=microgrid.get().api_client,
         # microgrid_api=microgrid_api.microgrid_api, in v0.8.0
-        component_graph=api.component_graph,
+        component_graph=microgrid.get().component_graph,
         users_channels={
             key: channel.service_handle
             for key, channel in power_distributor_channels.items()
@@ -200,7 +199,7 @@ async def run() -> None:
 
     # You should get components from ComponentGraph, not from the api.
     # It is faster and and non blocking approach.
-    batteries: Set[Component] = api.component_graph.components(
+    batteries: Set[Component] = microgrid.get().component_graph.components(
         # component_type=set(ComponentType.BATTERY) in v0.8.0
         component_category={ComponentCategory.BATTERY}
     )

src/frequenz/sdk/api_client/__init__.py src/frequenz/sdk/_api_client/__init__.py

@@ -13,7 +13,7 @@
 import numpy as np
 import pandas as pd
 
-from ..data_ingestion.load_historic_data import (
+from .._data_ingestion.load_historic_data import (
     LoadHistoricData,
     LoadHistoricDataSettings,
 )

src/frequenz/sdk/api_client/api_client.py src/frequenz/sdk/_api_client/api_client.py

@@ -7,8 +7,8 @@
 from dataclasses import dataclass
 from typing import Dict, List, Optional, Tuple
 
+from ..microgrid import ComponentGraph
 from ..microgrid.component import ComponentCategory
-from ..microgrid.graph import ComponentGraph
 
 logger = logging.Logger(__name__)
 

src/frequenz/sdk/data_handling/__init__.py src/frequenz/sdk/_data_handling/__init__.py

@@ -11,7 +11,7 @@
 
 import sympy
 
-from ..data_handling.time_series import (
+from .._data_handling.time_series import (
     BatteryField,
     EVChargerField,
     InverterField,
@@ -22,7 +22,8 @@
     TimeSeriesEntry,
     TimeSeriesFormula,
 )
-from ..microgrid import ComponentCategory, ComponentGraph
+from ..microgrid import ComponentGraph
+from ..microgrid.component import ComponentCategory
 from .component_info import infer_microgrid_config
 from .constants import (
     METRIC_BATTERIES_ACTIVE_POWER,

src/frequenz/sdk/data_handling/formula.py src/frequenz/sdk/_data_handling/formula.py

@@ -9,9 +9,9 @@
 from frequenz.channels.util import Merge
 
 from ..microgrid import client
-from ..microgrid.component import ComponentCategory
-from ..microgrid.component_data import (
+from ..microgrid.component import (
     BatteryData,
+    ComponentCategory,
     EVChargerData,
     InverterData,
     MeterData,

src/frequenz/sdk/data_handling/gen_historic_data_features.py src/frequenz/sdk/_data_handling/gen_historic_data_features.py

@@ -18,11 +18,11 @@
 from frequenz.channels import Broadcast, Receiver, Sender
 from frequenz.channels.util import Merge, Select
 
-from ..actor.decorator import actor
-from ..configs import Config
-from ..data_handling.time_series import TimeSeriesEntry
+from .._data_handling.time_series import TimeSeriesEntry
+from ..actor import actor
+from ..config import Config
+from ..microgrid import ComponentGraph
 from ..microgrid.client import MicrogridApiClient
-from ..microgrid.graph import ComponentGraph
 from .component_info import infer_microgrid_config
 from .formula_calculator import FormulaCalculator
 from .gen_component_receivers import gen_component_receivers