quickbase-extract 0.4.3__tar.gz → 0.5.0__tar.gz

{quickbase_extract-0.4.3 → quickbase_extract-0.5.0}/CHANGELOG.md

@@ -5,6 +5,41 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.5.0] - 2026-06-07
+
+### Changed
+
+- `handle_upsert`, `handle_delete`, and `handle_query` in `api_handlers.py` now delegate
+  rate limit retry logic to the session layer (`quickbase-api`), which correctly respects
+  the `retry-after` response header on all HTTP methods including POST and DELETE
+- Return type of `handle_upsert` corrected from `dict | None` to `dict`
+- Return type of `handle_delete` corrected from `int | None` to `int`
+- Return type of `handle_query` corrected from `dict | None` to `dict`
+
+### Fixed
+
+- `get_data_parallel` now correctly cancels pending futures on failure, matching the
+  behaviour of `get_report_metadata_parallel` and its own documented fail-fast behaviour
+
+### Removed
+
+- `max_retries` parameter removed from `handle_upsert`, `handle_delete`, and `handle_query`
+  — retry behaviour is now configured at the session level in `quickbase-api`
+
+### Breaking Changes
+
+- `max_retries` parameter has been removed from `handle_upsert`, `handle_delete`, and
+  `handle_query`. Any callers passing this argument will raise a `TypeError` and must be
+  updated.
+
+## [0.4.4] - 2026-05-13
+
+### Fixed
+
+- Changed `ask_values` parameter type annotations from `dict` to `Mapping` in `_refresh_data_cache` and `ensure_cache_freshness` in `cache_orchestration` to match `report_data` changes and accept any mapping type
+- Fixed `data_reasons` variable in `ensure_cache_freshness` being potentially unbound if accessed outside the `data_caching_enabled` block; initialised to `[]` alongside other data cache variables
+- Added `None` guard in `CacheManager._sync_to_s3` to raise `RuntimeError` with a clear message if called when `s3_client` is not configured, resolving type checker error and preventing unclear `AttributeError` at runtime
+
 ## [0.4.3] - 2026-05-13
 
 ### Fixed

{quickbase_extract-0.4.3 → quickbase_extract-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: quickbase-extract
-Version: 0.4.3
+Version: 0.5.0
 Summary: Extract and cache Quickbase report data with built-in error handling and S3 support
 Project-URL: Homepage, https://github.com/tbrezler/quickbase-extract
 Project-URL: Repository, https://github.com/tbrezler/quickbase-extract.git

{quickbase_extract-0.4.3 → quickbase_extract-0.5.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "quickbase-extract"
-version = "0.4.3"
+version = "0.5.0"
 description = "Extract and cache Quickbase report data with built-in error handling and S3 support"
 readme = "README.md"
 requires-python = ">=3.12"
@@ -50,3 +50,6 @@ target-version = "py312"
 [tool.ruff.lint]
 select = ["F", "E", "W", "B", "BLE", "I", "UP", "A", "RUF", "T10"]
 ignore = ["E501"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

quickbase_extract-0.5.0/src/quickbase_extract/api_handlers.py

@@ -0,0 +1,165 @@
+"""Error handling utilities for Quickbase operations.
+
+Provides standardized error handling and logging for Quickbase API operations.
+Rate limit retry logic with respect for the retry-after header is handled at
+the session level in quickbase-api's session.py.
+"""
+
+import logging
+
+logger = logging.getLogger(__name__)
+
+
+class QuickbaseOperationError(Exception):
+    """Raised when a Quickbase API operation fails."""
+
+    def __init__(self, operation: str, details: str = ""):
+        self.operation = operation
+        self.details = details
+        super().__init__(f"Quickbase {operation} failed: {details}")
+
+
+def handle_upsert(
+    client,
+    table_id: str,
+    data: list[dict],
+    description: str = "",
+) -> dict:
+    """Execute a Quickbase upsert with error handling and logging.
+
+    Rate limit retries with respect for the retry-after header are handled
+    at the session level.
+
+    Args:
+        client: Quickbase API client.
+        table_id: Target table ID.
+        data: List of record dicts to upsert.
+        description: Human-readable description for logging. Defaults to empty string.
+
+    Returns:
+        API response dict containing metadata about created/updated/unchanged records.
+
+    Raises:
+        QuickbaseOperationError: If the upsert fails.
+
+    Example:
+        >>> records = [{"6": {"value": "John"}, "7": {"value": "Doe"}}]
+        >>> result = handle_upsert(client, "bq8xyx9z", records, "customer records")
+    """
+    try:
+        result = client.upsert_records(table_id, data=data)
+
+        created = result.get("metadata", {}).get("createdRecordIds", [])
+        updated = result.get("metadata", {}).get("updatedRecordIds", [])
+        unchanged = result.get("metadata", {}).get("unchangedRecordIds", [])
+
+        logger.info(f"Upsert {description}: {len(created)} created, {len(updated)} updated, {len(unchanged)} unchanged")
+
+        return result
+
+    except Exception as e:
+        error_str = str(e)
+        logger.error(f"Upsert {description} failed: {error_str}")
+        raise QuickbaseOperationError("upsert", error_str) from e
+
+
+def handle_delete(
+    client,
+    table_id: str,
+    where: str,
+    description: str = "",
+) -> int:
+    """Execute a Quickbase delete with error handling and logging.
+
+    Rate limit retries with respect for the retry-after header are handled
+    at the session level.
+
+    Args:
+        client: Quickbase API client.
+        table_id: Target table ID.
+        where: Quickbase filter string specifying records to delete.
+        description: Human-readable description for logging. Defaults to empty string.
+
+    Returns:
+        Number of records deleted.
+
+    Raises:
+        QuickbaseOperationError: If the delete fails.
+
+    Example:
+        >>> deleted = handle_delete(client, "bq8xyx9z", "{3.EX.'test'}", "test records")
+
+    Note:
+        DELETE is safe to retry on any error — deleting already-deleted records
+        is a no-op in Quickbase.
+    """
+    try:
+        deleted = client.delete_records(table_id, where=where)
+        logger.info(f"Delete {description}: {deleted} records deleted")
+        return deleted
+
+    except Exception as e:
+        error_str = str(e)
+        logger.error(f"Delete {description} failed: {error_str}")
+        raise QuickbaseOperationError("delete", error_str) from e
+
+
+def handle_query(
+    client,
+    table_id: str,
+    *,
+    select: list[int] | None = None,
+    where: str | None = None,
+    sort_by: list[dict] | None = None,
+    group_by: list[dict] | None = None,
+    options: dict | None = None,
+    description: str = "",
+) -> dict:
+    """Execute a Quickbase query with error handling and logging.
+
+    Rate limit retries with respect for the retry-after header are handled
+    at the session level.
+
+    Args:
+        client: Quickbase API client.
+        table_id: Target table ID.
+        select: List of field IDs to return. If omitted, returns fields from
+            the default report.
+        where: A Quickbase query string (e.g., "{12.EX.'VPF'}").
+        sort_by: Sort order, e.g., [{"fieldId": 6, "order": "ASC"}].
+        group_by: Grouping, e.g., [{"fieldId": 6, "grouping": "equal-values"}].
+        options: Additional options, e.g.,
+            {"skip": 0, "top": 100, "compareWithAppLocalTime": False}.
+        description: Human-readable description for logging. Defaults to empty string.
+
+    Returns:
+        API response dict containing query results.
+
+    Raises:
+        QuickbaseOperationError: If the query fails.
+
+    Example:
+        >>> result = handle_query(
+        ...     client,
+        ...     "bq8xyx9z",
+        ...     select=[6, 7, 8],
+        ...     where="{12.EX.'Active'}",
+        ...     description="active customers"
+        ... )
+    """
+    try:
+        result = client.query_for_data(
+            table_id,
+            select=select,
+            where=where,
+            sort_by=sort_by,
+            group_by=group_by,
+            options=options,
+        )
+        return result
+
+    except Exception as e:
+        error_str = str(e)
+        desc_str = f" {description}" if description else f" on table {table_id}"
+        logger.error(f"Query{desc_str} failed: {error_str}")
+        raise QuickbaseOperationError("query", error_str) from e

{quickbase_extract-0.4.3 → quickbase_extract-0.5.0}/src/quickbase_extract/cache_manager.py

@@ -173,6 +173,8 @@ class CacheManager:
         Raises:
             Exception: If upload fails. This is critical - Lambda /tmp is ephemeral.
         """
+        if self.s3_client is None:
+            raise RuntimeError("_sync_to_s3 called but s3_client is not configured")
         try:
             relative_path = file_path.relative_to(self.cache_root)
             s3_key = f"{self.s3_prefix}/{relative_path}" if self.s3_prefix else str(relative_path)

{quickbase_extract-0.4.3 → quickbase_extract-0.5.0}/src/quickbase_extract/cache_orchestration.py

@@ -6,6 +6,7 @@ metadata and data caches. Ensures caches are up-to-date before processing.
 
 import logging
 import os
+from collections.abc import Mapping
 
 from quickbase_extract.cache_manager import DEFAULT_DATA_STALE_HOURS, DEFAULT_METADATA_STALE_HOURS, CacheManager
 from quickbase_extract.config import ReportConfig
@@ -123,7 +124,7 @@ def _refresh_data_cache(
     cache_manager: CacheManager,
     reports_to_refresh: list[ReportConfig],
     reasons: list[str],
-    ask_values: dict[ReportConfig, dict[str, str | list[str]]] | None = None,
+    ask_values: Mapping[ReportConfig, Mapping[str, str | list[str]]] | None = None,
 ) -> None:
     """Refresh data cache for specified reports.
 
@@ -132,8 +133,12 @@ def _refresh_data_cache(
         cache_manager: CacheManager instance.
         reports_to_refresh: Reports to refresh data for.
         reasons: List of reasons for refresh (for logging).
-        ask_values: Optional dict mapping ReportConfig -> ask_values dict.
+        ask_values: Optional mapping of ReportConfig -> ask_values mapping.
             Per-report "ask the user" filter values.
+            data cache. Example: {
+                ReportConfig("bq8x", "Accounts", "Python"): {"ask1": "abc"},
+                ReportConfig("bq9y", "Contacts", "Active"): {"ask1": "def"}
+            }
 
     Raises:
         CacheRefreshError: If data refresh fails.
@@ -164,7 +169,7 @@ def ensure_cache_freshness(
     cache_manager: CacheManager,
     report_configs_all: list[ReportConfig],
     report_configs_to_cache: list[ReportConfig] | None = None,
-    ask_values: dict[ReportConfig, dict[str, str | list[str]]] | None = None,
+    ask_values: Mapping[ReportConfig, Mapping[str, str | list[str]]] | None = None,
     metadata_stale_hours: float | None = None,
     data_stale_hours: float | None = None,
     cache_all_data: bool = False,
@@ -277,6 +282,7 @@ def ensure_cache_freshness(
     # Check data cache state and determine refresh needs (only if data caching enabled)
     data_needs_refresh = False
     reports_to_refresh_data = []
+    data_reasons: list[str] = []
     data_age = None
 
     if data_caching_enabled:

{quickbase_extract-0.4.3 → quickbase_extract-0.5.0}/src/quickbase_extract/report_data.py

@@ -308,9 +308,9 @@ def get_data_parallel(
     """Fetch multiple reports in parallel using cached report metadata.
 
     Executes data fetching for multiple reports concurrently to improve
-    performance. Uses a fail-fast approach: if any report fetch fails, the exception is raised
-    immediately and pending (not yet started) tasks will not be executed. Already
-    running tasks will complete before the exception propagates.
+    performance. Uses a fail-fast approach: if any report fetch fails, all pending tasks are
+    cancelled and the exception is raised. Already running tasks will complete
+    before the exception propagates.
 
     Args:
         client: Quickbase API client. Should be thread-safe for concurrent use.
@@ -387,6 +387,7 @@ def get_data_parallel(
                 data = future.result()  # Individual fetches are logged in get_data
                 results[config] = data
             except Exception as e:
+                executor.shutdown(wait=False, cancel_futures=True)
                 logger.error(f"Failed to fetch {config.app_id}/{config.table_name}/{config.report_name}: {e}")
                 raise
 

quickbase_extract-0.5.0/tests/test_api_handlers.py

@@ -0,0 +1,137 @@
+"""Unit tests for api_handlers module."""
+
+import pytest
+
+from quickbase_extract.api_handlers import (
+    QuickbaseOperationError,
+    handle_delete,
+    handle_query,
+    handle_upsert,
+)
+
+
+class TestQuickbaseOperationError:
+    """Tests for QuickbaseOperationError exception."""
+
+    def test_error_message(self):
+        """Test error message format."""
+        error = QuickbaseOperationError("upsert", "Rate limited")
+        assert "Quickbase upsert failed" in str(error)
+        assert "Rate limited" in str(error)
+
+    def test_error_attributes(self):
+        """Test error attributes."""
+        error = QuickbaseOperationError("delete", "Record not found")
+        assert error.operation == "delete"
+        assert error.details == "Record not found"
+
+
+class TestHandleUpsert:
+    """Tests for handle_upsert function."""
+
+    def test_upsert_success(self, mock_qb_api):
+        """Test successful upsert."""
+        data = [{"field1": "value1"}]
+
+        result = handle_upsert(mock_qb_api, "tblXYZ", data, description="Test upsert")
+
+        assert "metadata" in result
+        mock_qb_api.upsert_records.assert_called_once_with("tblXYZ", data=data)
+
+    def test_upsert_logs_result(self, mock_qb_api, caplog):
+        """Test that upsert logs result counts."""
+        data = [{"field1": "value1"}]
+
+        handle_upsert(mock_qb_api, "tblXYZ", data, description="Test upsert")
+
+        assert "1 created" in caplog.text
+        assert "1 updated" in caplog.text
+
+    def test_upsert_failure(self, mock_qb_api):
+        """Test that upsert failure raises QuickbaseOperationError."""
+        mock_qb_api.upsert_records.side_effect = Exception("Invalid field")
+
+        with pytest.raises(QuickbaseOperationError, match="upsert"):
+            handle_upsert(mock_qb_api, "tblXYZ", [], description="Test")
+
+
+class TestHandleDelete:
+    """Tests for handle_delete function."""
+
+    def test_delete_success(self, mock_qb_api):
+        """Test successful delete."""
+        result = handle_delete(mock_qb_api, "tblXYZ", where="{8.EX.'Inactive'}", description="Test delete")
+
+        assert result == 5
+        mock_qb_api.delete_records.assert_called_once_with("tblXYZ", where="{8.EX.'Inactive'}")
+
+    def test_delete_logs_result(self, mock_qb_api, caplog):
+        """Test that delete logs result."""
+        handle_delete(mock_qb_api, "tblXYZ", where="{8.EX.'Inactive'}")
+
+        assert "5 records deleted" in caplog.text
+
+    def test_delete_failure(self, mock_qb_api):
+        """Test that delete failure raises QuickbaseOperationError."""
+        mock_qb_api.delete_records.side_effect = Exception("Invalid where clause")
+
+        with pytest.raises(QuickbaseOperationError, match="delete"):
+            handle_delete(mock_qb_api, "tblXYZ", where="invalid")
+
+    def test_delete_failure_single_attempt(self, mock_qb_api):
+        """Test that delete fails immediately without retry."""
+        mock_qb_api.delete_records.side_effect = Exception("Permission denied")
+
+        with pytest.raises(QuickbaseOperationError):
+            handle_delete(mock_qb_api, "tblXYZ", where="{8.EX.'Test'}")
+
+        assert mock_qb_api.delete_records.call_count == 1
+
+
+class TestHandleQuery:
+    """Tests for handle_query function."""
+
+    def test_query_success(self, mock_qb_api):
+        """Test successful query."""
+        result = handle_query(
+            mock_qb_api,
+            "tblXYZ",
+            select=[3, 6, 7],
+            where="{8.EX.'Active'}",
+        )
+
+        assert "data" in result
+        assert len(result["data"]) == 2
+
+    def test_query_with_all_parameters(self, mock_qb_api):
+        """Test query with all optional parameters including description."""
+        result = handle_query(
+            mock_qb_api,
+            "tblXYZ",
+            select=[3, 6],
+            where="{8.EX.'Active'}",
+            sort_by=[{"fieldId": 6, "order": "ASC"}],
+            group_by=[{"fieldId": 8}],
+            options={"skip": 0, "top": 100},
+            description="active users",
+        )
+
+        assert result is not None
+        mock_qb_api.query_for_data.assert_called_once()
+
+    def test_query_failure(self, mock_qb_api):
+        """Test that query failure raises QuickbaseOperationError."""
+        mock_qb_api.query_for_data.side_effect = Exception("Invalid field ID")
+
+        with pytest.raises(QuickbaseOperationError, match="query"):
+            handle_query(mock_qb_api, "tblXYZ", select=[999])
+
+    def test_query_description_in_logs(self, mock_qb_api, caplog):
+        """Test that description appears in error log message on failure."""
+        mock_qb_api.query_for_data.side_effect = Exception("Invalid field ID")
+
+        with pytest.raises(QuickbaseOperationError):
+            handle_query(mock_qb_api, "tblXYZ", description="customer records")
+
+        assert "customer records" in caplog.text
+        assert any(record.levelname == "ERROR" for record in caplog.records)

quickbase_extract-0.4.3/src/quickbase_extract/api_handlers.py

@@ -1,210 +0,0 @@
-"""Error handling utilities for Quickbase operations.
-
-Provides retry logic for rate-limited requests, standardized error handling,
-and logging for Quickbase API operations.
-"""
-
-import logging
-import random
-import time
-
-logger = logging.getLogger(__name__)
-
-
-class QuickbaseOperationError(Exception):
-    """Raised when a Quickbase API operation fails."""
-
-    def __init__(self, operation: str, details: str = ""):
-        self.operation = operation
-        self.details = details
-        super().__init__(f"Quickbase {operation} failed: {details}")
-
-
-def handle_upsert(
-    client,
-    table_id: str,
-    data: list[dict],
-    description: str = "",
-    max_retries: int = 3,
-) -> dict | None:
-    """Execute a Quickbase upsert with error handling, retry logic, and logging.
-
-    Retries on rate limiting (429 errors) with exponential backoff and jitter.
-    Wait time is capped at 60 seconds per retry.
-
-    Args:
-        client: Quickbase API client.
-        table_id: Target table ID.
-        data: List of record dicts to upsert.
-        description: Human-readable description for logging. Defaults to empty string.
-        max_retries: Maximum number of retry attempts. Defaults to 3.
-
-    Returns:
-        API response dict containing metadata about created/updated/unchanged records.
-
-    Raises:
-        QuickbaseOperationError: If the upsert fails after all retries.
-
-    Example:
-        >>> records = [{"6": {"value": "John"}, "7": {"value": "Doe"}}]
-        >>> result = handle_upsert(client, "bq8xyx9z", records, "customer records")
-    """
-    for attempt in range(max_retries):
-        try:
-            result = client.upsert_records(table_id, data=data)
-
-            created = result.get("metadata", {}).get("createdRecordIds", [])
-            updated = result.get("metadata", {}).get("updatedRecordIds", [])
-            unchanged = result.get("metadata", {}).get("unchangedRecordIds", [])
-
-            logger.info(
-                f"Upsert {description}: {len(created)} created, {len(updated)} updated, {len(unchanged)} unchanged"
-            )
-
-            return result
-
-        except Exception as e:  # Need to catch all exceptions for retry logic
-            error_str = str(e)
-
-            # Retry on 429 (rate limit)
-            if "429" in error_str and attempt < max_retries - 1:
-                wait_time = min(2**attempt, 60) + random.uniform(0, 1)
-                logger.warning(
-                    f"Rate limited on upsert {description} (attempt {attempt + 1}/{max_retries}), "
-                    f"retrying in {wait_time:.1f}s"
-                )
-                time.sleep(wait_time)
-            else:
-                logger.error(f"Upsert {description} failed: {error_str}")
-                raise QuickbaseOperationError("upsert", error_str) from e
-
-
-def handle_delete(
-    client,
-    table_id: str,
-    where: str,
-    description: str = "",
-    max_retries: int = 3,
-) -> int | None:
-    """Execute a Quickbase delete with error handling, logging, and rate limit retry.
-
-    Only retries on rate limiting (429 errors) with exponential backoff and jitter.
-    Other errors fail immediately for safety. Wait time is capped at 60 seconds per retry.
-
-    Args:
-        client: Quickbase API client.
-        table_id: Target table ID.
-        where: Quickbase filter string specifying records to delete.
-        description: Human-readable description for logging. Defaults to empty string.
-        max_retries: Maximum number of retry attempts for rate limits. Defaults to 3.
-
-    Returns:
-        Number of records deleted.
-
-    Raises:
-        QuickbaseOperationError: If the delete fails.
-
-    Example:
-        >>> deleted = handle_delete(client, "bq8xyx9z", "{3.EX.'test'}", "test records")
-
-    Note:
-        For safety, only 429 (rate limit) errors are retried. All other errors
-        fail immediately to prevent unintended deletions.
-    """
-    for attempt in range(max_retries):
-        try:
-            deleted = client.delete_records(table_id, where=where)
-            logger.info(f"Delete {description}: {deleted} records deleted")
-            return deleted
-
-        except Exception as e:  # Need to catch all exceptions for retry logic
-            error_str = str(e)
-
-            # Only retry on 429 (rate limit) - other errors are too risky to retry
-            if "429" in error_str and attempt < max_retries - 1:
-                wait_time = min(2**attempt, 60) + random.uniform(0, 1)
-                logger.warning(
-                    f"Rate limited on delete {description} (attempt {attempt + 1}/{max_retries}), "
-                    f"retrying in {wait_time:.1f}s"
-                )
-                time.sleep(wait_time)
-            else:
-                logger.error(f"Delete {description} failed: {error_str}")
-                raise QuickbaseOperationError("delete", error_str) from e
-
-
-def handle_query(
-    client,
-    table_id: str,
-    *,
-    select: list[int] | None = None,
-    where: str | None = None,
-    sort_by: list[dict] | None = None,
-    group_by: list[dict] | None = None,
-    options: dict | None = None,
-    description: str = "",
-    max_retries: int = 3,
-) -> dict | None:
-    """Execute a Quickbase query with error handling, retry logic, and logging.
-
-    Retries on rate limiting (429 errors) with exponential backoff and jitter.
-    Wait time is capped at 60 seconds per retry.
-
-    Args:
-        client: Quickbase API client.
-        table_id: Target table ID.
-        select: List of field IDs to return. If omitted, returns fields from
-            the default report.
-        where: A Quickbase query string (e.g., "{12.EX.'VPF'}").
-        sort_by: Sort order, e.g., [{"fieldId": 6, "order": "ASC"}].
-        group_by: Grouping, e.g., [{"fieldId": 6, "grouping": "equal-values"}].
-        options: Additional options, e.g.,
-            {"skip": 0, "top": 100, "compareWithAppLocalTime": False}.
-        description: Human-readable description for logging. Defaults to empty string.
-        max_retries: Maximum number of retry attempts. Defaults to 3.
-
-    Returns:
-        API response dict containing query results.
-
-    Raises:
-        QuickbaseOperationError: If the query fails after all retries.
-
-    Example:
-        >>> result = handle_query(
-        ...     client,
-        ...     "bq8xyx9z",
-        ...     select=[6, 7, 8],
-        ...     where="{12.EX.'Active'}",
-        ...     description="active customers"
-        ... )
-    """
-    for attempt in range(max_retries):
-        try:
-            result = client.query_for_data(
-                table_id,
-                select=select,
-                where=where,
-                sort_by=sort_by,
-                group_by=group_by,
-                options=options,
-            )
-            record_count = len(result.get("data", []))
-            desc_str = f" {description}" if description else ""
-            logger.info(f"Query{desc_str} returned {record_count} records")
-            return result
-
-        except Exception as e:  # Need to catch all exceptions for retry logic
-            error_str = str(e)
-
-            if "429" in error_str and attempt < max_retries - 1:
-                wait_time = min(2**attempt, 60) + random.uniform(0, 1)
-                desc_str = f" {description}" if description else f" table {table_id}"
-                logger.warning(
-                    f"Rate limited on query{desc_str} (attempt {attempt + 1}/{max_retries}), "
-                    f"retrying in {wait_time:.1f}s"
-                )
-                time.sleep(wait_time)
-            else:
-                desc_str = f" {description}" if description else f" on table {table_id}"
-                logger.error(f"Query{desc_str} failed: {error_str}")
-                raise QuickbaseOperationError("query", error_str) from e

quickbase_extract-0.4.3/tests/test_api_handlers.py

@@ -1,244 +0,0 @@
-"""Unit tests for api_handlers module."""
-
-import time
-
-import pytest
-
-from quickbase_extract.api_handlers import (
-    QuickbaseOperationError,
-    handle_delete,
-    handle_query,
-    handle_upsert,
-)
-
-
-class TestQuickbaseOperationError:
-    """Tests for QuickbaseOperationError exception."""
-
-    def test_error_message(self):
-        """Test error message format."""
-        error = QuickbaseOperationError("upsert", "Rate limited")
-        assert "Quickbase upsert failed" in str(error)
-        assert "Rate limited" in str(error)
-
-    def test_error_attributes(self):
-        """Test error attributes."""
-        error = QuickbaseOperationError("delete", "Record not found")
-        assert error.operation == "delete"
-        assert error.details == "Record not found"
-
-
-class TestHandleUpsert:
-    """Tests for handle_upsert function."""
-
-    def test_upsert_success(self, mock_qb_api):
-        """Test successful upsert."""
-        data = [{"field1": "value1"}]
-
-        result = handle_upsert(mock_qb_api, "tblXYZ", data, description="Test upsert")
-
-        assert "metadata" in result
-        mock_qb_api.upsert_records.assert_called_once_with("tblXYZ", data=data)
-
-    def test_upsert_logs_result(self, mock_qb_api, caplog):
-        """Test that upsert logs result counts."""
-        data = [{"field1": "value1"}]
-
-        handle_upsert(mock_qb_api, "tblXYZ", data, description="Test upsert")
-
-        assert "1 created" in caplog.text
-        assert "1 updated" in caplog.text
-
-    def test_upsert_failure_non_retriable(self, mock_qb_api):
-        """Test upsert failure with non-retriable error."""
-        mock_qb_api.upsert_records.side_effect = Exception("Invalid field")
-
-        with pytest.raises(QuickbaseOperationError, match="upsert"):
-            handle_upsert(mock_qb_api, "tblXYZ", [], description="Test")
-
-    def test_upsert_retry_on_rate_limit(self, mock_qb_api):
-        """Test upsert retry on 429 rate limit."""
-        # Fail twice, then succeed
-        mock_qb_api.upsert_records.side_effect = [
-            Exception("429 Rate Limit Exceeded"),
-            Exception("429 Rate Limit Exceeded"),
-            {
-                "metadata": {
-                    "createdRecordIds": [],
-                    "updatedRecordIds": [],
-                    "unchangedRecordIds": [],
-                }
-            },
-        ]
-
-        with pytest.raises(QuickbaseOperationError):
-            # Will still fail after max retries, but should have tried multiple times
-            handle_upsert(mock_qb_api, "tblXYZ", [], max_retries=2)
-
-        assert mock_qb_api.upsert_records.call_count >= 2
-
-    def test_upsert_max_retries_customizable(self, mock_qb_api):
-        """Test that max_retries parameter is respected."""
-        mock_qb_api.upsert_records.side_effect = Exception("429 Rate Limit")
-
-        with pytest.raises(QuickbaseOperationError):
-            handle_upsert(mock_qb_api, "tblXYZ", [], max_retries=2)
-
-        assert mock_qb_api.upsert_records.call_count == 2
-
-    def test_upsert_wait_time_cap(self, mock_qb_api):
-        """Test that wait time is capped at 60 seconds."""
-        mock_qb_api.upsert_records.side_effect = [
-            Exception("429 Rate Limit"),
-            {
-                "metadata": {
-                    "createdRecordIds": [],
-                    "updatedRecordIds": [],
-                    "unchangedRecordIds": [],
-                }
-            },
-        ]
-
-        start = time.time()
-        handle_upsert(mock_qb_api, "tblXYZ", [], max_retries=10)  # Would be 2^9 = 512s without cap
-        elapsed = time.time() - start
-
-        # Should be capped at ~60 seconds, not 512
-        assert elapsed < 65  # Allow some margin
-
-
-class TestHandleDelete:
-    """Tests for handle_delete function."""
-
-    def test_delete_success(self, mock_qb_api):
-        """Test successful delete."""
-        result = handle_delete(mock_qb_api, "tblXYZ", where="{8.EX.'Inactive'}", description="Test delete")
-
-        assert result == 5
-        mock_qb_api.delete_records.assert_called_once_with("tblXYZ", where="{8.EX.'Inactive'}")
-
-    def test_delete_logs_result(self, mock_qb_api, caplog):
-        """Test that delete logs result."""
-        handle_delete(mock_qb_api, "tblXYZ", where="{8.EX.'Inactive'}")
-
-        assert "5 records deleted" in caplog.text
-
-    def test_delete_failure(self, mock_qb_api):
-        """Test delete failure."""
-        mock_qb_api.delete_records.side_effect = Exception("Invalid where clause")
-
-        with pytest.raises(QuickbaseOperationError, match="delete"):
-            handle_delete(mock_qb_api, "tblXYZ", where="invalid")
-
-    def test_delete_retries_on_rate_limit(self, mock_qb_api):
-        """Test that delete retries on 429 rate limit."""
-        mock_qb_api.delete_records.side_effect = [
-            Exception("429 Rate Limit"),
-            5,
-        ]
-
-        result = handle_delete(mock_qb_api, "tblXYZ", where="{8.EX.'Test'}")
-
-        assert result == 5
-        assert mock_qb_api.delete_records.call_count == 2
-
-    def test_delete_no_retry_on_other_errors(self, mock_qb_api):
-        """Test that delete does not retry non-rate-limit errors."""
-        mock_qb_api.delete_records.side_effect = Exception("Permission denied")
-
-        with pytest.raises(QuickbaseOperationError):
-            handle_delete(mock_qb_api, "tblXYZ", where="{8.EX.'Test'}")
-
-        # Should only try once for non-rate-limit errors
-        assert mock_qb_api.delete_records.call_count == 1
-
-
-class TestHandleQuery:
-    """Tests for handle_query function."""
-
-    def test_query_success(self, mock_qb_api):
-        """Test successful query."""
-        result = handle_query(
-            mock_qb_api,
-            "tblXYZ",
-            select=[3, 6, 7],
-            where="{8.EX.'Active'}",
-        )
-
-        assert "data" in result
-        assert len(result["data"]) == 2
-
-    def test_query_with_all_parameters(self, mock_qb_api):
-        """Test query with all optional parameters including description."""
-        result = handle_query(
-            mock_qb_api,
-            "tblXYZ",
-            select=[3, 6],
-            where="{8.EX.'Active'}",
-            sort_by=[{"fieldId": 6, "order": "ASC"}],
-            group_by=[{"fieldId": 8}],
-            options={"skip": 0, "top": 100},
-            description="active users",
-        )
-
-        assert result is not None
-        mock_qb_api.query_for_data.assert_called_once()
-
-    def test_query_failure_non_retriable(self, mock_qb_api):
-        """Test query failure with non-retriable error."""
-        mock_qb_api.query_for_data.side_effect = Exception("Invalid field ID")
-
-        with pytest.raises(QuickbaseOperationError, match="query"):
-            handle_query(mock_qb_api, "tblXYZ", select=[999])
-
-    def test_query_retry_on_rate_limit(self, mock_qb_api):
-        """Test query retry on 429 rate limit."""
-        mock_qb_api.query_for_data.side_effect = [
-            Exception("429 Rate Limit Exceeded"),
-            {"data": []},
-        ]
-
-        result = handle_query(mock_qb_api, "tblXYZ")
-
-        assert mock_qb_api.query_for_data.call_count == 2
-        assert result == {"data": []}
-
-    def test_query_max_retries_customizable(self, mock_qb_api):
-        """Test that max_retries parameter is respected."""
-        mock_qb_api.query_for_data.side_effect = Exception("429 Rate Limit")
-
-        with pytest.raises(QuickbaseOperationError):
-            handle_query(mock_qb_api, "tblXYZ", max_retries=2)
-
-        assert mock_qb_api.query_for_data.call_count == 2
-
-    def test_query_logs_record_count(self, mock_qb_api, caplog):
-        """Test that query logs record count at info level."""
-        handle_query(mock_qb_api, "tblXYZ", description="test query")
-
-        assert "2 records" in caplog.text
-        # Check it's at info level, not debug
-        assert any(record.levelname == "INFO" for record in caplog.records)
-
-    def test_query_exponential_backoff(self, mock_qb_api):
-        """Test that retries use exponential backoff with cap."""
-        mock_qb_api.query_for_data.side_effect = [
-            Exception("429 Rate Limit"),
-            Exception("429 Rate Limit"),
-            {"data": []},
-        ]
-
-        start = time.time()
-        handle_query(mock_qb_api, "tblXYZ", max_retries=3)
-        elapsed = time.time() - start
-
-        # Should have some delay due to exponential backoff
-        # (2^0 + 2^1) = 3 seconds + random = at least ~3 seconds
-        assert elapsed >= 2  # Allow some margin
-
-    def test_query_description_in_logs(self, mock_qb_api, caplog):
-        """Test that description appears in log messages."""
-        handle_query(mock_qb_api, "tblXYZ", description="customer records")
-
-        assert "customer records" in caplog.text
-        assert "customer records" in caplog.text