aepipe-sdk 0.1.0__tar.gz

aepipe_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,197 @@
+Metadata-Version: 2.4
+Name: aepipe-sdk
+Version: 0.1.0
+Summary: Python SDK for aepipe — multi-tenant log ingestion and query
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/loadchange/aepipe
+Project-URL: Repository, https://github.com/loadchange/aepipe
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+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
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# aepipe-sdk-python
+
+Python SDK for [aepipe](https://github.com/loadchange/aepipe), a multi-tenant log ingestion and query service built on Cloudflare Workers Analytics Engine.
+
+Zero external dependencies. Python 3.10+.
+
+## Installation
+
+```bash
+pip install aepipe-sdk
+```
+
+## Quick Start
+
+```python
+from aepipe import Aepipe
+
+client = Aepipe(
+    base_url="https://aepipe.yourdomain.com",
+    token="your-admin-token",
+)
+```
+
+## API Reference
+
+### `ingest(project, logstore, points) -> IngestResult`
+
+Write structured event points to Analytics Engine.
+
+| Parameter  | Type               | Description                                     |
+|------------|--------------------|-------------------------------------------------|
+| `project`  | `str`              | Project name (`^[a-zA-Z0-9_-]{1,64}$`)          |
+| `logstore` | `str`              | Logstore name (`^[a-zA-Z0-9_-]{1,64}$`)         |
+| `points`   | `list[DataPoint]`  | Event points (max 250 per call)                  |
+
+```python
+from aepipe import DataPoint
+
+result = client.ingest("myapp", "backend", [
+    DataPoint(event="user_login"),
+    DataPoint(event="api_error", level="error", blobs=["GET /api"], doubles=[1.23]),
+])
+print(result.ok)       # True
+print(result.written)  # 2
+```
+
+### `log(project, logstore, logs) -> LogResult`
+
+Write raw log entries via Workers Observability.
+
+| Parameter  | Type              | Description                                     |
+|------------|-------------------|-------------------------------------------------|
+| `project`  | `str`             | Project name                                     |
+| `logstore` | `str`             | Logstore name                                    |
+| `logs`     | `list[LogEntry]`  | Log entries (max 250 per call)                   |
+
+```python
+from aepipe import LogEntry
+
+result = client.log("myapp", "backend", [
+    LogEntry(message="server started"),
+    LogEntry(message="connection timeout", level="error", extra={"ip": "1.2.3.4"}),
+])
+print(result.written)  # 2
+```
+
+### `query(project, logstore, sql) -> QueryResult`
+
+Run a SQL query against Analytics Engine. Tenant filters are injected automatically.
+
+| Parameter  | Type   | Description                              |
+|------------|--------|------------------------------------------|
+| `project`  | `str`  | Project name                              |
+| `logstore` | `str`  | Logstore name                             |
+| `sql`      | `str`  | SQL query (Analytics Engine dialect)      |
+
+```python
+result = client.query("myapp", "backend", "SELECT count() as cnt FROM aepipe")
+print(result.data)
+```
+
+### `rawlog(project, logstore, *, limit=50, start=None, end=None) -> RawLogResult`
+
+Query raw Worker logs via Cloudflare Telemetry API.
+
+| Parameter  | Type           | Default | Description                    |
+|------------|----------------|---------|--------------------------------|
+| `project`  | `str`          |         | Project name                    |
+| `logstore` | `str`          |         | Logstore name                   |
+| `limit`    | `int`          | `50`    | Max results (server caps at 200)|
+| `start`    | `str or None`  | `None`  | Start timestamp (ISO 8601)      |
+| `end`      | `str or None`  | `None`  | End timestamp (ISO 8601)        |
+
+```python
+result = client.rawlog("myapp", "backend", limit=100, start="2025-01-01T00:00:00Z")
+for entry in result.logs:
+    print(f"[{entry.level}] {entry.timestamp} {entry.data}")
+print(f"total: {result.count}")
+```
+
+### `list_projects() -> ListResult`
+
+List all projects that have written data.
+
+```python
+result = client.list_projects()
+print(result.items)  # ["myapp", "analytics", ...]
+```
+
+### `list_logstores(project) -> ListResult`
+
+List all logstores within a project.
+
+```python
+result = client.list_logstores("myapp")
+print(result.items)  # ["backend", "frontend", ...]
+```
+
+## Data Types
+
+### `DataPoint`
+
+| Field     | Type            | Default  | Description                     |
+|-----------|-----------------|----------|---------------------------------|
+| `event`   | `str`           | required | Event name (non-empty)          |
+| `level`   | `str`           | `"info"` | Log level                       |
+| `blobs`   | `list[str]`     | `[]`     | String metadata (max 16 extra)  |
+| `doubles` | `list[float]`   | `[]`     | Numeric metrics (max 20)        |
+
+### `LogEntry`
+
+| Field     | Type              | Default  | Description                     |
+|-----------|-------------------|----------|---------------------------------|
+| `message` | `str`             | required | Log message (non-empty)         |
+| `level`   | `str`             | `"info"` | Log level                       |
+| `extra`   | `dict[str, Any]`  | `{}`     | Additional fields               |
+
+### Result Types
+
+| Type            | Fields                        |
+|-----------------|-------------------------------|
+| `IngestResult`  | `ok: bool`, `written: int`    |
+| `LogResult`     | `ok: bool`, `written: int`    |
+| `QueryResult`   | `data: Any`                   |
+| `RawLogResult`  | `logs: list[RawLogEntry]`, `count: int` |
+| `RawLogEntry`   | `timestamp: str`, `level: str`, `data: Any` |
+| `ListResult`    | `items: list[str]`            |
+
+## Validation
+
+All methods validate inputs before making network requests:
+
+- **Name format**: project and logstore names must match `^[a-zA-Z0-9_-]{1,64}$`.
+- **Batch size**: `ingest()` and `log()` accept at most 250 items per call.
+
+Invalid inputs raise `ValidationError` (subclass of `ValueError`).
+
+## Error Handling
+
+```python
+from aepipe import AepipeError, ValidationError
+
+try:
+    client.ingest("myapp", "backend", points)
+except ValidationError as e:
+    # Client-side validation failed
+    print(f"invalid input: {e}")
+except AepipeError as e:
+    # Server returned an error
+    print(f"API error {e.status}: {e.message}")
+```
+
+| Error Class      | Parent     | Fields               | When                       |
+|------------------|------------|----------------------|----------------------------|
+| `AepipeError`    | `Exception`| `status`, `message`  | Server returns non-2xx     |
+| `ValidationError`| `ValueError`| `message`           | Invalid client input       |
+
+## License
+
+MIT

aepipe_sdk-0.1.0/README.md

@@ -0,0 +1,180 @@
+# aepipe-sdk-python
+
+Python SDK for [aepipe](https://github.com/loadchange/aepipe), a multi-tenant log ingestion and query service built on Cloudflare Workers Analytics Engine.
+
+Zero external dependencies. Python 3.10+.
+
+## Installation
+
+```bash
+pip install aepipe-sdk
+```
+
+## Quick Start
+
+```python
+from aepipe import Aepipe
+
+client = Aepipe(
+    base_url="https://aepipe.yourdomain.com",
+    token="your-admin-token",
+)
+```
+
+## API Reference
+
+### `ingest(project, logstore, points) -> IngestResult`
+
+Write structured event points to Analytics Engine.
+
+| Parameter  | Type               | Description                                     |
+|------------|--------------------|-------------------------------------------------|
+| `project`  | `str`              | Project name (`^[a-zA-Z0-9_-]{1,64}$`)          |
+| `logstore` | `str`              | Logstore name (`^[a-zA-Z0-9_-]{1,64}$`)         |
+| `points`   | `list[DataPoint]`  | Event points (max 250 per call)                  |
+
+```python
+from aepipe import DataPoint
+
+result = client.ingest("myapp", "backend", [
+    DataPoint(event="user_login"),
+    DataPoint(event="api_error", level="error", blobs=["GET /api"], doubles=[1.23]),
+])
+print(result.ok)       # True
+print(result.written)  # 2
+```
+
+### `log(project, logstore, logs) -> LogResult`
+
+Write raw log entries via Workers Observability.
+
+| Parameter  | Type              | Description                                     |
+|------------|-------------------|-------------------------------------------------|
+| `project`  | `str`             | Project name                                     |
+| `logstore` | `str`             | Logstore name                                    |
+| `logs`     | `list[LogEntry]`  | Log entries (max 250 per call)                   |
+
+```python
+from aepipe import LogEntry
+
+result = client.log("myapp", "backend", [
+    LogEntry(message="server started"),
+    LogEntry(message="connection timeout", level="error", extra={"ip": "1.2.3.4"}),
+])
+print(result.written)  # 2
+```
+
+### `query(project, logstore, sql) -> QueryResult`
+
+Run a SQL query against Analytics Engine. Tenant filters are injected automatically.
+
+| Parameter  | Type   | Description                              |
+|------------|--------|------------------------------------------|
+| `project`  | `str`  | Project name                              |
+| `logstore` | `str`  | Logstore name                             |
+| `sql`      | `str`  | SQL query (Analytics Engine dialect)      |
+
+```python
+result = client.query("myapp", "backend", "SELECT count() as cnt FROM aepipe")
+print(result.data)
+```
+
+### `rawlog(project, logstore, *, limit=50, start=None, end=None) -> RawLogResult`
+
+Query raw Worker logs via Cloudflare Telemetry API.
+
+| Parameter  | Type           | Default | Description                    |
+|------------|----------------|---------|--------------------------------|
+| `project`  | `str`          |         | Project name                    |
+| `logstore` | `str`          |         | Logstore name                   |
+| `limit`    | `int`          | `50`    | Max results (server caps at 200)|
+| `start`    | `str or None`  | `None`  | Start timestamp (ISO 8601)      |
+| `end`      | `str or None`  | `None`  | End timestamp (ISO 8601)        |
+
+```python
+result = client.rawlog("myapp", "backend", limit=100, start="2025-01-01T00:00:00Z")
+for entry in result.logs:
+    print(f"[{entry.level}] {entry.timestamp} {entry.data}")
+print(f"total: {result.count}")
+```
+
+### `list_projects() -> ListResult`
+
+List all projects that have written data.
+
+```python
+result = client.list_projects()
+print(result.items)  # ["myapp", "analytics", ...]
+```
+
+### `list_logstores(project) -> ListResult`
+
+List all logstores within a project.
+
+```python
+result = client.list_logstores("myapp")
+print(result.items)  # ["backend", "frontend", ...]
+```
+
+## Data Types
+
+### `DataPoint`
+
+| Field     | Type            | Default  | Description                     |
+|-----------|-----------------|----------|---------------------------------|
+| `event`   | `str`           | required | Event name (non-empty)          |
+| `level`   | `str`           | `"info"` | Log level                       |
+| `blobs`   | `list[str]`     | `[]`     | String metadata (max 16 extra)  |
+| `doubles` | `list[float]`   | `[]`     | Numeric metrics (max 20)        |
+
+### `LogEntry`
+
+| Field     | Type              | Default  | Description                     |
+|-----------|-------------------|----------|---------------------------------|
+| `message` | `str`             | required | Log message (non-empty)         |
+| `level`   | `str`             | `"info"` | Log level                       |
+| `extra`   | `dict[str, Any]`  | `{}`     | Additional fields               |
+
+### Result Types
+
+| Type            | Fields                        |
+|-----------------|-------------------------------|
+| `IngestResult`  | `ok: bool`, `written: int`    |
+| `LogResult`     | `ok: bool`, `written: int`    |
+| `QueryResult`   | `data: Any`                   |
+| `RawLogResult`  | `logs: list[RawLogEntry]`, `count: int` |
+| `RawLogEntry`   | `timestamp: str`, `level: str`, `data: Any` |
+| `ListResult`    | `items: list[str]`            |
+
+## Validation
+
+All methods validate inputs before making network requests:
+
+- **Name format**: project and logstore names must match `^[a-zA-Z0-9_-]{1,64}$`.
+- **Batch size**: `ingest()` and `log()` accept at most 250 items per call.
+
+Invalid inputs raise `ValidationError` (subclass of `ValueError`).
+
+## Error Handling
+
+```python
+from aepipe import AepipeError, ValidationError
+
+try:
+    client.ingest("myapp", "backend", points)
+except ValidationError as e:
+    # Client-side validation failed
+    print(f"invalid input: {e}")
+except AepipeError as e:
+    # Server returned an error
+    print(f"API error {e.status}: {e.message}")
+```
+
+| Error Class      | Parent     | Fields               | When                       |
+|------------------|------------|----------------------|----------------------------|
+| `AepipeError`    | `Exception`| `status`, `message`  | Server returns non-2xx     |
+| `ValidationError`| `ValueError`| `message`           | Invalid client input       |
+
+## License
+
+MIT

aepipe_sdk-0.1.0/aepipe/__init__.py

@@ -0,0 +1,25 @@
+from .client import Aepipe, AepipeError, ValidationError
+from .types import (
+    DataPoint,
+    IngestResult,
+    ListResult,
+    LogEntry,
+    LogResult,
+    QueryResult,
+    RawLogEntry,
+    RawLogResult,
+)
+
+__all__ = [
+    "Aepipe",
+    "AepipeError",
+    "ValidationError",
+    "DataPoint",
+    "IngestResult",
+    "ListResult",
+    "LogEntry",
+    "LogResult",
+    "QueryResult",
+    "RawLogEntry",
+    "RawLogResult",
+]

aepipe_sdk-0.1.0/aepipe/client.py

@@ -0,0 +1,187 @@
+from __future__ import annotations
+
+import json
+import re
+from typing import Any
+from urllib.request import Request, urlopen
+from urllib.error import HTTPError
+
+from .types import (
+    DataPoint,
+    IngestResult,
+    ListResult,
+    LogEntry,
+    LogResult,
+    QueryResult,
+    RawLogEntry,
+    RawLogResult,
+)
+
+_NAME_RE = re.compile(r"^[a-zA-Z0-9_-]{1,64}$")
+_MAX_BATCH = 250
+
+
+class AepipeError(Exception):
+    """Raised when the aepipe API returns an error."""
+
+    def __init__(self, status: int, message: str):
+        self.status = status
+        self.message = message
+        super().__init__(f"aepipe error {status}: {message}")
+
+
+class ValidationError(ValueError):
+    """Raised when client-side validation fails."""
+
+
+def _validate_name(name: str, label: str) -> None:
+    if not _NAME_RE.match(name):
+        raise ValidationError(f"invalid {label}: {name!r}")
+
+
+def _serialize_point(p: DataPoint) -> dict[str, Any]:
+    d: dict[str, Any] = {"event": p.event, "level": p.level}
+    if p.blobs:
+        d["blobs"] = p.blobs
+    if p.doubles:
+        d["doubles"] = p.doubles
+    return d
+
+
+class Aepipe:
+    """Python SDK for the aepipe analytics engine."""
+
+    def __init__(self, base_url: str, token: str):
+        """
+        Args:
+            base_url: The aepipe worker URL, e.g. ``https://aepipe.example.com``.
+            token: The ``ADMIN_TOKEN`` secret.
+        """
+        self._base = base_url.rstrip("/")
+        self._token = token
+
+    # --- ingest ---
+
+    def ingest(
+        self,
+        project: str,
+        logstore: str,
+        points: list[DataPoint],
+    ) -> IngestResult:
+        """Write structured event points (max 250 per call)."""
+        _validate_name(project, "project")
+        _validate_name(logstore, "logstore")
+        if len(points) > _MAX_BATCH:
+            raise ValidationError(f"max {_MAX_BATCH} points per request, got {len(points)}")
+        body = {"points": [_serialize_point(p) for p in points]}
+        resp = self._post(f"/v1/{project}/{logstore}/ingest", body)
+        return IngestResult(ok=resp["ok"], written=resp["written"])
+
+    # --- log ---
+
+    def log(
+        self,
+        project: str,
+        logstore: str,
+        logs: list[LogEntry],
+    ) -> LogResult:
+        """Write raw log entries (max 250 per call)."""
+        _validate_name(project, "project")
+        _validate_name(logstore, "logstore")
+        if len(logs) > _MAX_BATCH:
+            raise ValidationError(f"max {_MAX_BATCH} logs per request, got {len(logs)}")
+        body = {
+            "logs": [
+                {"message": e.message, "level": e.level, **e.extra}
+                for e in logs
+            ]
+        }
+        resp = self._post(f"/v1/{project}/{logstore}/log", body)
+        return LogResult(ok=resp["ok"], written=resp["written"])
+
+    # --- query ---
+
+    def query(
+        self,
+        project: str,
+        logstore: str,
+        sql: str,
+    ) -> QueryResult:
+        """Run a SQL query against the Analytics Engine."""
+        _validate_name(project, "project")
+        _validate_name(logstore, "logstore")
+        resp = self._post(f"/v1/{project}/{logstore}/query", {"sql": sql})
+        return QueryResult(data=resp)
+
+    # --- rawlog ---
+
+    def rawlog(
+        self,
+        project: str,
+        logstore: str,
+        *,
+        limit: int = 50,
+        start: str | None = None,
+        end: str | None = None,
+    ) -> RawLogResult:
+        """Query raw Worker logs."""
+        _validate_name(project, "project")
+        _validate_name(logstore, "logstore")
+        body: dict[str, Any] = {"limit": limit}
+        if start is not None:
+            body["start"] = start
+        if end is not None:
+            body["end"] = end
+        resp = self._post(f"/v1/{project}/{logstore}/rawlog", body)
+        entries = [
+            RawLogEntry(
+                timestamp=e["timestamp"],
+                level=e["level"],
+                data=e["data"],
+            )
+            for e in resp.get("logs", [])
+        ]
+        return RawLogResult(logs=entries, count=resp.get("count", len(entries)))
+
+    # --- list ---
+
+    def list_projects(self) -> ListResult:
+        """List all projects."""
+        resp = self._get("/v1/projects")
+        return ListResult(items=resp.get("projects", []))
+
+    def list_logstores(self, project: str) -> ListResult:
+        """List all logstores in a project."""
+        _validate_name(project, "project")
+        resp = self._get(f"/v1/{project}/logstores")
+        return ListResult(items=resp.get("logstores", []))
+
+    # --- internal ---
+
+    def _headers(self) -> dict[str, str]:
+        return {
+            "Authorization": f"Bearer {self._token}",
+            "Content-Type": "application/json",
+            "User-Agent": "aepipe-sdk-python/0.1.0",
+        }
+
+    def _request(self, method: str, path: str, body: Any = None) -> Any:
+        url = f"{self._base}{path}"
+        data = json.dumps(body).encode() if body is not None else None
+        req = Request(url, data=data, headers=self._headers(), method=method)
+        try:
+            with urlopen(req) as resp:
+                return json.loads(resp.read())
+        except HTTPError as e:
+            text = e.read().decode()
+            try:
+                msg = json.loads(text).get("error", text)
+            except json.JSONDecodeError:
+                msg = text
+            raise AepipeError(e.code, msg) from e
+
+    def _get(self, path: str) -> Any:
+        return self._request("GET", path)
+
+    def _post(self, path: str, body: Any) -> Any:
+        return self._request("POST", path, body)

aepipe_sdk-0.1.0/aepipe/types.py

@@ -0,0 +1,58 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass
+class DataPoint:
+    """A structured event point to write to Analytics Engine."""
+
+    event: str
+    level: str = "info"
+    blobs: list[str] = field(default_factory=list)
+    doubles: list[float] = field(default_factory=list)
+
+
+@dataclass
+class LogEntry:
+    """A raw log entry to write via Workers Logs."""
+
+    message: str
+    level: str = "info"
+    extra: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class IngestResult:
+    ok: bool
+    written: int
+
+
+@dataclass
+class LogResult:
+    ok: bool
+    written: int
+
+
+@dataclass
+class RawLogEntry:
+    timestamp: str
+    level: str
+    data: Any
+
+
+@dataclass
+class RawLogResult:
+    logs: list[RawLogEntry]
+    count: int
+
+
+@dataclass
+class QueryResult:
+    data: Any
+
+
+@dataclass
+class ListResult:
+    items: list[str]