From 12a5d3dd2fc420bb1316c7a5a139687d38a4206a Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Mon, 21 Jul 2025 10:55:46 +0000 Subject: [PATCH 1/8] Initial plan From aa6f5a257adaea9fa4a408aba367c24f5c94fa54 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Mon, 21 Jul 2025 11:02:54 +0000 Subject: [PATCH 2/8] Add Quick Start and Installation sections to README.md Co-authored-by: llucax <1031485+llucax@users.noreply.github.com> --- README.md | 81 ++++++++++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 75 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 04c6ccb..26349eb 100644 --- a/README.md +++ b/README.md @@ -8,14 +8,52 @@ 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. +See [the documentation](https://frequenz-floss.github.io/frequenz-dispatch-python/v0.1/reference/frequenz/dispatch) +for more information. + +## Quick Start + +The `frequenz-dispatch` library provides a high-level interface to interact +with the dispatch API. Here's a minimal example to get you started: + +```python +import os +from datetime import timedelta +from frequenz.dispatch import Dispatcher + +async def main(): + # Configure connection to dispatch API + url = os.getenv("DISPATCH_API_URL", "grpc://your-dispatch-url.com") + key = os.getenv("DISPATCH_API_KEY", "your-api-key") + microgrid_id = 1 + + # Create and use the dispatcher + async with Dispatcher( + microgrid_id=microgrid_id, + server_url=url, + key=key, + ) as dispatcher: + # Your dispatch logic here + print("Dispatcher ready!") +``` + +For complete examples and advanced usage, see the [Usage](#usage) section below. ## 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: +The [`Dispatcher` class][dispatcher-class], 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. +* [Lifecycle events][lifecycle-events]: A channel that sends a message whenever + a [Dispatch][frequenz.dispatch.Dispatch] is created, updated or deleted. +* [Running status change][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. + +[dispatcher-class]: https://frequenz-floss.github.io/frequenz-dispatch-python/v0.1/reference/frequenz/dispatch/#frequenz.dispatch.Dispatcher +[lifecycle-events]: https://frequenz-floss.github.io/frequenz-dispatch-python/v0.1/reference/frequenz/dispatch/#frequenz.dispatch.Dispatcher.lifecycle_events +[running-status-change]: https://frequenz-floss.github.io/frequenz-dispatch-python/v0.1/reference/frequenz/dispatch/#frequenz.dispatch.Dispatcher.running_status_change ### Example using the running status change channel @@ -26,11 +64,15 @@ from datetime import timedelta from frequenz.dispatch import Dispatcher, DispatchInfo, MergeByType -async def create_actor(dispatch: DispatchInfo, receiver: Receiver[DispatchInfo]) -> Actor: +async def create_actor( + dispatch: DispatchInfo, receiver: Receiver[DispatchInfo] +) -> Actor: return MagicMock(dispatch=dispatch, receiver=receiver) async def run(): - url = os.getenv("DISPATCH_API_URL", "grpc://dispatch.url.goes.here.example.com") + url = os.getenv( + "DISPATCH_API_URL", "grpc://dispatch.url.goes.here.example.com" + ) key = os.getenv("DISPATCH_API_KEY", "some-key") microgrid_id = 1 @@ -58,6 +100,33 @@ The following platforms are officially supported (tested): - **Operating System:** Ubuntu Linux 20.04 - **Architectures:** amd64, arm64 +## Installation + +### Using pip + +You can install the package from PyPI: + +```bash +python3 -m pip install frequenz-dispatch +``` + +### Using pyproject.toml + +Add the dependency to your `pyproject.toml` file: + +```toml +[project] +dependencies = [ + "frequenz-dispatch >= 0.10.1, < 0.11", +] +``` + +> [!NOTE] +> We recommend pinning the dependency to the latest version for programs, +> like `"frequenz-dispatch == 0.10.1"`, and specifying a version range +> spanning one major version for libraries, like +> `"frequenz-dispatch >= 0.10.1, < 0.11"`. We follow [semver](https://semver.org/). + ## Contributing If you want to know how to build this project and contribute to it, please From 523d9512c32ba8ccb8cf122390dfbeca88c9eaf4 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Mon, 21 Jul 2025 11:27:35 +0000 Subject: [PATCH 3/8] Restructure README.md as requested: merge sections and improve content Co-authored-by: llucax <1031485+llucax@users.noreply.github.com> --- README.md | 93 +++++++++++++++++++++++++++++-------------------------- 1 file changed, 49 insertions(+), 44 deletions(-) diff --git a/README.md b/README.md index 26349eb..c7a4a5c 100644 --- a/README.md +++ b/README.md @@ -6,10 +6,50 @@ ## Introduction -A highlevel interface for the dispatch API. +The `frequenz-dispatch` library provides a high-level Python interface for +interacting with the Frequenz Dispatch API. This library enables you to +manage and monitor dispatch operations in microgrids, including lifecycle +events and running status changes of dispatch operations. -See [the documentation](https://frequenz-floss.github.io/frequenz-dispatch-python/v0.1/reference/frequenz/dispatch) -for more information. +The main entry point is the [`Dispatcher`][dispatcher-class] class, which +provides channels for receiving dispatch lifecycle events and running status +updates, allowing you to build reactive applications that respond to dispatch +state changes. + +## Supported Platforms + +The following platforms are officially supported (tested): + +- **Python:** 3.11 +- **Operating System:** Ubuntu Linux 20.04 +- **Architectures:** amd64, arm64 + +## Installation + +### Using pip + +You can install the package from PyPI: + +```bash +python3 -m pip install frequenz-dispatch +``` + +### Using pyproject.toml + +Add the dependency to your `pyproject.toml` file: + +```toml +[project] +dependencies = [ + "frequenz-dispatch >= 0.10.1, < 0.11", +] +``` + +> [!NOTE] +> We recommend pinning the dependency to the latest version for programs, +> like `"frequenz-dispatch == 0.10.1"`, and specifying a version range +> spanning one major version for libraries, like +> `"frequenz-dispatch >= 0.10.1, < 0.11"`. We follow [semver](https://semver.org/). ## Quick Start @@ -18,7 +58,6 @@ with the dispatch API. Here's a minimal example to get you started: ```python import os -from datetime import timedelta from frequenz.dispatch import Dispatcher async def main(): @@ -37,10 +76,6 @@ async def main(): print("Dispatcher ready!") ``` -For complete examples and advanced usage, see the [Usage](#usage) section below. - -## Usage - The [`Dispatcher` class][dispatcher-class], the main entry point for the API, provides two channels: @@ -51,10 +86,6 @@ provides two channels: running status of the dispatch changed in a way that could potentially require the actor to start, stop or reconfigure itself. -[dispatcher-class]: https://frequenz-floss.github.io/frequenz-dispatch-python/v0.1/reference/frequenz/dispatch/#frequenz.dispatch.Dispatcher -[lifecycle-events]: https://frequenz-floss.github.io/frequenz-dispatch-python/v0.1/reference/frequenz/dispatch/#frequenz.dispatch.Dispatcher.lifecycle_events -[running-status-change]: https://frequenz-floss.github.io/frequenz-dispatch-python/v0.1/reference/frequenz/dispatch/#frequenz.dispatch.Dispatcher.running_status_change - ### Example using the running status change channel ```python @@ -92,40 +123,14 @@ async def run(): await dispatcher ``` -## Supported Platforms - -The following platforms are officially supported (tested): - -- **Python:** 3.11 -- **Operating System:** Ubuntu Linux 20.04 -- **Architectures:** amd64, arm64 - -## Installation - -### Using pip - -You can install the package from PyPI: - -```bash -python3 -m pip install frequenz-dispatch -``` - -### Using pyproject.toml +[dispatcher-class]: https://frequenz-floss.github.io/frequenz-dispatch-python/v0.1/reference/frequenz/dispatch/#frequenz.dispatch.Dispatcher +[lifecycle-events]: https://frequenz-floss.github.io/frequenz-dispatch-python/v0.1/reference/frequenz/dispatch/#frequenz.dispatch.Dispatcher.lifecycle_events +[running-status-change]: https://frequenz-floss.github.io/frequenz-dispatch-python/v0.1/reference/frequenz/dispatch/#frequenz.dispatch.Dispatcher.running_status_change -Add the dependency to your `pyproject.toml` file: +## Documentation -```toml -[project] -dependencies = [ - "frequenz-dispatch >= 0.10.1, < 0.11", -] -``` - -> [!NOTE] -> We recommend pinning the dependency to the latest version for programs, -> like `"frequenz-dispatch == 0.10.1"`, and specifying a version range -> spanning one major version for libraries, like -> `"frequenz-dispatch >= 0.10.1, < 0.11"`. We follow [semver](https://semver.org/). +For complete API documentation, examples, and advanced usage patterns, see +[the documentation](https://frequenz-floss.github.io/frequenz-dispatch-python/v0.1/reference/frequenz/dispatch). ## Contributing From c873fcee4809553f9c5925a699c2cf80ebf39305 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Mon, 21 Jul 2025 11:33:25 +0000 Subject: [PATCH 4/8] Update documentation links from v0.1 to latest Co-authored-by: llucax <1031485+llucax@users.noreply.github.com> --- README.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index c7a4a5c..99a28c8 100644 --- a/README.md +++ b/README.md @@ -123,14 +123,14 @@ async def run(): await dispatcher ``` -[dispatcher-class]: https://frequenz-floss.github.io/frequenz-dispatch-python/v0.1/reference/frequenz/dispatch/#frequenz.dispatch.Dispatcher -[lifecycle-events]: https://frequenz-floss.github.io/frequenz-dispatch-python/v0.1/reference/frequenz/dispatch/#frequenz.dispatch.Dispatcher.lifecycle_events -[running-status-change]: https://frequenz-floss.github.io/frequenz-dispatch-python/v0.1/reference/frequenz/dispatch/#frequenz.dispatch.Dispatcher.running_status_change +[dispatcher-class]: https://frequenz-floss.github.io/frequenz-dispatch-python/latest/reference/frequenz/dispatch/#frequenz.dispatch.Dispatcher +[lifecycle-events]: https://frequenz-floss.github.io/frequenz-dispatch-python/latest/reference/frequenz/dispatch/#frequenz.dispatch.Dispatcher.lifecycle_events +[running-status-change]: https://frequenz-floss.github.io/frequenz-dispatch-python/latest/reference/frequenz/dispatch/#frequenz.dispatch.Dispatcher.running_status_change ## Documentation For complete API documentation, examples, and advanced usage patterns, see -[the documentation](https://frequenz-floss.github.io/frequenz-dispatch-python/v0.1/reference/frequenz/dispatch). +[the documentation](https://frequenz-floss.github.io/frequenz-dispatch-python/latest/reference/frequenz/dispatch). ## Contributing From a34762cd26ae9d752da353c3328de01c28b75a3d Mon Sep 17 00:00:00 2001 From: Leandro Lucarella Date: Mon, 21 Jul 2025 16:16:06 +0200 Subject: [PATCH 5/8] Fix extra whitespace in README Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> Signed-off-by: Leandro Lucarella --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 99a28c8..3f3c669 100644 --- a/README.md +++ b/README.md @@ -104,7 +104,7 @@ async def run(): url = os.getenv( "DISPATCH_API_URL", "grpc://dispatch.url.goes.here.example.com" ) - key = os.getenv("DISPATCH_API_KEY", "some-key") + key = os.getenv("DISPATCH_API_KEY", "some-key") microgrid_id = 1 From ae4ff45d1e2af7e5ec882da75b5f916e0c9f45e1 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Mon, 21 Jul 2025 15:54:13 +0000 Subject: [PATCH 6/8] Fix Ubuntu version and remove redundant text in README Co-authored-by: Marenz <424752+Marenz@users.noreply.github.com> --- README.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 3f3c669..74e2bb1 100644 --- a/README.md +++ b/README.md @@ -21,7 +21,7 @@ state changes. The following platforms are officially supported (tested): - **Python:** 3.11 -- **Operating System:** Ubuntu Linux 20.04 +- **Operating System:** Ubuntu Linux 24.04 - **Architectures:** amd64, arm64 ## Installation @@ -53,8 +53,7 @@ dependencies = [ ## Quick Start -The `frequenz-dispatch` library provides a high-level interface to interact -with the dispatch API. Here's a minimal example to get you started: +Here's a minimal example to get you started: ```python import os From 0bcd22225bbe23c5d884cbec84c31efc59f5b184 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Mon, 21 Jul 2025 15:57:27 +0000 Subject: [PATCH 7/8] Remove redundant text and fix example section title Co-authored-by: Marenz <424752+Marenz@users.noreply.github.com> --- README.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 74e2bb1..3926342 100644 --- a/README.md +++ b/README.md @@ -75,8 +75,7 @@ async def main(): print("Dispatcher ready!") ``` -The [`Dispatcher` class][dispatcher-class], the main entry point for the API, -provides two channels: +The [`Dispatcher` class][dispatcher-class] provides two channels: * [Lifecycle events][lifecycle-events]: A channel that sends a message whenever a [Dispatch][frequenz.dispatch.Dispatch] is created, updated or deleted. @@ -85,7 +84,7 @@ provides two channels: 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 +### Example managing actors with dispatch events ```python import os From 3c82cbef9619976a53a8fa1176d74b63a4cc0ecd Mon Sep 17 00:00:00 2001 From: Leandro Lucarella Date: Wed, 23 Jul 2025 09:39:35 +0200 Subject: [PATCH 8/8] Remove trailing whitespace Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> Signed-off-by: Leandro Lucarella --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 3926342..2bdd15e 100644 --- a/README.md +++ b/README.md @@ -127,7 +127,7 @@ async def run(): ## Documentation -For complete API documentation, examples, and advanced usage patterns, see +For complete API documentation, examples, and advanced usage patterns, see [the documentation](https://frequenz-floss.github.io/frequenz-dispatch-python/latest/reference/frequenz/dispatch). ## Contributing