tellaro-query-language 0.1.0__py3-none-any.whl

tql/parser_components/README.md

@@ -0,0 +1,72 @@
+# Parser Components
+
+This package contains the modular components that make up the TQL parser.
+
+## Overview
+
+The parser components package splits the TQL parser functionality into focused, maintainable modules:
+
+### Components
+
+#### `grammar.py` - Grammar Definitions
+Contains all pyparsing grammar definitions for TQL syntax, including:
+- Basic tokens (identifiers, strings, numbers)
+- Operators (comparison, logical, collection)
+- Field specifications with type hints and mutators
+- Value specifications with mutators
+- Special expressions (geo, nslookup)
+- Statistics expressions
+- Complete TQL expression grammar
+
+#### `ast_builder.py` - AST Construction
+Handles building Abstract Syntax Tree nodes from parsed tokens:
+- `extract_field_info()` - Extracts field name, type hints, and mutators
+- `extract_value_info()` - Extracts values and value mutators
+- Processes complex nested structures
+- Handles mutator parameter parsing
+
+#### `error_analyzer.py` - Error Analysis
+Provides detailed error analysis for parse failures:
+- `analyze_parse_error()` - Main error analysis entry point
+- Generates helpful error messages with context
+- Suggests corrections for common mistakes
+- Shows error location in the original query
+
+#### `field_extractor.py` - Field Extraction
+Extracts field references from parsed AST:
+- `extract_fields()` - Recursively finds all field references
+- Handles all node types including special expressions
+- Returns unique sorted list of fields
+- Used for validation and analysis
+
+## Usage
+
+These components are used internally by the main `TQLParser` class. They should not be imported directly in application code.
+
+```python
+# Don't do this:
+from tql.parser_components.grammar import TQLGrammar
+
+# Do this instead:
+from tql import TQL
+tql = TQL()
+ast = tql.parse("field = 'value'")
+```
+
+## Architecture
+
+The parser follows a modular architecture:
+
+```
+TQLParser (main class)
+    ├── TQLGrammar (grammar definitions)
+    ├── ASTBuilder (AST construction)
+    ├── ErrorAnalyzer (error handling)
+    └── FieldExtractor (field analysis)
+```
+
+This separation allows for:
+- Easier testing of individual components
+- Better code organization
+- Clearer separation of concerns
+- Easier maintenance and updates

tql/parser_components/__init__.py

@@ -0,0 +1,20 @@
+"""TQL Parser package.
+
+This package organizes the TQL parser into logical modules:
+- grammar: Grammar definitions using pyparsing
+- ast_builder: AST building utilities
+- error_analyzer: Error analysis and helpful feedback
+- field_extractor: Field extraction from AST
+"""
+
+from .ast_builder import ASTBuilder
+from .error_analyzer import ErrorAnalyzer
+from .field_extractor import FieldExtractor
+from .grammar import TQLGrammar
+
+__all__ = [
+    "TQLGrammar",
+    "ASTBuilder",
+    "ErrorAnalyzer",
+    "FieldExtractor",
+]

tql/parser_components/ast_builder.py

@@ -0,0 +1,162 @@
+"""AST building utilities for TQL parser."""
+
+from typing import Any, Dict, List, Tuple, Union
+
+
+class ASTBuilder:
+    """Builds Abstract Syntax Tree from parsed TQL expressions."""
+
+    def extract_field_info(self, field_spec: Any) -> Tuple[str, Union[str, None], List[Dict[str, Any]]]:
+        """Extract field name, optional type hint, and mutators from field specification.
+
+        Args:
+            field_spec: Field specification that may include type hint and mutators
+
+        Returns:
+            Tuple of (field_name, type_hint or None, list of mutators)
+        """
+        if isinstance(field_spec, list):
+            field_name = field_spec[0]
+            type_hint = None
+            mutators = []
+
+            # Process remaining elements
+            i = 1
+            while i < len(field_spec):
+                item = field_spec[i]
+                if isinstance(item, str) and item.lower() in [
+                    "number",
+                    "int",
+                    "float",
+                    "decimal",
+                    "date",
+                    "array",
+                    "bool",
+                    "boolean",
+                    "geo",
+                    "object",
+                    "string",
+                ]:
+                    # This is a type hint
+                    type_hint = item.lower()
+                elif isinstance(item, list):
+                    # This is a mutator [name, params] or [name]
+                    if len(item) >= 1:
+                        mutator_dict = {"name": item[0]}
+                        if len(item) > 1 and isinstance(item[1], list):
+                            # Has parameters
+                            params = []
+                            for param in item[1]:
+                                if isinstance(param, list) and len(param) == 2:
+                                    params.append(param)
+                            if params:
+                                mutator_dict["params"] = params
+                        mutators.append(mutator_dict)
+                i += 1
+
+            return field_name, type_hint, mutators
+        else:
+            # Just field name as string
+            return field_spec, None, []
+
+    def extract_value_info(self, value_spec: Any) -> Tuple[Any, List[Dict[str, Any]]]:  # noqa: C901
+        """Extract value and optional mutators from value specification.
+
+        Args:
+            value_spec: Value specification that may include mutators
+
+        Returns:
+            Tuple of (value, list of mutators)
+        """
+        if isinstance(value_spec, list):
+            # Check if this is a list literal (all elements are simple values)
+            # vs a value with mutators (first element is value, rest are mutator specs)
+            if len(value_spec) == 0:
+                return value_spec, []
+
+            # If it's a single-element list containing a list, unwrap it
+            if len(value_spec) == 1 and isinstance(value_spec[0], list):
+                return value_spec[0], []
+
+            # If it's a single-element list containing a simple value, unwrap it
+            if len(value_spec) == 1 and not isinstance(value_spec[0], list):
+                return value_spec[0], []
+
+            # Special case: if first element is a list and rest are mutators,
+            # this is a list literal with mutators
+            if isinstance(value_spec[0], list) and all(
+                isinstance(value_spec[0][i], str) for i in range(len(value_spec[0]))
+            ):
+                # First element is a list of strings
+                has_mutators = False
+                for i in range(1, len(value_spec)):
+                    item = value_spec[i]
+                    if isinstance(item, list) and len(item) >= 1 and isinstance(item[0], str):
+                        # This looks like a mutator spec
+                        has_mutators = True
+                        break
+
+                if has_mutators:
+                    # This is a list literal with mutators
+                    value = value_spec[0]
+                    mutators = []
+                    # Process remaining elements as mutators
+                    i = 1
+                    while i < len(value_spec):
+                        item = value_spec[i]
+                        if isinstance(item, list):
+                            # This is a mutator [name, params] or [name]
+                            if len(item) >= 1:
+                                mutator_dict = {"name": item[0]}
+                                if len(item) > 1 and isinstance(item[1], list):
+                                    # Has parameters
+                                    params = []
+                                    for param in item[1]:
+                                        if isinstance(param, list) and len(param) == 2:
+                                            params.append(param)
+                                    if params:
+                                        mutator_dict["params"] = params
+                                mutators.append(mutator_dict)
+                        i += 1
+                    return value, mutators
+
+            # Check if any element after the first looks like a mutator
+            has_mutators = False
+            for i in range(1, len(value_spec)):
+                item = value_spec[i]
+                if isinstance(item, list) and len(item) >= 1 and isinstance(item[0], str):
+                    # This looks like a mutator spec
+                    has_mutators = True
+                    break
+
+            if not has_mutators:
+                # This is a list literal, return it as-is
+                return value_spec, []
+
+            # This is a value with mutators
+            value = value_spec[0]
+            mutators = []
+
+            # Process remaining elements as mutators
+            i = 1
+            while i < len(value_spec):
+                item = value_spec[i]
+                if isinstance(item, list):
+                    # This is a mutator [name, params] or [name]
+                    if len(item) >= 1:
+                        mutator_dict = {"name": item[0]}
+                        if len(item) > 1 and isinstance(item[1], list):
+                            # Has parameters
+                            params = []
+                            for param in item[1]:
+                                if isinstance(param, list) and len(param) == 2:
+                                    params.append(param)
+                            if params:
+                                mutator_dict["params"] = params
+                        mutators.append(mutator_dict)
+                i += 1
+
+            return value, mutators
+        else:
+            # Just the value itself, no mutators
+            return value_spec, []

tql/parser_components/error_analyzer.py

@@ -0,0 +1,101 @@
+"""Error analysis utilities for TQL parser."""
+
+from typing import List, Tuple
+
+
+class ErrorAnalyzer:
+    """Analyzes parse errors to provide helpful feedback."""
+
+    @staticmethod
+    def analyze_parse_error(query: str, position: int, error_str: str) -> Tuple[str, List[str]]:  # noqa: C901
+        """Analyze parse error to provide helpful feedback.
+
+        Args:
+            query: The original query string
+            position: Character position where error occurred
+            error_str: The original error string from pyparsing
+
+        Returns:
+            Tuple of (error message, list of suggestions)
+        """
+        suggestions = []
+
+        # Check for invalid operators first (before position-specific checks)
+        if "==" in query:
+            pos = query.find("==")
+            return f"Invalid operator '==' at position {pos}. Use '=' for equality", [query.replace("==", "=")]
+
+        # Check if query ends with an operator (special case)
+        if query.rstrip().endswith(("=", "!=", ">", "<", ">=", "<=", "contains", "startswith", "endswith")):
+            # Find the operator
+            for op in [">=", "<=", "!=", "contains", "startswith", "endswith", "=", ">", "<"]:
+                if query.rstrip().endswith(op):
+                    return f"Expected value after operator '{op}'", [f'Examples: field {op} "value"']
+
+        # Get context around error position
+        if position >= 0 and position < len(query):
+            # Look at what's around the error position
+            # start = max(0, position - 10)  # Not used
+            # end = min(len(query), position + 10)  # Not used
+            # context = query[start:end]  # Not currently used
+
+            # Check for common issues
+            before = query[:position].strip()
+            after = query[position:].strip()
+
+            # Missing operator after field
+            if (
+                before
+                and after
+                and not any(op in before[-10:] for op in ["=", "!=", ">", "<", ">=", "<=", "in", "contains", "exists"])
+            ):
+                # Likely missing operator
+                last_word = before.split()[-1] if before.split() else ""
+                suggestions = [
+                    f'{last_word} = "{after.split()[0]}"' if after else f"{last_word} exists",
+                ]
+                if after:
+                    suggestions.append(f'{last_word} contains "{after.split()[0]}"')
+                return f"Expected operator after field '{last_word}'", suggestions
+
+            # Unclosed quote
+            if query.count('"') % 2 != 0:
+                last_quote_pos = query.rfind('"', 0, position)
+                if last_quote_pos >= 0:
+                    return f"Unterminated string literal starting at position {last_quote_pos}", []
+
+            if query.count("'") % 2 != 0:
+                last_quote_pos = query.rfind("'", 0, position)
+                if last_quote_pos >= 0:
+                    return f"Unterminated string literal starting at position {last_quote_pos}", []
+
+            # Missing value after operator
+            tokens = before.split()
+            if tokens and tokens[-1] in ["=", "!=", ">", "<", ">=", "<=", "contains", "startswith", "endswith"]:
+                return f"Expected value after operator '{tokens[-1]}'", [
+                    f'Examples: {tokens[-2] if len(tokens) > 1 else "field"} {tokens[-1]} "value"'
+                ]
+
+        # Default message if we can't determine specific issue
+        all_operators = [
+            "=",
+            "!=",
+            ">",
+            "<",
+            ">=",
+            "<=",
+            "contains",
+            "startswith",
+            "endswith",
+            "in",
+            "not in",
+            "between",
+            "not between",
+            "cidr",
+            "not cidr",
+            "exists",
+            "not exists",
+            "regexp",
+            "not regexp",
+        ]
+        return "Invalid syntax", [f"Valid operators: {', '.join(all_operators)}"]

tql/parser_components/field_extractor.py

@@ -0,0 +1,112 @@
+"""Field extraction utilities for TQL parser."""
+
+from typing import Any, Dict, List, Set
+
+
+class FieldExtractor:
+    """Extracts field references from TQL AST."""
+
+    @staticmethod
+    def extract_fields(ast: Dict[str, Any]) -> List[str]:
+        """Extract all unique field references from a TQL AST.
+
+        Args:
+            ast: The parsed AST
+
+        Returns:
+            Sorted list of unique field names referenced in the query
+        """
+        # Use a set to collect unique field names
+        fields: Set[str] = set()
+        FieldExtractor._collect_fields_from_node(ast, fields)
+
+        # Return sorted list of field names
+        return sorted(fields)
+
+    @staticmethod
+    def _collect_fields_from_node(node: Dict[str, Any], fields: Set[str]) -> None:  # noqa: C901
+        """Recursively collect field names from an AST node.
+
+        Args:
+            node: The AST node to extract fields from
+            fields: Set to collect unique field names
+        """
+        if not isinstance(node, dict):
+            return
+
+        node_type = node.get("type")
+
+        if node_type == "comparison":
+            # Standard comparison, add the field
+            if "field" in node:
+                field = node["field"]
+                # Handle case where field might be a list (should not happen with valid queries)
+                if isinstance(field, list):
+                    # This indicates a malformed query - skip it
+                    pass
+                else:
+                    fields.add(field)
+
+        elif node_type == "collection_op":
+            # Collection operation (ANY, ALL)
+            if "field" in node:
+                fields.add(node["field"])
+
+        elif node_type == "logical_op":
+            # Logical operation (AND, OR), process both sides
+            if "left" in node:
+                FieldExtractor._collect_fields_from_node(node["left"], fields)
+            if "right" in node:
+                FieldExtractor._collect_fields_from_node(node["right"], fields)
+
+        elif node_type == "unary_op":
+            # Unary operation (NOT), process the operand
+            if "operand" in node:
+                FieldExtractor._collect_fields_from_node(node["operand"], fields)
+
+        elif node_type == "geo_expr":
+            # Geo expression, add the field being geo-looked up
+            if "field" in node:
+                fields.add(node["field"])
+            # Also process any conditions inside the geo expression
+            if "conditions" in node:
+                FieldExtractor._collect_fields_from_node(node["conditions"], fields)
+
+        elif node_type == "nslookup_expr":
+            # NSLookup expression, add the field being looked up
+            if "field" in node:
+                fields.add(node["field"])
+            # Also process any conditions inside the nslookup expression
+            if "conditions" in node:
+                FieldExtractor._collect_fields_from_node(node["conditions"], fields)
+
+        elif node_type == "query_with_stats":
+            # Query with stats, process the filter part
+            if "filter" in node:
+                FieldExtractor._collect_fields_from_node(node["filter"], fields)
+            # Also collect fields from stats if needed
+            if "stats" in node:
+                FieldExtractor._collect_fields_from_stats(node["stats"], fields)
+
+        elif node_type == "stats_expr":
+            # Stats expression
+            FieldExtractor._collect_fields_from_stats(node, fields)
+
+    @staticmethod
+    def _collect_fields_from_stats(stats_node: Dict[str, Any], fields: Set[str]) -> None:
+        """Collect field names from stats expressions.
+
+        Args:
+            stats_node: Stats AST node
+            fields: Set to collect unique field names
+        """
+        # Collect fields from aggregations
+        if "aggregations" in stats_node:
+            for agg in stats_node["aggregations"]:
+                if "field" in agg and agg["field"] != "*":
+                    fields.add(agg["field"])
+
+        # Collect fields from group by
+        if "group_by" in stats_node:
+            for field in stats_node["group_by"]:
+                fields.add(field)