dinahosting-cli 0.1.0__py3-none-any.whl

dinacli/__init__.py

@@ -0,0 +1,27 @@
+"""Python client for the Dinahosting API."""
+
+from .bootstrap import DinaClient
+from .commands import COMMANDS
+from .models import (
+    CommandSpec,
+    DinaApiError,
+    DinaConfigurationError,
+    DinaConnectionError,
+    DinaError,
+    DinaProtocolError,
+    DinaResponse,
+)
+from .settings import DEFAULT_ENDPOINT
+
+__all__ = [
+    "COMMANDS",
+    "DEFAULT_ENDPOINT",
+    "CommandSpec",
+    "DinaApiError",
+    "DinaClient",
+    "DinaConfigurationError",
+    "DinaConnectionError",
+    "DinaError",
+    "DinaProtocolError",
+    "DinaResponse",
+]

dinacli/api.py

@@ -0,0 +1,119 @@
+"""Hierarchical access to the documented Dinahosting commands."""
+
+from __future__ import annotations
+
+import re
+from keyword import iskeyword
+from typing import Any
+
+from .commands import COMMANDS
+from .models import CommandExecutor, CommandSpec, DinaResponse
+
+_WORD_BOUNDARY = re.compile(r"(?<=[a-z0-9])(?=[A-Z])|(?<=[A-Z])(?=[A-Z][a-z])")
+
+
+def _python_name(name: str) -> str:
+    """Convert an API command segment into a Python attribute name."""
+    python_name = _WORD_BOUNDARY.sub("_", name).lower()
+    return f"{python_name}_" if iskeyword(python_name) else python_name
+
+
+def _path(name: str) -> tuple[str, ...]:
+    """Return the Python namespace path for an API command name."""
+    return tuple(_python_name(segment) for segment in name.split("_"))
+
+
+class Command:
+    """A callable documented Dinahosting command."""
+
+    def __init__(self, executor: CommandExecutor, spec: CommandSpec) -> None:
+        self._executor = executor
+        self._spec = spec
+
+    @property
+    def name(self) -> str:
+        """Return the API command name sent to Dinahosting."""
+        return self._spec.name
+
+    @property
+    def required(self) -> frozenset[str]:
+        """Return documented required parameters."""
+        return self._spec.required
+
+    @property
+    def optional(self) -> frozenset[str]:
+        """Return documented optional parameters."""
+        return self._spec.optional
+
+    def __getattr__(self, name: str) -> Any:
+        """Resolve commands nested below this callable command."""
+        return getattr(CommandGroup(self._executor, _path(self.name)), name)
+
+    def __dir__(self) -> list[str]:
+        """Expose both command attributes and nested documented commands."""
+        group = CommandGroup(self._executor, _path(self.name))
+        return sorted(set(object.__dir__(self)) | set(dir(group)))
+
+    def __call__(self, **parameters: Any) -> DinaResponse:
+        """Validate documented parameters and execute the command."""
+        unknown = parameters.keys() - self._spec.parameters - {"simulate"}
+        if unknown:
+            raise TypeError(
+                f"{self.name} does not accept: {', '.join(sorted(unknown))}"
+            )
+        missing = self._spec.required - parameters.keys()
+        if missing:
+            raise TypeError(f"{self.name} requires: {', '.join(sorted(missing))}")
+        request_parameters = dict(parameters)
+        if "simulate" in request_parameters:
+            request_parameters["SIMULATE"] = request_parameters.pop("simulate")
+        return self._executor.call(self.name, **request_parameters)
+
+
+class CommandGroup:
+    """A namespace that lazily resolves documented commands and subcommands."""
+
+    def __init__(self, executor: CommandExecutor, prefix: tuple[str, ...]) -> None:
+        self._executor = executor
+        self._prefix = prefix
+
+    def __getattr__(self, name: str) -> Any:
+        prefix = (*self._prefix, name)
+        matches = [
+            spec
+            for spec in COMMANDS.values()
+            if _path(spec.name)[: len(prefix)] == prefix
+        ]
+        if not matches:
+            raise AttributeError(name)
+        command = next((spec for spec in matches if _path(spec.name) == prefix), None)
+        if command is not None:
+            return Command(self._executor, command)
+        return CommandGroup(self._executor, prefix)
+
+    def __dir__(self) -> list[str]:
+        """Expose available child commands to interactive Python tooling."""
+        position = len(self._prefix)
+        return sorted(
+            {
+                _path(spec.name)[position]
+                for spec in COMMANDS.values()
+                if _path(spec.name)[:position] == self._prefix
+                and len(_path(spec.name)) > position
+            }
+        )
+
+
+class Api(CommandGroup):
+    """Root namespace for every command in the supplied documentation."""
+
+    def __init__(self, executor: CommandExecutor) -> None:
+        super().__init__(executor, ())
+
+    def __getitem__(self, name: str) -> Command:
+        """Return a command by its exact documented API name."""
+        return Command(self._executor, COMMANDS[name])
+
+    def names(self) -> tuple[str, ...]:
+        """Return every documented API command name."""
+        return tuple(COMMANDS)

dinacli/bootstrap.py

@@ -0,0 +1,48 @@
+"""Public composition root for the default Dinahosting client."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from pathlib import Path
+from typing import Self
+
+from .client import ApiClient
+from .configuration import settings_from_config, settings_from_environment
+from .settings import DEFAULT_ENDPOINT, ClientSettings
+from .transport import HttpTransport
+
+
+class DinaClient(ApiClient):
+    """Create an API client with the default HTTP transport."""
+
+    def __init__(
+        self,
+        user: str,
+        password: str,
+        *,
+        endpoint: str = DEFAULT_ENDPOINT,
+        timeout: float = 20.0,
+    ) -> None:
+        settings = ClientSettings(user, password, endpoint, timeout)
+        super().__init__(settings, HttpTransport(settings.endpoint, settings.timeout))
+
+    @classmethod
+    def from_environment(cls, environ: Mapping[str, str] | None = None) -> Self:
+        """Build a client from DINA_USER and DINA_PASSWORD environment variables."""
+        return cls._from_settings(settings_from_environment(environ))
+
+    @classmethod
+    def from_config(
+        cls, path: str | Path, environ: Mapping[str, str] | None = None
+    ) -> Self:
+        """Build a client from a TOML file, overridden by DINA_* variables."""
+        return cls._from_settings(settings_from_config(path, environ))
+
+    @classmethod
+    def _from_settings(cls, settings: ClientSettings) -> Self:
+        return cls(
+            settings.user,
+            settings.password,
+            endpoint=settings.endpoint,
+            timeout=settings.timeout,
+        )

dinacli/cli.py

@@ -0,0 +1,174 @@
+"""Command-line interface for the Dinahosting API client."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+from collections.abc import Callable, Sequence
+from importlib.metadata import version
+from math import isfinite
+from typing import Any, NoReturn, TextIO
+
+from .bootstrap import DinaClient
+from .commands import COMMANDS
+from .models import CommandSpec, DinaError, DinaResponse
+
+
+def main(arguments: Sequence[str] | None = None) -> int:
+    """Run the dinacli command-line interface."""
+    parser = _parser()
+    namespace = parser.parse_args(arguments)
+    try:
+        handler: Callable[[argparse.Namespace], int] = namespace.handler
+        return handler(namespace)
+    except (DinaError, TypeError, ValueError) as error:
+        if namespace.output == "json":
+            _write_json({"error": str(error)}, sys.stderr)
+        else:
+            print(f"error: {error}", file=sys.stderr)
+        return 1
+
+
+def _parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        description="Execute documented Dinahosting API commands."
+    )
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=f"%(prog)s {version('dinahosting-cli')}",
+    )
+    parser.add_argument("--config", help="TOML file with a [dina] section")
+    parser.add_argument("--user", help="Dinahosting API user")
+    parser.add_argument("--password", help="Dinahosting API password")
+    parser.add_argument("--endpoint", help="API endpoint URL")
+    parser.add_argument("--timeout", help="Request timeout in seconds")
+    parser.add_argument(
+        "--output",
+        choices=("json",),
+        help="Emit output as JSON, including errors on stderr",
+    )
+    actions = parser.add_subparsers(dest="action", required=True)
+
+    commands = actions.add_parser("commands", help="List documented API commands")
+    commands.set_defaults(handler=_list_commands)
+
+    describe = actions.add_parser("describe", help="Show a command's parameters")
+    describe.add_argument("command", help="Exact documented API command name")
+    describe.set_defaults(handler=_describe_command)
+
+    call = actions.add_parser("call", help="Execute a documented API command")
+    call.add_argument("command", help="Exact documented API command name")
+    call.add_argument(
+        "--param",
+        action="append",
+        default=[],
+        metavar="NAME=VALUE",
+        help="Parameter; VALUE is JSON when valid, otherwise text. Repeatable.",
+    )
+    call.add_argument(
+        "--simulate", action="store_true", help="Send the API SIMULATE parameter"
+    )
+    call.set_defaults(handler=_call_command)
+    return parser
+
+
+def _list_commands(arguments: argparse.Namespace) -> int:
+    commands = sorted(COMMANDS)
+    if arguments.output == "json":
+        _write_json(commands)
+    else:
+        print("\n".join(commands))
+    return 0
+
+
+def _describe_command(arguments: argparse.Namespace) -> int:
+    spec = _command_spec(arguments.command)
+    _write_json(
+        {
+            "command": spec.name,
+            "optional": sorted(spec.optional),
+            "required": sorted(spec.required),
+        }
+    )
+    return 0
+
+
+def _call_command(arguments: argparse.Namespace) -> int:
+    spec = _command_spec(arguments.command)
+    parameters = _parameters(arguments.param)
+    if arguments.simulate:
+        parameters["simulate"] = True
+    response = _client(arguments).api[spec.name](**parameters)
+    _write_response(response)
+    return 0
+
+
+def _command_spec(command: str) -> CommandSpec:
+    if command not in COMMANDS:
+        raise ValueError(f"Unknown command: {command}")
+    return COMMANDS[command]
+
+
+def _parameters(values: Sequence[str]) -> dict[str, Any]:
+    parameters: dict[str, Any] = {}
+    for value in values:
+        name, separator, raw_value = value.partition("=")
+        if not separator or not name:
+            raise ValueError("Parameters must use NAME=VALUE")
+        if name in parameters:
+            raise ValueError(f"Parameter specified more than once: {name}")
+        try:
+            parameters[name] = json.loads(
+                raw_value,
+                parse_constant=_invalid_json_constant,
+                parse_float=_finite_json_number,
+            )
+        except json.JSONDecodeError:
+            parameters[name] = raw_value
+    return parameters
+
+
+def _invalid_json_constant(value: str) -> NoReturn:
+    raise json.JSONDecodeError("Invalid JSON constant", value, 0)
+
+
+def _finite_json_number(value: str) -> float:
+    number = float(value)
+    if not isfinite(number):
+        raise json.JSONDecodeError("JSON number is not finite", value, 0)
+    return number
+
+
+def _client(arguments: argparse.Namespace) -> DinaClient:
+    environment = dict(os.environ)
+    for option, variable in (
+        ("user", "DINA_USER"),
+        ("password", "DINA_PASSWORD"),
+        ("endpoint", "DINA_ENDPOINT"),
+        ("timeout", "DINA_TIMEOUT"),
+    ):
+        value = getattr(arguments, option)
+        if value is not None:
+            environment[variable] = value
+    if arguments.config:
+        return DinaClient.from_config(arguments.config, environment)
+    return DinaClient.from_environment(environment)
+
+
+def _write_response(response: DinaResponse) -> None:
+    _write_json(
+        {
+            "code": response.code,
+            "command": response.command,
+            "data": response.data,
+            "message": response.message,
+            "transaction_id": response.transaction_id,
+        }
+    )
+
+
+def _write_json(value: object, stream: TextIO | None = None) -> None:
+    print(json.dumps(value, indent=2, sort_keys=True), file=stream)

dinacli/client.py

@@ -0,0 +1,29 @@
+"""Application service for documented Dinahosting API commands."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from .api import Api
+from .models import DinaResponse, Transport, response_from_payload
+from .settings import ClientSettings
+
+
+class ApiClient:
+    """Execute commands through a supplied transport port."""
+
+    def __init__(self, settings: ClientSettings, transport: Transport) -> None:
+        self._settings = settings
+        self._transport = transport
+        self.api = Api(self)
+
+    def call(self, command: str, /, **parameters: Any) -> DinaResponse:
+        """Call a documented Dinahosting command and return its decoded response."""
+        if not isinstance(command, str) or not command.strip():
+            raise ValueError("Command is required")
+        payload = self._transport.post(
+            {**parameters, "command": command, "responseType": "Json"},
+            self._settings.user,
+            self._settings.password,
+        )
+        return response_from_payload(payload, command)