dataerai-sdk 0.1.0__py3-none-any.whl

dataerai/__init__.py

@@ -0,0 +1,28 @@
+"""Dataerai Python SDK — public API surface."""
+
+from ._version import __version__
+from .client import DataeraiClient
+from ._errors import DaemonError, DaemonTimeoutError
+from ._types import (
+    AssetMetadata,
+    AuthStatus,
+    CollectionDownloadResult,
+    DownloadedFile,
+    DownloadResult,
+    ProgressEvent,
+    UploadResult,
+)
+
+__all__ = [
+    "__version__",
+    "DataeraiClient",
+    "DaemonError",
+    "DaemonTimeoutError",
+    "AuthStatus",
+    "UploadResult",
+    "DownloadedFile",
+    "DownloadResult",
+    "CollectionDownloadResult",
+    "ProgressEvent",
+    "AssetMetadata",
+]

dataerai/_daemon.py

@@ -0,0 +1,57 @@
+"""Daemon process management utilities."""
+
+from __future__ import annotations
+
+import os
+import subprocess
+import tempfile
+import time
+from pathlib import Path
+
+
+def default_socket_path() -> str:
+    """Return the default Unix socket path.
+
+    Resolution order:
+    1. ``$DATAERAI_SOCKET`` environment variable
+    2. ``$XDG_RUNTIME_DIR/dataerai-transfer.sock``  (Linux / systemd)
+    3. ``<tempdir>/dataerai-transfer.sock``          (macOS and other platforms)
+    """
+    env = os.environ.get("DATAERAI_SOCKET")
+    if env:
+        return env
+    xdg = os.environ.get("XDG_RUNTIME_DIR")
+    if xdg:
+        return str(Path(xdg) / "dataerai-transfer.sock")
+    return str(Path(tempfile.gettempdir()) / "dataerai-transfer.sock")
+
+
+def spawn_daemon(binary_path: str, socket_path: str) -> subprocess.Popen:
+    """Spawn the Dataerai daemon and return the :class:`subprocess.Popen` handle.
+
+    The caller is responsible for eventually killing the process.
+    stdout/stderr are piped so the daemon does not pollute the caller's output.
+    """
+    env = {**os.environ, "DATAERAI_SOCKET": socket_path}
+    return subprocess.Popen(
+        [binary_path, "--socket", socket_path],
+        stdin=subprocess.DEVNULL,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+        env=env,
+    )
+
+
+def wait_for_socket(socket_path: str, timeout_s: float = 10.0) -> None:
+    """Poll until *socket_path* exists or *timeout_s* elapses.
+
+    Raises :class:`TimeoutError` if the socket does not appear in time.
+    """
+    deadline = time.monotonic() + timeout_s
+    while not Path(socket_path).exists():
+        if time.monotonic() >= deadline:
+            raise TimeoutError(
+                f"Daemon socket '{socket_path}' not available after {timeout_s:.0f}s. "
+                "Ensure the Dataerai binary is installed and runnable."
+            )
+        time.sleep(0.2)

dataerai/_errors.py

@@ -0,0 +1,17 @@
+from __future__ import annotations
+
+
+class DaemonError(Exception):
+    """Raised when the daemon returns a coded error response."""
+
+    def __init__(self, code: str, message: str) -> None:
+        super().__init__(message)
+        self.code = code
+        self.message = message
+
+    def __repr__(self) -> str:  # pragma: no cover
+        return f"DaemonError(code={self.code!r}, message={self.message!r})"
+
+
+class DaemonTimeoutError(TimeoutError):
+    """Raised when a request to the daemon (or a transfer) exceeds its timeout."""

dataerai/_framing.py

@@ -0,0 +1,58 @@
+"""
+IPC wire framing for the Dataerai transfer daemon.
+
+Wire format per frame:
+    [length: uint32 LE] [direction: uint8] [JSON envelope: <length> bytes]
+
+direction = 0x01  Python SDK → Daemon (command)
+direction = 0x02  Daemon → Python SDK (message / event)
+"""
+
+from __future__ import annotations
+
+import json
+import struct
+
+DIR_COMMAND: int = 0x01
+DIR_MESSAGE: int = 0x02
+MAX_FRAME_BYTES: int = 32 * 1024 * 1024  # 32 MiB
+
+
+def encode_frame(payload: dict) -> bytes:
+    """Encode *payload* as a command frame (direction = DIR_COMMAND)."""
+    data = json.dumps(payload, separators=(",", ":")).encode("utf-8")
+    if len(data) > MAX_FRAME_BYTES:
+        raise ValueError(
+            f"payload too large: {len(data):,} bytes (max {MAX_FRAME_BYTES:,})"
+        )
+    return struct.pack("<IB", len(data), DIR_COMMAND) + data
+
+
+class FrameReader:
+    """Stateful streaming frame parser.
+
+    Feed incoming socket data via :meth:`push`.  *on_frame* is called once for
+    each complete, valid frame decoded from the stream.
+    """
+
+    def __init__(self, on_frame) -> None:
+        self._buf = bytearray()
+        self._on_frame = on_frame
+
+    def push(self, chunk: bytes) -> None:
+        self._buf += chunk
+        while len(self._buf) >= 5:
+            (length,) = struct.unpack_from("<I", self._buf, 0)
+            if length > MAX_FRAME_BYTES:
+                # Corrupt stream — reset and wait for re-sync.
+                self._buf.clear()
+                return
+            if len(self._buf) < 5 + length:
+                break
+            raw = bytes(self._buf[5 : 5 + length])
+            del self._buf[: 5 + length]
+            try:
+                self._on_frame(json.loads(raw.decode("utf-8")))
+            except (json.JSONDecodeError, UnicodeDecodeError):
+                # Silently discard frames with unparseable JSON.
+                pass

dataerai/_types.py

@@ -0,0 +1,112 @@
+"""Public data-transfer types for the Dataerai Python SDK."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import Any, Callable, Optional
+
+
+# ─── Auth ─────────────────────────────────────────────────────────────────────
+
+
+@dataclass
+class AuthStatus:
+    """Result of :meth:`DataeraiClient.auth_status`."""
+
+    user_email: str
+    expires_at: datetime
+
+
+# ─── Upload ───────────────────────────────────────────────────────────────────
+
+
+@dataclass
+class UploadResult:
+    """Returned by :meth:`DataeraiClient.upload` once the transfer completes."""
+
+    transfer_id: str
+    asset_id: str
+    content_id: str
+    total_bytes: int
+    chunk_count: int
+
+
+# ─── Download ─────────────────────────────────────────────────────────────────
+
+
+@dataclass
+class DownloadedFile:
+    filename: str
+    size: int
+    local_path: str
+
+
+@dataclass
+class DownloadResult:
+    """Returned by :meth:`DataeraiClient.download` once the transfer completes."""
+
+    transfer_id: str
+    asset_id: str
+    content_id: str
+    total_bytes: int
+    chunk_count: int
+    files: list[DownloadedFile] = field(default_factory=list)
+
+
+# ─── Progress ─────────────────────────────────────────────────────────────────
+
+
+@dataclass
+class ProgressEvent:
+    """Emitted periodically during an upload or download."""
+
+    transfer_id: str
+    bytes_done: int
+    bytes_total: int
+    chunk_index: int
+    chunk_count: int
+    rate_bps: float
+    file_index: int
+    file_name: str
+
+    @property
+    def percent(self) -> float:
+        """Transfer completion as a percentage (0–100)."""
+        if self.bytes_total == 0:
+            return 0.0
+        return self.bytes_done / self.bytes_total * 100
+
+    @property
+    def rate_mbps(self) -> float:
+        """Current transfer rate in MB/s (megabytes, not megabits)."""
+        return self.rate_bps / 1_000_000
+
+
+# ─── Metadata ─────────────────────────────────────────────────────────────────
+
+
+@dataclass
+class AssetMetadata:
+    """Asset metadata as returned by the daemon."""
+
+    asset_id: str
+    title: str
+    description: Optional[str] = None
+    alias: Optional[str] = None
+    tags: Optional[list[str]] = None
+    metadata: Optional[dict[str, Any]] = None
+    created_at: Optional[str] = None
+    updated_at: Optional[str] = None
+
+
+# ─── Collection download ───────────────────────────────────────────────────────
+
+
+@dataclass
+class CollectionDownloadResult:
+    """Returned by :meth:`DataeraiClient.download_collection` once all transfers are queued."""
+
+    collection_id: str
+    asset_count: int
+    transfers: list[DownloadResult] = field(default_factory=list)

dataerai/_version.py

@@ -0,0 +1,12 @@
+"""Single source of truth for the SDK's release *floor*.
+
+Hand-set ``MAJOR.MINOR`` here to start a new release line (a minor/major
+release) — that is the "easy to set" knob. The *patch* digit is the floor for
+a fresh line; CI auto-promotes the patch from the published git tags on every
+release to the stable channel, so you normally never touch it.
+
+See ``packaging/version.py`` (the ``compute_version`` brain) and
+``doc/runbooks/20260616_SDK_CLI_PyPI_Publish_Runbook.md``.
+"""
+
+__version__ = "0.1.0"