holocubic-cli-python 0.1.0__py3-none-any.whl

holocubic_cli_python/transport.py

@@ -0,0 +1,99 @@
+"""HTTP transport with stable timeout, connection, and device error handling."""
+
+import json
+import socket
+from dataclasses import dataclass
+from typing import Any, Mapping
+from urllib.error import HTTPError, URLError
+from urllib.request import Request, urlopen
+
+from .errors import CubicError, HttpError
+from .url import api_url, normalize_device_url
+
+
+@dataclass(frozen=True)
+class HttpResponse:
+    body: bytes
+    headers: Mapping[str, str]
+
+
+class HttpTransport:
+    def __init__(self, base_url: str, timeout_ms: int = 60_000) -> None:
+        if timeout_ms <= 0:
+            raise CubicError(
+                "Timeout must be greater than zero.", code="INVALID_TIMEOUT"
+            )
+        self.base_url = normalize_device_url(base_url)
+        self.timeout_ms = timeout_ms
+
+    def request(
+        self,
+        route: str,
+        *,
+        method: str = "GET",
+        query: Mapping[str, str | int | bool | None] | None = None,
+        body: bytes | None = None,
+        headers: Mapping[str, str] | None = None,
+    ) -> HttpResponse:
+        url = api_url(self.base_url, route, query)
+        request = Request(
+            url,
+            data=body,
+            method=method,
+            headers={"Accept": "application/json", **(headers or {})},
+        )
+        try:
+            with urlopen(request, timeout=self.timeout_ms / 1000) as response:
+                return HttpResponse(response.read(), dict(response.headers.items()))
+        except HTTPError as error:
+            request_path = url.removeprefix(self.base_url)
+            message = f"{method} {request_path} failed with HTTP {error.code}."
+            try:
+                payload = json.loads(error.read().decode("utf-8"))
+                if isinstance(payload, dict):
+                    detail = (
+                        payload.get("error")
+                        if isinstance(payload.get("error"), str)
+                        else payload.get("message")
+                    )
+                    if isinstance(detail, str):
+                        message = f"{message} {detail}"
+            except (json.JSONDecodeError, UnicodeDecodeError, OSError):
+                pass
+            raise HttpError(message, error.code, method, request_path) from error
+        except (socket.timeout, TimeoutError) as error:
+            raise CubicError(
+                f"Request timed out after {self.timeout_ms} ms.", code="TIMEOUT"
+            ) from error
+        except URLError as error:
+            if isinstance(error.reason, (socket.timeout, TimeoutError)):
+                raise CubicError(
+                    f"Request timed out after {self.timeout_ms} ms.", code="TIMEOUT"
+                ) from error
+            raise CubicError(
+                f"Unable to connect to {self.base_url}.", code="CONNECTION_ERROR"
+            ) from error
+        except OSError as error:
+            raise CubicError(
+                f"Unable to connect to {self.base_url}.", code="CONNECTION_ERROR"
+            ) from error
+
+    def json(
+        self,
+        route: str,
+        *,
+        method: str = "GET",
+        query: Mapping[str, str | int | bool | None] | None = None,
+        body: bytes | None = None,
+        headers: Mapping[str, str] | None = None,
+    ) -> Any:
+        response = self.request(
+            route, method=method, query=query, body=body, headers=headers
+        )
+        try:
+            return json.loads(response.body.decode("utf-8"))
+        except (json.JSONDecodeError, UnicodeDecodeError) as error:
+            raise CubicError(
+                f"Device returned malformed JSON for /api/{route}.",
+                code="INVALID_RESPONSE",
+            ) from error

holocubic_cli_python/url.py

@@ -0,0 +1,52 @@
+from collections.abc import Mapping
+from urllib.parse import SplitResult, urlencode, urlsplit, urlunsplit
+
+from .errors import UsageError
+
+
+def normalize_device_url(value: str) -> str:
+    trimmed = value.strip()
+    if not trimmed:
+        raise UsageError("Device host cannot be empty.")
+    if "\0" in trimmed:
+        raise UsageError("Device host contains an invalid NUL character.")
+
+    candidate = trimmed if "://" in trimmed else f"http://{trimmed}"
+    try:
+        parsed = urlsplit(candidate)
+        _ = parsed.port
+    except ValueError as error:
+        raise UsageError(f"Invalid device host: {value}") from error
+
+    if parsed.scheme not in {"http", "https"}:
+        raise UsageError(f"Unsupported device URL scheme: {parsed.scheme}")
+    if not parsed.hostname:
+        raise UsageError(f"Invalid device host: {value}")
+    if parsed.username is not None or parsed.password is not None:
+        raise UsageError("Credentials are not allowed in the device URL.")
+    if parsed.query or parsed.fragment:
+        raise UsageError("Device URL must not contain a query string or fragment.")
+
+    path = parsed.path.rstrip("/")
+    if path in {"", "/devtools"}:
+        path = "/devtools"
+    elif path == "/devtools/api":
+        path = "/devtools"
+    else:
+        raise UsageError("Device URL path must be /devtools or /devtools/api.")
+
+    normalized = SplitResult(parsed.scheme.lower(), parsed.netloc, path, "", "")
+    return urlunsplit(normalized)
+
+
+def api_url(
+    base_url: str,
+    route: str,
+    query: Mapping[str, str | int | bool | None] | None = None,
+) -> str:
+    clean_route = route.lstrip("/")
+    pairs = [
+        (key, str(value)) for key, value in (query or {}).items() if value is not None
+    ]
+    suffix = f"?{urlencode(pairs)}" if pairs else ""
+    return f"{base_url}/api/{clean_route}{suffix}"

holocubic_cli_python-0.1.0.dist-info/METADATA

@@ -0,0 +1,67 @@
+Metadata-Version: 2.4
+Name: holocubic-cli-python
+Version: 0.1.0
+Summary: Python CLI for HoloCubic DevTools file and app workflows
+Project-URL: Repository, https://github.com/Tim-1e/holocubic-cli
+Project-URL: Issues, https://github.com/Tim-1e/holocubic-cli/issues
+Author: Tim-1e
+License-Expression: MIT
+License-File: LICENSE
+Keywords: cli,devtools,esp32,holocubic
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# HoloCubic CLI — Python
+
+`cubic-py` is the Python implementation of the shared HoloCubic CLI v1
+contract. It supports the same device configuration, SD-card filesystem,
+recursive transfer, DevRun, and app workflows as the Node.js reference.
+
+The package requires Python 3.10 or newer. It is source-ready but has not been
+published to PyPI yet.
+
+## Installation from source
+
+```sh
+python -m venv .venv
+python -m pip install --editable .
+cubic-py --version
+```
+
+Activate `.venv` first if you want `cubic-py` available only inside the virtual
+environment. Connect and inspect a device with:
+
+```sh
+cubic-py device add desk 192.168.3.26
+cubic-py info
+cubic-py ls /sd/apps
+cubic-py push ./my-app /sd/apps/my-app
+```
+
+## Command overview
+
+```text
+cubic-py device add|list|use|remove
+cubic-py ping|info
+cubic-py ls|stat|cat|mkdir|mv|rm
+cubic-py push|upload
+cubic-py pull|download
+cubic-py devrun read|save|run
+cubic-py app list|install|remove
+```
+
+Use `--host` for one-off access, `--json` for scripts, and `--help` on a command
+for its transfer limits and safety options.
+
+## Development checks
+
+```sh
+python -m ruff check src tests
+python -m ruff format --check src tests
+python -m unittest discover -s tests -v
+python -m build
+python -m pip install .
+cubic-py --version
+```
+
+The API and CLI contracts live in [`../../spec`](../../spec).

holocubic_cli_python-0.1.0.dist-info/RECORD

@@ -0,0 +1,17 @@
+holocubic_cli_python/__init__.py,sha256=YGOTn7f4AkbrZ2E709idr3t4xwiKMQMw4XOqK207x0w,73
+holocubic_cli_python/__main__.py,sha256=k1ocEWawweo1qCJWNFAAvyxz3tcY13dzvCenHszij30,48
+holocubic_cli_python/app.py,sha256=lWoCrVRdyNbGeOopKa5tsSa7h-PgPOZ9vA9tP1XkbcY,2646
+holocubic_cli_python/cli.py,sha256=SrmXu-4oaZ2WKkxPuRs7DlpKFvwblTDxrPXoaKI7aQI,22720
+holocubic_cli_python/client.py,sha256=q-TMvd0cXkppbIPctUGUoajkgpVMUulACYSPRCHiM5Q,13642
+holocubic_cli_python/config.py,sha256=3-9AdyDz7BK5HqxKfFFzSShfSunELwDGDENC5cCiaow,4626
+holocubic_cli_python/errors.py,sha256=9HeW5hINsNTrBr3OJXTf4urGbm33l76q1neJk1gdLaU,864
+holocubic_cli_python/models.py,sha256=-l9M147CSoMqKG-1PZUT7zmzUbr6e34BxCWQA1YKJNM,3682
+holocubic_cli_python/remote_path.py,sha256=vcrWOV0yXlRY6xo82vIoREU5XP-3VLfhrv5-b5wTw5s,2246
+holocubic_cli_python/transfer.py,sha256=jgerCQcN1e2m1S1cqwn5AfAb7NyoyxGKBtxMcyaGAEo,22880
+holocubic_cli_python/transport.py,sha256=-FlmaHnWbEsQxn5xcXm8PNo_gsL_BxiE2bIztDSvLqM,3686
+holocubic_cli_python/url.py,sha256=njCGbEiRhAQckE9FV4sbXlW2pcq3qMGgXV3V4iQVEBM,1841
+holocubic_cli_python-0.1.0.dist-info/METADATA,sha256=Myp6E1o7lbQlAJ8mB7YpmMBaP3w48-pXj6PdRvrobsI,1764
+holocubic_cli_python-0.1.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+holocubic_cli_python-0.1.0.dist-info/entry_points.txt,sha256=F51dwgEYSzV07UIMjK6AwgVua4ogasJkhqbAV3sS8IM,59
+holocubic_cli_python-0.1.0.dist-info/licenses/LICENSE,sha256=XoTz3rF6vKPRejMH_vRunzeQCB2t0nX71o04KgFUnTU,1063
+holocubic_cli_python-0.1.0.dist-info/RECORD,,

holocubic_cli_python-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any

holocubic_cli_python-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+cubic-py = holocubic_cli_python.cli:main

holocubic_cli_python-0.1.0.dist-info/licenses/LICENSE

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