lumera 0.5.2__tar.gz → 0.5.3__tar.gz

{lumera-0.5.2 → lumera-0.5.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: lumera
-Version: 0.5.2
+Version: 0.5.3
 Summary: SDK for building on Lumera platform
 Requires-Python: >=3.11
 Requires-Dist: requests

{lumera-0.5.2 → lumera-0.5.3}/lumera/pb.py

@@ -1,10 +1,10 @@
 """
-Record operations for Lumera collections.
+Record and collection operations for Lumera.
 
 This module provides a clean interface for working with Lumera collections,
 using the `pb.` namespace convention familiar from automation contexts.
 
-Available functions:
+Record functions:
     search()          - Query records with filters, pagination, sorting
     get()             - Get single record by ID
     get_by_external_id() - Get record by external_id field
@@ -14,6 +14,14 @@ Available functions:
     delete()          - Delete record
     iter_all()        - Iterate all matching records (auto-pagination)
 
+Collection functions:
+    list_collections()    - List all collections
+    get_collection()      - Get collection by name
+    ensure_collection()   - Create or update collection (idempotent)
+    create_collection()   - Create new collection
+    update_collection()   - Update collection schema
+    delete_collection()   - Delete collection
+
 Filter Syntax:
     Filters can be passed as dict or JSON string to search() and iter_all().
 
@@ -40,9 +48,10 @@ Example:
     >>> deposit = pb.get("deposits", "rec_abc123")
 """
 
-from typing import Any, Iterator, Mapping
+from typing import Any, Iterator, Mapping, Sequence
 
 __all__ = [
+    # Record operations
     "search",
     "get",
     "get_by_external_id",
@@ -51,24 +60,47 @@ __all__ = [
     "upsert",
     "delete",
     "iter_all",
+    # Collection operations
+    "list_collections",
+    "get_collection",
+    "ensure_collection",
+    "create_collection",
+    "update_collection",
+    "delete_collection",
 ]
 
 # Import underlying SDK functions (prefixed with _ to indicate internal use)
+from .exceptions import LumeraAPIError
+from .sdk import (
+    create_collection as _create_collection,
+)
 from .sdk import (
     create_record as _create_record,
 )
+from .sdk import (
+    delete_collection as _delete_collection,
+)
 from .sdk import (
     delete_record as _delete_record,
 )
+from .sdk import (
+    get_collection as _get_collection,
+)
 from .sdk import (
     get_record as _get_record,
 )
 from .sdk import (
     get_record_by_external_id as _get_record_by_external_id,
 )
+from .sdk import (
+    list_collections as _list_collections,
+)
 from .sdk import (
     list_records as _list_records,
 )
+from .sdk import (
+    update_collection as _update_collection,
+)
 from .sdk import (
     update_record as _update_record,
 )
@@ -314,3 +346,173 @@ def iter_all(
             break
 
         page += 1
+
+
+# =============================================================================
+# Collection Management Functions
+# =============================================================================
+
+
+def list_collections() -> list[dict[str, Any]]:
+    """List all collections.
+
+    Returns:
+        List of collection objects with id, name, schema, etc.
+
+    Example:
+        >>> collections = pb.list_collections()
+        >>> for col in collections:
+        ...     print(col["name"])
+    """
+    result = _list_collections()
+    return result.get("items", [])
+
+
+def get_collection(name: str) -> dict[str, Any] | None:
+    """Get a collection by name.
+
+    Args:
+        name: Collection name
+
+    Returns:
+        Collection object if found, None if not found
+
+    Example:
+        >>> col = pb.get_collection("deposits")
+        >>> if col:
+        ...     print(col["schema"])
+    """
+    try:
+        return _get_collection(name)
+    except LumeraAPIError as e:
+        if e.status_code == 404:
+            return None
+        raise
+
+
+def create_collection(
+    name: str,
+    schema: Sequence[dict[str, Any]],
+    *,
+    indexes: Sequence[str] | None = None,
+) -> dict[str, Any]:
+    """Create a new collection.
+
+    Args:
+        name: Collection name (must not start with '_')
+        schema: List of field definitions. Each field is a dict with:
+            - name: Field name (required)
+            - type: Field type (required): text, number, bool, date, json,
+                    relation, select, editor, lumera_file
+            - required: Whether field is required (default False)
+            - options: Type-specific options (e.g., collectionId for relations)
+        indexes: Optional list of index definitions
+
+    Returns:
+        Created collection object
+
+    Example:
+        >>> col = pb.create_collection("deposits", [
+        ...     {"name": "amount", "type": "number", "required": True},
+        ...     {"name": "status", "type": "text"},
+        ...     {"name": "account_id", "type": "relation",
+        ...      "options": {"collectionId": "accounts"}}
+        ... ])
+    """
+    return _create_collection(name, schema=schema, indexes=indexes)
+
+
+def update_collection(
+    name: str,
+    schema: Sequence[dict[str, Any]],
+    *,
+    indexes: Sequence[str] | None = None,
+) -> dict[str, Any]:
+    """Update a collection's schema.
+
+    Args:
+        name: Collection name
+        schema: New schema (replaces existing user fields)
+        indexes: Optional new indexes
+
+    Returns:
+        Updated collection object
+
+    Example:
+        >>> col = pb.update_collection("deposits", [
+        ...     {"name": "amount", "type": "number", "required": True},
+        ...     {"name": "status", "type": "text"},
+        ...     {"name": "notes", "type": "text"}  # New field
+        ... ])
+    """
+    return _update_collection(name, schema=schema, indexes=indexes)
+
+
+def delete_collection(name: str) -> None:
+    """Delete a collection.
+
+    Args:
+        name: Collection name to delete
+
+    Raises:
+        LumeraAPIError: If collection doesn't exist or is protected
+
+    Example:
+        >>> pb.delete_collection("old_deposits")
+    """
+    _delete_collection(name)
+
+
+def ensure_collection(
+    name: str,
+    schema: Sequence[dict[str, Any]],
+    *,
+    update_schema: bool = False,
+    indexes: Sequence[str] | None = None,
+) -> dict[str, Any]:
+    """Ensure a collection exists with the given schema (idempotent).
+
+    This is the recommended way to set up collections in automation scripts.
+    Safe to call multiple times - will not fail if collection already exists.
+
+    Args:
+        name: Collection name
+        schema: List of field definitions
+        update_schema: If True, update existing collection's schema.
+                      If False (default), leave existing collection unchanged.
+        indexes: Optional list of index definitions
+
+    Returns:
+        Collection object (created, updated, or existing)
+
+    Behavior:
+        - Collection doesn't exist → create it
+        - Collection exists, update_schema=False → return existing (no-op)
+        - Collection exists, update_schema=True → update schema
+
+    Example:
+        >>> # Safe to run multiple times
+        >>> col = pb.ensure_collection("deposits", [
+        ...     {"name": "amount", "type": "number", "required": True},
+        ...     {"name": "status", "type": "text"},
+        ... ])
+        >>>
+        >>> # Update schema if collection exists
+        >>> col = pb.ensure_collection("deposits", [
+        ...     {"name": "amount", "type": "number", "required": True},
+        ...     {"name": "status", "type": "text"},
+        ...     {"name": "notes", "type": "text"},  # Add new field
+        ... ], update_schema=True)
+    """
+    existing = get_collection(name)
+
+    if existing is None:
+        # Collection doesn't exist, create it
+        return create_collection(name, schema, indexes=indexes)
+
+    if update_schema:
+        # Update existing collection's schema
+        return update_collection(name, schema, indexes=indexes)
+
+    # Collection exists and update_schema=False, return as-is
+    return existing

{lumera-0.5.2 → lumera-0.5.3}/lumera.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: lumera
-Version: 0.5.2
+Version: 0.5.3
 Summary: SDK for building on Lumera platform
 Requires-Python: >=3.11
 Requires-Dist: requests

{lumera-0.5.2 → lumera-0.5.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "lumera"
-version = "0.5.2"
+version = "0.5.3"
 description = "SDK for building on Lumera platform"
 requires-python = ">=3.11"
 dependencies = [