http: api: implement commands

rnovatorov · rnovatorov · commit e8a8d0696209 · 2025-12-04T09:46:47.000+01:00
diff --git a/src/enapter/cli/http/api/command.py b/src/enapter/cli/http/api/command.py
@@ -3,6 +3,7 @@
 from enapter import cli
 
 from .blueprint_command import BlueprintCommand
+from .command_command import CommandCommand
 from .device_command import DeviceCommand
 from .site_command import SiteCommand
 
@@ -17,6 +18,7 @@ def register(parent: cli.Subparsers) -> None:
         subparsers = parser.add_subparsers(dest="api_command", required=True)
         for command in [
             BlueprintCommand,
+            CommandCommand,
             DeviceCommand,
             SiteCommand,
         ]:
@@ -27,6 +29,8 @@ async def run(args: argparse.Namespace) -> None:
         match args.api_command:
             case "blueprint":
                 await BlueprintCommand.run(args)
+            case "command":
+                await CommandCommand.run(args)
             case "device":
                 await DeviceCommand.run(args)
             case "site":
diff --git a/src/enapter/cli/http/api/command_arguments.py b/src/enapter/cli/http/api/command_arguments.py
@@ -0,0 +1,11 @@
+import argparse
+import json
+
+
+def parse_command_arguments(arguments_string: str | None) -> dict:
+    if arguments_string is None:
+        return {}
+    try:
+        return json.loads(arguments_string)
+    except json.JSONDecodeError as e:
+        raise argparse.ArgumentTypeError(f"Decode JSON: {e.msg}")
diff --git a/src/enapter/cli/http/api/command_command.py b/src/enapter/cli/http/api/command_command.py
@@ -0,0 +1,39 @@
+import argparse
+
+from enapter import cli
+
+from .command_create_execution_command import CommandCreateExecutionCommand
+from .command_execute_command import CommandExecuteCommand
+from .command_get_execution_command import CommandGetExecutionCommand
+from .command_list_executions_command import CommandListExecutionsCommand
+
+
+class CommandCommand(cli.Command):
+
+    @staticmethod
+    def register(parent: cli.Subparsers) -> None:
+        parser = parent.add_parser(
+            "command", formatter_class=argparse.ArgumentDefaultsHelpFormatter
+        )
+        subparsers = parser.add_subparsers(dest="command_command", required=True)
+        for command in [
+            CommandCreateExecutionCommand,
+            CommandExecuteCommand,
+            CommandGetExecutionCommand,
+            CommandListExecutionsCommand,
+        ]:
+            command.register(subparsers)
+
+    @staticmethod
+    async def run(args: argparse.Namespace) -> None:
+        match args.command_command:
+            case "create-execution":
+                await CommandCreateExecutionCommand.run(args)
+            case "execute":
+                await CommandExecuteCommand.run(args)
+            case "get-execution":
+                await CommandGetExecutionCommand.run(args)
+            case "list-executions":
+                await CommandListExecutionsCommand.run(args)
+            case _:
+                raise NotImplementedError(args.command_command)
diff --git a/src/enapter/cli/http/api/command_create_execution_command.py b/src/enapter/cli/http/api/command_create_execution_command.py
@@ -0,0 +1,39 @@
+import argparse
+import json
+import logging
+
+from enapter import cli, http
+
+from .command_arguments import parse_command_arguments
+
+LOGGER = logging.getLogger(__name__)
+
+
+class CommandCreateExecutionCommand(cli.Command):
+
+    @staticmethod
+    def register(parent: cli.Subparsers) -> None:
+        parser = parent.add_parser(
+            "create-execution", formatter_class=argparse.ArgumentDefaultsHelpFormatter
+        )
+        parser.add_argument(
+            "-d",
+            "--device-id",
+            required=True,
+            help="ID or slug of the device to execute the command on",
+        )
+        parser.add_argument(
+            "-a",
+            "--arguments",
+            type=parse_command_arguments,
+            help="JSON string of arguments to pass to the command",
+        )
+        parser.add_argument("name", help="Name of the command to execute")
+
+    @staticmethod
+    async def run(args: argparse.Namespace) -> None:
+        async with http.api.Client(http.api.Config.from_env()) as client:
+            execution = await client.commands.create_execution(
+                device_id=args.device_id, name=args.name, arguments=args.arguments
+            )
+            print(json.dumps(execution.to_dto()))
diff --git a/src/enapter/cli/http/api/command_execute_command.py b/src/enapter/cli/http/api/command_execute_command.py
@@ -0,0 +1,48 @@
+import argparse
+import json
+import logging
+
+from enapter import cli, http
+
+from .command_arguments import parse_command_arguments
+
+LOGGER = logging.getLogger(__name__)
+
+
+class CommandExecuteCommand(cli.Command):
+
+    @staticmethod
+    def register(parent: cli.Subparsers) -> None:
+        parser = parent.add_parser(
+            "execute", formatter_class=argparse.ArgumentDefaultsHelpFormatter
+        )
+        parser.add_argument(
+            "-d",
+            "--device-id",
+            required=True,
+            help="ID or slug of the device to execute the command on",
+        )
+        parser.add_argument(
+            "-a",
+            "--arguments",
+            type=parse_command_arguments,
+            help="JSON string of arguments to pass to the command",
+        )
+        parser.add_argument(
+            "-l",
+            "--log",
+            action="store_true",
+            help="Expand command execution log in the output",
+        )
+        parser.add_argument("name", help="Name of the command to execute")
+
+    @staticmethod
+    async def run(args: argparse.Namespace) -> None:
+        async with http.api.Client(http.api.Config.from_env()) as client:
+            execution = await client.commands.execute(
+                device_id=args.device_id,
+                name=args.name,
+                arguments=args.arguments,
+                expand_log=args.log,
+            )
+            print(json.dumps(execution.to_dto()))
diff --git a/src/enapter/cli/http/api/command_get_execution_command.py b/src/enapter/cli/http/api/command_get_execution_command.py
@@ -0,0 +1,41 @@
+import argparse
+import json
+import logging
+
+from enapter import cli, http
+
+LOGGER = logging.getLogger(__name__)
+
+
+class CommandGetExecutionCommand(cli.Command):
+
+    @staticmethod
+    def register(parent: cli.Subparsers) -> None:
+        parser = parent.add_parser(
+            "get-execution", formatter_class=argparse.ArgumentDefaultsHelpFormatter
+        )
+        parser.add_argument(
+            "-d",
+            "--device-id",
+            required=True,
+            help="ID or slug of the device to get the command execution of",
+        )
+        parser.add_argument(
+            "-l",
+            "--log",
+            action="store_true",
+            help="Expand command execution log in the output",
+        )
+        parser.add_argument(
+            "execution_id", help="ID of the command execution to retrieve"
+        )
+
+    @staticmethod
+    async def run(args: argparse.Namespace) -> None:
+        async with http.api.Client(http.api.Config.from_env()) as client:
+            execution = await client.commands.get_execution(
+                device_id=args.device_id,
+                execution_id=args.execution_id,
+                expand_log=args.log,
+            )
+            print(json.dumps(execution.to_dto()))
diff --git a/src/enapter/cli/http/api/command_list_executions_command.py b/src/enapter/cli/http/api/command_list_executions_command.py
@@ -0,0 +1,49 @@
+import argparse
+import json
+
+from enapter import cli, http
+
+
+class CommandListExecutionsCommand(cli.Command):
+
+    @staticmethod
+    def register(parent: cli.Subparsers) -> None:
+        parser = parent.add_parser(
+            "list-executions", formatter_class=argparse.ArgumentDefaultsHelpFormatter
+        )
+        parser.add_argument(
+            "-l",
+            "--limit",
+            type=int,
+            help="Maximum number of command executions to list",
+            default=-1,
+        )
+        parser.add_argument(
+            "-o",
+            "--order",
+            choices=["created_at_asc", "created_at_desc"],
+            help="Order of the listed command executions",
+            default="created_at_asc",
+        )
+        parser.add_argument(
+            "-d",
+            "--device-id",
+            help="ID or slug of the device to list command executions for",
+            required=True,
+        )
+
+    @staticmethod
+    async def run(args: argparse.Namespace) -> None:
+        if args.limit == 0:
+            return
+        async with http.api.Client(http.api.Config.from_env()) as client:
+            async with client.commands.list_executions(
+                device_id=args.device_id,
+                order=http.api.commands.ListExecutionsOrder(args.order.upper()),
+            ) as stream:
+                count = 0
+                async for device in stream:
+                    print(json.dumps(device.to_dto()))
+                    count += 1
+                    if args.limit > 0 and count == args.limit:
+                        break
diff --git a/src/enapter/http/api/__init__.py b/src/enapter/http/api/__init__.py
@@ -2,14 +2,15 @@
 from .config import Config
 from .errors import Error, MultiError, check_error
 
-from . import devices, sites, blueprints  # isort: skip
+from . import devices, sites, commands, blueprints  # isort: skip
 
 __all__ = [
     "Client",
     "Config",
     "devices",
     "blueprints",
     "sites",
+    "commands",
     "Error",
     "MultiError",
     "check_error",
diff --git a/src/enapter/http/api/client.py b/src/enapter/http/api/client.py
@@ -2,7 +2,7 @@
 
 import httpx
 
-from enapter.http.api import blueprints, devices, sites
+from enapter.http.api import blueprints, commands, devices, sites
 
 from .config import Config
 
@@ -38,6 +38,10 @@ def devices(self) -> devices.Client:
     def sites(self) -> sites.Client:
         return sites.Client(client=self._client)
 
+    @property
+    def commands(self) -> commands.Client:
+        return commands.Client(client=self._client)
+
     @property
     def blueprints(self) -> blueprints.Client:
         return blueprints.Client(client=self._client)
diff --git a/src/enapter/http/api/commands/__init__.py b/src/enapter/http/api/commands/__init__.py
@@ -0,0 +1,14 @@
+from .client import Client
+from .execution import Execution, ExecutionState, ListExecutionsOrder
+from .request import Request
+from .response import Response, ResponseState
+
+__all__ = [
+    "Client",
+    "Execution",
+    "ExecutionState",
+    "ListExecutionsOrder",
+    "Request",
+    "Response",
+    "ResponseState",
+]
diff --git a/src/enapter/http/api/commands/client.py b/src/enapter/http/api/commands/client.py
@@ -0,0 +1,79 @@
+from typing import AsyncGenerator
+
+import httpx
+
+from enapter import async_
+from enapter.http import api
+
+from .execution import Execution, ListExecutionsOrder
+
+
+class Client:
+
+    def __init__(self, client: httpx.AsyncClient) -> None:
+        self._client = client
+
+    async def get_execution(
+        self, device_id: str, execution_id: str, expand_log: bool = False
+    ) -> Execution:
+        url = f"v3/devices/{device_id}/command_executions/{execution_id}"
+        expand = {"log": expand_log}
+        expand_string = ",".join(k for k, v in expand.items() if v)
+        response = await self._client.get(url, params={"expand": expand_string})
+        api.check_error(response)
+        return Execution.from_dto(response.json()["execution"])
+
+    @async_.generator
+    async def list_executions(
+        self,
+        device_id: str,
+        order: ListExecutionsOrder = ListExecutionsOrder.CREATED_AT_ASC,
+    ) -> AsyncGenerator[Execution, None]:
+        url = f"v3/devices/{device_id}/command_executions"
+        limit = 50
+        offset = 0
+        while True:
+            response = await self._client.get(
+                url, params={"order": order.value, "limit": limit, "offset": offset}
+            )
+            api.check_error(response)
+            payload = response.json()
+            if not payload["executions"]:
+                return
+            for dto in payload["executions"]:
+                yield Execution.from_dto(dto)
+            offset += limit
+
+    async def execute(
+        self,
+        device_id: str,
+        name: str,
+        arguments: dict | None = None,
+        expand_log: bool = False,
+    ) -> Execution:
+        url = f"v3/devices/{device_id}/execute_command"
+        expand = {"log": expand_log}
+        expand_string = ",".join(k for k, v in expand.items() if v)
+        if arguments is None:
+            arguments = {}
+        response = await self._client.post(
+            url,
+            params={"expand": expand_string},
+            json={"name": name, "arguments": arguments},
+        )
+        api.check_error(response)
+        return Execution.from_dto(response.json()["execution"])
+
+    async def create_execution(
+        self, device_id: str, name: str, arguments: dict | None = None
+    ) -> Execution:
+        url = f"v3/devices/{device_id}/command_executions"
+        if arguments is None:
+            arguments = {}
+        response = await self._client.post(
+            url, json={"name": name, "arguments": arguments}
+        )
+        api.check_error(response)
+        return await self.get_execution(
+            device_id=device_id, execution_id=response.json()["execution_id"]
+        )
diff --git a/src/enapter/http/api/commands/execution.py b/src/enapter/http/api/commands/execution.py
diff --git a/src/enapter/http/api/commands/request.py b/src/enapter/http/api/commands/request.py
diff --git a/src/enapter/http/api/commands/response.py b/src/enapter/http/api/commands/response.py
