dataceen-client 0.0.1__py3-none-any.whl

dataceen_client/__init__.py

@@ -0,0 +1,48 @@
+"""dataceen-client — Python port of the Dataceen GraphQL/subscription client.
+
+Public surface (phase 1):
+    - DataceenConfig, DataceenClientOptions, load_config_from_env
+    - DataceenClient
+    - DataceenError
+    - Result types: FindResult, SearchResult, MutationResult, …
+    - Runtime helpers via `dataceen_client.runtime`
+"""
+from .config import (
+    DataceenClientOptions,
+    DataceenConfig,
+    Logger,
+    console_logger,
+    load_config_from_env,
+    silent_logger,
+)
+from .dataceen_client import DataceenClient
+from .errors import DataceenError
+from .types import (
+    FindByIdResult,
+    FindResult,
+    MutationResult,
+    QueryResult,
+    RequestResult,
+    SearchResult,
+    SingleMutationResult,
+)
+
+__all__ = [
+    "DataceenClient",
+    "DataceenClientOptions",
+    "DataceenConfig",
+    "DataceenError",
+    "FindByIdResult",
+    "FindResult",
+    "Logger",
+    "MutationResult",
+    "QueryResult",
+    "RequestResult",
+    "SearchResult",
+    "SingleMutationResult",
+    "console_logger",
+    "load_config_from_env",
+    "silent_logger",
+]
+
+__version__ = "0.0.1"

dataceen_client/config.py

@@ -0,0 +1,105 @@
+"""Configuration types and helpers.
+
+Mirrors `DataceenClientTs/src/config.ts`.
+"""
+from __future__ import annotations
+
+import logging
+import os
+from dataclasses import dataclass
+from typing import Protocol
+
+
+@dataclass(frozen=True)
+class DataceenConfig:
+    """Configuration for a DataceenClient instance.
+
+    Mirrors values under e.g. "AllClient" in the C# example's appsettings.json.
+    """
+
+    tenant_id: str
+    client_id: str
+    client_secret: str
+
+    domain: str
+    model: str
+    scope: str
+
+    api_url: str
+    api_path: str
+    api_scope: str
+
+    subscription_url: str
+    subscription_scope: str
+
+
+class Logger(Protocol):
+    def log(self, level: str, message: str, error: BaseException | None = None) -> None: ...
+
+
+class _StdlibLogger:
+    """Default logger using stdlib `logging` with prefix `[dataceen-client]`."""
+
+    def __init__(self, name: str = "dataceen-client") -> None:
+        self._log = logging.getLogger(name)
+
+    def log(self, level: str, message: str, error: BaseException | None = None) -> None:
+        lvl = {
+            "debug": logging.DEBUG,
+            "info": logging.INFO,
+            "warn": logging.WARNING,
+            "error": logging.ERROR,
+        }.get(level, logging.INFO)
+        if error is not None:
+            self._log.log(lvl, "%s", message, exc_info=error)
+        else:
+            self._log.log(lvl, "%s", message)
+
+
+class _SilentLogger:
+    def log(self, level: str, message: str, error: BaseException | None = None) -> None:
+        pass
+
+
+console_logger: Logger = _StdlibLogger()
+silent_logger: Logger = _SilentLogger()
+
+
+@dataclass(frozen=True)
+class DataceenClientOptions:
+    logger: Logger | None = None
+    http_timeout_s: float = 60.0
+    max_transient_retries: int = 3
+    transient_retry_base_s: float = 0.2
+    slow_handler_threshold_ms: int = 500
+
+
+def load_config_from_env(
+    *, prefix: str = "DATACEEN_", config: dict[str, str] | None = None
+) -> DataceenConfig:
+    """Load `DataceenConfig` from environment variables (or a passed-in dict).
+
+    Variable names mirror `.env.example`: `DATACEEN_TENANT_ID`, `DATACEEN_API_URL`, …
+    """
+    src = config if config is not None else os.environ
+
+    def get(key: str) -> str:
+        full = f"{prefix}{key}"
+        value = src.get(full)
+        if value is None or value == "":
+            raise ValueError(f"Missing required env var {full}")
+        return value
+
+    return DataceenConfig(
+        tenant_id=get("TENANT_ID"),
+        client_id=get("CLIENT_ID"),
+        client_secret=get("CLIENT_SECRET"),
+        domain=get("DOMAIN"),
+        model=get("MODEL"),
+        scope=get("SCOPE"),
+        api_url=get("API_URL"),
+        api_path=get("API_PATH"),
+        api_scope=get("API_SCOPE"),
+        subscription_url=get("SUBSCRIPTION_URL"),
+        subscription_scope=get("SUBSCRIPTION_SCOPE"),
+    )

dataceen_client/dataceen_client.py

@@ -0,0 +1,230 @@
+"""DataceenClient — entry point for GraphQL queries and mutations.
+
+Mirrors `DataceenClientTs/src/client/dataceen-client.ts`. Subscriptions are
+deferred to phase 4 — the surface here is GraphQL only.
+"""
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from .config import (
+    DataceenClientOptions,
+    DataceenConfig,
+    Logger,
+    console_logger,
+)
+from .errors import DataceenError
+from .http_transport import GqlRequest, HttpTransport, HttpTransportOptions
+from .token_provider import TokenProvider, TokenProviderConfig, TokenProviderLike
+
+if False:  # TYPE_CHECKING — avoid hard import (subscriptions are optional)
+    from .subscriptions import Subscription
+
+
+class DataceenClient:
+    """Async low-level client. Codegen (phase 3) will layer typed per-entity
+    methods on top of this surface.
+
+    Use as an async context manager so the underlying httpx.AsyncClient is
+    closed cleanly:
+
+        async with DataceenClient(config) as client:
+            await client.execute_query(...)
+    """
+
+    def __init__(
+        self,
+        config: DataceenConfig,
+        options: DataceenClientOptions | None = None,
+        *,
+        token_provider: TokenProviderLike | None = None,
+        transport: HttpTransport | None = None,
+    ) -> None:
+        opts = options or DataceenClientOptions()
+        self.config = config
+        self._logger: Logger = opts.logger or console_logger
+        self._slow_handler_threshold_ms = opts.slow_handler_threshold_ms
+
+        if token_provider is None:
+            token_provider = TokenProvider(
+                TokenProviderConfig(
+                    tenant_id=config.tenant_id,
+                    client_id=config.client_id,
+                    client_secret=config.client_secret,
+                )
+            )
+        self._token_provider = token_provider
+
+        if transport is None:
+            api_path = (
+                f"{config.api_path}/{config.domain}/{config.model}/{config.scope}"
+            )
+            transport = HttpTransport(
+                HttpTransportOptions(
+                    api_url=config.api_url,
+                    api_path=api_path,
+                    api_scope=config.api_scope,
+                    token_provider=token_provider,
+                    logger=self._logger,
+                    http_timeout_s=opts.http_timeout_s,
+                    max_transient_retries=opts.max_transient_retries,
+                    transient_retry_base_s=opts.transient_retry_base_s,
+                )
+            )
+        self._transport = transport
+        self._subscription_counter = 0
+        self._slow_handler_threshold_ms_value = opts.slow_handler_threshold_ms
+
+    def create_subscription(
+        self,
+        *,
+        topics: list[str],
+        baseload_topics: list[str] | None = None,
+        ids: list[str] | None = None,
+        start_mode: str = "POSITION_BEGINNING",
+        position: str = "",
+        include_delta: bool = False,
+        include_complete: bool = False,
+        baseload_continue_object_type: str = "",
+        position_before_baseload: str = "",
+        domain: str | None = None,
+        model: str | None = None,
+        scope: str | None = None,
+    ) -> "Subscription":
+        """Create a Subscription. Fills in domain/model/scope from config when omitted."""
+        from .subscriptions import Subscription, SubscriptionRequest
+
+        self._subscription_counter += 1
+        request = SubscriptionRequest(
+            domain=domain or self.config.domain,
+            model=model or self.config.model,
+            scope=scope or self.config.scope,
+            topics=list(topics),
+            baseload_topics=list(baseload_topics or []),
+            ids=list(ids or []),
+            start_mode=start_mode,  # type: ignore[arg-type]
+            position=position,
+            include_delta=include_delta,
+            include_complete=include_complete,
+            baseload_continue_object_type=baseload_continue_object_type,
+            position_before_baseload=position_before_baseload,
+        )
+        return Subscription(f"sub-{self._subscription_counter}", request)
+
+    async def subscribe(
+        self,
+        subscription: "Subscription",
+        **overrides: Any,
+    ) -> None:
+        """Open the gRPC stream and dispatch events.
+
+        Returns when the subscription is cancelled or the stream closes.
+        Raises if reconnects are exhausted.
+        """
+        from .subscriptions import (
+            SubscriptionManagerOptions,
+            run_subscription,
+        )
+
+        opts = SubscriptionManagerOptions(
+            subscription_url=self.config.subscription_url,
+            subscription_scope=self.config.subscription_scope,
+            token_provider=self._token_provider,
+            logger=self._logger,
+            slow_handler_threshold_ms=self._slow_handler_threshold_ms_value,
+            **overrides,
+        )
+        await run_subscription(subscription, opts)
+
+    @property
+    def transport(self) -> HttpTransport:
+        return self._transport
+
+    @property
+    def token_provider(self) -> TokenProviderLike:
+        return self._token_provider
+
+    async def __aenter__(self) -> "DataceenClient":
+        return self
+
+    async def __aexit__(self, exc_type, exc, tb) -> None:
+        await self.aclose()
+
+    async def aclose(self) -> None:
+        await self._transport.aclose()
+
+    async def execute_query(
+        self,
+        operation_name: str,
+        query: str,
+        *,
+        retry_on_transient: bool = True,
+    ) -> Any:
+        """Execute a GraphQL query. Default: retries on transient errors."""
+        req = GqlRequest(operation_name=operation_name, query=query)
+        text = await self._transport.post_graphql(req, retry_on_transient)
+        return _parse_graphql_response(text, req)
+
+    async def execute_mutation(
+        self,
+        operation_name: str,
+        query: str,
+        *,
+        retry_on_transient: bool = False,
+    ) -> Any:
+        """Execute a GraphQL mutation. Default: NO retry (not idempotent)."""
+        req = GqlRequest(operation_name=operation_name, query=query)
+        text = await self._transport.post_graphql(req, retry_on_transient)
+        return _parse_graphql_response(text, req)
+
+
+def _parse_graphql_response(text: str, req: GqlRequest) -> Any:
+    """Envelope-parse a GraphQL response; throw DataceenError on any failure."""
+    try:
+        envelope = json.loads(text)
+    except json.JSONDecodeError as ex:
+        raise DataceenError(
+            f"Failed to parse response as JSON: {ex}. Raw: {text[:500]}",
+            -1,
+            req.query,
+            cause=ex,
+        ) from ex
+
+    if not isinstance(envelope, dict):
+        raise DataceenError(
+            f"Response root is not a JSON object. Raw: {text[:500]}",
+            -1,
+            req.query,
+        )
+
+    errors = envelope.get("errors")
+    if errors:
+        messages = "; ".join(
+            e.get("message", "?") if isinstance(e, dict) else str(e) for e in errors
+        )
+        raise DataceenError(f"GraphQL errors: {messages}", -1, req.query)
+
+    data = envelope.get("data")
+    if not isinstance(data, dict):
+        raise DataceenError(
+            f"Response does not contain a `data` object. Raw: {text[:500]}",
+            -1,
+            req.query,
+        )
+
+    payload = data.get(req.operation_name)
+    if payload is None:
+        raise DataceenError(
+            f"Response does not contain data.{req.operation_name}. Raw: {text[:500]}",
+            -1,
+            req.query,
+        )
+
+    if isinstance(payload, dict):
+        code = payload.get("ResponseCode")
+        if code is not None and code != 0:
+            message = payload.get("Message") or f"ResponseCode={code}"
+            raise DataceenError(message, code, req.query)
+
+    return payload

dataceen_client/errors.py

@@ -0,0 +1,36 @@
+"""DataceenError — single error type for the whole client pipeline.
+
+Mirrors C# `DataceenException` (HResult/SourceQuery) and TS `DataceenError`.
+"""
+from __future__ import annotations
+
+
+class DataceenError(Exception):
+    """Raised for any failure inside the Dataceen client pipeline.
+
+    Covers HTTP non-success responses, GraphQL errors, server-side
+    `ResponseCode != 0`, JSON parse failures, and transport errors that
+    exhausted retries.
+
+    `response_code` is the server-side ResponseCode if available, the negated
+    HTTP status as a fallback, or -1 for client-side failures.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        response_code: int,
+        source_query: str | None = None,
+        cause: BaseException | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.response_code = response_code
+        self.source_query = source_query
+        if cause is not None:
+            self.__cause__ = cause
+
+    def __repr__(self) -> str:
+        return (
+            f"DataceenError(response_code={self.response_code}, "
+            f"message={self.args[0]!r})"
+        )

dataceen_client/http_transport.py

@@ -0,0 +1,137 @@
+"""HttpTransport — POST GraphQL with 401-refresh + transient retry.
+
+Mirrors `DataceenClientTs/src/client/http-transport.ts`.
+"""
+from __future__ import annotations
+
+import asyncio
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Awaitable, Callable
+
+import httpx
+
+from .config import Logger, console_logger
+from .errors import DataceenError
+
+if TYPE_CHECKING:
+    from .token_provider import TokenProviderLike
+
+
+@dataclass(frozen=True)
+class GqlRequest:
+    operation_name: str
+    query: str
+
+    def to_body(self) -> dict[str, str]:
+        # GraphQL HTTP wire format uses `operationName`, not `operation_name`.
+        return {"operationName": self.operation_name, "query": self.query}
+
+
+@dataclass
+class HttpTransportOptions:
+    api_url: str
+    api_path: str  # full path including domain/model/scope suffix
+    api_scope: str
+    token_provider: "TokenProviderLike"
+    logger: Logger = console_logger
+    http_timeout_s: float = 60.0
+    max_transient_retries: int = 3
+    transient_retry_base_s: float = 0.2
+
+    # Allows tests to inject a fake httpx.AsyncClient. Default factory creates
+    # one with the configured timeout.
+    client_factory: Callable[[], httpx.AsyncClient] | None = None
+
+
+class HttpTransport:
+    """Owns the HTTP client and the resilience policy for GraphQL POSTs."""
+
+    def __init__(self, opts: HttpTransportOptions) -> None:
+        self._opts = opts
+        self._endpoint = f"{opts.api_url}{opts.api_path}"
+        if opts.client_factory is not None:
+            self._client = opts.client_factory()
+        else:
+            self._client = httpx.AsyncClient(timeout=opts.http_timeout_s)
+
+    async def aclose(self) -> None:
+        await self._client.aclose()
+
+    async def post_graphql(self, req: GqlRequest, retry_on_transient: bool) -> str:
+        """POST the GraphQL request and return the raw response body text."""
+        body = req.to_body()
+        max_transient = self._opts.max_transient_retries if retry_on_transient else 0
+        transient_attempt = 0
+        tried_auth_refresh = False
+        delay_s = self._opts.transient_retry_base_s
+
+        while True:
+            token = await self._opts.token_provider.get_access_token(
+                [self._opts.api_scope], tried_auth_refresh
+            )
+
+            try:
+                response = await self._client.post(
+                    self._endpoint,
+                    json=body,
+                    headers={
+                        "Authorization": f"Bearer {token}",
+                        "Content-Type": "application/json",
+                    },
+                )
+            except (httpx.TransportError, httpx.TimeoutException) as ex:
+                if transient_attempt < max_transient:
+                    transient_attempt += 1
+                    self._opts.logger.log(
+                        "warn",
+                        f"Transient HTTP error (attempt {transient_attempt}/"
+                        f"{max_transient}): {ex}. Retrying in "
+                        f"{int(delay_s * 1000)}ms.",
+                    )
+                    await asyncio.sleep(delay_s)
+                    delay_s *= 2
+                    continue
+                raise
+
+            status = response.status_code
+
+            if status == 401 and not tried_auth_refresh:
+                tried_auth_refresh = True
+                self._opts.logger.log(
+                    "warn",
+                    "401 Unauthorized — forcing token refresh and retrying once.",
+                )
+                continue
+
+            if (
+                retry_on_transient
+                and not _is_ok(status)
+                and _is_transient(status)
+                and transient_attempt < max_transient
+            ):
+                transient_attempt += 1
+                self._opts.logger.log(
+                    "warn",
+                    f"Transient HTTP status {status} (attempt {transient_attempt}/"
+                    f"{max_transient}). Retrying in {int(delay_s * 1000)}ms.",
+                )
+                await asyncio.sleep(delay_s)
+                delay_s *= 2
+                continue
+
+            text = response.text
+            if not _is_ok(status):
+                raise DataceenError(
+                    f"HTTP {status}: {text[:500]}",
+                    -status,
+                    req.query,
+                )
+            return text
+
+
+def _is_ok(status: int) -> bool:
+    return 200 <= status < 300
+
+
+def _is_transient(status: int) -> bool:
+    return status == 408 or status == 429 or status >= 500

dataceen_client/runtime/__init__.py

@@ -0,0 +1,48 @@
+"""Runtime helpers shared by all generated entity clients."""
+from .aggregations import (
+    DEFAULT_AGGREGATION_DEPTH,
+    aggregation_fragment,
+)
+from .fields import collect_fields
+from .filter import (
+    BooleanOps,
+    DateOps,
+    NumberOps,
+    StringOps,
+    filter_to_graphql,
+)
+from .operations import (
+    RelationRef,
+    do_create,
+    do_create_bulk,
+    do_create_relation,
+    do_create_relation_bulk,
+    do_delete,
+    do_find,
+    do_search,
+    do_update,
+    do_update_bulk,
+)
+from .order_by import order_by_to_graphql
+
+__all__ = [
+    "BooleanOps",
+    "DEFAULT_AGGREGATION_DEPTH",
+    "DateOps",
+    "NumberOps",
+    "StringOps",
+    "aggregation_fragment",
+    "collect_fields",
+    "filter_to_graphql",
+    "order_by_to_graphql",
+    "RelationRef",
+    "do_create",
+    "do_create_bulk",
+    "do_create_relation",
+    "do_create_relation_bulk",
+    "do_delete",
+    "do_find",
+    "do_search",
+    "do_update",
+    "do_update_bulk",
+]

dataceen_client/runtime/aggregations.py

@@ -0,0 +1,54 @@
+"""Aggregation types and result-fragment expansion.
+
+Mirrors `DataceenClientTs/src/runtime/aggregations.ts`. The server's
+introspection does not advertise the Aggregations field on
+`<Entity>SearchResult`, but it returns it when the selection asks for it.
+We expand the fragment at a fixed depth so callers can nest up to N levels.
+"""
+from __future__ import annotations
+
+from typing import Any, Literal, NotRequired, TypedDict
+
+
+AggregationType = Literal["Bucket_Terms", "Metrics_Sum"]
+
+
+class AggregationDetails(TypedDict, total=False):
+    """Per-field aggregation request shape. Matches server's
+    `Search<Entity>AggregationDetails`."""
+
+    name: str
+    size: int
+    type: AggregationType
+    aggregations: list[Any]
+
+
+class Bucket(TypedDict):
+    Key: Any
+    Count: int
+    Aggregations: NotRequired[list["Aggregation"]]
+
+
+class Aggregation(TypedDict):
+    Name: str
+    SumOtherDocCount: NotRequired[int]
+    DocCountErrorUpperBound: NotRequired[int]
+    Buckets: list[Bucket]
+    Value: NotRequired[float]
+
+
+DEFAULT_AGGREGATION_DEPTH = 3
+
+
+def aggregation_fragment(depth: int) -> str:
+    """Build a GraphQL selection fragment for the Aggregations result, expanded
+    to the given nesting depth. Deeper buckets are returned by the server but
+    silently dropped by the selection."""
+    scalar_fields = "Name SumOtherDocCount DocCountErrorUpperBound Value"
+    fragment = f"Aggregations {{ {scalar_fields} Buckets {{ Key Count }} }}"
+    for _ in range(depth - 1):
+        fragment = (
+            f"Aggregations {{ {scalar_fields} "
+            f"Buckets {{ Key Count {fragment} }} }}"
+        )
+    return fragment