Document class and module attributes (#618)

Add or amend docstrings for all classes and modules where needed.

Fixes #74

Author: daniel-zullo-frequenz

src/frequenz/sdk/_api_client/api_client.py

@@ -11,8 +11,13 @@ class ApiProtocol(Enum):
     """Enumerated values of supported API types."""
 
     GRPC = 1
+    """gRPC API."""
+
     REST = 2
+    """REST API."""
+
     FILESYSTEM = 3
+    """Filesystem API."""
 
 
 class ApiClient(ABC):

src/frequenz/sdk/_internal/_asyncio.py

@@ -15,7 +15,7 @@ async def cancel_and_await(task: asyncio.Task[Any]) -> None:
 
     Exits immediately if the task is already done.
 
-    The `CancelledError` is suppresed, but any other exception will be propagated.
+    The `CancelledError` is suppressed, but any other exception will be propagated.
 
     Args:
         task: The task to be cancelled and waited for.

src/frequenz/sdk/_internal/_singleton_meta.py

@@ -11,7 +11,14 @@ class SingletonMeta(type):
     """This is a thread-safe implementation of Singleton."""
 
     _instances: Dict[Any, type] = {}
+    """The dictionary of instances of the singleton classes."""
+
     _lock: Lock = Lock()
+    """The lock to ensure thread safety.
+
+    The lock to acquire when creating a singleton instance, preventing
+    multiple threads from creating instances simultaneously.
+    """
 
     def __call__(cls, *args: Any, **kwargs: Any) -> type:
         """Overload function call operator to return the singleton instance.

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

@@ -141,8 +141,13 @@ def __init__(
                 instance.
         """
         self._comp_categories_cache: Dict[int, ComponentCategory] = {}
+
         self.comp_data_receivers: Dict[int, Receiver[Any]] = {}
+        """The dictionary of component IDs to data receivers."""
+
         self.comp_data_tasks: Dict[int, asyncio.Task[None]] = {}
+        """The dictionary of component IDs to asyncio tasks."""
+
         self._registry = registry
         self._req_streaming_metrics: Dict[
             int, Dict[ComponentMetricId, List[ComponentMetricRequest]]
@@ -343,10 +348,10 @@ def _get_metric_senders(
                 self._get_data_extraction_method(category, metric),
                 [
                     self._registry.new_sender(request.get_channel_name())
-                    for request in reqlist
+                    for request in req_list
                 ],
             )
-            for (metric, reqlist) in requests.items()
+            for (metric, req_list) in requests.items()
         ]
 
     async def _handle_data_stream(

src/frequenz/sdk/actor/_resampling.py

@@ -43,7 +43,7 @@ def __init__(  # pylint: disable=too-many-arguments
                 the [`DataSourcingActor`][frequenz.sdk.actor.DataSourcingActor]
                 to subscribe to component metrics.
             resampling_request_receiver: The receiver to use to receive new
-                resampmling subscription requests.
+                resampling subscription requests.
             config: The configuration for the resampler.
             name: The name of the actor. If `None`, `str(id(self))` will be used. This
                 is used mostly for debugging purposes.

src/frequenz/sdk/actor/power_distributing/_battery_status.py

@@ -10,7 +10,7 @@
 from dataclasses import dataclass
 from datetime import datetime, timedelta, timezone
 from enum import Enum
-from typing import Iterable, Optional, Set, TypeVar, Union
+from typing import Iterable, Optional, Set, Union
 
 # pylint: disable=no-name-in-module
 from frequenz.api.microgrid.battery_pb2 import ComponentState as BatteryComponentState
@@ -60,9 +60,6 @@ class SetPowerResult:
     """Set of the batteries that failed."""
 
 
-T = TypeVar("T")
-
-
 @dataclass
 class _ComponentStreamStatus:
     component_id: int
@@ -81,15 +78,23 @@ class _ComponentStreamStatus:
 @dataclass
 class _BlockingStatus:
     min_duration_sec: float
+    """The minimum blocking duration (in seconds)."""
+
     max_duration_sec: float
+    """The maximum blocking duration (in seconds)."""
+
+    last_blocking_duration_sec: float = 0.0
+    """Last blocking duration (in seconds)."""
+
+    blocked_until: datetime | None = None
+    """Until when the battery is blocked."""
 
     def __post_init__(self) -> None:
         assert self.min_duration_sec <= self.max_duration_sec, (
             f"Minimum blocking duration ({self.min_duration_sec}) cannot be greater "
             f"than maximum blocking duration ({self.max_duration_sec})"
         )
-        self.last_blocking_duration_sec: float = self.min_duration_sec
-        self.blocked_until: Optional[datetime] = None
+        self.last_blocking_duration_sec = self.min_duration_sec
 
     def block(self) -> float:
         """Block battery.
@@ -150,21 +155,34 @@ class BatteryStatusTracker:
     Status updates are sent out only when there is a status change.
     """
 
-    # Class attributes
     _battery_valid_relay: Set[BatteryRelayState.ValueType] = {
         BatteryRelayState.RELAY_STATE_CLOSED
     }
+    """The list of valid relay states of a battery.
+
+    A working battery in any other battery relay state will be reported as failing.
+    """
+
     _battery_valid_state: Set[BatteryComponentState.ValueType] = {
         BatteryComponentState.COMPONENT_STATE_IDLE,
         BatteryComponentState.COMPONENT_STATE_CHARGING,
         BatteryComponentState.COMPONENT_STATE_DISCHARGING,
     }
+    """The list of valid states of a battery.
+
+    A working battery in any other battery state will be reported as failing.
+    """
+
     _inverter_valid_state: Set[InverterComponentState.ValueType] = {
         InverterComponentState.COMPONENT_STATE_STANDBY,
         InverterComponentState.COMPONENT_STATE_IDLE,
         InverterComponentState.COMPONENT_STATE_CHARGING,
         InverterComponentState.COMPONENT_STATE_DISCHARGING,
     }
+    """The list of valid states of an inverter.
+
+    A working inverter in any other inverter state will be reported as failing.
+    """
 
     def __init__(  # pylint: disable=too-many-arguments
         self,

src/frequenz/sdk/actor/power_distributing/power_distributing.py

@@ -146,9 +146,16 @@ def __init__(
 
         # NOTE: power_distributor_exponent should be received from ConfigManager
         self.power_distributor_exponent: float = 1.0
+        """The exponent for the power distribution algorithm.
+
+        The exponent determines how fast the batteries should strive to the
+        equal SoC level.
+        """
+
         self.distribution_algorithm = DistributionAlgorithm(
             self.power_distributor_exponent
         )
+        """The distribution algorithm used to distribute power between batteries."""
 
         self._bat_inv_map, self._inv_bat_map = self._get_components_pairs(
             connection_manager.get().component_graph

src/frequenz/sdk/actor/power_distributing/result.py

@@ -84,9 +84,16 @@ class PowerBounds:
     """Inclusion and exclusion power bounds for requested batteries."""
 
     inclusion_lower: float
+    """The lower value of the inclusion power bounds for the requested batteries."""
+
     exclusion_lower: float
+    """The lower value of the exclusion power bounds for the requested batteries."""
+
     exclusion_upper: float
+    """The upper value of the exclusion power bounds for the requested batteries."""
+
     inclusion_upper: float
+    """The upper value of the inclusion power bounds for the requested batteries."""
 
 
 @dataclasses.dataclass

src/frequenz/sdk/config/_config.py

@@ -12,6 +12,7 @@
 _logger = logging.getLogger(__name__)
 
 T = TypeVar("T")
+"""Type variable for validating configuration values."""
 
 
 class Config:

src/frequenz/sdk/microgrid/_data_pipeline.py

@@ -51,14 +51,18 @@
 """
 
 _T = typing.TypeVar("_T")
+"""Type variable for generic actor types."""
 
 
 @dataclass
 class _ActorInfo(typing.Generic[_T]):
     """Holds instances of core data pipeline actors and their request channels."""
 
     actor: _T
+    """The actor instance."""
+
     channel: Broadcast["ComponentMetricRequest"]
+    """The request channel for the actor."""
 
 
 class _DataPipeline: