jsondb-cloud 1.0.4__py3-none-any.whl

jsondb_cloud/__init__.py

@@ -0,0 +1,65 @@
+"""jsondb-cloud — The official Python SDK for jsondb.cloud.
+
+Quick start::
+
+    from jsondb_cloud import JsonDB
+
+    db = JsonDB(api_key="jdb_sk_live_xxxx")
+    users = db.collection("users")
+
+    user = users.create({"name": "Alice", "email": "alice@example.com"})
+    print(user["_id"])
+
+Async usage::
+
+    from jsondb_cloud import AsyncJsonDB
+
+    async with AsyncJsonDB(api_key="jdb_sk_live_xxxx") as db:
+        users = db.collection("users")
+        user = await users.create({"name": "Alice"})
+"""
+
+from .client import AsyncJsonDB, JsonDB
+from .collection import AsyncCollection, Collection
+from .errors import (
+    ConflictError,
+    DocumentTooLargeError,
+    ForbiddenError,
+    JsonDBError,
+    NotFoundError,
+    QuotaExceededError,
+    RateLimitError,
+    ServerError,
+    UnauthorizedError,
+    ValidationError,
+    create_error,
+)
+from .models import BulkResult, BulkResultSummary, ListResult, Meta
+
+__all__ = [
+    # Clients
+    "JsonDB",
+    "AsyncJsonDB",
+    # Collections
+    "Collection",
+    "AsyncCollection",
+    # Response models
+    "ListResult",
+    "Meta",
+    "BulkResult",
+    "BulkResultSummary",
+    # Errors
+    "JsonDBError",
+    "NotFoundError",
+    "ConflictError",
+    "ValidationError",
+    "UnauthorizedError",
+    "ForbiddenError",
+    "QuotaExceededError",
+    "RateLimitError",
+    "DocumentTooLargeError",
+    "ServerError",
+    "create_error",
+]
+
+__version__ = "1.0.0"

jsondb_cloud/_http.py

@@ -0,0 +1,244 @@
+"""Low-level HTTP client wrappers with auto-retry for the jsondb.cloud API."""
+
+from __future__ import annotations
+
+import asyncio
+import math
+import time
+from typing import Any, Dict, Optional
+
+import httpx
+
+from .errors import JsonDBError, create_error
+
+
+# HTTP status codes that should trigger an automatic retry.
+_RETRYABLE_STATUSES = frozenset({429, 500, 502, 503, 504})
+
+
+def _backoff_delay(attempt: int, base_delay: float, max_delay: float) -> float:
+    """Calculate exponential backoff delay with jitter cap.
+
+    Args:
+        attempt: Zero-based attempt index (0 = first retry).
+        base_delay: Base delay in seconds.
+        max_delay: Maximum delay in seconds.
+
+    Returns:
+        Delay in seconds before the next retry.
+    """
+    return min(base_delay * math.pow(2, attempt), max_delay)
+
+
+class SyncHTTPClient:
+    """Synchronous HTTP client wrapper around ``httpx.Client``.
+
+    Handles Bearer token auth, automatic retries on 429/5xx with exponential
+    backoff, and translation of error responses into ``JsonDBError`` subclasses.
+    """
+
+    def __init__(
+        self,
+        *,
+        api_key: str,
+        base_url: str = "https://api.jsondb.cloud",
+        max_retries: int = 3,
+        retry_base_delay: float = 1.0,
+        retry_max_delay: float = 10.0,
+        timeout: float = 30.0,
+        headers: Optional[Dict[str, str]] = None,
+    ) -> None:
+        self._api_key = api_key
+        self._base_url = base_url.rstrip("/")
+        self._max_retries = max_retries
+        self._retry_base_delay = retry_base_delay
+        self._retry_max_delay = retry_max_delay
+
+        default_headers = {
+            "Authorization": f"Bearer {api_key}",
+            "Content-Type": "application/json",
+            "Accept": "application/json",
+        }
+        if headers:
+            default_headers.update(headers)
+
+        self._client = httpx.Client(
+            base_url=self._base_url,
+            headers=default_headers,
+            timeout=httpx.Timeout(timeout),
+        )
+
+    def close(self) -> None:
+        """Close the underlying HTTP client."""
+        self._client.close()
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: Any = None,
+        headers: Optional[Dict[str, str]] = None,
+    ) -> Any:
+        """Execute an HTTP request with automatic retry.
+
+        Args:
+            method: HTTP method (``GET``, ``POST``, ``PUT``, ``PATCH``, ``DELETE``).
+            path: URL path relative to ``base_url`` (should start with ``/``).
+            json: JSON-serializable request body (for POST/PUT/PATCH).
+            headers: Extra headers to merge for this request only.
+
+        Returns:
+            Parsed JSON response body, or ``None`` for 204 responses.
+
+        Raises:
+            JsonDBError: On non-retryable API errors.
+        """
+        max_attempts = self._max_retries + 1
+        last_error: Optional[Exception] = None
+
+        for attempt in range(max_attempts):
+            try:
+                response = self._client.request(
+                    method,
+                    path,
+                    json=json,
+                    headers=headers,
+                )
+
+                # Retry on retryable status codes
+                if response.status_code in _RETRYABLE_STATUSES and attempt < max_attempts - 1:
+                    delay = _backoff_delay(attempt, self._retry_base_delay, self._retry_max_delay)
+                    time.sleep(delay)
+                    continue
+
+                # No content
+                if response.status_code == 204:
+                    return None
+
+                data = response.json()
+
+                if not response.is_success:
+                    raise create_error(response.status_code, data)
+
+                return data
+
+            except JsonDBError:
+                raise
+            except Exception as exc:
+                last_error = exc
+                if attempt < max_attempts - 1:
+                    delay = _backoff_delay(attempt, self._retry_base_delay, self._retry_max_delay)
+                    time.sleep(delay)
+                    continue
+
+        if last_error is not None:
+            raise last_error
+        raise JsonDBError("Request failed after retries")  # pragma: no cover
+
+
+class AsyncHTTPClient:
+    """Asynchronous HTTP client wrapper around ``httpx.AsyncClient``.
+
+    Handles Bearer token auth, automatic retries on 429/5xx with exponential
+    backoff, and translation of error responses into ``JsonDBError`` subclasses.
+    """
+
+    def __init__(
+        self,
+        *,
+        api_key: str,
+        base_url: str = "https://api.jsondb.cloud",
+        max_retries: int = 3,
+        retry_base_delay: float = 1.0,
+        retry_max_delay: float = 10.0,
+        timeout: float = 30.0,
+        headers: Optional[Dict[str, str]] = None,
+    ) -> None:
+        self._api_key = api_key
+        self._base_url = base_url.rstrip("/")
+        self._max_retries = max_retries
+        self._retry_base_delay = retry_base_delay
+        self._retry_max_delay = retry_max_delay
+
+        default_headers = {
+            "Authorization": f"Bearer {api_key}",
+            "Content-Type": "application/json",
+            "Accept": "application/json",
+        }
+        if headers:
+            default_headers.update(headers)
+
+        self._client = httpx.AsyncClient(
+            base_url=self._base_url,
+            headers=default_headers,
+            timeout=httpx.Timeout(timeout),
+        )
+
+    async def close(self) -> None:
+        """Close the underlying async HTTP client."""
+        await self._client.aclose()
+
+    async def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: Any = None,
+        headers: Optional[Dict[str, str]] = None,
+    ) -> Any:
+        """Execute an async HTTP request with automatic retry.
+
+        Args:
+            method: HTTP method (``GET``, ``POST``, ``PUT``, ``PATCH``, ``DELETE``).
+            path: URL path relative to ``base_url`` (should start with ``/``).
+            json: JSON-serializable request body (for POST/PUT/PATCH).
+            headers: Extra headers to merge for this request only.
+
+        Returns:
+            Parsed JSON response body, or ``None`` for 204 responses.
+
+        Raises:
+            JsonDBError: On non-retryable API errors.
+        """
+        max_attempts = self._max_retries + 1
+        last_error: Optional[Exception] = None
+
+        for attempt in range(max_attempts):
+            try:
+                response = await self._client.request(
+                    method,
+                    path,
+                    json=json,
+                    headers=headers,
+                )
+
+                # Retry on retryable status codes
+                if response.status_code in _RETRYABLE_STATUSES and attempt < max_attempts - 1:
+                    delay = _backoff_delay(attempt, self._retry_base_delay, self._retry_max_delay)
+                    await asyncio.sleep(delay)
+                    continue
+
+                # No content
+                if response.status_code == 204:
+                    return None
+
+                data = response.json()
+
+                if not response.is_success:
+                    raise create_error(response.status_code, data)
+
+                return data
+
+            except JsonDBError:
+                raise
+            except Exception as exc:
+                last_error = exc
+                if attempt < max_attempts - 1:
+                    delay = _backoff_delay(attempt, self._retry_base_delay, self._retry_max_delay)
+                    await asyncio.sleep(delay)
+                    continue
+
+        if last_error is not None:
+            raise last_error
+        raise JsonDBError("Request failed after retries")  # pragma: no cover

jsondb_cloud/client.py

@@ -0,0 +1,177 @@
+"""Client classes for the jsondb.cloud Python SDK."""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional, cast
+
+from ._http import AsyncHTTPClient, SyncHTTPClient
+from .collection import AsyncCollection, Collection
+
+
+class JsonDB:
+    """Synchronous client for the jsondb.cloud API.
+
+    Usage::
+
+        from jsondb_cloud import JsonDB
+
+        db = JsonDB(api_key="jdb_sk_live_xxxx")
+        users = db.collection("users")
+
+        # Create a document
+        alice = users.create({"name": "Alice", "email": "alice@example.com"})
+
+        # Read it back
+        user = users.get(alice["_id"])
+
+    Supports use as a context manager::
+
+        with JsonDB(api_key="jdb_sk_live_xxxx") as db:
+            users = db.collection("users")
+            users.create({"name": "Alice"})
+
+    Args:
+        api_key: API key (``jdb_sk_live_*`` or ``jdb_sk_test_*``).
+        project: Project name. Defaults to ``"v1"``.
+        base_url: API base URL. Defaults to ``"https://api.jsondb.cloud"``.
+        max_retries: Maximum number of retries on 429/5xx. Defaults to ``3``.
+        retry_base_delay: Base delay in seconds for exponential backoff. Defaults to ``1.0``.
+        retry_max_delay: Maximum delay in seconds for exponential backoff. Defaults to ``10.0``.
+        timeout: Request timeout in seconds. Defaults to ``30.0``.
+        headers: Optional extra headers to include with every request.
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        project: str = "v1",
+        base_url: str = "https://api.jsondb.cloud",
+        max_retries: int = 3,
+        retry_base_delay: float = 1.0,
+        retry_max_delay: float = 10.0,
+        timeout: float = 30.0,
+        headers: Optional[Dict[str, str]] = None,
+    ) -> None:
+        if not api_key:
+            raise ValueError("api_key is required")
+
+        self._project = project
+        self._http = SyncHTTPClient(
+            api_key=api_key,
+            base_url=base_url,
+            max_retries=max_retries,
+            retry_base_delay=retry_base_delay,
+            retry_max_delay=retry_max_delay,
+            timeout=timeout,
+            headers=headers,
+        )
+
+    def collection(self, name: str) -> Collection:
+        """Get a reference to a collection.
+
+        Args:
+            name: Collection name (e.g. ``"users"``, ``"posts"``).
+
+        Returns:
+            A :class:`Collection` instance bound to this client and project.
+        """
+        return Collection(name=name, project=self._project, http=self._http)
+
+    def list_collections(self) -> List[str]:
+        """List all collections in the project."""
+        data = self._http.request("GET", f"/{self._project}")
+        return cast(List[str], data.get("data", data) if isinstance(data, dict) else data)
+
+    def close(self) -> None:
+        """Close the underlying HTTP client and release resources."""
+        self._http.close()
+
+    def __enter__(self) -> "JsonDB":
+        return self
+
+    def __exit__(self, *args: Any) -> None:
+        self.close()
+
+
+class AsyncJsonDB:
+    """Asynchronous client for the jsondb.cloud API.
+
+    Usage::
+
+        from jsondb_cloud import AsyncJsonDB
+
+        db = AsyncJsonDB(api_key="jdb_sk_live_xxxx")
+        users = db.collection("users")
+
+        alice = await users.create({"name": "Alice", "email": "alice@example.com"})
+        user = await users.get(alice["_id"])
+
+    Supports use as an async context manager::
+
+        async with AsyncJsonDB(api_key="jdb_sk_live_xxxx") as db:
+            users = db.collection("users")
+            await users.create({"name": "Alice"})
+
+    Args:
+        api_key: API key (``jdb_sk_live_*`` or ``jdb_sk_test_*``).
+        project: Project name. Defaults to ``"v1"``.
+        base_url: API base URL. Defaults to ``"https://api.jsondb.cloud"``.
+        max_retries: Maximum number of retries on 429/5xx. Defaults to ``3``.
+        retry_base_delay: Base delay in seconds for exponential backoff. Defaults to ``1.0``.
+        retry_max_delay: Maximum delay in seconds for exponential backoff. Defaults to ``10.0``.
+        timeout: Request timeout in seconds. Defaults to ``30.0``.
+        headers: Optional extra headers to include with every request.
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        project: str = "v1",
+        base_url: str = "https://api.jsondb.cloud",
+        max_retries: int = 3,
+        retry_base_delay: float = 1.0,
+        retry_max_delay: float = 10.0,
+        timeout: float = 30.0,
+        headers: Optional[Dict[str, str]] = None,
+    ) -> None:
+        if not api_key:
+            raise ValueError("api_key is required")
+
+        self._project = project
+        self._http = AsyncHTTPClient(
+            api_key=api_key,
+            base_url=base_url,
+            max_retries=max_retries,
+            retry_base_delay=retry_base_delay,
+            retry_max_delay=retry_max_delay,
+            timeout=timeout,
+            headers=headers,
+        )
+
+    def collection(self, name: str) -> AsyncCollection:
+        """Get a reference to a collection.
+
+        Args:
+            name: Collection name (e.g. ``"users"``, ``"posts"``).
+
+        Returns:
+            An :class:`AsyncCollection` instance bound to this client and project.
+        """
+        return AsyncCollection(name=name, project=self._project, http=self._http)
+
+    async def list_collections(self) -> List[str]:
+        """List all collections in the project."""
+        data = await self._http.request("GET", f"/{self._project}")
+        return cast(List[str], data.get("data", data) if isinstance(data, dict) else data)
+
+    async def close(self) -> None:
+        """Close the underlying async HTTP client and release resources."""
+        await self._http.close()
+
+    async def __aenter__(self) -> "AsyncJsonDB":
+        return self
+
+    async def __aexit__(self, *args: Any) -> None:
+        await self.close()