terminusdb-async 0.1.0__tar.gz

terminusdb_async-0.1.0/PKG-INFO

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

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

@@ -0,0 +1,30 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "terminusdb-async"
+version = "0.1.0"
+description = "Small native async HTTP client for TerminusDB"
+requires-python = ">=3.11"
+readme = "README.md"
+dependencies = [
+  "httpx>=0.27,<1",
+]
+
+[project.urls]
+Source = "https://gitlab.com/ed-tech6370840/terminusdb-async"
+Issues = "https://gitlab.com/ed-tech6370840/terminusdb-async/-/issues"
+
+[dependency-groups]
+dev = [
+  "pytest>=8",
+  "pytest-asyncio>=0.23",
+]
+
+[tool.uv]
+package = true
+trusted-publishing = "always"
+
+[tool.setuptools.packages.find]
+where = ["src"]

terminusdb_async-0.1.0/setup.cfg

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

terminusdb_async-0.1.0/src/terminusdb_async/__init__.py

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

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

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

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

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

@@ -0,0 +1 @@
+

terminusdb_async-0.1.0/src/terminusdb_async.egg-info/requires.txt

@@ -0,0 +1 @@
+httpx<1,>=0.27

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

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

terminusdb_async-0.1.0/tests/test_async_client.py

@@ -0,0 +1,46 @@
+import json
+
+import httpx
+import pytest
+
+from terminusdb_async import AsyncTerminusClient
+
+
+@pytest.mark.asyncio
+async def test_get_document_and_branch_path():
+    async def handler(request: httpx.Request) -> httpx.Response:
+        assert request.url.path == "/api/document/admin/edtech/local/branch/main"
+        assert request.url.params["id"] == "Discipline/M1"
+        return httpx.Response(200, json={"@id": "Discipline/M1", "@type": "Discipline", "name": "Math"})
+
+    transport = httpx.MockTransport(handler)
+    http = httpx.AsyncClient(base_url="http://test", transport=transport)
+    client = AsyncTerminusClient("http://test", organization="admin", database="edtech", http_client=http)
+    doc = await client.get_document("Discipline/M1")
+    assert doc["name"] == "Math"
+    await http.aclose()
+
+
+@pytest.mark.asyncio
+async def test_migration_payload():
+    seen = {}
+
+    async def handler(request: httpx.Request) -> httpx.Response:
+        seen["path"] = request.url.path
+        seen["params"] = dict(request.url.params)
+        seen["body"] = json.loads(request.content)
+        return httpx.Response(200, json={"@type": "api:MigrationResponse", "api:status": "api:success"})
+
+    transport = httpx.MockTransport(handler)
+    http = httpx.AsyncClient(base_url="http://test", transport=transport)
+    client = AsyncTerminusClient("http://test", organization="admin", database="edtech", http_client=http)
+    await client.migrate(
+        [{"@type": "ExpandEnum", "enum": "Level", "values": ["master"]}],
+        author="bot",
+        message="migrate",
+        dry_run=True,
+    )
+    assert seen["path"] == "/api/migration/admin/edtech/local/branch/main"
+    assert seen["params"]["dry_run"] == "true"
+    assert seen["body"]["author"] == "bot"
+    await http.aclose()