Added a done() method to BackgroundService to check for completion

This is usefull if we have type: `asyncio.Task | Actor`
and need to check if actor finished.

Signed-off-by: Elzbieta Kotulska <[email protected]>

Author: ela-kotulska-frequenz

RELEASE_NOTES.md

@@ -10,7 +10,7 @@
 
 ## New Features
 
-<!-- Here goes the main new features and examples or instructions on how to use them -->
+* Added a `done()` method to `BackgroundService` to check for completion.
 
 ## Bug Fixes
 

src/frequenz/sdk/actor/_background_service.py

@@ -161,6 +161,17 @@ def is_running(self) -> bool:
         """
         return any(not task.done() for task in self._tasks)
 
+    def done(self) -> bool:
+        """Return whether this background service is done.
+
+        A service is considered done when all tasks
+        are finished or raised exception or were cancelled.
+
+        Returns:
+            Whether this background service is done.
+        """
+        return not self.is_running
+
     def cancel(self, msg: str | None = None) -> None:
         """Cancel all running tasks spawned by this background service.
 

tests/actor/test_background_service.py

@@ -50,6 +50,7 @@ async def test_construction_defaults() -> None:
     assert fake_service.name == str(id(fake_service))
     assert fake_service.tasks == set()
     assert fake_service.is_running is False
+    assert fake_service.done() is True
     assert str(fake_service) == f"FakeService[{fake_service.name}]"
     assert repr(fake_service) == f"FakeService(name={fake_service.name!r}, tasks=set())"
 
@@ -60,49 +61,60 @@ async def test_construction_custom() -> None:
     assert fake_service.name == "test"
     assert fake_service.tasks == set()
     assert fake_service.is_running is False
+    assert fake_service.done() is True
 
 
 async def test_start_await() -> None:
     """Test a background service starts and can be awaited."""
     fake_service = FakeService(name="test")
     assert fake_service.name == "test"
     assert fake_service.is_running is False
+    assert fake_service.done() is True
 
     # Is a no-op if the service is not running
     await fake_service.stop()
     assert fake_service.is_running is False
+    assert fake_service.done() is True
 
     fake_service.start()
     assert fake_service.is_running is True
+    assert fake_service.done() is False
 
     # Should stop immediately
     async with asyncio.timeout(1.0):
         await fake_service
 
     assert fake_service.is_running is False
+    assert fake_service.done() is True
 
 
 async def test_start_stop() -> None:
     """Test a background service starts and stops correctly."""
     fake_service = FakeService(name="test", sleep=2.0)
     assert fake_service.name == "test"
     assert fake_service.is_running is False
+    assert fake_service.done() is True
 
     # Is a no-op if the service is not running
     await fake_service.stop()
     assert fake_service.is_running is False
+    assert fake_service.done() is True
 
     fake_service.start()
     assert fake_service.is_running is True
+    assert fake_service.done() is False
 
     await asyncio.sleep(1.0)
     assert fake_service.is_running is True
+    assert fake_service.done() is False
 
     await fake_service.stop()
     assert fake_service.is_running is False
+    assert fake_service.done() is True
 
     await fake_service.stop()
     assert fake_service.is_running is False
+    assert fake_service.done() is True
 
 
 @pytest.mark.parametrize("method", ["await", "wait", "stop"])
@@ -114,6 +126,7 @@ async def test_start_and_crash(
     fake_service = FakeService(name="test", exc=exc)
     assert fake_service.name == "test"
     assert fake_service.is_running is False
+    assert fake_service.done() is True
 
     fake_service.start()
     with pytest.raises(BaseExceptionGroup) as exc_info:
@@ -141,9 +154,12 @@ async def test_async_context_manager() -> None:
     """Test a background service works as an async context manager."""
     async with FakeService(name="test", sleep=1.0) as fake_service:
         assert fake_service.is_running is True
+        assert fake_service.done() is False
         # Is a no-op if the service is running
         fake_service.start()
         await asyncio.sleep(0)
         assert fake_service.is_running is True
+        assert fake_service.done() is False
 
     assert fake_service.is_running is False
+    assert fake_service.done() is True