pywhales 0.2.1__py3-none-any.whl

pywhales/__init__.py

@@ -0,0 +1,48 @@
+from .client_config import ClientNotFoundError
+from .components.buildx.cli_wrapper import Builder
+from .components.config.cli_wrapper import Config
+from .components.container.cli_wrapper import Container, ContainerStats
+from .components.context.cli_wrapper import (
+    Context,
+    DockerContextConfig,
+    KubernetesContextConfig,
+)
+from .components.image.cli_wrapper import Image
+from .components.network.cli_wrapper import Network
+from .components.node.cli_wrapper import Node
+from .components.plugin.cli_wrapper import Plugin
+from .components.secret.cli_wrapper import Secret
+from .components.service.cli_wrapper import Service
+from .components.stack.cli_wrapper import Stack
+from .components.system.cli_wrapper import SystemInfo
+from .components.task.cli_wrapper import Task
+from .components.volume.cli_wrapper import Volume
+from .docker_client import DockerClient, Version
+from .exceptions import DockerException
+
+# alias
+docker = DockerClient(client_type="docker")
+
+__all__ = [
+    "Builder",
+    "ClientNotFoundError",
+    "Config",
+    "Container",
+    "ContainerStats",
+    "Context",
+    "DockerClient",
+    "DockerContextConfig",
+    "DockerException",
+    "Image",
+    "KubernetesContextConfig",
+    "Network",
+    "Node",
+    "Plugin",
+    "Secret",
+    "Service",
+    "Stack",
+    "SystemInfo",
+    "Task",
+    "Version",
+    "Volume",
+]

pywhales/client_config.py

@@ -0,0 +1,325 @@
+import json
+import os
+import shutil
+import tempfile
+import warnings
+from collections.abc import Iterable, Mapping, Sequence
+from dataclasses import dataclass, field
+from datetime import datetime, timedelta
+from pathlib import Path
+from typing import Any, Literal, override
+
+import pydantic
+
+from . import utils
+from .utils import ValidPath, run, to_list
+
+CACHE_VALIDITY_PERIOD: float = 0.01
+
+
+class ParsingError(Exception):
+    pass
+
+
+class ClientNotFoundError(Exception):
+    pass
+
+
+class Command(list[object]):
+    def add_simple_arg(self, name: str, value: object) -> None:
+        if value is not None:
+            self.extend([name, value])
+
+    def add_flag(self, name: str, value: bool) -> None:
+        if value:
+            self.append(name)
+
+    def add_args_iterable(self, arg_name: str, values: Iterable[object]) -> None:
+        for value in values:
+            self.extend([arg_name, value])
+
+    def add_args_iterable_or_single(
+        self, arg_name: str, iterable_or_single: object
+    ) -> None:
+        for value in to_list(iterable_or_single):
+            self.extend([arg_name, value])
+
+    def add_args_mapping(
+        self, arg_name: str, mapping: Mapping[str, object], *, separator: str = "="
+    ) -> None:
+        self.add_args_iterable(
+            arg_name, utils.format_mapping_for_cli(mapping, separator)
+        )
+
+    @override
+    def __add__[ElementT](self, other: list[ElementT]) -> Command:
+        return Command(super().__add__(other))
+
+
+@dataclass
+class ClientConfig:
+    config: ValidPath | None = None
+    context: str | None = None
+    debug: bool | None = None
+    host: str | None = None
+    log_level: str | None = None
+    tls: bool | None = None
+    tlscacert: ValidPath | None = None
+    tlscert: ValidPath | None = None
+    tlskey: ValidPath | None = None
+    tlsverify: bool | None = None
+    client_binary_path: ValidPath | None = None
+    compose_files: list[ValidPath] = field(default_factory=list)
+    compose_profiles: list[str] = field(default_factory=list)
+    compose_env_file: ValidPath | None = None
+    compose_env_files: Sequence[ValidPath] = field(default_factory=list)
+    compose_project_name: str | None = None
+    compose_project_directory: ValidPath | None = None
+    compose_compatibility: bool | None = None
+    client_call: list[str] = field(default_factory=lambda: ["docker"])
+    client_type: Literal["docker", "nerdctl", "unknown"] = "unknown"
+    _client_call_with_path: list[Path | str] | None = None
+    compose_dry_run: bool = False
+    compose_parallel: int | None = None
+    compose_progress: Literal["auto", "tty", "plain", "json", "quiet"] | None = None
+
+    def get_client_call_with_path(self) -> list[Path | str]:
+        if self._client_call_with_path is None:
+            self._client_call_with_path = [
+                Path(self._get_docker_path()),
+                *self.client_call[1:],
+            ]
+
+        return self._client_call_with_path
+
+    def _get_docker_path(self) -> str:
+        which_result = shutil.which(self.client_call[0])
+        if which_result is None:
+            raise ClientNotFoundError(
+                f"The binary '{self.client_call[0]}' could not be found on your PATH. "
+                "Please ensure that your PATH has the directory of the binary you're looking for. "
+                "You can use `print(os.environ['PATH'])` to verify what directories are in your PATH."
+            )
+        return which_result
+
+    @property
+    def docker_cmd(self) -> Command:
+        result = Command(self.get_client_call_with_path())
+
+        if self.config is not None:
+            result += ["--config", self.config]
+
+        if self.context is not None:
+            result += ["--context", self.context]
+
+        if self.debug is True:
+            result.append("--debug")
+
+        if self.host is not None:
+            result += ["--host", self.host]
+
+        if self.log_level is not None:
+            result += ["--log-level", self.log_level]
+
+        if self.tls is True:
+            result.append("--tls")
+
+        if self.tlscacert is not None:
+            result += ["--tlscacert", self.tlscacert]
+
+        if self.tlscert is not None:
+            result += ["--tlscert", self.tlscert]
+
+        if self.tlskey is not None:
+            result += ["--tlskey", self.tlskey]
+
+        if self.tlsverify is True:
+            result.append("--tlsverify")
+
+        return result
+
+    @property
+    def docker_compose_cmd(self) -> Command:
+        return self.get_compose_command()
+
+    def get_compose_command(self, *, progress: str | None = None) -> Command:
+        """Build Compose globals, optionally overriding progress for one command."""
+        base_cmd = Command([*self.docker_cmd, "compose"])
+        base_cmd.add_args_iterable_or_single("--file", self.compose_files)
+        base_cmd.add_args_iterable_or_single("--profile", self.compose_profiles)
+        if self.compose_env_files:
+            if self.compose_env_file is not None:
+                warnings.warn(
+                    "You can't set both `compose_env_file` and `compose_env_files`. Files used in `compose_env_files` will be used.",
+                    stacklevel=2,
+                )
+            base_cmd.add_args_iterable("--env-file", self.compose_env_files)
+        elif self.compose_env_file is not None:
+            warnings.warn(
+                "`compose_env_file` is deprecated. Use `compose_env_files` instead.",
+                stacklevel=2,
+            )
+            base_cmd.add_simple_arg("--env-file", self.compose_env_file)
+
+        base_cmd.add_simple_arg("--project-name", self.compose_project_name)
+        base_cmd.add_simple_arg("--project-directory", self.compose_project_directory)
+        base_cmd.add_flag("--compatibility", self.compose_compatibility is True)
+        base_cmd.add_flag("--dry-run", self.compose_dry_run)
+        base_cmd.add_simple_arg("--parallel", self.compose_parallel)
+        base_cmd.add_simple_arg(
+            "--progress", self.compose_progress if progress is None else progress
+        )
+        return base_cmd
+
+
+class DockerCLICaller:
+    def __init__(self, client_config: ClientConfig) -> None:
+        self.client_config = client_config
+
+    @property
+    def docker_cmd(self) -> Command:
+        return self.client_config.docker_cmd
+
+    @property
+    def docker_compose_cmd(self) -> Command:
+        return self.client_config.docker_compose_cmd
+
+
+class ReloadableObject[InspectResultT, ReferenceT: str | None = str](DockerCLICaller):
+    def __init__(
+        self,
+        client_config: ClientConfig,
+        id_in_inspect: str,
+        reference_or_id: ReferenceT,
+        is_immutable_id: bool = False,
+    ) -> None:
+        super().__init__(client_config)
+        self._last_refreshed_time = datetime.min
+        self._inspect_result: InspectResultT | None = None
+        self._id_in_inspect = id_in_inspect
+        if is_immutable_id:
+            self._immutable_id: ReferenceT = reference_or_id
+        else:
+            inspect_result = self._fetch_and_parse_inspect_result(reference_or_id)
+            self._set_inspect_result(inspect_result)
+            self._immutable_id = getattr(inspect_result, id_in_inspect)
+
+    @override
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, ReloadableObject):
+            return False
+        return (
+            self._get_immutable_id() == other._get_immutable_id()
+            and self.client_config == other.client_config
+        )
+
+    @override
+    def __str__(self) -> str:
+        reference = self._get_immutable_id()
+        if reference is None:
+            raise TypeError("__str__ returned non-string (type NoneType)")
+        return reference
+
+    def _needs_reload(self) -> bool:
+        return (datetime.now() - self._last_refreshed_time) >= timedelta(
+            seconds=CACHE_VALIDITY_PERIOD
+        )
+
+    def reload(self) -> None:
+        self._reload()
+
+    def _reload(self) -> InspectResultT:
+        inspect_result = self._fetch_and_parse_inspect_result(self._immutable_id)
+        self._set_inspect_result(inspect_result)
+        return inspect_result
+
+    def _fetch_and_parse_inspect_result(self, reference: ReferenceT) -> InspectResultT:
+        raise NotImplementedError
+
+    def _get_inspect_result(self) -> InspectResultT:
+        if self._inspect_result is None or self._needs_reload():
+            return self._reload()
+        return self._inspect_result
+
+    def _set_inspect_result(self, inspect_result: InspectResultT) -> None:
+        self._inspect_result = inspect_result
+        self._last_refreshed_time = datetime.now()
+
+    def _get_immutable_id(self) -> ReferenceT:
+        return self._immutable_id
+
+    @override
+    def __hash__(self) -> int:
+        # maybe we can do better.
+        return hash(self._get_immutable_id())
+
+
+class ReloadableObjectFromJson[InspectResultT, ReferenceT: str | None = str](
+    ReloadableObject[InspectResultT, ReferenceT]
+):
+    def _fetch_inspect_result_json(self, reference: ReferenceT) -> dict[str, Any]:
+        raise NotImplementedError
+
+    def _parse_json_object(self, json_object: dict[str, Any]) -> InspectResultT:
+        raise NotImplementedError
+
+    @override
+    def _fetch_and_parse_inspect_result(self, reference: ReferenceT) -> InspectResultT:
+        json_object = self._fetch_inspect_result_json(reference)
+        return self._parse_inspect_result(json_object)
+
+    def _parse_inspect_results(
+        self, json_str: str, references: Sequence[str]
+    ) -> list[InspectResultT]:
+        try:
+            json_objects = pydantic.TypeAdapter(
+                list[dict[str, pydantic.JsonValue]]
+            ).validate_json(json_str)
+        except pydantic.ValidationError as err:
+            raise ParsingError("Invalid batch inspect JSON response") from err
+        if len(json_objects) != len(references):
+            raise ParsingError(
+                f"Expected {len(references)} inspect results, received {len(json_objects)}"
+            )
+        results = [self._parse_inspect_result(item) for item in json_objects]
+        resolved: dict[str, str] = {}
+        for reference, result in zip(references, results, strict=True):
+            identity = getattr(result, self._id_in_inspect)
+            if not isinstance(identity, str) or not identity:
+                raise ParsingError(f"Missing inspect identity for {reference!r}")
+            if reference in resolved and resolved[reference] != identity:
+                raise ParsingError(f"Inconsistent inspect identity for {reference!r}")
+            resolved[reference] = identity
+        return results
+
+    def _parse_inspect_result(self, json_object: dict[str, Any]) -> InspectResultT:
+        try:
+            return self._parse_json_object(json_object)
+        except pydantic.ValidationError as err:
+            fd, json_response_file = tempfile.mkstemp(suffix=".json", text=True)
+            with os.fdopen(fd, "w") as f:
+                json.dump(json_object, f, indent=2)
+
+            raise ParsingError(
+                f"There was an error parsing the json response from the Docker daemon. \n"
+                f"This is a bug with pywhales itself. Please head to \n"
+                f"https://github.com/MaraClaw/PyWhales/issues \n"
+                f"and open an issue. You should copy this error message and \n"
+                f"the json response from the Docker daemon. The json response was put \n"
+                f"in {json_response_file} because it's a bit too big to be printed \n"
+                f"on the screen. Make sure that there are no sensitive data in the \n"
+                f"json file before copying it in the github issue."
+            ) from err
+
+
+def bulk_reload[InspectResultT, ReferenceT: str | None](
+    docker_objects: Sequence[ReloadableObjectFromJson[InspectResultT, ReferenceT]],
+) -> None:
+    assert len({x.client_config for x in docker_objects}) == 1
+    all_ids = [x._get_immutable_id() for x in docker_objects]
+    full_cmd = [*docker_objects[0].docker_cmd, "inspect", *all_ids]
+    json_str = run(full_cmd)
+    for json_obj, docker_object in zip(
+        json.loads(json_str), docker_objects, strict=False
+    ):
+        docker_object._set_inspect_result(docker_object._parse_json_object(json_obj))

pywhales/command_line_entrypoint.py

@@ -0,0 +1,8 @@
+def main() -> None:
+    print(
+        "The PyWhales command line interface does not perform any action. "
+        "If you were using it to download the docker CLI, "
+        "you should instead do it manually. "
+        "Take a look at https://github.com/MaraClaw/PyWhales/blob/HEAD/docs/template/docker_client.md#the-docker-cli "
+        "which has instructions to download the Docker client."
+    )

pywhales/components/_swarm_inspect.py

@@ -0,0 +1,78 @@
+from collections import Counter
+from collections.abc import Sequence
+from typing import assert_never
+
+from pywhales.client_config import ParsingError, ReloadableObjectFromJson
+from pywhales.components.config.models import ConfigInspectResult
+from pywhales.components.node.models import NodeInspectResult
+from pywhales.components.secret.models import SecretInspectResult
+from pywhales.components.service.models import ServiceInspectResult
+
+type SwarmInspectResult = (
+    ConfigInspectResult | NodeInspectResult | SecretInspectResult | ServiceInspectResult
+)
+
+
+def _inspect_name(result: SwarmInspectResult) -> str | None:
+    match result:
+        case NodeInspectResult(description=description):
+            return description.hostname if description is not None else None
+        case (
+            ConfigInspectResult(spec=spec)
+            | SecretInspectResult(spec=spec)
+            | ServiceInspectResult(spec=spec)
+        ):
+            return spec.name if spec is not None else None
+        case unreachable:
+            assert_never(unreachable)
+
+
+def parse_swarm_inspect_results[InspectResultT: SwarmInspectResult](
+    parser: ReloadableObjectFromJson[InspectResultT],
+    json_str: str,
+    references: Sequence[str],
+) -> list[tuple[str, InspectResultT]]:
+    """Validate response slots, then resolve references independently of their order.
+
+    Unique slot labels keep the shared parser's positional duplicate check from
+    associating repeated request references with unrelated reordered responses.
+    Identity consistency and multiplicity are checked after reference resolution.
+    """
+    results = parser._parse_inspect_results(
+        json_str, [str(index) for index in range(len(references))]
+    )
+    snapshots: dict[str, InspectResultT] = {}
+    identities: list[str] = []
+    for result in results:
+        identity = result.id
+        if identity is None or identity == "":
+            raise ParsingError("Missing Swarm inspect identity")
+        if identity in snapshots and snapshots[identity] != result:
+            raise ParsingError(f"Inconsistent inspect snapshot for {identity!r}")
+        snapshots[identity] = result
+        identities.append(identity)
+
+    resolved: list[tuple[str, InspectResultT]] = []
+    for reference in references:
+        if reference in snapshots:
+            resolved.append((reference, snapshots[reference]))
+            continue
+        matches = [
+            (identity, result)
+            for identity, result in snapshots.items()
+            if reference and _inspect_name(result) == reference
+        ]
+        if not matches:
+            matches = [
+                (identity, result)
+                for identity, result in snapshots.items()
+                if reference and identity.startswith(reference)
+            ]
+        if len(matches) != 1:
+            raise ParsingError(
+                f"Expected one inspect identity for {reference!r}, received {len(matches)}"
+            )
+        resolved.append(matches[0])
+    if Counter(identity for identity, _ in resolved) != Counter(identities):
+        raise ParsingError("Inspect identities do not match requested multiplicities")
+    return resolved