edgebase-core 0.1.3__tar.gz

edgebase_core-0.1.3/.gitignore

@@ -0,0 +1,11 @@
+__pycache__/
+*.pyc
+*.pyo
+*.egg-info/
+dist/
+build/
+.eggs/
+.pytest_cache/
+.ruff_cache/
+*.egg
+.venv/

edgebase_core-0.1.3/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 melodysdreamj
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

edgebase_core-0.1.3/PKG-INFO

@@ -0,0 +1,70 @@
+Metadata-Version: 2.4
+Name: edgebase-core
+Version: 0.1.3
+Summary: Shared Python core for EdgeBase table, storage, and HTTP primitives
+Author: EdgeBase Team
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Description-Content-Type: text/markdown
+
+# edgebase-core
+
+Shared low-level Python primitives for EdgeBase.
+
+`edgebase-core` is the foundation used by `edgebase` and `edgebase-admin`. It contains the HTTP client, table/query builder, storage helpers, push primitives, field operations, and common error types.
+
+Most application code should install one of these instead:
+
+- `pip install edgebase`
+- `pip install edgebase-admin`
+
+Install `edgebase-core` directly only if you are building custom wrappers, generated bindings, or internal integrations on top of the EdgeBase APIs.
+
+## Docs
+
+- SDK overview: https://edgebase.fun/docs/sdks
+- Database admin SDK: https://edgebase.fun/docs/database/admin-sdk
+- Storage docs: https://edgebase.fun/docs/storage/upload-download
+
+## Quick Start
+
+```python
+from edgebase_core import HttpClient, StorageClient, TableRef
+
+http = HttpClient(
+    "https://your-project.edgebase.fun",
+    service_key="service-key",
+)
+
+posts = (
+    TableRef(http, "shared", None, "posts")
+    .where("published", "==", True)
+    .order_by("createdAt", "desc")
+    .limit(20)
+    .get_list()
+)
+
+bucket = StorageClient(http).bucket("avatars")
+```
+
+## Included Surfaces
+
+- `HttpClient`
+- `TableRef`, `DocRef`, `ListResult`
+- `StorageClient`, `StorageBucket`
+- `PushClient`
+- `FieldOps`, `increment`, `delete_field`
+- `ContextManager`
+- `EdgeBaseError`
+
+## AI Assistant
+
+- Package guide: `packages/sdk/python/packages/core/README.md`
+- Assistant reference: `packages/sdk/python/packages/core/llms.txt`
+
+## Requirements
+
+- Python `3.10+`
+- `httpx>=0.27`

edgebase_core-0.1.3/README.md

@@ -0,0 +1,59 @@
+# edgebase-core
+
+Shared low-level Python primitives for EdgeBase.
+
+`edgebase-core` is the foundation used by `edgebase` and `edgebase-admin`. It contains the HTTP client, table/query builder, storage helpers, push primitives, field operations, and common error types.
+
+Most application code should install one of these instead:
+
+- `pip install edgebase`
+- `pip install edgebase-admin`
+
+Install `edgebase-core` directly only if you are building custom wrappers, generated bindings, or internal integrations on top of the EdgeBase APIs.
+
+## Docs
+
+- SDK overview: https://edgebase.fun/docs/sdks
+- Database admin SDK: https://edgebase.fun/docs/database/admin-sdk
+- Storage docs: https://edgebase.fun/docs/storage/upload-download
+
+## Quick Start
+
+```python
+from edgebase_core import HttpClient, StorageClient, TableRef
+
+http = HttpClient(
+    "https://your-project.edgebase.fun",
+    service_key="service-key",
+)
+
+posts = (
+    TableRef(http, "shared", None, "posts")
+    .where("published", "==", True)
+    .order_by("createdAt", "desc")
+    .limit(20)
+    .get_list()
+)
+
+bucket = StorageClient(http).bucket("avatars")
+```
+
+## Included Surfaces
+
+- `HttpClient`
+- `TableRef`, `DocRef`, `ListResult`
+- `StorageClient`, `StorageBucket`
+- `PushClient`
+- `FieldOps`, `increment`, `delete_field`
+- `ContextManager`
+- `EdgeBaseError`
+
+## AI Assistant
+
+- Package guide: `packages/sdk/python/packages/core/README.md`
+- Assistant reference: `packages/sdk/python/packages/core/llms.txt`
+
+## Requirements
+
+- Python `3.10+`
+- `httpx>=0.27`

edgebase_core-0.1.3/llms.txt

@@ -0,0 +1,86 @@
+# edgebase-core
+
+Use this file as a quick-reference contract for AI coding assistants working with the `edgebase-core` Python package.
+
+## Package Boundary
+
+Use `edgebase-core` for low-level EdgeBase building blocks.
+
+This package is shared infrastructure for `edgebase` and `edgebase-admin`. Most app code should install one of those higher-level packages instead of using `edgebase-core` directly.
+
+`edgebase-core` does not provide a top-level server client, auth convenience helpers, or package-level factories like `create_admin_client(...)`.
+
+## Source Of Truth
+
+- Package README: https://github.com/edge-base/edgebase/blob/main/packages/sdk/python/packages/core/README.md
+- SDK overview: https://edgebase.fun/docs/sdks
+- Database admin SDK: https://edgebase.fun/docs/database/admin-sdk
+- Storage docs: https://edgebase.fun/docs/storage/upload-download
+
+If docs, snippets, and assumptions disagree, prefer the current package API over guessed patterns from another runtime.
+
+## Canonical Examples
+
+### Build a table reference from a custom HTTP client
+
+```python
+from edgebase_core import HttpClient, TableRef
+
+http = HttpClient(
+    "https://your-project.edgebase.fun",
+    service_key="service-key",
+)
+
+posts = TableRef(http, "shared", None, "posts").where("published", "==", True).get_list()
+```
+
+### Use document helpers
+
+```python
+table = TableRef(http, "shared", None, "posts")
+post = table.doc("post-1").get()
+```
+
+### Work with storage directly
+
+```python
+from edgebase_core import StorageClient
+
+storage = StorageClient(http)
+bucket = storage.bucket("avatars")
+bucket.upload("user-1.jpg", file_bytes, content_type="image/jpeg")
+```
+
+## Common Mistakes
+
+- do not expect a top-level `EdgeBaseServer` or `AdminClient` here; those live in higher-level packages
+- `TableRef(http, namespace, instance_id, table_name)` requires the low-level HTTP client as its first argument
+- `table.get()` returns a `ListResult`, not a single record
+- use `table.get_one(id)` or `table.doc(id).get()` for a single record
+- `StorageClient` requires an initialized `HttpClient`
+- `PushClient` exists in this package, but most applications should access push through `edgebase-admin` or `edgebase`
+- `increment` and `delete_field` are aliases from `FieldOps`
+
+## Quick Reference
+
+```python
+http = HttpClient(base_url, service_key=service_key)
+
+table = TableRef(http, "shared", None, "posts")
+table.where("published", "==", True).order_by("createdAt", "desc").limit(20).get_list()
+table.get_one("id-1")
+table.insert({"title": "Hello"})
+table.update("id-1", {"title": "Updated"})
+table.delete("id-1")
+
+doc = DocRef(http, "shared", None, "posts", "id-1")
+doc.get()
+
+storage = StorageClient(http)
+bucket = storage.bucket("avatars")
+bucket.upload("user-1.jpg", file_bytes, content_type="image/jpeg")
+bucket.create_signed_upload_url("large.zip", expires_in=600)
+
+increment(1)
+delete_field()
+```

edgebase_core-0.1.3/pyproject.toml

@@ -0,0 +1,24 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "edgebase-core"
+version = "0.1.3"
+description = "Shared Python core for EdgeBase table, storage, and HTTP primitives"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [
+    { name = "EdgeBase Team" }
+]
+dependencies = ["httpx>=0.27"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/edgebase_core", "README.md", "llms.txt"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/edgebase_core"]
+
+[tool.hatch.build.targets.wheel.force-include]
+"llms.txt" = "edgebase_core/llms.txt"

edgebase_core-0.1.3/src/edgebase_core/__init__.py

@@ -0,0 +1,13 @@
+"""EdgeBase Core SDK — shared types, HTTP client, table, storage."""
+
+from edgebase_core.http_client import HttpClient
+from edgebase_core.table import TableRef, DocRef, ListResult
+from edgebase_core.storage import StorageClient, StorageBucket
+from edgebase_core.field_ops import FieldOps
+from edgebase_core.context_manager import ContextManager
+from edgebase_core.errors import EdgeBaseError
+from edgebase_core.push import PushClient
+
+# Convenience aliases
+increment = FieldOps.increment
+delete_field = FieldOps.delete_field

edgebase_core-0.1.3/src/edgebase_core/context_manager.py

@@ -0,0 +1,27 @@
+"""Context manager for legacy isolateBy compatibility state.
+
+: auth.id isolation uses JWT extraction server-side.
+The 'auth.id' key is silently filtered from context to prevent
+client-side override attempts.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+class ContextManager:
+    """Thread-safe context storage retained for compatibility helpers."""
+
+    def __init__(self) -> None:
+        self._context: dict[str, Any] = {}
+
+    def set_context(self, context: dict[str, Any]) -> None:
+        # Filter out auth.id — server extracts from JWT only
+        self._context = {k: v for k, v in context.items() if k != "auth.id"}
+
+    def get_context(self) -> dict[str, Any]:
+        return dict(self._context)
+
+    def clear_context(self) -> None:
+        self._context = {}

edgebase_core-0.1.3/src/edgebase_core/errors.py

@@ -0,0 +1,40 @@
+"""EdgeBase error types."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass
+class EdgeBaseError(Exception):
+    """Base error for all EdgeBase API errors."""
+
+    status_code: int
+    message: str
+    details: dict[str, list[str]] | None = field(default=None)
+
+    def __str__(self) -> str:
+        parts = [f"EdgeBaseError({self.status_code}): {self.message}"]
+        if self.details:
+            for k, v in self.details.items():
+                rendered = ", ".join(str(item) for item in v) if isinstance(v, list) else str(v)
+                parts.append(f"  {k}: {rendered}")
+        return "\n".join(parts)
+
+    @classmethod
+    def from_json(cls, data: dict[str, Any], status_code: int) -> EdgeBaseError:
+        """Create from API JSON response."""
+        return cls(
+            status_code=status_code,
+            message=data.get("message", "Unknown error"),
+            details=data.get("details"),
+        )
+
+
+@dataclass
+class EdgeBaseAuthError(EdgeBaseError):
+    """Authentication-specific error."""
+
+    def __str__(self) -> str:
+        return f"EdgeBaseAuthError({self.status_code}): {self.message}"

edgebase_core-0.1.3/src/edgebase_core/field_ops.py

@@ -0,0 +1,51 @@
+"""Field operation helpers for atomic updates."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+class FieldOps:
+    """Atomic field operation markers ($op pattern — mirrors JS SDK, server op-parser.ts)."""
+
+    @staticmethod
+    def increment(value: int | float = 1) -> dict[str, Any]:
+        """Increment a numeric field atomically.
+
+        Usage::
+
+            doc_ref.update({"views": FieldOps.increment(1)})
+            doc_ref.update({"score": FieldOps.increment(-5)})
+        """
+        return {"$op": "increment", "value": value}
+
+    @staticmethod
+    def delete_field() -> dict[str, str]:
+        """Delete a field from a document.
+
+        Usage::
+
+            doc_ref.update({"oldField": FieldOps.delete_field()})
+        """
+        return {"$op": "deleteField"}
+
+
+# Standalone module-level functions — enable `from edgebase_core.field_ops import increment, delete_field`
+def increment(value: int | float = 1) -> dict[str, Any]:
+    """Increment a numeric field atomically. See :meth:`FieldOps.increment`."""
+    return FieldOps.increment(value)
+
+
+def delete_field() -> dict[str, str]:
+    """Delete a field from a document. See :meth:`FieldOps.delete_field`."""
+    return FieldOps.delete_field()
+
+
+def serialize_field_ops(data: dict[str, Any]) -> dict[str, Any]:
+    """Pass through data dict, preserving field-op markers as-is.
+
+    Field ops (``increment()``, ``delete_field()``) already produce the
+    ``{"$op": ...}`` dict that the server expects, so this function simply
+    returns a shallow copy.
+    """
+    return {k: v for k, v in data.items()}