lumera 0.4.6__py3-none-any.whl → 0.9.6__py3-none-any.whl

lumera/pb.py

@@ -0,0 +1,679 @@
+"""
+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.
+
+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
+    create()          - Create new record
+    update()          - Update existing record
+    upsert()          - Create or update by external_id
+    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().
+
+    Simple equality:
+        {"status": "pending"}
+        {"external_id": "dep-001"}
+
+    Comparison operators (eq, gt, gte, lt, lte):
+        {"amount": {"gt": 1000}}
+        {"amount": {"gte": 100, "lte": 500}}
+
+    OR logic:
+        {"or": [{"status": "pending"}, {"status": "review"}]}
+
+    AND logic (implicit - multiple fields at same level):
+        {"status": "pending", "amount": {"gt": 1000}}
+
+    Combined:
+        {"status": "active", "or": [{"priority": "high"}, {"amount": {"gt": 5000}}]}
+
+Example:
+    >>> from lumera import pb
+    >>> results = pb.search("deposits", filter={"status": "pending"})
+    >>> deposit = pb.get("deposits", "rec_abc123")
+"""
+
+import warnings
+from typing import Any, Iterator, Mapping, Sequence
+
+__all__ = [
+    # Record operations
+    "search",
+    "get",
+    "get_by_external_id",
+    "create",
+    "update",
+    "upsert",
+    "delete",
+    "iter_all",
+    # Bulk operations
+    "bulk_delete",
+    "bulk_update",
+    "bulk_upsert",
+    "bulk_insert",
+    # 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 ._utils import LumeraAPIError
+from .sdk import (
+    bulk_delete_records as _bulk_delete_records,
+)
+from .sdk import (
+    bulk_insert_records as _bulk_insert_records,
+)
+from .sdk import (
+    bulk_update_records as _bulk_update_records,
+)
+from .sdk import (
+    bulk_upsert_records as _bulk_upsert_records,
+)
+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 (
+    ensure_collection as _ensure_collection,
+)
+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_record as _update_record,
+)
+from .sdk import (
+    upsert_record as _upsert_record,
+)
+
+
+def search(
+    collection: str,
+    *,
+    filter: Mapping[str, Any] | str | None = None,
+    per_page: int = 50,
+    page: int = 1,
+    sort: str | None = None,
+    expand: str | None = None,
+) -> dict[str, Any]:
+    """Search records in a collection.
+
+    Args:
+        collection: Collection name or ID
+        filter: Filter as dict or JSON string. See module docstring for syntax.
+                Examples:
+                - {"status": "pending"} - equality
+                - {"amount": {"gt": 1000}} - comparison
+                - {"or": [{"status": "a"}, {"status": "b"}]} - OR logic
+        per_page: Results per page (max 500, default 50)
+        page: Page number, 1-indexed (default 1)
+        sort: Sort expression (e.g., "-created,name" for created DESC, name ASC)
+        expand: Comma-separated relation fields to expand (e.g., "user_id,company_id")
+
+    Returns:
+        Paginated results with structure:
+        {
+            "items": [...],      # List of records
+            "page": 1,
+            "perPage": 50,
+            "totalItems": 100,
+            "totalPages": 2
+        }
+
+    Example:
+        >>> results = pb.search("deposits",
+        ...     filter={"status": "pending", "amount": {"gt": 1000}},
+        ...     per_page=100,
+        ...     sort="-created"
+        ... )
+        >>> for deposit in results["items"]:
+        ...     print(deposit["id"], deposit["amount"])
+    """
+    # Note: _list_records handles both dict and str filters via JSON encoding
+    return _list_records(
+        collection,
+        filter=filter,
+        per_page=per_page,
+        page=page,
+        sort=sort,
+        expand=expand,
+    )
+
+
+def get(collection: str, record_id: str) -> dict[str, Any]:
+    """Get a single record by ID.
+
+    Args:
+        collection: Collection name or ID
+        record_id: Record ID (15-character alphanumeric ID)
+
+    Returns:
+        Record data with all fields
+
+    Raises:
+        LumeraAPIError: If record doesn't exist (404)
+
+    Example:
+        >>> deposit = pb.get("deposits", "dep_abc123")
+        >>> print(deposit["amount"])
+    """
+    return _get_record(collection, record_id)
+
+
+def get_by_external_id(collection: str, external_id: str) -> dict[str, Any]:
+    """Get a single record by external_id (unique field).
+
+    Args:
+        collection: Collection name or ID
+        external_id: Value of the external_id field (your business identifier)
+
+    Returns:
+        Record data
+
+    Raises:
+        LumeraAPIError: If no record with that external_id (404)
+
+    Example:
+        >>> deposit = pb.get_by_external_id("deposits", "dep-2024-001")
+    """
+    return _get_record_by_external_id(collection, external_id)
+
+
+def create(collection: str, data: dict[str, Any]) -> dict[str, Any]:
+    """Create a new record.
+
+    Args:
+        collection: Collection name or ID
+        data: Record data as dict mapping field names to values
+
+    Returns:
+        Created record with id, created, and updated timestamps
+
+    Raises:
+        LumeraAPIError: If validation fails or unique constraint violated
+
+    Example:
+        >>> deposit = pb.create("deposits", {
+        ...     "external_id": "dep-001",
+        ...     "amount": 1000,
+        ...     "status": "pending"
+        ... })
+        >>> print(deposit["id"])
+    """
+    return _create_record(collection, data)
+
+
+def update(collection: str, record_id: str, data: dict[str, Any]) -> dict[str, Any]:
+    """Update an existing record (partial update).
+
+    Args:
+        collection: Collection name or ID
+        record_id: Record ID to update
+        data: Fields to update (only include fields you want to change)
+
+    Returns:
+        Updated record
+
+    Raises:
+        LumeraAPIError: If record doesn't exist or validation fails
+
+    Example:
+        >>> deposit = pb.update("deposits", "dep_abc123", {
+        ...     "status": "processed",
+        ...     "processed_at": datetime.utcnow().isoformat()
+        ... })
+    """
+    return _update_record(collection, record_id, data)
+
+
+def upsert(collection: str, data: dict[str, Any]) -> dict[str, Any]:
+    """Create or update a record by external_id.
+
+    If a record with the given external_id exists, updates it.
+    Otherwise, creates a new record. This is useful for idempotent imports.
+
+    Args:
+        collection: Collection name or ID
+        data: Record data (MUST include "external_id" field)
+
+    Returns:
+        Created or updated record
+
+    Raises:
+        ValueError: If data doesn't contain "external_id"
+        LumeraAPIError: If validation fails
+
+    Example:
+        >>> deposit = pb.upsert("deposits", {
+        ...     "external_id": "dep-001",
+        ...     "amount": 1000,
+        ...     "status": "pending"
+        ... })
+        >>> # Second call updates the existing record
+        >>> deposit = pb.upsert("deposits", {
+        ...     "external_id": "dep-001",
+        ...     "amount": 2000
+        ... })
+    """
+    return _upsert_record(collection, data)
+
+
+def delete(collection: str, record_id: str) -> None:
+    """Delete a record.
+
+    Args:
+        collection: Collection name or ID
+        record_id: Record ID to delete
+
+    Raises:
+        LumeraAPIError: If record doesn't exist
+
+    Example:
+        >>> pb.delete("deposits", "dep_abc123")
+    """
+    _delete_record(collection, record_id)
+
+
+# =============================================================================
+# Bulk Operations
+# =============================================================================
+
+
+def bulk_delete(
+    collection: str,
+    record_ids: Sequence[str],
+    *,
+    transaction: bool = False,
+) -> dict[str, Any]:
+    """Delete multiple records by ID.
+
+    Args:
+        collection: Collection name or ID
+        record_ids: List of record IDs to delete (max 1000)
+        transaction: If True, use all-or-nothing semantics (rollback on any failure).
+                     If False (default), partial success is allowed.
+
+    Returns:
+        Result with succeeded/failed counts and any errors:
+        {
+            "succeeded": 10,
+            "failed": 0,
+            "errors": [],
+            "rolled_back": false  # only present if transaction=True and failed
+        }
+
+    Example:
+        >>> result = pb.bulk_delete("deposits", ["id1", "id2", "id3"])
+        >>> print(f"Deleted {result['succeeded']} records")
+
+        >>> # Use transaction mode for all-or-nothing
+        >>> result = pb.bulk_delete("deposits", ids, transaction=True)
+    """
+    return _bulk_delete_records(collection, record_ids, transaction=transaction)
+
+
+def bulk_update(
+    collection: str,
+    records: Sequence[dict[str, Any]],
+    *,
+    transaction: bool = False,
+) -> dict[str, Any]:
+    """Update multiple records with individual data per record.
+
+    Each record must have an 'id' field plus fields to update.
+    Records must exist (returns error if not found, does not create).
+
+    Args:
+        collection: Collection name or ID
+        records: List of records to update (max 1000). Each must have 'id' field.
+        transaction: If True, use all-or-nothing semantics (rollback on any failure).
+                     If False (default), partial success is allowed.
+
+    Returns:
+        Result with succeeded/failed counts:
+        {
+            "succeeded": 2,
+            "failed": 0,
+            "errors": [],
+            "rolled_back": false  # only present if transaction=True and failed
+        }
+
+    Example:
+        >>> result = pb.bulk_update("deposits", [
+        ...     {"id": "rec1", "status": "approved", "amount": 100},
+        ...     {"id": "rec2", "status": "rejected", "amount": 200},
+        ... ])
+        >>> print(f"Updated {result['succeeded']} records")
+
+        >>> # Use transaction mode for all-or-nothing
+        >>> result = pb.bulk_update("deposits", records, transaction=True)
+    """
+    return _bulk_update_records(collection, records, transaction=transaction)
+
+
+def bulk_upsert(
+    collection: str,
+    records: Sequence[dict[str, Any]],
+    *,
+    transaction: bool = False,
+) -> dict[str, Any]:
+    """Create or update multiple records by ID.
+
+    Each record can include an "id" field. Records with matching IDs will be
+    updated; records without IDs or with non-existent IDs create new records.
+
+    Args:
+        collection: Collection name or ID
+        records: List of records (max 1000)
+        transaction: If True, use all-or-nothing semantics (rollback on any failure).
+                     If False (default), partial success is allowed.
+
+    Returns:
+        Result with succeeded/failed counts and created record IDs:
+        {
+            "succeeded": 2,
+            "failed": 0,
+            "errors": [],
+            "records": [{"id": "..."}, ...],
+            "rolled_back": false  # only present if transaction=True and failed
+        }
+
+    Example:
+        >>> result = pb.bulk_upsert("deposits", [
+        ...     {"id": "existing_id", "amount": 100},
+        ...     {"amount": 200},  # creates new record
+        ... ])
+
+        >>> # Use transaction mode for all-or-nothing
+        >>> result = pb.bulk_upsert("deposits", records, transaction=True)
+    """
+    return _bulk_upsert_records(collection, records, transaction=transaction)
+
+
+def bulk_insert(
+    collection: str,
+    records: Sequence[dict[str, Any]],
+    *,
+    transaction: bool = False,
+) -> dict[str, Any]:
+    """Insert multiple new records.
+
+    Args:
+        collection: Collection name or ID
+        records: List of records to create (max 1000)
+        transaction: If True, use all-or-nothing semantics (rollback on any failure).
+                     If False (default), partial success is allowed.
+
+    Returns:
+        Result with succeeded/failed counts and created record IDs:
+        {
+            "succeeded": 2,
+            "failed": 0,
+            "errors": [],
+            "records": [{"id": "..."}, {"id": "..."}],
+            "rolled_back": false  # only present if transaction=True and failed
+        }
+
+    Example:
+        >>> result = pb.bulk_insert("deposits", [
+        ...     {"external_id": "dep-001", "amount": 100},
+        ...     {"external_id": "dep-002", "amount": 200},
+        ... ])
+        >>> for rec in result["records"]:
+        ...     print(f"Created: {rec['id']}")
+
+        >>> # Use transaction mode for all-or-nothing
+        >>> result = pb.bulk_insert("deposits", records, transaction=True)
+    """
+    return _bulk_insert_records(collection, records, transaction=transaction)
+
+
+def iter_all(
+    collection: str,
+    *,
+    filter: Mapping[str, Any] | str | None = None,
+    sort: str | None = None,
+    expand: str | None = None,
+    batch_size: int = 500,
+) -> Iterator[dict[str, Any]]:
+    """Iterate over all matching records, handling pagination automatically.
+
+    This is a convenience function for processing large result sets without
+    manually handling pagination. Use this instead of manual page loops.
+
+    Args:
+        collection: Collection name or ID
+        filter: Optional filter as dict or JSON string (e.g., {"status": "pending"})
+        sort: Optional sort expression (e.g., "-created" for newest first)
+        expand: Optional comma-separated relation fields to expand
+        batch_size: Records per API request (max 500, default 500)
+
+    Yields:
+        Individual records
+
+    Example:
+        >>> for deposit in pb.iter_all("deposits", filter={"status": "pending"}):
+        ...     process(deposit)
+    """
+    page = 1
+    while True:
+        result = search(
+            collection,
+            filter=filter,
+            per_page=batch_size,
+            page=page,
+            sort=sort,
+            expand=expand,
+        )
+
+        items = result.get("items", [])
+        if not items:
+            break
+
+        yield from items
+
+        # Check if there are more pages
+        # Use `or 0` instead of default to handle None values
+        total_pages = result.get("totalPages") or 0
+        if page >= total_pages:
+            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 ensure_collection(
+    name: str,
+    schema: Sequence[dict[str, Any]] | None = None,
+    *,
+    id: str | None = None,
+    indexes: Sequence[str] | None = None,
+) -> dict[str, Any]:
+    """Ensure a collection exists with the given schema (idempotent).
+
+    This is the recommended way to manage collections. It creates the collection
+    if it doesn't exist, or updates it if it does. Safe to call multiple times.
+
+    IMPORTANT: The schema and indexes are declarative:
+    - schema: The COMPLETE list of user fields you want (replaces all existing user fields)
+    - indexes: The COMPLETE list of user indexes you want (replaces all existing user indexes)
+    - System fields (id, created, updated, etc.) are automatically managed
+    - System indexes (external_id, updated) are automatically managed
+
+    If you omit schema or indexes, existing values are preserved.
+
+    Args:
+        name: Collection name (can be renamed later in UI)
+        schema: List of field definitions. If provided, replaces all user fields.
+                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)
+        id: Optional stable identifier for the collection. If provided on creation,
+            this ID will be used instead of an auto-generated one. The ID remains
+            stable even if the collection is renamed, making it ideal for use in
+            automations and hooks. Must be alphanumeric with underscores only.
+            Cannot be changed after creation.
+        indexes: Optional list of user index DDL statements. If provided,
+                replaces all user indexes.
+
+    Returns:
+        Collection object with:
+        - id: The collection's stable identifier
+        - name: The collection's display name
+        - schema: User-defined fields only (what you can modify)
+        - indexes: User-defined indexes only (what you can modify)
+        - systemInfo: Read-only system fields and indexes (automatically managed)
+
+    Example:
+        >>> # Create with stable ID for use in automations
+        >>> col = pb.ensure_collection(
+        ...     "Customer Orders Q1",
+        ...     schema=[
+        ...         {"name": "amount", "type": "number", "required": True},
+        ...         {"name": "status", "type": "text"},
+        ...     ],
+        ...     id="orders",  # stable reference
+        ... )
+        >>>
+        >>> # Later, collection can be renamed but ID stays "orders"
+        >>> # Automations using pb.search("orders", ...) still work!
+        >>>
+        >>> # Create without custom ID (auto-generated)
+        >>> col = pb.ensure_collection("deposits", [...])
+    """
+    return _ensure_collection(name, schema=schema, id=id, 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)
+
+
+# Backwards compatibility aliases
+def create_collection(
+    name: str,
+    schema: Sequence[dict[str, Any]],
+    *,
+    indexes: Sequence[str] | None = None,
+) -> dict[str, Any]:
+    """Create a new collection.
+
+    .. deprecated::
+        Use :func:`ensure_collection` instead, which handles both create and update.
+    """
+    warnings.warn(
+        "create_collection() is deprecated, use ensure_collection() instead",
+        DeprecationWarning,
+        stacklevel=2,
+    )
+    return ensure_collection(name, 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.
+
+    .. deprecated::
+        Use :func:`ensure_collection` instead, which handles both create and update.
+    """
+    warnings.warn(
+        "update_collection() is deprecated, use ensure_collection() instead",
+        DeprecationWarning,
+        stacklevel=2,
+    )
+    return ensure_collection(name, schema, indexes=indexes)