trashdb 0.1.0__tar.gz

trashdb-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,25 @@
+# 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/pyproject.toml

@@ -0,0 +1,38 @@
+[build-system]
+requires = ["setuptools>=70", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "trashdb"
+version = "0.1.0"
+description = "Official Python SDK for TrashDB — ephemeral database containers on demand"
+readme = "README.md"
+license = "MIT"
+authors = [
+    { name = "trashdb", email = "hello@trashdb.dev" },
+]
+keywords = [
+    "trashdb",
+    "ephemeral",
+    "database",
+    "docker",
+    "postgres",
+    "mongodb",
+    "redis",
+    "chromadb",
+    "qdrant",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+]
+requires-python = ">=3.9"
+
+[tool.setuptools.packages.find]
+where = ["src"]

trashdb-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

trashdb-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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/src/trashdb.egg-info/PKG-INFO

@@ -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/src/trashdb.egg-info/SOURCES.txt

@@ -0,0 +1,11 @@
+README.md
+pyproject.toml
+src/trashdb/__init__.py
+src/trashdb/client.py
+src/trashdb/errors.py
+src/trashdb/types.py
+src/trashdb.egg-info/PKG-INFO
+src/trashdb.egg-info/SOURCES.txt
+src/trashdb.egg-info/dependency_links.txt
+src/trashdb.egg-info/top_level.txt
+tests/test_client.py

trashdb-0.1.0/src/trashdb.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

trashdb-0.1.0/src/trashdb.egg-info/top_level.txt

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

trashdb-0.1.0/tests/test_client.py

@@ -0,0 +1,105 @@
+from __future__ import annotations
+
+import os
+from typing import Generator
+
+import pytest
+
+from trashdb import (
+    ContainerResponse,
+    CreateContainerParams,
+    EngineInfo,
+    TrashDB,
+    TrashDBAPIError,
+    TrashDBOptions,
+)
+
+
+@pytest.fixture
+def api_key() -> str:
+    key = os.environ.get("TRASHDB_API_KEY")
+    if not key:
+        pytest.skip("TRASHDB_API_KEY not set — skipping integration tests")
+    return key
+
+
+@pytest.fixture
+def client(api_key: str) -> Generator[TrashDB, None, None]:
+    db = TrashDB(TrashDBOptions(api_key=api_key))
+    yield db
+    # No explicit close needed — urllib has no persistent connection
+
+
+class TestEngines:
+    def test_list_engines(self, client: TrashDB) -> None:
+        engines = client.get_engines()
+        assert isinstance(engines, list)
+        assert len(engines) > 0
+
+        engine = engines[0]
+        assert isinstance(engine, EngineInfo)
+        assert engine.id
+        assert engine.name
+        assert engine.max_ttl_minutes > 0
+
+
+class TestContainers:
+    @pytest.fixture
+    def container(self, client: TrashDB) -> Generator[ContainerResponse, None, None]:
+        params = CreateContainerParams(engine="postgres", ttl_minutes=3)
+        c = client.create_container(params)
+        yield c
+        client.destroy_container(c.id)
+
+    def test_create_and_destroy(self, client: TrashDB) -> None:
+        params = CreateContainerParams(engine="postgres", ttl_minutes=3)
+        c = client.create_container(params)
+        assert isinstance(c, ContainerResponse)
+        assert c.id
+        assert c.engine == "postgres"
+        assert c.port > 0
+        assert c.connection_string
+        assert c.ttl_minutes == 3
+
+        destroyed = client.destroy_container(c.id)
+        assert destroyed is True
+
+    def test_create_with_name(self, client: TrashDB) -> None:
+        params = CreateContainerParams(
+            engine="postgres", ttl_minutes=3, name="my-integration-test"
+        )
+        c = client.create_container(params)
+        assert c.name == "my-integration-test"
+        client.destroy_container(c.id)
+
+    def test_get_running_containers(
+        self, client: TrashDB, container: ContainerResponse
+    ) -> None:
+        containers = client.get_running_containers()
+        ids = [c.id for c in containers]
+        assert container.id in ids
+
+    def test_destroy_nonexistent(self, client: TrashDB) -> None:
+        result = client.destroy_container("nonexistent-id")
+        assert result is False
+
+    def test_unauthorized(self) -> None:
+        bad_client = TrashDB(TrashDBOptions(api_key="bad-key"))
+        with pytest.raises(TrashDBAPIError) as exc_info:
+            bad_client.create_container(CreateContainerParams(engine="postgres"))
+        assert exc_info.value.status == 401
+        assert exc_info.value.code == 4001
+
+    def test_unsupported_engine(self, client: TrashDB) -> None:
+        with pytest.raises(TrashDBAPIError) as exc_info:
+            client.create_container(CreateContainerParams(engine="nonexistent"))
+        assert exc_info.value.code == 1001
+
+    def test_container_logs(self, client: TrashDB) -> None:
+        params = CreateContainerParams(engine="postgres", ttl_minutes=3)
+        c = client.create_container(params)
+        try:
+            logs = client.get_container_logs(c.id)
+            assert isinstance(logs, str)
+        finally:
+            client.destroy_container(c.id)