lumera 0.9.0__tar.gz → 0.9.2__tar.gz

{lumera-0.9.0 → lumera-0.9.2}/PKG-INFO

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

lumera-0.9.2/lumera/integrations/__init__.py

@@ -0,0 +1,34 @@
+"""
+Lumera SDK Integrations
+
+Third-party service integrations with Lumera credential management.
+
+Each integration module provides:
+- A `get_*_client()` or `get_*_service()` function that returns an authenticated client
+- Optional helper functions for common Lumera patterns
+
+Example:
+    from lumera.integrations import google, get_access_token
+
+    # Google Sheets with Lumera-managed OAuth
+    sheets = google.get_sheets_service()
+    data = sheets.spreadsheets().values().get(...)
+
+    # Google Drive
+    drive = google.get_drive_service()
+    files = drive.files().list().execute()
+
+    # Get raw access token for any provider
+    token = get_access_token("slack")
+
+Available integrations:
+- `google` - Google APIs (Sheets, Drive)
+
+Utilities:
+- `get_access_token(provider)` - Get OAuth token for any Lumera-connected provider
+"""
+
+from .._utils import get_access_token
+from . import google
+
+__all__ = ["get_access_token", "google"]

lumera-0.9.2/lumera/integrations/google.py

@@ -0,0 +1,338 @@
+"""
+Google API Integration
+
+Provides authenticated Google API clients using Lumera-managed OAuth credentials.
+
+Example:
+    from lumera.integrations import google
+
+    # Get authenticated Sheets service
+    sheets = google.get_sheets_service()
+    data = sheets.spreadsheets().values().get(
+        spreadsheetId="...",
+        range="Sheet1!A1:D10"
+    ).execute()
+
+    # Get authenticated Drive service
+    drive = google.get_drive_service()
+    files = drive.files().list().execute()
+
+    # Share credentials between services
+    creds = google.get_credentials()
+    sheets = google.get_sheets_service(credentials=creds)
+    drive = google.get_drive_service(credentials=creds)
+"""
+
+import io
+import logging
+import os
+import re
+from typing import TYPE_CHECKING, Optional, Tuple
+
+# When type checking we want access to the concrete ``Resource`` class that
+# ``googleapiclient.discovery.build`` returns. Importing it unconditionally
+# would require ``googleapiclient`` to be available in every execution
+# environment – something we cannot guarantee.  By guarding the import with
+# ``TYPE_CHECKING`` we give static analysers (ruff, mypy, etc.) the
+# information they need without introducing a hard runtime dependency.
+# During static analysis we want to import ``Resource`` so that it is a known
+# name for type checkers, but we don't require this import at runtime. Guard
+# it with ``TYPE_CHECKING`` to avoid hard dependencies.
+if TYPE_CHECKING:  # pragma: no cover
+    from googleapiclient.discovery import Resource  # noqa: F401
+
+# Always ensure that the symbol ``Resource`` exists at runtime to placate static
+# analysers like ruff (F821) that inspect the AST without executing the code.
+try:  # pragma: no cover – optional runtime import
+    from googleapiclient.discovery import Resource  # type: ignore
+except ModuleNotFoundError:  # pragma: no cover – provide a stub fallback
+
+    class Resource:  # noqa: D401
+        """Stub replacement for ``googleapiclient.discovery.Resource``."""
+
+        pass
+
+
+from google.oauth2.credentials import Credentials
+from googleapiclient.discovery import build
+from googleapiclient.http import MediaFileUpload, MediaIoBaseDownload
+
+from .._utils import get_access_token
+
+# Module logger
+logger = logging.getLogger(__name__)
+
+# =====================================================================================
+# Configuration
+# =====================================================================================
+
+MIME_GOOGLE_SHEET = "application/vnd.google-apps.spreadsheet"
+MIME_EXCEL = "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"
+
+# =====================================================================================
+# Authentication & Service Initialization
+# =====================================================================================
+
+
+def get_credentials() -> Credentials:
+    """
+    Retrieves a Google OAuth token from Lumera and
+    converts it into a Credentials object usable by googleapiclient.
+
+    Returns:
+        google.oauth2.credentials.Credentials: Authenticated credentials object.
+
+    Raises:
+        RuntimeError: If LUMERA_TOKEN is not set or token fetch fails.
+    """
+    logger.debug("Fetching Google access token from Lumera…")
+    access_token = get_access_token("google")
+    logger.debug("Access token received.")
+    creds = Credentials(token=access_token)
+    logger.debug("Credentials object created.")
+    return creds
+
+
+# Backward compatibility alias
+get_google_credentials = get_credentials
+
+
+def get_sheets_service(credentials: Optional[Credentials] = None) -> "Resource":
+    """
+    Initializes and returns the Google Sheets API service.
+
+    If no credentials are provided, this function will automatically fetch a
+    Google access token from Lumera and construct the appropriate
+    ``google.oauth2.credentials.Credentials`` instance.
+
+    Args:
+        credentials: Optional pre-fetched credentials. If None, fetches from Lumera.
+
+    Returns:
+        Google Sheets API service resource.
+    """
+    if credentials is None:
+        logger.info("No credentials provided; fetching Google token…")
+        credentials = get_credentials()
+    logger.info("Google Sheets API service being initialized…")
+    return build("sheets", "v4", credentials=credentials)
+
+
+def get_drive_service(credentials: Optional[Credentials] = None) -> "Resource":
+    """
+    Initializes and returns the Google Drive API service.
+
+    If no credentials are provided, this function will automatically fetch a
+    Google access token from Lumera and construct the appropriate
+    ``google.oauth2.credentials.Credentials`` instance.
+
+    Args:
+        credentials: Optional pre-fetched credentials. If None, fetches from Lumera.
+
+    Returns:
+        Google Drive API service resource.
+    """
+    if credentials is None:
+        logger.info("No credentials provided; fetching Google token…")
+        credentials = get_credentials()
+    logger.info("Google Drive API service being initialized…")
+    return build("drive", "v3", credentials=credentials)
+
+
+# =====================================================================================
+# Google Sheets & Drive Utility Functions
+# =====================================================================================
+
+
+def get_spreadsheet_and_sheet_id(
+    service: "Resource", spreadsheet_url: str, tab_name: str
+) -> Tuple[Optional[str], Optional[int]]:
+    """
+    Given a Google Sheets URL and a tab (sheet) name, returns a tuple:
+    (spreadsheet_id, sheet_id)
+    """
+    spreadsheet_id = _extract_spreadsheet_id(spreadsheet_url)
+    if not spreadsheet_id:
+        return None, None
+
+    sheet_id = _get_sheet_id_from_name(service, spreadsheet_id, tab_name)
+    return spreadsheet_id, sheet_id
+
+
+def _extract_spreadsheet_id(spreadsheet_url: str) -> Optional[str]:
+    """Extracts the spreadsheet ID from a Google Sheets URL."""
+    logger.debug(f"Extracting spreadsheet ID from URL: {spreadsheet_url}")
+    pattern = r"/d/([a-zA-Z0-9-_]+)"
+    match = re.search(pattern, spreadsheet_url)
+    if match:
+        spreadsheet_id = match.group(1)
+        logger.debug(f"Spreadsheet ID extracted: {spreadsheet_id}")
+        return spreadsheet_id
+    logger.warning("Could not extract Spreadsheet ID.")
+    return None
+
+
+def _get_sheet_id_from_name(
+    service: "Resource", spreadsheet_id: str, tab_name: str
+) -> Optional[int]:
+    """Uses the Google Sheets API to fetch the sheet ID corresponding to 'tab_name'."""
+    logger.debug(f"Requesting sheet metadata for spreadsheet ID: {spreadsheet_id}")
+    response = (
+        service.spreadsheets()
+        .get(spreadsheetId=spreadsheet_id, fields="sheets.properties")
+        .execute()
+    )
+    logger.debug("Metadata received. Searching for tab…")
+
+    for sheet in response.get("sheets", []):
+        properties = sheet.get("properties", {})
+        if properties.get("title") == tab_name:
+            sheet_id = properties.get("sheetId")
+            logger.debug(f"Match found for tab '{tab_name}'. Sheet ID is {sheet_id}")
+            return sheet_id
+    logger.warning(f"No sheet found with tab name '{tab_name}'.")
+    return None
+
+
+def sheet_name_from_gid(service: "Resource", spreadsheet_id: str, gid: int) -> Optional[str]:
+    """Resolve a sheet's human-readable name (title) from its gid."""
+    logger.debug(f"Resolving sheet name from gid={gid} …")
+    meta = (
+        service.spreadsheets()
+        .get(
+            spreadsheetId=spreadsheet_id,
+            includeGridData=False,
+            fields="sheets(properties(sheetId,title))",
+        )
+        .execute()
+    )
+
+    for sheet in meta.get("sheets", []):
+        props = sheet.get("properties", {})
+        if props.get("sheetId") == gid:
+            title = props["title"]
+            logger.debug(f"Sheet gid={gid} corresponds to sheet name='{title}'.")
+            return title
+    logger.warning(f"No sheet found with gid={gid}")
+    return None
+
+
+def read_cell(service: "Resource", spreadsheet_id: str, range_a1: str) -> Optional[str]:
+    """Fetch a single cell value (as string); returns None if empty."""
+    logger.debug(f"Reading cell '{range_a1}' …")
+    resp = (
+        service.spreadsheets()
+        .values()
+        .get(spreadsheetId=spreadsheet_id, range=range_a1, majorDimension="ROWS")
+        .execute()
+    )
+
+    values = resp.get("values", [])
+    return values[0][0] if values and values[0] else None
+
+
+# NOTE: The function performs I/O side-effects and does not return a value.
+def download_file_direct(drive_service: "Resource", file_id: str, dest_path: str) -> None:
+    """
+    Downloads a file directly from Google Drive using files().get_media
+    without any format conversion.
+    """
+    logger.info(f"Initiating direct download for file ID: {file_id}")
+
+    request = drive_service.files().get_media(fileId=file_id)
+    fh = io.BytesIO()
+    downloader = MediaIoBaseDownload(fh, request)
+
+    done = False
+    while not done:
+        status, done = downloader.next_chunk()
+        if status:
+            logger.debug(f"Download progress: {int(status.progress() * 100)}%")
+
+    with open(dest_path, "wb") as f:
+        f.write(fh.getvalue())
+    logger.info(f"File saved to: {dest_path}")
+
+
+def upload_excel_as_google_sheet(
+    drive_service: "Resource", local_path: str, desired_name: str
+) -> Tuple[Optional[str], Optional[str]]:
+    """
+    Uploads a local XLSX file to Google Drive, converting it to Google Sheets format.
+    Returns the file ID and web link.
+    """
+    logger.info(f"Preparing to upload '{local_path}' as Google Sheet named '{desired_name}'")
+
+    if not os.path.isfile(local_path):
+        logger.error(f"Local file not found at '{local_path}'. Aborting.")
+        return None, None
+
+    media = MediaFileUpload(local_path, mimetype=MIME_EXCEL, resumable=True)
+    file_metadata = {"name": desired_name, "mimeType": MIME_GOOGLE_SHEET}
+
+    logger.info("Initiating Google Drive upload & conversion…")
+    request = drive_service.files().create(
+        body=file_metadata, media_body=media, fields="id, webViewLink"
+    )
+
+    response = None
+    while response is None:
+        status, response = request.next_chunk()
+        if status:
+            logger.debug(f"Upload progress: {int(status.progress() * 100)}%")
+
+    file_id = response.get("id")
+    web_view_link = response.get("webViewLink")
+    logger.info(f"Upload completed. File ID: {file_id}")
+    return file_id, web_view_link
+
+
+# Remove rows from a sheet.  All parameters are 1-based (both *start_row* and
+# *end_row* are inclusive) mirroring the UI behaviour in Google Sheets.
+def delete_rows_api_call(
+    service: "Resource",
+    spreadsheet_id: str,
+    sheet_gid: int,
+    start_row: int,
+    end_row: int,
+) -> None:
+    """Executes the API call to delete rows."""
+    logger.info(f"Deleting rows {start_row}-{end_row} (1-based inclusive)…")
+
+    body = {
+        "requests": [
+            {
+                "deleteDimension": {
+                    "range": {
+                        "sheetId": sheet_gid,
+                        "dimension": "ROWS",
+                        "startIndex": start_row - 1,  # 0-based
+                        "endIndex": end_row,  # end-exclusive
+                    }
+                }
+            }
+        ]
+    }
+    service.spreadsheets().batchUpdate(spreadsheetId=spreadsheet_id, body=body).execute()
+    logger.info("Rows deleted.")
+
+
+__all__ = [
+    # Authentication
+    "get_credentials",
+    "get_google_credentials",  # backward compat alias
+    # Services
+    "get_sheets_service",
+    "get_drive_service",
+    # Sheets helpers
+    "get_spreadsheet_and_sheet_id",
+    "sheet_name_from_gid",
+    "read_cell",
+    "delete_rows_api_call",
+    # Drive helpers
+    "download_file_direct",
+    "upload_excel_as_google_sheet",
+    # Constants
+    "MIME_GOOGLE_SHEET",
+    "MIME_EXCEL",
+]

{lumera-0.9.0 → lumera-0.9.2}/lumera/pb.py

@@ -318,31 +318,44 @@ def delete(collection: str, record_id: str) -> None:
 # =============================================================================
 
 
-def bulk_delete(collection: str, record_ids: Sequence[str]) -> dict[str, Any]:
+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": []
+            "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)
+    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.
 
@@ -352,9 +365,17 @@ def bulk_update(
     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
+        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", [
@@ -362,11 +383,19 @@ def bulk_update(
         ...     {"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)
+    return _bulk_update_records(collection, records, transaction=transaction)
 
 
-def bulk_upsert(collection: str, records: Sequence[dict[str, Any]]) -> dict[str, Any]:
+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
@@ -375,25 +404,44 @@ def bulk_upsert(collection: str, records: Sequence[dict[str, Any]]) -> dict[str,
     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
+        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)
+    return _bulk_upsert_records(collection, records, transaction=transaction)
 
 
-def bulk_insert(collection: str, records: Sequence[dict[str, Any]]) -> dict[str, Any]:
+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:
@@ -401,7 +449,8 @@ def bulk_insert(collection: str, records: Sequence[dict[str, Any]]) -> dict[str,
             "succeeded": 2,
             "failed": 0,
             "errors": [],
-            "records": [{"id": "..."}, {"id": "..."}]
+            "records": [{"id": "..."}, {"id": "..."}],
+            "rolled_back": false  # only present if transaction=True and failed
         }
 
     Example:
@@ -411,8 +460,11 @@ def bulk_insert(collection: str, records: Sequence[dict[str, Any]]) -> dict[str,
         ... ])
         >>> 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)
+    return _bulk_insert_records(collection, records, transaction=transaction)
 
 
 def iter_all(

{lumera-0.9.0 → lumera-0.9.2}/lumera/sdk.py

@@ -591,12 +591,15 @@ def delete_record(collection_id_or_name: str, record_id: str) -> None:
 def bulk_delete_records(
     collection_id_or_name: str,
     record_ids: Sequence[str],
+    *,
+    transaction: bool = False,
 ) -> dict[str, Any]:
     """Bulk delete records by IDs.
 
     Args:
         collection_id_or_name: 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)
 
     Returns:
         Result with succeeded/failed counts and any errors
@@ -607,19 +610,25 @@ def bulk_delete_records(
         raise ValueError("record_ids is required")
 
     path = f"collections/{collection_id_or_name}/records/bulk/delete"
-    result = _api_request("POST", path, json_body={"ids": list(record_ids)})
+    body: dict[str, Any] = {"ids": list(record_ids)}
+    if transaction:
+        body["transaction"] = True
+    result = _api_request("POST", path, json_body=body)
     return result if isinstance(result, dict) else {}
 
 
 def bulk_update_records(
     collection_id_or_name: str,
     records: Sequence[Mapping[str, Any]],
+    *,
+    transaction: bool = False,
 ) -> dict[str, Any]:
     """Update multiple records with individual data per record.
 
     Args:
         collection_id_or_name: Collection name or ID
         records: List of records to update (max 1000). Each record must have an 'id' field.
+        transaction: If True, use all-or-nothing semantics (rollback on any failure)
 
     Returns:
         Result with succeeded/failed counts
@@ -630,19 +639,25 @@ def bulk_update_records(
         raise ValueError("records is required")
 
     path = f"collections/{collection_id_or_name}/records/bulk/update"
-    result = _api_request("POST", path, json_body={"records": [dict(r) for r in records]})
+    body: dict[str, Any] = {"records": [dict(r) for r in records]}
+    if transaction:
+        body["transaction"] = True
+    result = _api_request("POST", path, json_body=body)
     return result if isinstance(result, dict) else {}
 
 
 def bulk_upsert_records(
     collection_id_or_name: str,
     records: Sequence[Mapping[str, Any]],
+    *,
+    transaction: bool = False,
 ) -> dict[str, Any]:
     """Upsert multiple records (create or update by ID).
 
     Args:
         collection_id_or_name: Collection name or ID
         records: List of records (max 1000). Include 'id' field to update existing.
+        transaction: If True, use all-or-nothing semantics (rollback on any failure)
 
     Returns:
         Result with succeeded/failed counts and created record IDs
@@ -653,19 +668,25 @@ def bulk_upsert_records(
         raise ValueError("records is required")
 
     path = f"collections/{collection_id_or_name}/records/bulk/upsert"
-    result = _api_request("POST", path, json_body={"records": [dict(r) for r in records]})
+    body: dict[str, Any] = {"records": [dict(r) for r in records]}
+    if transaction:
+        body["transaction"] = True
+    result = _api_request("POST", path, json_body=body)
     return result if isinstance(result, dict) else {}
 
 
 def bulk_insert_records(
     collection_id_or_name: str,
     records: Sequence[Mapping[str, Any]],
+    *,
+    transaction: bool = False,
 ) -> dict[str, Any]:
     """Insert multiple new records.
 
     Args:
         collection_id_or_name: Collection name or ID
         records: List of records to create (max 1000)
+        transaction: If True, use all-or-nothing semantics (rollback on any failure)
 
     Returns:
         Result with succeeded/failed counts and created record IDs
@@ -676,7 +697,10 @@ def bulk_insert_records(
         raise ValueError("records is required")
 
     path = f"collections/{collection_id_or_name}/records/bulk/insert"
-    result = _api_request("POST", path, json_body={"records": [dict(r) for r in records]})
+    body: dict[str, Any] = {"records": [dict(r) for r in records]}
+    if transaction:
+        body["transaction"] = True
+    result = _api_request("POST", path, json_body=body)
     return result if isinstance(result, dict) else {}
 
 

{lumera-0.9.0 → lumera-0.9.2}/lumera.egg-info/PKG-INFO

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

{lumera-0.9.0 → lumera-0.9.2}/lumera.egg-info/SOURCES.txt

@@ -15,4 +15,6 @@ lumera.egg-info/SOURCES.txt
 lumera.egg-info/dependency_links.txt
 lumera.egg-info/requires.txt
 lumera.egg-info/top_level.txt
+lumera/integrations/__init__.py
+lumera/integrations/google.py
 tests/test_sdk.py

{lumera-0.9.0 → lumera-0.9.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "lumera"
-version = "0.9.0"
+version = "0.9.2"
 description = "SDK for building on Lumera platform"
 requires-python = ">=3.11"
 dependencies = [
@@ -45,8 +45,9 @@ full = [
     "requests==2.32.4",
 ]
 
-[tool.setuptools]
-packages = ["lumera"]
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["lumera*"]
 
 [tool.pytest.ini_options]
 minversion = "8.0"