Rename BackgroundService to Service

The name `BackgroundService` is a bit too verbose now in the context of
an asyncio library. Services are usually already understood as running
in the background, so the `Background` prefix is redundant and makes the
class name too long.

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

Author: llucax

src/frequenz/core/asyncio.py

@@ -10,8 +10,8 @@
 
 - [cancel_and_await][frequenz.core.asyncio.cancel_and_await]: A function that cancels a
   task and waits for it to finish, handling `CancelledError` exceptions.
-- [BackgroundService][frequenz.core.asyncio.BackgroundService]: A base class for
-  implementing background services that can be started and stopped.
+- [Service][frequenz.core.asyncio.Service]: A base class for
+  implementing services running in the background that can be started and stopped.
 """
 
 
@@ -41,38 +41,38 @@ async def cancel_and_await(task: asyncio.Task[Any]) -> None:
         pass
 
 
-class BackgroundService(abc.ABC):
-    """A background service that can be started and stopped.
+class Service(abc.ABC):
+    """A service running in the background.
 
-    A background service is a service that runs in the background spawning one or more
-    tasks. The service can be [started][frequenz.core.asyncio.BackgroundService.start]
-    and [stopped][frequenz.core.asyncio.BackgroundService.stop] and can work as an
-    async context manager to provide deterministic cleanup.
+    A service swpawns one of more background tasks and can be
+    [started][frequenz.core.asyncio.Service.start] and
+    [stopped][frequenz.core.asyncio.Service.stop] and can work as an async context
+    manager to provide deterministic cleanup.
 
-    To implement a background service, subclasses must implement the
-    [`start()`][frequenz.core.asyncio.BackgroundService.start] method, which should
-    start the background tasks needed by the service, and add them to the `_tasks`
-    protected attribute.
+    To implement a service, subclasses must implement the
+    [`start()`][frequenz.core.asyncio.Service.start] method, which should start the
+    background tasks needed by the service, and add them to the `_tasks` protected
+    attribute.
 
     If you need to collect results or handle exceptions of the tasks when stopping the
     service, then you need to also override the
-    [`stop()`][frequenz.core.asyncio.BackgroundService.stop] method, as the base
+    [`stop()`][frequenz.core.asyncio.Service.stop] method, as the base
     implementation does not collect any results and re-raises all exceptions.
 
     !!! warning
 
-        As background services manage [`asyncio.Task`][] objects, a reference to them
-        must be held for as long as the background service is expected to be running,
-        otherwise its tasks will be cancelled and the service will stop. For more
-        information, please refer to the [Python `asyncio`
+        As services manage [`asyncio.Task`][] objects, a reference to them must be held
+        for as long as the service is expected to be running, otherwise its tasks will
+        be cancelled and the service will stop. For more information, please refer to
+        the [Python `asyncio`
         documentation](https://docs.python.org/3/library/asyncio-task.html#asyncio.create_task).
 
     Example:
         ```python
         import datetime
         import asyncio
 
-        class Clock(BackgroundService):
+        class Clock(Service):
             def __init__(self, resolution_s: float, *, unique_id: str | None = None) -> None:
                 super().__init__(unique_id=unique_id)
                 self._resolution_s = resolution_s
@@ -101,13 +101,13 @@ async def main() -> None:
     """
 
     def __init__(self, *, unique_id: str | None = None) -> None:
-        """Initialize this BackgroundService.
+        """Initialize this Service.
 
         Args:
-            unique_id: The string to uniquely identify this background service instance.
+            unique_id: The string to uniquely identify this service instance.
                 If `None`, a string based on `hex(id(self))` will be used. This is
                 used in `__repr__` and `__str__` methods, mainly for debugging
-                purposes, to identify a particular instance of a background service.
+                purposes, to identify a particular instance of a service.
         """
         # [2:] is used to remove the '0x' prefix from the hex representation of the id,
         # as it doesn't add any uniqueness to the string.
@@ -116,16 +116,16 @@ def __init__(self, *, unique_id: str | None = None) -> None:
 
     @abc.abstractmethod
     def start(self) -> None:
-        """Start this background service."""
+        """Start this service."""
 
     @property
     def unique_id(self) -> str:
-        """The unique ID of this background service."""
+        """The unique ID of this service."""
         return self._unique_id
 
     @property
     def tasks(self) -> collections.abc.Set[asyncio.Task[Any]]:
-        """The set of running tasks spawned by this background service.
+        """The set of running tasks spawned by this service.
 
         Users typically should not modify the tasks in the returned set and only use
         them for informational purposes.
@@ -139,14 +139,14 @@ def tasks(self) -> collections.abc.Set[asyncio.Task[Any]]:
 
     @property
     def is_running(self) -> bool:
-        """Whether this background service is running.
+        """Whether this service is running.
 
         A service is considered running when at least one task is running.
         """
         return any(not task.done() for task in self._tasks)
 
     def cancel(self, msg: str | None = None) -> None:
-        """Cancel all running tasks spawned by this background service.
+        """Cancel all running tasks spawned by this service.
 
         Args:
             msg: The message to be passed to the tasks being cancelled.
@@ -155,7 +155,7 @@ def cancel(self, msg: str | None = None) -> None:
             task.cancel(msg)
 
     async def stop(self, msg: str | None = None) -> None:
-        """Stop this background service.
+        """Stop this service.
 
         This method cancels all running tasks spawned by this service and waits for them
         to finish.
@@ -184,10 +184,10 @@ async def stop(self, msg: str | None = None) -> None:
     async def __aenter__(self) -> Self:
         """Enter an async context.
 
-        Start this background service.
+        Start this service.
 
         Returns:
-            This background service.
+            This service.
         """
         self.start()
         return self
@@ -200,7 +200,7 @@ async def __aexit__(
     ) -> None:
         """Exit an async context.
 
-        Stop this background service.
+        Stop this service.
 
         Args:
             exc_type: The type of the exception raised, if any.
@@ -210,9 +210,9 @@ async def __aexit__(
         await self.stop()
 
     async def wait(self) -> None:
-        """Wait this background service to finish.
+        """Wait for this service to finish.
 
-        Wait until all background service tasks are finished.
+        Wait until all the service tasks are finished.
 
         Raises:
             BaseExceptionGroup: If any of the tasks spawned by this service raised an
@@ -239,13 +239,13 @@ async def wait(self) -> None:
                     exceptions.append(error)
             if exceptions:
                 raise BaseExceptionGroup(
-                    f"Error while stopping background service {self}", exceptions
+                    f"Error while stopping service {self}", exceptions
                 )
 
     def __await__(self) -> collections.abc.Generator[None, None, None]:
-        """Await this background service.
+        """Await this service.
 
-        An awaited background service will wait for all its tasks to finish.
+        An awaited service will wait for all its tasks to finish.
 
         Returns:
             An implementation-specific generator for the awaitable.
@@ -255,7 +255,7 @@ def __await__(self) -> collections.abc.Generator[None, None, None]:
     def __del__(self) -> None:
         """Destroy this instance.
 
-        Cancel all running tasks spawned by this background service.
+        Cancel all running tasks spawned by this service.
         """
         self.cancel("{self!r} was deleted")
 

tests/test_asyncio.py

@@ -9,7 +9,7 @@
 import async_solipsism
 import pytest
 
-from frequenz.core.asyncio import BackgroundService
+from frequenz.core.asyncio import Service
 
 
 # This method replaces the event loop for all tests in the file.
@@ -19,8 +19,8 @@ def event_loop_policy() -> async_solipsism.EventLoopPolicy:
     return async_solipsism.EventLoopPolicy()
 
 
-class FakeService(BackgroundService):
-    """A background service that does nothing."""
+class FakeService(Service):
+    """A service that does nothing."""
 
     def __init__(
         self,
@@ -47,7 +47,7 @@ async def nop() -> None:
 
 
 async def test_construction_defaults() -> None:
-    """Test the construction of a background service with default arguments."""
+    """Test the construction of a service with default arguments."""
     fake_service = FakeService()
     assert fake_service.unique_id == hex(id(fake_service))[2:]
     assert fake_service.tasks == set()
@@ -60,15 +60,15 @@ async def test_construction_defaults() -> None:
 
 
 async def test_construction_custom() -> None:
-    """Test the construction of a background service with a custom unique ID."""
+    """Test the construction of a service with a custom unique ID."""
     fake_service = FakeService(unique_id="test")
     assert fake_service.unique_id == "test"
     assert fake_service.tasks == set()
     assert fake_service.is_running is False
 
 
 async def test_start_await() -> None:
-    """Test a background service starts and can be awaited."""
+    """Test a service starts and can be awaited."""
     fake_service = FakeService(unique_id="test")
     assert fake_service.unique_id == "test"
     assert fake_service.is_running is False
@@ -88,7 +88,7 @@ async def test_start_await() -> None:
 
 
 async def test_start_stop() -> None:
-    """Test a background service starts and stops correctly."""
+    """Test a service starts and stops correctly."""
     fake_service = FakeService(unique_id="test", sleep=2.0)
     assert fake_service.unique_id == "test"
     assert fake_service.is_running is False
@@ -114,7 +114,7 @@ async def test_start_stop() -> None:
 async def test_start_and_crash(
     method: Literal["await"] | Literal["wait"] | Literal["stop"],
 ) -> None:
-    """Test a background service reports when crashing."""
+    """Test a service reports when crashing."""
     exc = RuntimeError("error")
     fake_service = FakeService(unique_id="test", exc=exc)
     assert fake_service.unique_id == "test"
@@ -143,7 +143,7 @@ async def test_start_and_crash(
 
 
 async def test_async_context_manager() -> None:
-    """Test a background service works as an async context manager."""
+    """Test a service works as an async context manager."""
     async with FakeService(unique_id="test", sleep=1.0) as fake_service:
         assert fake_service.is_running is True
         # Is a no-op if the service is running