everypixel-cli 0.1.0__py3-none-any.whl

everypixel_cli/client.py

@@ -0,0 +1,159 @@
+"""Everypixel API HTTP transport.
+
+The client stores connection settings, reuses one httpx connection pool, and
+normalizes remote failures into typed application errors.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+from .errors import (
+    APIRequestError,
+    APIResponseError,
+    AuthenticationError,
+    http_exit_code,
+)
+
+
+class APIClient:
+    """Thin HTTP API wrapper with Basic Auth and normalized errors."""
+
+    def __init__(
+        self,
+        *,
+        base_url: str,
+        client_id: str | None,
+        client_secret: str | None,
+        timeout: float = 30.0,
+    ):
+        self.base_url = base_url.rstrip("/")
+        self.client_id = client_id
+        self.client_secret = client_secret
+        self.timeout = timeout
+        self._http = httpx.Client(timeout=timeout, follow_redirects=True)
+
+    @property
+    def auth(self) -> tuple[str, str] | None:
+        """Return a Basic Auth pair or None."""
+
+        if self.client_id and self.client_secret:
+            return self.client_id, self.client_secret
+        return None
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: dict[str, Any] | None = None,
+        params: dict[str, Any] | None = None,
+        files: dict[str, Any] | None = None,
+        auth_required: bool = True,
+    ) -> Any:
+        """Perform an HTTP request and return an arbitrary decoded JSON value."""
+
+        if auth_required and not self.auth:
+            raise AuthenticationError(
+                "Credentials are not configured", code="auth_missing"
+            )
+        url = self.base_url + (path if path.startswith("/") else f"/{path}")
+        try:
+            response = self._http.request(
+                method,
+                url,
+                json=json,
+                params=drop_none(params),
+                files=files,
+                auth=self.auth,
+            )
+        except httpx.TimeoutException as exc:
+            raise APIRequestError("API request timed out", code="api_timeout") from exc
+        except httpx.RequestError as exc:
+            raise APIRequestError(
+                "Unable to connect to API", code="network_error"
+            ) from exc
+        if response.status_code >= 400:
+            detail = extract_error_detail(response)
+            exit_code, code = http_exit_code(response.status_code, detail)
+            error_type = (
+                AuthenticationError
+                if response.status_code in (401, 403)
+                else APIRequestError
+            )
+            raise error_type(
+                "API request failed",
+                code=code,
+                exit_code=exit_code,
+                details={
+                    "status_code": response.status_code,
+                    "api_message": detail[:500],
+                },
+            )
+        if not response.content:
+            return {}
+        try:
+            return response.json()
+        except ValueError as exc:
+            raise APIResponseError("API returned invalid JSON response") from exc
+
+    def get_status(self, task_id: str) -> Any:
+        """Fetch async task state by task_id."""
+
+        return self.request(
+            "GET",
+            "/v1/status",
+            params={"task_id": task_id},
+            auth_required=False,
+        )
+
+    def check_auth(self) -> None:
+        """Check that Basic Auth is accepted by the API."""
+
+        if not self.auth:
+            raise AuthenticationError(
+                "Credentials are not configured", code="auth_missing"
+            )
+        self.request("GET", "/v1/auth/check")
+
+    def close(self) -> None:
+        """Close the shared HTTP connection pool."""
+
+        self._http.close()
+
+    def __enter__(self) -> "APIClient":
+        return self
+
+    def __exit__(self, *_exc_info: Any) -> None:
+        self.close()
+
+
+def drop_none(data: dict[str, Any] | None) -> dict[str, Any] | None:
+    """Drop None values from query params."""
+
+    if data is None:
+        return None
+    return {key: value for key, value in data.items() if value is not None}
+
+
+def extract_error_detail(response: httpx.Response) -> str:
+    """Extract a human-readable error from an API response."""
+
+    try:
+        data = response.json()
+    except ValueError:
+        return response.text
+    detail = data.get("detail") or data.get("message") or data.get("error") or data
+    return format_error_detail(detail)
+
+
+def format_error_detail(detail: Any) -> str:
+    """Normalize different API error shapes into one string."""
+
+    if isinstance(detail, list):
+        return "; ".join(format_error_detail(item) for item in detail)
+    if isinstance(detail, dict):
+        return str(detail.get("message") or detail.get("msg") or detail)
+    return str(detail)

everypixel_cli/config.py

@@ -0,0 +1,221 @@
+"""Local CLI configuration and credential storage.
+
+The module keeps public client_id values in the JSON profile config and stores
+client_secret in the system keyring when possible. If keyring is unavailable,
+config.json is used as a fallback so the CLI still works in minimal setups.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from contextlib import suppress
+from pathlib import Path
+from typing import Any
+
+import keyring
+from platformdirs import user_config_dir
+from pydantic import BaseModel, Field, HttpUrl
+
+from .errors import ConfigurationError, FileWriteError, ValidationCLIError, mask_secret
+
+
+DEFAULT_BASE_URL = "https://api.everypixel.com"
+SERVICE_NAME = "everypixel-cli"
+
+
+class ProfileConfig(BaseModel):
+    """Settings for one Everypixel API profile."""
+
+    base_url: str = DEFAULT_BASE_URL
+    client_id: str | None = None
+    client_secret: str | None = None
+
+
+class AppConfig(BaseModel):
+    """Full local CLI configuration."""
+
+    current_profile: str = "default"
+    profiles: dict[str, ProfileConfig] = Field(
+        default_factory=lambda: {"default": ProfileConfig()}
+    )
+
+
+def config_dir() -> Path:
+    """Return the user config directory."""
+
+    return Path(user_config_dir("everypixel-cli", "Everypixel"))
+
+
+def config_path() -> Path:
+    """Return the config.json path."""
+
+    return config_dir() / "config.json"
+
+
+def load_config() -> AppConfig:
+    """Read config.json or return defaults."""
+
+    path = config_path()
+    if not path.exists():
+        return AppConfig()
+    try:
+        return AppConfig.model_validate_json(path.read_text(encoding="utf-8"))
+    except (OSError, ValueError) as exc:
+        raise ConfigurationError(
+            "Unable to read configuration",
+            code="config_read_error",
+            details={"path": str(path)},
+        ) from exc
+
+
+def save_config(config: AppConfig) -> None:
+    """Save config and try to restrict file permissions."""
+
+    path = config_path()
+    try:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(
+            json.dumps(config.model_dump(), indent=2, ensure_ascii=False),
+            encoding="utf-8",
+        )
+        with suppress(OSError):
+            path.chmod(0o600)
+    except OSError as exc:
+        raise FileWriteError(
+            "Unable to write configuration", details={"path": str(path)}
+        ) from exc
+
+
+def resolve_profile_name(
+    config: AppConfig,
+    profile: str | None = None,
+    dev: bool = False,
+) -> str:
+    """Resolve the active profile name."""
+
+    env_profile = os.getenv("EVERYPIXEL_PROFILE")
+    if dev:
+        return "dev"
+    return profile or env_profile or config.current_profile
+
+
+def get_or_create_profile(config: AppConfig, name: str) -> ProfileConfig:
+    """Return an existing profile or create it."""
+
+    if name not in config.profiles:
+        config.profiles[name] = ProfileConfig()
+    return config.profiles[name]
+
+
+def keyring_name(profile: str) -> str:
+    """Build a keyring service name for a profile."""
+
+    return f"{SERVICE_NAME}:{profile}"
+
+
+def save_credentials(profile: str, client_id: str, client_secret: str) -> bool:
+    """Save profile credentials.
+
+    Returns True when the secret was stored in keyring. False means the secret
+    was stored in config.json as a fallback.
+    """
+
+    config = load_config()
+    profile_config = get_or_create_profile(config, profile)
+    profile_config.client_id = client_id
+    profile_config.client_secret = None
+    try:
+        keyring.set_password(keyring_name(profile), client_id, client_secret)
+        keyring_ok = True
+    except Exception:  # noqa: BLE001
+        profile_config.client_secret = client_secret
+        keyring_ok = False
+    save_config(config)
+    return keyring_ok
+
+
+def delete_credentials(profile: str) -> None:
+    """Delete profile client_id/client_secret from config and keyring."""
+
+    config = load_config()
+    profile_config = get_or_create_profile(config, profile)
+    client_id = profile_config.client_id
+    if client_id:
+        # Keyring backends differ in how they report an already-missing entry.
+        with suppress(Exception):
+            keyring.delete_password(keyring_name(profile), client_id)
+    profile_config.client_id = None
+    profile_config.client_secret = None
+    save_config(config)
+
+
+def resolved_settings(
+    profile: str | None = None,
+    dev: bool = False,
+    base_url: str | None = None,
+) -> dict[str, Any]:
+    """Resolve effective settings for one run.
+
+    Source priority is CLI options, environment variables, then saved profile.
+    The secret comes from env/config or is fetched from keyring.
+    """
+
+    config = load_config()
+    profile_name = resolve_profile_name(config, profile=profile, dev=dev)
+    profile_config = get_or_create_profile(config, profile_name)
+
+    client_id = os.getenv("EVERYPIXEL_CLIENT_ID") or profile_config.client_id
+    client_secret = (
+        os.getenv("EVERYPIXEL_CLIENT_SECRET") or profile_config.client_secret
+    )
+    if client_id and not client_secret:
+        try:
+            client_secret = keyring.get_password(keyring_name(profile_name), client_id)
+        except Exception:
+            client_secret = None
+
+    return {
+        "profile": profile_name,
+        "base_url": (
+            base_url or os.getenv("EVERYPIXEL_BASE_URL") or profile_config.base_url
+        ),
+        "client_id": client_id,
+        "client_secret": client_secret,
+    }
+
+
+def set_config_value(profile: str, key: str, value: str) -> None:
+    """Set a supported profile option."""
+
+    config = load_config()
+    profile_config = get_or_create_profile(config, profile)
+    if key != "base_url":
+        raise ValidationCLIError("Unsupported configuration key", details={"key": key})
+    profile_config.base_url = str(HttpUrl(value))
+    save_config(config)
+
+
+def use_profile(profile: str) -> None:
+    """Make a profile active."""
+
+    config = load_config()
+    get_or_create_profile(config, profile)
+    config.current_profile = profile
+    save_config(config)
+
+
+def safe_config_payload(config: AppConfig) -> dict[str, Any]:
+    """Return config data without exposing secrets."""
+
+    return {
+        "current_profile": config.current_profile,
+        "profiles": {
+            name: {
+                "base_url": profile.base_url,
+                "client_id": profile.client_id,
+                "client_secret": mask_secret(profile.client_secret),
+            }
+            for name, profile in config.profiles.items()
+        },
+    }

everypixel_cli/errors.py

@@ -0,0 +1,262 @@
+"""Application error model and stable CLI exit codes."""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from pydantic import ValidationError
+
+
+EXIT_GENERAL = 1
+EXIT_VALIDATION = 2
+EXIT_AUTH = 3
+EXIT_API = 4
+EXIT_FILE = 5
+EXIT_RESULT = 6
+
+# Backwards-compatible names used by the existing public Python API.
+EXIT_RATE_LIMIT = EXIT_API
+EXIT_NOT_FOUND = EXIT_API
+EXIT_BILLING = EXIT_API
+EXIT_TIMEOUT = EXIT_API
+EXIT_API_VALIDATION = EXIT_API
+EXIT_TASK_FAILURE = EXIT_API
+
+
+class EverypixelCLIError(Exception):
+    """Base error rendered consistently by the CLI boundary."""
+
+    code = "cli_error"
+    exit_code = EXIT_GENERAL
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        code: str | None = None,
+        exit_code: int | None = None,
+        details: dict[str, Any] | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.code = code or self.code
+        self.exit_code = exit_code if exit_code is not None else self.exit_code
+        self.details = safe_details(details or {})
+
+    def to_payload(self) -> dict[str, Any]:
+        """Return the stable JSON error contract."""
+
+        return {
+            "ok": False,
+            "error": {
+                "type": type(self).__name__,
+                "code": self.code,
+                "message": self.message,
+                "details": self.details,
+            },
+        }
+
+
+# CLIError remains an alias so third-party callers and existing tests keep working.
+CLIError = EverypixelCLIError
+
+
+class ConfigurationError(EverypixelCLIError):
+    code = "configuration_error"
+    exit_code = EXIT_AUTH
+
+
+class AuthenticationError(EverypixelCLIError):
+    code = "authentication_error"
+    exit_code = EXIT_AUTH
+
+
+class ValidationCLIError(EverypixelCLIError):
+    code = "validation_error"
+    exit_code = EXIT_VALIDATION
+
+
+class InputParsingError(ValidationCLIError):
+    code = "input_parsing_error"
+
+
+class FileReadError(EverypixelCLIError):
+    code = "file_read_error"
+    exit_code = EXIT_FILE
+
+
+class FileWriteError(EverypixelCLIError):
+    code = "file_write_error"
+    exit_code = EXIT_FILE
+
+
+class PayloadPreparationError(ValidationCLIError):
+    code = "payload_preparation_error"
+
+
+class APIRequestError(EverypixelCLIError):
+    code = "api_request_error"
+    exit_code = EXIT_API
+
+
+class APIResponseError(EverypixelCLIError):
+    code = "api_response_error"
+    exit_code = EXIT_API
+
+
+class TaskPollingError(APIRequestError):
+    code = "task_polling_error"
+
+
+class TaskFailedError(EverypixelCLIError):
+    """A task reached the API-level FAILURE terminal state."""
+
+    code = "task_failed"
+    exit_code = EXIT_API
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        task_id: str,
+        status: str = "FAILURE",
+        details: dict[str, Any] | None = None,
+    ) -> None:
+        self.task_id = task_id
+        self.status = status
+        super().__init__(
+            message, details={"task_id": task_id, "status": status, **(details or {})}
+        )
+
+    def to_payload(self) -> dict[str, Any]:
+        """Include task state alongside the shared error contract."""
+
+        payload = super().to_payload()
+        payload["task"] = {"id": self.task_id, "status": self.status}
+        return payload
+
+
+class DownloadError(FileWriteError):
+    code = "download_error"
+
+
+class JqExpressionError(EverypixelCLIError):
+    code = "jq_expression_error"
+    exit_code = EXIT_RESULT
+
+
+class SerializationError(EverypixelCLIError):
+    code = "serialization_error"
+    exit_code = EXIT_RESULT
+
+
+class UnsupportedResultError(EverypixelCLIError):
+    code = "unsupported_result_error"
+    exit_code = EXIT_RESULT
+
+
+class InternalCLIError(EverypixelCLIError):
+    code = "internal_error"
+    exit_code = EXIT_GENERAL
+
+
+def safe_details(value: dict[str, Any]) -> dict[str, Any]:
+    """Make details JSON-safe and remove credential-like keys."""
+
+    sensitive = {
+        "authorization",
+        "client_secret",
+        "api_key",
+        "secret",
+        "token",
+        "password",
+    }
+
+    def sanitize(item: Any, key: str | None = None) -> Any:
+        if key and key.lower().replace("-", "_") in sensitive:
+            return "***"
+        if isinstance(item, dict):
+            return {str(name): sanitize(raw, str(name)) for name, raw in item.items()}
+        if isinstance(item, (list, tuple)):
+            return [sanitize(raw) for raw in item]
+        if isinstance(item, str) and item.startswith(("http://", "https://")):
+            return item.split("?", 1)[0]
+        if isinstance(item, (str, int, float, bool)) or item is None:
+            return item
+        return str(item)
+
+    return sanitize(value)
+
+
+def fallback_serialization_error() -> SerializationError:
+    """Return the only error safe to emit when JSON serialization itself fails."""
+
+    return SerializationError("Unable to serialize CLI response")
+
+
+def serialize_error(error: EverypixelCLIError) -> str:
+    """Serialize an error without allowing JSON failures to leak a traceback."""
+
+    try:
+        return json.dumps(error.to_payload(), ensure_ascii=False)
+    except (TypeError, ValueError):
+        return json.dumps(fallback_serialization_error().to_payload())
+
+
+def http_exit_code(status_code: int, detail: str = "") -> tuple[int, str]:
+    """Map API status codes to stable remote-service categories."""
+
+    normalized = detail.lower()
+    if status_code in (401, 403):
+        return EXIT_AUTH, "auth_error"
+    if status_code == 404:
+        return EXIT_API, "not_found"
+    if status_code == 429:
+        return EXIT_API, "rate_limit"
+    if "billing" in normalized or "quota" in normalized or "limit" in normalized:
+        return EXIT_API, "billing_or_limit_error"
+    if status_code in (400, 422):
+        return EXIT_API, "api_validation_error"
+    return EXIT_API, "api_error"
+
+
+def mask_secret(value: str | None, visible: int = 4) -> str | None:
+    """Mask a secret for safe console output."""
+
+    if value is None:
+        return None
+    if len(value) <= visible:
+        return "*" * len(value)
+    return f"{value[:visible]}{'*' * 8}"
+
+
+def format_validation_errors(errors: list[Any]) -> str:
+    """Format Pydantic validation errors for users."""
+
+    messages: list[str] = []
+    for item in errors:
+        location = ".".join(
+            str(part) for part in item.get("loc", ()) if part != "__root__"
+        )
+        message = str(item.get("msg", "Invalid value"))
+        if message.startswith("Value error, "):
+            message = message.removeprefix("Value error, ")
+        messages.append(f"{location}: {message}" if location else message)
+    return "; ".join(messages)
+
+
+def normalize_exception(exc: Exception) -> EverypixelCLIError:
+    """Convert expected technical exceptions into stable application errors."""
+
+    if isinstance(exc, EverypixelCLIError):
+        return exc
+    if isinstance(exc, ValidationError):
+        return ValidationCLIError(format_validation_errors(exc.errors()))
+    if isinstance(exc, json.JSONDecodeError):
+        return InputParsingError("Unable to parse JSON input")
+    if isinstance(exc, (FileNotFoundError, PermissionError, OSError)):
+        return FileReadError("Unable to access local file")
+    if isinstance(exc, ValueError):
+        return PayloadPreparationError("Unable to prepare request payload")
+    return InternalCLIError("Unexpected internal error")