trashdb 0.1.0__py3-none-any.whl

trashdb/__init__.py

@@ -0,0 +1,17 @@
+from .client import TrashDB
+from .errors import TrashDBAPIError
+from .types import (
+    ContainerResponse,
+    CreateContainerParams,
+    EngineInfo,
+    TrashDBOptions,
+)
+
+__all__ = [
+    "TrashDB",
+    "TrashDBAPIError",
+    "TrashDBOptions",
+    "CreateContainerParams",
+    "ContainerResponse",
+    "EngineInfo",
+]

trashdb/client.py

@@ -0,0 +1,156 @@
+from __future__ import annotations
+
+import json
+import time
+import urllib.error
+import urllib.request
+from typing import Any, Optional
+
+from .errors import RETRYABLE_STATUSES, TrashDBAPIError
+from .types import (
+    ContainerResponse,
+    CreateContainerParams,
+    EngineInfo,
+    TrashDBOptions,
+)
+
+
+def _dict_to_container(data: dict[str, Any]) -> ContainerResponse:
+    return ContainerResponse(
+        id=data["id"],
+        engine=data["engine"],
+        port=data["port"],
+        connection_string=data["connectionString"],
+        created_at=data["createdAt"],
+        ttl_minutes=data["ttlMinutes"],
+        name=data.get("name"),
+        expires_at=data.get("expiresAt"),
+    )
+
+
+def _dict_to_engine(data: dict[str, Any]) -> EngineInfo:
+    return EngineInfo(
+        id=data["id"],
+        name=data["name"],
+        max_ttl_minutes=data["maxTtlMinutes"],
+    )
+
+
+class TrashDB:
+    def __init__(self, options: TrashDBOptions) -> None:
+        self._api_key = options.api_key
+        self._max_retries = max(0, options.max_retries)
+        self._initial_backoff_ms = options.initial_backoff_ms
+        self._base_url = options.base_url.rstrip("/")
+
+    def create_container(self, params: CreateContainerParams) -> ContainerResponse:
+        body = {
+            "engine": params.engine,
+            "ttlMinutes": params.ttl_minutes,
+        }
+        if params.name is not None:
+            body["name"] = params.name
+
+        data = self._request(
+            f"{self._base_url}/containers",
+            method="POST",
+            headers={"Content-Type": "application/json", "x-api-key": self._api_key},
+            body=json.dumps(body).encode("utf-8"),
+        )
+        return _dict_to_container(data)
+
+    def get_running_containers(self) -> list[ContainerResponse]:
+        data = self._request(
+            f"{self._base_url}/containers",
+            headers={"x-api-key": self._api_key},
+        )
+        return [_dict_to_container(c) for c in data]
+
+    def destroy_container(self, container_id: str) -> bool:
+        try:
+            self._raw_request(
+                f"{self._base_url}/containers/{container_id}",
+                method="DELETE",
+                headers={"x-api-key": self._api_key},
+            )
+            return True
+        except TrashDBAPIError as exc:
+            if exc.status == 404:
+                return False
+            raise
+
+    def get_engines(self) -> list[EngineInfo]:
+        data = self._request(f"{self._base_url}/engines")
+        return [_dict_to_engine(e) for e in data]
+
+    def get_container_logs(
+        self,
+        container_id: str,
+        tail: int = 200,
+        since_seconds: Optional[int] = None,
+    ) -> str:
+        url = f"{self._base_url}/containers/{container_id}/logs?tail={tail}"
+        if since_seconds is not None:
+            url += f"&sinceSeconds={since_seconds}"
+
+        data = self._request(url, headers={"x-api-key": self._api_key})
+        return data["logs"]
+
+    # ------------------------------------------------------------------
+    # Internal helpers
+    # ------------------------------------------------------------------
+
+    def _request(
+        self,
+        url: str,
+        method: str = "GET",
+        headers: Optional[dict[str, str]] = None,
+        body: Optional[bytes] = None,
+    ) -> Any:
+        res = self._raw_request(url, method=method, headers=headers, body=body)
+        content = res.read()
+        if not content:
+            return None
+        return json.loads(content.decode("utf-8"))
+
+    def _raw_request(
+        self,
+        url: str,
+        method: str = "GET",
+        headers: Optional[dict[str, str]] = None,
+        body: Optional[bytes] = None,
+    ) -> Any:
+        max_attempts = self._max_retries + 1
+
+        for attempt in range(1, max_attempts + 1):
+            req = urllib.request.Request(url, data=body, method=method)
+            if headers:
+                for k, v in headers.items():
+                    req.add_header(k, v)
+
+            try:
+                return urllib.request.urlopen(req, timeout=30)
+
+            except urllib.error.HTTPError as exc:
+                if attempt == max_attempts or exc.code not in RETRYABLE_STATUSES:
+                    error_body = exc.read()
+                    error_data: dict[str, Any] = {}
+                    if error_body:
+                        try:
+                            error_data = json.loads(error_body.decode("utf-8"))
+                        except (json.JSONDecodeError, ValueError):
+                            pass
+                    raise TrashDBAPIError(exc.code, error_data) from exc
+
+                self._sleep(attempt)
+
+            except urllib.error.URLError as exc:
+                if attempt == max_attempts:
+                    raise TrashDBAPIError(0, {"message": str(exc.reason)}) from exc
+                self._sleep(attempt)
+
+        raise TrashDBAPIError(0, {"message": "Unreachable"})
+
+    def _sleep(self, attempt: int) -> None:
+        delay_ms = self._initial_backoff_ms * (2 ** (attempt - 1))
+        time.sleep(delay_ms / 1000)

trashdb/errors.py

@@ -0,0 +1,20 @@
+from __future__ import annotations
+
+from typing import Any
+
+
+class TrashDBAPIError(Exception):
+    status: int
+    code: int
+
+    def __init__(self, status: int, error: dict[str, Any]) -> None:
+        self.status = status
+        self.code = error.get("code", 0)
+        message = error.get("message", "Unknown error")
+        super().__init__(message)
+
+    def __str__(self) -> str:
+        return f"[{self.status}] code={self.code}: {self.args[0]}"
+
+
+RETRYABLE_STATUSES: set[int] = {502, 503, 504}

trashdb/types.py

@@ -0,0 +1,47 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Callable, Optional
+
+
+@dataclass
+class TrashDBOptions:
+    api_key: str
+    base_url: str = "https://api.trashdb.dev/api/v1"
+    max_retries: int = 3
+    initial_backoff_ms: int = 500
+    http_client: Optional[Callable[..., object]] = None
+
+
+@dataclass
+class CreateContainerParams:
+    engine: str
+    ttl_minutes: int = 5
+    name: Optional[str] = None
+
+
+@dataclass
+class ContainerResponse:
+    id: str
+    engine: str
+    port: int
+    connection_string: str
+    created_at: str
+    ttl_minutes: int
+    name: Optional[str] = None
+    expires_at: Optional[str] = None
+
+
+@dataclass
+class EngineInfo:
+    id: str
+    name: str
+    max_ttl_minutes: int
+
+
+@dataclass
+class ContainerLogs:
+    logs: str
+
+
+ErrorInfo = dict  # {"code": int, "message": str}

trashdb-0.1.0.dist-info/METADATA

@@ -0,0 +1,43 @@
+Metadata-Version: 2.4
+Name: trashdb
+Version: 0.1.0
+Summary: Official Python SDK for TrashDB — ephemeral database containers on demand
+Author-email: trashdb <hello@trashdb.dev>
+License-Expression: MIT
+Keywords: trashdb,ephemeral,database,docker,postgres,mongodb,redis,chromadb,qdrant
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# TrashDB Python SDK
+
+[![PyPI version](https://img.shields.io/pypi/v/trashdb)](https://pypi.org/project/trashdb/)
+[![Python versions](https://img.shields.io/pypi/pyversions/trashdb)](https://pypi.org/project/trashdb/)
+[![License](https://img.shields.io/pypi/l/trashdb)](LICENSE)
+
+Official Python SDK for [TrashDB](https://trashdb.dev) — ephemeral database containers on demand.
+
+```python
+from trashdb import TrashDB, TrashDBOptions, CreateContainerParams
+
+db = TrashDB(TrashDBOptions(api_key="trdb_your_key_here"))
+container = db.create_container(CreateContainerParams(engine="postgres", ttl_minutes=5))
+print(container.connection_string)
+```
+
+## Installation
+
+```bash
+pip install trashdb
+```
+
+## Documentation
+
+See https://trashdb.dev/docs

trashdb-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+trashdb/__init__.py,sha256=Z4H8nweOhynOHSIPnGEQSOmSzEJ1vV5xRDu0ipj7_eA,320
+trashdb/client.py,sha256=hbpcaCRTMLyojL-P2IP-P2fETXl_kywTHAQNnPk40oo,5079
+trashdb/errors.py,sha256=dVBr2g8JnwiWqtWr-O_9nsI_BL1c9Y2_SezmLwmMriY,501
+trashdb/types.py,sha256=7Izoxp52ApdajU3mLFVPh7t-yQybis64Zn7TTTLKRhc,847
+trashdb-0.1.0.dist-info/METADATA,sha256=AYgowdEM0mG_E5DZEP2_MjH1xYKeMXeQt7hqbPXy8HE,1482
+trashdb-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+trashdb-0.1.0.dist-info/top_level.txt,sha256=MpXvNcOBR7HCJM2BdEiNF1cM6BLPaJIbuARBWkvpQj0,8
+trashdb-0.1.0.dist-info/RECORD,,

trashdb-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

trashdb-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+trashdb