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

.github/labeler.yml

@@ -6,7 +6,7 @@
 # For more details on the configuration please see:
 # https://github.com/marketplace/actions/labeler
 
-"part:docs": 
+"part:docs":
   - "**/*.md"
   - "docs/**"
   - "examples/**"
@@ -31,14 +31,16 @@
   - noxfile.py
 
 "part:channels":
-  - any:
-      - "src/frequenz/channels/**"
-      - "!src/frequenz/channels/util/**"
+  - "src/frequenz/channels/anycast.py"
+  - "src/frequenz/channels/bidirectional.py"
+  - "src/frequenz/channels/broadcast.py"
 
 "part:receivers":
-  - any:
-      - "src/frequenz/channels/util/**"
-      - "!src/frequenz/channels/util/_select.py"
+  - "src/frequenz/channels/event.py"
+  - "src/frequenz/channels/file_watcher.py"
+  - "src/frequenz/channels/merge.py"
+  - "src/frequenz/channels/merge_named.py"
+  - "src/frequenz/channels/timer.py"
 
 "part:select":
-  - "src/frequenz/channels/util/_select.py"
+  - "src/frequenz/channels/_select.py"

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

@@ -6,80 +6,50 @@
 This package contains
 [channel](https://en.wikipedia.org/wiki/Channel_(programming)) implementations.
 
-Channels:
-
-* [Anycast][frequenz.channels.Anycast]: A channel that supports multiple
-  senders and multiple receivers.  A message sent through a sender will be
-  received by exactly one receiver.
-
-* [Bidirectional][frequenz.channels.Bidirectional]: A channel providing
-  a `client` and a `service` handle to send and receive bidirectionally.
-
-* [Broadcast][frequenz.channels.Broadcast]: A channel to broadcast messages
-  from multiple senders to multiple receivers. Each message sent through any of
-  the senders is received by all of the receivers.
-
-Other base classes:
-
-* [Peekable][frequenz.channels.Peekable]: An object to allow users to get
-  a peek at the latest value in the channel, without consuming anything.
-
-* [Receiver][frequenz.channels.Receiver]: An object that can wait for and
-  consume messages from a channel.
+Main base classes and functions:
 
 * [Sender][frequenz.channels.Sender]: An object that can send messages to
   a channel.
 
-Utilities:
-
-* [util][frequenz.channels.util]: A module with utilities, like special
-  receivers that implement timers, file watchers, merge receivers, or wait for
-  messages in multiple channels.
-
-Exception classes:
-
-* [Error][frequenz.channels.Error]: Base class for all errors in this
-  library.
-
-* [ChannelError][frequenz.channels.ChannelError]: Base class for all errors
-  related to channels.
+* [Receiver][frequenz.channels.Receiver]: An object that can wait for and
+  consume messages from a channel.
 
-* [ChannelClosedError][frequenz.channels.ChannelClosedError]: Error raised when
-  trying to operate (send, receive, etc.) through a closed channel.
+* [selected()][frequenz.channels.select]: A function to wait on multiple
+  receivers at once.
 
-* [SenderError][frequenz.channels.SenderError]: Base class for all errors
-  related to senders.
+Channels:
 
-* [ReceiverError][frequenz.channels.ReceiverError]: Base class for all errors
-  related to receivers.
+* [Anycast][frequenz.channels.anycast.Anycast]: A channel that supports multiple
+  senders and multiple receivers.  A message sent through a sender will be
+  received by exactly one receiver.
 
-* [ReceiverStoppedError][frequenz.channels.ReceiverStoppedError]: A receiver
-  stopped producing messages.
+* [Bidirectional][frequenz.channels.bidirectional.Bidirectional]: A channel providing
+  a `client` and a `service` handle to send and receive bidirectionally.
 
-* [ReceiverInvalidatedError][frequenz.channels.ReceiverInvalidatedError]:
-  A receiver is not longer valid (for example if it was converted into
-  a peekable.
+* [Broadcast][frequenz.channels.broadcast.Broadcast]: A channel to broadcast messages
+  from multiple senders to multiple receivers. Each message sent through any of
+  the senders is received by all of the receivers.
 """
 
-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 +58,12 @@
     "ReceiverError",
     "ReceiverInvalidatedError",
     "ReceiverStoppedError",
+    "SelectError",
+    "SelectErrorGroup",
+    "Selected",
     "Sender",
     "SenderError",
-    "util",
+    "UnhandledSelectedError",
+    "select",
+    "selected_from",
 ]