# 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/e5/ed/6ebdf9a8b22051d0e347ae94c5553403db6a6cf168af20dc2c217ab19629/frequenz_dispatch-0.5.1.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.1",
"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": null,
"digests": {
"blake2b_256": "9d8d514e267b9eac04d7ed10d4736c072a78eeaafdca48239044bf5872973158",
"md5": "c58334977cb41a3626af70b9f40021cd",
"sha256": "bb24c072a62f4a69443d214ef888cff886501649a2068a6fd839c2f77c21cb5a"
},
"downloads": -1,
"filename": "frequenz_dispatch-0.5.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "c58334977cb41a3626af70b9f40021cd",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4,>=3.11",
"size": 14893,
"upload_time": "2025-01-24T13:12:01",
"upload_time_iso_8601": "2025-01-24T13:12:01.594106Z",
"url": "https://files.pythonhosted.org/packages/9d/8d/514e267b9eac04d7ed10d4736c072a78eeaafdca48239044bf5872973158/frequenz_dispatch-0.5.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "e5ed6ebdf9a8b22051d0e347ae94c5553403db6a6cf168af20dc2c217ab19629",
"md5": "5a9ca6b085686b1358c2b8e182ab9f84",
"sha256": "2fadca6286c36d39f655fb7a272f6eae2381fb8c1f8715ba4b5b2bdb9c2c2f20"
},
"downloads": -1,
"filename": "frequenz_dispatch-0.5.1.tar.gz",
"has_sig": false,
"md5_digest": "5a9ca6b085686b1358c2b8e182ab9f84",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4,>=3.11",
"size": 15441,
"upload_time": "2025-01-24T13:12:03",
"upload_time_iso_8601": "2025-01-24T13:12:03.036357Z",
"url": "https://files.pythonhosted.org/packages/e5/ed/6ebdf9a8b22051d0e347ae94c5553403db6a6cf168af20dc2c217ab19629/frequenz_dispatch-0.5.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-01-24 13:12:03",
"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
