intelion-cloud 0.2.0__py3-none-any.whl

intelion_cloud/__init__.py

@@ -0,0 +1,82 @@
+"""Intelion Cloud Python client.
+
+Usage::
+
+    from intelion_cloud import IntelionCloud
+
+    client = IntelionCloud(token="your_api_token")
+    servers = client.cloud_servers.list()
+"""
+
+from ._client import AsyncIntelionCloud, IntelionCloud
+from .constants import BillingPeriod, PricePlan, ServerState
+from .constants import ServerStatus as ServerStatusEnum
+from .exceptions import (
+    APIError,
+    AuthenticationError,
+    ConflictError,
+    ConnectionError,
+    ForbiddenError,
+    IntelionCloudError,
+    NotFoundError,
+    RateLimitError,
+    ServerError,
+    ValidationError,
+)
+from .models import (
+    CPU,
+    GPU,
+    OSImage,
+    RAM,
+    SSD,
+    CloudServer,
+    DebtInfo,
+    Flavor,
+    PhysicalServer,
+    Promocode,
+    ServerStatus,
+    SoftwareAddonInstance,
+    UsageAct,
+    User,
+    WhiteIP,
+)
+
+__version__ = "0.2.0"
+
+__all__ = [
+    # Clients
+    "IntelionCloud",
+    "AsyncIntelionCloud",
+    # Models
+    "CloudServer",
+    "ServerStatus",
+    "Flavor",
+    "User",
+    "GPU",
+    "CPU",
+    "RAM",
+    "SSD",
+    "OSImage",
+    "UsageAct",
+    "DebtInfo",
+    "Promocode",
+    "WhiteIP",
+    "PhysicalServer",
+    "SoftwareAddonInstance",
+    # Constants
+    "ServerStatusEnum",
+    "ServerState",
+    "PricePlan",
+    "BillingPeriod",
+    # Exceptions
+    "IntelionCloudError",
+    "APIError",
+    "AuthenticationError",
+    "ForbiddenError",
+    "NotFoundError",
+    "ConflictError",
+    "RateLimitError",
+    "ValidationError",
+    "ServerError",
+    "ConnectionError",
+]

intelion_cloud/_client.py

@@ -0,0 +1,108 @@
+"""Main client classes: IntelionCloud (sync) and AsyncIntelionCloud (async)."""
+
+from __future__ import annotations
+
+from typing import Optional
+
+from .constants import DEFAULT_BASE_URL, DEFAULT_CONNECT_TIMEOUT, DEFAULT_TIMEOUT
+from ._transport import AsyncTransport, SyncTransport
+from .resources.cloud_servers import AsyncCloudServers, CloudServers
+from .resources.flavors import AsyncFlavors, Flavors
+from .resources.os_images import AsyncOSImages, OSImages
+from .resources.users import AsyncUsers, Users
+
+
+class IntelionCloud:
+    """Synchronous client for the Intelion Cloud API.
+
+    Usage::
+
+        client = IntelionCloud(token="your_api_token")
+        servers = client.cloud_servers.list()
+        client.close()
+
+    Or as a context manager::
+
+        with IntelionCloud(token="your_api_token") as client:
+            servers = client.cloud_servers.list()
+
+    Args:
+        token: API authentication token (``Authorization: Token <token>``).
+        base_url: Base URL of the Intelion Cloud instance.
+        timeout: Overall request timeout in seconds.
+        connect_timeout: Connection establishment timeout in seconds.
+    """
+
+    def __init__(
+        self,
+        token: str,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT,
+        connect_timeout: float = DEFAULT_CONNECT_TIMEOUT,
+    ) -> None:
+        self._transport = SyncTransport(
+            token=token,
+            base_url=base_url,
+            timeout=timeout,
+            connect_timeout=connect_timeout,
+        )
+        self.cloud_servers = CloudServers(self._transport)
+        self.flavors = Flavors(self._transport)
+        self.os_images = OSImages(self._transport)
+        self.users = Users(self._transport)
+
+    def close(self) -> None:
+        """Close the underlying HTTP connection pool."""
+        self._transport.close()
+
+    def __enter__(self) -> IntelionCloud:
+        return self
+
+    def __exit__(self, *args: object) -> None:
+        self.close()
+
+
+class AsyncIntelionCloud:
+    """Asynchronous client for the Intelion Cloud API.
+
+    Usage::
+
+        async with AsyncIntelionCloud(token="your_api_token") as client:
+            servers = await client.cloud_servers.list()
+
+    Args:
+        token: API authentication token (``Authorization: Token <token>``).
+        base_url: Base URL of the Intelion Cloud instance.
+        timeout: Overall request timeout in seconds.
+        connect_timeout: Connection establishment timeout in seconds.
+    """
+
+    def __init__(
+        self,
+        token: str,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT,
+        connect_timeout: float = DEFAULT_CONNECT_TIMEOUT,
+    ) -> None:
+        self._transport = AsyncTransport(
+            token=token,
+            base_url=base_url,
+            timeout=timeout,
+            connect_timeout=connect_timeout,
+        )
+        self.cloud_servers = AsyncCloudServers(self._transport)
+        self.flavors = AsyncFlavors(self._transport)
+        self.os_images = AsyncOSImages(self._transport)
+        self.users = AsyncUsers(self._transport)
+
+    async def close(self) -> None:
+        """Close the underlying async HTTP connection pool."""
+        await self._transport.close()
+
+    async def __aenter__(self) -> AsyncIntelionCloud:
+        return self
+
+    async def __aexit__(self, *args: object) -> None:
+        await self.close()

intelion_cloud/_pagination.py

@@ -0,0 +1,66 @@
+"""Pagination helpers for DRF paginated responses."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Dict, Generic, List, Optional, Tuple, TypeVar
+from urllib.parse import parse_qs, urlparse
+
+T = TypeVar("T")
+
+
+@dataclass
+class PaginatedResponse(Generic[T]):
+    """A single page of results from the API."""
+
+    count: int
+    results: List[T]
+    next_url: Optional[str] = None
+    previous_url: Optional[str] = None
+
+    @property
+    def has_next(self) -> bool:
+        return self.next_url is not None
+
+
+def parse_paginated(data: Dict[str, Any]) -> Dict[str, Any]:
+    """Extract pagination metadata from a DRF response.
+
+    Returns dict with 'count', 'next', 'previous', 'results'.
+    If the response is not paginated (plain list), wraps it.
+    """
+    if isinstance(data, list):
+        return {"count": len(data), "next": None, "previous": None, "results": data}
+    return {
+        "count": data.get("count", 0),
+        "next": data.get("next"),
+        "previous": data.get("previous"),
+        "results": data.get("results", []),
+    }
+
+
+def extract_next_page(url: Optional[str]) -> Optional[Tuple[str, Dict[str, str]]]:
+    """Convert an absolute next/previous URL to (path, params) for the transport.
+
+    Returns None if URL is None, otherwise (relative_path, query_params).
+
+    Example:
+        'https://intelion.cloud/api/v2/flavors/?page=2'
+        -> ('flavors/', {'page': '2'})
+    """
+    if url is None:
+        return None
+
+    parsed = urlparse(url)
+
+    # Extract relative path after /api/v2/
+    path = parsed.path
+    marker = "/api/v2/"
+    idx = path.find(marker)
+    if idx >= 0:
+        path = path[idx + len(marker) :]
+
+    # Parse query string into flat dict (take first value of each key)
+    params = {k: v[0] for k, v in parse_qs(parsed.query).items()}
+
+    return path, params

intelion_cloud/_transport.py

@@ -0,0 +1,342 @@
+"""HTTP transport layer with retry logic, error mapping, and logging."""
+
+from __future__ import annotations
+
+import logging
+import time
+from typing import Any, Dict, Optional
+
+import httpx
+
+from .constants import DEFAULT_BASE_URL, DEFAULT_CONNECT_TIMEOUT, DEFAULT_TIMEOUT
+from .exceptions import (
+    APIError,
+    AuthenticationError,
+    ConnectionError,
+    ConflictError,
+    ForbiddenError,
+    NotFoundError,
+    RateLimitError,
+    ServerError,
+    ValidationError,
+)
+
+logger = logging.getLogger("intelion_cloud")
+
+_IDEMPOTENT_METHODS = frozenset({"GET", "PUT", "PATCH", "DELETE"})
+
+# Retry configuration
+_MAX_RATE_LIMIT_RETRIES = 3
+_MAX_SERVER_ERROR_RETRIES = 1
+_MAX_CONNECTION_RETRIES = 2
+_RATE_LIMIT_BASE_DELAY = 1.0
+_SERVER_ERROR_DELAY = 1.0
+_CONNECTION_BASE_DELAY = 0.5
+
+
+def _build_api_url(base_url: str) -> str:
+    return base_url.rstrip("/") + "/api/v2/"
+
+
+def _raise_for_status(response: httpx.Response) -> None:
+    """Map HTTP error responses to typed exceptions."""
+    status = response.status_code
+    if status < 400:
+        return
+
+    try:
+        body = response.json()
+    except Exception:
+        body = response.text
+
+    message = _extract_message(body, status)
+
+    if status == 400:
+        field_errors = body if isinstance(body, dict) else {}
+        raise ValidationError(
+            message,
+            status_code=status,
+            response_body=body,
+            field_errors=field_errors,
+        )
+    if status == 401:
+        raise AuthenticationError(message, status_code=status, response_body=body)
+    if status == 403:
+        raise ForbiddenError(message, status_code=status, response_body=body)
+    if status == 404:
+        raise NotFoundError(message, status_code=status, response_body=body)
+    if status == 409:
+        raise ConflictError(message, status_code=status, response_body=body)
+    if status == 429:
+        retry_after = _parse_retry_after(response)
+        raise RateLimitError(
+            message,
+            status_code=status,
+            response_body=body,
+            retry_after=retry_after,
+        )
+    if status >= 500:
+        raise ServerError(message, status_code=status, response_body=body)
+
+    raise APIError(message, status_code=status, response_body=body)
+
+
+def _extract_message(body: Any, status_code: int) -> str:
+    if isinstance(body, dict):
+        for key in ("detail", "message", "error", "non_field_errors"):
+            if key in body:
+                val = body[key]
+                if isinstance(val, list):
+                    return "; ".join(str(v) for v in val)
+                return str(val)
+    if isinstance(body, str) and body:
+        return body
+    return f"API error {status_code}"
+
+
+def _parse_retry_after(response: httpx.Response) -> Optional[float]:
+    header = response.headers.get("retry-after")
+    if header is None:
+        return None
+    try:
+        return float(header)
+    except (ValueError, TypeError):
+        return None
+
+
+def _should_retry_rate_limit(attempt: int) -> bool:
+    return attempt < _MAX_RATE_LIMIT_RETRIES
+
+
+def _should_retry_server_error(method: str, attempt: int) -> bool:
+    return attempt < _MAX_SERVER_ERROR_RETRIES and method in _IDEMPOTENT_METHODS
+
+
+def _should_retry_connection(method: str, attempt: int) -> bool:
+    return attempt < _MAX_CONNECTION_RETRIES and method in _IDEMPOTENT_METHODS
+
+
+def _rate_limit_delay(attempt: int, retry_after: Optional[float]) -> float:
+    if retry_after is not None and retry_after > 0:
+        return min(retry_after, 30.0)
+    return _RATE_LIMIT_BASE_DELAY * (2**attempt)
+
+
+class SyncTransport:
+    """Synchronous HTTP transport using httpx.Client."""
+
+    def __init__(
+        self,
+        token: str,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT,
+        connect_timeout: float = DEFAULT_CONNECT_TIMEOUT,
+    ) -> None:
+        self._client = httpx.Client(
+            base_url=_build_api_url(base_url),
+            headers={
+                "Authorization": f"Token {token}",
+                "Accept": "application/json",
+            },
+            timeout=httpx.Timeout(timeout, connect=connect_timeout),
+        )
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: Optional[Dict[str, Any]] = None,
+        params: Optional[Dict[str, Any]] = None,
+    ) -> httpx.Response:
+        attempt = 0
+        while True:
+            start = time.monotonic()
+            try:
+                response = self._client.request(
+                    method,
+                    path,
+                    json=json,
+                    params=params,
+                )
+                duration = time.monotonic() - start
+                logger.debug(
+                    "%s %s -> %d (%.2fs)",
+                    method,
+                    path,
+                    response.status_code,
+                    duration,
+                )
+
+                try:
+                    _raise_for_status(response)
+                except RateLimitError as exc:
+                    if _should_retry_rate_limit(attempt):
+                        delay = _rate_limit_delay(attempt, exc.retry_after)
+                        logger.warning(
+                            "Rate limited, retry %d/%d in %.1fs",
+                            attempt + 1,
+                            _MAX_RATE_LIMIT_RETRIES,
+                            delay,
+                        )
+                        time.sleep(delay)
+                        attempt += 1
+                        continue
+                    raise
+                except ServerError:
+                    if _should_retry_server_error(method, attempt):
+                        logger.warning(
+                            "Server error %d, retry %d/%d in %.1fs",
+                            response.status_code,
+                            attempt + 1,
+                            _MAX_SERVER_ERROR_RETRIES,
+                            _SERVER_ERROR_DELAY,
+                        )
+                        time.sleep(_SERVER_ERROR_DELAY)
+                        attempt += 1
+                        continue
+                    raise
+
+                return response
+
+            except (httpx.ConnectError, httpx.ReadError, httpx.WriteError) as exc:
+                if _should_retry_connection(method, attempt):
+                    delay = _CONNECTION_BASE_DELAY * (2**attempt)
+                    logger.warning(
+                        "Connection error (%s), retry %d/%d in %.1fs",
+                        type(exc).__name__,
+                        attempt + 1,
+                        _MAX_CONNECTION_RETRIES,
+                        delay,
+                    )
+                    time.sleep(delay)
+                    attempt += 1
+                    continue
+                raise ConnectionError(str(exc)) from exc
+            except httpx.TimeoutException as exc:
+                if method == "GET" and attempt < _MAX_CONNECTION_RETRIES:
+                    delay = _RATE_LIMIT_BASE_DELAY * (2**attempt)
+                    logger.warning(
+                        "Timeout on GET, retry %d/%d in %.1fs",
+                        attempt + 1,
+                        _MAX_CONNECTION_RETRIES,
+                        delay,
+                    )
+                    time.sleep(delay)
+                    attempt += 1
+                    continue
+                raise ConnectionError(str(exc)) from exc
+
+    def close(self) -> None:
+        self._client.close()
+
+
+class AsyncTransport:
+    """Asynchronous HTTP transport using httpx.AsyncClient."""
+
+    def __init__(
+        self,
+        token: str,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT,
+        connect_timeout: float = DEFAULT_CONNECT_TIMEOUT,
+    ) -> None:
+        self._client = httpx.AsyncClient(
+            base_url=_build_api_url(base_url),
+            headers={
+                "Authorization": f"Token {token}",
+                "Accept": "application/json",
+            },
+            timeout=httpx.Timeout(timeout, connect=connect_timeout),
+        )
+
+    async def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: Optional[Dict[str, Any]] = None,
+        params: Optional[Dict[str, Any]] = None,
+    ) -> httpx.Response:
+        import asyncio
+
+        attempt = 0
+        while True:
+            start = time.monotonic()
+            try:
+                response = await self._client.request(
+                    method,
+                    path,
+                    json=json,
+                    params=params,
+                )
+                duration = time.monotonic() - start
+                logger.debug(
+                    "%s %s -> %d (%.2fs)",
+                    method,
+                    path,
+                    response.status_code,
+                    duration,
+                )
+
+                try:
+                    _raise_for_status(response)
+                except RateLimitError as exc:
+                    if _should_retry_rate_limit(attempt):
+                        delay = _rate_limit_delay(attempt, exc.retry_after)
+                        logger.warning(
+                            "Rate limited, retry %d/%d in %.1fs",
+                            attempt + 1,
+                            _MAX_RATE_LIMIT_RETRIES,
+                            delay,
+                        )
+                        await asyncio.sleep(delay)
+                        attempt += 1
+                        continue
+                    raise
+                except ServerError:
+                    if _should_retry_server_error(method, attempt):
+                        logger.warning(
+                            "Server error %d, retry %d/%d in %.1fs",
+                            response.status_code,
+                            attempt + 1,
+                            _MAX_SERVER_ERROR_RETRIES,
+                            _SERVER_ERROR_DELAY,
+                        )
+                        await asyncio.sleep(_SERVER_ERROR_DELAY)
+                        attempt += 1
+                        continue
+                    raise
+
+                return response
+
+            except (httpx.ConnectError, httpx.ReadError, httpx.WriteError) as exc:
+                if _should_retry_connection(method, attempt):
+                    delay = _CONNECTION_BASE_DELAY * (2**attempt)
+                    logger.warning(
+                        "Connection error (%s), retry %d/%d in %.1fs",
+                        type(exc).__name__,
+                        attempt + 1,
+                        _MAX_CONNECTION_RETRIES,
+                        delay,
+                    )
+                    await asyncio.sleep(delay)
+                    attempt += 1
+                    continue
+                raise ConnectionError(str(exc)) from exc
+            except httpx.TimeoutException as exc:
+                if method == "GET" and attempt < _MAX_CONNECTION_RETRIES:
+                    delay = _RATE_LIMIT_BASE_DELAY * (2**attempt)
+                    logger.warning(
+                        "Timeout on GET, retry %d/%d in %.1fs",
+                        attempt + 1,
+                        _MAX_CONNECTION_RETRIES,
+                        delay,
+                    )
+                    await asyncio.sleep(delay)
+                    attempt += 1
+                    continue
+                raise ConnectionError(str(exc)) from exc
+
+    async def close(self) -> None:
+        await self._client.aclose()

intelion_cloud/constants.py

@@ -0,0 +1,74 @@
+"""Enumerations and constants matching the Intelion Cloud API."""
+
+from enum import IntEnum
+
+__all__ = [
+    "ServerStatus",
+    "ServerState",
+    "PricePlan",
+    "BillingPeriod",
+    "OSType",
+    "DEFAULT_BASE_URL",
+    "DEFAULT_TIMEOUT",
+    "DEFAULT_CONNECT_TIMEOUT",
+]
+
+DEFAULT_BASE_URL = "https://intelion.cloud"
+DEFAULT_TIMEOUT = 30.0
+DEFAULT_CONNECT_TIMEOUT = 10.0
+
+
+class ServerStatus(IntEnum):
+    """Server status codes returned by the API."""
+
+    ERROR = -4
+    DELETED = -3
+    REQUESTED = -2
+    PAUSED = -1
+    PAUSING = 0
+    START = 1
+    ACTIVE = 2
+    PREPARING = 3
+
+
+class ServerState(IntEnum):
+    """Server state codes indicating current operation."""
+
+    IDLE = 0
+    STARTING = 100
+    SHELVING = 200
+    MIGRATING_SHELVING = 301
+    MIGRATING_SNAPSHOTTING = 302
+    MIGRATING_DELETING = 303
+    MIGRATING_CREATING = 304
+    CLONING = 400
+    QUEUED = 500
+    AWAITING_PASSWORD = 600
+    MAINTENANCE = 700
+
+
+class PricePlan(IntEnum):
+    """Billing plan options for server configurations."""
+
+    POSTPAID_QUARTER = -3
+    POSTPAID_MONTHLY = -1
+    HOURLY = 0
+    MONTHLY = 1
+    QUARTERLY = 3
+    SEMIANNUAL = 6
+    ANNUAL = 12
+
+
+class BillingPeriod(IntEnum):
+    """Billing period types used in usage acts."""
+
+    HOURLY = 0
+    MONTHLY = 30
+    MONTHLY_ALIGNED = 31
+
+
+class OSType:
+    """Operating system type identifiers."""
+
+    WINDOWS = "win"
+    LINUX = "lin"