Split the asyncio module

Since more code is coming, and this module is already a bit large, we
split it into a util and a service sub-module.

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

Author: llucax

src/frequenz/core/asyncio/__init__.py

@@ -0,0 +1,29 @@
+# License: MIT
+# Copyright © 2024 Frequenz Energy-as-a-Service GmbH
+
+"""General purpose async tools.
+
+This module provides general purpose async tools that can be used to simplify the
+development of asyncio-based applications.
+
+The module provides the following classes and functions:
+
+- [cancel_and_await][frequenz.core.asyncio.cancel_and_await]: A function that cancels a
+  task and waits for it to finish, handling `CancelledError` exceptions.
+- [Service][frequenz.core.asyncio.Service]: An interface for services running in the
+  background.
+- [ServiceBase][frequenz.core.asyncio.ServiceBase]: A base class for implementing
+  services running in the background.
+- [TaskCreator][frequenz.core.asyncio.TaskCreator]: A protocol for creating tasks.
+"""
+
+from ._service import Service, ServiceBase
+from ._util import TaskCreator, TaskReturnT, cancel_and_await
+
+__all__ = [
+    "Service",
+    "ServiceBase",
+    "TaskCreator",
+    "TaskReturnT",
+    "cancel_and_await",
+]

src/frequenz/core/asyncio.py src/frequenz/core/asyncio/_service.pysrc/frequenz/core/asyncio.py renamed to src/frequenz/core/asyncio/_service.py

@@ -1,21 +1,7 @@
 # License: MIT
 # Copyright © 2024 Frequenz Energy-as-a-Service GmbH
 
-"""General purpose async tools.
-
-This module provides general purpose async tools that can be used to simplify the
-development of asyncio-based applications.
-
-The module provides the following classes and functions:
-
-- [cancel_and_await][frequenz.core.asyncio.cancel_and_await]: A function that cancels a
-  task and waits for it to finish, handling `CancelledError` exceptions.
-- [Service][frequenz.core.asyncio.Service]: An interface for services running in the
-  background.
-- [ServiceBase][frequenz.core.asyncio.ServiceBase]: A base class for implementing
-  services running in the background.
-- [TaskCreator][frequenz.core.asyncio.TaskCreator]: A protocol for creating tasks.
-"""
+"""Module implementing the `Service` and `ServiceBase` classes."""
 
 
 import abc
@@ -24,66 +10,13 @@
 import contextvars
 import logging
 from types import TracebackType
-from typing import Any, Protocol, Self, TypeVar, runtime_checkable
+from typing import Any, Self
 
 from typing_extensions import override
 
-_logger = logging.getLogger(__name__)
-
-
-TaskReturnT = TypeVar("TaskReturnT")
-"""The type of the return value of a task."""
-
-
-@runtime_checkable
-class TaskCreator(Protocol):
-    """A protocol for creating tasks.
-
-    Built-in asyncio functions and classes implementing this protocol:
-
-    - [`asyncio`][]
-    - [`asyncio.AbstractEventLoop`][] (returned by [`asyncio.get_event_loop`][] for
-      example)
-    - [`asyncio.TaskGroup`][]
-    """
-
-    def create_task(
-        self,
-        coro: collections.abc.Coroutine[Any, Any, TaskReturnT],
-        *,
-        name: str | None = None,
-        context: contextvars.Context | None = None,
-    ) -> asyncio.Task[TaskReturnT]:
-        """Create a task.
-
-        Args:
-            coro: The coroutine to be executed.
-            name: The name of the task.
-            context: The context to be used for the task.
-
-        Returns:
-            The new task.
-        """
-        ...  # pylint: disable=unnecessary-ellipsis
-
-
-async def cancel_and_await(task: asyncio.Task[Any]) -> None:
-    """Cancel a task and wait for it to finish.
+from ._util import TaskCreator, TaskReturnT
 
-    Exits immediately if the task is already done.
-
-    The `CancelledError` is suppressed, but any other exception will be propagated.
-
-    Args:
-        task: The task to be cancelled and waited for.
-    """
-    if task.done():
-        return
-    task.cancel()
-    try:
-        await task
-    except asyncio.CancelledError:
-        pass
+_logger = logging.getLogger(__name__)
 
 
 class Service(abc.ABC):

src/frequenz/core/asyncio/_util.py

@@ -0,0 +1,64 @@
+# License: MIT
+# Copyright © 2024 Frequenz Energy-as-a-Service GmbH
+
+"""General purpose async utilities."""
+
+
+import asyncio
+import collections.abc
+import contextvars
+from typing import Any, Protocol, TypeVar, runtime_checkable
+
+TaskReturnT = TypeVar("TaskReturnT")
+"""The type of the return value of a task."""
+
+
+@runtime_checkable
+class TaskCreator(Protocol):
+    """A protocol for creating tasks.
+
+    Built-in asyncio functions and classes implementing this protocol:
+
+    - [`asyncio`][]
+    - [`asyncio.AbstractEventLoop`][] (returned by [`asyncio.get_event_loop`][] for
+      example)
+    - [`asyncio.TaskGroup`][]
+    """
+
+    def create_task(
+        self,
+        coro: collections.abc.Coroutine[Any, Any, TaskReturnT],
+        *,
+        name: str | None = None,
+        context: contextvars.Context | None = None,
+    ) -> asyncio.Task[TaskReturnT]:
+        """Create a task.
+
+        Args:
+            coro: The coroutine to be executed.
+            name: The name of the task.
+            context: The context to be used for the task.
+
+        Returns:
+            The new task.
+        """
+        ...  # pylint: disable=unnecessary-ellipsis
+
+
+async def cancel_and_await(task: asyncio.Task[Any]) -> None:
+    """Cancel a task and wait for it to finish.
+
+    Exits immediately if the task is already done.
+
+    The `CancelledError` is suppressed, but any other exception will be propagated.
+
+    Args:
+        task: The task to be cancelled and waited for.
+    """
+    if task.done():
+        return
+    task.cancel()
+    try:
+        await task
+    except asyncio.CancelledError:
+        pass

tests/test_asyncio.py tests/asyncio/test_service.pytests/test_asyncio.py renamed to tests/asyncio/test_service.py

@@ -1,15 +1,15 @@
 # License: MIT
 # Copyright © 2022 Frequenz Energy-as-a-Service GmbH
 
-"""Tests for the asyncio module."""
+"""Tests for the asyncio service module."""
 
 import asyncio
 from typing import Literal, assert_never
 
 import async_solipsism
 import pytest
 
-from frequenz.core.asyncio import ServiceBase, TaskCreator
+from frequenz.core.asyncio import ServiceBase
 
 
 # This method replaces the event loop for all tests in the file.
@@ -147,18 +147,3 @@ async def test_async_context_manager() -> None:
         assert fake_service.is_running is True
 
     assert fake_service.is_running is False
-
-
-def test_task_creator_asyncio() -> None:
-    """Test that the asyncio module is a TaskCreator."""
-    assert isinstance(asyncio, TaskCreator)
-
-
-async def test_task_creator_loop() -> None:
-    """Test that the asyncio event loop is a TaskCreator."""
-    assert isinstance(asyncio.get_event_loop(), TaskCreator)
-
-
-def test_task_creator_task_group() -> None:
-    """Test that the asyncio task group is a TaskCreator."""
-    assert isinstance(asyncio.TaskGroup(), TaskCreator)

tests/asyncio/test_util.py

@@ -0,0 +1,23 @@
+# License: MIT
+# Copyright © 2022 Frequenz Energy-as-a-Service GmbH
+
+"""Tests for the asyncio util module."""
+
+import asyncio
+
+from frequenz.core.asyncio import TaskCreator
+
+
+def test_task_creator_asyncio() -> None:
+    """Test that the asyncio module is a TaskCreator."""
+    assert isinstance(asyncio, TaskCreator)
+
+
+async def test_task_creator_loop() -> None:
+    """Test that the asyncio event loop is a TaskCreator."""
+    assert isinstance(asyncio.get_event_loop(), TaskCreator)
+
+
+def test_task_creator_task_group() -> None:
+    """Test that the asyncio task group is a TaskCreator."""
+    assert isinstance(asyncio.TaskGroup(), TaskCreator)