Expose public API only in channels and channels.util

llucax · llucax · commit 19591abef5c0 · 2022-11-22T12:29:47.000+01:00
To avoid having a confusing API documentation, we now make all modules
"internal" (use a "_" prefix) except for frequenz.channels (exposing
base classes and channel implementations) and frequenz.channels.util
(exposing utility receivers and Select).

Signed-off-by: Leandro Lucarella &lt;leandro.lucarella@frequenz.com&gt;
diff --git a/.github/labeler.yml b/.github/labeler.yml
@@ -30,11 +30,12 @@
 "part:channels":
   - any:
       - "src/frequenz/channels/**"
-      - "!src/frequenz/channels/select.py"
       - "!src/frequenz/channels/util/**"
 
 "part:receivers":
-  - "src/frequenz/channels/util/**"
+  - any:
+      - "src/frequenz/channels/util/**"
+      - "!src/frequenz/channels/util/_select.py"
 
 "part:select":
-  - "src/frequenz/channels/select.py"
+  - "src/frequenz/channels/util/_select.py"
diff --git a/RELEASE_NOTES.md b/RELEASE_NOTES.md
@@ -18,6 +18,26 @@ time.
   `new_receiver()` and `new_sender()` respectively. This is to make it more
   clear that new objects are being created.
 
+* The public API surface has been reduced considerably to make it more clear
+  where to import symbols.  You should update your imports.  The new symbol
+  locations are:
+
+  * `frequenz.channels.Anycast`
+  * `frequenz.channels.Broadcast`
+  * `frequenz.channels.Anycast`
+  * `frequenz.channels.Bidirectional`
+  * `frequenz.channels.BidirectionalHandle`
+  * `frequenz.channels.Broadcast`
+  * `frequenz.channels.BufferedReceiver`
+  * `frequenz.channels.Peekable`
+  * `frequenz.channels.Receiver`
+  * `frequenz.channels.Sender`
+  * `frequenz.channels.util.Merge`
+  * `frequenz.channels.util.MergeNamed`
+  * `frequenz.channels.util.FileWatcher`
+  * `frequenz.channels.util.Select`
+  * `frequenz.channels.util.Timer`
+
 ## New Features
 
 <!-- Here goes the main new features and examples or instructions on how to use them -->
diff --git a/docs/mkdocstrings_autoapi.py b/docs/mkdocstrings_autoapi.py
@@ -8,12 +8,30 @@
 """
 
 from pathlib import Path
+from typing import Tuple
 
 import mkdocs_gen_files
 
 SRC_PATH = "src"
 DST_PATH = "reference"
 
+
+def is_internal(path_parts: Tuple[str, ...]) -> bool:
+    """Tell if the path is internal judging by the parts.
+
+    Args:
+        path_parts: Path.parts of the path to check.
+
+    Returns:
+        True if the path is internal.
+    """
+
+    def with_underscore_not_init(part: str) -> bool:
+        return part.startswith("_") and part != "__init__"
+
+    return any(p for p in path_parts if with_underscore_not_init(p))
+
+
 # type ignore because mkdocs_gen_files uses a very weird module-level
 # __getattr__() which messes up the type system
 nav = mkdocs_gen_files.Nav()  # type: ignore
@@ -24,15 +42,17 @@
     doc_path = path.relative_to(SRC_PATH).with_suffix(".md")
     full_doc_path = Path(DST_PATH, doc_path)
     parts = tuple(module_path.parts)
+    if is_internal(parts):
+        continue
     if parts[-1] == "__init__":
         doc_path = doc_path.with_name("index.md")
         full_doc_path = full_doc_path.with_name("index.md")
         parts = parts[:-1]
 
     nav[parts] = doc_path.as_posix()
 
-    with mkdocs_gen_files.open(full_doc_path, "w") as fd:
-        fd.write(f"::: {'.'.join(parts)}\n")
+    with mkdocs_gen_files.open(full_doc_path, "w") as output_file:
+        output_file.write(f"::: {'.'.join(parts)}\n")
 
     mkdocs_gen_files.set_edit_path(full_doc_path, Path("..") / path)
 
diff --git a/src/frequenz/channels/__init__.py b/src/frequenz/channels/__init__.py
@@ -3,28 +3,29 @@
 
 """Channel implementations."""
 
-from frequenz.channels.anycast import Anycast
-from frequenz.channels.base_classes import BufferedReceiver, Peekable, Receiver, Sender
-from frequenz.channels.bidirectional import Bidirectional, BidirectionalHandle
-from frequenz.channels.broadcast import Broadcast
-from frequenz.channels.merge import Merge
-from frequenz.channels.merge_named import MergeNamed
-from frequenz.channels.select import Select
-from frequenz.channels.utils.file_watcher import FileWatcher
-from frequenz.channels.utils.timer import Timer
+from . import util
+from ._anycast import Anycast
+from ._base_classes import (
+    BufferedReceiver,
+    ChannelClosedError,
+    ChannelError,
+    Peekable,
+    Receiver,
+    Sender,
+)
+from ._bidirectional import Bidirectional, BidirectionalHandle
+from ._broadcast import Broadcast
 
 __all__ = [
     "Anycast",
     "Bidirectional",
     "BidirectionalHandle",
     "Broadcast",
     "BufferedReceiver",
-    "FileWatcher",
-    "Merge",
-    "MergeNamed",
+    "ChannelClosedError",
+    "ChannelError",
     "Peekable",
     "Receiver",
-    "Select",
     "Sender",
-    "Timer",
+    "util",
 ]
diff --git a/src/frequenz/channels/_anycast.py b/src/frequenz/channels/_anycast.py
@@ -9,10 +9,10 @@
 from collections import deque
 from typing import Deque, Generic, Optional
 
-from frequenz.channels.base_classes import ChannelClosedError
-from frequenz.channels.base_classes import Receiver as BaseReceiver
-from frequenz.channels.base_classes import Sender as BaseSender
-from frequenz.channels.base_classes import T
+from ._base_classes import ChannelClosedError
+from ._base_classes import Receiver as BaseReceiver
+from ._base_classes import Sender as BaseSender
+from ._base_classes import T
 
 
 class Anycast(Generic[T]):
@@ -28,9 +28,9 @@ class Anycast(Generic[T]):
     thread-safe.
 
     When there are multiple channel receivers, they can be awaited
-    simultaneously using [Select][frequenz.channels.Select],
-    [Merge][frequenz.channels.Merge] or
-    [MergeNamed][frequenz.channels.MergeNamed].
+    simultaneously using [Select][frequenz.channels.util.Select],
+    [Merge][frequenz.channels.util.Merge] or
+    [MergeNamed][frequenz.channels.util.MergeNamed].
 
     Example:
         ``` python
diff --git a/src/frequenz/channels/_base_classes.py b/src/frequenz/channels/_base_classes.py
diff --git a/src/frequenz/channels/_bidirectional.py b/src/frequenz/channels/_bidirectional.py
@@ -7,8 +7,8 @@
 
 from typing import Generic
 
-from frequenz.channels.base_classes import Receiver, Sender, T, U
-from frequenz.channels.broadcast import Broadcast
+from ._base_classes import Receiver, Sender, T, U
+from ._broadcast import Broadcast
 
 
 class Bidirectional(Generic[T, U]):
diff --git a/src/frequenz/channels/_broadcast.py b/src/frequenz/channels/_broadcast.py
@@ -12,10 +12,10 @@
 from typing import Deque, Dict, Generic, Optional
 from uuid import UUID, uuid4
 
-from frequenz.channels.base_classes import BufferedReceiver, ChannelClosedError
-from frequenz.channels.base_classes import Peekable as BasePeekable
-from frequenz.channels.base_classes import Sender as BaseSender
-from frequenz.channels.base_classes import T
+from ._base_classes import BufferedReceiver, ChannelClosedError
+from ._base_classes import Peekable as BasePeekable
+from ._base_classes import Sender as BaseSender
+from ._base_classes import T
 
 logger = logging.Logger(__name__)
 
@@ -32,9 +32,9 @@ class Broadcast(Generic[T]):
     are thread-safe.  Because of this, `Broadcast` channels are thread-safe.
 
     When there are multiple channel receivers, they can be awaited
-    simultaneously using [Select][frequenz.channels.Select],
-    [Merge][frequenz.channels.Merge] or
-    [MergeNamed][frequenz.channels.MergeNamed].
+    simultaneously using [Select][frequenz.channels.util.Select],
+    [Merge][frequenz.channels.util.Merge] or
+    [MergeNamed][frequenz.channels.util.MergeNamed].
 
     Example:
         ``` python
diff --git a/src/frequenz/channels/util/__init__.py b/src/frequenz/channels/util/__init__.py
@@ -0,0 +1,18 @@
+# License: MIT
+# Copyright © 2022 Frequenz Energy-as-a-Service GmbH
+
+"""Channel utilities."""
+
+from ._file_watcher import FileWatcher
+from ._merge import Merge
+from ._merge_named import MergeNamed
+from ._select import Select
+from ._timer import Timer
+
+__all__ = [
+    "FileWatcher",
+    "Merge",
+    "MergeNamed",
+    "Select",
+    "Timer",
+]
diff --git a/src/frequenz/channels/util/_file_watcher.py b/src/frequenz/channels/util/_file_watcher.py
@@ -10,7 +10,7 @@
 from watchfiles import Change, awatch
 from watchfiles.main import FileChange
 
-from frequenz.channels.base_classes import ChannelClosedError, Receiver
+from .._base_classes import ChannelClosedError, Receiver
 
 
 class EventType(Enum):
diff --git a/src/frequenz/channels/util/_merge.py b/src/frequenz/channels/util/_merge.py
@@ -7,7 +7,7 @@
 from collections import deque
 from typing import Any, Deque, Set
 
-from frequenz.channels.base_classes import ChannelClosedError, Receiver, T
+from .._base_classes import ChannelClosedError, Receiver, T
 
 
 class Merge(Receiver[T]):
diff --git a/src/frequenz/channels/util/_merge_named.py b/src/frequenz/channels/util/_merge_named.py
@@ -7,7 +7,7 @@
 from collections import deque
 from typing import Any, Deque, Set, Tuple
 
-from frequenz.channels.base_classes import ChannelClosedError, Receiver, T
+from .._base_classes import ChannelClosedError, Receiver, T
 
 
 class MergeNamed(Receiver[Tuple[str, T]]):
diff --git a/src/frequenz/channels/util/_select.py b/src/frequenz/channels/util/_select.py
@@ -13,7 +13,7 @@
 from dataclasses import dataclass
 from typing import Any, Dict, List, Optional, Set, TypeVar
 
-from frequenz.channels.base_classes import ChannelClosedError, Receiver
+from .._base_classes import ChannelClosedError, Receiver
 
 logger = logging.Logger(__name__)
 T = TypeVar("T")
@@ -57,9 +57,9 @@ class Select:
     """Select the next available message from a group of Receivers.
 
     If `Select` was created with more `Receiver` than what are read in
-    the if-chain after each call to [ready()][frequenz.channels.Select.ready],
-    messages coming in the additional receivers are dropped, and
-    a warning message is logged.
+    the if-chain after each call to
+    [ready()][frequenz.channels.util.Select.ready], messages coming in the
+    additional receivers are dropped, and a warning message is logged.
 
     [Receiver][frequenz.channels.Receiver]s also function as `Receiver`.
 
diff --git a/src/frequenz/channels/util/_timer.py b/src/frequenz/channels/util/_timer.py
@@ -7,21 +7,21 @@
 from datetime import datetime, timedelta, timezone
 from typing import Optional
 
-from frequenz.channels.base_classes import ChannelClosedError, Receiver
+from .._base_classes import ChannelClosedError, Receiver
 
 
 class Timer(Receiver[datetime]):
     """A timer receiver that returns the timestamp every `interval` seconds.
 
-    Primarily for use with [Select][frequenz.channels.Select].
+    Primarily for use with [Select][frequenz.channels.util.Select].
 
     The timestamp generated is a timezone-aware datetime using UTC as timezone.
 
     Example:
         When you want something to happen with a fixed period:
 
         ```python
-        timer = channel.Timer(30.0)
+        timer = Timer(30.0)
         select = Select(bat_1 = receiver1, timer = timer)
         while await select.ready():
             if msg := select.bat_1:
@@ -38,7 +38,7 @@ class Timer(Receiver[datetime]):
         certain interval:
 
         ```python
-        timer = channel.Timer(30.0)
+        timer = Timer(30.0)
         select = Select(bat_1 = receiver1, timer = timer)
         while await select.ready():
             timer.reset()
@@ -72,22 +72,22 @@ def stop(self) -> None:
         """Stop the timer.
 
         Once `stop` has been called, all subsequent calls to
-        [receive()][frequenz.channels.Timer.receive] will immediately return
-        `None`.
+        [receive()][frequenz.channels.Receiver.receive] will immediately
+        return `None`.
         """
         self._stopped = True
 
     async def ready(self) -> None:
         """Return the current time (in UTC) once the next tick is due.
 
         Raises:
-            ChannelClosedError: if [stop()][frequenz.channels.Timer.stop] has been
-                called on the timer.
+            ChannelClosedError: if [stop()][frequenz.channels.util.Timer.stop]
+                has been called on the timer.
 
         Returns:
             The time of the next tick in UTC or `None` if
-                [stop()][frequenz.channels.Timer.stop] has been called on the
-                timer.
+                [stop()][frequenz.channels.util.Timer.stop] has been called on
+                the timer.
         """
         # if there are messages waiting to be consumed, return immediately.
         if self._now is not None:
diff --git a/src/frequenz/channels/utils/__init__.py b/src/frequenz/channels/utils/__init__.py
diff --git a/tests/test_anycast.py b/tests/test_anycast.py
@@ -7,8 +7,7 @@
 
 import pytest
 
-from frequenz.channels import Anycast, Receiver, Sender
-from frequenz.channels.base_classes import ChannelClosedError
+from frequenz.channels import Anycast, ChannelClosedError, Receiver, Sender
 
 
 async def test_anycast() -> None:
diff --git a/tests/test_broadcast.py b/tests/test_broadcast.py
@@ -8,8 +8,7 @@
 
 import pytest
 
-from frequenz.channels import Broadcast, Receiver, Sender
-from frequenz.channels.base_classes import ChannelClosedError
+from frequenz.channels import Broadcast, Receiver, Sender, ChannelClosedError
 
 
 async def test_broadcast() -> None:
diff --git a/tests/test_merge.py b/tests/test_merge.py
@@ -6,7 +6,8 @@
 import asyncio
 from typing import List
 
-from frequenz.channels import Anycast, Merge, Sender
+from frequenz.channels import Anycast, Sender
+from frequenz.channels.util import Merge
 
 
 async def test_merge() -> None:
diff --git a/tests/test_mergenamed.py b/tests/test_mergenamed.py
@@ -6,7 +6,8 @@
 import asyncio
 from typing import List, Tuple
 
-from frequenz.channels import Anycast, MergeNamed, Sender
+from frequenz.channels import Anycast, Sender
+from frequenz.channels.util import MergeNamed
 
 
 async def test_mergenamed() -> None:
diff --git a/tests/test_select.py b/tests/test_select.py
@@ -6,7 +6,8 @@
 import asyncio
 from typing import List
 
-from frequenz.channels import Anycast, Select, Sender
+from frequenz.channels import Anycast, Sender
+from frequenz.channels.util import Select
 
 
 async def test_select() -> None:
diff --git a/tests/utils/test_file_watcher.py b/tests/utils/test_file_watcher.py
diff --git a/tests/utils/test_timer.py b/tests/utils/test_timer.py
