postbase 0.1.0__py3-none-any.whl

postbase/__init__.py

@@ -0,0 +1,89 @@
+"""postbase — the official Python client for Postbase.
+
+Postbase is a self-hosted, open-source backend-as-a-service built on
+PostgreSQL: a REST query API, authentication, file storage, and row-level
+security.
+
+Quick start (sync)::
+
+    from postbase import create_client
+
+    postbase = create_client(
+        "https://your-postbase-instance.com",
+        "pb_anon_your_api_key",
+        project_id="your-project-id",
+    )
+    result = postbase.from_("posts").select().eq("status", "published").execute()
+
+Quick start (async)::
+
+    from postbase.aio import create_async_client
+
+    postbase = create_async_client(
+        "https://your-postbase-instance.com",
+        "pb_anon_your_api_key",
+        project_id="your-project-id",
+    )
+    result = await postbase.from_("posts").select().eq("status", "published").execute()
+"""
+
+from .auth import AuthAdminClient, AuthClient
+from .client import Client, create_client
+from .email import EmailClient
+from .query import DeleteBuilder, InsertBuilder, QueryBuilder, UpdateBuilder
+from .storage import StorageBucketClient, StorageClient
+from .types import (
+    AuthChangeEvent,
+    AuthResponse,
+    AuthUser,
+    Bucket,
+    Cookie,
+    CookieAdapter,
+    CookieToSet,
+    Filter,
+    FilterOperator,
+    JoinClause,
+    JoinType,
+    NativeOAuthProvider,
+    QueryResult,
+    RealtimeEvent,
+    RealtimePayload,
+    Session,
+    SingleResult,
+    StorageObject,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "create_client",
+    "Client",
+    "QueryBuilder",
+    "InsertBuilder",
+    "UpdateBuilder",
+    "DeleteBuilder",
+    "AuthClient",
+    "AuthAdminClient",
+    "StorageClient",
+    "StorageBucketClient",
+    "EmailClient",
+    "AuthUser",
+    "Session",
+    "AuthResponse",
+    "AuthChangeEvent",
+    "NativeOAuthProvider",
+    "Filter",
+    "FilterOperator",
+    "JoinClause",
+    "JoinType",
+    "QueryResult",
+    "SingleResult",
+    "StorageObject",
+    "Bucket",
+    "RealtimeEvent",
+    "RealtimePayload",
+    "Cookie",
+    "CookieToSet",
+    "CookieAdapter",
+    "__version__",
+]

postbase/_internal.py

@@ -0,0 +1,158 @@
+"""Internal helpers shared by the sync and async clients.
+
+Not part of the public API — names here may change without notice.
+"""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import os
+import secrets
+from typing import Any, Dict, List, Tuple
+
+from .types import Filter
+
+
+def base64url_encode(raw: bytes) -> str:
+    return base64.urlsafe_b64encode(raw).rstrip(b"=").decode("ascii")
+
+
+def generate_code_verifier() -> str:
+    return base64url_encode(os.urandom(32))
+
+
+def generate_code_challenge(verifier: str) -> str:
+    digest = hashlib.sha256(verifier.encode("ascii")).digest()
+    return base64url_encode(digest)
+
+
+def generate_state() -> str:
+    return base64url_encode(os.urandom(16))
+
+
+def random_verifier_pair() -> Tuple[str, str, str]:
+    """Returns (code_verifier, code_challenge, state) for a PKCE OAuth flow."""
+    verifier = generate_code_verifier()
+    challenge = generate_code_challenge(verifier)
+    state = generate_state()
+    return verifier, challenge, state
+
+
+def secure_token() -> str:
+    return secrets.token_urlsafe(24)
+
+
+# ─── Column parsing (SELECT "col AS alias" support) ────────────────────────
+
+
+class ParsedColumn:
+    __slots__ = ("col", "alias")
+
+    def __init__(self, col: str, alias: str) -> None:
+        self.col = col
+        self.alias = alias
+
+
+def parse_columns(columns: str) -> List[ParsedColumn]:
+    parsed: List[ParsedColumn] = []
+    for raw in columns.split(","):
+        part = raw.strip()
+        lower = part.lower()
+        as_idx = -1
+        i = 0
+        while True:
+            idx = lower.find(" as ", i)
+            if idx == -1:
+                break
+            as_idx = idx
+            i = idx + 1
+        if as_idx == -1:
+            parsed.append(ParsedColumn(part, part))
+            continue
+        col = part[:as_idx].strip()
+        alias = part[as_idx + 4 :].strip()
+        parsed.append(ParsedColumn(col, alias))
+    return parsed
+
+
+def apply_aliases(rows: List[Dict[str, Any]], parsed: List[ParsedColumn]) -> List[Dict[str, Any]]:
+    alias_map: Dict[str, str] = {}
+    for p in parsed:
+        if p.col != p.alias:
+            server_key = p.col.split(".")[-1] if "." in p.col else p.col
+            alias_map.setdefault(server_key, p.alias)
+    if not alias_map:
+        return rows
+    out: List[Dict[str, Any]] = []
+    for row in rows:
+        new_row: Dict[str, Any] = {}
+        for k, v in row.items():
+            new_row[alias_map.get(k, k)] = v
+        out.append(new_row)
+    return out
+
+
+# ─── OR filter string parser ────────────────────────────────────────────────
+#
+# Parses Supabase/postbasejs-style filter strings into structured Filter lists.
+#   "email.ilike.%foo%,name.ilike.%foo%"  -> [Filter, Filter]
+#   "status.eq.active,age.gt.18"          -> [Filter, Filter]
+#   "role.in.(admin,owner)"               -> [Filter(op="in", value=[...])]
+#
+# The value is everything after the second dot, so dots in values are safe.
+# Commas inside balanced parentheses (for the `in` operator) are not split on.
+
+
+def parse_or_filter_string(filter_str: str) -> List[Filter]:
+    segments: List[str] = []
+    depth = 0
+    start = 0
+    for i, ch in enumerate(filter_str):
+        if ch == "(":
+            depth += 1
+        elif ch == ")":
+            depth -= 1
+        elif ch == "," and depth == 0:
+            segments.append(filter_str[start:i].strip())
+            start = i + 1
+    segments.append(filter_str[start:].strip())
+
+    filters: List[Filter] = []
+    for seg in segments:
+        if not seg:
+            continue
+        first_dot = seg.find(".")
+        second_dot = seg.find(".", first_dot + 1)
+        if first_dot == -1 or second_dot == -1:
+            filters.append(Filter(column=seg, operator="eq", value=None))
+            continue
+        column = seg[:first_dot]
+        operator = seg[first_dot + 1 : second_dot]
+        raw_value = seg[second_dot + 1 :]
+
+        value: Any = raw_value
+        if operator == "in":
+            inner = raw_value
+            if inner.startswith("("):
+                inner = inner[1:]
+            if inner.endswith(")"):
+                inner = inner[:-1]
+            value = [v.strip() for v in inner.split(",")]
+        elif raw_value == "true":
+            value = True
+        elif raw_value == "false":
+            value = False
+        elif raw_value == "null":
+            value = None
+
+        filters.append(Filter(column=column, operator=operator, value=value))  # type: ignore[arg-type]
+    return filters
+
+
+def filter_to_dict(f: Filter) -> Dict[str, Any]:
+    return {"column": f.column, "operator": f.operator, "value": f.value}
+
+
+def filters_to_dicts(filters: List[Filter]) -> List[Dict[str, Any]]:
+    return [filter_to_dict(f) for f in filters]

postbase/_query_state.py

@@ -0,0 +1,100 @@
+"""Query state shared by sync and async query builders."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field, replace
+from typing import Any, Dict, List, Literal, Optional, Union
+
+from .types import Filter, JoinClause, OrderBy
+
+Operation = Literal["select", "insert", "update", "delete", "upsert"]
+
+
+@dataclass(frozen=True)
+class QueryState:
+    base_url: str
+    api_key: str
+    table: str
+    columns: str = "*"
+    select_count: Optional[str] = None
+    select_head: Optional[bool] = None
+    filters: List[Filter] = field(default_factory=list)
+    or_filters: List[List[Filter]] = field(default_factory=list)
+    not_filters: List[Dict[str, Any]] = field(default_factory=list)
+    order_by: List[OrderBy] = field(default_factory=list)
+    joins: List[JoinClause] = field(default_factory=list)
+    limit_: Optional[int] = None
+    offset_: Optional[int] = None
+    range_: Optional[Dict[str, int]] = None
+    operation: Operation = "select"
+    insert_data: Optional[Union[Dict[str, Any], List[Dict[str, Any]]]] = None
+    upsert_on_conflict: Optional[str] = None
+    update_data: Optional[Dict[str, Any]] = None
+    returning: Optional[str] = None
+    extra_headers: Dict[str, str] = field(default_factory=dict)
+    session_token: Optional[str] = None
+
+    def evolve(self, **changes: Any) -> QueryState:
+        return replace(self, **changes)
+
+
+def build_request_body(state: QueryState) -> Dict[str, Any]:
+    body: Dict[str, Any] = {
+        "operation": "upsert" if state.operation == "upsert" else state.operation,
+        "table": state.table,
+    }
+
+    parsed_columns = None
+    if state.operation == "select":
+        if state.columns and state.columns != "*":
+            from ._internal import parse_columns
+
+            parsed_columns = parse_columns(state.columns)
+            body["columns"] = [p.col for p in parsed_columns]
+        if state.select_count is not None:
+            body["count"] = state.select_count
+        if state.select_head is not None:
+            body["head"] = state.select_head
+        if state.joins:
+            body["joins"] = [
+                {"table": j.table, "on": j.on, **({"type": j.type} if j.type else {})}
+                for j in state.joins
+            ]
+
+    if state.operation in ("select", "update", "delete"):
+        from ._internal import filters_to_dicts
+
+        if state.filters:
+            body["filters"] = filters_to_dicts(state.filters)
+        if state.or_filters:
+            body["orFilters"] = [filters_to_dicts(group) for group in state.or_filters]
+        if state.not_filters:
+            body["notFilters"] = state.not_filters
+
+    if state.operation in ("insert", "upsert"):
+        body["data"] = state.insert_data
+        if state.upsert_on_conflict:
+            body["onConflict"] = state.upsert_on_conflict
+
+    if state.operation == "update":
+        body["data"] = state.update_data
+
+    if state.order_by:
+        body["order"] = [
+            {
+                "column": o.column,
+                **({"ascending": o.ascending} if o.ascending is not None else {}),
+                **({"nullsFirst": o.nulls_first} if o.nulls_first is not None else {}),
+            }
+            for o in state.order_by
+        ]
+    if state.limit_ is not None:
+        body["limit"] = state.limit_
+    if state.offset_ is not None:
+        body["offset"] = state.offset_
+    if state.range_ is not None:
+        body["range"] = state.range_
+    if state.returning:
+        body["returning"] = state.returning
+
+    return body

postbase/aio/__init__.py

@@ -0,0 +1,25 @@
+"""postbase.aio — asynchronous Postbase client (httpx.AsyncClient based).
+
+Use this in async web frameworks (FastAPI, Starlette, aiohttp servers) or
+async scripts. See `postbase` (the top-level package) for the sync client.
+"""
+
+from .auth import AsyncAuthAdminClient, AsyncAuthClient
+from .client import AsyncClient, create_async_client
+from .email import AsyncEmailClient
+from .query import AsyncDeleteBuilder, AsyncInsertBuilder, AsyncQueryBuilder, AsyncUpdateBuilder
+from .storage import AsyncStorageBucketClient, AsyncStorageClient
+
+__all__ = [
+    "create_async_client",
+    "AsyncClient",
+    "AsyncQueryBuilder",
+    "AsyncInsertBuilder",
+    "AsyncUpdateBuilder",
+    "AsyncDeleteBuilder",
+    "AsyncAuthClient",
+    "AsyncAuthAdminClient",
+    "AsyncStorageClient",
+    "AsyncStorageBucketClient",
+    "AsyncEmailClient",
+]