chronix-client 0.2.0__py3-none-any.whl

chronix_client/__init__.py

@@ -0,0 +1,41 @@
+"""Chronix Python client — async-first SDK for Chronix time-series database."""
+
+from chronix_client.client import ChronixClient
+from chronix_client.exceptions import (
+    BackpressureError,
+    ChronixError,
+    ConnectionError,
+    DeadlineExceeded,
+    QueryError,
+    WriteError,
+)
+from chronix_client.models import (
+    ColumnSchema,
+    FieldValue,
+    MeasurementInfo,
+    Point,
+    QueryResult,
+    DeleteResult,
+    ServerInfo,
+    TimeRange,
+)
+
+__all__ = [
+    "BackpressureError",
+    "ChronixClient",
+    "ChronixError",
+    "ColumnSchema",
+    "ConnectionError",
+    "DeadlineExceeded",
+    "DeleteResult",
+    "FieldValue",
+    "MeasurementInfo",
+    "Point",
+    "QueryError",
+    "QueryResult",
+    "ServerInfo",
+    "TimeRange",
+    "WriteError",
+]
+
+__version__ = "0.2.0"

chronix_client/client.py

@@ -0,0 +1,530 @@
+"""Async HTTP client for the Chronix REST API."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+from chronix_client.exceptions import (
+    BackpressureError,
+    ChronixError,
+    ConnectionError,
+    DeadlineExceeded,
+    QueryError,
+    WriteError,
+)
+from chronix_client.models import (
+    ColumnSchema,
+    DeleteResult,
+    MeasurementInfo,
+    Point,
+    QueryResult,
+    ServerInfo,
+    TimeRange,
+)
+
+_DEFAULT_TIMEOUT = 30.0
+
+
+class ChronixClient:
+    """Async client for the Chronix time-series database REST API.
+
+    Parameters
+    ----------
+    base_url : str
+        Chronix server URL, e.g. ``"http://localhost:5555"``.
+    api_key : str | None
+        Optional API key for authentication (sent as ``Authorization: Bearer``).
+    timeout : float
+        Default request timeout in seconds.
+    namespace : str | None
+        Optional namespace header for multi-tenant deployments.
+
+    Examples
+    --------
+    >>> async with ChronixClient("http://localhost:5555") as client:
+    ...     await client.write([Point("cpu", {"usage": 42.5}, tags={"host": "a"})])
+    ...     result = await client.query("cpu", TimeRange(start=0, end=2**63 - 1))
+    ...     print(len(result))
+    """
+
+    def __init__(
+        self,
+        base_url: str,
+        *,
+        api_key: str | None = None,
+        timeout: float = _DEFAULT_TIMEOUT,
+        namespace: str | None = None,
+    ) -> None:
+        headers: dict[str, str] = {"Content-Type": "application/json"}
+        if api_key is not None:
+            headers["Authorization"] = f"Bearer {api_key}"
+        if namespace is not None:
+            headers["X-Chronix-Namespace"] = namespace
+
+        self._client = httpx.AsyncClient(
+            base_url=base_url,
+            headers=headers,
+            timeout=timeout,
+        )
+
+    async def __aenter__(self) -> ChronixClient:
+        return self
+
+    async def __aexit__(self, *exc: object) -> None:
+        await self.close()
+
+    async def close(self) -> None:
+        """Close the underlying HTTP connection pool."""
+        await self._client.aclose()
+
+    # ── Health ────────────────────────────────────────────────────
+
+    async def health(self) -> dict[str, Any]:
+        """Check server health.
+
+        Returns a dict with ``status`` key.
+        """
+        return await self._get("/health")
+
+    async def ready(self) -> dict[str, Any]:
+        """Check server readiness."""
+        return await self._get("/ready")
+
+    async def server_info(self) -> ServerInfo:
+        """Get server metadata (version, uptime, measurement count).
+
+        Assembled from ``/health`` and the measurement listing's ``total``;
+        there is no ``/api/v1/server_info`` route.
+        """
+        health = await self._get("/health")
+        listing = await self._get("/api/v1/measurements", params={"limit": 1})
+        return ServerInfo(
+            version=str(health.get("version", "unknown")),
+            uptime_seconds=float(health.get("uptime_secs", 0) or 0),
+            measurement_count=int(listing.get("total", 0) or 0),
+        )
+
+    # ── Write ─────────────────────────────────────────────────────
+
+    async def write(
+        self,
+        points: list[Point],
+        *,
+        idempotency_key: str | None = None,
+        backfill: bool = False,
+    ) -> int:
+        """Write points via JSON endpoint.
+
+        Parameters
+        ----------
+        points : list[Point]
+            Data points to write.
+        idempotency_key : str | None
+            Optional idempotency key (HTTP 409 on duplicate).
+        backfill : bool
+            Write **outside** the server's out-of-order window — importing
+            history rather than ingesting live. Live writes are held to
+            ``±ooo_shard_tolerance`` shards of the newest write; anything
+            older is refused, and this is the way to store it. Off by
+            default, because the window is what keeps the number of open
+            memtables bounded.
+
+        Returns
+        -------
+        int
+            Number of points written.
+        """
+        headers: dict[str, str] = {}
+        if idempotency_key is not None:
+            headers["Idempotency-Key"] = idempotency_key
+
+        body = [p.to_dict() for p in points]
+        # `POST /api/v1/write` answers **204 No Content** — no body to parse,
+        # so the count returned here is the caller's own.
+        #
+        # `params`, never a query string concatenated into the path: the live
+        # smoke test checks every path this file names against the server's
+        # OpenAPI document, and a path carrying its own query matches nothing.
+        params = {"backfill": "true"} if backfill else None
+        await self._post_no_content(
+            "/api/v1/write", json=body, params=params, extra_headers=headers
+        )
+        return len(points)
+
+    async def write_line_protocol(
+        self,
+        lines: str | list[str],
+        *,
+        idempotency_key: str | None = None,
+    ) -> int:
+        """Write using InfluxDB line protocol.
+
+        Parameters
+        ----------
+        lines : str | list[str]
+            Line protocol string(s).
+        idempotency_key : str | None
+            Optional idempotency key.
+
+        Returns
+        -------
+        int
+            Number of points written.
+        """
+        if isinstance(lines, list):
+            body = "\n".join(lines)
+        else:
+            body = lines
+
+        headers: dict[str, str] = {"Content-Type": "text/plain"}
+        if idempotency_key is not None:
+            headers["Idempotency-Key"] = idempotency_key
+
+        resp = await self._client.post(
+            "/api/v1/write/influx", content=body, headers=headers
+        )
+        self._check_response(resp)
+        data = resp.json()
+        return data.get("written", 0)
+
+    # ── Query ─────────────────────────────────────────────────────
+
+    async def query(
+        self,
+        measurement: str,
+        time_range: TimeRange,
+        *,
+        tags: dict[str, str] | None = None,
+        fields: list[str] | None = None,
+        limit: int | None = None,
+        offset: int | None = None,
+    ) -> QueryResult:
+        """Execute a structured query.
+
+        Parameters
+        ----------
+        measurement : str
+            Measurement name.
+        time_range : TimeRange
+            Time range to query.
+        tags : dict[str, str] | None
+            Optional tag filter predicates (exact match).
+        fields : list[str] | None
+            Specific fields to return (default: all).
+        limit : int | None
+            Maximum rows to return.
+        offset : int | None
+            Rows to skip.
+
+        Returns
+        -------
+        QueryResult
+            Query results with row dicts.
+        """
+        body: dict[str, Any] = {
+            "measurement": measurement,
+            "range": time_range.to_dict(),
+        }
+        if tags:
+            body["tags"] = dict(tags)
+        if fields:
+            body["fields"] = list(fields)
+        if limit is not None:
+            body["limit"] = limit
+        if offset is not None:
+            body["offset"] = offset
+
+        # The response is a bare JSON **array** of rows, not an object with a
+        # `rows` key. Every field name here was wrong in the same direction:
+        # the body used `tag_filters`/`field_columns`, which the server's
+        # `QueryRequest` does not define — and it ignores unknown fields, so
+        # the query silently ran unfiltered and unprojected before failing on
+        # the response shape.
+        rows = await self._post("/api/v1/chronix/query", json=body)
+        return QueryResult(rows=rows if isinstance(rows, list) else [])
+
+    async def sql(self, query: str) -> QueryResult:
+        """Execute a SQL query.
+
+        Parameters
+        ----------
+        query : str
+            SQL query string.
+
+        Returns
+        -------
+        QueryResult
+            Query results.
+        """
+        # The SQL endpoint answers column-oriented metadata plus **positional**
+        # rows — `{"columns": [{"name", "data_type"}], "rows": [[...]],
+        # "row_count": n}`. `QueryResult` holds row dicts, so the two are
+        # zipped here; handing the raw arrays through would give callers rows
+        # with no column names and a `to_dataframe()` with integer headers.
+        data = await self._post("/api/v1/chronix/sql", json={"query": query})
+        names = [c["name"] for c in data.get("columns", [])]
+        rows = [dict(zip(names, row)) for row in data.get("rows", [])]
+        return QueryResult(rows=rows, truncated=bool(data.get("truncated", False)))
+
+    async def explain(self, measurement: str, time_range: TimeRange) -> dict[str, Any]:
+        """Get the query execution plan (EXPLAIN)."""
+        body = {"measurement": measurement, "range": time_range.to_dict()}
+        return await self._post("/api/v1/chronix/query/explain", json=body)
+
+    # ── Schema ────────────────────────────────────────────────────
+
+    async def list_measurements(
+        self,
+        *,
+        offset: int | None = None,
+        limit: int | None = None,
+    ) -> list[MeasurementInfo]:
+        """List measurements.
+
+        The endpoint is **paginated** and answers
+        ``{"items": [...], "total": n, "offset": n, "limit": n}``; this method
+        read a ``measurements`` key that no response carries, so it always
+        returned an empty list. Pass ``limit`` to page explicitly — the server
+        applies its own default otherwise.
+        """
+        params: dict[str, Any] = {}
+        if offset is not None:
+            params["offset"] = offset
+        if limit is not None:
+            params["limit"] = limit
+        data = await self._get("/api/v1/measurements", params=params or None)
+        return [MeasurementInfo(name=m["name"]) for m in data.get("items", [])]
+
+    async def get_schema(self, measurement: str) -> list[ColumnSchema]:
+        """Get schema for a measurement."""
+        data = await self._get(f"/api/v1/measurements/{measurement}/schema")
+        # `data_type` is omitted for timestamp and tag columns — the server
+        # skips serialising `None` — so indexing it raised `KeyError` on every
+        # measurement that has a tag.
+        return [
+            ColumnSchema(
+                name=c["name"], role=c["role"], data_type=c.get("data_type")
+            )
+            for c in data.get("columns", [])
+        ]
+
+    async def drop_measurement(self, measurement: str) -> None:
+        """Drop a measurement and all its data."""
+        resp = await self._client.delete(f"/api/v1/measurements/{measurement}")
+        self._check_response(resp)
+
+    # ── Delete ────────────────────────────────────────────────────
+
+    async def delete(
+        self,
+        measurement: str,
+        time_range: TimeRange | None = None,
+        *,
+        tags: dict[str, str] | None = None,
+    ) -> DeleteResult:
+        """Delete data by measurement, optional time range, and optional tags.
+
+        ``time_range`` is inclusive at both ends. Omitting it deletes
+        everything currently stored for the matching series — but not data
+        written afterwards, so writing to a deleted series re-creates it.
+
+        Returns a :class:`DeleteResult`. Check
+        :attr:`~DeleteResult.complete` before treating the delete as done: the
+        server skips segments it cannot read rather than failing the request.
+        """
+        body: dict[str, Any] = {"measurement": measurement}
+        if time_range is not None:
+            body["range"] = time_range.to_dict()
+        if tags:
+            body["tags"] = dict(tags)
+        data = await self._post("/api/v1/delete", json=body)
+        return DeleteResult.from_dict(data)
+
+    # ── Admin ─────────────────────────────────────────────────────
+
+    async def list_rollups(self) -> list[dict[str, Any]]:
+        """List configured rollup rules.
+
+        Paginated, like every listing endpoint: the payload key is ``items``.
+        """
+        data = await self._get("/api/v1/rollups")
+        return data.get("items", [])
+
+    async def list_connectors(self) -> list[dict[str, Any]]:
+        """List active connectors (payload key is ``items``)."""
+        data = await self._get("/api/v1/connectors")
+        return data.get("items", [])
+
+    async def openapi_spec(self) -> dict[str, Any]:
+        """Fetch the OpenAPI 3.1 specification."""
+        return await self._get("/api/v1/openapi.json")
+
+    # ── PromQL ────────────────────────────────────────────────────
+
+    async def prom_query(self, query: str, *, time: str | None = None) -> dict[str, Any]:
+        """Execute an instant PromQL query.
+
+        Parameters
+        ----------
+        query : str
+            PromQL expression.
+        time : str | None
+            Evaluation timestamp (RFC 3339 or Unix seconds).
+        """
+        params: dict[str, str] = {"query": query}
+        if time is not None:
+            params["time"] = time
+        return await self._get("/api/v1/prom/query", params=params)
+
+    async def prom_query_range(
+        self,
+        query: str,
+        start: str,
+        end: str,
+        step: str,
+    ) -> dict[str, Any]:
+        """Execute a range PromQL query.
+
+        Parameters
+        ----------
+        query : str
+            PromQL expression.
+        start, end : str
+            Range boundaries (RFC 3339 or Unix seconds).
+        step : str
+            Query resolution step (e.g. ``"15s"``).
+        """
+        params = {"query": query, "start": start, "end": end, "step": step}
+        return await self._get("/api/v1/prom/query_range", params=params)
+
+    async def prom_labels(self) -> list[str]:
+        """List all Prometheus label names."""
+        data = await self._get("/api/v1/prom/labels")
+        return data.get("data", [])
+
+    async def prom_label_values(self, label: str) -> list[str]:
+        """Get values for a Prometheus label."""
+        data = await self._get(f"/api/v1/prom/label/{label}/values")
+        return data.get("data", [])
+
+    async def prom_series(self, match: list[str]) -> list[dict[str, str]]:
+        """Find series matching label selectors."""
+        params = {"match[]": match}
+        data = await self._get("/api/v1/prom/series", params=params)
+        return data.get("data", [])
+
+    # ── Arrow Flight SQL ──────────────────────────────────────────
+
+    @staticmethod
+    def flight_sql_uri(host: str = "localhost", port: int = 5557) -> str:
+        """Build an ADBC Flight SQL connection URI.
+
+        Use with ``adbc_driver_flightsql`` for Arrow-native queries::
+
+            import adbc_driver_flightsql.dbapi
+            uri = ChronixClient.flight_sql_uri()
+            conn = adbc_driver_flightsql.dbapi.connect(uri)
+            cursor = conn.cursor()
+            cursor.execute("SELECT * FROM cpu LIMIT 10")
+            df = cursor.fetch_arrow_table().to_pandas()
+        """
+        return f"grpc://{host}:{port}"
+
+    # ── Internal ──────────────────────────────────────────────────
+
+    async def _get(
+        self,
+        path: str,
+        *,
+        params: dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        try:
+            resp = await self._client.get(path, params=params)
+        except httpx.ConnectError as e:
+            raise ConnectionError(str(e)) from e
+        self._check_response(resp)
+        return resp.json()
+
+    async def _post(
+        self,
+        path: str,
+        *,
+        json: Any = None,
+        extra_headers: dict[str, str] | None = None,
+    ) -> Any:
+        """POST and decode the JSON body.
+
+        The return is deliberately `Any` rather than `dict`: `/api/v1/query`
+        answers a bare JSON **array**. Typing this as a dict is what let
+        `data.get("rows", [])` past review on a response that has no keys.
+        """
+        try:
+            resp = await self._client.post(path, json=json, headers=extra_headers)
+        except httpx.ConnectError as e:
+            raise ConnectionError(str(e)) from e
+        self._check_response(resp)
+        return resp.json()
+
+    async def _post_no_content(
+        self,
+        path: str,
+        *,
+        json: Any = None,
+        params: dict[str, str] | None = None,
+        extra_headers: dict[str, str] | None = None,
+    ) -> None:
+        """POST to an endpoint that answers `204 No Content`."""
+        try:
+            resp = await self._client.post(
+                path, json=json, params=params, headers=extra_headers
+            )
+        except httpx.ConnectError as e:
+            raise ConnectionError(str(e)) from e
+        self._check_response(resp)
+
+    @staticmethod
+    def _check_response(resp: httpx.Response) -> None:
+        """Turn an error response into the exception that says what to do.
+
+        The server's `code` is the machine-readable half of every error and
+        the API reference tells clients to branch on it; this used to discard
+        it, so `503 BACKPRESSURE` — back off a second, the flush clearing it
+        is already running — was indistinguishable from a bug in the server.
+        """
+        if resp.is_success:
+            return
+        status = resp.status_code
+        code: str | None = None
+        detail = resp.text
+        try:
+            body = resp.json()
+            detail = body.get("error", resp.text)
+            code = body.get("code")
+        except Exception:  # noqa: BLE001
+            pass
+
+        retry_after: float | None = None
+        header = resp.headers.get("retry-after")
+        if header is not None:
+            try:
+                retry_after = float(header)
+            except ValueError:
+                # An HTTP-date is legal here and chronix never sends one;
+                # ignoring it is better than failing the error path.
+                retry_after = None
+
+        kwargs = {"status_code": status, "code": code, "retry_after": retry_after}
+
+        if status == 409:
+            raise WriteError(
+                f"duplicate write (idempotency conflict): {detail}", **kwargs
+            )
+        if status in (503, 507):
+            raise BackpressureError(f"server unavailable {status}: {detail}", **kwargs)
+        if status == 504:
+            raise DeadlineExceeded(f"deadline exceeded {status}: {detail}", **kwargs)
+        if 400 <= status < 500:
+            raise QueryError(f"client error {status}: {detail}", **kwargs)
+        raise ChronixError(f"server error {status}: {detail}", **kwargs)

chronix_client/exceptions.py

@@ -0,0 +1,89 @@
+"""Exception hierarchy for the Chronix Python client.
+
+Every error response carries a machine-readable ``code`` beside its message,
+and the API reference tells clients to branch on that rather than on the
+sentence.  This module used to throw it away: a full memtable, a query that
+ran out of time and a genuine server bug all arrived as a bare
+:class:`ChronixError` whose only distinguishing feature was a status number
+embedded in a string.  So the one thing an ingestion loop needs to decide —
+*should I retry, and when?* — was not available to it.
+"""
+
+from __future__ import annotations
+
+
+class ChronixError(Exception):
+    """Base exception for all Chronix client errors.
+
+    Attributes:
+        status_code: The HTTP status, when the failure came from the server.
+        code: The server's machine-readable error code (``BACKPRESSURE``,
+            ``CARDINALITY_EXCEEDED``, …), or ``None`` for a transport failure.
+        retry_after: Seconds the server asked the client to wait, from the
+            ``Retry-After`` header, or ``None`` when it did not say.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: int | None = None,
+        code: str | None = None,
+        retry_after: float | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+        self.code = code
+        self.retry_after = retry_after
+
+    @property
+    def retryable(self) -> bool:
+        """Whether re-sending the same request could succeed.
+
+        ``True`` for the conditions the server marks as the deployment's and
+        transient — back-pressure, a full disk, the database shutting down —
+        and for a deadline, which a smaller query or a quieter moment may
+        clear.  ``False`` for anything the caller has to change first.
+        """
+        return isinstance(self, (BackpressureError, DeadlineExceeded))
+
+
+class ConnectionError(ChronixError):  # noqa: A001 — intentional shadow
+    """Raised when the client cannot reach the Chronix server."""
+
+    @property
+    def retryable(self) -> bool:
+        """A server that is not there yet may be there in a moment."""
+        return True
+
+
+class WriteError(ChronixError):
+    """Raised when a write operation fails."""
+
+
+class QueryError(ChronixError):
+    """Raised when a query operation fails."""
+
+
+class BackpressureError(ChronixError):
+    """The server is temporarily unable to accept the request.
+
+    ``503 BACKPRESSURE`` (the memtable is at capacity and the flush that
+    clears it is already running), ``503 OVERLOADED`` (a condition that needs
+    an operator), ``503 DATABASE_CLOSED`` (the server is shutting down) and
+    ``507 STORAGE_FULL``.  :attr:`~ChronixError.retry_after` carries the wait
+    the server asked for, in seconds.
+    """
+
+
+class DeadlineExceeded(ChronixError):
+    """The server stopped waiting.
+
+    ``504 QUERY_TIMEOUT`` — the read outran its deadline; narrow the range or
+    raise the setting.
+
+    ``504 WRITE_TIMEOUT`` — the server stopped waiting for a write it cannot
+    cancel, so **the outcome is unknown and the write may still land**.
+    Retrying is safe: a point is identified by its series and its timestamp,
+    so writing it twice stores it once.
+    """

chronix_client/models.py

@@ -0,0 +1,194 @@
+"""Data models for the Chronix Python client."""
+
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any
+
+
+class FieldValue(Enum):
+    """Discriminator for Chronix field types."""
+
+    FLOAT64 = "float64"
+    INT64 = "int64"
+    UINT64 = "uint64"
+    BOOL = "boolean"
+    STRING = "string"
+
+
+@dataclass(slots=True)
+class Point:
+    """A single data point to write to Chronix.
+
+    Parameters
+    ----------
+    measurement : str
+        Measurement name.
+    tags : dict[str, str]
+        Tag key-value pairs (indexed, low cardinality).
+    fields : dict[str, int | float | bool | str]
+        Field key-value pairs (the actual data).
+    timestamp : int | None
+        Unix timestamp in nanoseconds. Defaults to current time.
+    """
+
+    measurement: str
+    fields: dict[str, int | float | bool | str]
+    tags: dict[str, str] = field(default_factory=dict)
+    timestamp: int | None = None
+
+    def to_dict(self) -> dict[str, Any]:
+        """Serialize to the JSON write request format."""
+        return {
+            "measurement": self.measurement,
+            "tags": self.tags,
+            "fields": self.fields,
+            "timestamp": self.timestamp or time.time_ns(),
+        }
+
+    def to_line_protocol(self) -> str:
+        """Serialize to InfluxDB line protocol format."""
+        parts = [self.measurement]
+
+        # Tags (sorted by key for canonical ordering).
+        if self.tags:
+            tag_str = ",".join(
+                f"{_escape_tag(k)}={_escape_tag(v)}"
+                for k, v in sorted(self.tags.items())
+            )
+            parts[0] = f"{self.measurement},{tag_str}"
+
+        # Fields (sorted by key).
+        field_parts: list[str] = []
+        for k, v in sorted(self.fields.items()):
+            field_parts.append(f"{_escape_tag(k)}={_encode_field(v)}")
+        parts.append(",".join(field_parts))
+
+        # Timestamp.
+        ts = self.timestamp or time.time_ns()
+        parts.append(str(ts))
+
+        return " ".join(parts)
+
+
+@dataclass(slots=True, frozen=True)
+class TimeRange:
+    """Closed time range ``[start, end]`` in nanoseconds.
+
+    Both ends are **inclusive**, matching the server's ``TimeRangeRequest``.
+    This docstring said half-open for as long as it existed, which is a
+    one-nanosecond error on a query and a whole-boundary-sample error on a
+    delete.
+    """
+
+    start: int
+    end: int
+
+    def to_dict(self) -> dict[str, int]:
+        return {"start": self.start, "end": self.end}
+
+
+@dataclass(slots=True, frozen=True)
+class DeleteResult:
+    """Outcome of a predicate delete.
+
+    A delete can be **partial**: a segment the server could not open or read is
+    skipped rather than aborting the whole operation, so ``series_tombstoned``
+    on its own cannot distinguish "nothing matched" from "some data was never
+    scanned". Callers acting on an erasure obligation must check
+    :attr:`complete` and retry.
+    """
+
+    series_tombstoned: int
+    segments_skipped: int
+
+    @property
+    def complete(self) -> bool:
+        """Whether every matching segment was scanned."""
+        return self.segments_skipped == 0
+
+    @classmethod
+    def from_dict(cls, data: dict[str, object]) -> "DeleteResult":
+        return cls(
+            series_tombstoned=int(data.get("deleted", 0) or 0),
+            segments_skipped=int(data.get("segments_skipped", 0) or 0),
+        )
+
+
+@dataclass(slots=True, frozen=True)
+class ColumnSchema:
+    """Schema for a single column in a measurement.
+
+    ``data_type`` is ``None`` for timestamp and tag columns: the server omits
+    the key rather than sending null.
+    """
+
+    name: str
+    role: str  # "tag", "field", or "timestamp"
+    data_type: str | None = None
+
+
+@dataclass(slots=True, frozen=True)
+class MeasurementInfo:
+    """Summary of a measurement."""
+
+    name: str
+
+
+@dataclass(slots=True, frozen=True)
+class ServerInfo:
+    """Server metadata."""
+
+    version: str
+    uptime_seconds: float
+    measurement_count: int
+
+
+@dataclass(slots=True)
+class QueryResult:
+    """Result of a query — a list of row dicts.
+
+    ``truncated`` is ``True`` when the server's ``sql_max_rows`` cut the
+    answer short. It is not decoration: an aggregate computed over a
+    truncated scan is a **wrong** number, not a partial one, and before the
+    server reported this there was no way for a caller to tell the two apart.
+    """
+
+    rows: list[dict[str, Any]]
+    truncated: bool = False
+
+    def __len__(self) -> int:
+        return len(self.rows)
+
+    def __iter__(self):
+        return iter(self.rows)
+
+    def to_dataframe(self):
+        """Convert to a pandas DataFrame (requires ``pandas`` extra)."""
+        import pandas as pd  # noqa: PLC0415 — lazy import
+
+        return pd.DataFrame(self.rows)
+
+
+# ── helpers ──────────────────────────────────────────────────────
+
+def _escape_tag(s: str) -> str:
+    """Escape special characters for line protocol tags/keys."""
+    return s.replace("\\", "\\\\").replace(" ", "\\ ").replace(",", "\\,").replace("=", "\\=")
+
+
+def _encode_field(v: int | float | bool | str) -> str:
+    """Encode a field value for line protocol."""
+    if isinstance(v, bool):
+        return "true" if v else "false"
+    if isinstance(v, int):
+        return f"{v}i"
+    if isinstance(v, float):
+        return repr(v)
+    if isinstance(v, str):
+        escaped = v.replace("\\", "\\\\").replace('"', '\\"')
+        return f'"{escaped}"'
+    msg = f"unsupported field type: {type(v)}"
+    raise TypeError(msg)

chronix_client-0.2.0.dist-info/METADATA

@@ -0,0 +1,200 @@
+Metadata-Version: 2.5
+Name: chronix-client
+Version: 0.2.0
+Summary: Python client for Chronix time-series database
+Author: Chronix Authors
+License-Expression: Apache-2.0
+Keywords: chronix,client,database,timeseries
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Database
+Classifier: Topic :: Scientific/Engineering
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: adbc-driver-flightsql>=1.0
+Requires-Dist: httpx<1,>=0.27
+Requires-Dist: pyarrow>=17
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Provides-Extra: pandas
+Requires-Dist: pandas>=2; extra == 'pandas'
+Description-Content-Type: text/markdown
+
+# chronix-client (Python)
+
+Async Python client for the [Chronix](https://github.com/hupe1980/chronix) time-series database.
+
+## Features
+
+- **Async-first** — built on `httpx` for non-blocking I/O
+- **JSON + Line Protocol writes** — both formats supported
+- **Structured queries + SQL** — first-class support for both query APIs
+- **PromQL** — instant & range queries via Prometheus-compatible endpoints
+- **Arrow Flight SQL** — zero-copy queries via ADBC driver
+- **Schema introspection** — list measurements, get column schemas
+- **Multi-tenant** — namespace header support
+- **Typed** — full type annotations with `py.typed` marker
+
+## Installation
+
+```bash
+pip install chronix-client
+```
+
+With pandas support:
+
+```bash
+pip install "chronix-client[pandas]"
+```
+
+## Quick Start
+
+```python
+import asyncio
+from chronix_client import ChronixClient, Point, TimeRange
+
+async def main():
+    async with ChronixClient("http://localhost:5555") as client:
+        # Write
+        await client.write([
+            Point("cpu", {"usage": 42.5}, tags={"host": "a"})
+        ])
+
+        # Query
+        result = await client.query(
+            "cpu",
+            TimeRange(start=0, end=2**63 - 1),
+            tag_filters={"host": "a"},
+        )
+        for row in result:
+            print(row)
+
+        # SQL
+        result = await client.sql("SELECT * FROM cpu ORDER BY _time DESC LIMIT 10")
+        df = result.to_dataframe()  # requires pandas extra
+
+asyncio.run(main())
+```
+
+## Line Protocol Writes
+
+```python
+await client.write_line_protocol([
+    "cpu,host=a usage=42.5 1700000000000000000",
+    "mem,host=a total=16384i,used=8192i 1700000000000000000",
+])
+```
+
+## PromQL Queries
+
+```python
+# Instant query
+result = await client.prom_query('cpu_usage{host="server-1"}')
+
+# Range query
+result = await client.prom_query_range(
+    'rate(cpu_usage[5m])',
+    start="2024-01-01T00:00:00Z",
+    end="2024-01-02T00:00:00Z",
+    step="60s",
+)
+
+# Label discovery
+labels = await client.prom_labels()
+values = await client.prom_label_values("host")
+```
+
+## Arrow Flight SQL (Zero-Copy)
+
+For high-throughput analytical queries, use Arrow Flight SQL via ADBC:
+
+```python
+import adbc_driver_flightsql.dbapi
+
+uri = ChronixClient.flight_sql_uri("localhost", 5557)
+conn = adbc_driver_flightsql.dbapi.connect(uri)
+cursor = conn.cursor()
+cursor.execute("SELECT * FROM cpu WHERE _time > now() - INTERVAL '1 hour'")
+table = cursor.fetch_arrow_table()
+df = table.to_pandas()
+```
+
+## Authentication & Multi-Tenancy
+
+```python
+client = ChronixClient(
+    "http://localhost:5555",
+    api_key="your-api-key",
+    namespace="production",
+)
+```
+
+## Idempotent Writes
+
+```python
+await client.write(
+    [Point("cpu", {"usage": 42.5})],
+    idempotency_key="batch-2024-01-15-001",
+)
+# Second call with same key → WriteError (HTTP 409)
+```
+
+## API Reference
+
+### `ChronixClient`
+
+| Method | Description |
+|--------|-------------|
+| `health()` | Health check |
+| `ready()` | Readiness check |
+| `server_info()` | Server metadata |
+| `write(points, *, idempotency_key)` | Write points (JSON) |
+| `write_line_protocol(lines, *, idempotency_key)` | Write (line protocol) |
+| `query(measurement, time_range, *, tag_filters, field_columns, limit)` | Structured query |
+| `sql(query)` | SQL query |
+| `explain(measurement, time_range)` | Explain query plan |
+| `list_measurements()` | List measurements |
+| `get_schema(measurement)` | Get column schema |
+| `drop_measurement(measurement)` | Drop measurement |
+| `delete(measurement, time_range=None, *, tags)` | Delete data; returns a `DeleteResult` — check `.complete` |
+| `prom_query(query, *, time)` | PromQL instant query |
+| `prom_query_range(query, start, end, step)` | PromQL range query |
+| `prom_labels()` | List Prometheus labels |
+| `prom_label_values(label)` | Label values |
+| `prom_series(match)` | Find series |
+| `list_rollups()` | List rollup rules |
+| `list_connectors()` | List connectors |
+| `openapi_spec()` | Fetch OpenAPI spec |
+| `flight_sql_uri(host, port)` | Build Flight SQL URI |
+
+### Models
+
+| Type | Description |
+|------|-------------|
+| `Point` | Data point with measurement, tags, fields, timestamp |
+| `TimeRange` | Half-open `[start, end)` in nanoseconds |
+| `QueryResult` | Query result with `.rows`, `.to_dataframe()` |
+| `ColumnSchema` | Column metadata (name, role, data_type) |
+| `MeasurementInfo` | Measurement summary (name) |
+| `ServerInfo` | Server metadata (version, uptime, measurement_count) |
+
+### Exceptions
+
+| Exception | When |
+|-----------|------|
+| `ChronixError` | Base exception (server errors) |
+| `ConnectionError` | Cannot reach server |
+| `WriteError` | Write failure (including idempotency conflict) |
+| `QueryError` | Query/client error (4xx) |
+
+## License
+
+Apache-2.0 — same as Chronix.

chronix_client-0.2.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+chronix_client/__init__.py,sha256=lp7eqUy8erKHWXcWzzZSh2AhXvTN3x93uPrBkfPwnKY,794
+chronix_client/client.py,sha256=jNx4WfD3GBz7qCVMA-b5M0x5FdGQwa8KijFE3zg1JpA,19426
+chronix_client/exceptions.py,sha256=DD3y7mJEwyPfd7f6pQdidbOzidrTJU5Bn47IXWjGRlg,3267
+chronix_client/models.py,sha256=iA2ptCU1WGw2WyXRYO2qiudYGPTTm9qxwW7QNZ_mZbk,5646
+chronix_client/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+chronix_client-0.2.0.dist-info/METADATA,sha256=GJleEy4oBnjOc0l75Cf5AZWYXrBZ449kwmHFaOeyo8w,5887
+chronix_client-0.2.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+chronix_client-0.2.0.dist-info/RECORD,,

chronix_client-0.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any