# 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, RunningState
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:
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.selector,
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.selector,
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
```
## 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/6d/13/3570a8bd838cfc34080052b37fdceaef1f7f28d9f16821e7c34464389b65/frequenz-dispatch-0.3.4.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, RunningState\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 match dispatch.running(\"DEMO_TYPE\"):\n case RunningState.RUNNING:\n print(f\"Executing dispatch {dispatch.id}, due on {dispatch.start_time}\")\n if actor.is_running:\n actor.reconfigure(\n components=dispatch.selector,\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.selector,\n run_parameters=dispatch.payload, # custom actor parameters\n dry_run=dispatch.dry_run,\n until=dispatch.until,\n )\n case RunningState.STOPPED:\n actor.stop() # this will stop the actor\n case RunningState.DIFFERENT_TYPE:\n pass # dispatch not for this type\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.3.4",
"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": "b956e3cc7dbc3a722f6c343ff3740063c98decf03c859b0bc2ccfeea9228246f",
"md5": "6ad59d0693c9d4d0d3dfb1046812f0b1",
"sha256": "18098d83c0d5a822da881722a0e0b24b3a9fe5a8f3fb43ff00c23556c9db7fd8"
},
"downloads": -1,
"filename": "frequenz_dispatch-0.3.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "6ad59d0693c9d4d0d3dfb1046812f0b1",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4,>=3.11",
"size": 16603,
"upload_time": "2024-10-24T09:37:14",
"upload_time_iso_8601": "2024-10-24T09:37:14.114937Z",
"url": "https://files.pythonhosted.org/packages/b9/56/e3cc7dbc3a722f6c343ff3740063c98decf03c859b0bc2ccfeea9228246f/frequenz_dispatch-0.3.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "6d133570a8bd838cfc34080052b37fdceaef1f7f28d9f16821e7c34464389b65",
"md5": "2fa57c52f4ce020e01a0e10582b6e52d",
"sha256": "e4b241149123a06468f101654634c0046e72d13d8b621de2a306ffecb2c03581"
},
"downloads": -1,
"filename": "frequenz-dispatch-0.3.4.tar.gz",
"has_sig": false,
"md5_digest": "2fa57c52f4ce020e01a0e10582b6e52d",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4,>=3.11",
"size": 16751,
"upload_time": "2024-10-24T09:37:15",
"upload_time_iso_8601": "2024-10-24T09:37:15.435185Z",
"url": "https://files.pythonhosted.org/packages/6d/13/3570a8bd838cfc34080052b37fdceaef1f7f28d9f16821e7c34464389b65/frequenz-dispatch-0.3.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-24 09:37:15",
"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
