sonata-tasks 0.6.1__tar.gz

sonata_tasks-0.6.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 miciav
+
+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.

sonata_tasks-0.6.1/PKG-INFO

@@ -0,0 +1,44 @@
+Metadata-Version: 2.4
+Name: sonata-tasks
+Version: 0.6.1
+Summary: Reusable task catalogue for the Sonata workflow engine
+Author-email: miciav <5889596+miciav@users.noreply.github.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/Nanofaas/sonata
+Project-URL: Repository, https://github.com/Nanofaas/sonata
+Project-URL: Issues, https://github.com/Nanofaas/sonata/issues
+Keywords: workflow,tasks,catalogue,orchestration,devops
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: System :: Distributed Computing
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: sonata-engine==0.6.1
+Provides-Extra: shell
+Requires-Dist: subprocess-toolkit==0.6.0; extra == "shell"
+Provides-Extra: prometheus
+Requires-Dist: httpx>=0.27; extra == "prometheus"
+Provides-Extra: multipass
+Requires-Dist: multipass-vm-sdk==0.6.0; extra == "multipass"
+Requires-Dist: pydantic>=2.9.2; extra == "multipass"
+Requires-Dist: subprocess-toolkit==0.6.0; extra == "multipass"
+Provides-Extra: azure
+Requires-Dist: azure-vm-sdk==0.6.0; extra == "azure"
+Requires-Dist: pydantic>=2.9.2; extra == "azure"
+Requires-Dist: subprocess-toolkit==0.6.0; extra == "azure"
+Provides-Extra: proxmox
+Requires-Dist: proxmox-vm-sdk==0.6.0; extra == "proxmox"
+Requires-Dist: pydantic>=2.9.2; extra == "proxmox"
+Requires-Dist: subprocess-toolkit==0.6.0; extra == "proxmox"
+Dynamic: license-file
+
+# sonata-tasks
+
+Reusable, product-independent tasks for `sonata-engine`. The base installation
+contains command execution contracts and common command-line tool tasks.
+Provider and transport integrations are installed through optional extras.

sonata_tasks-0.6.1/README.md

@@ -0,0 +1,5 @@
+# sonata-tasks
+
+Reusable, product-independent tasks for `sonata-engine`. The base installation
+contains command execution contracts and common command-line tool tasks.
+Provider and transport integrations are installed through optional extras.

sonata_tasks-0.6.1/pyproject.toml

@@ -0,0 +1,181 @@
+[project]
+name = "sonata-tasks"
+license = "MIT"
+license-files = ["LICENSE"]
+version = "0.6.1"
+description = "Reusable task catalogue for the Sonata workflow engine"
+readme = "README.md"
+requires-python = ">=3.12"
+authors = [
+    { name = "miciav", email = "5889596+miciav@users.noreply.github.com" }
+]
+keywords = ["workflow", "tasks", "catalogue", "orchestration", "devops"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: System :: Distributed Computing",
+]
+dependencies = [
+    "sonata-engine==0.6.1",
+]
+
+# PyPI shows a package page with no link home at all without these.
+[project.urls]
+Homepage = "https://github.com/Nanofaas/sonata"
+Repository = "https://github.com/Nanofaas/sonata"
+Issues = "https://github.com/Nanofaas/sonata/issues"
+
+[project.optional-dependencies]
+shell = [
+    "subprocess-toolkit==0.6.0",
+]
+prometheus = ["httpx>=0.27"]
+multipass = [
+    "multipass-vm-sdk==0.6.0",
+    "pydantic>=2.9.2",
+    "subprocess-toolkit==0.6.0",
+]
+azure = [
+    "azure-vm-sdk==0.6.0",
+    "pydantic>=2.9.2",
+    "subprocess-toolkit==0.6.0",
+]
+proxmox = [
+    "proxmox-vm-sdk==0.6.0",
+    "pydantic>=2.9.2",
+    "subprocess-toolkit==0.6.0",
+]
+
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+sonata_tasks = ["py.typed"]
+
+[dependency-groups]
+dev = [
+    "basedpyright>=1.39.3",
+    "httpx>=0.27",
+    "grimp>=3.14",
+    "import-linter>=2.11",
+    "pytest>=9.0.3",
+    "pytest-cov>=6.0",
+    # Pinned exactly to match the ruff-pre-commit revision in
+    # .pre-commit-config.yaml. A newer ruff in either place makes the hook and a
+    # local `ruff check` disagree about what a violation is. Bump both together.
+    "ruff==0.16.6",
+    "bandit>=1.8",
+    "pre-commit>=4.0",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+# The coverage threshold lives in [tool.coverage.report] and is deliberately
+# not repeated as --cov-fail-under here: stating it twice is how two values come
+# to disagree, with the command-line flag silently winning.
+addopts = "-q --cov=sonata_tasks --cov-report=term-missing"
+
+# =============================================================================
+# Ruff - linting + formatting
+# =============================================================================
+# Same rule set as the engine and the sibling projects.
+
+[tool.ruff]
+target-version = "py312"
+line-length = 88
+# See the same note in the engine's pyproject.toml: ruff does not exclude
+# `build` by default, and a stale build tree must not be linted as source.
+extend-exclude = ["build", "dist"]
+
+[tool.ruff.lint]
+select = [
+    "ANN",   # flake8-annotations
+    "E",     # pycodestyle errors
+    "W",     # pycodestyle warnings
+    "F",     # Pyflakes
+    "I",     # isort
+    "N",     # pep8-naming
+    "UP",    # pyupgrade
+    "B",     # flake8-bugbear
+    "C4",    # flake8-comprehensions
+    "SIM",   # flake8-simplify
+    "TID",   # flake8-tidy-imports
+    "RUF",   # Ruff-specific rules
+    "PERF",  # Perflint
+    "PT",    # flake8-pytest-style
+    "RET",   # flake8-return
+    "PTH",   # flake8-use-pathlib
+    "ERA",   # eradicate - commented-out code
+    "D",     # pydocstyle - this is a published package with a public API
+]
+ignore = [
+    # Mutually exclusive summary conventions; see the same note in the engine's
+    # pyproject.toml.
+    "D203",
+    "D213",
+    "PT018",
+]
+
+[tool.ruff.lint.isort]
+# Declared rather than inferred. Ruff derives first-party packages from the
+# project root, which changes with --config: run with this file as the config
+# and `sonata_tasks` was inferred as third-party, so the blank line separating
+# it from pytest was reported as an unsorted import, while running with the
+# engine's config reported nothing. Naming the packages makes both invocations
+# agree, and the catalogue legitimately imports both.
+known-first-party = ["sonata_tasks", "sonata_engine"]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**/*.py" = [
+    "ANN",
+    "D100", "D101", "D102", "D103", "D104", "D105", "D107",
+]
+"**/tests/**/*.py" = [
+    "ANN",
+    "D100", "D101", "D102", "D103", "D104", "D105", "D107",
+]
+
+# =============================================================================
+# Coverage
+# =============================================================================
+
+[tool.coverage.report]
+show_missing = true
+fail_under = 90
+
+# =============================================================================
+# basedpyright - type checking
+# =============================================================================
+
+[tool.basedpyright]
+include = ["src/sonata_tasks", "tests"]
+typeCheckingMode = "standard"
+reportImplicitOverride = true
+reportMissingTypeStubs = false
+venvPath = "../.."
+venv = ".venv"
+
+# =============================================================================
+# Bandit - security static analysis
+# =============================================================================
+# This package drives VMs and containers through external CLIs, so subprocess is
+# its subject matter rather than a smell.
+
+[tool.bandit]
+exclude_dirs = ["tests", ".venv"]
+skips = [
+    "B404",
+    "B603",
+    "B607",
+]

sonata_tasks-0.6.1/setup.cfg

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

sonata_tasks-0.6.1/src/sonata_tasks/__init__.py

@@ -0,0 +1,6 @@
+"""Reusable tasks for the Sonata workflow engine."""
+
+from sonata_tasks.core.command import CommandTask
+from sonata_tasks.execution.models import CommandOptions, CommandTaskSpec, TaskResult
+
+__all__ = ["CommandOptions", "CommandTask", "CommandTaskSpec", "TaskResult"]

sonata_tasks-0.6.1/src/sonata_tasks/ansible.py

@@ -0,0 +1,83 @@
+"""Run an Ansible playbook as a command task."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import replace
+from pathlib import Path
+
+from sonata_tasks.command import CommandTask
+from sonata_tasks.execution.models import CommandOptions
+from sonata_tasks.execution.ports import CommandTaskExecutor
+
+
+def build_ansible_argv(
+    *,
+    playbook: Path,
+    inventory: str,
+    user: str,
+    private_key_path: Path | None = None,
+    extra_vars: Mapping[str, str] | None = None,
+) -> tuple[str, ...]:
+    """Build the ``ansible-playbook`` argv for a playbook run.
+
+    ``private_key_path`` becomes ``--private-key`` and each ``extra_vars`` entry
+    becomes an ``-e key=value`` pair. The playbook is appended last as an
+    absolute path, so the command does not depend on the caller's working
+    directory.
+    """
+    argv = ["ansible-playbook", "-i", inventory, "-u", user]
+    if private_key_path is not None:
+        argv.extend(("--private-key", str(private_key_path)))
+    for key, value in (extra_vars or {}).items():
+        argv.extend(("-e", f"{key}={value}"))
+    argv.append(str(Path(playbook).absolute()))
+    return tuple(argv)
+
+
+class AnsiblePlaybookTask(CommandTask):
+    """Run a playbook against an inventory, optionally under a custom config.
+
+    Command building is left to :func:`build_ansible_argv`; this class only
+    folds ``ansible_config`` into the environment as ``ANSIBLE_CONFIG`` before
+    handing everything to :class:`~sonata_tasks.command.CommandTask`.
+    """
+
+    def __init__(
+        self,
+        *,
+        playbook: Path,
+        inventory: str,
+        user: str,
+        executor: CommandTaskExecutor,
+        role: str = "host",
+        private_key_path: Path | None = None,
+        extra_vars: Mapping[str, str] | None = None,
+        ansible_config: Path | None = None,
+        options: CommandOptions | None = None,
+        title: str | None = None,
+    ) -> None:
+        """Configure the playbook run.
+
+        ``ansible_config`` is exported as ``ANSIBLE_CONFIG`` on top of any
+        environment already set in ``options``. ``title`` defaults to the
+        playbook's file name, and ``role`` selects the executor binding.
+        """
+        current = options or CommandOptions()
+        if ansible_config is not None:
+            current = replace(
+                current, env={**current.env, "ANSIBLE_CONFIG": str(ansible_config)}
+            )
+        super().__init__(
+            title=title or f"Run Ansible playbook {Path(playbook).name}",
+            argv=build_ansible_argv(
+                playbook=playbook,
+                inventory=inventory,
+                user=user,
+                private_key_path=private_key_path,
+                extra_vars=extra_vars,
+            ),
+            executor=executor,
+            role=role,
+            options=current,
+        )

sonata_tasks-0.6.1/src/sonata_tasks/archive.py

@@ -0,0 +1,147 @@
+"""Ship a git commit's tree to a remote host as an extracted source archive."""
+
+from __future__ import annotations
+
+import contextlib
+import hashlib
+import subprocess
+import tempfile
+from pathlib import Path
+
+from sonata_engine import Resource, TaskInputs
+from sonata_tasks.compensation import best_effort
+from sonata_tasks.transfer import RemoteProvider
+
+
+def _exec[RequestT](
+    provider: RemoteProvider[RequestT], request: RequestT, argv: tuple[str, ...]
+) -> str:
+    result = provider.exec_argv(request, argv=argv)
+    if not isinstance(result.return_code, int) or isinstance(result.return_code, bool):
+        raise RuntimeError("remote command returned no integer return_code")
+    if result.return_code != 0:
+        detail = result.stderr or result.stdout
+        raise RuntimeError(
+            f"remote command failed (exit {result.return_code})"
+            + (f": {detail}" if detail else "")
+        )
+    return result.stdout
+
+
+def _transfer_archive[RequestT](
+    provider: RemoteProvider[RequestT],
+    request: RequestT,
+    archive_path: Path,
+    remote_archive: str,
+) -> None:
+    result = provider.transfer_to(
+        request, source=archive_path, destination=remote_archive
+    )
+    if not isinstance(result.return_code, int) or isinstance(result.return_code, bool):
+        raise RuntimeError("transfer returned no integer return_code")
+    if result.return_code != 0:
+        detail = result.stderr or result.stdout
+        raise RuntimeError(
+            f"transfer failed (exit {result.return_code})"
+            + (f": {detail}" if detail else "")
+        )
+
+
+def _verify_remote_archive[RequestT](
+    provider: RemoteProvider[RequestT],
+    request: RequestT,
+    remote_archive: str,
+    local_checksum: str,
+) -> None:
+    try:
+        remote_checksum = _exec(
+            provider, request, ("sha256sum", remote_archive)
+        ).split()[0]
+        if remote_checksum != local_checksum:
+            raise RuntimeError(
+                f"sha256sum mismatch: local={local_checksum}, remote={remote_checksum}"
+            )
+    except BaseException as error:
+        best_effort(
+            error,
+            lambda: provider.exec_argv(request, argv=("rm", "-f", remote_archive)),
+            what="cleanup remote archive after failed verify",
+        )
+        raise
+
+
+def _extract_remote_archive[RequestT](
+    provider: RemoteProvider[RequestT],
+    request: RequestT,
+    remote_archive: str,
+    remote_source_dir: str,
+) -> None:
+    try:
+        _exec(provider, request, ("mkdir", "-p", remote_source_dir))
+        _exec(
+            provider, request, ("tar", "-xf", remote_archive, "-C", remote_source_dir)
+        )
+    except BaseException as error:
+        best_effort(
+            error,
+            lambda: provider.exec_argv(
+                request, argv=("rm", "-rf", remote_source_dir, remote_archive)
+            ),
+            what="cleanup after failed extract",
+        )
+        raise
+
+
+def source_archive_resource[RequestT](
+    *,
+    repo_root: Path,
+    commit: str,
+    remote_source_dir: str,
+    remote_archive: str,
+    provider: RemoteProvider[RequestT],
+    request: RequestT,
+) -> Resource[str]:
+    """Package ``commit`` locally and unpack it on the remote host.
+
+    The commit is exported with ``git archive``, transferred, verified against
+    its local SHA-256, and extracted into ``remote_source_dir``. Acquiring
+    returns ``remote_source_dir``; releasing best-effort deletes that extracted
+    directory on the remote host.
+    """
+
+    def acquire(_inputs: TaskInputs) -> str:
+        with tempfile.TemporaryDirectory() as tmp:
+            archive_path = Path(tmp) / "source.tar"
+            subprocess.run(
+                [
+                    "git",
+                    "-C",
+                    str(repo_root),
+                    "archive",
+                    "--format=tar",
+                    commit,
+                    "-o",
+                    str(archive_path),
+                ],
+                check=True,
+                capture_output=True,
+                text=True,
+            )
+            checksum = hashlib.sha256(archive_path.read_bytes()).hexdigest()
+            _exec(provider, request, ("mkdir", "-p", str(Path(remote_archive).parent)))
+            _transfer_archive(provider, request, archive_path, remote_archive)
+            _verify_remote_archive(provider, request, remote_archive, checksum)
+            _extract_remote_archive(
+                provider, request, remote_archive, remote_source_dir
+            )
+        return remote_source_dir
+
+    def release(_inputs: TaskInputs, _state: str) -> None:
+        with contextlib.suppress(RuntimeError):
+            provider.exec_argv(request, argv=("rm", "-rf", remote_source_dir))
+
+    return Resource(
+        title=f"Acquire source archive at {remote_source_dir}",
+        acquire=acquire,
+        release=release,
+    )

sonata_tasks-0.6.1/src/sonata_tasks/buildx.py

@@ -0,0 +1,139 @@
+"""Manage a docker buildx builder as a resource."""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Sequence
+from dataclasses import replace
+from typing import Any
+
+from sonata_engine import Resource, TaskInputs
+from sonata_tasks.command import CommandTask
+from sonata_tasks.compensation import best_effort
+from sonata_tasks.execution.models import CommandOptions, TaskResult
+from sonata_tasks.execution.ports import CommandTaskExecutor
+
+
+def _run(
+    inputs: TaskInputs,
+    executor: CommandTaskExecutor,
+    role: str,
+    options: CommandOptions,
+    *args: str,
+    expected: frozenset[int] = frozenset({0}),
+) -> TaskResult:
+    outcome = CommandTask(
+        title=f"docker buildx {' '.join(args)}",
+        argv=("docker", "buildx", *args),
+        executor=executor,
+        role=role,
+        options=replace(options, expected_exit_codes=expected),
+    ).run(inputs)
+    if outcome.value is None:
+        raise RuntimeError("docker buildx returned no command result")
+    return outcome.value
+
+
+def _create_argv(
+    name: str,
+    buildkitd_config: str | None,
+    driver_options: Sequence[str],
+) -> tuple[str, ...]:
+    argv = ["create", "--name", name, "--driver", "docker-container"]
+    if buildkitd_config is not None:
+        argv.extend(("--buildkitd-config", buildkitd_config))
+    for option in driver_options:
+        argv.extend(("--driver-opt", option))
+    argv.append("--use")
+    return tuple(argv)
+
+
+def _validate_output(validate: Callable[[str], None] | None, stdout: str) -> None:
+    if validate is not None:
+        validate(stdout)
+
+
+def buildx_builder_resource(
+    *,
+    name: str,
+    executor: CommandTaskExecutor,
+    role: str = "host",
+    options: CommandOptions | None = None,
+    requires: tuple[Resource[Any], ...] = (),
+    buildkitd_config: str | None = None,
+    # Driver options the created builder gets, as `--driver-opt` arguments. A
+    # `docker-container` builder runs buildkitd in a container of its own, so
+    # its `localhost` is itself: reaching a registry on the host's loopback
+    # needs `network=host` here, and buildkitd's own `[worker.oci] networkMode`
+    # does not substitute, because that governs the network of build steps
+    # rather than the daemon that pushes.
+    driver_options: Sequence[str] = (),
+    validate: Callable[[str], None] | None = None,
+    validation_key: str | None = None,
+    replace_existing: bool = False,
+) -> Resource[str]:
+    """Acquire a named docker buildx builder, bootstrapping it when missing.
+
+    Acquiring inspects the builder. A missing one — or one that
+    ``replace_existing`` asks to redo, which is removed first — is created as a
+    ``docker-container`` builder with ``--use`` and any ``driver_options``,
+    bootstrapped, and checked through ``validate``. Acquiring returns the builder
+    name for a builder this resource created, or ``"existing"`` when it left a
+    pre-existing builder untouched; releasing removes only the former.
+
+    Raises:
+        ValueError: If ``validate`` is configured without a ``validation_key``.
+
+    """
+    if validate is not None and not validation_key:
+        raise ValueError("validation_key is required when validate is configured")
+    current = options or CommandOptions()
+
+    def remove(inputs: TaskInputs) -> None:
+        _ = _run(inputs, executor, role, current, "rm", "--force", name)
+
+    def bootstrap(inputs: TaskInputs) -> None:
+        try:
+            _ = _run(
+                inputs,
+                executor,
+                role,
+                current,
+                *_create_argv(name, buildkitd_config, driver_options),
+            )
+            result = _run(
+                inputs, executor, role, current, "inspect", "--bootstrap", name
+            )
+            _validate_output(validate, result.stdout)
+        except BaseException as error:
+            best_effort(
+                error,
+                lambda: remove(inputs),
+                what=f"cleanup failed buildx builder {name}",
+            )
+            raise
+
+    def acquire(inputs: TaskInputs) -> str:
+        inspected = _run(
+            inputs, executor, role, current, "inspect", name, expected=frozenset({0, 1})
+        )
+        if inspected.return_code != 0:
+            bootstrap(inputs)
+            return name
+        if not replace_existing:
+            _validate_output(validate, inspected.stdout)
+            return "existing"
+        remove(inputs)
+        bootstrap(inputs)
+        return name
+
+    def release(inputs: TaskInputs, state: str) -> None:
+        if state != "existing":
+            remove(inputs)
+
+    return Resource(
+        title=f"Acquire {name} buildx builder",
+        acquire=acquire,
+        release=release,
+        requires=requires,
+        always_release=True,
+    )

sonata_tasks-0.6.1/src/sonata_tasks/command.py

@@ -0,0 +1,5 @@
+"""Compatibility import for the public command task."""
+
+from sonata_tasks.core.command import Argv, CommandTask
+
+__all__ = ["Argv", "CommandTask"]