pyronites 0.1.0__py3-none-any.whl

pyronites/__init__.py

@@ -0,0 +1,14 @@
+"""pyronites — official Python client for the Pyronites backend."""
+
+from pyronites.client import create_client
+from pyronites.errors import ApiError, AuthError, NotFoundError
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "create_client",
+    "ApiError",
+    "AuthError",
+    "NotFoundError",
+    "__version__",
+]

pyronites/auth.py

@@ -0,0 +1,45 @@
+"""Auth methods for the pyronites client."""
+
+from __future__ import annotations
+
+from typing import Any, Dict, Optional
+
+from pyronites.errors import AuthError
+from pyronites.http import HttpTransport
+
+
+class AuthClient:
+    def __init__(self, transport: HttpTransport) -> None:
+        self._http = transport
+        self._user: Optional[Dict[str, Any]] = None
+
+    def sign_up(self, email: str, password: str) -> Dict[str, Any]:
+        data = self._http.request(
+            "POST", "/auth/signup",
+            json={"email": email, "password": password},
+        )
+        self._user = data
+        return data  # type: ignore[return-value]
+
+    def sign_in(self, email: str, password: str) -> Dict[str, Any]:
+        data = self._http.request(
+            "POST", "/auth/login",
+            json={"email": email, "password": password},
+        )
+        self._user = data
+        return data  # type: ignore[return-value]
+
+    def sign_out(self) -> None:
+        try:
+            self._http.request("POST", "/auth/logout")
+        finally:
+            self._user = None
+
+    def user(self) -> Optional[Dict[str, Any]]:
+        try:
+            data = self._http.request("GET", "/auth/me")
+            self._user = data
+            return data  # type: ignore[return-value]
+        except AuthError:
+            self._user = None
+            return None

pyronites/client.py

@@ -0,0 +1,121 @@
+"""Main façade for the pyronites client."""
+
+from __future__ import annotations
+
+from typing import Optional, Sequence
+
+from pyronites.auth import AuthClient
+from pyronites.config import ClientConfig, load_config
+from pyronites.errors import ApiError
+from pyronites.http import HttpTransport
+from pyronites.local import LocalStore
+from pyronites.storage import StorageClient
+from pyronites.table import TableQuery
+
+
+class PyronitesClient:
+    """High-level client. Prefer ``create_client()`` over constructing this directly."""
+
+    def __init__(self, config: ClientConfig) -> None:
+        self._config = config
+        self._http = HttpTransport(config)
+        self.auth = AuthClient(self._http)
+        self.storage = StorageClient(self._http)
+        self._local: Optional[LocalStore] = None
+        if config.local_db_path or config.local_tables or config.cache_tables:
+            path = config.local_db_path or "./.pyronites_local.db"
+            self._local = LocalStore(path)
+
+    def table(self, name: str) -> TableQuery:
+        """Return a fluent table handle for the given table name."""
+        if not name or not isinstance(name, str):
+            raise ApiError("table name must be a non-empty string")
+        policy = self._config.table_policy(name)
+        return TableQuery(self._http, name, policy=policy, local=self._local)
+
+    def tables(self) -> list:
+        """List user tables with row counts. Maps to ``GET /tables``."""
+        result = self._http.request("GET", "/tables")
+        return result if isinstance(result, list) else []
+
+    def sql(self, query: str) -> dict:
+        """Execute raw SQL (admin-scoped key required)."""
+        return self._http.request(  # type: ignore[return-value]
+            "POST", "/sql/execute", json={"sql": query},
+        )
+
+    def pull(self, table: str) -> int:
+        """Fetch all remote rows and replace the local copy. Remote wins."""
+        if self._local is None:
+            raise ApiError(
+                "Local store is not configured. Pass local_db_path=... "
+                "or list local_tables/cache_tables on create_client()."
+            )
+        rows = self._http.request("GET", f"/tables/{table}", params={"limit": 200})
+        if not isinstance(rows, list):
+            rows = []
+        return self._local.replace_all(table, rows)
+
+    def push(self, table: str) -> int:
+        """Push local rows to remote. Local-only tables cannot be pushed."""
+        if self._local is None:
+            raise ApiError("Local store is not configured.")
+        if self._config.table_policy(table) == "local":
+            raise ApiError(
+                f"Table {table!r} is local-only and cannot be pushed to the backend."
+            )
+        rows = self._local.all_rows(table)
+        count = 0
+        for row in rows:
+            row_id = row.get("id")
+            if not row_id:
+                self._http.request("POST", f"/tables/{table}", json=row)
+                count += 1
+                continue
+            try:
+                self._http.request(
+                    "PATCH", f"/tables/{table}/{row_id}",
+                    json={k: v for k, v in row.items() if k != "id"},
+                )
+                count += 1
+            except ApiError as e:
+                if e.status_code == 404 or e.code == "not_found":
+                    self._http.request("POST", f"/tables/{table}", json=row)
+                    count += 1
+                else:
+                    raise
+        return count
+
+    def sync(self, table: str) -> int:
+        """v1 policy: remote wins → equivalent to pull."""
+        return self.pull(table)
+
+    def close(self) -> None:
+        self._http.close()
+        if self._local is not None:
+            self._local.close()
+
+    def __enter__(self) -> "PyronitesClient":
+        return self
+
+    def __exit__(self, *args: object) -> None:
+        self.close()
+
+
+def create_client(
+    url: Optional[str] = None,
+    key: Optional[str] = None,
+    timeout: float = 30.0,
+    local_tables: Optional[Sequence[str]] = None,
+    remote_tables: Optional[Sequence[str]] = None,
+    cache_tables: Optional[Sequence[str]] = None,
+    local_db_path: Optional[str] = None,
+) -> PyronitesClient:
+    config = load_config(
+        url=url, key=key, timeout=timeout,
+        local_tables=local_tables,
+        remote_tables=remote_tables,
+        cache_tables=cache_tables,
+        local_db_path=local_db_path,
+    )
+    return PyronitesClient(config)

pyronites/config.py

@@ -0,0 +1,80 @@
+"""Configuration resolution for the pyronites client."""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+from typing import FrozenSet, Optional, Sequence
+
+from pyronites.errors import ApiError
+
+POLICY_REMOTE = "remote"
+POLICY_LOCAL = "local"
+POLICY_CACHE = "cache"
+
+
+@dataclass(frozen=True)
+class ClientConfig:
+    """Resolved client configuration."""
+
+    url: str
+    key: Optional[str]
+    timeout: float = 30.0
+    local_tables: FrozenSet[str] = field(default_factory=frozenset)
+    remote_tables: FrozenSet[str] = field(default_factory=frozenset)
+    cache_tables: FrozenSet[str] = field(default_factory=frozenset)
+    local_db_path: Optional[str] = None
+
+    def table_policy(self, name: str) -> str:
+        """Return policy for a table: local, cache, or remote (default).
+
+        Priority: local_tables > cache_tables > remote (default).
+        """
+        if name in self.local_tables:
+            return POLICY_LOCAL
+        if name in self.cache_tables:
+            return POLICY_CACHE
+        return POLICY_REMOTE
+
+
+def _normalize_url(url: str) -> str:
+    return url.rstrip("/")
+
+
+def _to_frozenset(names: Optional[Sequence[str]]) -> FrozenSet[str]:
+    if not names:
+        return frozenset()
+    return frozenset(str(n) for n in names)
+
+
+def load_config(
+    url: Optional[str] = None,
+    key: Optional[str] = None,
+    timeout: float = 30.0,
+    local_tables: Optional[Sequence[str]] = None,
+    remote_tables: Optional[Sequence[str]] = None,
+    cache_tables: Optional[Sequence[str]] = None,
+    local_db_path: Optional[str] = None,
+) -> ClientConfig:
+    resolved_url = url if url is not None else os.environ.get("PYRONITES_URL")
+    resolved_key = key if key is not None else os.environ.get("PYRONITES_KEY")
+
+    if not resolved_url:
+        raise ApiError(
+            "Missing backend URL. Pass url=... to create_client() "
+            "or set the PYRONITES_URL environment variable."
+        )
+
+    path = local_db_path
+    if path is None:
+        path = os.environ.get("PYRONITES_LOCAL_DB")
+
+    return ClientConfig(
+        url=_normalize_url(resolved_url),
+        key=resolved_key or None,
+        timeout=timeout,
+        local_tables=_to_frozenset(local_tables),
+        remote_tables=_to_frozenset(remote_tables),
+        cache_tables=_to_frozenset(cache_tables),
+        local_db_path=path,
+    )

pyronites/errors.py

@@ -0,0 +1,40 @@
+"""Typed exceptions raised by the pyronites client."""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+
+class ApiError(Exception):
+    """Base error for non-2xx API responses and client-side validation failures."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: Optional[int] = None,
+        code: Optional[str] = None,
+        body: Any = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.status_code = status_code
+        self.code = code
+        self.body = body
+
+    def __str__(self) -> str:
+        parts = []
+        if self.status_code is not None:
+            parts.append(str(self.status_code))
+        if self.code:
+            parts.append(self.code)
+        parts.append(self.message)
+        return " ".join(parts)
+
+
+class AuthError(ApiError):
+    """Raised for 401 / 403 responses."""
+
+
+class NotFoundError(ApiError):
+    """Raised for 404 responses."""

pyronites/http.py

@@ -0,0 +1,124 @@
+"""HTTP transport layer for the pyronites client."""
+
+from __future__ import annotations
+
+import time
+from typing import Any, Dict, Optional, Set
+
+import httpx
+
+from pyronites.config import ClientConfig
+from pyronites.errors import ApiError, AuthError, NotFoundError
+
+_RETRYABLE_STATUS: Set[int] = {502, 503, 504}
+_DEFAULT_MAX_RETRIES = 2
+_DEFAULT_BACKOFF_BASE = 0.3
+
+
+class HttpTransport:
+    """Thin wrapper around ``httpx.Client`` with auth headers, retries, and error mapping."""
+
+    def __init__(
+        self,
+        config: ClientConfig,
+        *,
+        max_retries: int = _DEFAULT_MAX_RETRIES,
+        backoff_base: float = _DEFAULT_BACKOFF_BASE,
+    ) -> None:
+        self._config = config
+        self._max_retries = max(0, max_retries)
+        self._backoff_base = backoff_base
+        headers: Dict[str, str] = {}
+        if config.key:
+            headers["Authorization"] = f"Bearer {config.key}"
+        self._client = httpx.Client(
+            base_url=config.url,
+            headers=headers,
+            timeout=config.timeout,
+            follow_redirects=True,
+        )
+
+    @property
+    def config(self) -> ClientConfig:
+        return self._config
+
+    def close(self) -> None:
+        self._client.close()
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: Any = None,
+        params: Optional[Dict[str, Any]] = None,
+        files: Any = None,
+        data: Any = None,
+    ) -> Any:
+        """Perform a request with conservative retries on transient failures."""
+        if not path.startswith("/"):
+            path = "/" + path
+
+        last_exc: Optional[Exception] = None
+        attempts = self._max_retries + 1
+
+        for attempt in range(attempts):
+            try:
+                response = self._client.request(
+                    method, path, json=json, params=params, files=files, data=data,
+                )
+            except httpx.TimeoutException as exc:
+                last_exc = ApiError(f"Request timed out after {self._config.timeout}s")
+                last_exc.__cause__ = exc
+                if attempt < self._max_retries:
+                    time.sleep(self._backoff_base * (2 ** attempt))
+                    continue
+                raise last_exc from exc
+            except httpx.RequestError as exc:
+                last_exc = ApiError(f"Network error: {exc}")
+                last_exc.__cause__ = exc
+                if attempt < self._max_retries:
+                    time.sleep(self._backoff_base * (2 ** attempt))
+                    continue
+                raise last_exc from exc
+
+            if response.status_code in _RETRYABLE_STATUS and attempt < self._max_retries:
+                time.sleep(self._backoff_base * (2 ** attempt))
+                continue
+
+            return self._handle_response(response)
+
+        if last_exc is not None:
+            raise last_exc
+        raise ApiError("Request failed after retries")
+
+    def _handle_response(self, response: httpx.Response) -> Any:
+        if 200 <= response.status_code < 300:
+            if not response.content:
+                return None
+            try:
+                return response.json()
+            except ValueError:
+                return response.content
+
+        code: Optional[str] = None
+        message = response.text or f"HTTP {response.status_code}"
+        body: Any = None
+        try:
+            body = response.json()
+            detail = body.get("detail") if isinstance(body, dict) else None
+            if isinstance(detail, dict):
+                code = detail.get("code")
+                message = detail.get("message") or message
+            elif isinstance(body, dict):
+                code = body.get("code")
+                message = body.get("message") or message
+        except ValueError:
+            pass
+
+        status = response.status_code
+        if status in (401, 403):
+            raise AuthError(message, status_code=status, code=code, body=body)
+        if status == 404:
+            raise NotFoundError(message, status_code=status, code=code, body=body)
+        raise ApiError(message, status_code=status, code=code, body=body)

pyronites/local.py

@@ -0,0 +1,128 @@
+"""Local SQLite store for local-only and cache tables (Phase P3)."""
+
+from __future__ import annotations
+
+import json
+import sqlite3
+import uuid
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+from pyronites.errors import ApiError
+
+
+class LocalStore:
+    """Minimal JSON-row store backed by SQLite."""
+
+    def __init__(self, path: str) -> None:
+        self._path = path
+        Path(path).parent.mkdir(parents=True, exist_ok=True)
+        self._conn = sqlite3.connect(path)
+        self._conn.row_factory = sqlite3.Row
+
+    def close(self) -> None:
+        self._conn.close()
+
+    def _ensure_table(self, name: str) -> None:
+        if not name.replace("_", "").isalnum():
+            raise ApiError(f"Invalid local table name: {name!r}")
+        self._conn.execute(
+            f'CREATE TABLE IF NOT EXISTS "{name}" ('
+            "id TEXT PRIMARY KEY, "
+            "data TEXT NOT NULL"
+            ")"
+        )
+        self._conn.commit()
+
+    def select(
+        self,
+        table: str,
+        *,
+        filter_column: Optional[str] = None,
+        filter_value: Optional[str] = None,
+        limit: Optional[int] = None,
+        offset: Optional[int] = None,
+    ) -> List[Dict[str, Any]]:
+        self._ensure_table(table)
+        cur = self._conn.execute(f'SELECT id, data FROM "{table}"')
+        rows: List[Dict[str, Any]] = []
+        for r in cur.fetchall():
+            row = json.loads(r["data"])
+            if "id" not in row:
+                row["id"] = r["id"]
+            if filter_column is not None and filter_value is not None:
+                if str(row.get(filter_column)) != str(filter_value):
+                    continue
+            rows.append(row)
+        if offset:
+            rows = rows[offset:]
+        if limit is not None:
+            rows = rows[:limit]
+        return rows
+
+    def get(self, table: str, row_id: str) -> Optional[Dict[str, Any]]:
+        self._ensure_table(table)
+        cur = self._conn.execute(
+            f'SELECT data FROM "{table}" WHERE id = ?', (row_id,)
+        )
+        r = cur.fetchone()
+        if not r:
+            return None
+        row = json.loads(r["data"])
+        if "id" not in row:
+            row["id"] = row_id
+        return row
+
+    def insert(self, table: str, row: Dict[str, Any]) -> Dict[str, Any]:
+        self._ensure_table(table)
+        data = dict(row)
+        row_id = data.get("id")
+        if not row_id:
+            row_id = str(uuid.uuid4())
+            data["id"] = row_id
+        else:
+            row_id = str(row_id)
+            data["id"] = row_id
+        self._conn.execute(
+            f'INSERT OR REPLACE INTO "{table}" (id, data) VALUES (?, ?)',
+            (row_id, json.dumps(data)),
+        )
+        self._conn.commit()
+        return data
+
+    def update(self, table: str, row_id: str, data: Dict[str, Any]) -> Dict[str, Any]:
+        existing = self.get(table, row_id)
+        if existing is None:
+            raise ApiError("Row not found", status_code=404, code="not_found")
+        merged = {**existing, **data, "id": row_id}
+        self._conn.execute(
+            f'UPDATE "{table}" SET data = ? WHERE id = ?',
+            (json.dumps(merged), row_id),
+        )
+        self._conn.commit()
+        return merged
+
+    def delete(self, table: str, row_id: str) -> Dict[str, Any]:
+        existing = self.get(table, row_id)
+        if existing is None:
+            raise ApiError("Row not found", status_code=404, code="not_found")
+        self._conn.execute(f'DELETE FROM "{table}" WHERE id = ?', (row_id,))
+        self._conn.commit()
+        return {"message": "Row deleted"}
+
+    def replace_all(self, table: str, rows: List[Dict[str, Any]]) -> int:
+        self._ensure_table(table)
+        self._conn.execute(f'DELETE FROM "{table}"')
+        for row in rows:
+            data = dict(row)
+            row_id = str(data.get("id") or uuid.uuid4())
+            data["id"] = row_id
+            self._conn.execute(
+                f'INSERT INTO "{table}" (id, data) VALUES (?, ?)',
+                (row_id, json.dumps(data)),
+            )
+        self._conn.commit()
+        return len(rows)
+
+    def all_rows(self, table: str) -> List[Dict[str, Any]]:
+        return self.select(table)

pyronites/storage.py

@@ -0,0 +1,140 @@
+"""Storage methods for the pyronites client."""
+
+from __future__ import annotations
+
+import mimetypes
+from pathlib import Path
+from typing import Any, BinaryIO, Dict, List, Optional, Union
+
+from pyronites.errors import ApiError
+from pyronites.http import HttpTransport
+
+
+class StorageClient:
+    """Client for ``/storage/*`` routes."""
+
+    def __init__(self, transport: HttpTransport) -> None:
+        self._http = transport
+
+    def upload(
+        self,
+        source: Union[str, Path, BinaryIO, bytes],
+        *,
+        filename: Optional[str] = None,
+        content_type: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """Upload a file.
+
+        Parameters
+        ----------
+        source:
+            Path string, ``Path``, open binary file, or raw ``bytes``.
+        filename:
+            Required when ``source`` is bytes or a file object without a name.
+        content_type:
+            Optional MIME type; guessed from filename when omitted.
+
+        Returns
+        -------
+        dict
+            Metadata matching backend shape:
+            ``id``, ``original_filename``, ``content_type``, ``size_bytes``,
+            ``uploaded_at``, ``project_id``.
+        """
+        name, data, ctype = self._resolve_upload(source, filename, content_type)
+        files = {"file": (name, data, ctype)}
+        result = self._http.request("POST", "/storage/upload", files=files)
+        if not isinstance(result, dict):
+            raise ApiError("Unexpected response from storage upload")
+        return result
+
+    def list(
+        self,
+        *,
+        prefix: Optional[str] = None,
+        limit: int = 50,
+        offset: int = 0,
+    ) -> List[Dict[str, Any]]:
+        """List stored files (newest first).
+
+        Maps to ``GET /storage``.
+        """
+        params: Dict[str, Any] = {"limit": limit, "offset": offset}
+        if prefix is not None:
+            params["prefix"] = prefix
+        result = self._http.request("GET", "/storage", params=params)
+        return result if isinstance(result, list) else []
+
+    def get(self, file_id: str) -> Dict[str, Any]:
+        """Return metadata for a file.
+
+        Maps to ``GET /storage/{id}``.
+        """
+        result = self._http.request("GET", f"/storage/{file_id}")
+        if not isinstance(result, dict):
+            raise ApiError("Unexpected response from storage get")
+        return result
+
+    def download(
+        self,
+        file_id: str,
+        *,
+        path: Optional[Union[str, Path]] = None,
+    ) -> bytes:
+        """Download file bytes.
+
+        Maps to ``GET /storage/{id}/download``.
+
+        If ``path`` is given, also writes the bytes to that filesystem path.
+        """
+        data = self._http.request("GET", f"/storage/{file_id}/download")
+        if isinstance(data, dict):
+            raise ApiError("Unexpected JSON response from storage download")
+        if not isinstance(data, (bytes, bytearray)):
+            data = bytes(data) if data is not None else b""
+        else:
+            data = bytes(data)
+
+        if path is not None:
+            Path(path).write_bytes(data)
+        return data
+
+    def remove(self, file_id: str) -> Dict[str, Any]:
+        """Delete a file.
+
+        Maps to ``DELETE /storage/{id}``.
+        """
+        result = self._http.request("DELETE", f"/storage/{file_id}")
+        return result if isinstance(result, dict) else {"message": "File deleted successfully"}
+
+    def _resolve_upload(
+        self,
+        source: Union[str, Path, BinaryIO, bytes],
+        filename: Optional[str],
+        content_type: Optional[str],
+    ) -> tuple[str, bytes, str]:
+        if isinstance(source, (str, Path)):
+            p = Path(source)
+            if not p.is_file():
+                raise ApiError(f"File not found: {p}")
+            name = filename or p.name
+            data = p.read_bytes()
+        elif isinstance(source, (bytes, bytearray)):
+            if not filename:
+                raise ApiError("filename is required when uploading raw bytes")
+            name = filename
+            data = bytes(source)
+        else:
+            name = filename
+            if not name:
+                name = getattr(source, "name", None)
+                if name:
+                    name = Path(name).name
+            if not name:
+                raise ApiError("filename is required when uploading a file object without a name")
+            data = source.read()
+            if isinstance(data, str):
+                data = data.encode("utf-8")
+
+        ctype = content_type or mimetypes.guess_type(name)[0] or "application/octet-stream"
+        return name, data, ctype

pyronites/table.py

@@ -0,0 +1,217 @@
+"""Table (database) methods for the pyronites client."""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional, Union
+
+from pyronites.config import POLICY_CACHE, POLICY_LOCAL, POLICY_REMOTE
+from pyronites.errors import ApiError, NotFoundError
+from pyronites.http import HttpTransport
+from pyronites.local import LocalStore
+
+
+class TableQuery:
+    """Fluent builder for table operations on a single table."""
+
+    def __init__(
+        self,
+        transport: HttpTransport,
+        name: str,
+        *,
+        policy: str = POLICY_REMOTE,
+        local: Optional[LocalStore] = None,
+    ) -> None:
+        self._http = transport
+        self._name = name
+        self._policy = policy
+        self._local = local
+        self._filter_column: Optional[str] = None
+        self._filter_value: Optional[str] = None
+        self._limit: Optional[int] = None
+        self._offset: Optional[int] = None
+        self._update_data: Optional[Dict[str, Any]] = None
+        self._op: Optional[str] = None
+
+    def eq(self, column: str, value: Any) -> Any:
+        """Add a single equality filter. On update/delete, executes immediately."""
+        self._filter_column = column
+        self._filter_value = str(value) if value is not None else None
+        if self._op in ("update", "delete"):
+            return self._dispatch()
+        return self
+
+    def limit(self, n: int) -> "TableQuery":
+        self._limit = n
+        return self
+
+    def offset(self, n: int) -> "TableQuery":
+        self._offset = n
+        return self
+
+    def select(self) -> "TableQuery":
+        self._op = "select"
+        return self
+
+    def insert(
+        self, row: Union[Dict[str, Any], List[Dict[str, Any]]]
+    ) -> Union[Dict[str, Any], List[Dict[str, Any]]]:
+        if isinstance(row, list):
+            return [self._insert_one(r) for r in row]
+        return self._insert_one(row)
+
+    def update(self, data: Dict[str, Any]) -> "TableQuery":
+        if not data:
+            raise ApiError("update() requires a non-empty data dict")
+        self._op = "update"
+        self._update_data = data
+        return self
+
+    def delete(self) -> "TableQuery":
+        self._op = "delete"
+        return self
+
+    def single(self) -> Dict[str, Any]:
+        rows = self._execute_select()
+        if not rows:
+            raise ApiError("No rows returned for .single()", code="not_found")
+        if len(rows) > 1:
+            raise ApiError("Multiple rows returned for .single()")
+        return rows[0]
+
+    def get(self, row_id: str) -> Dict[str, Any]:
+        if self._policy == POLICY_LOCAL:
+            assert self._local is not None
+            row = self._local.get(self._name, row_id)
+            if row is None:
+                raise NotFoundError("Row not found", status_code=404, code="not_found")
+            return row
+
+        if self._policy == POLICY_CACHE and self._local is not None:
+            row = self._local.get(self._name, row_id)
+            if row is not None:
+                return row
+
+        result = self._http.request("GET", f"/tables/{self._name}/{row_id}")
+        if self._policy == POLICY_CACHE and self._local is not None and isinstance(result, dict):
+            self._local.insert(self._name, result)
+        return result  # type: ignore[return-value]
+
+    def schema(self) -> List[Dict[str, Any]]:
+        """Return column definitions. Maps to ``GET /tables/{name}/schema``."""
+        result = self._http.request("GET", f"/tables/{self._name}/schema")
+        return result if isinstance(result, list) else []
+
+    def execute(self) -> Any:
+        return self._dispatch()
+
+    def __iter__(self):
+        return iter(self._execute_select())
+
+    def __call__(self) -> Any:
+        return self._dispatch()
+
+    def _require_local(self) -> LocalStore:
+        if self._local is None:
+            raise ApiError(
+                "Local store is not configured. Pass local_db_path=... to create_client()."
+            )
+        return self._local
+
+    def _insert_one(self, row: Dict[str, Any]) -> Dict[str, Any]:
+        if self._policy == POLICY_LOCAL:
+            return self._require_local().insert(self._name, row)
+
+        result = self._http.request(
+            "POST", f"/tables/{self._name}", json=row,
+        )  # type: ignore[return-value]
+        if self._policy == POLICY_CACHE and self._local is not None and isinstance(result, dict):
+            self._local.insert(self._name, result)
+        return result
+
+    def _execute_select(self) -> List[Dict[str, Any]]:
+        if self._policy == POLICY_LOCAL:
+            return self._require_local().select(
+                self._name,
+                filter_column=self._filter_column,
+                filter_value=self._filter_value,
+                limit=self._limit,
+                offset=self._offset,
+            )
+
+        if self._policy == POLICY_CACHE and self._local is not None:
+            local_rows = self._local.select(
+                self._name,
+                filter_column=self._filter_column,
+                filter_value=self._filter_value,
+                limit=self._limit,
+                offset=self._offset,
+            )
+            if local_rows:
+                return local_rows
+            remote_rows = self._select_remote()
+            if remote_rows:
+                self._local.replace_all(self._name, remote_rows)
+            return remote_rows
+
+        return self._select_remote()
+
+    def _select_remote(self) -> List[Dict[str, Any]]:
+        params: Dict[str, Any] = {}
+        if self._limit is not None:
+            params["limit"] = self._limit
+        if self._offset is not None:
+            params["offset"] = self._offset
+        if self._filter_column is not None and self._filter_value is not None:
+            params["filter_column"] = self._filter_column
+            params["filter_value"] = self._filter_value
+        result = self._http.request(
+            "GET", f"/tables/{self._name}", params=params or None,
+        )
+        return result if isinstance(result, list) else []
+
+    def _execute_update(self) -> Dict[str, Any]:
+        if self._filter_column != "id" or self._filter_value is None:
+            raise ApiError(
+                'update() currently requires .eq("id", value) '
+                "because the backend only supports update-by-id."
+            )
+        assert self._update_data is not None
+        row_id = self._filter_value
+
+        if self._policy == POLICY_LOCAL:
+            return self._require_local().update(self._name, row_id, self._update_data)
+
+        result = self._http.request(
+            "PATCH", f"/tables/{self._name}/{row_id}", json=self._update_data,
+        )  # type: ignore[return-value]
+        if self._policy == POLICY_CACHE and self._local is not None and isinstance(result, dict):
+            self._local.insert(self._name, result)
+        return result
+
+    def _execute_delete(self) -> Any:
+        if self._filter_column != "id" or self._filter_value is None:
+            raise ApiError(
+                'delete() currently requires .eq("id", value) '
+                "because the backend only supports delete-by-id."
+            )
+        row_id = self._filter_value
+
+        if self._policy == POLICY_LOCAL:
+            return self._require_local().delete(self._name, row_id)
+
+        result = self._http.request("DELETE", f"/tables/{self._name}/{row_id}")
+        if self._policy == POLICY_CACHE and self._local is not None:
+            try:
+                self._local.delete(self._name, row_id)
+            except ApiError:
+                pass
+        return result
+
+    def _dispatch(self) -> Any:
+        if self._op == "select":
+            return self._execute_select()
+        if self._op == "update":
+            return self._execute_update()
+        if self._op == "delete":
+            return self._execute_delete()
+        raise ApiError("No operation specified. Call select(), update(), or delete() first.")

pyronites-0.1.0.dist-info/METADATA

@@ -0,0 +1,109 @@
+Metadata-Version: 2.4
+Name: pyronites
+Version: 0.1.0
+Summary: Official Python client for the Pyronites (PyroCore) backend
+Project-URL: Homepage, https://github.com/Ashutosh3021/Pyronites
+Project-URL: Repository, https://github.com/Ashutosh3021/Pyronites
+Project-URL: Documentation, https://github.com/Ashutosh3021/Pyronites/tree/main/pyronites/docs
+Author: Ashutosh
+License: MIT
+Keywords: backend,client,pyrocore,pyronites,sqlite,supabase
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT 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: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27.0
+Provides-Extra: dev
+Requires-Dist: build>=1.0; extra == 'dev'
+Requires-Dist: pytest-httpx>=0.30; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: twine>=5.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# pyronites
+
+Official Python client for the [Pyronites](https://github.com/Ashutosh3021/Pyronites) backend.
+
+Supabase-style API, zero mandatory paid services — point it at your own backend URL + API key.
+
+## Install
+
+```bash
+# Development (from this repo)
+pip install -e ./pyronites
+
+# From PyPI (after publish)
+pip install pyronites
+```
+
+Requires **Python 3.10+**.
+
+## 5-minute setup
+
+```bash
+export PYRONITES_URL="https://your-backend.example.com"
+export PYRONITES_KEY="pyro_live_..."
+```
+
+```python
+from pyronites import create_client
+
+client = create_client()
+
+# Auth (optional)
+client.auth.sign_in("user@example.com", "password")
+print(client.auth.user())
+
+# Tables
+note = client.table("notes").insert({"title": "Hello", "body": "World"})
+for row in client.table("notes").select().limit(10):
+    print(row)
+client.table("notes").update({"title": "Updated"}).eq("id", note["id"])
+client.table("notes").delete().eq("id", note["id"])
+
+# Storage
+meta = client.storage.upload("photo.jpg")
+data = client.storage.download(meta["id"])
+client.storage.remove(meta["id"])
+
+# Local-only / cache tables (optional)
+client = create_client(
+    local_tables=["settings"],
+    cache_tables=["catalog"],
+    local_db_path="./.pyronites_local.db",
+)
+client.table("settings").insert({"theme": "dark"})
+client.pull("catalog")
+```
+
+## Config
+
+| Source | Variables / args |
+|--------|------------------|
+| Env | `PYRONITES_URL`, `PYRONITES_KEY`, optional `PYRONITES_LOCAL_DB` |
+| Constructor | `create_client(url=..., key=..., timeout=30, local_tables=..., cache_tables=..., remote_tables=..., local_db_path=...)` |
+
+Args override env. Missing URL raises a clear error at create time.
+
+**Security:** never put a powerful service key in a public frontend.
+
+## Public API
+
+See [`docs/syntax.md`](docs/syntax.md).
+
+## Development
+
+```bash
+cd pyronites
+pip install -e ".[dev]"
+pytest
+```
+
+## License
+
+MIT

pyronites-0.1.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+pyronites/__init__.py,sha256=t03obFUXOOqA7js4Bjca17CWxUNvXriE_ke_jrPVfFw,324
+pyronites/auth.py,sha256=fnXWWWhMv4BKjTIzEaSk9p7S2H-J0-mltfDlDTUD_mo,1404
+pyronites/client.py,sha256=m6vBrURSOWAXfHtc1kqAHOO4Nsqqr87PW8dCiUWaKfo,4591
+pyronites/config.py,sha256=GwjIU_xQW8sloNqWjg93LHR81O-4bQdJgIri0sDhkR0,2452
+pyronites/errors.py,sha256=1k1gEU79ctDSxDTrt4qoq3kkAQ0omAkjDZTD0RKaLhg,1021
+pyronites/http.py,sha256=PyiwwC_LqRiTQerefCQfvgcXgpfOLcggvw1KW5wl9CY,4288
+pyronites/local.py,sha256=imp5zykRzDwlhjQgyJt36YnP4CGgtdju_69lsbDhXBE,4360
+pyronites/storage.py,sha256=smd0bdkR2gBa2lgXHwRneVf5vN-qMlrit_B-OXqJeHY,4762
+pyronites/table.py,sha256=zSAU8tBEzuugHQhHJZZRZwFZyiEm1qK-tWuop_o50F8,8169
+pyronites-0.1.0.dist-info/METADATA,sha256=CfNkoUUf3hVpq8J2DW3RcKB9JF1SR4P53mbUQMISRVo,2982
+pyronites-0.1.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+pyronites-0.1.0.dist-info/RECORD,,

pyronites-0.1.0.dist-info/WHEEL

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