fix: cleanup tests and core (#59)

Remove unnecessary comments and improve code clarity by cleaning up tests and core functionality. This enhances maintainability and readability.

Author: cofin

sqlspec/_sql.py

@@ -466,7 +466,7 @@ def _populate_insert_from_sql(self, builder: "Insert", sql_string: str) -> "Inse
         """Parse SQL string and populate INSERT builder using SQLGlot directly."""
         try:
             # Use SQLGlot directly for parsing - no validation here
-            parsed_expr = exp.maybe_parse(sql_string, dialect=self.dialect)  # type: ignore[var-annotated]
+            parsed_expr: exp.Expression = exp.maybe_parse(sql_string, dialect=self.dialect)
 
             if isinstance(parsed_expr, exp.Insert):
                 builder._expression = parsed_expr
@@ -488,7 +488,7 @@ def _populate_select_from_sql(self, builder: "Select", sql_string: str) -> "Sele
         """Parse SQL string and populate SELECT builder using SQLGlot directly."""
         try:
             # Use SQLGlot directly for parsing - no validation here
-            parsed_expr = exp.maybe_parse(sql_string, dialect=self.dialect)  # type: ignore[var-annotated]
+            parsed_expr: exp.Expression = exp.maybe_parse(sql_string, dialect=self.dialect)
 
             if isinstance(parsed_expr, exp.Select):
                 builder._expression = parsed_expr
@@ -504,7 +504,7 @@ def _populate_update_from_sql(self, builder: "Update", sql_string: str) -> "Upda
         """Parse SQL string and populate UPDATE builder using SQLGlot directly."""
         try:
             # Use SQLGlot directly for parsing - no validation here
-            parsed_expr = exp.maybe_parse(sql_string, dialect=self.dialect)  # type: ignore[var-annotated]
+            parsed_expr: exp.Expression = exp.maybe_parse(sql_string, dialect=self.dialect)
 
             if isinstance(parsed_expr, exp.Update):
                 builder._expression = parsed_expr
@@ -520,7 +520,7 @@ def _populate_delete_from_sql(self, builder: "Delete", sql_string: str) -> "Dele
         """Parse SQL string and populate DELETE builder using SQLGlot directly."""
         try:
             # Use SQLGlot directly for parsing - no validation here
-            parsed_expr = exp.maybe_parse(sql_string, dialect=self.dialect)  # type: ignore[var-annotated]
+            parsed_expr: exp.Expression = exp.maybe_parse(sql_string, dialect=self.dialect)
 
             if isinstance(parsed_expr, exp.Delete):
                 builder._expression = parsed_expr
@@ -536,7 +536,7 @@ def _populate_merge_from_sql(self, builder: "Merge", sql_string: str) -> "Merge"
         """Parse SQL string and populate MERGE builder using SQLGlot directly."""
         try:
             # Use SQLGlot directly for parsing - no validation here
-            parsed_expr = exp.maybe_parse(sql_string, dialect=self.dialect)  # type: ignore[var-annotated]
+            parsed_expr: exp.Expression = exp.maybe_parse(sql_string, dialect=self.dialect)
 
             if isinstance(parsed_expr, exp.Merge):
                 builder._expression = parsed_expr
@@ -725,9 +725,8 @@ def raw(sql_fragment: str, **parameters: Any) -> "Union[exp.Expression, SQL]":
         if not parameters:
             # Original behavior - return pure expression
             try:
-                parsed: Optional[exp.Expression] = exp.maybe_parse(sql_fragment)
-                if parsed is not None:
-                    return parsed
+                parsed: exp.Expression = exp.maybe_parse(sql_fragment)
+                return parsed
                 if sql_fragment.strip().replace("_", "").replace(".", "").isalnum():
                     return exp.to_identifier(sql_fragment)
                 return exp.Literal.string(sql_fragment)
@@ -940,10 +939,8 @@ def any(values: Union[list[Any], exp.Expression, str]) -> FunctionExpression:
             return FunctionExpression(exp.Any(this=exp.Array(expressions=literals)))
         if isinstance(values, str):
             # Parse as SQL
-            parsed = exp.maybe_parse(values)  # type: ignore[var-annotated]
-            if parsed:
-                return FunctionExpression(exp.Any(this=parsed))
-            return FunctionExpression(exp.Any(this=exp.Literal.string(values)))
+            parsed: exp.Expression = exp.maybe_parse(values)
+            return FunctionExpression(exp.Any(this=parsed))
         return FunctionExpression(exp.Any(this=values))
 
     @staticmethod

sqlspec/core/__init__.py

@@ -1,17 +1,92 @@
-"""SQLSpec Core Module - SQL Processing System.
-
-This module provides the core SQL processing components including statement handling,
-parameter processing, compilation, and result management.
-
-Components:
-- statement.py: SQL class with StatementConfig
-- parameters.py: Parameter processing pipeline
-- compiler.py: SQL compilation with caching
-- result.py: Result classes for query execution
-- filters.py: Statement filter system
-- cache.py: Unified caching system
-- splitter.py: SQL statement splitter
-- hashing.py: Cache key generation
+"""SQLSpec Core Module - High-Performance SQL Processing System.
+
+This module provides the core SQL processing infrastructure for SQLSpec, implementing
+a complete pipeline for SQL statement compilation, parameter processing, caching,
+and result management. All components are optimized for MyPyC compilation and
+designed for maximum performance with minimal overhead.
+
+Architecture Overview:
+    The core module implements a single-pass processing pipeline where SQL statements
+    are parsed once, transformed once, and validated once. The SQL object serves as
+    the single source of truth throughout the system.
+
+Key Components:
+    statement.py: SQL statement representation and configuration management
+        - SQL class for statement encapsulation with lazy compilation
+        - StatementConfig for processing pipeline configuration
+        - ProcessedState for cached compilation results
+        - Support for execute_many and script execution modes
+
+    parameters.py: Type-safe parameter processing and style conversion
+        - Automatic parameter style detection and conversion
+        - Support for QMARK (?), NAMED (:name), NUMERIC ($1), FORMAT (%s) styles
+        - Parameter validation and type coercion
+        - Batch parameter handling for execute_many operations
+
+    compiler.py: SQL compilation with validation and optimization
+        - SQLProcessor for statement compilation and validation
+        - Operation type detection (SELECT, INSERT, UPDATE, DELETE, etc.)
+        - AST-based SQL analysis using SQLGlot
+        - Support for multiple SQL dialects
+        - Compiled result caching for performance
+
+    result.py: Comprehensive result handling for all SQL operations
+        - SQLResult for standard query results with metadata
+        - ArrowResult for Apache Arrow format integration
+        - Support for DML operations with RETURNING clauses
+        - Script execution result aggregation
+        - Iterator protocol support for result rows
+
+    filters.py: Composable SQL statement filters
+        - BeforeAfterFilter for date range filtering
+        - InCollectionFilter for IN clause generation
+        - LimitOffsetFilter for pagination
+        - OrderByFilter for dynamic sorting
+        - SearchFilter for text search operations
+        - Parameter conflict resolution
+
+    cache.py: Unified caching system with LRU eviction
+        - UnifiedCache with configurable TTL and size limits
+        - StatementCache for compiled SQL statements
+        - ExpressionCache for parsed SQLGlot expressions
+        - ParameterCache for processed parameters
+        - Thread-safe operations with fine-grained locking
+        - Cache statistics and monitoring
+
+    splitter.py: Dialect-aware SQL script splitting
+        - Support for Oracle PL/SQL, T-SQL, PostgreSQL, MySQL
+        - Proper handling of block structures (BEGIN/END)
+        - Dollar-quoted string support for PostgreSQL
+        - Batch separator recognition (GO for T-SQL)
+        - Comment and string literal preservation
+
+    hashing.py: Efficient cache key generation
+        - SQL statement hashing with parameter consideration
+        - Expression tree hashing for AST caching
+        - Parameter set hashing for batch operations
+        - Optimized hash computation with caching
+
+Performance Optimizations:
+    - MyPyC compilation support with proper annotations
+    - __slots__ usage for memory efficiency
+    - Final annotations for constant folding
+    - Lazy evaluation and compilation
+    - Comprehensive result caching
+    - Minimal object allocation in hot paths
+
+Thread Safety:
+    All caching components are thread-safe with RLock protection.
+    The processing pipeline is stateless and safe for concurrent use.
+
+Example Usage:
+    >>> from sqlspec.core import SQL, StatementConfig
+    >>> config = StatementConfig(dialect="postgresql")
+    >>> stmt = SQL(
+    ...     "SELECT * FROM users WHERE id = ?",
+    ...     1,
+    ...     statement_config=config,
+    ... )
+    >>> compiled_sql, params = stmt.compile()
 """
 
 from sqlspec.core import filters