frequenz-dispatch 0.1.0__tar.gz

frequenz-dispatch-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright © 2024 Frequenz Energy-as-a-Service GmbH
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

frequenz-dispatch-0.1.0/MANIFEST.in

@@ -0,0 +1,13 @@
+exclude .cookiecutter-replay.json
+exclude .editorconfig
+exclude .gitignore
+exclude CODEOWNERS
+exclude CONTRIBUTING.md
+exclude mkdocs.yml
+exclude noxfile.py
+exclude src/conftest.py
+recursive-exclude .github *
+recursive-exclude benchmarks *
+recursive-exclude docs *
+recursive-exclude tests *
+recursive-include py *.pyi

frequenz-dispatch-0.1.0/PKG-INFO

@@ -0,0 +1,109 @@
+Metadata-Version: 2.1
+Name: frequenz-dispatch
+Version: 0.1.0
+Summary: A highlevel interface for the dispatch API
+Author-email: Frequenz Energy-as-a-Service GmbH <floss@frequenz.com>
+License: MIT
+Project-URL: Documentation, https://frequenz-floss.github.io/frequenz-dispatch-python/
+Project-URL: Changelog, https://github.com/frequenz-floss/frequenz-dispatch-python/releases
+Project-URL: Issues, https://github.com/frequenz-floss/frequenz-dispatch-python/issues
+Project-URL: Repository, https://github.com/frequenz-floss/frequenz-dispatch-python
+Project-URL: Support, https://github.com/frequenz-floss/frequenz-dispatch-python/discussions/categories/support
+Keywords: frequenz,python,actor,frequenz-dispatch,dispatch,highlevel,api
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Typing :: Typed
+Requires-Python: <4,>=3.11
+Description-Content-Type: text/markdown
+Provides-Extra: dev-flake8
+Provides-Extra: dev-formatting
+Provides-Extra: dev-mkdocs
+Provides-Extra: dev-mypy
+Provides-Extra: dev-noxfile
+Provides-Extra: dev-pylint
+Provides-Extra: dev-pytest
+Provides-Extra: dev
+License-File: LICENSE
+
+# Dispatch Highlevel Interface
+
+[![Build Status](https://github.com/frequenz-floss/frequenz-dispatch-python/actions/workflows/ci.yaml/badge.svg)](https://github.com/frequenz-floss/frequenz-dispatch-python/actions/workflows/ci.yaml)
+[![PyPI Package](https://img.shields.io/pypi/v/frequenz-dispatch)](https://pypi.org/project/frequenz-dispatch/)
+[![Docs](https://img.shields.io/badge/docs-latest-informational)](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
+import grpc.aio
+from unittest.mock import MagicMock
+
+async def run():
+    host = os.getenv("DISPATCH_API_HOST", "localhost")
+    port = os.getenv("DISPATCH_API_PORT", "50051")
+
+    service_address = f"{host}:{port}"
+    grpc_channel = grpc.aio.insecure_channel(service_address)
+    microgrid_id = 1
+    dispatcher = Dispatcher(microgrid_id, grpc_channel, service_address)
+    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).

frequenz-dispatch-0.1.0/README.md

@@ -0,0 +1,78 @@
+# Dispatch Highlevel Interface
+
+[![Build Status](https://github.com/frequenz-floss/frequenz-dispatch-python/actions/workflows/ci.yaml/badge.svg)](https://github.com/frequenz-floss/frequenz-dispatch-python/actions/workflows/ci.yaml)
+[![PyPI Package](https://img.shields.io/pypi/v/frequenz-dispatch)](https://pypi.org/project/frequenz-dispatch/)
+[![Docs](https://img.shields.io/badge/docs-latest-informational)](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
+import grpc.aio
+from unittest.mock import MagicMock
+
+async def run():
+    host = os.getenv("DISPATCH_API_HOST", "localhost")
+    port = os.getenv("DISPATCH_API_PORT", "50051")
+
+    service_address = f"{host}:{port}"
+    grpc_channel = grpc.aio.insecure_channel(service_address)
+    microgrid_id = 1
+    dispatcher = Dispatcher(microgrid_id, grpc_channel, service_address)
+    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).

frequenz-dispatch-0.1.0/RELEASE_NOTES.md

@@ -0,0 +1,14 @@
+# Dispatch Highlevel Interface Release Notes
+
+## Summary
+
+This is the first release of the highlevel dispatch interface!
+
+## Upgrading
+
+* `Dispatcher.ready_to_execute()` was renamed to `Dispatcher.running_status_change()`
+
+## New Features
+
+* Introduced new class `Dispatch` (based on the client class) that contains useful functions and extended information about the received dispatch.
+* `Dispatcher.client` was added to provide an easy access to the client for updating, deleting and creating dispatches

frequenz-dispatch-0.1.0/pyproject.toml

@@ -0,0 +1,184 @@
+# License: MIT
+# Copyright © 2024 Frequenz Energy-as-a-Service GmbH
+
+[build-system]
+requires = [
+  "setuptools == 68.1.0",
+  "setuptools_scm[toml] == 7.1.0",
+  "frequenz-repo-config[lib] == 0.9.2",
+]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "frequenz-dispatch"
+description = "A highlevel interface for the dispatch API"
+readme = "README.md"
+license = { text = "MIT" }
+keywords = [
+  "frequenz",
+  "python",
+  "actor",
+  "frequenz-dispatch",
+  "dispatch",
+  "highlevel",
+  "api",
+]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Topic :: Software Development :: Libraries",
+  "Typing :: Typed",
+]
+requires-python = ">= 3.11, < 4"
+dependencies = [
+  "python-dateutil >= 2.8.2, < 3.0",
+  "typing-extensions == 4.11.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 == v1.0.0-rc6",
+  "frequenz-channels == 1.0.0",
+  "frequenz-api-dispatch >= 0.13.0, < 0.14",
+  "frequenz-client-dispatch == 0.2.0",
+  "frequenz-client-base >= 0.3.0, < 0.4.0",
+  "frequenz-client-common >= 0.1.0, < 0.2.0",
+]
+dynamic = ["version"]
+
+[[project.authors]]
+name = "Frequenz Energy-as-a-Service GmbH"
+email = "floss@frequenz.com"
+
+[project.optional-dependencies]
+dev-flake8 = [
+  "flake8 == 7.0.0",
+  "flake8-docstrings == 1.7.0",
+  "flake8-pyproject == 1.2.3",  # For reading the flake8 config from pyproject.toml
+  "pydoclint == 0.4.1",
+  "pydocstyle == 6.3.0",
+]
+dev-formatting = ["black == 24.4.2", "isort == 5.13.2"]
+dev-mkdocs = [
+  "black == 24.4.2",
+  "Markdown==3.6",
+  "mike == 2.1.0",
+  "mkdocs-gen-files == 0.5.0",
+  "mkdocs-literate-nav == 0.6.1",
+  "mkdocs-macros-plugin == 1.0.5",
+  "mkdocs-material == 9.5.20",
+  "mkdocstrings[python] == 0.25.0",
+  "frequenz-repo-config[lib] == 0.9.2",
+]
+dev-mypy = [
+  "mypy == 1.10.0",
+  "types-Markdown == 3.6.0.20240316",
+  "types-python-dateutil==2.9.0.20240316",
+  # For checking the noxfile, docs/ script, and tests
+  "frequenz-dispatch[dev-mkdocs,dev-noxfile,dev-pytest]",
+]
+dev-noxfile = [
+  "uv == 0.1.39",
+  "nox == 2024.4.15",
+  "frequenz-repo-config[lib] == 0.9.2",
+]
+dev-pylint = [
+  "pylint == 3.1.0",
+  # For checking the noxfile, docs/ script, and tests
+  "frequenz-dispatch[dev-mkdocs,dev-noxfile,dev-pytest]",
+]
+dev-pytest = [
+  "pytest == 8.2.0",
+  "frequenz-repo-config[extra-lint-examples] == 0.9.2",
+  "pytest-mock == 3.14.0",
+  "pytest-asyncio == 0.23.6",
+  "async-solipsism == 0.6",
+  "time-machine == 2.14.1",
+]
+dev = [
+  "frequenz-dispatch[dev-mkdocs,dev-flake8,dev-formatting,dev-mkdocs,dev-mypy,dev-noxfile,dev-pylint,dev-pytest]",
+]
+
+[project.urls]
+Documentation = "https://frequenz-floss.github.io/frequenz-dispatch-python/"
+Changelog = "https://github.com/frequenz-floss/frequenz-dispatch-python/releases"
+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"
+
+[tool.black]
+line-length = 88
+target-version = ['py311']
+include = '\.pyi?$'
+
+[tool.isort]
+profile = "black"
+line_length = 88
+src_paths = ["benchmarks", "examples", "src", "tests"]
+
+[tool.flake8]
+# We give some flexibility to go over 88, there are cases like long URLs or
+# code in documenation that have extra indentation. Black will still take care
+# of making everything that can be 88 wide, 88 wide.
+max-line-length = 100
+extend-ignore = [
+  "E203", # Whitespace before ':' (conflicts with black)
+  "W503", # Line break before binary operator (conflicts with black)
+]
+# pydoclint options
+style = "google"
+check-return-types = false
+check-yield-types = false
+arg-type-hints-in-docstring = false
+arg-type-hints-in-signature = true
+allow-init-docstring = true
+
+[tool.pylint.similarities]
+ignore-comments = ['yes']
+ignore-docstrings = ['yes']
+ignore-imports = ['no']
+min-similarity-lines = 40
+
+[tool.pylint.messages_control]
+disable = [
+  "too-few-public-methods",
+  "too-many-return-statements",
+  # disabled because it conflicts with isort
+  "wrong-import-order",
+  "ungrouped-imports",
+  # pylint's unsubscriptable check is buggy and is not needed because
+  # it is a type-check, for which we already have mypy.
+  "unsubscriptable-object",
+  # Checked by flake8
+  "line-too-long",
+  "redefined-outer-name",
+  "unnecessary-lambda-assignment",
+  "unused-import",
+  "unused-variable",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests", "src"]
+asyncio_mode = "auto"
+required_plugins = ["pytest-asyncio", "pytest-mock"]
+
+[tool.mypy]
+explicit_package_bases = true
+namespace_packages = true
+# This option disables mypy cache, and it is sometimes useful to enable it if
+# you are getting weird intermittent error, or error in the CI but not locally
+# (or vice versa). In particular errors saying that type: ignore is not
+# used but getting the original ignored error when removing the type: ignore.
+# See for example: https://github.com/python/mypy/issues/2960
+#no_incremental = true
+packages = ["frequenz.dispatch"]
+strict = true
+
+[[tool.mypy.overrides]]
+module = ["mkdocs_macros.*", "async_solipsism", "async_solipsism.*"]
+ignore_missing_imports = true
+
+[tool.setuptools_scm]
+version_scheme = "post-release"

frequenz-dispatch-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

frequenz-dispatch-0.1.0/src/frequenz/dispatch/__init__.py

@@ -0,0 +1,29 @@
+# License: MIT
+# Copyright © 2024 Frequenz Energy-as-a-Service GmbH
+
+"""A highlevel interface for the dispatch API.
+
+A small overview of the most important classes in this module:
+
+* [Dispatcher][frequenz.dispatch.Dispatcher]: The entry point for the API.
+* [Dispatch][frequenz.dispatch.Dispatch]: A dispatch type with lots of useful extra functionality.
+* [Created][frequenz.dispatch.Created],
+  [Updated][frequenz.dispatch.Updated],
+  [Deleted][frequenz.dispatch.Deleted]: Dispatch event types.
+
+"""
+
+from ._dispatch import Dispatch, RunningState
+from ._dispatcher import Dispatcher, ReceiverFetcher
+from ._event import Created, Deleted, DispatchEvent, Updated
+
+__all__ = [
+    "Created",
+    "Deleted",
+    "DispatchEvent",
+    "Dispatcher",
+    "ReceiverFetcher",
+    "Updated",
+    "Dispatch",
+    "RunningState",
+]