sqlspec 0.19.0__py3-none-any.whl → 0.21.0__py3-none-any.whl

sqlspec/core/splitter.py

@@ -1,21 +1,16 @@
 """SQL statement splitter with caching and dialect support.
 
-This module provides a SQL script statement splitter with caching and
-multiple dialect support.
+This module provides SQL script statement splitting functionality
+with support for multiple SQL dialects and caching for performance.
 
 Components:
-- StatementSplitter: SQL splitter with caching
-- DialectConfig: Dialect configuration system
-- Token/TokenType: Tokenization system
-- Caching: LRU caching for split results
-- Pattern compilation caching
-
-Features:
-- Support for multiple SQL dialects (Oracle, T-SQL, PostgreSQL, MySQL, SQLite, DuckDB, BigQuery)
-- Cached pattern compilation
-- LRU caching for split results
-- Optimized tokenization
-- Complete preservation of split_sql_script function
+    StatementSplitter: Main SQL script splitter with caching
+    DialectConfig: Base class for dialect-specific configurations
+    Token/TokenType: Token representation and classification
+    Caching: Pattern and result caching for performance
+
+Supported dialects include Oracle PL/SQL, T-SQL, PostgreSQL,
+MySQL, SQLite, DuckDB, and BigQuery.
 """
 
 import re
@@ -166,7 +161,11 @@ class DialectConfig(ABC):
         return self._max_nesting_depth
 
     def get_all_token_patterns(self) -> list[tuple[TokenType, TokenPattern]]:
-        """Assembles the complete, ordered list of token regex patterns."""
+        """Get the complete ordered list of token patterns for this dialect.
+
+        Returns:
+            List of tuples containing token types and their regex patterns
+        """
         patterns: list[tuple[TokenType, TokenPattern]] = [
             (TokenType.COMMENT_LINE, r"--[^\n]*"),
             (TokenType.COMMENT_BLOCK, r"/\*[\s\S]*?\*/"),
@@ -190,16 +189,36 @@ class DialectConfig(ABC):
         return patterns
 
     def _get_dialect_specific_patterns(self) -> list[tuple[TokenType, TokenPattern]]:
-        """Override to add dialect-specific token patterns."""
+        """Get dialect-specific token patterns.
+
+        Returns:
+            List of dialect-specific token patterns
+        """
         return []
 
     @staticmethod
     def is_real_block_ender(tokens: list[Token], current_pos: int) -> bool:  # noqa: ARG004
-        """Check if this END keyword is actually a block ender."""
+        """Check if END keyword represents an actual block terminator.
+
+        Args:
+            tokens: List of all tokens
+            current_pos: Position of END token
+
+        Returns:
+            True if END represents a block terminator, False otherwise
+        """
         return True
 
     def should_delay_semicolon_termination(self, tokens: list[Token], current_pos: int) -> bool:
-        """Check if semicolon termination should be delayed."""
+        """Check if semicolon termination should be delayed.
+
+        Args:
+            tokens: List of all tokens
+            current_pos: Current position in token list
+
+        Returns:
+            True if termination should be delayed, False otherwise
+        """
         return False
 
 
@@ -237,7 +256,15 @@ class OracleDialectConfig(DialectConfig):
         return self._special_terminators
 
     def should_delay_semicolon_termination(self, tokens: list[Token], current_pos: int) -> bool:
-        """Check if we should delay semicolon termination to look for a slash."""
+        """Check if semicolon termination should be delayed for Oracle slash terminators.
+
+        Args:
+            tokens: List of all tokens
+            current_pos: Current position in token list
+
+        Returns:
+            True if termination should be delayed, False otherwise
+        """
         pos = current_pos - 1
         while pos >= 0:
             token = tokens[pos]
@@ -251,7 +278,15 @@ class OracleDialectConfig(DialectConfig):
         return False
 
     def _has_upcoming_slash(self, tokens: list[Token], current_pos: int) -> bool:
-        """Check if there's a / terminator coming up on its own line."""
+        """Check if there's a slash terminator on its own line ahead.
+
+        Args:
+            tokens: List of all tokens
+            current_pos: Current position in token list
+
+        Returns:
+            True if slash terminator found on its own line, False otherwise
+        """
         pos = current_pos + 1
         found_newline = False
 
@@ -273,7 +308,15 @@ class OracleDialectConfig(DialectConfig):
 
     @staticmethod
     def is_real_block_ender(tokens: list[Token], current_pos: int) -> bool:
-        """Check if this END keyword is actually a block ender for Oracle PL/SQL."""
+        """Check if END keyword represents a block terminator in Oracle PL/SQL.
+
+        Args:
+            tokens: List of all tokens
+            current_pos: Position of END token
+
+        Returns:
+            True if END represents a block terminator, False otherwise
+        """
         pos = current_pos + 1
         while pos < len(tokens):
             next_token = tokens[pos]
@@ -296,7 +339,18 @@ class OracleDialectConfig(DialectConfig):
 
     @staticmethod
     def _handle_slash_terminator(tokens: list[Token], current_pos: int) -> bool:
-        """Oracle / must be on its own line after whitespace only."""
+        """Check if Oracle slash terminator is properly positioned.
+
+        Oracle slash terminators must be on their own line with only
+        whitespace or comments preceding them on the same line.
+
+        Args:
+            tokens: List of all tokens
+            current_pos: Position of slash token
+
+        Returns:
+            True if slash is properly positioned, False otherwise
+        """
         if current_pos == 0:
             return True
 
@@ -374,12 +428,29 @@ class PostgreSQLDialectConfig(DialectConfig):
         return self._statement_terminators
 
     def _get_dialect_specific_patterns(self) -> list[tuple[TokenType, TokenPattern]]:
-        """Add PostgreSQL-specific patterns like dollar-quoted strings."""
+        """Get PostgreSQL-specific token patterns.
+
+        Returns:
+        List of dialect-specific token patterns
+        """
         return [(TokenType.STRING_LITERAL, self._handle_dollar_quoted_string)]
 
     @staticmethod
     def _handle_dollar_quoted_string(text: str, position: int, line: int, column: int) -> Optional[Token]:
-        """Handle PostgreSQL dollar-quoted strings like $tag$...$tag$."""
+        """Handle PostgreSQL dollar-quoted string literals.
+
+        Parses dollar-quoted strings in the format $tag$content$tag$
+        where tag is optional.
+
+        Args:
+            text: The full SQL text being tokenized
+            position: Current position in the text
+            line: Current line number
+            column: Current column number
+
+        Returns:
+            Token representing the dollar-quoted string, or None if no match
+        """
         start_match = re.match(r"\$([a-zA-Z_][a-zA-Z0-9_]*)?\$", text[position:])
         if not start_match:
             return None
@@ -548,7 +619,11 @@ _cache_lock = threading.Lock()
 
 
 def _get_pattern_cache() -> UnifiedCache:
-    """Get or create the pattern compilation cache."""
+    """Get or create the global pattern compilation cache.
+
+    Returns:
+        The pattern cache instance
+    """
     global _pattern_cache
     if _pattern_cache is None:
         with _cache_lock:
@@ -558,7 +633,11 @@ def _get_pattern_cache() -> UnifiedCache:
 
 
 def _get_result_cache() -> UnifiedCache:
-    """Get or create the result cache."""
+    """Get or create the global result cache.
+
+    Returns:
+        The result cache instance
+    """
     global _result_cache
     if _result_cache is None:
         with _cache_lock:
@@ -574,7 +653,12 @@ class StatementSplitter:
     __slots__ = SPLITTER_SLOTS
 
     def __init__(self, dialect: DialectConfig, strip_trailing_semicolon: bool = False) -> None:
-        """Initialize the splitter with caching and dialect support."""
+        """Initialize the statement splitter.
+
+        Args:
+            dialect: The SQL dialect configuration to use
+            strip_trailing_semicolon: Whether to remove trailing semicolons from statements
+        """
         self._dialect = dialect
         self._strip_trailing_semicolon = strip_trailing_semicolon
         self._token_patterns = dialect.get_all_token_patterns()
@@ -587,7 +671,11 @@ class StatementSplitter:
         self._compiled_patterns = self._get_or_compile_patterns()
 
     def _get_or_compile_patterns(self) -> list[tuple[TokenType, CompiledTokenPattern]]:
-        """Get compiled patterns from cache or compile and cache them."""
+        """Get compiled regex patterns from cache or compile and cache them.
+
+        Returns:
+            List of compiled token patterns with their types
+        """
         cache_key = CacheKey(("pattern", self._pattern_cache_key))
 
         cached_patterns = self._pattern_cache.get(cache_key)
@@ -605,7 +693,14 @@ class StatementSplitter:
         return compiled
 
     def _tokenize(self, sql: str) -> Generator[Token, None, None]:
-        """Tokenize SQL string."""
+        """Tokenize SQL string into Token objects.
+
+        Args:
+            sql: The SQL string to tokenize
+
+        Yields:
+            Token objects representing the lexical elements
+        """
         pos = 0
         line = 1
         line_start = 0
@@ -650,7 +745,14 @@ class StatementSplitter:
                 pos += 1
 
     def split(self, sql: str) -> list[str]:
-        """Split SQL script with result caching."""
+        """Split SQL script into individual statements.
+
+        Args:
+            sql: The SQL script to split
+
+        Returns:
+            List of individual SQL statements
+        """
         script_hash = hash(sql)
         cache_key = CacheKey(("split", self._dialect.name, script_hash, self._strip_trailing_semicolon))
 
@@ -664,7 +766,14 @@ class StatementSplitter:
         return statements
 
     def _do_split(self, sql: str) -> list[str]:
-        """Perform SQL script splitting."""
+        """Perform the actual SQL script splitting logic.
+
+        Args:
+            sql: The SQL script to split
+
+        Returns:
+            List of individual SQL statements
+        """
         statements = []
         current_statement_tokens = []
         current_statement_chars = []
@@ -738,14 +847,28 @@ class StatementSplitter:
 
     @staticmethod
     def _is_plsql_block(tokens: list[Token]) -> bool:
-        """Check if the token list represents a PL/SQL block."""
+        """Check if the token list represents a PL/SQL block.
+
+        Args:
+            tokens: List of tokens to examine
+
+        Returns:
+            True if tokens represent a PL/SQL block, False otherwise
+        """
         for token in tokens:
             if token.type == TokenType.KEYWORD:
                 return token.value.upper() in {"BEGIN", "DECLARE"}
         return False
 
     def _contains_executable_content(self, statement: str) -> bool:
-        """Check if a statement contains actual executable content."""
+        """Check if a statement contains executable content.
+
+        Args:
+            statement: The SQL statement to check
+
+        Returns:
+            True if statement contains non-whitespace/non-comment content
+        """
         tokens = list(self._tokenize(statement))
 
         for token in tokens:
@@ -793,7 +916,10 @@ def split_sql_script(script: str, dialect: Optional[str] = None, strip_trailing_
 
 
 def clear_splitter_caches() -> None:
-    """Clear all splitter caches for memory management."""
+    """Clear all splitter caches.
+
+    Clears both pattern and result caches to free memory.
+    """
     pattern_cache = _get_pattern_cache()
     result_cache = _get_result_cache()
     pattern_cache.clear()

sqlspec/core/statement.py

@@ -10,6 +10,7 @@ from typing_extensions import TypeAlias
 
 from sqlspec.core.compiler import OperationType, SQLProcessor
 from sqlspec.core.parameters import ParameterConverter, ParameterStyle, ParameterStyleConfig, ParameterValidator
+from sqlspec.exceptions import SQLSpecError
 from sqlspec.typing import Empty, EmptyEnum
 from sqlspec.utils.logging import get_logger
 from sqlspec.utils.type_guards import is_statement_filter, supports_where
@@ -64,7 +65,11 @@ PROCESSED_STATE_SLOTS: Final = (
 
 @mypyc_attr(allow_interpreted_subclasses=False)
 class ProcessedState:
-    """Processing results for SQL statements."""
+    """Processing results for SQL statements.
+
+    Contains the compiled SQL, execution parameters, parsed expression,
+    operation type, and validation errors for a processed SQL statement.
+    """
 
     __slots__ = PROCESSED_STATE_SLOTS
     operation_type: "OperationType"
@@ -91,7 +96,12 @@ class ProcessedState:
 
 @mypyc_attr(allow_interpreted_subclasses=False)
 class SQL:
-    """SQL statement with parameter and filter support."""
+    """SQL statement with parameter and filter support.
+
+    Represents a SQL statement that can be compiled with parameters and filters.
+    Supports both positional and named parameters, statement filtering,
+    and various execution modes including batch operations.
+    """
 
     __slots__ = (
         "_dialect",
@@ -153,11 +163,27 @@ class SQL:
     def _create_auto_config(
         self, statement: "Union[str, exp.Expression, 'SQL']", parameters: tuple, kwargs: dict[str, Any]
     ) -> "StatementConfig":
-        """Create auto-detected StatementConfig when none provided."""
+        """Create default StatementConfig when none provided.
+
+        Args:
+            statement: The SQL statement
+            parameters: Statement parameters
+            kwargs: Additional keyword arguments
+
+        Returns:
+            Default StatementConfig instance
+        """
         return get_default_config()
 
     def _normalize_dialect(self, dialect: "Optional[DialectType]") -> "Optional[str]":
-        """Normalize dialect to string representation."""
+        """Convert dialect to string representation.
+
+        Args:
+            dialect: Dialect type or string
+
+        Returns:
+            String representation of the dialect or None
+        """
         if dialect is None:
             return None
         if isinstance(dialect, str):
@@ -165,7 +191,11 @@ class SQL:
         return dialect.__class__.__name__.lower()
 
     def _init_from_sql_object(self, sql_obj: "SQL") -> None:
-        """Initialize from existing SQL object."""
+        """Initialize instance attributes from existing SQL object.
+
+        Args:
+            sql_obj: Existing SQL object to copy from
+        """
         self._raw_sql = sql_obj._raw_sql
         self._filters = sql_obj._filters.copy()
         self._named_parameters = sql_obj._named_parameters.copy()
@@ -176,7 +206,14 @@ class SQL:
             self._processed_state = sql_obj._processed_state
 
     def _should_auto_detect_many(self, parameters: tuple) -> bool:
-        """Auto-detect execute_many from parameter structure."""
+        """Detect execute_many mode from parameter structure.
+
+        Args:
+            parameters: Parameter tuple to analyze
+
+        Returns:
+            True if parameters indicate batch execution
+        """
         if len(parameters) == 1 and isinstance(parameters[0], list):
             param_list = parameters[0]
             if param_list and all(isinstance(item, (tuple, list)) for item in param_list):
@@ -184,7 +221,13 @@ class SQL:
         return False
 
     def _process_parameters(self, *parameters: Any, dialect: Optional[str] = None, **kwargs: Any) -> None:
-        """Process parameters and filters."""
+        """Process and organize parameters and filters.
+
+        Args:
+            *parameters: Variable parameters and filters
+            dialect: SQL dialect override
+            **kwargs: Additional named parameters
+        """
         if dialect is not None:
             self._dialect = self._normalize_dialect(dialect)
 
@@ -211,6 +254,9 @@ class SQL:
                     if self._is_many:
                         self._positional_parameters = list(param)
                     else:
+                        # For drivers with native list expansion support, each item in the tuple/list
+                        # should be treated as a separate parameter (but preserve inner lists/arrays)
+                        # This allows passing arrays/lists as single JSONB parameters
                         self._positional_parameters.extend(param)
                 else:
                     self._positional_parameters.append(param)
@@ -288,7 +334,11 @@ class SQL:
         return len(self.validation_errors) > 0
 
     def returns_rows(self) -> bool:
-        """Check if statement returns rows."""
+        """Check if statement returns rows.
+
+        Returns:
+            True if the SQL statement returns result rows
+        """
         if self._processed_state is Empty:
             self.compile()
             if self._processed_state is Empty:
@@ -324,7 +374,11 @@ class SQL:
         return False
 
     def compile(self) -> tuple[str, Any]:
-        """Compile the SQL statement."""
+        """Compile SQL statement with parameters.
+
+        Returns:
+            Tuple of compiled SQL string and execution parameters
+        """
         if self._processed_state is Empty:
             try:
                 config = self._statement_config
@@ -341,6 +395,8 @@ class SQL:
                     validation_errors=[],
                     is_many=self._is_many,
                 )
+            except SQLSpecError:
+                raise
             except Exception as e:
                 logger.warning("Processing failed, using fallback: %s", e)
                 self._processed_state = ProcessedState(
@@ -353,7 +409,11 @@ class SQL:
         return self._processed_state.compiled_sql, self._processed_state.execution_parameters
 
     def as_script(self) -> "SQL":
-        """Mark as script execution."""
+        """Create copy marked for script execution.
+
+        Returns:
+            New SQL instance configured for script execution
+        """
         original_params = self._original_parameters
         config = self._statement_config
         is_many = self._is_many
@@ -367,7 +427,16 @@ class SQL:
     def copy(
         self, statement: "Optional[Union[str, exp.Expression]]" = None, parameters: Optional[Any] = None, **kwargs: Any
     ) -> "SQL":
-        """Create copy with modifications."""
+        """Create copy with modifications.
+
+        Args:
+            statement: New SQL statement to use
+            parameters: New parameters to use
+            **kwargs: Additional modifications
+
+        Returns:
+            New SQL instance with modifications applied
+        """
         new_sql = SQL(
             statement or self._raw_sql,
             *(parameters if parameters is not None else self._original_parameters),
@@ -484,7 +553,11 @@ class SQL:
 
 @mypyc_attr(allow_interpreted_subclasses=False)
 class StatementConfig:
-    """Configuration for SQL statement processing."""
+    """Configuration for SQL statement processing.
+
+    Controls SQL parsing, validation, transformations, parameter handling,
+    and other processing options for SQL statements.
+    """
 
     __slots__ = SQL_CONFIG_SLOTS
 
@@ -653,12 +726,20 @@ class StatementConfig:
 
 
 def get_default_config() -> StatementConfig:
-    """Get default statement configuration."""
+    """Get default statement configuration.
+
+    Returns:
+        StatementConfig with default settings
+    """
     return StatementConfig()
 
 
 def get_default_parameter_config() -> ParameterStyleConfig:
-    """Get default parameter configuration."""
+    """Get default parameter configuration.
+
+    Returns:
+        ParameterStyleConfig with QMARK style as default
+    """
     return ParameterStyleConfig(
         default_parameter_style=ParameterStyle.QMARK, supported_parameter_styles={ParameterStyle.QMARK}
     )

sqlspec/driver/_common.py

@@ -190,6 +190,15 @@ class CommonDriverAttributesMixin:
         """Build SQL statement from various input types.
 
         Ensures dialect is set and preserves existing state when rebuilding SQL objects.
+
+        Args:
+            statement: SQL statement or QueryBuilder to prepare
+            parameters: Parameters for the SQL statement
+            statement_config: Statement configuration
+            kwargs: Additional keyword arguments
+
+        Returns:
+            Prepared SQL statement
         """
         kwargs = kwargs or {}
 
@@ -291,8 +300,8 @@ class CommonDriverAttributesMixin:
     def _format_parameter_set_for_many(self, parameters: Any, statement_config: "StatementConfig") -> Any:
         """Prepare a single parameter set for execute_many operations.
 
-        Unlike _format_parameter_set, this method handles parameter sets without
-        converting the structure itself to array format.
+        Handles parameter sets without converting the structure to array format,
+        applying type coercion to individual values while preserving structure.
 
         Args:
             parameters: Single parameter set (tuple, list, or dict)
@@ -394,7 +403,7 @@ class CommonDriverAttributesMixin:
 
         Args:
             statement: SQL statement to compile
-            statement_config: Complete statement configuration including parameter config, dialect, etc.
+            statement_config: Statement configuration including parameter config and dialect
             flatten_single_parameters: If True, flatten single-element lists for scalar parameters
 
         Returns:

sqlspec/driver/mixins/_result_tools.py

@@ -1,3 +1,5 @@
+"""Result handling and schema conversion mixins for database drivers."""
+
 import datetime
 import logging
 from collections.abc import Sequence
@@ -41,7 +43,16 @@ _DEFAULT_TYPE_DECODERS: Final[list[tuple[Callable[[Any], bool], Callable[[Any, A
 def _default_msgspec_deserializer(
     target_type: Any, value: Any, type_decoders: "Optional[Sequence[tuple[Any, Any]]]" = None
 ) -> Any:
-    """Default msgspec deserializer with type conversion support."""
+    """Convert msgspec types with type decoder support.
+
+    Args:
+        target_type: Type to convert to
+        value: Value to convert
+        type_decoders: Optional sequence of (predicate, decoder) pairs
+
+    Returns:
+        Converted value or original value if conversion not applicable
+    """
     if type_decoders:
         for predicate, decoder in type_decoders:
             if predicate(target_type):
@@ -74,6 +85,8 @@ def _default_msgspec_deserializer(
 
 @trait
 class ToSchemaMixin:
+    """Mixin providing data transformation methods for various schema types."""
+
     __slots__ = ()
 
     @overload
@@ -114,11 +127,15 @@ class ToSchemaMixin:
     def to_schema(data: Any, *, schema_type: "Optional[type[ModelDTOT]]" = None) -> Any:
         """Convert data to a specified schema type.
 
-        Raises:
-            SQLSpecError if `schema_type` is not a valid type.
+        Args:
+            data: Input data to convert
+            schema_type: Target schema type for conversion
 
         Returns:
-            Converted data in the specified schema type.
+            Converted data in the specified schema type
+
+        Raises:
+            SQLSpecError: If schema_type is not a supported type
         """
         if schema_type is None:
             return data