Centralize error detection logic in pystackql

This commit implements centralized error detection to move error handling
logic from external applications (like stackql-deploy) into pystackql itself.

Changes:
- Add errors.yaml configuration file with error patterns
  - Fuzzy matches for HTTP 4xx/5xx status codes
  - Exact matches for error prefixes
  - StackQL-specific error patterns (disparity, missing operations)

- Implement ErrorDetector class (pystackql/core/error_detector.py)
  - Loads error patterns from errors.yaml at initialization
  - Supports fuzzy (case-insensitive substring) matching
  - Supports exact (prefix) matching
  - Provides is_error() and extract_error_info() methods

- Integrate error detection into OutputFormatter
  - Check raw data strings for error patterns
  - Check parsed JSON data recursively for errors
  - Move detected errors to 'error' field instead of 'data'
  - Return empty list for data when error is detected
  - Apply detection to both query and statement results

- Add PyYAML>=5.4.0 dependency
  - Updated requirements.txt
  - Updated pyproject.toml dependencies

- Add MANIFEST.in to include errors.yaml in package distribution

- Add comprehensive test suite (tests/test_error_detection.py)
  - Tests for ErrorDetector class
  - Tests for OutputFormatter integration
  - Tests for specific homebrew provider 404 error scenario

This centralizes error detection so external applications no longer need
to parse stdout messages to identify error conditions. When StackQL
returns error messages in stdout (instead of stderr), they are now
automatically detected and properly formatted as errors.

Author: claude

MANIFEST.in

@@ -0,0 +1 @@
+include pystackql/errors.yaml

pyproject.toml

@@ -31,6 +31,7 @@ dependencies = [
     "nest-asyncio>=1.5.5",
     "termcolor>=1.1.0",
     "tqdm>=4.61.0",
+    "PyYAML>=5.4.0",
 ]
 
 [tool.setuptools.packages.find]

pystackql/core/error_detector.py

@@ -0,0 +1,121 @@
+# pystackql/core/error_detector.py
+
+"""
+Error detection module for PyStackQL.
+
+This module provides centralized error detection logic that checks messages
+against predefined error patterns loaded from errors.yaml.
+"""
+
+import os
+import yaml
+
+
+class ErrorDetector:
+    """Detects errors in query results based on predefined patterns.
+
+    This class loads error patterns from errors.yaml and provides methods
+    to check if a message contains any of these error patterns.
+    """
+
+    def __init__(self):
+        """Initialize the ErrorDetector by loading error patterns from errors.yaml."""
+        self.fuzzy_patterns = []
+        self.exact_patterns = []
+        self._load_error_patterns()
+
+    def _load_error_patterns(self):
+        """Load error patterns from the errors.yaml file.
+
+        The errors.yaml file should be located in the same directory as this module.
+        """
+        # Get the directory containing the pystackql package
+        current_dir = os.path.dirname(os.path.abspath(__file__))
+        package_dir = os.path.dirname(current_dir)
+        errors_file = os.path.join(package_dir, 'errors.yaml')
+
+        try:
+            if os.path.exists(errors_file):
+                with open(errors_file, 'r') as f:
+                    error_config = yaml.safe_load(f)
+
+                if error_config and 'errors' in error_config:
+                    errors = error_config['errors']
+
+                    # Load fuzzy match patterns (case-insensitive substring matching)
+                    if 'fuzzy_matches' in errors:
+                        self.fuzzy_patterns = [
+                            pattern.lower()
+                            for pattern in errors['fuzzy_matches']
+                            if pattern
+                        ]
+
+                    # Load exact match patterns (case-sensitive exact/prefix matching)
+                    if 'exact_matches' in errors:
+                        self.exact_patterns = [
+                            pattern
+                            for pattern in errors['exact_matches']
+                            if pattern
+                        ]
+        except Exception as e:
+            # If we can't load the error patterns, continue with empty lists
+            # This ensures the module doesn't break existing functionality
+            print(f"Warning: Could not load error patterns from {errors_file}: {e}")
+
+    def is_error(self, message):
+        """Check if a message contains any error patterns.
+
+        Args:
+            message (str): The message to check for error patterns
+
+        Returns:
+            bool: True if the message matches any error pattern, False otherwise
+        """
+        if not message or not isinstance(message, str):
+            return False
+
+        message_lower = message.lower()
+
+        # Check fuzzy matches (case-insensitive substring matching)
+        for pattern in self.fuzzy_patterns:
+            if pattern in message_lower:
+                return True
+
+        # Check exact matches (exact string or starts with prefix)
+        for pattern in self.exact_patterns:
+            if message == pattern or message.startswith(pattern):
+                return True
+
+        return False
+
+    def extract_error_info(self, message):
+        """Extract error information from a message.
+
+        Args:
+            message (str): The error message
+
+        Returns:
+            dict: Dictionary containing error details with 'error' and 'detected_pattern' keys
+        """
+        if not self.is_error(message):
+            return None
+
+        message_lower = message.lower()
+        detected_pattern = None
+
+        # Find which pattern was matched
+        for pattern in self.fuzzy_patterns:
+            if pattern in message_lower:
+                detected_pattern = pattern
+                break
+
+        if not detected_pattern:
+            for pattern in self.exact_patterns:
+                if message == pattern or message.startswith(pattern):
+                    detected_pattern = pattern
+                    break
+
+        return {
+            "error": message,
+            "detected_pattern": detected_pattern
+        }

pystackql/core/output.py

@@ -8,6 +8,7 @@
 
 import json
 from io import StringIO
+from .error_detector import ErrorDetector
 
 class OutputFormatter:
     """Formats query results into different output formats.
@@ -18,18 +19,19 @@ class OutputFormatter:
 
     def __init__(self, output_format='dict'):
         """Initialize the OutputFormatter.
-        
+
         Args:
             output_format (str, optional): The output format. Defaults to 'dict'.
                 Allowed values: 'dict', 'pandas', 'csv'
-                
+
         Raises:
             ValueError: If an invalid output format is specified
         """
         ALLOWED_OUTPUTS = {'dict', 'pandas', 'csv'}
         if output_format.lower() not in ALLOWED_OUTPUTS:
             raise ValueError(f"Invalid output format. Expected one of {ALLOWED_OUTPUTS}, got {output_format}.")
         self.output_format = output_format.lower()
+        self.error_detector = ErrorDetector()
 
     def format_query_result(self, result, suppress_errors=True):
         """Format a query result.
@@ -95,21 +97,32 @@ def _format_error(self, error_msg):
 
     def _format_data(self, data):
         """Format data.
-        
+
         This method processes SQL type objects from StackQL:
         - SQL NULL values: {'String': '', 'Valid': False} → None
         - Regular values: {'String': 'value', 'Valid': True} → 'value'
         - Empty strings: {'String': '', 'Valid': True} → '' (preserved as empty string)
-        
+
+        Additionally, this method checks for error patterns in the data and
+        converts them to proper error responses.
+
         Args:
             data (str): The data string
-            
+
         Returns:
             The formatted data in the specified output format
         """
         if self.output_format == 'csv':
+            # For CSV, check if the raw data contains error patterns
+            if self.error_detector.is_error(data):
+                return data  # Return the error message as-is for CSV
             return data
-        
+
+        # Check if the raw data string itself is an error message (before JSON parsing)
+        if isinstance(data, str) and self.error_detector.is_error(data):
+            # The entire response is an error message
+            return self._format_error(data)
+
         try:
             # Attempt to parse JSON first
             raw_json_data = json.loads(data)
@@ -129,27 +142,70 @@ def _format_data(self, data):
         try:
             # Process the JSON data to clean up SQL type objects
             processed_json_data = self._process_sql_types(raw_json_data)
-            
+
             # Handle empty data
             if not processed_json_data:
                 return pd.DataFrame() if self.output_format == 'pandas' else []
-            
+
+            # Check if the processed data contains error patterns
+            # This handles cases where StackQL returns error messages in structured data
+            detected_error = self._check_data_for_errors(processed_json_data)
+            if detected_error:
+                return self._format_error(detected_error)
+
             if self.output_format == 'pandas':
                 import pandas as pd
                 # Convert the preprocessed JSON data to a DataFrame
                 return pd.DataFrame(processed_json_data)
-            
+
             # Return the preprocessed dictionary data
             return processed_json_data
-            
+
         except Exception as e:
             # Handle any errors during processing
             error_msg = f"Error processing data: {str(e)}"
             if self.output_format == 'pandas':
                 import pandas as pd
                 return pd.DataFrame([{"error": error_msg}])
             return [{"error": error_msg}]
-        
+
+    def _check_data_for_errors(self, data):
+        """Check if processed data contains error patterns.
+
+        This method recursively checks all string values in the data structure
+        to detect error patterns that might have been returned as valid data.
+
+        Args:
+            data: The processed data (list, dict, or primitive type)
+
+        Returns:
+            str: The error message if an error pattern is detected, None otherwise
+        """
+        if isinstance(data, list):
+            # Check each item in the list
+            for item in data:
+                error = self._check_data_for_errors(item)
+                if error:
+                    return error
+
+        elif isinstance(data, dict):
+            # Check each value in the dictionary
+            for key, value in data.items():
+                # Check string values for error patterns
+                if isinstance(value, str) and self.error_detector.is_error(value):
+                    return value
+                # Recursively check nested structures
+                error = self._check_data_for_errors(value)
+                if error:
+                    return error
+
+        elif isinstance(data, str):
+            # Check if the string itself is an error
+            if self.error_detector.is_error(data):
+                return data
+
+        return None
+
     def _process_sql_types(self, data):
         """Process SQL type objects in the data.
         
@@ -203,21 +259,26 @@ def _format_empty(self):
 
     def format_statement_result(self, result):
         """Format a statement result.
-        
+
         Args:
             result (dict): The raw statement result from the executor
-            
+
         Returns:
             The formatted result in the specified output format
         """
         # Handle exceptions
         if "exception" in result:
             exception_msg = result["exception"]
             return self._format_exception(exception_msg)
-        
+
         # Message on stderr or empty message
         message = result.get("error", "")
-        
+
+        # Check if the message contains error patterns
+        if message and self.error_detector.is_error(message):
+            # Return as error instead of as a regular message
+            return self._format_error(message)
+
         if self.output_format == 'pandas':
             import pandas as pd
             return pd.DataFrame({'message': [message]}) if message else pd.DataFrame({'message': []})

pystackql/errors.yaml

@@ -0,0 +1,32 @@
+# Error patterns for centralized error detection in PyStackQL
+#
+# This file defines patterns that should be detected as errors when they appear
+# in query results. These patterns are checked against messages returned in stdout
+# to identify error conditions that would otherwise be treated as valid data.
+#
+# Pattern Types:
+# - fuzzy_matches: Substring matching (case-insensitive)
+# - exact_matches: Exact string matching (case-sensitive)
+
+errors:
+  # Fuzzy matches - will match if the pattern appears anywhere in the message
+  fuzzy_matches:
+    # HTTP error status codes (4xx client errors, 5xx server errors)
+    - "http response status code: 4"
+    - "http response status code: 5"
+
+    # StackQL-specific error patterns from stackql-deploy
+    - "disparity in fields"
+    - "cannot find matching operation"
+
+    # Additional StackQL error patterns
+    - "invalid query"
+    - "syntax error"
+
+  # Exact matches - must match the entire message or start with this prefix
+  exact_matches:
+    - "error:"
+    - "ERROR:"
+    - "Error:"
+    - "FAILED"
+    - "FAILURE"

requirements.txt

@@ -3,6 +3,7 @@ pandas>=1.3.0
 requests>=2.25.0
 IPython>=7.0.0
 termcolor>=1.1.0
+PyYAML>=5.4.0
 
 # Documentation
 sphinx>=4.0.0