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/channels/_anycast.py

@@ -68,18 +68,42 @@ def __init__(self, maxsize: int = 10) -> None:
             maxsize: Size of the channel's buffer.
         """
         self.limit: int = maxsize
+        """The maximum number of values that can be stored in the channel's buffer.
+
+        If the length of channel's buffer reaches the limit, then the sender
+        blocks at the [send()][frequenz.channels.Sender.send] method until
+        a value is consumed.
+        """
+
         self.deque: Deque[T] = deque(maxlen=maxsize)
+        """The channel's buffer."""
+
         self.send_cv: Condition = Condition()
+        """The condition to wait for free space in the channel's buffer.
+
+        If the channel's buffer is full, then the sender waits for values to
+        get consumed using this condition until there's some free space
+        available in the channel's buffer.
+        """
+
         self.recv_cv: Condition = Condition()
+        """The condition to wait for values in the channel's buffer.
+
+        If the channel's buffer is empty, then the receiver waits for values
+        using this condition until there's a value available in the channel's
+        buffer.
+        """
+
         self.closed: bool = False
+        """Whether the channel is closed."""
 
     async def close(self) -> None:
         """Close the channel.
 
         Any further attempts to [send()][frequenz.channels.Sender.send] data
         will return `False`.
 
-        Receivers will still be able to drain the pending items on the channel,
+        Receivers will still be able to drain the pending values on the channel,
         but after that, subsequent
         [receive()][frequenz.channels.Receiver.receive] calls will return `None`
         immediately.
@@ -122,6 +146,7 @@ def __init__(self, chan: Anycast[T]) -> None:
             chan: A reference to the channel that this sender belongs to.
         """
         self._chan = chan
+        """The channel that this sender belongs to."""
 
     async def send(self, msg: T) -> None:
         """Send a message across the channel.
@@ -169,6 +194,8 @@ def __init__(self, chan: Anycast[T]) -> None:
             chan: A reference to the channel that this receiver belongs to.
         """
         self._chan = chan
+        """The channel that this receiver belongs to."""
+
         self._next: T | type[_Empty] = _Empty
 
     async def ready(self) -> bool:

src/frequenz/channels/_base_classes.py

@@ -1,7 +1,7 @@
 # License: MIT
 # Copyright © 2022 Frequenz Energy-as-a-Service GmbH
 
-"""Baseclasses for Channel Sender and Receiver."""
+"""Base classes for Channel Sender and Receiver."""
 
 from __future__ import annotations
 
@@ -169,11 +169,13 @@ def __init__(self, recv: Receiver[T], transform: Callable[[T], U]) -> None:
 
         Args:
             recv: The input receiver.
-            transform: The function to run on the input
-                data.
+            transform: The function to run on the input data.
         """
         self._recv = recv
+        """The input receiver."""
+
         self._transform = transform
+        """The function to run on the input data."""
 
     async def ready(self) -> bool:
         """Wait until the receiver is ready with a value or an error.

src/frequenz/channels/_bidirectional.py

@@ -38,8 +38,13 @@ def __init__(
                 receiver: A receiver to receive values from.
             """
             self._chan = channel
+            """The underlying channel."""
+
             self._sender = sender
+            """The sender to send values with."""
+
             self._receiver = receiver
+            """The receiver to receive values from."""
 
         async def send(self, msg: V) -> None:
             """Send a value to the other side.
@@ -117,21 +122,29 @@ def __init__(self, client_id: str, service_id: str) -> None:
             service_id: A name for the service end of the channels.
         """
         self._client_id = client_id
+        """The name for the client, used to name the channels."""
+
         self._request_channel: Broadcast[T] = Broadcast(f"req_{service_id}_{client_id}")
+        """The channel to send requests."""
+
         self._response_channel: Broadcast[U] = Broadcast(
             f"resp_{service_id}_{client_id}"
         )
+        """The channel to send responses."""
 
         self._client_handle = Bidirectional.Handle(
             self,
             self._request_channel.new_sender(),
             self._response_channel.new_receiver(),
         )
+        """The handle for the client side to send/receive values."""
+
         self._service_handle = Bidirectional.Handle(
             self,
             self._response_channel.new_sender(),
             self._request_channel.new_receiver(),
         )
+        """The handle for the service side to send/receive values."""
 
     @property
     def client_handle(self) -> Bidirectional.Handle[T, U]:

src/frequenz/channels/_broadcast.py

@@ -85,12 +85,25 @@ def __init__(self, name: str, resend_latest: bool = False) -> None:
                 to wait for the next message on the channel to arrive.
         """
         self.name: str = name
+        """The name of the broadcast channel.
+
+        Only used for debugging purposes.
+        """
+
         self._resend_latest = resend_latest
+        """Whether to resend the latest value to new receivers."""
 
         self.recv_cv: Condition = Condition()
+        """The condition to wait for data in the channel's buffer."""
+
         self.receivers: dict[UUID, weakref.ReferenceType[Receiver[T]]] = {}
+        """The receivers attached to the channel, indexed by their UUID."""
+
         self.closed: bool = False
+        """Whether the channel is closed."""
+
         self._latest: T | None = None
+        """The latest value sent to the channel."""
 
     async def close(self) -> None:
         """Close the Broadcast channel.
@@ -167,6 +180,7 @@ def __init__(self, chan: Broadcast[T]) -> None:
             chan: A reference to the broadcast channel this sender belongs to.
         """
         self._chan = chan
+        """The broadcast channel this sender belongs to."""
 
     async def send(self, msg: T) -> None:
         """Send a message to all broadcast receivers.
@@ -222,11 +236,26 @@ def __init__(self, uuid: UUID, name: str, maxsize: int, chan: Broadcast[T]) -> N
                 belongs to.
         """
         self._uuid = uuid
+        """The UUID to identify the receiver in the broadcast channel's list of receivers."""
+
         self._name = name
+        """The name to identify the receiver.
+
+        Only used for debugging purposes.
+        """
+
         self._chan = chan
+        """The broadcast channel that this receiver belongs to."""
+
         self._q: Deque[T] = deque(maxlen=maxsize)
+        """The receiver's internal message queue."""
 
         self._active = True
+        """Whether the receiver is still active.
+
+        If this receiver is converted into a Peekable, it will neither be
+        considered valid nor active.
+        """
 
     def enqueue(self, msg: T) -> None:
         """Put a message into this receiver's queue.
@@ -343,6 +372,7 @@ def __init__(self, chan: Broadcast[T]) -> None:
             chan: The broadcast channel this Peekable will try to peek into.
         """
         self._chan = chan
+        """The broadcast channel this Peekable will try to peek into."""
 
     def peek(self) -> T | None:
         """Return the latest value that was sent to the channel.

src/frequenz/channels/_exceptions.py

@@ -43,6 +43,7 @@ def __init__(self, message: Any, channel: Any):
         """
         super().__init__(message)
         self.channel: Any = channel
+        """The channel where the error happened."""
 
 
 class ChannelClosedError(ChannelError):
@@ -73,6 +74,7 @@ def __init__(self, message: Any, sender: _base_classes.Sender[T]):
         """
         super().__init__(message)
         self.sender: _base_classes.Sender[T] = sender
+        """The sender where the error happened."""
 
 
 class ReceiverError(Error, Generic[T]):
@@ -91,6 +93,7 @@ def __init__(self, message: Any, receiver: _base_classes.Receiver[T]):
         """
         super().__init__(message)
         self.receiver: _base_classes.Receiver[T] = receiver
+        """The receiver where the error happened."""
 
 
 class ReceiverStoppedError(ReceiverError[T]):

src/frequenz/channels/util/_file_watcher.py

@@ -1,7 +1,7 @@
 # License: MIT
 # Copyright © 2022 Frequenz Energy-as-a-Service GmbH
 
-"""A Channel receiver for watching for new (or modified) files."""
+"""A Channel receiver for watching for new, modified or deleted files."""
 
 from __future__ import annotations
 
@@ -55,6 +55,8 @@ def __init__(
                 all event types.
         """
         self.event_types: frozenset[FileWatcher.EventType] = frozenset(event_types)
+        """The types of events to watch for."""
+
         self._stop_event = asyncio.Event()
         self._paths = [
             path if isinstance(path, pathlib.Path) else pathlib.Path(path)

src/frequenz/channels/util/_merge_named.py

@@ -25,11 +25,16 @@ def __init__(self, **kwargs: Receiver[T]) -> None:
             **kwargs: sequence of channel receivers.
         """
         self._receivers = kwargs
+        """The sequence of channel receivers to get the messages to merge."""
+
         self._pending: set[asyncio.Task[Any]] = {
             asyncio.create_task(recv.__anext__(), name=name)
             for name, recv in self._receivers.items()
         }
+        """The set of pending tasks to merge messages."""
+
         self._results: Deque[tuple[str, T]] = deque(maxlen=len(self._receivers))
+        """The internal buffer of merged messages."""
 
     def __del__(self) -> None:
         """Cleanup any pending tasks."""

src/frequenz/channels/util/_select.py

@@ -192,6 +192,7 @@ def __init__(self, selected: Selected[_T]) -> None:
         recv = selected._recv  # pylint: disable=protected-access
         super().__init__(f"Selected receiver {recv} was not handled in the if-chain")
         self.selected = selected
+        """The selected receiver that was not handled."""
 
 
 class SelectErrorGroup(BaseExceptionGroup[BaseException], SelectError):

tests/utils/test_file_watcher.py

@@ -29,6 +29,7 @@ def __init__(self, changes: Sequence[FileChange] = ()) -> None:
                 function.
         """
         self.changes: Sequence[FileChange] = changes
+        """The sequence of file changes."""
 
     async def fake_awatch(
         self, *paths: str, **kwargs: Any  # pylint: disable=unused-argument