bytesmap 0.1.1__py3-none-any.whl

bytesmap/events.py

@@ -0,0 +1,435 @@
+"""Append-only event delivery with bounded envelopes and identity-preserving retries."""
+
+from __future__ import annotations
+
+import json
+import math
+import random
+import re
+import time
+import traceback
+from collections.abc import Callable, Mapping, Sequence
+from dataclasses import dataclass
+from datetime import UTC, datetime
+from email.utils import parsedate_to_datetime
+from importlib.resources import files
+from typing import Any, Self
+from uuid import uuid4
+
+from ._transport import (
+    Transport,
+    TransportError,
+    UrllibTransport,
+    validate_origin,
+    validate_timeout,
+)
+
+_LIMITS = json.loads(files(__package__).joinpath("_limits.json").read_text("utf-8"))
+_LABEL = re.compile(_LIMITS["label_pattern"])
+_DIMENSION = re.compile(_LIMITS["dimension_pattern"])
+
+
+@dataclass(frozen=True)
+class EventContext:
+    namespace: str | None = None
+    group: str | None = None
+    schema_version: int | None = None
+    dimensions: Mapping[str, Any] | None = None
+    data: Mapping[str, Any] | None = None
+
+
+@dataclass(frozen=True)
+class EventDraft:
+    type: str
+    id: str | None = None
+    timestamp: datetime | str | None = None
+    context: EventContext | None = None
+    error: BaseException | None = None
+
+
+class EventDeliveryError(Exception):
+    def __init__(self, code: str, payload: bytes, status: int | None = None) -> None:
+        super().__init__(code)
+        self.code, self.status = code, status
+        self._payload = payload
+
+    @property
+    def batch(self) -> dict[str, Any]:
+        """A detached copy to pass to retry(); no credentials are included."""
+        return json.loads(self._payload)
+
+
+def _encode(value: Any) -> bytes:
+    return json.dumps(
+        value,
+        ensure_ascii=False,
+        allow_nan=False,
+        sort_keys=True,
+        separators=(",", ":"),
+    ).encode("utf-8")
+
+
+def _json_value(value: Any, depth: int = 1) -> None:
+    if value is None or isinstance(value, (str, bool)):
+        return
+    if isinstance(value, (int, float)):
+        if abs(value) > 9007199254740991 or not math.isfinite(value):
+            raise ValueError(
+                "Event numbers must be finite and within the JavaScript safe range"
+            )
+        return
+    if depth > _LIMITS["max_depth"]:
+        raise ValueError("Event data is too deep")
+    if isinstance(value, dict) and all(isinstance(key, str) for key in value):
+        for item in value.values():
+            _json_value(item, depth + 1)
+    elif isinstance(value, list):
+        for item in value:
+            _json_value(item, depth + 1)
+    else:
+        raise TypeError("Event values must be JSON-compatible")
+
+
+def _snapshot(value: Mapping[str, Any] | None) -> dict[str, Any]:
+    if value is None:
+        return {}
+    if not isinstance(value, Mapping):
+        raise TypeError("Event dimensions and data must be mappings")
+    result = dict(value)
+    _json_value(result)
+    return json.loads(_encode(result))
+
+
+def _merge(parent: EventContext, child: EventContext | None) -> EventContext:
+    child = child or EventContext()
+    result = EventContext(
+        namespace=child.namespace if child.namespace is not None else parent.namespace,
+        group=child.group if child.group is not None else parent.group,
+        schema_version=child.schema_version
+        if child.schema_version is not None
+        else parent.schema_version,
+        dimensions={**_snapshot(parent.dimensions), **_snapshot(child.dimensions)},
+        data={**_snapshot(parent.data), **_snapshot(child.data)},
+    )
+    for label in (result.namespace, result.group):
+        if not isinstance(label, str) or not _LABEL.fullmatch(label):
+            raise ValueError("Invalid event namespace or group")
+    if (
+        type(result.schema_version) is not int
+        or not 1 <= result.schema_version <= 2147483647
+    ):
+        raise ValueError("Invalid event schema version")
+    return result
+
+
+def _error_data(error: BaseException, depth: int = 1) -> dict[str, Any]:
+    if depth > _LIMITS["max_depth"]:
+        raise ValueError("Exception causes are too deep")
+    result: dict[str, Any] = {"name": type(error).__name__, "message": str(error)}
+    if error.__traceback__ is not None:
+        result["stack"] = "".join(
+            traceback.format_exception(
+                type(error), error, error.__traceback__, chain=False
+            )
+        )
+    if error.__cause__ is not None:
+        result["cause"] = _error_data(error.__cause__, depth + 1)
+    return result
+
+
+def _validate_batch(batch: Any, payload: bytes) -> None:
+    if len(payload) > _LIMITS["max_batch_bytes"]:
+        raise ValueError("Event batch exceeds 1 MiB")
+    if not isinstance(batch, dict) or set(batch) != {"version", "batchId", "events"}:
+        raise ValueError("Invalid event batch fields")
+    if (
+        type(batch["version"]) is not int
+        or batch["version"] != 1
+        or not isinstance(batch["batchId"], str)
+        or not re.fullmatch(r"[a-f0-9-]{36}", batch["batchId"])
+    ):
+        raise ValueError("Invalid event batch identity")
+    events = batch["events"]
+    if (
+        not isinstance(events, list)
+        or not 1 <= len(events) <= _LIMITS["max_batch_events"]
+    ):
+        raise ValueError("Invalid event batch count")
+    for event in events:
+        if (
+            not isinstance(event, dict)
+            or not {
+                "id",
+                "namespace",
+                "group",
+                "type",
+                "timestamp",
+                "schemaVersion",
+                "data",
+            }
+            <= event.keys()
+            or set(event)
+            - {
+                "id",
+                "namespace",
+                "group",
+                "type",
+                "timestamp",
+                "schemaVersion",
+                "dimensions",
+                "data",
+            }
+        ):
+            raise ValueError("Invalid event fields")
+        for field in ("id", "namespace", "group", "type"):
+            if not isinstance(event[field], str) or not _LABEL.fullmatch(event[field]):
+                raise ValueError("Invalid event label")
+        if (
+            type(event["schemaVersion"]) is not int
+            or not 1 <= event["schemaVersion"] <= 2147483647
+        ):
+            raise ValueError("Invalid event schema version")
+        timestamp = event["timestamp"]
+        if not isinstance(timestamp, str) or not re.fullmatch(
+            r"\d{4}-\d\d-\d\dT\d\d:\d\d:\d\d\.\d{3}Z", timestamp
+        ):
+            raise ValueError("Timestamp must be UTC ISO milliseconds")
+        at = datetime.fromisoformat(timestamp)
+        if not 1900 <= at.year <= 2299:
+            raise ValueError("Event timestamp year must be between 1900 and 2299")
+        dimensions, data = event.get("dimensions", {}), event["data"]
+        if (
+            not isinstance(dimensions, dict)
+            or len(dimensions) > _LIMITS["max_dimensions"]
+            or not isinstance(data, dict)
+        ):
+            raise ValueError("Invalid event dimensions or data")
+        for key, value in dimensions.items():
+            if (
+                not _DIMENSION.fullmatch(key)
+                or isinstance(value, (dict, list))
+                or isinstance(value, str)
+                and len(value.encode("utf-16-le")) > 2048
+            ):
+                raise ValueError("Invalid event dimension")
+        _json_value(dimensions)
+        _json_value(data)
+        if len(_encode([dimensions, data])) > _LIMITS["max_data_bytes"]:
+            raise ValueError("Event dimensions and data exceed 64 KiB")
+
+
+class BytesMapEventClient:
+    def __init__(
+        self,
+        endpoint: str,
+        dataset: str,
+        token: str,
+        *,
+        namespace: str = "default",
+        group: str = "default",
+        context: EventContext | None = None,
+        allow_plaintext_loopback: bool = False,
+        timeout: float = 10,
+        max_attempts: int = 5,
+        transport: Transport | None = None,
+        sleep: Callable[[float], None] = time.sleep,
+    ) -> None:
+        endpoint, plaintext = validate_origin(endpoint)
+        if plaintext and not allow_plaintext_loopback:
+            raise ValueError(
+                "HTTP loopback event ingestion requires allow_plaintext_loopback=True"
+            )
+        if not isinstance(dataset, str) or not re.fullmatch(
+            r"[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}",
+            dataset,
+        ):
+            raise ValueError("Invalid event dataset ID")
+        if not isinstance(token, str) or not re.fullmatch(
+            r"bmap_event_[A-Za-z0-9_-]{43}", token
+        ):
+            raise ValueError("Invalid append-only event token")
+        validate_timeout(timeout)
+        if (
+            not 0.01 <= timeout <= 60
+            or type(max_attempts) is not int
+            or not 1 <= max_attempts <= 10
+        ):
+            raise ValueError("Invalid event timeout or retry limit")
+        self._endpoint, self._dataset, self._token = endpoint, dataset, token
+        self._url = f"{endpoint}/v1/events/batches?dataset={dataset}"
+        self._timeout, self._max_attempts, self._sleep = timeout, max_attempts, sleep
+        self._context = _merge(EventContext(namespace, group, 1), context)
+        self._transport = transport or UrllibTransport()
+        self._owns_transport = transport is None
+        self._closed = False
+        self._owner: BytesMapEventClient | None = None
+
+    def scope(
+        self, context: EventContext | None = None, **kwargs: Any
+    ) -> BytesMapEventClient:
+        self._check_open()
+        if context is not None and kwargs:
+            raise ValueError("Pass an EventContext or context keywords")
+        merged = _merge(self._context, context or EventContext(**kwargs))
+        scoped = BytesMapEventClient(
+            self._endpoint,
+            self._dataset,
+            self._token,
+            context=merged,
+            allow_plaintext_loopback=self._endpoint.startswith("http:"),
+            timeout=self._timeout,
+            max_attempts=self._max_attempts,
+            transport=self._transport,
+            sleep=self._sleep,
+        )
+        scoped._owner = self._owner or self
+        return scoped
+
+    def emit(
+        self,
+        event: str | EventDraft,
+        *,
+        namespace: str | None = None,
+        group: str | None = None,
+        dimensions: Mapping[str, Any] | None = None,
+        data: Mapping[str, Any] | None = None,
+        error: BaseException | None = None,
+    ) -> dict[str, Any]:
+        if isinstance(event, str):
+            event = EventDraft(
+                event,
+                context=EventContext(
+                    namespace=namespace, group=group, dimensions=dimensions, data=data
+                ),
+                error=error,
+            )
+        elif any(
+            value is not None for value in (namespace, group, dimensions, data, error)
+        ):
+            raise ValueError("Supply an EventDraft or event keyword arguments")
+        return self.send([event])
+
+    def send(self, events: Sequence[EventDraft]) -> dict[str, Any]:
+        self._check_open()
+        if not 1 <= len(events) <= _LIMITS["max_batch_events"]:
+            raise ValueError("Invalid event batch count")
+        envelopes = []
+        for event in events:
+            if not isinstance(event, EventDraft):
+                raise TypeError("send() expects EventDraft instances")
+            context = _merge(self._context, event.context)
+            data = _snapshot(context.data)
+            if event.error is not None:
+                if "error" in data:
+                    raise ValueError("Supply error or data['error'], not both")
+                if not isinstance(event.error, BaseException):
+                    raise TypeError("Event error must be an exception")
+                data["error"] = _error_data(event.error)
+            timestamp = event.timestamp
+            if timestamp is None:
+                timestamp = datetime.now(UTC)
+            if isinstance(timestamp, datetime):
+                if timestamp.tzinfo is None:
+                    raise ValueError("Event datetimes must include a timezone")
+                timestamp = (
+                    timestamp.astimezone(UTC)
+                    .isoformat(timespec="milliseconds")
+                    .replace("+00:00", "Z")
+                )
+            envelopes.append(
+                {
+                    "id": event.id if event.id is not None else str(uuid4()),
+                    "namespace": context.namespace,
+                    "group": context.group,
+                    "schemaVersion": context.schema_version,
+                    "type": event.type,
+                    "timestamp": timestamp,
+                    "dimensions": _snapshot(context.dimensions),
+                    "data": data,
+                }
+            )
+        return self.retry({"version": 1, "batchId": str(uuid4()), "events": envelopes})
+
+    def retry(self, batch: Mapping[str, Any]) -> dict[str, Any]:
+        self._check_open()
+        _json_value(batch)
+        payload = _encode(batch)
+        snapshot = json.loads(payload)
+        _validate_batch(snapshot, payload)
+        status = None
+        code = "event_delivery_unconfirmed"
+        for attempt in range(self._max_attempts):
+            delay = min(0.1 * 2**attempt * random.uniform(0.5, 1.5), 10)
+            try:
+                response = self._transport.request(
+                    "POST",
+                    self._url,
+                    {
+                        "authorization": "Bearer " + self._token,
+                        "content-type": "application/json",
+                        "accept": "application/json",
+                    },
+                    payload,
+                    self._timeout,
+                )
+                status = response.status
+                if status == 202:
+                    try:
+                        if len(response.body) > 16384:
+                            raise ValueError("Oversized event acceptance")
+                        receipt = json.loads(response.body)
+                        if (
+                            isinstance(receipt, dict)
+                            and type(receipt.get("version")) is int
+                            and receipt["version"] == 1
+                            and receipt.get("status") == "accepted"
+                            and receipt.get("batchId") == snapshot["batchId"]
+                            and type(receipt.get("acceptedEvents")) is int
+                            and receipt["acceptedEvents"] == len(snapshot["events"])
+                            and type(receipt.get("duplicate")) is bool
+                        ):
+                            return receipt
+                    except (ValueError, UnicodeError):
+                        pass
+                elif status not in (408, 429) and status < 500:
+                    raise EventDeliveryError("event_rejected", payload, status)
+                headers = {
+                    key.lower(): value for key, value in response.headers.items()
+                }
+                retry_after = headers.get("retry-after")
+                if retry_after is not None:
+                    try:
+                        delay = (
+                            float(retry_after)
+                            if retry_after.strip().isdigit()
+                            else (
+                                parsedate_to_datetime(retry_after) - datetime.now(UTC)
+                            ).total_seconds()
+                        )
+                        delay = max(0, delay)
+                        if delay > 60:
+                            raise EventDeliveryError("retry_later", payload, status)
+                    except (ValueError, TypeError, OverflowError):
+                        pass
+            except (TransportError, OSError):
+                status = None
+            if attempt + 1 < self._max_attempts:
+                self._sleep(delay)
+        raise EventDeliveryError(code, payload, status)
+
+    def _check_open(self) -> None:
+        if self._closed or self._owner is not None and self._owner._closed:
+            raise RuntimeError("BytesMap event client is closed")
+
+    def close(self) -> None:
+        if not self._closed:
+            self._closed = True
+            if self._owns_transport:
+                self._transport.close()
+
+    def __enter__(self) -> Self:
+        self._check_open()
+        return self
+
+    def __exit__(self, *_: object) -> None:
+        self.close()

bytesmap-0.1.1.dist-info/METADATA

@@ -0,0 +1,133 @@
+Metadata-Version: 2.5
+Name: bytesmap
+Version: 0.1.1
+Summary: The official BytesMap Python SDK: workspace API operations and event ingestion.
+Project-URL: Homepage, https://bytesmap.com
+Project-URL: Repository, https://github.com/oblien/bytesmap
+Project-URL: Documentation, https://github.com/oblien/bytesmap/tree/main/packages/python
+Project-URL: Issues, https://github.com/oblien/bytesmap/issues
+Author: BytesMap
+License-Expression: Apache-2.0
+License-File: LICENSE
+Keywords: analytics,bytesmap,database,events,sdk
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# BytesMap for Python
+
+The official Python 3.11+ SDK for the BytesMap workspace API and append-only event
+ingestion. It has no runtime dependencies and uses the standard library with
+verified TLS. All 240 API methods are generated from BytesMap's shared operation
+catalogue, with Python names and keyword arguments.
+
+```sh
+pip install bytesmap
+```
+
+## Send events
+
+Create a dataset and an ingestion key in **Events → Connect application**. Set
+`BYTESMAP_EVENTS_URL`, `BYTESMAP_EVENT_DATASET`, and `BYTESMAP_EVENT_TOKEN`, then:
+
+```python
+import os
+from bytesmap import EventClient
+
+with EventClient(
+    endpoint=os.environ["BYTESMAP_EVENTS_URL"],
+    dataset=os.environ["BYTESMAP_EVENT_DATASET"],
+    token=os.environ["BYTESMAP_EVENT_TOKEN"],
+    namespace="production",
+    group="application",
+) as events:
+    accepted = events.emit("app.started")
+    # Declare durationMs on the dataset before sending this dimension.
+    events.emit(
+        "request.finished", dimensions={"durationMs": 120}, data={"route": "/orders"}
+    )
+```
+
+`emit()` waits for durable acceptance. There is no background buffer or shutdown
+flush. IDs, UTC timestamps and schema version 1 are supplied automatically.
+`events.scope(dimensions={"userId": "user_42"})` snapshots request context while
+sharing the transport. Declare dimension names and types on the dataset first;
+full JSON belongs in `data`. Pass `error=exception` to capture its name, message,
+stack and explicit cause.
+
+Use `send([EventDraft("app.started"), ...])` for a batch. Limits match the server:
+1,000 events, 1 MiB per batch, 64 dimensions and 64 KiB of dimensions/data per event.
+Numbers must fit the JavaScript safe range. HTTPS is required. Local testing on
+HTTP loopback requires explicit `allow_plaintext_loopback=True`.
+
+Network errors, HTTP 408/429/5xx and invalid acceptance receipts retry with the
+same batch identity and bytes (default five attempts). Other HTTP errors fail
+immediately. `EventDeliveryError.batch` returns the original payload for
+`events.retry(error.batch)`. An unconfirmed send may already have been accepted;
+preserve its batch identity when retrying. `Retry-After` above one minute returns
+`retry_later` so the application can schedule its retry.
+
+## Workspace API
+
+```python
+import os
+from bytesmap import BytesMapClient, CallOptions
+
+with BytesMapClient(
+    base_url="https://api.example.com",
+    token=os.environ["BYTESMAP_API_TOKEN"],
+    project_id="project-id",
+) as client:
+    dashboards = client.dashboards.list()
+    result = client.queries.run(id="saved-query-id")
+    workspace = client.scope("workspace-id")
+    workspace.sources.list(call_options=CallOptions(project_id="another-project"))
+```
+
+API and event ingestion keys are separate credentials. Keep workspace API keys on
+your server. Scopes cannot widen a key's server-enforced permissions. Modules and
+methods use `snake_case` (`client.event_destinations.list()`); keyword arguments
+are mapped to the wire contract's field names (`destination_id` → `destinationId`).
+Pass a dictionary with original wire field names for nested payloads:
+
+```python
+client.dashboards.update({"id": "dashboard-id", "folderId": None})
+client.invoke("queries.run", {"id": "saved-query-id", "params": {"customer": "id"}})
+```
+
+Omitted fields stay omitted; `None` sends explicit JSON null. Methods return public
+JSON values (dicts, lists and scalars). `BytesMapError` exposes `code`, `params` and
+`status`; its string representation contains only the error code. Export methods
+return `filename`, `contentType` and `contentBase64`.
+
+API mutations are never automatically retried. All requests reject redirects and
+use a finite timeout. A `token` callback supports rotating credentials; a
+`project_id` callback supports current project selection. Project selection is
+captured before the token callback. Closing a scope never closes its parent;
+closing the parent makes its scopes unavailable.
+
+Clients are synchronous. In async applications, use `asyncio.to_thread` around
+calls; cancelling that await does not cancel the underlying HTTP request, which
+remains bounded by its timeout. An optional `transport` implementing the exported
+`Transport` protocol supports host-owned HTTP clients and tests; the caller owns
+its lifetime and must disable redirects and retain TLS verification.
+
+## Development
+
+```sh
+bun --no-env-file scripts/generate-python-sdk.ts
+bun --no-env-file scripts/generate-python-sdk.ts --check
+PYTHONPATH=packages/python/src python3 -m unittest discover -s packages/python/tests -v
+python3 -m build packages/python
+```
+
+Generated catalogue files are committed. Regenerate them when the shared operation
+catalogue or event limits change. Python releases are independent of npm and NuGet.

bytesmap-0.1.1.dist-info/RECORD

@@ -0,0 +1,12 @@
+bytesmap/__init__.py,sha256=otj1uuselBTbU9tbMa--2Oy4Q6OXHKxFc6G4Dk0zIIg,612
+bytesmap/_catalog.json,sha256=Q-jRlPceh6lOc9fa3LPBSAkA8Qov7fNsT1uQW3UfeMA,47939
+bytesmap/_generated.py,sha256=WmikKA69hrGbSO3-hjgZ6wd1p-WX6VuXPP4lKdtcm4E,58025
+bytesmap/_limits.json,sha256=qmYmDKzeSjCpONhVjEa_A47smP9q_4v2O-iumidoZu8,246
+bytesmap/_transport.py,sha256=I0aampC99v3EvTMMwksgHCe7yu3skHN2854h8hhpPoo,3715
+bytesmap/client.py,sha256=XXNtk2JoD3LW2839N-uOHTQRadXdF6B9n74HtefBKfo,7709
+bytesmap/events.py,sha256=HMu5vkeZu3FBd63ZpWmcruRD868bzTG4jYIoadS0JRI,16558
+bytesmap/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+bytesmap-0.1.1.dist-info/METADATA,sha256=g1IAGRzMl5c08DG3qmeGy7hLlSV2kdhuhTnoK92aEzM,5747
+bytesmap-0.1.1.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+bytesmap-0.1.1.dist-info/licenses/LICENSE,sha256=z8d0m5b2O9McPEK1xHG_dWgUBT6EfBDz6wA0F7xSPTA,11358
+bytesmap-0.1.1.dist-info/RECORD,,

bytesmap-0.1.1.dist-info/WHEEL

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