# Dispatch Highlevel Interface
[](https://github.com/frequenz-floss/frequenz-dispatch-python/actions/workflows/ci.yaml)
[](https://pypi.org/project/frequenz-dispatch/)
[](https://frequenz-floss.github.io/frequenz-dispatch-python/)
## Introduction
A highlevel interface for the dispatch API.
See [the documentation](https://frequenz-floss.github.io/frequenz-dispatch-python/v0.1/reference/frequenz/dispatch) for more information.
## Usage
The [`Dispatcher` class](https://frequenz-floss.github.io/frequenz-dispatch-python/v0.1/reference/frequenz/dispatch/#frequenz.dispatch.Dispatcher), the main entry point for the API, provides two channels:
* [Lifecycle events](https://frequenz-floss.github.io/frequenz-dispatch-python/v0.1/reference/frequenz/dispatch/#frequenz.dispatch.Dispatcher.lifecycle_events): A channel that sends a message whenever a [Dispatch][frequenz.dispatch.Dispatch] is created, updated or deleted.
* [Running status change](https://frequenz-floss.github.io/frequenz-dispatch-python/v0.1/reference/frequenz/dispatch/#frequenz.dispatch.Dispatcher.running_status_change): Sends a dispatch message whenever a dispatch is ready to be executed according to the schedule or the running status of the dispatch changed in a way that could potentially require the actor to start, stop or reconfigure itself.
### Example using the running status change channel
```python
import os
from frequenz.dispatch import Dispatcher
from unittest.mock import MagicMock
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
)
await dispatcher.start()
actor = MagicMock() # replace with your actor
changed_running_status_rx = dispatcher.running_status_change.new_receiver()
async for dispatch in changed_running_status_rx:
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
The following platforms are officially supported (tested):
- **Python:** 3.11
- **Operating System:** Ubuntu Linux 20.04
- **Architectures:** amd64, arm64
## Contributing
If you want to know how to build this project and contribute to it, please
check out the [Contributing Guide](CONTRIBUTING.md).
Raw data
{
"_id": null,
"home_page": null,
"name": "frequenz-dispatch",
"maintainer": null,
"docs_url": null,
"requires_python": "<4,>=3.11",
"maintainer_email": null,
"keywords": "frequenz, python, actor, frequenz-dispatch, dispatch, highlevel, api",
"author": null,
"author_email": "Frequenz Energy-as-a-Service GmbH <floss@frequenz.com>",
"download_url": "https://files.pythonhosted.org/packages/50/af/5d02d717dd803fdc4ffe4fdae7332d8e8eab3850d9631fdda1be1fb1571d/frequenz_dispatch-0.5.0.tar.gz",
"platform": null,
"description": "# Dispatch Highlevel Interface\n\n[](https://github.com/frequenz-floss/frequenz-dispatch-python/actions/workflows/ci.yaml)\n[](https://pypi.org/project/frequenz-dispatch/)\n[](https://frequenz-floss.github.io/frequenz-dispatch-python/)\n\n## Introduction\n\nA highlevel interface for the dispatch API.\n\nSee [the documentation](https://frequenz-floss.github.io/frequenz-dispatch-python/v0.1/reference/frequenz/dispatch) for more information.\n\n## Usage\n\nThe [`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:\n\n* [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.\n* [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.\n\n### Example using the running status change channel\n\n```python\nimport os\nfrom frequenz.dispatch import Dispatcher\nfrom unittest.mock import MagicMock\n\nasync def run():\n url = os.getenv(\"DISPATCH_API_URL\", \"grpc://fz-0004.frequenz.io:50051\")\n key = os.getenv(\"DISPATCH_API_KEY\", \"some-key\")\n\n microgrid_id = 1\n\n dispatcher = Dispatcher(\n microgrid_id=microgrid_id,\n server_url=url,\n key=key\n )\n await dispatcher.start()\n\n actor = MagicMock() # replace with your actor\n\n changed_running_status_rx = dispatcher.running_status_change.new_receiver()\n\n async for dispatch in changed_running_status_rx:\n if dispatch.type != \"MY_TYPE\":\n continue\n\n if dispatch.started:\n print(f\"Executing dispatch {dispatch.id}, due on {dispatch.start_time}\")\n if actor.is_running:\n actor.reconfigure(\n components=dispatch.target,\n run_parameters=dispatch.payload, # custom actor parameters\n dry_run=dispatch.dry_run,\n until=dispatch.until,\n ) # this will reconfigure the actor\n else:\n # this will start a new actor with the given components\n # and run it for the duration of the dispatch\n actor.start(\n components=dispatch.target,\n run_parameters=dispatch.payload, # custom actor parameters\n dry_run=dispatch.dry_run,\n until=dispatch.until,\n )\n else:\n actor.stop() # this will stop the actor\n```\n\n## Supported Platforms\n\nThe following platforms are officially supported (tested):\n\n- **Python:** 3.11\n- **Operating System:** Ubuntu Linux 20.04\n- **Architectures:** amd64, arm64\n\n## Contributing\n\nIf you want to know how to build this project and contribute to it, please\ncheck out the [Contributing Guide](CONTRIBUTING.md).\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A highlevel interface for the dispatch API",
"version": "0.5.0",
"project_urls": {
"Changelog": "https://github.com/frequenz-floss/frequenz-dispatch-python/releases",
"Documentation": "https://frequenz-floss.github.io/frequenz-dispatch-python/",
"Issues": "https://github.com/frequenz-floss/frequenz-dispatch-python/issues",
"Repository": "https://github.com/frequenz-floss/frequenz-dispatch-python",
"Support": "https://github.com/frequenz-floss/frequenz-dispatch-python/discussions/categories/support"
},
"split_keywords": [
"frequenz",
" python",
" actor",
" frequenz-dispatch",
" dispatch",
" highlevel",
" api"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "2a1d29223286721a2c17b0e3a634f74fd636fb33be0589d0afc1bb2b12aea97d",
"md5": "754fd3ad1ada9bcc293ae4b12beeaaeb",
"sha256": "cf923a09ba8bfa8cbc0b6f59c16fcfcfd1f3f4cafb773dbc6d2ed85e0b5a1bfa"
},
"downloads": -1,
"filename": "frequenz_dispatch-0.5.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "754fd3ad1ada9bcc293ae4b12beeaaeb",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4,>=3.11",
"size": 14893,
"upload_time": "2024-12-04T18:07:03",
"upload_time_iso_8601": "2024-12-04T18:07:03.799037Z",
"url": "https://files.pythonhosted.org/packages/2a/1d/29223286721a2c17b0e3a634f74fd636fb33be0589d0afc1bb2b12aea97d/frequenz_dispatch-0.5.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "50af5d02d717dd803fdc4ffe4fdae7332d8e8eab3850d9631fdda1be1fb1571d",
"md5": "e431fa808f357367a4a38ecbcfd9f599",
"sha256": "746fcc075c440f7f8df781062e90818094bf74f9af74717db0dfa014872f094d"
},
"downloads": -1,
"filename": "frequenz_dispatch-0.5.0.tar.gz",
"has_sig": false,
"md5_digest": "e431fa808f357367a4a38ecbcfd9f599",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4,>=3.11",
"size": 15607,
"upload_time": "2024-12-04T18:07:05",
"upload_time_iso_8601": "2024-12-04T18:07:05.745740Z",
"url": "https://files.pythonhosted.org/packages/50/af/5d02d717dd803fdc4ffe4fdae7332d8e8eab3850d9631fdda1be1fb1571d/frequenz_dispatch-0.5.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-12-04 18:07:05",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "frequenz-floss",
"github_project": "frequenz-dispatch-python",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "frequenz-dispatch"
}
JSON
