frequenz-dispatch 0.4.0__tar.gz → 0.5.0__tar.gz

{frequenz-dispatch-0.4.0/src/frequenz_dispatch.egg-info → frequenz_dispatch-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: frequenz-dispatch
-Version: 0.4.0
+Version: 0.5.0
 Summary: A highlevel interface for the dispatch API
 Author-email: Frequenz Energy-as-a-Service GmbH <floss@frequenz.com>
 License: MIT
@@ -19,15 +19,52 @@ Classifier: Topic :: Software Development :: Libraries
 Classifier: Typing :: Typed
 Requires-Python: <4,>=3.11
 Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: typing-extensions<5.0.0,>=4.11.0
+Requires-Dist: frequenz-sdk<1.0.0-rc1500,>=1.0.0-rc1302
+Requires-Dist: frequenz-channels<2.0.0,>=1.3.0
+Requires-Dist: frequenz-client-dispatch<0.9.0,>=0.8.2
 Provides-Extra: dev-flake8
+Requires-Dist: flake8==7.1.1; 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.5.9; extra == "dev-flake8"
+Requires-Dist: pydocstyle==6.3.0; extra == "dev-flake8"
 Provides-Extra: dev-formatting
+Requires-Dist: black==24.10.0; extra == "dev-formatting"
+Requires-Dist: isort==5.13.2; extra == "dev-formatting"
 Provides-Extra: dev-mkdocs
+Requires-Dist: black==24.10.0; extra == "dev-mkdocs"
+Requires-Dist: Markdown==3.7; extra == "dev-mkdocs"
+Requires-Dist: mike==2.1.3; 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.3.7; extra == "dev-mkdocs"
+Requires-Dist: mkdocs-material==9.5.47; extra == "dev-mkdocs"
+Requires-Dist: mkdocstrings[python]==0.27.0; extra == "dev-mkdocs"
+Requires-Dist: mkdocstrings-python==1.12.2; extra == "dev-mkdocs"
+Requires-Dist: frequenz-repo-config[lib]==0.11.0; extra == "dev-mkdocs"
 Provides-Extra: dev-mypy
+Requires-Dist: mypy==1.13.0; extra == "dev-mypy"
+Requires-Dist: grpc-stubs==1.53.0.5; extra == "dev-mypy"
+Requires-Dist: types-Markdown==3.7.0.20240822; extra == "dev-mypy"
+Requires-Dist: frequenz-dispatch[dev-mkdocs,dev-noxfile,dev-pytest]; extra == "dev-mypy"
 Provides-Extra: dev-noxfile
+Requires-Dist: uv==0.5.5; extra == "dev-noxfile"
+Requires-Dist: nox==2024.10.9; extra == "dev-noxfile"
+Requires-Dist: frequenz-repo-config[lib]==0.11.0; extra == "dev-noxfile"
 Provides-Extra: dev-pylint
+Requires-Dist: pylint==3.3.2; extra == "dev-pylint"
+Requires-Dist: frequenz-dispatch[dev-mkdocs,dev-noxfile,dev-pytest]; extra == "dev-pylint"
 Provides-Extra: dev-pytest
+Requires-Dist: pytest==8.3.4; extra == "dev-pytest"
+Requires-Dist: frequenz-repo-config[extra-lint-examples]==0.11.0; extra == "dev-pytest"
+Requires-Dist: pytest-mock==3.14.0; extra == "dev-pytest"
+Requires-Dist: pytest-asyncio==0.24.0; extra == "dev-pytest"
+Requires-Dist: async-solipsism==0.7; extra == "dev-pytest"
+Requires-Dist: time-machine==2.16.0; extra == "dev-pytest"
 Provides-Extra: dev
-License-File: LICENSE
+Requires-Dist: frequenz-dispatch[dev-flake8,dev-formatting,dev-mkdocs,dev-mypy,dev-noxfile,dev-pylint,dev-pytest]; extra == "dev"
 
 # Dispatch Highlevel Interface
 
@@ -52,7 +89,7 @@ The [`Dispatcher` class](https://frequenz-floss.github.io/frequenz-dispatch-pyth
 
 ```python
 import os
-from frequenz.dispatch import Dispatcher, RunningState
+from frequenz.dispatch import Dispatcher
 from unittest.mock import MagicMock
 
 async def run():
@@ -73,29 +110,29 @@ async def run():
     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.target,
-                        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.target,
-                        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
+        if dispatch.type != "MY_TYPE":
+            continue
+
+        if dispatch.started:
+            print(f"Executing dispatch {dispatch.id}, due on {dispatch.start_time}")
+            if actor.is_running:
+                actor.reconfigure(
+                    components=dispatch.target,
+                    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.target,
+                    run_parameters=dispatch.payload, # custom actor parameters
+                    dry_run=dispatch.dry_run,
+                    until=dispatch.until,
+                )
+        else:
+            actor.stop()  # this will stop the actor
 ```
 
 ## Supported Platforms

{frequenz-dispatch-0.4.0 → frequenz_dispatch-0.5.0}/README.md

@@ -21,7 +21,7 @@ The [`Dispatcher` class](https://frequenz-floss.github.io/frequenz-dispatch-pyth
 
 ```python
 import os
-from frequenz.dispatch import Dispatcher, RunningState
+from frequenz.dispatch import Dispatcher
 from unittest.mock import MagicMock
 
 async def run():
@@ -42,29 +42,29 @@ async def run():
     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.target,
-                        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.target,
-                        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
+        if dispatch.type != "MY_TYPE":
+            continue
+
+        if dispatch.started:
+            print(f"Executing dispatch {dispatch.id}, due on {dispatch.start_time}")
+            if actor.is_running:
+                actor.reconfigure(
+                    components=dispatch.target,
+                    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.target,
+                    run_parameters=dispatch.payload, # custom actor parameters
+                    dry_run=dispatch.dry_run,
+                    until=dispatch.until,
+                )
+        else:
+            actor.stop()  # this will stop the actor
 ```
 
 ## Supported Platforms

frequenz_dispatch-0.5.0/RELEASE_NOTES.md

@@ -0,0 +1,18 @@
+# Dispatch Highlevel Interface Release Notes
+
+## Summary
+
+<!-- Here goes a general summary of what this release is about -->
+
+## Upgrading
+
+* The method `Dispatch.running(type: str)` was replaced with the property `Dispatch.started: bool`.
+* The SDK dependency was widened to allow versions up to (excluding) v1.0.0-rc1500
+
+## New Features
+
+<!-- Here goes the main new features and examples or instructions on how to use them -->
+
+## Bug Fixes
+
+* Fixed a crash when reading a Dispatch with frequency YEARLY.

{frequenz-dispatch-0.4.0 → frequenz_dispatch-0.5.0}/pyproject.toml

@@ -3,9 +3,9 @@
 
 [build-system]
 requires = [
-  "setuptools == 68.1.0",
-  "setuptools_scm[toml] == 7.1.0",
-  "frequenz-repo-config[lib] == 0.10.0",
+  "setuptools == 75.6.0",
+  "setuptools_scm[toml] == 8.1.0",
+  "frequenz-repo-config[lib] == 0.11.0",
 ]
 build-backend = "setuptools.build_meta"
 
@@ -34,14 +34,13 @@ classifiers = [
 ]
 requires-python = ">= 3.11, < 4"
 dependencies = [
-  "python-dateutil >= 2.8.2, < 3.0",
   "typing-extensions >= 4.11.0, < 5.0.0",
   # 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-rc1300, < 1.0.0-rc1400",
+  "frequenz-sdk >= 1.0.0-rc1302, < 1.0.0-rc1500",
   "frequenz-channels >= 1.3.0, < 2.0.0",
-  "frequenz-client-dispatch >= 0.8.1, < 0.9.0",
+  "frequenz-client-dispatch >= 0.8.2, < 0.9.0",
 ]
 dynamic = ["version"]
 
@@ -65,32 +64,32 @@ dev-mkdocs = [
   "mkdocs-gen-files == 0.5.0",
   "mkdocs-literate-nav == 0.6.1",
   "mkdocs-macros-plugin == 1.3.7",
-  "mkdocs-material == 9.5.43",
-  "mkdocstrings[python] == 0.26.2",
+  "mkdocs-material == 9.5.47",
+  "mkdocstrings[python] == 0.27.0",
   "mkdocstrings-python == 1.12.2",
-  "frequenz-repo-config[lib] == 0.10.0",
+  "frequenz-repo-config[lib] == 0.11.0",
 ]
 dev-mypy = [
   "mypy == 1.13.0",
-  "grpc-stubs == 1.53.0.5",               # This dependency introduces breaking changes in patch releases
+  # This dependency introduces breaking changes in patch releases
+  "grpc-stubs == 1.53.0.5",
   "types-Markdown == 3.7.0.20240822",
-  "types-python-dateutil==2.9.0.20241003",
   # For checking the noxfile, docs/ script, and tests
   "frequenz-dispatch[dev-mkdocs,dev-noxfile,dev-pytest]",
 ]
 dev-noxfile = [
-  "uv == 0.4.29",
+  "uv == 0.5.5",
   "nox == 2024.10.9",
-  "frequenz-repo-config[lib] == 0.10.0",
+  "frequenz-repo-config[lib] == 0.11.0",
 ]
 dev-pylint = [
-  "pylint == 3.3.1",
+  "pylint == 3.3.2",
   # For checking the noxfile, docs/ script, and tests
   "frequenz-dispatch[dev-mkdocs,dev-noxfile,dev-pytest]",
 ]
 dev-pytest = [
-  "pytest == 8.3.3",
-  "frequenz-repo-config[extra-lint-examples] == 0.10.0",
+  "pytest == 8.3.4",
+  "frequenz-repo-config[extra-lint-examples] == 0.11.0",
   "pytest-mock == 3.14.0",
   "pytest-asyncio == 0.24.0",
   "async-solipsism == 0.7",
@@ -152,6 +151,8 @@ disable = [
   "unsubscriptable-object",
   # Checked by mypy
   "no-member",
+  "possibly-used-before-assignment",
+  "no-name-in-module",
   # Checked by flake8
   "f-string-without-interpolation",
   "line-too-long",

{frequenz-dispatch-0.4.0 → frequenz_dispatch-0.5.0}/src/frequenz/dispatch/__init__.py

@@ -15,7 +15,7 @@ A small overview of the most important classes in this module:
 
 """
 
-from ._dispatch import Dispatch, RunningState
+from ._dispatch import Dispatch
 from ._dispatcher import Dispatcher, ReceiverFetcher
 from ._event import Created, Deleted, DispatchEvent, Updated
 from ._managing_actor import DispatchManagingActor, DispatchUpdate
@@ -28,7 +28,6 @@ __all__ = [
     "ReceiverFetcher",
     "Updated",
     "Dispatch",
-    "RunningState",
     "DispatchManagingActor",
     "DispatchUpdate",
 ]

frequenz_dispatch-0.5.0/src/frequenz/dispatch/_dispatch.py

@@ -0,0 +1,71 @@
+# License: MIT
+# Copyright © 2024 Frequenz Energy-as-a-Service GmbH
+
+"""Dispatch type with support for next_run calculation."""
+
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from typing import Iterator
+
+from frequenz.client.dispatch.types import Dispatch as BaseDispatch
+
+
+@dataclass(frozen=True)
+class Dispatch(BaseDispatch):
+    """Dispatch type with extra functionality."""
+
+    deleted: bool = False
+    """Whether the dispatch is deleted."""
+
+    def __init__(
+        self,
+        client_dispatch: BaseDispatch,
+        deleted: bool = False,
+    ):
+        """Initialize the dispatch.
+
+        Args:
+            client_dispatch: The client dispatch.
+            deleted: Whether the dispatch is deleted.
+        """
+        super().__init__(**client_dispatch.__dict__)
+        # Work around frozen to set deleted
+        object.__setattr__(self, "deleted", deleted)
+
+    def _set_deleted(self) -> None:
+        """Mark the dispatch as deleted."""
+        object.__setattr__(self, "deleted", True)
+
+    @property
+    def started(self) -> bool:
+        """Check if the dispatch is started.
+
+        Returns:
+            True if the dispatch is started, False otherwise.
+        """
+        if self.deleted:
+            return False
+
+        return super().started
+
+    # 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, since: datetime) -> Iterator[datetime]:  # noqa: DOC405
+        """Yield all missed runs of a dispatch.
+
+        Yields all missed runs of a dispatch.
+
+        Args:
+            since: The time to start checking for missed runs.
+
+        Returns:
+            A generator that yields all missed runs of a dispatch.
+
+        Yields:
+            datetime: The missed run.
+        """
+        now = datetime.now(tz=timezone.utc)
+
+        while (next_run := self.next_run_after(since)) and next_run < now:
+            yield next_run
+            since = next_run

{frequenz-dispatch-0.4.0 → frequenz_dispatch-0.5.0}/src/frequenz/dispatch/_dispatcher.py

@@ -54,7 +54,7 @@ class Dispatcher:
     Example: Processing running state change dispatches
         ```python
         import os
-        from frequenz.dispatch import Dispatcher, RunningState
+        from frequenz.dispatch import Dispatcher
         from unittest.mock import MagicMock
 
         async def run():
@@ -75,29 +75,29 @@ class Dispatcher:
             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.target,
-                                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.target,
-                                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
+                if dispatch.type != "YOUR_DISPATCH_TYPE":
+                    continue
+
+                if dispatch.started:
+                    print(f"Executing dispatch {dispatch.id}, due on {dispatch.start_time}")
+                    if actor.is_running:
+                        actor.reconfigure(
+                            components=dispatch.target,
+                            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.target,
+                            run_parameters=dispatch.payload, # custom actor parameters
+                            dry_run=dispatch.dry_run,
+                            until=dispatch.until,
+                        )
+                else:
+                    actor.stop()  # this will stop the actor
         ```
 
     Example: Getting notification about dispatch lifecycle events
@@ -255,10 +255,6 @@ class Dispatcher:
          - 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.
         """

{frequenz-dispatch-0.4.0 → frequenz_dispatch-0.5.0}/src/frequenz/dispatch/_managing_actor.py

@@ -11,7 +11,7 @@ from frequenz.channels import Receiver, Sender
 from frequenz.client.dispatch.types import TargetComponents
 from frequenz.sdk.actor import Actor
 
-from ._dispatch import Dispatch, RunningState
+from ._dispatch import Dispatch
 
 _logger = logging.getLogger(__name__)
 
@@ -121,7 +121,9 @@ class DispatchManagingActor(Actor):
         """
         super().__init__()
         self._dispatch_rx = running_status_receiver
-        self._actors = frozenset([actor] if isinstance(actor, Actor) else actor)
+        self._actors: frozenset[Actor] = frozenset(
+            [actor] if isinstance(actor, Actor) else actor
+        )
         self._dispatch_type = dispatch_type
         self._updates_sender = updates_sender
 
@@ -156,25 +158,23 @@ class DispatchManagingActor(Actor):
         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.target,
-                            dry_run=dispatch.dry_run,
-                            options=dispatch.payload,
-                        )
+        if dispatch.type != self._dispatch_type:
+            _logger.debug("Ignoring dispatch %s", dispatch.id)
+            return
+
+        if dispatch.started:
+            if self._updates_sender is not None:
+                _logger.info("Updated by dispatch %s", dispatch.id)
+                await self._updates_sender.send(
+                    DispatchUpdate(
+                        components=dispatch.target,
+                        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
                 )
+
+            _logger.info("Started by dispatch %s", dispatch.id)
+            self._start_actors()
+        else:
+            _logger.info("Stopped by dispatch %s", dispatch.id)
+            await self._stop_actors("Dispatch stopped")

{frequenz-dispatch-0.4.0 → frequenz_dispatch-0.5.0}/src/frequenz/dispatch/actor.py

@@ -15,7 +15,7 @@ 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 ._dispatch import Dispatch
 from ._event import Created, Deleted, DispatchEvent, Updated
 
 _logger = logging.getLogger(__name__)
@@ -126,7 +126,6 @@ class DispatchingActor(Actor):
                         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)
                         )
@@ -142,7 +141,7 @@ class DispatchingActor(Actor):
         # 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 dispatch.started:
             # 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
@@ -193,7 +192,7 @@ class DispatchingActor(Actor):
             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()
+            # Set deleted only here as it influences the result of dispatch.started
             # 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))
@@ -221,8 +220,11 @@ class DispatchingActor(Actor):
         if not dispatch and old_dispatch:
             self._remove_scheduled(old_dispatch)
 
+            was_running = old_dispatch.started
+            old_dispatch._set_deleted()  # pylint: disable=protected-access)
+
             # If the dispatch was running, we need to notify
-            if old_dispatch.running(old_dispatch.type) == RunningState.RUNNING:
+            if was_running:
                 await self._send_running_state_change(old_dispatch)
 
         # A new dispatch was created
@@ -230,9 +232,8 @@ class DispatchingActor(Actor):
             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:
+            if dispatch.started:
                 await self._send_running_state_change(dispatch)
 
                 self._schedule_stop(dispatch)
@@ -249,7 +250,7 @@ class DispatchingActor(Actor):
             if self._update_changed_running_state(dispatch, old_dispatch):
                 await self._send_running_state_change(dispatch)
 
-            if dispatch.running(dispatch.type) == RunningState.RUNNING:
+            if dispatch.started:
                 self._schedule_stop(dispatch)
             else:
                 self._schedule_start(dispatch)
@@ -336,7 +337,7 @@ class DispatchingActor(Actor):
         """
         # If any of the runtime attributes changed, we need to send a message
         runtime_state_attributes = [
-            "running",
+            "started",
             "type",
             "target",
             "duration",
@@ -359,6 +360,3 @@ class DispatchingActor(Actor):
             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.4.0 → frequenz_dispatch-0.5.0/src/frequenz_dispatch.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: frequenz-dispatch
-Version: 0.4.0
+Version: 0.5.0
 Summary: A highlevel interface for the dispatch API
 Author-email: Frequenz Energy-as-a-Service GmbH <floss@frequenz.com>
 License: MIT
@@ -19,15 +19,52 @@ Classifier: Topic :: Software Development :: Libraries
 Classifier: Typing :: Typed
 Requires-Python: <4,>=3.11
 Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: typing-extensions<5.0.0,>=4.11.0
+Requires-Dist: frequenz-sdk<1.0.0-rc1500,>=1.0.0-rc1302
+Requires-Dist: frequenz-channels<2.0.0,>=1.3.0
+Requires-Dist: frequenz-client-dispatch<0.9.0,>=0.8.2
 Provides-Extra: dev-flake8
+Requires-Dist: flake8==7.1.1; 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.5.9; extra == "dev-flake8"
+Requires-Dist: pydocstyle==6.3.0; extra == "dev-flake8"
 Provides-Extra: dev-formatting
+Requires-Dist: black==24.10.0; extra == "dev-formatting"
+Requires-Dist: isort==5.13.2; extra == "dev-formatting"
 Provides-Extra: dev-mkdocs
+Requires-Dist: black==24.10.0; extra == "dev-mkdocs"
+Requires-Dist: Markdown==3.7; extra == "dev-mkdocs"
+Requires-Dist: mike==2.1.3; 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.3.7; extra == "dev-mkdocs"
+Requires-Dist: mkdocs-material==9.5.47; extra == "dev-mkdocs"
+Requires-Dist: mkdocstrings[python]==0.27.0; extra == "dev-mkdocs"
+Requires-Dist: mkdocstrings-python==1.12.2; extra == "dev-mkdocs"
+Requires-Dist: frequenz-repo-config[lib]==0.11.0; extra == "dev-mkdocs"
 Provides-Extra: dev-mypy
+Requires-Dist: mypy==1.13.0; extra == "dev-mypy"
+Requires-Dist: grpc-stubs==1.53.0.5; extra == "dev-mypy"
+Requires-Dist: types-Markdown==3.7.0.20240822; extra == "dev-mypy"
+Requires-Dist: frequenz-dispatch[dev-mkdocs,dev-noxfile,dev-pytest]; extra == "dev-mypy"
 Provides-Extra: dev-noxfile
+Requires-Dist: uv==0.5.5; extra == "dev-noxfile"
+Requires-Dist: nox==2024.10.9; extra == "dev-noxfile"
+Requires-Dist: frequenz-repo-config[lib]==0.11.0; extra == "dev-noxfile"
 Provides-Extra: dev-pylint
+Requires-Dist: pylint==3.3.2; extra == "dev-pylint"
+Requires-Dist: frequenz-dispatch[dev-mkdocs,dev-noxfile,dev-pytest]; extra == "dev-pylint"
 Provides-Extra: dev-pytest
+Requires-Dist: pytest==8.3.4; extra == "dev-pytest"
+Requires-Dist: frequenz-repo-config[extra-lint-examples]==0.11.0; extra == "dev-pytest"
+Requires-Dist: pytest-mock==3.14.0; extra == "dev-pytest"
+Requires-Dist: pytest-asyncio==0.24.0; extra == "dev-pytest"
+Requires-Dist: async-solipsism==0.7; extra == "dev-pytest"
+Requires-Dist: time-machine==2.16.0; extra == "dev-pytest"
 Provides-Extra: dev
-License-File: LICENSE
+Requires-Dist: frequenz-dispatch[dev-flake8,dev-formatting,dev-mkdocs,dev-mypy,dev-noxfile,dev-pylint,dev-pytest]; extra == "dev"
 
 # Dispatch Highlevel Interface
 
@@ -52,7 +89,7 @@ The [`Dispatcher` class](https://frequenz-floss.github.io/frequenz-dispatch-pyth
 
 ```python
 import os
-from frequenz.dispatch import Dispatcher, RunningState
+from frequenz.dispatch import Dispatcher
 from unittest.mock import MagicMock
 
 async def run():
@@ -73,29 +110,29 @@ async def run():
     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.target,
-                        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.target,
-                        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
+        if dispatch.type != "MY_TYPE":
+            continue
+
+        if dispatch.started:
+            print(f"Executing dispatch {dispatch.id}, due on {dispatch.start_time}")
+            if actor.is_running:
+                actor.reconfigure(
+                    components=dispatch.target,
+                    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.target,
+                    run_parameters=dispatch.payload, # custom actor parameters
+                    dry_run=dispatch.dry_run,
+                    until=dispatch.until,
+                )
+        else:
+            actor.stop()  # this will stop the actor
 ```
 
 ## Supported Platforms

{frequenz-dispatch-0.4.0 → frequenz_dispatch-0.5.0}/src/frequenz_dispatch.egg-info/requires.txt

@@ -1,8 +1,7 @@
-python-dateutil<3.0,>=2.8.2
 typing-extensions<5.0.0,>=4.11.0
-frequenz-sdk<1.0.0-rc1400,>=1.0.0-rc1300
+frequenz-sdk<1.0.0-rc1500,>=1.0.0-rc1302
 frequenz-channels<2.0.0,>=1.3.0
-frequenz-client-dispatch<0.9.0,>=0.8.1
+frequenz-client-dispatch<0.9.0,>=0.8.2
 
 [dev]
 frequenz-dispatch[dev-flake8,dev-formatting,dev-mkdocs,dev-mypy,dev-noxfile,dev-pylint,dev-pytest]
@@ -25,30 +24,29 @@ mike==2.1.3
 mkdocs-gen-files==0.5.0
 mkdocs-literate-nav==0.6.1
 mkdocs-macros-plugin==1.3.7
-mkdocs-material==9.5.43
-mkdocstrings[python]==0.26.2
+mkdocs-material==9.5.47
+mkdocstrings[python]==0.27.0
 mkdocstrings-python==1.12.2
-frequenz-repo-config[lib]==0.10.0
+frequenz-repo-config[lib]==0.11.0
 
 [dev-mypy]
 mypy==1.13.0
 grpc-stubs==1.53.0.5
 types-Markdown==3.7.0.20240822
-types-python-dateutil==2.9.0.20241003
 frequenz-dispatch[dev-mkdocs,dev-noxfile,dev-pytest]
 
 [dev-noxfile]
-uv==0.4.29
+uv==0.5.5
 nox==2024.10.9
-frequenz-repo-config[lib]==0.10.0
+frequenz-repo-config[lib]==0.11.0
 
 [dev-pylint]
-pylint==3.3.1
+pylint==3.3.2
 frequenz-dispatch[dev-mkdocs,dev-noxfile,dev-pytest]
 
 [dev-pytest]
-pytest==8.3.3
-frequenz-repo-config[extra-lint-examples]==0.10.0
+pytest==8.3.4
+frequenz-repo-config[extra-lint-examples]==0.11.0
 pytest-mock==3.14.0
 pytest-asyncio==0.24.0
 async-solipsism==0.7

frequenz-dispatch-0.4.0/RELEASE_NOTES.md

@@ -1,21 +0,0 @@
-# Dispatch Highlevel Interface Release Notes
-
-## Summary
-
-* Updates lots of dependencies and through those gets a few new features:
- * `start_immediately` when creating dispatches is now supported.
- * `http2 keepalive` is now supported and enabled by default.
- * Some bugfixes from the channels & sdk libraries. are now included.
-
-
-## Upgrading
-
-<!-- Here goes notes on how to upgrade from previous versions, including deprecations and what they should be replaced with -->
-
-## New Features
-
-<!-- Here goes the main new features and examples or instructions on how to use them -->
-
-## Bug Fixes
-
-* Fixed a crash in the `DispatchManagingActor` when dispatches shared an equal start time.

frequenz-dispatch-0.4.0/src/frequenz/dispatch/_dispatch.py

@@ -1,272 +0,0 @@
-# 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.recurrence import Frequency, Weekday
-from frequenz.client.dispatch.types import Dispatch as BaseDispatch
-
-_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 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
-
-        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
-            or self.duration is None  # Infinite duration
-        ):
-            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.
-
-        Raises:
-            ValueError: If the interval is invalid.
-        """
-        count, until = (None, None)
-        if end := self.recurrence.end_criteria:
-            count = end.count
-            until = end.until
-
-        if self.recurrence.interval is None or self.recurrence.interval < 1:
-            raise ValueError("Interval must be at least 1")
-
-        rrule_obj = rrule.rrule(
-            freq=_RRULE_FREQ_MAP[self.recurrence.frequency],
-            dtstart=self.start_time,
-            count=count,
-            until=until,
-            byminute=self.recurrence.byminutes or None,
-            byhour=self.recurrence.byhours or None,
-            byweekday=[
-                _RRULE_WEEKDAY_MAP[weekday] for weekday in self.recurrence.byweekdays
-            ]
-            or None,
-            bymonthday=self.recurrence.bymonthdays or None,
-            bymonth=self.recurrence.bymonths or None,
-            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.
-
-        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
-        ):
-            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