plato-sdk-v2 2.0.50__py3-none-any.whl → 2.2.4__py3-none-any.whl

plato/chronos/api/worlds/get_world.py

@@ -0,0 +1,62 @@
+"""Get World"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+from plato.chronos.errors import raise_for_status
+from plato.chronos.models import WorldResponse
+
+
+def _build_request_args(
+    public_id: str,
+    x_api_key: str | None = None,
+) -> dict[str, Any]:
+    """Build request arguments."""
+    url = f"/api/worlds/{public_id}"
+
+    headers: dict[str, str] = {}
+    if x_api_key is not None:
+        headers["X-API-Key"] = x_api_key
+
+    return {
+        "method": "GET",
+        "url": url,
+        "headers": headers,
+    }
+
+
+def sync(
+    client: httpx.Client,
+    public_id: str,
+    x_api_key: str | None = None,
+) -> WorldResponse:
+    """Get a world by public ID."""
+
+    request_args = _build_request_args(
+        public_id=public_id,
+        x_api_key=x_api_key,
+    )
+
+    response = client.request(**request_args)
+    raise_for_status(response)
+    return WorldResponse.model_validate(response.json())
+
+
+async def asyncio(
+    client: httpx.AsyncClient,
+    public_id: str,
+    x_api_key: str | None = None,
+) -> WorldResponse:
+    """Get a world by public ID."""
+
+    request_args = _build_request_args(
+        public_id=public_id,
+        x_api_key=x_api_key,
+    )
+
+    response = await client.request(**request_args)
+    raise_for_status(response)
+    return WorldResponse.model_validate(response.json())

plato/chronos/api/worlds/list_worlds.py

@@ -0,0 +1,57 @@
+"""List Worlds"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+from plato.chronos.errors import raise_for_status
+from plato.chronos.models import WorldListResponse
+
+
+def _build_request_args(
+    x_api_key: str | None = None,
+) -> dict[str, Any]:
+    """Build request arguments."""
+    url = "/api/worlds"
+
+    headers: dict[str, str] = {}
+    if x_api_key is not None:
+        headers["X-API-Key"] = x_api_key
+
+    return {
+        "method": "GET",
+        "url": url,
+        "headers": headers,
+    }
+
+
+def sync(
+    client: httpx.Client,
+    x_api_key: str | None = None,
+) -> WorldListResponse:
+    """List all worlds for the org."""
+
+    request_args = _build_request_args(
+        x_api_key=x_api_key,
+    )
+
+    response = client.request(**request_args)
+    raise_for_status(response)
+    return WorldListResponse.model_validate(response.json())
+
+
+async def asyncio(
+    client: httpx.AsyncClient,
+    x_api_key: str | None = None,
+) -> WorldListResponse:
+    """List all worlds for the org."""
+
+    request_args = _build_request_args(
+        x_api_key=x_api_key,
+    )
+
+    response = await client.request(**request_args)
+    raise_for_status(response)
+    return WorldListResponse.model_validate(response.json())

plato/chronos/client.py

@@ -0,0 +1,171 @@
+"""HTTP client for Chronos API."""
+
+from __future__ import annotations
+
+import warnings
+from collections.abc import Callable
+from typing import Any
+
+import httpx
+
+
+class Client:
+    """Sync HTTP client for Chronos API."""
+
+    def __init__(
+        self,
+        base_url: str,
+        timeout: float = 30.0,
+        headers: dict[str, str] | None = None,
+        max_retries: int = 3,
+        retry_on_status: tuple[int, ...] = (429, 500, 502, 503, 504),
+        on_request: Callable[[httpx.Request], None] | None = None,
+        on_response: Callable[[httpx.Response], None] | None = None,
+        **kwargs: Any,
+    ):
+        """Initialize the HTTP client.
+
+        Args:
+            base_url: Base URL for API requests
+            timeout: Request timeout in seconds
+            headers: Default headers to include in all requests
+            max_retries: Maximum number of retry attempts for failed requests
+            retry_on_status: HTTP status codes that trigger a retry
+            on_request: Hook called before each request
+            on_response: Hook called after each response
+            **kwargs: Additional arguments passed to httpx.Client
+        """
+        self._base_url = base_url.rstrip("/")
+        self._headers = headers or {}
+        self._max_retries = max_retries
+        self._retry_on_status = retry_on_status
+        self._closed = False
+
+        event_hooks: dict[str, list[Callable]] = {"request": [], "response": []}
+        if on_request:
+            event_hooks["request"].append(on_request)
+        if on_response:
+            event_hooks["response"].append(on_response)
+
+        self._client = httpx.Client(
+            base_url=self._base_url,
+            timeout=timeout,
+            headers=self._headers,
+            event_hooks=event_hooks if any(event_hooks.values()) else None,
+            **kwargs,
+        )
+
+    @property
+    def httpx(self) -> httpx.Client:
+        """Access the underlying httpx client."""
+        return self._client
+
+    @property
+    def max_retries(self) -> int:
+        """Maximum number of retry attempts."""
+        return self._max_retries
+
+    @property
+    def retry_on_status(self) -> tuple[int, ...]:
+        """HTTP status codes that trigger a retry."""
+        return self._retry_on_status
+
+    def close(self) -> None:
+        """Close the client."""
+        self._closed = True
+        self._client.close()
+
+    def __enter__(self) -> Client:
+        return self
+
+    def __exit__(self, *args: Any) -> None:
+        self.close()
+
+    def __del__(self) -> None:
+        if not self._closed:
+            warnings.warn(
+                f"{self.__class__.__name__} was not closed. Use 'with' statement or call 'client.close()'",
+                ResourceWarning,
+                stacklevel=2,
+            )
+
+
+class AsyncClient:
+    """Async HTTP client for Chronos API."""
+
+    def __init__(
+        self,
+        base_url: str,
+        timeout: float = 30.0,
+        headers: dict[str, str] | None = None,
+        max_retries: int = 3,
+        retry_on_status: tuple[int, ...] = (429, 500, 502, 503, 504),
+        on_request: Callable[[httpx.Request], None] | None = None,
+        on_response: Callable[[httpx.Response], None] | None = None,
+        **kwargs: Any,
+    ):
+        """Initialize the async HTTP client.
+
+        Args:
+            base_url: Base URL for API requests
+            timeout: Request timeout in seconds
+            headers: Default headers to include in all requests
+            max_retries: Maximum number of retry attempts for failed requests
+            retry_on_status: HTTP status codes that trigger a retry
+            on_request: Hook called before each request
+            on_response: Hook called after each response
+            **kwargs: Additional arguments passed to httpx.AsyncClient
+        """
+        self._base_url = base_url.rstrip("/")
+        self._headers = headers or {}
+        self._max_retries = max_retries
+        self._retry_on_status = retry_on_status
+        self._closed = False
+
+        event_hooks: dict[str, list[Callable]] = {"request": [], "response": []}
+        if on_request:
+            event_hooks["request"].append(on_request)
+        if on_response:
+            event_hooks["response"].append(on_response)
+
+        self._client = httpx.AsyncClient(
+            base_url=self._base_url,
+            timeout=timeout,
+            headers=self._headers,
+            event_hooks=event_hooks if any(event_hooks.values()) else None,
+            **kwargs,
+        )
+
+    @property
+    def httpx(self) -> httpx.AsyncClient:
+        """Access the underlying httpx client."""
+        return self._client
+
+    @property
+    def max_retries(self) -> int:
+        """Maximum number of retry attempts."""
+        return self._max_retries
+
+    @property
+    def retry_on_status(self) -> tuple[int, ...]:
+        """HTTP status codes that trigger a retry."""
+        return self._retry_on_status
+
+    async def close(self) -> None:
+        """Close the client."""
+        self._closed = True
+        await self._client.aclose()
+
+    async def __aenter__(self) -> AsyncClient:
+        return self
+
+    async def __aexit__(self, *args: Any) -> None:
+        await self.close()
+
+    def __del__(self) -> None:
+        if not self._closed:
+            warnings.warn(
+                f"{self.__class__.__name__} was not closed. Use 'async with' statement or call 'await client.close()'",
+                ResourceWarning,
+                stacklevel=2,
+            )

plato/chronos/errors.py

@@ -0,0 +1,141 @@
+"""API error types for Chronos API."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+class APIError(Exception):
+    """Base exception for API errors."""
+
+    def __init__(
+        self,
+        status_code: int,
+        message: str | None = None,
+        body: dict[str, Any] | None = None,
+    ):
+        self.status_code = status_code
+        self.message = message or f"API request failed with status {status_code}"
+        self.body = body
+        super().__init__(self.message)
+
+    def __repr__(self) -> str:
+        return f"{self.__class__.__name__}(status_code={self.status_code}, message={self.message!r})"
+
+
+class BadRequestError(APIError):
+    """400 Bad Request - Invalid request parameters."""
+
+    def __init__(self, message: str | None = None, body: dict[str, Any] | None = None):
+        super().__init__(400, message or "Bad request", body)
+
+
+class UnauthorizedError(APIError):
+    """401 Unauthorized - Invalid or missing authentication."""
+
+    def __init__(self, message: str | None = None, body: dict[str, Any] | None = None):
+        super().__init__(401, message or "Unauthorized", body)
+
+
+class ForbiddenError(APIError):
+    """403 Forbidden - Insufficient permissions."""
+
+    def __init__(self, message: str | None = None, body: dict[str, Any] | None = None):
+        super().__init__(403, message or "Forbidden", body)
+
+
+class NotFoundError(APIError):
+    """404 Not Found - Resource not found."""
+
+    def __init__(self, message: str | None = None, body: dict[str, Any] | None = None):
+        super().__init__(404, message or "Not found", body)
+
+
+class ConflictError(APIError):
+    """409 Conflict - Resource conflict."""
+
+    def __init__(self, message: str | None = None, body: dict[str, Any] | None = None):
+        super().__init__(409, message or "Conflict", body)
+
+
+class UnprocessableEntityError(APIError):
+    """422 Unprocessable Entity - Validation error."""
+
+    def __init__(self, message: str | None = None, body: dict[str, Any] | None = None):
+        super().__init__(422, message or "Unprocessable entity", body)
+
+
+class RateLimitError(APIError):
+    """429 Too Many Requests - Rate limit exceeded."""
+
+    def __init__(
+        self,
+        message: str | None = None,
+        body: dict[str, Any] | None = None,
+        retry_after: float | None = None,
+    ):
+        super().__init__(429, message or "Rate limit exceeded", body)
+        self.retry_after = retry_after
+
+
+class InternalServerError(APIError):
+    """500 Internal Server Error - Server error."""
+
+    def __init__(self, message: str | None = None, body: dict[str, Any] | None = None):
+        super().__init__(500, message or "Internal server error", body)
+
+
+class ServiceUnavailableError(APIError):
+    """503 Service Unavailable - Service temporarily unavailable."""
+
+    def __init__(self, message: str | None = None, body: dict[str, Any] | None = None):
+        super().__init__(503, message or "Service unavailable", body)
+
+
+def raise_for_status(response) -> None:
+    """Raise appropriate error based on response status code.
+
+    Args:
+        response: httpx.Response object
+
+    Raises:
+        APIError: Appropriate subclass based on status code
+    """
+    if response.is_success:
+        return
+
+    status = response.status_code
+
+    try:
+        body = response.json()
+        message = body.get("message") or body.get("error") or body.get("detail")
+    except Exception:
+        body = None
+        message = response.text or None
+
+    error_map = {
+        400: BadRequestError,
+        401: UnauthorizedError,
+        403: ForbiddenError,
+        404: NotFoundError,
+        409: ConflictError,
+        422: UnprocessableEntityError,
+        429: RateLimitError,
+        500: InternalServerError,
+        503: ServiceUnavailableError,
+    }
+
+    error_class = error_map.get(status, APIError)
+
+    if status == 429:
+        retry_after = response.headers.get("retry-after")
+        raise RateLimitError(
+            message=message,
+            body=body,
+            retry_after=float(retry_after) if retry_after else None,
+        )
+
+    if error_class == APIError:
+        raise APIError(status, message, body)
+
+    raise error_class(message, body)