RFC: Revamp the repository modules structure

These are the most notable changes:

- The `_base_classes` modules is split into the `_receiver` and
  `_sender` modules.

- Sender and receiver exceptions are moved from the `_exceptions` module
  to the new `_sender` and `_receiver` modules.

- The `frequenz.channel` package now only exposes the new `_receiver`
  and `_sender` modules, and the `_exceptions` and `_select` modules.

- All channels and receiver modules are moved to the `frequenz.channels`
  package and made public.

- All public nested classes were moved to the top level of the
  corresponding module.

Advantages of this structure:

- It completely removes circular dependencies.

- It avoids importing unnecessary code. In Python importing means code
  execution, so even when it is done only at startup, it adds some
  overhead.

  Also by not importing unnecessary code, we can potentially add real
  optional dependencies. For example, if a project doesn't need to use
  a file watcher, they could avoid pulling the unnecessary `awatch`
  dependency. This is not done in this PR, but it could be done in the
  future.

- By having the channels and receivers on their own module we can move
  public nested classes were moved to the top level of the corresponding
  module withough having to add superflous prefixes for support classes.

- Removing nested classes avoids having to use hacky constructions, like
  requiring the use of `from __future__ import annotations`, types as
  strings (nested classes) and confusing the `mkdocstrings` tools when
  extracting and cross-linking docs.

- The `frequenz.channels` package exposes all classes that are used once
  you have setted up your channels, so the importing should still be
  pretty terse in most cases and only `frequenz.channels` would need to
  be imported in modules only taking some receivers and iterating or
  selecting over them.

Signed-off-by: Leandro Lucarella <[email protected]>

Author: llucax

benchmarks/benchmark_anycast.py

@@ -9,7 +9,8 @@
 from collections.abc import Coroutine
 from typing import Any
 
-from frequenz.channels import Anycast, Receiver, Sender
+from frequenz.channels import Receiver, Sender
+from frequenz.channels.anycast import Anycast
 
 
 async def send_msg(num_messages: int, chan: Sender[int]) -> None:

benchmarks/benchmark_broadcast.py

@@ -10,7 +10,8 @@
 from functools import partial
 from typing import Any
 
-from frequenz.channels import Broadcast, Receiver, Sender
+from frequenz.channels import Receiver, Sender
+from frequenz.channels.broadcast import Broadcast
 
 
 async def component_sender(num_messages: int, chan: Sender[int]) -> None:

src/frequenz/channels/__init__.py

@@ -61,25 +61,25 @@
   a peekable.
 """
 
-from . import util
-from ._anycast import Anycast
-from ._base_classes import Peekable, Receiver, Sender
-from ._bidirectional import Bidirectional
-from ._broadcast import Broadcast
-from ._exceptions import (
-    ChannelClosedError,
-    ChannelError,
-    Error,
+from ._exceptions import ChannelClosedError, ChannelError, Error
+from ._receiver import (
+    Peekable,
+    Receiver,
     ReceiverError,
     ReceiverInvalidatedError,
     ReceiverStoppedError,
-    SenderError,
 )
+from ._select import (
+    Selected,
+    SelectError,
+    SelectErrorGroup,
+    UnhandledSelectedError,
+    select,
+    selected_from,
+)
+from ._sender import Sender, SenderError
 
 __all__ = [
-    "Anycast",
-    "Bidirectional",
-    "Broadcast",
     "ChannelClosedError",
     "ChannelError",
     "Error",
@@ -88,7 +88,12 @@
     "ReceiverError",
     "ReceiverInvalidatedError",
     "ReceiverStoppedError",
+    "SelectError",
+    "SelectErrorGroup",
+    "Selected",
     "Sender",
     "SenderError",
-    "util",
+    "UnhandledSelectedError",
+    "select",
+    "selected_from",
 ]

src/frequenz/channels/_bidirectional.py

@@ -3,14 +3,7 @@
 
 """Exception classes."""
 
-from __future__ import annotations
-
-from typing import TYPE_CHECKING, Any, Generic, TypeVar
-
-if TYPE_CHECKING:
-    from . import _base_classes
-
-T = TypeVar("T")
+from typing import Any
 
 
 class Error(RuntimeError):
@@ -56,63 +49,3 @@ def __init__(self, channel: Any):
             channel: A reference to the channel that was closed.
         """
         super().__init__(f"Channel {channel} was closed", channel)
-
-
-class SenderError(Error, Generic[T]):
-    """An error produced in a [Sender][frequenz.channels.Sender].
-
-    All exceptions generated by senders inherit from this exception.
-    """
-
-    def __init__(self, message: str, sender: _base_classes.Sender[T]):
-        """Create an instance.
-
-        Args:
-            message: An error message.
-            sender: The [Sender][frequenz.channels.Sender] where the error
-                happened.
-        """
-        super().__init__(message)
-        self.sender: _base_classes.Sender[T] = sender
-        """The sender where the error happened."""
-
-
-class ReceiverError(Error, Generic[T]):
-    """An error produced in a [Receiver][frequenz.channels.Receiver].
-
-    All exceptions generated by receivers inherit from this exception.
-    """
-
-    def __init__(self, message: str, receiver: _base_classes.Receiver[T]):
-        """Create an instance.
-
-        Args:
-            message: An error message.
-            receiver: The [Receiver][frequenz.channels.Receiver] where the
-                error happened.
-        """
-        super().__init__(message)
-        self.receiver: _base_classes.Receiver[T] = receiver
-        """The receiver where the error happened."""
-
-
-class ReceiverStoppedError(ReceiverError[T]):
-    """The [Receiver][frequenz.channels.Receiver] stopped producing messages."""
-
-    def __init__(self, receiver: _base_classes.Receiver[T]):
-        """Create an instance.
-
-        Args:
-            receiver: The [Receiver][frequenz.channels.Receiver] where the
-                error happened.
-        """
-        super().__init__(f"Receiver {receiver} was stopped", receiver)
-
-
-class ReceiverInvalidatedError(ReceiverError[T]):
-    """The [Receiver][frequenz.channels.Receiver] was invalidated.
-
-    This happens when the Receiver is converted
-    [into][frequenz.channels.Receiver.into_peekable]
-    a [Peekable][frequenz.channels.Peekable].
-    """