quickbase-extract 0.3.1__tar.gz → 0.4.1__tar.gz

{quickbase_extract-0.3.1 → quickbase_extract-0.4.1}/.pre-commit-config.yaml

@@ -9,7 +9,7 @@ repos:
       - id: debug-statements    # Prevents accidental pdb/breakpoint commits
 
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.1.11
+    rev: v0.15.11
     hooks:
       - id: ruff
         args: [--fix]

{quickbase_extract-0.3.1 → quickbase_extract-0.4.1}/CHANGELOG.md

@@ -5,6 +5,37 @@ 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.4.1] - 2026-05-01
+
+### Fixed
+
+- `load_report_metadata()` return type changed from `dict` to `dict[ReportConfig, dict]` to match `load_report_metadata_batch()` and ensure consistent API with `get_data()`
+- Fixed incompatibility where `load_report_metadata()` result could not be directly passed to `get_data()` due to format mismatch
+
+## [0.4.0] - 2026-04-29
+
+### Added
+
+- Support for multiple values in `ask_values` parameters - values can now be strings or lists of strings
+- Automatic OR condition expansion: list values like `{"ask1": ["val1", "val2", "val3"]}` expand to `({'25'.EX.'val1'}OR{'25'.EX.'val2'}OR{'25'.EX.'val3'})`
+- Proper grouping with parentheses when multiple values are used to preserve filter logic precedence
+- Validation for empty lists in `ask_values` - raises `ValueError` if empty list provided
+- `filter_metadata_by_table()` helper function for convenient report metadata lookup by table name, with optional app name filtering to resolve ambiguous table names across apps
+- Helper functions `_validate_ask_values()` and `_normalize_ask_values()` for cleaner separation of concerns in placeholder replacement
+
+### Changed
+
+- `ask_values` type hint updated from `dict[str, str]` to `dict[str, str | list[str]]` in `get_data()` and `get_data_parallel()`
+- `_replace_ask_placeholders()` refactored to use helper functions for validation and normalization, improving testability and maintainability
+- Filter replacement now extracts and replaces full condition blocks (e.g., `{'25'.EX.'_ask1_'}`) instead of just placeholders
+- Placeholder replacement now processes all occurrences using `re.finditer()` instead of only the first match
+
+### Fixed
+
+- Complex filters with multiple conditions now maintain proper precedence when list values are expanded
+- **BREAKING FIX**: Multiple condition blocks with the same placeholder are now all replaced correctly (previously only first occurrence was replaced)
+- String position preservation during replacement to handle complex multi-placeholder filters correctly
+
 ## [0.3.1] - 2026-04-27
 
 ### Fixed
@@ -83,9 +114,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - `cache_freshness.py` module — functionality consolidated into `cache_manager.py` (use `ensure_cache_freshness()` instead)
 - `check_cache_freshness()`, `get_cache_files()`, `get_cache_summary()` functions — use `CacheManager` methods directly or `ensure_cache_freshness()` for orchestration
-- `refresh_all()` function**: Use `ensure_cache_freshness()` for cache management
-- `client.py` module**: Users must create Quickbase clients directly using `quickbase-api` package
-- `get_cache_manager()` singleton**: Users must create `CacheManager` instances explicitly
+- `refresh_all()` function\*\*: Use `ensure_cache_freshness()` for cache management
+- `client.py` module\*\*: Users must create Quickbase clients directly using `quickbase-api` package
+- `get_cache_manager()` singleton\*\*: Users must create `CacheManager` instances explicitly
 - `find_report()` function from utils - no longer needed with `ReportConfig`
 - Dict-based report config format - all configs must use `ReportConfig` NamedTuple
 - Nested `report` object from metadata - simplified structure

{quickbase_extract-0.3.1 → quickbase_extract-0.4.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: quickbase-extract
-Version: 0.3.1
+Version: 0.4.1
 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
@@ -20,8 +20,8 @@ Requires-Dist: boto3>=1.26.0
 Requires-Dist: quickbase-api>=0.3.1
 Provides-Extra: dev
 Requires-Dist: pytest-cov>=4.0; extra == 'dev'
-Requires-Dist: pytest>=7.0; extra == 'dev'
-Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Requires-Dist: pytest>=9.0.3; extra == 'dev'
+Requires-Dist: ruff>=0.15.11; extra == 'dev'
 Description-Content-Type: text/markdown
 
 # Quickbase Extract
@@ -47,7 +47,7 @@ pip install quickbase-extract
 
 ### Requirements
 
-- Python 3.9+
+- Python 3.12+
 - `quickbase-api` - Quickbase API client
 - `boto3` - AWS SDK (for Lambda/S3 support)
 

{quickbase_extract-0.3.1 → quickbase_extract-0.4.1}/README.md

@@ -21,7 +21,7 @@ pip install quickbase-extract
 
 ### Requirements
 
-- Python 3.9+
+- Python 3.12+
 - `quickbase-api` - Quickbase API client
 - `boto3` - AWS SDK (for Lambda/S3 support)
 

{quickbase_extract-0.3.1 → quickbase_extract-0.4.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "quickbase-extract"
-version = "0.3.1"
+version = "0.4.1"
 description = "Extract and cache Quickbase report data with built-in error handling and S3 support"
 readme = "README.md"
 requires-python = ">=3.12"
@@ -29,9 +29,9 @@ dependencies = [
 
 [project.optional-dependencies]
 dev = [
-    "pytest>=7.0",
+    "pytest>=9.0.3",
     "pytest-cov>=4.0",
-    "ruff>=0.1.0",
+    "ruff>=0.15.11",
 ]
 
 [project.urls]
@@ -48,5 +48,5 @@ line-length = 120
 target-version = "py312"
 
 [tool.ruff.lint]
-select = ["E", "F", "W", "I", "UP", "N", "C4", "BLE", "A"]
+select = ["F", "E", "W", "B", "BLE", "I", "UP", "A", "RUF", "T10"]
 ignore = ["E501"]

{quickbase_extract-0.3.1 → quickbase_extract-0.4.1}/src/quickbase_extract/__init__.py

@@ -42,11 +42,12 @@ from quickbase_extract.cache_sync import complete_cache_refresh, is_cache_synced
 # Config
 from quickbase_extract.config import ReportConfig
 
-# Report data retrieval
+# Report data
 from quickbase_extract.report_data import get_data, get_data_parallel, load_data, load_data_batch
 
 # Report metadata
 from quickbase_extract.report_metadata import (
+    filter_metadata_by_table,
     get_report_metadata,
     get_report_metadata_parallel,
     load_report_metadata,
@@ -62,31 +63,25 @@ __version__ = version("quickbase-extract")
 logging.getLogger(__name__).addHandler(logging.NullHandler())
 
 __all__ = [
-    # Version
-    "__version__",
-    # Cache management
     "CacheManager",
-    "ensure_cache_freshness",
-    "complete_cache_refresh",
-    "sync_from_s3_once",
-    "is_cache_synced",
-    # Config
-    "ReportConfig",
-    # API operations
     "QuickbaseOperationError",
+    "ReportConfig",
+    "__version__",
+    "complete_cache_refresh",
+    "ensure_cache_freshness",
+    "filter_metadata_by_table",
+    "get_data",
+    "get_data_parallel",
+    "get_report_metadata",
+    "get_report_metadata_parallel",
     "handle_delete",
     "handle_query",
     "handle_upsert",
-    # Report metadata
-    "get_report_metadata",
-    "get_report_metadata_parallel",
-    "load_report_metadata",
-    "load_report_metadata_batch",
-    # Report data
-    "get_data",
-    "get_data_parallel",
+    "is_cache_synced",
     "load_data",
     "load_data_batch",
-    # Utilities
+    "load_report_metadata",
+    "load_report_metadata_batch",
     "normalize_name",
+    "sync_from_s3_once",
 ]

{quickbase_extract-0.3.1 → quickbase_extract-0.4.1}/src/quickbase_extract/api_handlers.py

@@ -4,8 +4,6 @@ Provides retry logic for rate-limited requests, standardized error handling,
 and logging for Quickbase API operations.
 """
 
-# ruff: noqa: BLE001
-
 import logging
 import random
 import time
@@ -139,11 +137,11 @@ def handle_query(
     client,
     table_id: str,
     *,
-    select: list[int] = None,
-    where: str = None,
-    sort_by: list[dict] = None,
-    group_by: list[dict] = None,
-    options: dict = None,
+    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:

{quickbase_extract-0.3.1 → quickbase_extract-0.4.1}/src/quickbase_extract/cache_manager.py

@@ -308,7 +308,7 @@ class CacheManager:
             return 0
 
         oldest_mtime = min(f.stat().st_mtime for f in json_files)
-        # 60 sec × 60 min = 3600
+        # 60 sec * 60 min = 3600
         age_hours = (time.time() - oldest_mtime) / 3600
 
         return round(age_hours, 1)

{quickbase_extract-0.3.1 → quickbase_extract-0.4.1}/src/quickbase_extract/cache_orchestration.py

@@ -123,6 +123,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 = None,
 ) -> None:
     """Refresh data cache for specified reports.
 
@@ -131,6 +132,8 @@ 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.
+            Per-report "ask the user" filter values.
 
     Raises:
         CacheRefreshError: If data refresh fails.
@@ -148,6 +151,7 @@ def _refresh_data_cache(
             report_configs=reports_to_refresh,
             report_metadata=metadata,
             cache=True,
+            ask_values=ask_values,
         )
         logger.info("Data cache refresh completed successfully")
     except Exception as e:
@@ -160,6 +164,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 = None,
     metadata_stale_hours: float | None = None,
     data_stale_hours: float | None = None,
     cache_all_data: bool = False,
@@ -184,6 +189,12 @@ def ensure_cache_freshness(
         report_configs_to_cache: Optional subset of ReportConfig instances to
             cache data for. If cache_all_data is True, this parameter is ignored
             and all reports' data is cached instead.
+        ask_values: Optional dict mapping ReportConfig -> ask_values dict.
+            Per-report "ask the user" filter values. Only used when refreshing
+            data cache. Example: {
+                ReportConfig("bq8x", "Accounts", "Python"): {"ask1": "abc"},
+                ReportConfig("bq9y", "Contacts", "Active"): {"ask1": "def"}
+            }
         metadata_stale_hours: Threshold (hours) for metadata staleness.
             If not provided, reads from METADATA_STALE_HOURS env var,
             falls back to DEFAULT_METADATA_STALE_HOURS (168 hours / 7 days).
@@ -221,12 +232,14 @@ def ensure_cache_freshness(
         ...     report_configs_to_cache=get_reports_to_cache(),
         ... )
         >>>
-        >>> # Cache all reports' data
+        >>> # Cache all reports' data with ask_values
+        >>> ask_vals = {get_all_reports()[0]: {"ask1": "value1"}}
         >>> ensure_cache_freshness(
         ...     client=client,
         ...     cache_manager=cache_manager,
         ...     report_configs_all=get_all_reports(),
         ...     cache_all_data=True,
+        ...     ask_values=ask_vals,
         ... )
     """
     # Resolve thresholds from arguments, environment, or defaults
@@ -295,4 +308,4 @@ def ensure_cache_freshness(
 
     # Refresh data if needed
     if data_needs_refresh:
-        _refresh_data_cache(client, cache_manager, reports_to_refresh_data, data_reasons)
+        _refresh_data_cache(client, cache_manager, reports_to_refresh_data, reasons=data_reasons, ask_values=ask_values)

{quickbase_extract-0.3.1 → quickbase_extract-0.4.1}/src/quickbase_extract/report_data.py

@@ -12,70 +12,153 @@ from quickbase_extract.config import ReportConfig
 logger = logging.getLogger(__name__)
 
 
+def _validate_ask_values(
+    ask_values: dict[str, str | list[str]],
+    placeholders_in_filter: set[str],
+    report_config: ReportConfig,
+) -> None:
+    """Validate that ask_values matches placeholders in filter.
+
+    Ensures that:
+    - All placeholders in the filter have corresponding values in ask_values
+    - All values in ask_values are actually used in the filter
+    - No empty lists are provided
+
+    Args:
+        ask_values: Dict mapping placeholder keys (e.g., "ask1") to values or lists of values.
+        placeholders_in_filter: Set of placeholder strings found in filter (e.g., {"_ask1_", "_ask2_"}).
+        report_config: ReportConfig for error messages.
+
+    Raises:
+        ValueError: If values are missing, unused, or if any list is empty.
+    """
+    # Check for missing values
+    missing_values = [p for p in placeholders_in_filter if p.strip("_") not in ask_values]
+    if missing_values:
+        raise ValueError(
+            f"Report {report_config} filter requires values for {missing_values}, "
+            f"but they were not provided in ask_values."
+        )
+
+    # Check for unused values
+    unused_values = [k for k in ask_values.keys() if f"_{k}_" not in placeholders_in_filter]
+    if unused_values:
+        raise ValueError(
+            f"Report {report_config} received ask_values {unused_values} "
+            f"that are not used in the filter. Available placeholders: {list(placeholders_in_filter)}"
+        )
+
+    # Check for empty lists
+    empty_list_keys = [k for k, v in ask_values.items() if isinstance(v, list) and len(v) == 0]
+    if empty_list_keys:
+        raise ValueError(
+            f"Report {report_config} received empty lists for ask_values keys: {empty_list_keys}. "
+            f"Empty lists are not allowed."
+        )
+
+
+def _normalize_ask_values(ask_values: dict[str, str | list[str]]) -> dict[str, list[str]]:
+    """Normalize all ask_values to lists for consistent processing.
+
+    Converts single string values to single-element lists, leaving list values
+    unchanged. This allows downstream logic to handle all values uniformly.
+
+    Args:
+        ask_values: Dict with values that are either strings or lists of strings.
+
+    Returns:
+        Dict with all values as lists of strings.
+
+    Example:
+        >>> _normalize_ask_values({"ask1": "value", "ask2": ["a", "b"]})
+        {"ask1": ["value"], "ask2": ["a", "b"]}
+    """
+    normalized = {}
+    for key, value in ask_values.items():
+        normalized[key] = [value] if isinstance(value, str) else value
+    return normalized
+
+
 def _replace_ask_placeholders(
     report_filter: str,
-    ask_values: dict[str, str],
+    ask_values: dict[str, str | list[str]],
     report_config: ReportConfig,
 ) -> str:
     """Replace ask-the-user placeholders in a Quickbase filter with actual values.
 
+    Finds all placeholders (e.g., _ask1_, _ask2_) in the filter and replaces them
+    with provided values. Single values are replaced directly, while multiple values
+    in a list are expanded into OR conditions with proper grouping to preserve
+    filter logic precedence.
+
     Args:
         report_filter: The filter string from report metadata (e.g., "{'25'.EX.'_ask1_'}").
-        ask_values: Dict mapping placeholder keys to values (e.g., {"ask1": "abc123"}).
+        ask_values: Dict mapping placeholder keys to values or lists of values.
+            Keys like "ask1", "ask2". Values can be strings or lists of strings.
+            Example: {"ask1": "abc123"} or {"ask1": ["abc123", "abc456"]}
         report_config: ReportConfig for error messages.
 
     Returns:
         Modified filter string with placeholders replaced.
 
     Raises:
-        ValueError: If required placeholders are missing values or unused values provided.
+        ValueError: If required placeholders are missing values, unused values provided,
+                   empty lists provided, or condition blocks cannot be found.
 
     Example:
         >>> filter_str = "{'25'.EX.'_ask1_'}AND{'10'.AF.'today'}"
         >>> config = ReportConfig("bq8xyx9z", "Accounts", "Python")
+        >>> # Single value
         >>> _replace_ask_placeholders(filter_str, {"ask1": "abc123"}, config)
         "{'25'.EX.'abc123'}AND{'10'.AF.'today'}"
+        >>> # Multiple values
+        >>> _replace_ask_placeholders(filter_str, {"ask1": ["val1", "val2"]}, config)
+        "(({'25'.EX.'val1'}OR{'25'.EX.'val2'}))AND{'10'.AF.'today'}"
+        >>> # Multiple condition blocks with same placeholder
+        >>> _replace_ask_placeholders(
+        ...     "({'41'.EX.'_ask1_'}OR{'40'.EX.'_ask1_'})",
+        ...     {"ask1": ["a", "b"]},
+        ...     config
+        ... )
+        "(({'41'.EX.'a'}OR{'41'.EX.'b'})OR({'40'.EX.'a'}OR{'40'.EX.'b'}))"
     """
-    # Find all placeholders in the filter (e.g., _ask1_, _ask2_)
     placeholders_in_filter = set(re.findall(r"_ask\d+_", report_filter))
 
     if not placeholders_in_filter:
-        # No placeholders found - nothing to replace
         return report_filter
 
-    # Validate: all placeholders in filter must have corresponding values
-    missing_values = []
+    # Validate and normalize
+    _validate_ask_values(ask_values, placeholders_in_filter, report_config)
+    normalized_values = _normalize_ask_values(ask_values)
+
+    # Replace placeholders
+    modified_filter = report_filter
     for placeholder in placeholders_in_filter:
-        # Convert _ask1_ to ask1 for lookup
         key = placeholder.strip("_")
-        if key not in ask_values:
-            missing_values.append(placeholder)
+        values = normalized_values[key]
 
-    if missing_values:
-        raise ValueError(
-            f"Report {report_config} filter requires values for {missing_values}, "
-            f"but they were not provided in ask_values."
-        )
+        # Find ALL condition blocks containing this placeholder
+        # Pattern: {...'_ask1_'...} where we capture the entire {...}
+        condition_pattern = rf"(\{{[^}}]*{re.escape(placeholder)}[^{{]*\}})"
+        matches = list(re.finditer(condition_pattern, modified_filter))
 
-    # Validate: all provided values must be used in filter
-    unused_values = []
-    for key in ask_values.keys():
-        placeholder = f"_{key}_"
-        if placeholder not in placeholders_in_filter:
-            unused_values.append(key)
+        if not matches:
+            raise ValueError(f"Report {report_config} could not find condition block for placeholder {placeholder}")
 
-    if unused_values:
-        raise ValueError(
-            f"Report {report_config} received ask_values {unused_values} "
-            f"that are not used in the filter. Available placeholders: {list(placeholders_in_filter)}"
-        )
+        # Process matches in reverse order to maintain string positions during replacement
+        for match in reversed(matches):
+            original_condition = match.group(1)
 
-    # Replace placeholders with actual values
-    modified_filter = report_filter
-    for placeholder in placeholders_in_filter:
-        key = placeholder.strip("_")
-        value = ask_values[key]
-        modified_filter = modified_filter.replace(placeholder, value)
+            if len(values) == 1:
+                # Single value: simple replacement
+                new_condition = original_condition.replace(placeholder, values[0])
+            else:
+                # Multiple values: replicate condition and join with OR
+                replicated_conditions = [original_condition.replace(placeholder, v) for v in values]
+                new_condition = f"({('OR'.join(replicated_conditions))})"
+
+            # Replace using string slicing to preserve positions for other replacements
+            modified_filter = modified_filter[: match.start()] + new_condition + modified_filter[match.end() :]
 
     return modified_filter
 
@@ -132,7 +215,7 @@ def get_data(
     report_config: ReportConfig,
     report_metadata: dict[ReportConfig, dict],
     cache: bool = False,
-    ask_values: dict[str, str] | None = None,
+    ask_values: dict[str, str | list[str]] | None = None,
 ) -> list[dict]:
     """Query a Quickbase table for data using cached report metadata.
 
@@ -217,7 +300,7 @@ def get_data_parallel(
     report_metadata: dict,
     cache: bool = False,
     max_workers: int = 8,
-    ask_values: dict[ReportConfig, dict[str, str] | None] | None = None,
+    ask_values: dict[ReportConfig, dict[str, str | list[str]] | None] | None = None,
 ) -> dict[ReportConfig, list[dict]]:
     """Fetch multiple reports in parallel using cached report metadata.
 

{quickbase_extract-0.3.1 → quickbase_extract-0.4.1}/src/quickbase_extract/report_metadata.py

@@ -238,7 +238,7 @@ def get_report_metadata_parallel(
 def load_report_metadata(
     cache_manager: CacheManager,
     report_config: ReportConfig,
-) -> dict:
+) -> dict[ReportConfig, dict]:
     """Load cached report metadata from disk.
 
     Args:
@@ -246,7 +246,8 @@ def load_report_metadata(
         report_config: ReportConfig identifying the report to load.
 
     Returns:
-        Dict containing table ID, field mappings, query config, and filters.
+        Dict mapping ReportConfig -> metadata dict (table ID, field mappings,
+        query config, and filters).
 
     Raises:
         FileNotFoundError: If cached metadata does not exist.
@@ -255,6 +256,7 @@ def load_report_metadata(
         >>> cache_manager = CacheManager(cache_root=Path("my_project/dev/cache"))
         >>> config = ReportConfig("bq8xyx9z", "Accounts", "Python")
         >>> metadata = load_report_metadata(cache_manager, config)
+        >>> config_metadata = metadata[config]
     """
     # Normalize names to match how they were saved
     app_name = normalize_name(report_config.app_name)
@@ -268,7 +270,8 @@ def load_report_metadata(
             f"Report metadata not found for {report_config}. Run get_report_metadata() first. Expected: {md_path}"
         )
 
-    return json.loads(cache_manager.read_file(md_path))
+    metadata_dict = json.loads(cache_manager.read_file(md_path))
+    return {report_config: metadata_dict}
 
 
 def load_report_metadata_batch(
@@ -304,6 +307,56 @@ def load_report_metadata_batch(
 
     metadata: dict[ReportConfig, dict] = {}
     for config in report_configs:
-        metadata[config] = load_report_metadata(cache_manager, config)
+        metadata.update(load_report_metadata(cache_manager, config))
 
     return metadata
+
+
+def filter_metadata_by_table(
+    report_metadata: dict[ReportConfig, dict],
+    table_name: str,
+    app_name: str | None = None,
+) -> dict:
+    """Retrieve metadata for a specific table, optionally filtered by app.
+
+    Args:
+        report_metadata: dict from load_report_metadata_batch()
+        table_name: Table name (e.g., "Accounts", "Billing Runs")
+        app_name: Optional app name. If not provided, table_name must be unique
+                  across all apps.
+
+    Returns:
+        Metadata dict for the specified table (and app if provided).
+
+    Raises:
+        ValueError: If not found, or if table_name is ambiguous (multiple apps)
+                   without app_name specified.
+
+    Example:
+        >>> metadata = load_report_metadata_batch(cache_manager, configs)
+        >>> runs_md = filter_metadata_by_app_table(metadata, "Billing Runs")
+        >>> accounts = filter_metadata_by_app_table(metadata, "Accounts", app_name="date_lake")
+    """
+    if app_name:
+        # Filter by both app and table
+        results = [
+            data
+            for config, data in report_metadata.items()
+            if config.app_name == app_name and config.table_name == table_name
+        ]
+        error_msg = f"app={app_name}, table={table_name}"
+    else:
+        # Filter by table only
+        results = [data for config, data in report_metadata.items() if config.table_name == table_name]
+        error_msg = f"table={table_name}"
+
+    if not results:
+        raise ValueError(f"No metadata found for {error_msg}")
+
+    if len(results) > 1:
+        available_apps = [config.app_name for config, _ in report_metadata.items() if config.table_name == table_name]
+        raise ValueError(
+            f"Multiple apps have table '{table_name}': {available_apps}. Please specify app_name: {available_apps[0]}"
+        )
+
+    return results[0]

{quickbase_extract-0.3.1 → quickbase_extract-0.4.1}/tests/conftest.py

@@ -3,6 +3,7 @@
 from unittest.mock import MagicMock
 
 import pytest
+
 from quickbase_extract.config import ReportConfig
 
 
@@ -217,5 +218,3 @@ def mock_s3_client():
     from unittest.mock import MagicMock
 
     return MagicMock()
-    return MagicMock()
-    return MagicMock()

{quickbase_extract-0.3.1 → quickbase_extract-0.4.1}/tests/test_api_handlers.py

@@ -3,6 +3,7 @@
 import time
 
 import pytest
+
 from quickbase_extract.api_handlers import (
     QuickbaseOperationError,
     handle_delete,

{quickbase_extract-0.3.1 → quickbase_extract-0.4.1}/tests/test_cache_manager.py

@@ -8,6 +8,7 @@ from pathlib import Path
 from unittest.mock import MagicMock, patch
 
 import pytest
+
 from quickbase_extract.cache_manager import CacheManager
 
 

{quickbase_extract-0.3.1 → quickbase_extract-0.4.1}/tests/test_cache_orchestration.py

@@ -6,6 +6,7 @@ import time
 from unittest.mock import MagicMock, patch
 
 import pytest
+
 from quickbase_extract.cache_manager import CacheManager
 from quickbase_extract.cache_orchestration import (
     CacheRefreshError,
@@ -264,6 +265,7 @@ class TestRefreshDataCache:
                     report_configs=sample_report_configs,
                     report_metadata={config: {} for config in sample_report_configs},
                     cache=True,
+                    ask_values=None,
                 )
                 assert "Data cache refresh needed: data stale" in caplog.text
                 assert "Data cache refresh completed successfully" in caplog.text

{quickbase_extract-0.3.1 → quickbase_extract-0.4.1}/tests/test_cache_sync.py

@@ -3,6 +3,7 @@
 from unittest.mock import MagicMock, patch
 
 import pytest
+
 from quickbase_extract.cache_manager import CacheManager
 from quickbase_extract.cache_sync import (
     _reset_cache_sync,

{quickbase_extract-0.3.1 → quickbase_extract-0.4.1}/tests/test_report_data.py

@@ -3,11 +3,14 @@
 import json
 
 import pytest
+
 from quickbase_extract.cache_manager import CacheManager
 from quickbase_extract.config import ReportConfig
 from quickbase_extract.report_data import (
     _extract_report_names,
+    _normalize_ask_values,
     _replace_ask_placeholders,
+    _validate_ask_values,
     get_data,
     get_data_parallel,
     load_data,
@@ -19,6 +22,103 @@ from quickbase_extract.report_metadata import (
 )
 
 
+class TestValidateAskValues:
+    """Tests for _validate_ask_values helper function."""
+
+    def test_valid_single_placeholder_value(self, sample_report_configs):
+        """Test validation passes with valid single placeholder and value."""
+        config = sample_report_configs[0]
+        placeholders = {"_ask1_"}
+        ask_values = {"ask1": "value"}
+
+        # Should not raise
+        _validate_ask_values(ask_values, placeholders, config)
+
+    def test_valid_multiple_placeholders(self, sample_report_configs):
+        """Test validation passes with multiple placeholders and values."""
+        config = sample_report_configs[0]
+        placeholders = {"_ask1_", "_ask2_"}
+        ask_values = {"ask1": "value1", "ask2": ["value2", "value3"]}
+
+        # Should not raise
+        _validate_ask_values(ask_values, placeholders, config)
+
+    def test_missing_placeholder_value_raises_error(self, sample_report_configs):
+        """Test error when placeholder has no corresponding value."""
+        config = sample_report_configs[0]
+        placeholders = {"_ask1_", "_ask2_"}
+        ask_values = {"ask1": "value1"}  # Missing ask2
+
+        with pytest.raises(ValueError, match=r"requires values for.*_ask2_"):
+            _validate_ask_values(ask_values, placeholders, config)
+
+    def test_unused_ask_value_raises_error(self, sample_report_configs):
+        """Test error when provided value is not used in filter."""
+        config = sample_report_configs[0]
+        placeholders = {"_ask1_"}
+        ask_values = {"ask1": "value1", "ask2": "value2"}  # ask2 not in filter
+
+        with pytest.raises(ValueError, match=r"received ask_values.*ask2.*not used"):
+            _validate_ask_values(ask_values, placeholders, config)
+
+    def test_empty_list_raises_error(self, sample_report_configs):
+        """Test error when empty list provided."""
+        config = sample_report_configs[0]
+        placeholders = {"_ask1_"}
+        ask_values = {"ask1": []}  # Empty list
+
+        with pytest.raises(ValueError, match="empty lists"):
+            _validate_ask_values(ask_values, placeholders, config)
+
+    def test_empty_placeholders_set_validates(self, sample_report_configs):
+        """Test that empty placeholders set validates successfully with empty ask_values."""
+        config = sample_report_configs[0]
+        placeholders = set()
+        ask_values = {}
+
+        # Should not raise
+        _validate_ask_values(ask_values, placeholders, config)
+
+
+class TestNormalizeAskValues:
+    """Tests for _normalize_ask_values helper function."""
+
+    def test_normalize_string_to_list(self):
+        """Test that string values are converted to single-element lists."""
+        ask_values = {"ask1": "value"}
+        result = _normalize_ask_values(ask_values)
+
+        assert result == {"ask1": ["value"]}
+
+    def test_normalize_list_unchanged(self):
+        """Test that list values remain unchanged."""
+        ask_values = {"ask1": ["val1", "val2"]}
+        result = _normalize_ask_values(ask_values)
+
+        assert result == {"ask1": ["val1", "val2"]}
+
+    def test_normalize_mixed_values(self):
+        """Test normalization with mixed string and list values."""
+        ask_values = {"ask1": "single", "ask2": ["multi1", "multi2"]}
+        result = _normalize_ask_values(ask_values)
+
+        assert result == {"ask1": ["single"], "ask2": ["multi1", "multi2"]}
+
+    def test_normalize_empty_dict(self):
+        """Test normalization with empty dict."""
+        ask_values = {}
+        result = _normalize_ask_values(ask_values)
+
+        assert result == {}
+
+    def test_normalize_preserves_order(self):
+        """Test that normalization preserves dict key order."""
+        ask_values = {"ask3": "val3", "ask1": "val1", "ask2": "val2"}
+        result = _normalize_ask_values(ask_values)
+
+        assert list(result.keys()) == ["ask3", "ask1", "ask2"]
+
+
 class TestReplaceAskPlaceholders:
     """Tests for _replace_ask_placeholders function."""
 
@@ -33,7 +133,7 @@ class TestReplaceAskPlaceholders:
         assert result == "{'25'.EX.'abc123'}"
 
     def test_replace_multiple_placeholders(self, sample_report_configs):
-        """Test replacing multiple ask placeholders."""
+        """Test replacing multiple different placeholders."""
         config = sample_report_configs[0]
         filter_str = "({'25'.EX.'_ask1_'}AND{'40'.EX.'_ask2_'})"
         ask_values = {"ask1": "value1", "ask2": "value2"}
@@ -42,6 +142,84 @@ class TestReplaceAskPlaceholders:
 
         assert result == "({'25'.EX.'value1'}AND{'40'.EX.'value2'})"
 
+    def test_replace_placeholder_with_list_values(self, sample_report_configs):
+        """Test replacing placeholder with multiple values creates OR condition."""
+        config = sample_report_configs[0]
+        filter_str = "{'25'.EX.'_ask1_'}"
+        ask_values = {"ask1": ["val1", "val2", "val3"]}
+
+        result = _replace_ask_placeholders(filter_str, ask_values, config)
+
+        expected = "({'25'.EX.'val1'}OR{'25'.EX.'val2'}OR{'25'.EX.'val3'})"
+        assert result == expected
+
+    def test_replace_list_with_single_element(self, sample_report_configs):
+        """Test that list with single element is treated as single value."""
+        config = sample_report_configs[0]
+        filter_str = "{'25'.EX.'_ask1_'}"
+        ask_values = {"ask1": ["only_value"]}
+
+        result = _replace_ask_placeholders(filter_str, ask_values, config)
+
+        # Single element list should not create OR
+        assert result == "{'25'.EX.'only_value'}"
+
+    def test_empty_list_raises_error(self, sample_report_configs):
+        """Test that empty list in ask_values raises ValueError."""
+        config = sample_report_configs[0]
+        filter_str = "{'25'.EX.'_ask1_'}"
+        ask_values = {"ask1": []}
+
+        with pytest.raises(ValueError, match="empty lists"):
+            _replace_ask_placeholders(filter_str, ask_values, config)
+
+    def test_mixed_string_and_list_values(self, sample_report_configs):
+        """Test replacing multiple placeholders with mixed string and list values."""
+        config = sample_report_configs[0]
+        filter_str = "({'25'.EX.'_ask1_'}AND{'40'.EX.'_ask2_'})"
+        ask_values = {"ask1": "single_value", "ask2": ["val1", "val2"]}
+
+        result = _replace_ask_placeholders(filter_str, ask_values, config)
+
+        # ask1 should be simple replacement, ask2 should have OR
+        assert "{'25'.EX.'single_value'}" in result
+        assert "({'40'.EX.'val1'}OR{'40'.EX.'val2'})" in result
+
+    def test_list_values_in_complex_filter(self, sample_report_configs):
+        """Test list value expansion maintains filter logic in complex expressions."""
+        config = sample_report_configs[0]
+        filter_str = "({'15'.EX.'Pending'}AND{'41'.EX.'_ask1_'})"
+        ask_values = {"ask1": ["urgent", "high"]}
+
+        result = _replace_ask_placeholders(filter_str, ask_values, config)
+
+        # Should preserve outer AND structure with inner OR
+        assert "{'15'.EX.'Pending'}" in result
+        assert "({'41'.EX.'urgent'}OR{'41'.EX.'high'})" in result
+
+    def test_multiple_condition_blocks_same_placeholder(self, sample_report_configs):
+        """Test replacing multiple condition blocks with same placeholder."""
+        config = sample_report_configs[0]
+        filter_str = "({'41'.EX.'_ask1_'}OR{'40'.EX.'_ask1_'})"
+        ask_values = {"ask1": "urgent"}
+
+        result = _replace_ask_placeholders(filter_str, ask_values, config)
+
+        expected = "({'41'.EX.'urgent'}OR{'40'.EX.'urgent'})"
+        assert result == expected
+
+    def test_multiple_blocks_same_placeholder_with_list_values(self, sample_report_configs):
+        """Test replacing multiple condition blocks with same placeholder using list values."""
+        config = sample_report_configs[0]
+        filter_str = "({'41'.EX.'_ask1_'}OR{'40'.EX.'_ask1_'})"
+        ask_values = {"ask1": ["a", "b"]}
+
+        result = _replace_ask_placeholders(filter_str, ask_values, config)
+
+        # Each condition block should be expanded
+        assert "({'41'.EX.'a'}OR{'41'.EX.'b'})" in result
+        assert "({'40'.EX.'a'}OR{'40'.EX.'b'})" in result
+
     def test_no_placeholders_returns_unchanged(self, sample_report_configs):
         """Test that filter without placeholders is returned unchanged."""
         config = sample_report_configs[0]
@@ -58,7 +236,7 @@ class TestReplaceAskPlaceholders:
         filter_str = "{'25'.EX.'_ask1_'}AND{'40'.EX.'_ask2_'}"
         ask_values = {"ask1": "value1"}  # Missing ask2
 
-        with pytest.raises(ValueError, match="requires values for.*_ask2_"):
+        with pytest.raises(ValueError, match=r"requires values for.*_ask2_"):
             _replace_ask_placeholders(filter_str, ask_values, config)
 
     def test_unused_placeholder_value_raises_error(self, sample_report_configs):
@@ -67,7 +245,7 @@ class TestReplaceAskPlaceholders:
         filter_str = "{'25'.EX.'_ask1_'}"
         ask_values = {"ask1": "value1", "ask2": "value2"}  # ask2 not in filter
 
-        with pytest.raises(ValueError, match="received ask_values.*ask2.*not used"):
+        with pytest.raises(ValueError, match=r"received ask_values.*ask2.*not used"):
             _replace_ask_placeholders(filter_str, ask_values, config)
 
     def test_placeholder_with_special_characters(self, sample_report_configs):
@@ -81,14 +259,28 @@ class TestReplaceAskPlaceholders:
         assert result == "{'25'.EX.'value with spaces & symbols!'}"
 
     def test_complex_filter_with_mixed_content(self, sample_report_configs):
-        """Test replacing placeholders in complex filter."""
+        """Test replacing placeholders in complex filter with both fixed and dynamic values."""
         config = sample_report_configs[0]
         filter_str = "({'15'.EX.'Pending'}AND({'41'.EX.'_ask1_'}OR{'40'.EX.'_ask1_'}))"
         ask_values = {"ask1": "urgent"}
 
         result = _replace_ask_placeholders(filter_str, ask_values, config)
 
-        assert result == ("({'15'.EX.'Pending'}AND({'41'.EX.'urgent'}OR{'40'.EX.'urgent'}))")
+        expected = "({'15'.EX.'Pending'}AND({'41'.EX.'urgent'}OR{'40'.EX.'urgent'}))"
+        assert result == expected
+
+    def test_complex_filter_with_mixed_content_and_list(self, sample_report_configs):
+        """Test complex filter with multiple condition blocks and list values."""
+        config = sample_report_configs[0]
+        filter_str = "({'15'.EX.'Pending'}AND({'41'.EX.'_ask1_'}OR{'40'.EX.'_ask1_'}))"
+        ask_values = {"ask1": ["urgent", "high"]}
+
+        result = _replace_ask_placeholders(filter_str, ask_values, config)
+
+        # Should have outer structure preserved and inner ORs expanded
+        assert "{'15'.EX.'Pending'}" in result
+        assert "({'41'.EX.'urgent'}OR{'41'.EX.'high'})" in result
+        assert "({'40'.EX.'urgent'}OR{'40'.EX.'high'})" in result
 
 
 class TestExtractReportNames:

{quickbase_extract-0.3.1 → quickbase_extract-0.4.1}/tests/test_report_metadata.py

@@ -3,10 +3,12 @@
 import json
 
 import pytest
+
 from quickbase_extract.cache_manager import CacheManager
 from quickbase_extract.config import ReportConfig
 from quickbase_extract.report_metadata import (
     fetch_report_metadata_api,
+    filter_metadata_by_table,
     get_report_metadata,
     get_report_metadata_parallel,
     load_report_metadata,
@@ -70,7 +72,7 @@ class TestFetchReportMetadataApi:
             {"id": "rptABC", "name": "Default"},
         ]
 
-        with pytest.raises(ValueError, match="Report .* not found"):
+        with pytest.raises(ValueError, match=r"Report .* not found"):
             fetch_report_metadata_api(
                 mock_qb_api,
                 "appXYZ123",
@@ -166,7 +168,7 @@ class TestGetReportMetadata:
             report_name="Nonexistent",
         )
 
-        with pytest.raises(ValueError, match="Report .* not found"):
+        with pytest.raises(ValueError, match=r"Report .* not found"):
             get_report_metadata(
                 mock_qb_api,
                 cache_mgr,
@@ -298,10 +300,12 @@ class TestLoadReportMetadata:
         # Now load it
         metadata = load_report_metadata(cache_mgr, config)
 
-        assert metadata["table_id"] == "tblXYZ123"
-        assert metadata["table_name"] == "test_table"
-        assert "fields" in metadata
-        assert "filter" in metadata
+        # Metadata is now dict[ReportConfig, dict]
+        assert config in metadata
+        assert metadata[config]["table_id"] == "tblXYZ123"
+        assert metadata[config]["table_name"] == "test_table"
+        assert "fields" in metadata[config]
+        assert "filter" in metadata[config]
 
     def test_load_nonexistent_metadata(self, temp_cache_dir, sample_report_configs):
         """Test error when loading non-cached metadata."""
@@ -333,7 +337,8 @@ class TestLoadReportMetadata:
 
         # Should be able to load with original config
         metadata = load_report_metadata(cache_mgr, config)
-        assert metadata is not None
+        assert config in metadata
+        assert metadata[config] is not None
 
 
 class TestLoadReportMetadataBatch:
@@ -392,7 +397,48 @@ class TestLoadReportMetadataBatch:
         # Should be able to look up by config
         config1 = sample_report_configs[0]
         assert all_metadata[config1]["table_id"] == "tblXYZ123"
-        assert all_metadata[config1]["table_id"] == "tblXYZ123"
-        assert all_metadata[config1]["table_id"] == "tblXYZ123"
-        assert all_metadata[config1]["table_id"] == "tblXYZ123"
-        assert all_metadata[config1]["table_id"] == "tblXYZ123"
+
+
+class TestFilterMetadataByTable:
+    """Tests for filter_metadata_by_table function."""
+
+    def test_filter_metadata_by_table_unique(self, sample_report_metadata, sample_report_configs):
+        """Test retrieving metadata for a unique table."""
+
+        table_name = sample_report_configs[0].table_name
+        result = filter_metadata_by_table(sample_report_metadata, table_name)
+
+        assert result["table_name"] == "test_table"
+        assert result["table_id"] == "tblXYZ123"
+
+    def test_get_metadata_by_table_with_app_name(self, sample_report_metadata, sample_report_configs):
+        """Test retrieving metadata filtering by both app and table."""
+
+        config = sample_report_configs[0]
+        result = filter_metadata_by_table(sample_report_metadata, config.table_name, app_name=config.app_name)
+
+        assert result["table_name"] == "test_table"
+        assert result["app_name"] == "test_app"
+
+    def test_get_metadata_by_table_not_found(self, sample_report_metadata):
+        """Test error when table not found."""
+
+        with pytest.raises(ValueError, match="No metadata found"):
+            filter_metadata_by_table(sample_report_metadata, "Nonexistent Table")
+
+    def test_get_metadata_by_table_ambiguous_without_app(self, sample_report_metadata):
+        """Test error when table exists in multiple apps without app_name specified."""
+
+        # Create a second metadata entry with same table name but different app
+        # This would require a fixture with duplicate table names across apps
+        # For now, this documents expected behavior
+        pass
+
+    def test_get_metadata_by_table_ambiguous_with_app(self, sample_report_metadata, sample_report_configs):
+        """Test successful lookup when table is ambiguous but app_name is provided."""
+
+        config = sample_report_configs[0]
+        # Should not raise error because app_name disambiguates
+        result = filter_metadata_by_table(sample_report_metadata, config.table_name, app_name=config.app_name)
+
+        assert result is not None