terminusdb-async 0.1.0__py3-none-any.whl

terminusdb_async/__init__.py

@@ -0,0 +1,4 @@
+from .client import AsyncTerminusClient
+from .errors import TerminusDBError
+
+__all__ = ["AsyncTerminusClient", "TerminusDBError"]

terminusdb_async/client.py

@@ -0,0 +1,284 @@
+from __future__ import annotations
+
+import json
+from collections.abc import Iterable, Mapping, Sequence
+from typing import Any
+from urllib.parse import quote
+
+import httpx
+
+from .errors import TerminusDBError
+
+Json = dict[str, Any]
+
+
+class AsyncTerminusClient:
+    """Thin async wrapper around the TerminusDB HTTP API.
+
+    The client owns an ``httpx.AsyncClient`` unless one is injected. Resource paths
+    target a branch by default: ``<org>/<db>/local/branch/<branch>``.
+    """
+
+    def __init__(
+        self,
+        base_url: str,
+        *,
+        organization: str,
+        database: str,
+        branch: str = "main",
+        username: str | None = None,
+        password: str | None = None,
+        token: str | None = None,
+        timeout: float | httpx.Timeout = 30.0,
+        http_client: httpx.AsyncClient | None = None,
+    ) -> None:
+        if token and username:
+            raise ValueError("Use token auth or basic auth, not both")
+        self.base_url = base_url.rstrip("/")
+        self.organization = organization
+        self.database = database
+        self.branch = branch
+        self._owns_client = http_client is None
+
+        headers: dict[str, str] = {"Accept": "application/json"}
+        auth: httpx.Auth | None = None
+        if token:
+            headers["Authorization"] = f"Token {token}"
+        elif username is not None:
+            auth = httpx.BasicAuth(username, password or "")
+
+        self.http = http_client or httpx.AsyncClient(
+            base_url=self.base_url,
+            headers=headers,
+            auth=auth,
+            timeout=timeout,
+        )
+
+    async def __aenter__(self) -> "AsyncTerminusClient":
+        return self
+
+    async def __aexit__(self, exc_type, exc, tb) -> None:
+        await self.aclose()
+
+    async def aclose(self) -> None:
+        if self._owns_client:
+            await self.http.aclose()
+
+    @property
+    def database_path(self) -> str:
+        return f"{quote(self.organization, safe='')}/{quote(self.database, safe='')}"
+
+    @property
+    def resource_path(self) -> str:
+        return f"{self.database_path}/local/branch/{quote(self.branch, safe='')}"
+
+    async def _request(self, method: str, path: str, **kwargs: Any) -> httpx.Response:
+        response = await self.http.request(method, path, **kwargs)
+        if response.is_error:
+            try:
+                body: object = response.json()
+            except Exception:
+                body = response.text
+            raise TerminusDBError(
+                f"TerminusDB {method} {path} failed with HTTP {response.status_code}",
+                status_code=response.status_code,
+                body=body,
+            )
+        return response
+
+    @staticmethod
+    def _decode(response: httpx.Response) -> Any:
+        if not response.content:
+            return None
+        try:
+            return response.json()
+        except json.JSONDecodeError:
+            docs: list[Any] = []
+            for line in response.text.splitlines():
+                line = line.strip()
+                if line:
+                    docs.append(json.loads(line))
+            return docs
+
+    async def ok(self) -> Any:
+        return self._decode(await self._request("GET", "/api/ok"))
+
+    async def info(self) -> Any:
+        return self._decode(await self._request("GET", "/api/info"))
+
+    async def get_document(
+        self,
+        document_id: str,
+        *,
+        graph_type: str = "instance",
+        raw_json: bool = False,
+    ) -> Json:
+        params = {"id": document_id, "graph_type": graph_type, "raw_json": _bool(raw_json)}
+        data = self._decode(await self._request("GET", f"/api/document/{self.resource_path}", params=params))
+        if isinstance(data, list):
+            if len(data) != 1:
+                raise TerminusDBError(f"Expected one document, got {len(data)}", body=data)
+            return data[0]
+        if not isinstance(data, dict):
+            raise TerminusDBError("Unexpected document response", body=data)
+        return data
+
+    async def get_documents(
+        self,
+        *,
+        document_type: str | None = None,
+        ids: Sequence[str] | None = None,
+        graph_type: str = "instance",
+        count: int | None = None,
+        skip: int | None = None,
+    ) -> list[Json]:
+        params: dict[str, Any] = {"graph_type": graph_type}
+        if document_type:
+            params["type"] = document_type
+        if ids:
+            params["ids"] = json.dumps(list(ids))
+        if count is not None:
+            params["count"] = count
+        if skip is not None:
+            params["skip"] = skip
+        data = self._decode(await self._request("GET", f"/api/document/{self.resource_path}", params=params))
+        if data is None:
+            return []
+        if isinstance(data, dict):
+            return [data]
+        return list(data)
+
+    async def query_documents(
+        self,
+        query: Mapping[str, Any],
+        *,
+        document_type: str | None = None,
+        count: int | None = None,
+        skip: int | None = None,
+        graph_type: str = "instance",
+    ) -> list[Json]:
+        payload: dict[str, Any] = {"query": dict(query), "graph_type": graph_type}
+        if document_type:
+            payload["@rdf:type"] = document_type
+        if count is not None:
+            payload["count"] = count
+        if skip is not None:
+            payload["skip"] = skip
+        response = await self._request(
+            "POST",
+            f"/api/document/{self.resource_path}",
+            headers={"X-HTTP-Method-Override": "GET"},
+            json=payload,
+        )
+        data = self._decode(response)
+        if data is None:
+            return []
+        if isinstance(data, dict):
+            return [data]
+        return list(data)
+
+    async def insert_documents(
+        self,
+        documents: Mapping[str, Any] | Sequence[Mapping[str, Any]],
+        *,
+        author: str,
+        message: str,
+        graph_type: str = "instance",
+        overwrite: bool = False,
+        full_replace: bool = False,
+        raw_json: bool = False,
+        require_migration: bool = False,
+        allow_destructive_migration: bool = False,
+    ) -> list[str]:
+        params = {
+            "author": author,
+            "message": message,
+            "graph_type": graph_type,
+            "overwrite": _bool(overwrite),
+            "full_replace": _bool(full_replace),
+            "raw_json": _bool(raw_json),
+            "require_migration": _bool(require_migration),
+            "allow_destructive_migration": _bool(allow_destructive_migration),
+        }
+        payload: Any = dict(documents) if isinstance(documents, Mapping) else [dict(d) for d in documents]
+        data = self._decode(await self._request("POST", f"/api/document/{self.resource_path}", params=params, json=payload))
+        return list(data or [])
+
+    async def replace_documents(
+        self,
+        documents: Mapping[str, Any] | Sequence[Mapping[str, Any]],
+        *,
+        author: str,
+        message: str,
+        graph_type: str = "instance",
+        create: bool = False,
+        require_migration: bool = False,
+        allow_destructive_migration: bool = False,
+    ) -> Any:
+        params = {
+            "author": author,
+            "message": message,
+            "graph_type": graph_type,
+            "create": _bool(create),
+            "require_migration": _bool(require_migration),
+            "allow_destructive_migration": _bool(allow_destructive_migration),
+        }
+        payload: Any = dict(documents) if isinstance(documents, Mapping) else [dict(d) for d in documents]
+        return self._decode(await self._request("PUT", f"/api/document/{self.resource_path}", params=params, json=payload))
+
+    async def delete_documents(
+        self,
+        ids: str | Sequence[str],
+        *,
+        author: str,
+        message: str,
+        graph_type: str = "instance",
+    ) -> Any:
+        params = {"author": author, "message": message, "graph_type": graph_type}
+        if isinstance(ids, str):
+            params["id"] = ids
+            response = await self._request("DELETE", f"/api/document/{self.resource_path}", params=params)
+        else:
+            response = await self._request("DELETE", f"/api/document/{self.resource_path}", params=params, json=list(ids))
+        return self._decode(response)
+
+    async def get_schema_documents(self) -> list[Json]:
+        return await self.get_documents(graph_type="schema")
+
+    async def bootstrap_schema(self, documents: Sequence[Mapping[str, Any]], *, author: str, message: str) -> list[str]:
+        return await self.insert_documents(
+            documents,
+            author=author,
+            message=message,
+            graph_type="schema",
+            full_replace=True,
+        )
+
+    async def insert_schema_documents(self, documents: Sequence[Mapping[str, Any]], *, author: str, message: str) -> list[str]:
+        return await self.insert_documents(documents, author=author, message=message, graph_type="schema")
+
+    async def migrate(
+        self,
+        operations: Sequence[Mapping[str, Any]],
+        *,
+        author: str,
+        message: str,
+        dry_run: bool = False,
+        verbose: bool = False,
+    ) -> Any:
+        payload = {"author": author, "message": message, "operations": [dict(op) for op in operations]}
+        params = {"dry_run": _bool(dry_run), "verbose": _bool(verbose)}
+        response = await self._request("POST", f"/api/migration/{self.resource_path}", params=params, json=payload)
+        return self._decode(response)
+
+    async def graphql(self, query: str, variables: Mapping[str, Any] | None = None) -> Any:
+        response = await self._request(
+            "POST",
+            f"/api/graphql/{self.database_path}",
+            json={"query": query, "variables": dict(variables or {})},
+        )
+        return self._decode(response)
+
+
+def _bool(value: bool) -> str:
+    return "true" if value else "false"

terminusdb_async/errors.py

@@ -0,0 +1,5 @@
+class TerminusDBError(RuntimeError):
+    def __init__(self, message: str, *, status_code: int | None = None, body: object = None):
+        super().__init__(message)
+        self.status_code = status_code
+        self.body = body

terminusdb_async-0.1.0.dist-info/METADATA

@@ -0,0 +1,35 @@
+Metadata-Version: 2.4
+Name: terminusdb-async
+Version: 0.1.0
+Summary: Small native async HTTP client for TerminusDB
+Project-URL: Source, https://gitlab.com/ed-tech6370840/terminusdb-async
+Project-URL: Issues, https://gitlab.com/ed-tech6370840/terminusdb-async/-/issues
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: httpx<1,>=0.27
+
+# terminusdb-async
+
+Native async TerminusDB HTTP client based on `httpx.AsyncClient`.
+
+## Development
+
+```bash
+uv sync --group dev
+uv run pytest
+uv build --no-sources
+```
+
+Dependencies are managed in `pyproject.toml` with uv.
+
+## Release
+
+PyPI publication uses GitLab OIDC Trusted Publishing. A version tag matching
+`project.version` (for example `v0.1.0`) triggers `uv build` and `uv publish`.
+
+PyPI publisher:
+
+- Namespace: `ed-tech6370840`
+- Repository: `terminusdb-async`
+- Top-level pipeline: `.gitlab-ci.yml`
+- Environment: `pypi`

terminusdb_async-0.1.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+terminusdb_async/__init__.py,sha256=l-LCsIa1iW9Jtwf91RK2EjN8AYeOogZm1w1A8QRSkkc,130
+terminusdb_async/client.py,sha256=rvYFWyLwr7ft74Lu2lpnKSAUKNK6C019Gyvp4ZBi9OM,9969
+terminusdb_async/errors.py,sha256=0forVNBC0XwLouXG53dd7p-NwyRyy0Eqz_hX_yd6RJI,229
+terminusdb_async-0.1.0.dist-info/METADATA,sha256=0MRUv21rl3q0Dgz3eOJ0xWtUtfVnGc4il1STIVUI3-A,900
+terminusdb_async-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+terminusdb_async-0.1.0.dist-info/top_level.txt,sha256=m-WwQInYYXW4LnW-9jjA_gYu82SSdymLQkxht341XHg,17
+terminusdb_async-0.1.0.dist-info/RECORD,,

terminusdb_async-0.1.0.dist-info/WHEEL

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

terminusdb_async-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+terminusdb_async