Rename name to unique_id for BackgroundService (#26)

Using `name` was confusing, as people didn't realize that it is used to
actually identify one of multiple instances. Also people were very prone
to use the class name as `name`, which is redundant as the class name is
also included in `str` and `repr`.

Using `unique_id` makes it more clear that this is used for
identification in logs and that a default is better than passing a
string that is not really unique (like the class name).

Also use `hex()` instead of `str()` to build the default `unique_id`, as
it a more compact representation of the id.

Fixes #7.

Author: llucax

src/frequenz/core/asyncio.py

@@ -73,8 +73,8 @@ class BackgroundService(abc.ABC):
         import asyncio
 
         class Clock(BackgroundService):
-            def __init__(self, resolution_s: float, *, name: str | None = None) -> None:
-                super().__init__(name=name)
+            def __init__(self, resolution_s: float, *, unique_id: str | None = None) -> None:
+                super().__init__(unique_id=unique_id)
                 self._resolution_s = resolution_s
 
             def start(self) -> None:
@@ -100,28 +100,32 @@ async def main() -> None:
         ```
     """
 
-    def __init__(self, *, name: str | None = None) -> None:
+    def __init__(self, *, unique_id: str | None = None) -> None:
         """Initialize this BackgroundService.
 
         Args:
-            name: The name of this background service. If `None`, `str(id(self))` will
-                be used. This is used mostly for debugging purposes.
+            unique_id: The string to uniquely identify this background 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.
         """
-        self._name: str = str(id(self)) if name is None else name
+        # [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.
+        self._unique_id: str = hex(id(self))[2:] if unique_id is None else unique_id
         self._tasks: set[asyncio.Task[Any]] = set()
 
     @abc.abstractmethod
     def start(self) -> None:
         """Start this background service."""
 
     @property
-    def name(self) -> str:
-        """The name of this background service.
+    def unique_id(self) -> str:
+        """The unique ID of this background service.
 
         Returns:
-            The name of this background service.
+            The unique ID of this background service.
         """
-        return self._name
+        return self._unique_id
 
     @property
     def tasks(self) -> collections.abc.Set[asyncio.Task[Any]]:
@@ -271,12 +275,12 @@ def __repr__(self) -> str:
         Returns:
             A string representation of this instance.
         """
-        return f"{type(self).__name__}(name={self._name!r}, tasks={self._tasks!r})"
+        return f"{type(self).__name__}(unique_id={self._unique_id!r}, tasks={self._tasks!r})"
 
     def __str__(self) -> str:
         """Return a string representation of this instance.
 
         Returns:
             A string representation of this instance.
         """
-        return f"{type(self).__name__}[{self._name}]"
+        return f"{type(self).__name__}[{self._unique_id}]"

tests/test_asyncio.py

@@ -25,12 +25,12 @@ class FakeService(BackgroundService):
     def __init__(
         self,
         *,
-        name: str | None = None,
+        unique_id: str | None = None,
         sleep: float | None = None,
         exc: BaseException | None = None,
     ) -> None:
         """Initialize a new FakeService."""
-        super().__init__(name=name)
+        super().__init__(unique_id=unique_id)
         self._sleep = sleep
         self._exc = exc
 
@@ -49,25 +49,28 @@ async def nop() -> None:
 async def test_construction_defaults() -> None:
     """Test the construction of a background service with default arguments."""
     fake_service = FakeService()
-    assert fake_service.name == str(id(fake_service))
+    assert fake_service.unique_id == hex(id(fake_service))[2:]
     assert fake_service.tasks == set()
     assert fake_service.is_running is False
-    assert str(fake_service) == f"FakeService[{fake_service.name}]"
-    assert repr(fake_service) == f"FakeService(name={fake_service.name!r}, tasks=set())"
+    assert str(fake_service) == f"FakeService[{fake_service.unique_id}]"
+    assert (
+        repr(fake_service)
+        == f"FakeService(unique_id={fake_service.unique_id!r}, tasks=set())"
+    )
 
 
 async def test_construction_custom() -> None:
-    """Test the construction of a background service with a custom name."""
-    fake_service = FakeService(name="test")
-    assert fake_service.name == "test"
+    """Test the construction of a background 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."""
-    fake_service = FakeService(name="test")
-    assert fake_service.name == "test"
+    fake_service = FakeService(unique_id="test")
+    assert fake_service.unique_id == "test"
     assert fake_service.is_running is False
 
     # Is a no-op if the service is not running
@@ -86,8 +89,8 @@ async def test_start_await() -> None:
 
 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"
+    fake_service = FakeService(unique_id="test", sleep=2.0)
+    assert fake_service.unique_id == "test"
     assert fake_service.is_running is False
 
     # Is a no-op if the service is not running
@@ -113,8 +116,8 @@ async def test_start_and_crash(
 ) -> None:
     """Test a background service reports when crashing."""
     exc = RuntimeError("error")
-    fake_service = FakeService(name="test", exc=exc)
-    assert fake_service.name == "test"
+    fake_service = FakeService(unique_id="test", exc=exc)
+    assert fake_service.unique_id == "test"
     assert fake_service.is_running is False
 
     fake_service.start()
@@ -141,7 +144,7 @@ async def test_start_and_crash(
 
 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:
+    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
         fake_service.start()