From bd5579ef6185c74cdb6e4aefe5b7ab374a475e3a Mon Sep 17 00:00:00 2001
From: "Mathias L. Baumann" <mathias.baumann@frequenz.com>
Date: Thu, 25 Sep 2025 17:54:34 +0200
Subject: [PATCH] Rename `DispatchInfo`'s `components` to `target`

in a backwards compatible way with deprecation warning.

Signed-off-by: Mathias L. Baumann <mathias.baumann@frequenz.com>
---
 RELEASE_NOTES.md                           |  1 +
 src/frequenz/dispatch/_actor_dispatcher.py | 17 ++++++++++++++---
 tests/test_managing_actor.py               |  6 ++----
 3 files changed, 17 insertions(+), 7 deletions(-)

diff --git a/RELEASE_NOTES.md b/RELEASE_NOTES.md
index caa92f1..090a007 100644
--- a/RELEASE_NOTES.md
+++ b/RELEASE_NOTES.md
@@ -7,6 +7,7 @@
 ## Upgrading
 
 * The `key` parameter in the `Dispatcher` constructor is now deprecated. Use `auth_key` instead. The `sign_secret` parameter is an additional optional parameter for signing.
+* The `components` property in `DispatchInfo` is now deprecated. Use `target` instead.
 
 ## New Features
 
diff --git a/src/frequenz/dispatch/_actor_dispatcher.py b/src/frequenz/dispatch/_actor_dispatcher.py
index 4750d33..00e6833 100644
--- a/src/frequenz/dispatch/_actor_dispatcher.py
+++ b/src/frequenz/dispatch/_actor_dispatcher.py
@@ -15,6 +15,7 @@
 from frequenz.client.dispatch.types import DispatchId, TargetComponents
 from frequenz.core.id import BaseId
 from frequenz.sdk.actor import Actor, BackgroundService
+from typing_extensions import deprecated
 
 from ._dispatch import Dispatch
 
@@ -37,8 +38,18 @@ def __init__(self, dispatch_id: DispatchId | int) -> None:
 class DispatchInfo:
     """Event emitted when the dispatch changes."""
 
-    components: TargetComponents
-    """Components to be used."""
+    @property
+    @deprecated("'components' is deprecated, use 'target' instead.")
+    def components(self) -> TargetComponents:
+        """Get the target components.
+
+        Deprecation: Deprecated in v0.10.3
+            Use [`target`][frequenz.dispatch.DispatchInfo.target] instead.
+        """
+        return self.target
+
+    target: TargetComponents
+    """Target components to be used."""
 
     dry_run: bool
     """Whether this is a dry run."""
@@ -200,7 +211,7 @@ def start(self) -> None:
     async def _start_actor(self, dispatch: Dispatch) -> None:
         """Start the actor the given dispatch refers to."""
         dispatch_update = DispatchInfo(
-            components=dispatch.target,
+            target=dispatch.target,
             dry_run=dispatch.dry_run,
             options=dispatch.payload,
             _src=dispatch,
diff --git a/tests/test_managing_actor.py b/tests/test_managing_actor.py
index f05cabc..773460a 100644
--- a/tests/test_managing_actor.py
+++ b/tests/test_managing_actor.py
@@ -177,9 +177,7 @@ async def test_simple_start_stop(
 
     event = test_env.actor(1).initial_dispatch
     assert event.options == {"test": True}
-    assert event.components == TargetIds(
-        ComponentId(1), ComponentId(10), ComponentId(15)
-    )
+    assert event.target == TargetIds(ComponentId(1), ComponentId(10), ComponentId(15))
     assert event.dry_run is False
 
     assert test_env.actor(1).is_running is True
@@ -309,7 +307,7 @@ async def test_dry_run(test_env: _TestEnv, fake_time: time_machine.Coordinates)
     event = test_env.actor(1).initial_dispatch
 
     assert event.dry_run is dispatch.dry_run
-    assert event.components == dispatch.target
+    assert event.target == dispatch.target
     assert event.options == dispatch.payload
     assert test_env.actor(1).is_running is True