frequenz-dispatch 0.1.0__py3-none-any.whl

frequenz/dispatch/__init__.py

@@ -0,0 +1,29 @@
+# License: MIT
+# Copyright © 2024 Frequenz Energy-as-a-Service GmbH
+
+"""A highlevel interface for the dispatch API.
+
+A small overview of the most important classes in this module:
+
+* [Dispatcher][frequenz.dispatch.Dispatcher]: The entry point for the API.
+* [Dispatch][frequenz.dispatch.Dispatch]: A dispatch type with lots of useful extra functionality.
+* [Created][frequenz.dispatch.Created],
+  [Updated][frequenz.dispatch.Updated],
+  [Deleted][frequenz.dispatch.Deleted]: Dispatch event types.
+
+"""
+
+from ._dispatch import Dispatch, RunningState
+from ._dispatcher import Dispatcher, ReceiverFetcher
+from ._event import Created, Deleted, DispatchEvent, Updated
+
+__all__ = [
+    "Created",
+    "Deleted",
+    "DispatchEvent",
+    "Dispatcher",
+    "ReceiverFetcher",
+    "Updated",
+    "Dispatch",
+    "RunningState",
+]

frequenz/dispatch/_dispatch.py

@@ -0,0 +1,251 @@
+# License: MIT
+# Copyright © 2024 Frequenz Energy-as-a-Service GmbH
+
+"""Dispatch type with support for next_run calculation."""
+
+
+import logging
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from enum import Enum
+from typing import Iterator, cast
+
+from dateutil import rrule
+from frequenz.client.dispatch.types import Dispatch as BaseDispatch
+from frequenz.client.dispatch.types import Frequency, Weekday
+
+_logger = logging.getLogger(__name__)
+"""The logger for this module."""
+
+_RRULE_FREQ_MAP = {
+    Frequency.MINUTELY: rrule.MINUTELY,
+    Frequency.HOURLY: rrule.HOURLY,
+    Frequency.DAILY: rrule.DAILY,
+    Frequency.WEEKLY: rrule.WEEKLY,
+    Frequency.MONTHLY: rrule.MONTHLY,
+}
+"""To map from our Frequency enum to the dateutil library enum."""
+
+_RRULE_WEEKDAY_MAP = {
+    Weekday.MONDAY: rrule.MO,
+    Weekday.TUESDAY: rrule.TU,
+    Weekday.WEDNESDAY: rrule.WE,
+    Weekday.THURSDAY: rrule.TH,
+    Weekday.FRIDAY: rrule.FR,
+    Weekday.SATURDAY: rrule.SA,
+    Weekday.SUNDAY: rrule.SU,
+}
+"""To map from our Weekday enum to the dateutil library enum."""
+
+
+class RunningState(Enum):
+    """The running state of a dispatch."""
+
+    RUNNING = "RUNNING"
+    """The dispatch is running."""
+
+    STOPPED = "STOPPED"
+    """The dispatch is stopped."""
+
+    DIFFERENT_TYPE = "DIFFERENT_TYPE"
+    """The dispatch is for a different type."""
+
+
+@dataclass(frozen=True)
+class Dispatch(BaseDispatch):
+    """Dispatch type with extra functionality."""
+
+    deleted: bool = False
+    """Whether the dispatch is deleted."""
+
+    running_state_change_synced: datetime | None = None
+    """The last time a message was sent about the running state change."""
+
+    def __init__(
+        self,
+        client_dispatch: BaseDispatch,
+        deleted: bool = False,
+        running_state_change_synced: datetime | None = None,
+    ):
+        """Initialize the dispatch.
+
+        Args:
+            client_dispatch: The client dispatch.
+            deleted: Whether the dispatch is deleted.
+            running_state_change_synced: Timestamp of the last running state change message.
+        """
+        super().__init__(**client_dispatch.__dict__)
+        # Work around frozen to set deleted
+        object.__setattr__(self, "deleted", deleted)
+        object.__setattr__(
+            self,
+            "running_state_change_synced",
+            running_state_change_synced,
+        )
+
+    def _set_deleted(self) -> None:
+        """Mark the dispatch as deleted."""
+        object.__setattr__(self, "deleted", True)
+
+    @property
+    def _running_status_notified(self) -> bool:
+        """Check that the latest running state change notification was sent.
+
+        Returns:
+            True if the latest running state change notification was sent, False otherwise.
+        """
+        return self.running_state_change_synced == self.update_time
+
+    def _set_running_status_notified(self) -> None:
+        """Mark the latest running state change notification as sent."""
+        object.__setattr__(self, "running_state_change_synced", self.update_time)
+
+    def running(self, type_: str) -> RunningState:
+        """Check if the dispatch is currently supposed to be running.
+
+        Args:
+            type_: The type of the dispatch that should be running.
+
+        Returns:
+            RUNNING if the dispatch is running,
+            STOPPED if it is stopped,
+            DIFFERENT_TYPE if it is for a different type.
+        """
+        if self.type != type_:
+            return RunningState.DIFFERENT_TYPE
+
+        if not self.active or self.deleted:
+            return RunningState.STOPPED
+
+        now = datetime.now(tz=timezone.utc)
+        if until := self._until(now):
+            return RunningState.RUNNING if now < until else RunningState.STOPPED
+
+        return RunningState.STOPPED
+
+    @property
+    def until(self) -> datetime | None:
+        """Time when the dispatch should end.
+
+        Returns the time that a running dispatch should end.
+        If the dispatch is not running, None is returned.
+
+        Returns:
+            The time when the dispatch should end or None if the dispatch is not running.
+        """
+        if not self.active or self.deleted:
+            return None
+
+        now = datetime.now(tz=timezone.utc)
+        return self._until(now)
+
+    @property
+    # noqa is needed because of a bug in pydoclint that makes it think a `return` without a return
+    # value needs documenting
+    def missed_runs(self) -> Iterator[datetime]:  # noqa: DOC405
+        """Yield all missed runs of a dispatch.
+
+        Yields all missed runs of a dispatch.
+
+        If a running state change notification was not sent in time
+        due to connection issues, this method will yield all missed runs
+        since the last sent notification.
+
+        Returns:
+            A generator that yields all missed runs of a dispatch.
+        """
+        if self.update_time == self.running_state_change_synced:
+            return
+
+        from_time = self.update_time
+        now = datetime.now(tz=timezone.utc)
+
+        while (next_run := self.next_run_after(from_time)) and next_run < now:
+            yield next_run
+            from_time = next_run
+
+    @property
+    def next_run(self) -> datetime | None:
+        """Calculate the next run of a dispatch.
+
+        Returns:
+            The next run of the dispatch or None if the dispatch is finished.
+        """
+        return self.next_run_after(datetime.now(tz=timezone.utc))
+
+    def next_run_after(self, after: datetime) -> datetime | None:
+        """Calculate the next run of a dispatch.
+
+        Args:
+            after: The time to calculate the next run from.
+
+        Returns:
+            The next run of the dispatch or None if the dispatch is finished.
+        """
+        if (
+            not self.recurrence.frequency
+            or self.recurrence.frequency == Frequency.UNSPECIFIED
+        ):
+            if after > self.start_time:
+                return None
+            return self.start_time
+
+        # Make sure no weekday is UNSPECIFIED
+        if Weekday.UNSPECIFIED in self.recurrence.byweekdays:
+            _logger.warning("Dispatch %s has UNSPECIFIED weekday, ignoring...", self.id)
+            return None
+
+        # No type information for rrule, so we need to cast
+        return cast(datetime | None, self._prepare_rrule().after(after, inc=True))
+
+    def _prepare_rrule(self) -> rrule.rrule:
+        """Prepare the rrule object.
+
+        Returns:
+            The rrule object.
+        """
+        count, until = (None, None)
+        if end := self.recurrence.end_criteria:
+            count = end.count
+            until = end.until
+
+        rrule_obj = rrule.rrule(
+            freq=_RRULE_FREQ_MAP[self.recurrence.frequency],
+            dtstart=self.start_time,
+            count=count,
+            until=until,
+            byminute=self.recurrence.byminutes,
+            byhour=self.recurrence.byhours,
+            byweekday=[
+                _RRULE_WEEKDAY_MAP[weekday] for weekday in self.recurrence.byweekdays
+            ],
+            bymonthday=self.recurrence.bymonthdays,
+            bymonth=self.recurrence.bymonths,
+            interval=self.recurrence.interval,
+        )
+
+        return rrule_obj
+
+    def _until(self, now: datetime) -> datetime | None:
+        """Calculate the time when the dispatch should end.
+
+        If no previous run is found, None is returned.
+
+        Args:
+            now: The current time.
+
+        Returns:
+            The time when the dispatch should end or None if the dispatch is not running.
+        """
+        if (
+            not self.recurrence.frequency
+            or self.recurrence.frequency == Frequency.UNSPECIFIED
+        ):
+            return self.start_time + self.duration
+
+        latest_past_start: datetime | None = self._prepare_rrule().before(now, inc=True)
+
+        if not latest_past_start:
+            return None
+
+        return latest_past_start + self.duration

frequenz/dispatch/_dispatcher.py

@@ -0,0 +1,252 @@
+# License: MIT
+# Copyright © 2024 Frequenz Energy-as-a-Service GmbH
+
+"""A highlevel interface for the dispatch API."""
+
+import abc
+from typing import Protocol, TypeVar
+
+import grpc.aio
+from frequenz.channels import Broadcast, Receiver
+from frequenz.client.dispatch import Client
+
+from ._dispatch import Dispatch
+from ._event import DispatchEvent
+from .actor import DispatchingActor
+
+ReceivedT_co = TypeVar("ReceivedT_co", covariant=True)
+"""The type being received."""
+
+
+class ReceiverFetcher(Protocol[ReceivedT_co]):
+    """An interface that just exposes a `new_receiver` method."""
+
+    @abc.abstractmethod
+    def new_receiver(
+        self, *, name: str | None = None, limit: int = 50
+    ) -> Receiver[ReceivedT_co]:
+        """Get a receiver from the channel.
+
+        Args:
+            name: A name to identify the receiver in the logs.
+            limit: The maximum size of the receiver.
+
+        Returns:
+            A receiver instance.
+        """
+
+
+class Dispatcher:
+    """A highlevel interface for the dispatch API.
+
+    This class provides a highlevel interface to the dispatch API.
+    It provides two channels:
+
+    Lifecycle events:
+        A channel that sends a dispatch event message whenever a dispatch
+        is created, updated or deleted.
+
+    Running status change:
+        Sends a dispatch message whenever a dispatch is ready
+        to be executed according to the schedule or the running status of the
+        dispatch changed in a way that could potentially require the consumer to start,
+        stop or reconfigure itself.
+
+    Example: Processing running state change dispatches
+        ```python
+        import os
+        import grpc.aio
+        from frequenz.dispatch import Dispatcher, RunningState
+        from unittest.mock import MagicMock
+
+        async def run():
+            host = os.getenv("DISPATCH_API_HOST", "localhost")
+            port = os.getenv("DISPATCH_API_PORT", "50051")
+
+            service_address = f"{host}:{port}"
+            grpc_channel = grpc.aio.insecure_channel(service_address)
+            microgrid_id = 1
+            dispatcher = Dispatcher(microgrid_id, grpc_channel, service_address)
+            await dispatcher.start()
+
+            actor = MagicMock() # replace with your actor
+
+            changed_running_status = dispatcher.running_status_change.new_receiver()
+
+            async for dispatch in changed_running_status:
+                match dispatch.running("DEMO_TYPE"):
+                    case RunningState.RUNNING:
+                        print(f"Executing dispatch {dispatch.id}, due on {dispatch.start_time}")
+                        if actor.is_running:
+                            actor.reconfigure(
+                                components=dispatch.selector,
+                                run_parameters=dispatch.payload, # custom actor parameters
+                                dry_run=dispatch.dry_run,
+                                until=dispatch.until,
+                            )  # this will reconfigure the actor
+                        else:
+                            # this will start a new actor with the given components
+                            # and run it for the duration of the dispatch
+                            actor.start(
+                                components=dispatch.selector,
+                                run_parameters=dispatch.payload, # custom actor parameters
+                                dry_run=dispatch.dry_run,
+                                until=dispatch.until,
+                            )
+                    case RunningState.STOPPED:
+                        actor.stop()  # this will stop the actor
+                    case RunningState.DIFFERENT_TYPE:
+                        pass  # dispatch not for this type
+        ```
+
+    Example: Getting notification about dispatch lifecycle events
+        ```python
+        import os
+        from typing import assert_never
+
+        import grpc.aio
+        from frequenz.dispatch import Created, Deleted, Dispatcher, Updated
+
+        async def run():
+            host = os.getenv("DISPATCH_API_HOST", "localhost")
+            port = os.getenv("DISPATCH_API_PORT", "50051")
+
+            service_address = f"{host}:{port}"
+            grpc_channel = grpc.aio.insecure_channel(service_address)
+            microgrid_id = 1
+            dispatcher = Dispatcher(microgrid_id, grpc_channel, service_address)
+            dispatcher.start()  # this will start the actor
+
+            events_receiver = dispatcher.lifecycle_events.new_receiver()
+
+            async for event in events_receiver:
+                match event:
+                    case Created(dispatch):
+                        print(f"A dispatch was created: {dispatch}")
+                    case Deleted(dispatch):
+                        print(f"A dispatch was deleted: {dispatch}")
+                    case Updated(dispatch):
+                        print(f"A dispatch was updated: {dispatch}")
+                    case _ as unhandled:
+                        assert_never(unhandled)
+        ```
+
+    Example: Creating a new dispatch and then modifying it.
+        Note that this uses the lower-level `Client` class to create and update the dispatch.
+
+        ```python
+        import os
+        from datetime import datetime, timedelta, timezone
+
+        import grpc.aio
+        from frequenz.client.common.microgrid.components import ComponentCategory
+
+        from frequenz.dispatch import Dispatcher
+
+        async def run():
+            host = os.getenv("DISPATCH_API_HOST", "localhost")
+            port = os.getenv("DISPATCH_API_PORT", "50051")
+
+            service_address = f"{host}:{port}"
+            grpc_channel = grpc.aio.insecure_channel(service_address)
+            microgrid_id = 1
+            dispatcher = Dispatcher(microgrid_id, grpc_channel, service_address)
+            await dispatcher.start()  # this will start the actor
+
+            # Create a new dispatch
+            new_dispatch = await dispatcher.client.create(
+                microgrid_id=microgrid_id,
+                _type="ECHO_FREQUENCY",  # replace with your own type
+                start_time=datetime.now(tz=timezone.utc) + timedelta(minutes=10),
+                duration=timedelta(minutes=5),
+                selector=ComponentCategory.INVERTER,
+                payload={"font": "Times New Roman"},  # Arbitrary payload data
+            )
+
+            # Modify the dispatch
+            await dispatcher.client.update(
+                dispatch_id=new_dispatch.id, new_fields={"duration": timedelta(minutes=10)}
+            )
+
+            # Validate the modification
+            modified_dispatch = await dispatcher.client.get(new_dispatch.id)
+            assert modified_dispatch.duration == timedelta(minutes=10)
+        ```
+    """
+
+    def __init__(
+        self, microgrid_id: int, grpc_channel: grpc.aio.Channel, svc_addr: str
+    ):
+        """Initialize the dispatcher.
+
+        Args:
+            microgrid_id: The microgrid id.
+            grpc_channel: The gRPC channel.
+            svc_addr: The service address.
+        """
+        self._running_state_channel = Broadcast[Dispatch](name="running_state_change")
+        self._lifecycle_events_channel = Broadcast[DispatchEvent](
+            name="lifecycle_events"
+        )
+        self._client = Client(grpc_channel, svc_addr)
+        self._actor = DispatchingActor(
+            microgrid_id,
+            self._client,
+            self._lifecycle_events_channel.new_sender(),
+            self._running_state_channel.new_sender(),
+        )
+
+    async def start(self) -> None:
+        """Start the actor."""
+        self._actor.start()
+
+    @property
+    def client(self) -> Client:
+        """Return the client."""
+        return self._client
+
+    @property
+    def lifecycle_events(self) -> ReceiverFetcher[DispatchEvent]:
+        """Return new, updated or deleted dispatches receiver fetcher.
+
+        Returns:
+            A new receiver for new dispatches.
+        """
+        return self._lifecycle_events_channel
+
+    @property
+    def running_status_change(self) -> ReceiverFetcher[Dispatch]:
+        """Return running status change receiver fetcher.
+
+        This receiver will receive a message whenever the current running
+        status of a dispatch changes.
+
+        Usually, one message per scheduled run is to be expected.
+        However, things get complicated when a dispatch was modified:
+
+        If it was currently running and the modification now says
+        it should not be running or running with different parameters,
+        then a message will be sent.
+
+        In other words: Any change that is expected to make an actor start, stop
+        or reconfigure itself with new parameters causes a message to be
+        sent.
+
+        A non-exhaustive list of possible changes that will cause a message to be sent:
+         - The normal scheduled start_time has been reached
+         - The duration of the dispatch has been modified
+         - The start_time has been modified to be in the future
+         - The component selection changed
+         - The active status changed
+         - The dry_run status changed
+         - The payload changed
+         - The dispatch was deleted
+
+        Note: Reaching the end time (start_time + duration) will not
+        send a message, except when it was reached by modifying the duration.
+
+
+        Returns:
+            A new receiver for dispatches whose running status changed.
+        """
+        return self._running_state_channel

frequenz/dispatch/_event.py

@@ -0,0 +1,40 @@
+# License: MIT
+# Copyright © 2024 Frequenz Energy-as-a-Service GmbH
+
+"""Dispatch lifecycle events."""
+
+from dataclasses import dataclass
+
+from ._dispatch import Dispatch
+
+
+@dataclass(frozen=True)
+class Created:
+    """A dispatch created event."""
+
+    dispatch: Dispatch
+    """The dispatch that was created."""
+
+
+@dataclass(frozen=True)
+class Updated:
+    """A dispatch updated event."""
+
+    dispatch: Dispatch
+    """The dispatch that was updated."""
+
+
+@dataclass(frozen=True)
+class Deleted:
+    """A dispatch deleted event."""
+
+    dispatch: Dispatch
+    """The dispatch that was deleted."""
+
+
+DispatchEvent = Created | Updated | Deleted
+"""Type that is sent over the channel for dispatch updates.
+
+This type is used to send dispatches that were created, updated or deleted
+over the channel.
+"""

frequenz/dispatch/actor.py

@@ -0,0 +1,256 @@
+# License: MIT
+# Copyright © 2024 Frequenz Energy-as-a-Service GmbH
+
+"""The dispatch actor."""
+
+import asyncio
+import logging
+from datetime import datetime, timedelta, timezone
+
+import grpc.aio
+from frequenz.channels import Sender
+from frequenz.channels.timer import SkipMissedAndDrift, Timer
+from frequenz.client.dispatch import Client
+from frequenz.sdk.actor import Actor
+
+from ._dispatch import Dispatch, RunningState
+from ._event import Created, Deleted, DispatchEvent, Updated
+
+_MAX_AHEAD_SCHEDULE = timedelta(hours=5)
+"""The maximum time ahead to schedule a dispatch.
+
+We don't want to schedule dispatches too far ahead,
+as they could start drifting if the delay is too long.
+
+This also prevents us from scheduling too many dispatches at once.
+
+The exact value is not important, but should be a few hours and not more than a day.
+"""
+
+_DEFAULT_POLL_INTERVAL = timedelta(seconds=10)
+"""The default interval to poll the API for dispatch changes."""
+
+_logger = logging.getLogger(__name__)
+"""The logger for this module."""
+
+
+class DispatchingActor(Actor):
+    """Dispatch actor.
+
+    This actor is responsible for handling dispatches for a microgrid.
+
+    This means staying in sync with the API and scheduling
+    dispatches as necessary.
+    """
+
+    # pylint: disable=too-many-arguments
+    def __init__(
+        self,
+        microgrid_id: int,
+        client: Client,
+        lifecycle_updates_sender: Sender[DispatchEvent],
+        running_state_change_sender: Sender[Dispatch],
+        poll_interval: timedelta = _DEFAULT_POLL_INTERVAL,
+    ) -> None:
+        """Initialize the actor.
+
+        Args:
+            microgrid_id: The microgrid ID to handle dispatches for.
+            client: The client to use for fetching dispatches.
+            lifecycle_updates_sender: A sender for dispatch lifecycle events.
+            running_state_change_sender: A sender for dispatch running state changes.
+            poll_interval: The interval to poll the API for dispatche changes.
+        """
+        super().__init__(name="dispatch")
+
+        self._client = client
+        self._dispatches: dict[int, Dispatch] = {}
+        self._scheduled: dict[int, asyncio.Task[None]] = {}
+        self._microgrid_id = microgrid_id
+        self._lifecycle_updates_sender = lifecycle_updates_sender
+        self._running_state_change_sender = running_state_change_sender
+        self._poll_timer = Timer(poll_interval, SkipMissedAndDrift())
+
+    async def _run(self) -> None:
+        """Run the actor."""
+        self._poll_timer.reset()
+        try:
+            async for _ in self._poll_timer:
+                await self._fetch()
+        except asyncio.CancelledError:
+            for task in self._scheduled.values():
+                task.cancel()
+            raise
+
+    async def _fetch(self) -> None:
+        """Fetch all relevant dispatches."""
+        old_dispatches = self._dispatches
+        self._dispatches = {}
+
+        try:
+            _logger.info("Fetching dispatches for microgrid %s", self._microgrid_id)
+            async for client_dispatch in self._client.list(
+                microgrid_id=self._microgrid_id
+            ):
+                dispatch = Dispatch(client_dispatch)
+
+                self._dispatches[dispatch.id] = Dispatch(client_dispatch)
+                old_dispatch = old_dispatches.pop(dispatch.id, None)
+                if not old_dispatch:
+                    self._update_dispatch_schedule(dispatch, None)
+                    _logger.info("New dispatch: %s", dispatch)
+                    await self._lifecycle_updates_sender.send(
+                        Created(dispatch=dispatch)
+                    )
+                elif dispatch.update_time != old_dispatch.update_time:
+                    self._update_dispatch_schedule(dispatch, old_dispatch)
+                    _logger.info("Updated dispatch: %s", dispatch)
+                    await self._lifecycle_updates_sender.send(
+                        Updated(dispatch=dispatch)
+                    )
+
+                    if self._running_state_change(dispatch, old_dispatch):
+                        await self._send_running_state_change(dispatch)
+
+        except grpc.aio.AioRpcError as error:
+            _logger.error("Error fetching dispatches: %s", error)
+            self._dispatches = old_dispatches
+            return
+
+        for dispatch in old_dispatches.values():
+            _logger.info("Deleted dispatch: %s", dispatch)
+            dispatch._set_deleted()  # pylint: disable=protected-access
+            await self._lifecycle_updates_sender.send(Deleted(dispatch=dispatch))
+            if task := self._scheduled.pop(dispatch.id, None):
+                task.cancel()
+
+            if self._running_state_change(None, dispatch):
+                await self._send_running_state_change(dispatch)
+
+    def _update_dispatch_schedule(
+        self, dispatch: Dispatch, old_dispatch: Dispatch | None
+    ) -> None:
+        """Update the schedule for a dispatch.
+
+        Schedules, reschedules or cancels the dispatch based on the start_time
+        and active status.
+
+        For example:
+            * when the start_time changes, the dispatch is rescheduled
+            * when the dispatch is deactivated, the dispatch is cancelled
+
+        Args:
+            dispatch: The dispatch to update the schedule for.
+            old_dispatch: The old dispatch, if available.
+        """
+        if (
+            old_dispatch
+            and old_dispatch.active
+            and old_dispatch.start_time != dispatch.start_time
+        ):
+            if task := self._scheduled.pop(dispatch.id, None):
+                task.cancel()
+
+        if dispatch.active and dispatch.id not in self._scheduled:
+            self._scheduled[dispatch.id] = asyncio.create_task(
+                self._schedule_task(dispatch)
+            )
+
+    async def _schedule_task(self, dispatch: Dispatch) -> None:
+        """Wait for a dispatch to become ready.
+
+        Waits for the dispatches next run and then notifies that it is ready.
+
+        Args:
+            dispatch: The dispatch to schedule.
+        """
+
+        def next_run_info() -> tuple[datetime, datetime] | None:
+            now = datetime.now(tz=timezone.utc)
+            next_run = dispatch.next_run_after(now)
+
+            if next_run is None:
+                return None
+
+            return now, next_run
+
+        while pair := next_run_info():
+            now, next_time = pair
+
+            if next_time - now > _MAX_AHEAD_SCHEDULE:
+                await asyncio.sleep(_MAX_AHEAD_SCHEDULE.total_seconds())
+                continue
+
+            _logger.info("Dispatch %s scheduled for %s", dispatch.id, next_time)
+            await asyncio.sleep((next_time - now).total_seconds())
+
+            _logger.info("Dispatch ready: %s", dispatch)
+            await self._running_state_change_sender.send(dispatch)
+
+        _logger.info("Dispatch finished: %s", dispatch)
+        self._scheduled.pop(dispatch.id)
+
+    def _running_state_change(
+        self, updated_dispatch: Dispatch | None, previous_dispatch: Dispatch | None
+    ) -> bool:
+        """Check if the running state of a dispatch has changed.
+
+        Checks if any of the running state changes to the dispatch
+        require a new message to be sent to the actor so that it can potentially
+        change its runtime configuration or start/stop itself.
+
+        Also checks if a dispatch update was not sent due to connection issues
+        in which case we need to send the message now.
+
+        Args:
+            updated_dispatch: The new dispatch, if available.
+            previous_dispatch: The old dispatch, if available.
+
+        Returns:
+            True if the running state has changed, False otherwise.
+        """
+        # New dispatch
+        if previous_dispatch is None:
+            assert updated_dispatch is not None
+
+            # Client was not informed about the dispatch, do it now
+            # pylint: disable=protected-access
+            if not updated_dispatch._running_status_notified:
+                return True
+
+        # Deleted dispatch
+        if updated_dispatch is None:
+            assert previous_dispatch is not None
+            return (
+                previous_dispatch.running(previous_dispatch.type)
+                == RunningState.RUNNING
+            )
+
+        # If any of the runtime attributes changed, we need to send a message
+        runtime_state_attributes = [
+            "running",
+            "type",
+            "selector",
+            "duration",
+            "dry_run",
+            "payload",
+        ]
+
+        for attribute in runtime_state_attributes:
+            if getattr(updated_dispatch, attribute) != getattr(
+                previous_dispatch, attribute
+            ):
+                return True
+
+        return False
+
+    async def _send_running_state_change(self, dispatch: Dispatch) -> None:
+        """Send a running state change message.
+
+        Args:
+            dispatch: The dispatch that changed.
+        """
+        await self._running_state_change_sender.send(dispatch)
+        # Update the last sent notification time
+        # so we know if this change was already sent
+        dispatch._set_running_status_notified()  # pylint: disable=protected-access

frequenz/dispatch/conftest.py

@@ -0,0 +1,13 @@
+# License: MIT
+# Copyright © 2024 Frequenz Energy-as-a-Service GmbH
+
+"""Validate docstring code examples.
+
+Code examples are often wrapped in triple backticks (```) within docstrings.
+This plugin extracts these code examples and validates them using pylint.
+"""
+
+from frequenz.repo.config.pytest import examples
+from sybil import Sybil
+
+pytest_collect_file = Sybil(**examples.get_sybil_arguments()).pytest()

frequenz_dispatch-0.1.0.dist-info/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright © 2024 Frequenz Energy-as-a-Service GmbH
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

frequenz_dispatch-0.1.0.dist-info/METADATA

@@ -0,0 +1,149 @@
+Metadata-Version: 2.1
+Name: frequenz-dispatch
+Version: 0.1.0
+Summary: A highlevel interface for the dispatch API
+Author-email: Frequenz Energy-as-a-Service GmbH <floss@frequenz.com>
+License: MIT
+Project-URL: Documentation, https://frequenz-floss.github.io/frequenz-dispatch-python/
+Project-URL: Changelog, https://github.com/frequenz-floss/frequenz-dispatch-python/releases
+Project-URL: Issues, https://github.com/frequenz-floss/frequenz-dispatch-python/issues
+Project-URL: Repository, https://github.com/frequenz-floss/frequenz-dispatch-python
+Project-URL: Support, https://github.com/frequenz-floss/frequenz-dispatch-python/discussions/categories/support
+Keywords: frequenz,python,actor,frequenz-dispatch,dispatch,highlevel,api
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Typing :: Typed
+Requires-Python: <4,>=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: python-dateutil <3.0,>=2.8.2
+Requires-Dist: typing-extensions ==4.11.0
+Requires-Dist: frequenz-sdk ==v1.0.0-rc6
+Requires-Dist: frequenz-channels ==1.0.0
+Requires-Dist: frequenz-api-dispatch <0.14,>=0.13.0
+Requires-Dist: frequenz-client-dispatch ==0.2.0
+Requires-Dist: frequenz-client-base <0.4.0,>=0.3.0
+Requires-Dist: frequenz-client-common <0.2.0,>=0.1.0
+Provides-Extra: dev
+Requires-Dist: frequenz-dispatch[dev-flake8,dev-formatting,dev-mkdocs,dev-mypy,dev-noxfile,dev-pylint,dev-pytest] ; extra == 'dev'
+Provides-Extra: dev-flake8
+Requires-Dist: flake8 ==7.0.0 ; extra == 'dev-flake8'
+Requires-Dist: flake8-docstrings ==1.7.0 ; extra == 'dev-flake8'
+Requires-Dist: flake8-pyproject ==1.2.3 ; extra == 'dev-flake8'
+Requires-Dist: pydoclint ==0.4.1 ; extra == 'dev-flake8'
+Requires-Dist: pydocstyle ==6.3.0 ; extra == 'dev-flake8'
+Provides-Extra: dev-formatting
+Requires-Dist: black ==24.4.2 ; extra == 'dev-formatting'
+Requires-Dist: isort ==5.13.2 ; extra == 'dev-formatting'
+Provides-Extra: dev-mkdocs
+Requires-Dist: black ==24.4.2 ; extra == 'dev-mkdocs'
+Requires-Dist: Markdown ==3.6 ; extra == 'dev-mkdocs'
+Requires-Dist: mike ==2.1.0 ; extra == 'dev-mkdocs'
+Requires-Dist: mkdocs-gen-files ==0.5.0 ; extra == 'dev-mkdocs'
+Requires-Dist: mkdocs-literate-nav ==0.6.1 ; extra == 'dev-mkdocs'
+Requires-Dist: mkdocs-macros-plugin ==1.0.5 ; extra == 'dev-mkdocs'
+Requires-Dist: mkdocs-material ==9.5.20 ; extra == 'dev-mkdocs'
+Requires-Dist: mkdocstrings[python] ==0.25.0 ; extra == 'dev-mkdocs'
+Requires-Dist: frequenz-repo-config[lib] ==0.9.2 ; extra == 'dev-mkdocs'
+Provides-Extra: dev-mypy
+Requires-Dist: mypy ==1.10.0 ; extra == 'dev-mypy'
+Requires-Dist: types-Markdown ==3.6.0.20240316 ; extra == 'dev-mypy'
+Requires-Dist: types-python-dateutil ==2.9.0.20240316 ; extra == 'dev-mypy'
+Requires-Dist: frequenz-dispatch[dev-mkdocs,dev-noxfile,dev-pytest] ; extra == 'dev-mypy'
+Provides-Extra: dev-noxfile
+Requires-Dist: uv ==0.1.39 ; extra == 'dev-noxfile'
+Requires-Dist: nox ==2024.4.15 ; extra == 'dev-noxfile'
+Requires-Dist: frequenz-repo-config[lib] ==0.9.2 ; extra == 'dev-noxfile'
+Provides-Extra: dev-pylint
+Requires-Dist: pylint ==3.1.0 ; extra == 'dev-pylint'
+Requires-Dist: frequenz-dispatch[dev-mkdocs,dev-noxfile,dev-pytest] ; extra == 'dev-pylint'
+Provides-Extra: dev-pytest
+Requires-Dist: pytest ==8.2.0 ; extra == 'dev-pytest'
+Requires-Dist: frequenz-repo-config[extra-lint-examples] ==0.9.2 ; extra == 'dev-pytest'
+Requires-Dist: pytest-mock ==3.14.0 ; extra == 'dev-pytest'
+Requires-Dist: pytest-asyncio ==0.23.6 ; extra == 'dev-pytest'
+Requires-Dist: async-solipsism ==0.6 ; extra == 'dev-pytest'
+Requires-Dist: time-machine ==2.14.1 ; extra == 'dev-pytest'
+
+# Dispatch Highlevel Interface
+
+[![Build Status](https://github.com/frequenz-floss/frequenz-dispatch-python/actions/workflows/ci.yaml/badge.svg)](https://github.com/frequenz-floss/frequenz-dispatch-python/actions/workflows/ci.yaml)
+[![PyPI Package](https://img.shields.io/pypi/v/frequenz-dispatch)](https://pypi.org/project/frequenz-dispatch/)
+[![Docs](https://img.shields.io/badge/docs-latest-informational)](https://frequenz-floss.github.io/frequenz-dispatch-python/)
+
+## Introduction
+
+A highlevel interface for the dispatch API.
+
+See [the documentation](https://frequenz-floss.github.io/frequenz-dispatch-python/v0.1/reference/frequenz/dispatch) for more information.
+
+## Usage
+
+The [`Dispatcher` class](https://frequenz-floss.github.io/frequenz-dispatch-python/v0.1/reference/frequenz/dispatch/#frequenz.dispatch.Dispatcher), the main entry point for the API, provides two channels:
+
+* [Lifecycle events](https://frequenz-floss.github.io/frequenz-dispatch-python/v0.1/reference/frequenz/dispatch/#frequenz.dispatch.Dispatcher.lifecycle_events): A channel that sends a message whenever a [Dispatch][frequenz.dispatch.Dispatch] is created, updated or deleted.
+* [Running status change](https://frequenz-floss.github.io/frequenz-dispatch-python/v0.1/reference/frequenz/dispatch/#frequenz.dispatch.Dispatcher.running_status_change): Sends a dispatch message whenever a dispatch is ready to be executed according to the schedule or the running status of the dispatch changed in a way that could potentially require the actor to start, stop or reconfigure itself.
+
+### Example using the running status change channel
+
+```python
+import os
+import grpc.aio
+from unittest.mock import MagicMock
+
+async def run():
+    host = os.getenv("DISPATCH_API_HOST", "localhost")
+    port = os.getenv("DISPATCH_API_PORT", "50051")
+
+    service_address = f"{host}:{port}"
+    grpc_channel = grpc.aio.insecure_channel(service_address)
+    microgrid_id = 1
+    dispatcher = Dispatcher(microgrid_id, grpc_channel, service_address)
+    await dispatcher.start()
+
+    actor = MagicMock() # replace with your actor
+
+    changed_running_status_rx = dispatcher.running_status_change.new_receiver()
+
+    async for dispatch in changed_running_status_rx:
+        match dispatch.running("DEMO_TYPE"):
+            case RunningState.RUNNING:
+                print(f"Executing dispatch {dispatch.id}, due on {dispatch.start_time}")
+                if actor.is_running:
+                    actor.reconfigure(
+                        components=dispatch.selector,
+                        run_parameters=dispatch.payload, # custom actor parameters
+                        dry_run=dispatch.dry_run,
+                        until=dispatch.until,
+                    )  # this will reconfigure the actor
+                else:
+                    # this will start a new actor with the given components
+                    # and run it for the duration of the dispatch
+                    actor.start(
+                        components=dispatch.selector,
+                        run_parameters=dispatch.payload, # custom actor parameters
+                        dry_run=dispatch.dry_run,
+                        until=dispatch.until,
+                    )
+            case RunningState.STOPPED:
+                actor.stop()  # this will stop the actor
+            case RunningState.DIFFERENT_TYPE:
+                pass  # dispatch not for this type
+```
+
+## Supported Platforms
+
+The following platforms are officially supported (tested):
+
+- **Python:** 3.11
+- **Operating System:** Ubuntu Linux 20.04
+- **Architectures:** amd64, arm64
+
+## Contributing
+
+If you want to know how to build this project and contribute to it, please
+check out the [Contributing Guide](CONTRIBUTING.md).

frequenz_dispatch-0.1.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+frequenz/dispatch/__init__.py,sha256=jHsYSQPqc9TAOojlARbb63UsulHv5_gfyXb_mpkIWJQ,822
+frequenz/dispatch/_dispatch.py,sha256=NAhGufnIuQgYbef-tgqwCdq503khW_BEQM7JsXnomDc,7959
+frequenz/dispatch/_dispatcher.py,sha256=uXHdG43ig7nuFXkFF3payCFwi_OyC02Rpltj_bOVViU,9509
+frequenz/dispatch/_event.py,sha256=70fhuxMJ4CY_Gi-9kGh5URFpguD2WeXUgn3g1tevbTQ,801
+frequenz/dispatch/actor.py,sha256=JnIiTwqPuuhUfnVODj7YfSW0WAZzDTkRwZO1A3IwAHA,9226
+frequenz/dispatch/conftest.py,sha256=kxmvkzTdvGfh7SiDINIFX0FG9PU0EoKROl9YY75zN8w,409
+frequenz/dispatch/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+frequenz_dispatch-0.1.0.dist-info/LICENSE,sha256=zt0sW1KvE_KWE2ILOabrQYlfOoP0zUZXC3xCLrzGpIA,1089
+frequenz_dispatch-0.1.0.dist-info/METADATA,sha256=8sZYjNr1gztS7sjtbF08YH1j_iTYjaE98XNYtIzbQRk,7580
+frequenz_dispatch-0.1.0.dist-info/WHEEL,sha256=GJ7t_kWBFywbagK5eo9IoUwLW6oyOeTKmQ-9iHFVNxQ,92
+frequenz_dispatch-0.1.0.dist-info/top_level.txt,sha256=x08GRcWytsyKXa2Ayme9e5pg3L5Kcq6lw_BaQmToMO4,9
+frequenz_dispatch-0.1.0.dist-info/RECORD,,

frequenz_dispatch-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: bdist_wheel (0.43.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

frequenz_dispatch-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+frequenz