Document class and module attributes

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

Signed-off-by: Daniel Zullo <[email protected]>

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/_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]]

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

@@ -78,15 +78,21 @@ 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)."""
 
     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
+        """Last blocking duration (in seconds)."""  # pylint: disable=pointless-string-statement
+
         self.blocked_until: Optional[datetime] = None
+        """Until when battery is blocked."""  # pylint: disable=pointless-string-statement
 
     def block(self) -> float:
         """Block battery.
@@ -147,21 +153,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:

src/frequenz/sdk/microgrid/client/_client.py

@@ -42,8 +42,8 @@
 from ._connection import Connection
 from ._retry import LinearBackoff, RetryStrategy
 
-# Default timeout applied to all gRPC calls
 DEFAULT_GRPC_CALL_TIMEOUT = 60.0
+"""The default timeout for gRPC calls made by this client (in seconds)."""
 
 # A generic type for representing various component data types, used in the
 # generic function `MicrogridGrpcClient._component_data_task` that fetches
@@ -55,6 +55,7 @@
     InverterData,
     EVChargerData,
 )
+"""Type variable for representing various component data types."""
 
 _logger = logging.getLogger(__name__)
 
@@ -215,7 +216,11 @@ def __init__(
                 method gets lost.
         """
         self.target = target
+        """The location (as "host:port") of the microgrid API gRPC server."""
+
         self.api = MicrogridStub(grpc_channel)
+        """The gRPC stub for the microgrid API."""
+
         self._component_streams: Dict[int, Broadcast[Any]] = {}
         self._streaming_tasks: Dict[int, asyncio.Task[None]] = {}
         self._retry_spec = retry_spec

src/frequenz/sdk/microgrid/client/_connection.py

@@ -10,7 +10,10 @@ class Connection(NamedTuple):
     """Metadata for a connection between microgrid components."""
 
     start: int
+    """The component ID that represents the start component of the connection."""
+
     end: int
+    """The component ID that represents the end component of the connection."""
 
     def is_valid(self) -> bool:
         """Check if this instance contains valid data.