frequenz-dispatch 0.3.0__tar.gz → 0.3.2__tar.gz

{frequenz-dispatch-0.3.0/src/frequenz_dispatch.egg-info → frequenz-dispatch-0.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: frequenz-dispatch
-Version: 0.3.0
+Version: 0.3.2
 Summary: A highlevel interface for the dispatch API
 Author-email: Frequenz Energy-as-a-Service GmbH <floss@frequenz.com>
 License: MIT

frequenz-dispatch-0.3.2/RELEASE_NOTES.md

@@ -0,0 +1,5 @@
+# Dispatch Highlevel Interface Release Notes
+
+## Summary
+
+* This fixes a crash when the `YEARLY` frequency is used in a dispatch.

{frequenz-dispatch-0.3.0 → frequenz-dispatch-0.3.2}/pyproject.toml

@@ -39,9 +39,9 @@ dependencies = [
   # Make sure to update the version for cross-referencing also in the
   # mkdocs.yml file when changing the version here (look for the config key
   # plugins.mkdocstrings.handlers.python.import)
-  "frequenz-sdk == 1.0.0-rc900",
-  "frequenz-channels >= 1.1.0, < 2.0.0",
-  "frequenz-client-dispatch >= 0.6.0, < 0.7.0",
+  "frequenz-sdk >= 1.0.0-rc900, < 1.0.0-rc1000",
+  "frequenz-channels >= 1.2.0, < 2.0.0",
+  "frequenz-client-dispatch >= 0.7.1, < 0.8.0",
 ]
 dynamic = ["version"]
 
@@ -54,7 +54,7 @@ dev-flake8 = [
   "flake8 == 7.1.1",
   "flake8-docstrings == 1.7.0",
   "flake8-pyproject == 1.2.3",  # For reading the flake8 config from pyproject.toml
-  "pydoclint == 0.5.6",
+  "pydoclint == 0.5.9",
   "pydocstyle == 6.3.0",
 ]
 dev-formatting = ["black == 24.8.0", "isort == 5.13.2"]
@@ -64,32 +64,32 @@ dev-mkdocs = [
   "mike == 2.1.3",
   "mkdocs-gen-files == 0.5.0",
   "mkdocs-literate-nav == 0.6.1",
-  "mkdocs-macros-plugin == 1.0.5",
-  "mkdocs-material == 9.5.34",
-  "mkdocstrings[python] == 0.25.2",
-  "mkdocstrings-python == 1.10.9",
+  "mkdocs-macros-plugin == 1.2.0",
+  "mkdocs-material == 9.5.39",
+  "mkdocstrings[python] == 0.26.1",
+  "mkdocstrings-python == 1.11.1",
   "frequenz-repo-config[lib] == 0.10.0",
 ]
 dev-mypy = [
   "mypy == 1.11.2",
   "grpc-stubs == 1.53.0.5",               # This dependency introduces breaking changes in patch releases
   "types-Markdown == 3.7.0.20240822",
-  "types-python-dateutil==2.9.0.20240821",
+  "types-python-dateutil==2.9.0.20240906",
   # For checking the noxfile, docs/ script, and tests
   "frequenz-dispatch[dev-mkdocs,dev-noxfile,dev-pytest]",
 ]
 dev-noxfile = [
-  "uv == 0.4.1",
+  "uv == 0.4.17",
   "nox == 2024.4.15",
   "frequenz-repo-config[lib] == 0.10.0",
 ]
 dev-pylint = [
-  "pylint == 3.2.7",
+  "pylint == 3.3.1",
   # For checking the noxfile, docs/ script, and tests
   "frequenz-dispatch[dev-mkdocs,dev-noxfile,dev-pytest]",
 ]
 dev-pytest = [
-  "pytest == 8.3.2",
+  "pytest == 8.3.3",
   "frequenz-repo-config[extra-lint-examples] == 0.10.0",
   "pytest-mock == 3.14.0",
   "pytest-asyncio == 0.24.0",
@@ -165,6 +165,7 @@ disable = [
 [tool.pytest.ini_options]
 testpaths = ["tests", "src"]
 asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"
 required_plugins = ["pytest-asyncio", "pytest-mock"]
 
 [tool.mypy]

{frequenz-dispatch-0.3.0 → frequenz-dispatch-0.3.2}/src/frequenz/dispatch/__init__.py

@@ -7,6 +7,8 @@ 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.
+* [DispatchManagingActor][frequenz.dispatch.DispatchManagingActor]: An actor to
+    manage other actors based on incoming dispatches.
 * [Created][frequenz.dispatch.Created],
   [Updated][frequenz.dispatch.Updated],
   [Deleted][frequenz.dispatch.Deleted]: Dispatch event types.
@@ -16,6 +18,7 @@ A small overview of the most important classes in this module:
 from ._dispatch import Dispatch, RunningState
 from ._dispatcher import Dispatcher, ReceiverFetcher
 from ._event import Created, Deleted, DispatchEvent, Updated
+from ._managing_actor import DispatchManagingActor, DispatchUpdate
 
 __all__ = [
     "Created",
@@ -26,4 +29,6 @@ __all__ = [
     "Updated",
     "Dispatch",
     "RunningState",
+    "DispatchManagingActor",
+    "DispatchUpdate",
 ]

{frequenz-dispatch-0.3.0 → frequenz-dispatch-0.3.2}/src/frequenz/dispatch/_dispatch.py

@@ -118,6 +118,13 @@ class Dispatch(BaseDispatch):
             return RunningState.STOPPED
 
         now = datetime.now(tz=timezone.utc)
+
+        if now < self.start_time:
+            return RunningState.STOPPED
+        # A dispatch without duration is always running once it started
+        if self.duration is None:
+            return RunningState.RUNNING
+
         if until := self._until(now):
             return RunningState.RUNNING if now < until else RunningState.STOPPED
 
@@ -185,6 +192,7 @@ class Dispatch(BaseDispatch):
         if (
             not self.recurrence.frequency
             or self.recurrence.frequency == Frequency.UNSPECIFIED
+            or self.duration is None  # Infinite duration
         ):
             if after > self.start_time:
                 return None
@@ -236,7 +244,13 @@ class Dispatch(BaseDispatch):
 
         Returns:
             The time when the dispatch should end or None if the dispatch is not running.
+
+        Raises:
+            ValueError: If the dispatch has no duration.
         """
+        if self.duration is None:
+            raise ValueError("_until: Dispatch has no duration")
+
         if (
             not self.recurrence.frequency
             or self.recurrence.frequency == Frequency.UNSPECIFIED

frequenz-dispatch-0.3.2/src/frequenz/dispatch/_managing_actor.py

@@ -0,0 +1,180 @@
+# License: All rights reserved
+# Copyright © 2024 Frequenz Energy-as-a-Service GmbH
+
+"""Helper class to manage actors based on dispatches."""
+
+import logging
+from dataclasses import dataclass
+from typing import Any, Set
+
+from frequenz.channels import Receiver, Sender
+from frequenz.client.dispatch.types import ComponentSelector
+from frequenz.sdk.actor import Actor
+
+from ._dispatch import Dispatch, RunningState
+
+_logger = logging.getLogger(__name__)
+
+
+@dataclass(frozen=True, kw_only=True)
+class DispatchUpdate:
+    """Event emitted when the dispatch changes."""
+
+    components: ComponentSelector
+    """Components to be used."""
+
+    dry_run: bool
+    """Whether this is a dry run."""
+
+    options: dict[str, Any]
+    """Additional options."""
+
+
+class DispatchManagingActor(Actor):
+    """Helper class to manage actors based on dispatches.
+
+    Example usage:
+
+    ```python
+    import os
+    import asyncio
+    from frequenz.dispatch import Dispatcher, DispatchManagingActor, DispatchUpdate
+    from frequenz.client.dispatch.types import ComponentSelector
+    from frequenz.client.common.microgrid.components import ComponentCategory
+
+    from frequenz.channels import Receiver, Broadcast
+
+    class MyActor(Actor):
+        def __init__(self, updates_channel: Receiver[DispatchUpdate]):
+            super().__init__()
+            self._updates_channel = updates_channel
+            self._dry_run: bool
+            self._options : dict[str, Any]
+
+        async def _run(self) -> None:
+            while True:
+                update = await self._updates_channel.receive()
+                print("Received update:", update)
+
+                self.set_components(update.components)
+                self._dry_run = update.dry_run
+                self._options = update.options
+
+        def set_components(self, components: ComponentSelector) -> None:
+            match components:
+                case [int(), *_] as component_ids:
+                    print("Dispatch: Setting components to %s", components)
+                case [ComponentCategory.BATTERY, *_]:
+                    print("Dispatch: Using all battery components")
+                case unsupported:
+                    print(
+                        "Dispatch: Requested an unsupported selector %r, "
+                        "but only component IDs or category BATTERY are supported.",
+                        unsupported,
+                    )
+
+    async def run():
+        url = os.getenv("DISPATCH_API_URL", "grpc://fz-0004.frequenz.io:50051")
+        key  = os.getenv("DISPATCH_API_KEY", "some-key")
+
+        microgrid_id = 1
+
+        dispatcher = Dispatcher(
+            microgrid_id=microgrid_id,
+            server_url=url,
+            key=key
+        )
+
+        # Create update channel to receive dispatch update events pre-start and mid-run
+        dispatch_updates_channel = Broadcast[DispatchUpdate](name="dispatch_updates_channel")
+
+        # Start actor and give it an dispatch updates channel receiver
+        my_actor = MyActor(dispatch_updates_channel.new_receiver())
+
+        status_receiver = dispatcher.running_status_change.new_receiver()
+
+        managing_actor = DispatchManagingActor(
+            actor=my_actor,
+            dispatch_type="EXAMPLE",
+            running_status_receiver=status_receiver,
+            updates_sender=dispatch_updates_channel.new_sender(),
+        )
+
+        await asyncio.gather(dispatcher.start(), managing_actor.start())
+    ```
+    """
+
+    def __init__(
+        self,
+        actor: Actor | Set[Actor],
+        dispatch_type: str,
+        running_status_receiver: Receiver[Dispatch],
+        updates_sender: Sender[DispatchUpdate] | None = None,
+    ) -> None:
+        """Initialize the dispatch handler.
+
+        Args:
+            actor: A set of actors or a single actor to manage.
+            dispatch_type: The type of dispatches to handle.
+            running_status_receiver: The receiver for dispatch running status changes.
+            updates_sender: The sender for dispatch events
+        """
+        super().__init__()
+        self._dispatch_rx = running_status_receiver
+        self._actors = frozenset([actor] if isinstance(actor, Actor) else actor)
+        self._dispatch_type = dispatch_type
+        self._updates_sender = updates_sender
+
+    def _start_actors(self) -> None:
+        """Start all actors."""
+        for actor in self._actors:
+            if actor.is_running:
+                _logger.warning("Actor %s is already running", actor.name)
+            else:
+                actor.start()
+
+    async def _stop_actors(self, msg: str) -> None:
+        """Stop all actors.
+
+        Args:
+            msg: The message to be passed to the actors being stopped.
+        """
+        for actor in self._actors:
+            if actor.is_running:
+                await actor.stop(msg)
+            else:
+                _logger.warning("Actor %s is not running", actor.name)
+
+    async def _run(self) -> None:
+        """Wait for dispatches and handle them."""
+        async for dispatch in self._dispatch_rx:
+            await self._handle_dispatch(dispatch=dispatch)
+
+    async def _handle_dispatch(self, dispatch: Dispatch) -> None:
+        """Handle a dispatch.
+
+        Args:
+            dispatch: The dispatch to handle.
+        """
+        running = dispatch.running(self._dispatch_type)
+        match running:
+            case RunningState.STOPPED:
+                _logger.info("Stopped by dispatch %s", dispatch.id)
+                await self._stop_actors("Dispatch stopped")
+            case RunningState.RUNNING:
+                if self._updates_sender is not None:
+                    _logger.info("Updated by dispatch %s", dispatch.id)
+                    await self._updates_sender.send(
+                        DispatchUpdate(
+                            components=dispatch.selector,
+                            dry_run=dispatch.dry_run,
+                            options=dispatch.payload,
+                        )
+                    )
+
+                _logger.info("Started by dispatch %s", dispatch.id)
+                self._start_actors()
+            case RunningState.DIFFERENT_TYPE:
+                _logger.debug(
+                    "Unknown dispatch! Ignoring dispatch of type %s", dispatch.type
+                )

frequenz-dispatch-0.3.2/src/frequenz/dispatch/actor.py

@@ -0,0 +1,347 @@
+# License: MIT
+# Copyright © 2024 Frequenz Energy-as-a-Service GmbH
+
+"""The dispatch actor."""
+
+import logging
+from datetime import datetime, timedelta, timezone
+from heapq import heappop, heappush
+
+import grpc.aio
+from frequenz.channels import Sender, select, selected_from
+from frequenz.channels.timer import SkipMissedAndResync, Timer
+from frequenz.client.dispatch import Client
+from frequenz.client.dispatch.types import Event
+from frequenz.sdk.actor import Actor
+
+from ._dispatch import Dispatch, RunningState
+from ._event import Created, Deleted, DispatchEvent, Updated
+
+_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],
+    ) -> 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.
+        """
+        super().__init__(name="dispatch")
+
+        self._client = client
+        self._dispatches: dict[int, Dispatch] = {}
+        self._microgrid_id = microgrid_id
+        self._lifecycle_updates_sender = lifecycle_updates_sender
+        self._running_state_change_sender = running_state_change_sender
+        self._next_event_timer = Timer(
+            timedelta(seconds=100), SkipMissedAndResync(), auto_start=False
+        )
+        """The timer to schedule the next event.
+
+        Interval is chosen arbitrarily, as it will be reset on the first event.
+        """
+
+        self._scheduled_events: list[tuple[datetime, Dispatch]] = []
+        """The scheduled events, sorted by time.
+
+        Each event is a tuple of the scheduled time and the dispatch.
+        heapq is used to keep the list sorted by time, so the next event is
+        always at index 0.
+        """
+
+    async def _run(self) -> None:
+        """Run the actor."""
+        _logger.info("Starting dispatch actor for microgrid %s", self._microgrid_id)
+
+        # Initial fetch
+        await self._fetch()
+
+        stream = self._client.stream(microgrid_id=self._microgrid_id)
+
+        # Streaming updates
+        async for selected in select(self._next_event_timer, stream):
+            if selected_from(selected, self._next_event_timer):
+                if not self._scheduled_events:
+                    continue
+                _logger.debug(
+                    "Executing scheduled event: %s", self._scheduled_events[0][1]
+                )
+                await self._execute_scheduled_event(heappop(self._scheduled_events)[1])
+            elif selected_from(selected, stream):
+                _logger.debug("Received dispatch event: %s", selected.message)
+                dispatch = Dispatch(selected.message.dispatch)
+                match selected.message.event:
+                    case Event.CREATED:
+                        self._dispatches[dispatch.id] = dispatch
+                        await self._update_dispatch_schedule_and_notify(dispatch, None)
+                        await self._lifecycle_updates_sender.send(
+                            Created(dispatch=dispatch)
+                        )
+                    case Event.UPDATED:
+                        await self._update_dispatch_schedule_and_notify(
+                            dispatch, self._dispatches[dispatch.id]
+                        )
+                        self._dispatches[dispatch.id] = dispatch
+                        await self._lifecycle_updates_sender.send(
+                            Updated(dispatch=dispatch)
+                        )
+                    case Event.DELETED:
+                        self._dispatches.pop(dispatch.id)
+                        await self._update_dispatch_schedule_and_notify(None, dispatch)
+
+                        dispatch._set_deleted()  # pylint: disable=protected-access
+                        await self._lifecycle_updates_sender.send(
+                            Deleted(dispatch=dispatch)
+                        )
+
+    async def _execute_scheduled_event(self, dispatch: Dispatch) -> None:
+        """Execute a scheduled event.
+
+        Args:
+            dispatch: The dispatch to execute.
+        """
+        await self._send_running_state_change(dispatch)
+
+        # The timer is always a tiny bit delayed, so we need to check if the
+        # actor is supposed to be running now (we're assuming it wasn't already
+        # running, as all checks are done before scheduling)
+        if dispatch.running(dispatch.type) == RunningState.RUNNING:
+            # If it should be running, schedule the stop event
+            self._schedule_stop(dispatch)
+        # If the actor is not running, we need to schedule the next start
+        else:
+            self._schedule_start(dispatch)
+
+        self._update_timer()
+
+    async def _fetch(self) -> None:
+        """Fetch all relevant dispatches using list.
+
+        This is used for the initial fetch and for re-fetching all dispatches
+        if the connection was lost.
+        """
+        old_dispatches = self._dispatches
+        self._dispatches = {}
+
+        try:
+            _logger.info("Fetching dispatches for microgrid %s", self._microgrid_id)
+            async for page in self._client.list(microgrid_id=self._microgrid_id):
+                for client_dispatch in page:
+                    dispatch = Dispatch(client_dispatch)
+
+                    self._dispatches[dispatch.id] = Dispatch(client_dispatch)
+                    old_dispatch = old_dispatches.pop(dispatch.id, None)
+                    if not old_dispatch:
+                        _logger.info("New dispatch: %s", dispatch)
+                        await self._update_dispatch_schedule_and_notify(dispatch, None)
+                        await self._lifecycle_updates_sender.send(
+                            Created(dispatch=dispatch)
+                        )
+                    elif dispatch.update_time != old_dispatch.update_time:
+                        _logger.info("Updated dispatch: %s", dispatch)
+                        await self._update_dispatch_schedule_and_notify(
+                            dispatch, old_dispatch
+                        )
+                        await self._lifecycle_updates_sender.send(
+                            Updated(dispatch=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)
+            await self._lifecycle_updates_sender.send(Deleted(dispatch=dispatch))
+            await self._update_dispatch_schedule_and_notify(None, dispatch)
+
+            # Set deleted only here as it influences the result of dispatch.running()
+            # which is used in above in _running_state_change
+            dispatch._set_deleted()  # pylint: disable=protected-access
+            await self._lifecycle_updates_sender.send(Deleted(dispatch=dispatch))
+
+    async def _update_dispatch_schedule_and_notify(
+        self, dispatch: Dispatch | None, old_dispatch: Dispatch | None
+    ) -> None:
+        """Update the schedule for a dispatch.
+
+        Schedules, reschedules or cancels the dispatch events
+        based on the start_time and active status.
+
+        Sends a running state change notification if necessary.
+
+        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 dispatch is None, the dispatch was deleted
+        # and we need to cancel any existing event for it
+        if not dispatch and old_dispatch:
+            self._remove_scheduled(old_dispatch)
+
+            # If the dispatch was running, we need to notify
+            if old_dispatch.running(old_dispatch.type) == RunningState.RUNNING:
+                await self._send_running_state_change(old_dispatch)
+
+        # A new dispatch was created
+        elif dispatch and not old_dispatch:
+            assert not self._remove_scheduled(
+                dispatch
+            ), "New dispatch already scheduled?!"
+
+            # If its currently running, send notification right away
+            if dispatch.running(dispatch.type) == RunningState.RUNNING:
+                await self._send_running_state_change(dispatch)
+
+                self._schedule_stop(dispatch)
+            # Otherwise, if it's enabled but not yet running, schedule it
+            else:
+                self._schedule_start(dispatch)
+
+        # Dispatch was updated
+        elif dispatch and old_dispatch:
+            # Remove potentially existing scheduled event
+            self._remove_scheduled(old_dispatch)
+
+            # Check if the change requires an immediate notification
+            if self._update_changed_running_state(dispatch, old_dispatch):
+                await self._send_running_state_change(dispatch)
+
+            if dispatch.running(dispatch.type) == RunningState.RUNNING:
+                self._schedule_stop(dispatch)
+            else:
+                self._schedule_start(dispatch)
+
+        # We modified the schedule, so we need to reset the timer
+        self._update_timer()
+
+    def _update_timer(self) -> None:
+        """Update the timer to the next event."""
+        if self._scheduled_events:
+            due_at: datetime = self._scheduled_events[0][0]
+            self._next_event_timer.reset(interval=due_at - datetime.now(timezone.utc))
+            _logger.debug("Next event scheduled at %s", self._scheduled_events[0][0])
+
+    def _remove_scheduled(self, dispatch: Dispatch) -> bool:
+        """Remove a dispatch from the scheduled events.
+
+        Args:
+            dispatch: The dispatch to remove.
+
+        Returns:
+            True if the dispatch was found and removed, False otherwise.
+        """
+        for idx, (_, sched_dispatch) in enumerate(self._scheduled_events):
+            if dispatch.id == sched_dispatch.id:
+                self._scheduled_events.pop(idx)
+                return True
+
+        return False
+
+    def _schedule_start(self, dispatch: Dispatch) -> None:
+        """Schedule a dispatch to start.
+
+        Args:
+            dispatch: The dispatch to schedule.
+        """
+        # If the dispatch is not active, don't schedule it
+        if not dispatch.active:
+            return
+
+        # Schedule the next run
+        try:
+            if next_run := dispatch.next_run:
+                heappush(self._scheduled_events, (next_run, dispatch))
+                _logger.debug(
+                    "Scheduled dispatch %s to start at %s", dispatch.id, next_run
+                )
+            else:
+                _logger.debug("Dispatch %s has no next run", dispatch.id)
+        except ValueError as error:
+            _logger.error("Error scheduling dispatch %s: %s", dispatch.id, error)
+
+    def _schedule_stop(self, dispatch: Dispatch) -> None:
+        """Schedule a dispatch to stop.
+
+        Args:
+            dispatch: The dispatch to schedule.
+        """
+        # Setup stop timer if the dispatch has a duration
+        if dispatch.duration and dispatch.duration > timedelta(seconds=0):
+            until = dispatch.until
+            assert until is not None
+            heappush(self._scheduled_events, (until, dispatch))
+            _logger.debug("Scheduled dispatch %s to stop at %s", dispatch, until)
+
+    def _update_changed_running_state(
+        self, updated_dispatch: Dispatch, previous_dispatch: Dispatch
+    ) -> 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
+            previous_dispatch: The old dispatch
+
+        Returns:
+            True if the running state has changed, False otherwise.
+        """
+        # 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-0.3.0 → frequenz-dispatch-0.3.2/src/frequenz_dispatch.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: frequenz-dispatch
-Version: 0.3.0
+Version: 0.3.2
 Summary: A highlevel interface for the dispatch API
 Author-email: Frequenz Energy-as-a-Service GmbH <floss@frequenz.com>
 License: MIT

{frequenz-dispatch-0.3.0 → frequenz-dispatch-0.3.2}/src/frequenz_dispatch.egg-info/SOURCES.txt

@@ -7,6 +7,7 @@ src/frequenz/dispatch/__init__.py
 src/frequenz/dispatch/_dispatch.py
 src/frequenz/dispatch/_dispatcher.py
 src/frequenz/dispatch/_event.py
+src/frequenz/dispatch/_managing_actor.py
 src/frequenz/dispatch/actor.py
 src/frequenz/dispatch/conftest.py
 src/frequenz/dispatch/py.typed

{frequenz-dispatch-0.3.0 → frequenz-dispatch-0.3.2}/src/frequenz_dispatch.egg-info/requires.txt

@@ -1,8 +1,8 @@
 python-dateutil<3.0,>=2.8.2
 typing-extensions<5.0.0,>=4.11.0
-frequenz-sdk==1.0.0-rc900
-frequenz-channels<2.0.0,>=1.1.0
-frequenz-client-dispatch<0.7.0,>=0.6.0
+frequenz-sdk<1.0.0-rc1000,>=1.0.0-rc900
+frequenz-channels<2.0.0,>=1.2.0
+frequenz-client-dispatch<0.8.0,>=0.7.1
 
 [dev]
 frequenz-dispatch[dev-flake8,dev-formatting,dev-mkdocs,dev-mypy,dev-noxfile,dev-pylint,dev-pytest]
@@ -11,7 +11,7 @@ frequenz-dispatch[dev-flake8,dev-formatting,dev-mkdocs,dev-mypy,dev-noxfile,dev-
 flake8==7.1.1
 flake8-docstrings==1.7.0
 flake8-pyproject==1.2.3
-pydoclint==0.5.6
+pydoclint==0.5.9
 pydocstyle==6.3.0
 
 [dev-formatting]
@@ -24,30 +24,30 @@ Markdown==3.7
 mike==2.1.3
 mkdocs-gen-files==0.5.0
 mkdocs-literate-nav==0.6.1
-mkdocs-macros-plugin==1.0.5
-mkdocs-material==9.5.34
-mkdocstrings[python]==0.25.2
-mkdocstrings-python==1.10.9
+mkdocs-macros-plugin==1.2.0
+mkdocs-material==9.5.39
+mkdocstrings[python]==0.26.1
+mkdocstrings-python==1.11.1
 frequenz-repo-config[lib]==0.10.0
 
 [dev-mypy]
 mypy==1.11.2
 grpc-stubs==1.53.0.5
 types-Markdown==3.7.0.20240822
-types-python-dateutil==2.9.0.20240821
+types-python-dateutil==2.9.0.20240906
 frequenz-dispatch[dev-mkdocs,dev-noxfile,dev-pytest]
 
 [dev-noxfile]
-uv==0.4.1
+uv==0.4.17
 nox==2024.4.15
 frequenz-repo-config[lib]==0.10.0
 
 [dev-pylint]
-pylint==3.2.7
+pylint==3.3.1
 frequenz-dispatch[dev-mkdocs,dev-noxfile,dev-pytest]
 
 [dev-pytest]
-pytest==8.3.2
+pytest==8.3.3
 frequenz-repo-config[extra-lint-examples]==0.10.0
 pytest-mock==3.14.0
 pytest-asyncio==0.24.0

frequenz-dispatch-0.3.0/RELEASE_NOTES.md

@@ -1,20 +0,0 @@
-# Dispatch Highlevel Interface Release Notes
-
-## Summary
-
-<!-- Here goes a general summary of what this release is about -->
-
-## Upgrading
-
-- The dispatch high level interface now depends on `frequenz-sdk` version `v1.0.0-rc900`.
-- We are now using the version `0.6.0` of the underlying `frequenz-client-dispatch` client library.
-- The init parameter of the `Dispatcher` class has been changed to accept a `server_url` instead.
-
-## New Features
-
-* Using the new dispatch client, we now have support for pagination in the dispatch list request.
-* The new client version also supports streaming, however it is not yet used internally in the high level interface.
-
-## Bug Fixes
-
-- Fix documentation cross-linking to the `frequenz-client-dispatch` package.

frequenz-dispatch-0.3.0/src/frequenz/dispatch/actor.py

@@ -1,255 +0,0 @@
-# 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 page in self._client.list(microgrid_id=self._microgrid_id):
-                for client_dispatch in page:
-                    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