sqlspec 0.18.0__py3-none-any.whl → 0.20.0__py3-none-any.whl

sqlspec/core/parameters.py

@@ -12,7 +12,7 @@ Components:
 - ParameterProcessor: Parameter processing coordinator
 - ParameterStyleConfig: Configuration for parameter processing
 
-Features:
+Processing:
 - Two-phase processing: compatibility and execution format
 - Type-specific parameter wrapping
 - Parameter style conversions
@@ -99,12 +99,10 @@ class TypedParameter:
     Maintains type information through parsing and execution
     format conversion.
 
-    Use Cases:
-    - Preserve boolean values through parsing
-    - Maintain Decimal precision
-    - Handle date/datetime formatting
-    - Preserve array/list structures
-    - Handle JSON serialization for dict parameters
+    Attributes:
+        value: The parameter value
+        original_type: The original Python type of the value
+        semantic_name: Optional name for debugging purposes
     """
 
     __slots__ = ("_hash", "original_type", "semantic_name", "value")
@@ -123,7 +121,7 @@ class TypedParameter:
         self._hash: Optional[int] = None
 
     def __hash__(self) -> int:
-        """Cached hash value with optimization."""
+        """Cached hash value."""
         if self._hash is None:
             value_id = id(self.value)
             self._hash = hash((value_id, self.original_type, self.semantic_name))
@@ -193,12 +191,14 @@ def _(value: bytes, semantic_name: Optional[str] = None) -> TypedParameter:
 class ParameterInfo:
     """Information about a detected parameter in SQL.
 
-    Tracks parameter metadata for conversion:
-    - name: Parameter name (for named styles)
-    - style: Parameter style
-    - position: Character position in SQL string
-    - ordinal: Order of appearance (0-indexed)
-    - placeholder_text: Original text in SQL
+    Tracks parameter metadata for conversion operations.
+
+    Attributes:
+        name: Parameter name (for named styles)
+        style: Parameter style
+        position: Character position in SQL string
+        ordinal: Order of appearance (0-indexed)
+        placeholder_text: Original text in SQL
     """
 
     __slots__ = ("name", "ordinal", "placeholder_text", "position", "style")
@@ -234,15 +234,17 @@ class ParameterInfo:
 class ParameterStyleConfig:
     """Configuration for parameter style processing.
 
-    Provides configuration for parameter processing including:
-    - default_parameter_style: Primary parsing style
-    - supported_parameter_styles: All input styles supported
-    - supported_execution_parameter_styles: Styles driver can execute
-    - default_execution_parameter_style: Target execution format
-    - type_coercion_map: Type conversions
-    - output_transformer: Final SQL/parameter transformation hook
-    - preserve_parameter_format: Maintain original parameter structure
-    - needs_static_script_compilation: Embed parameters in SQL
+    Provides configuration for parameter processing operations.
+
+    Attributes:
+        default_parameter_style: Primary parsing style
+        supported_parameter_styles: All input styles supported
+        supported_execution_parameter_styles: Styles driver can execute
+        default_execution_parameter_style: Target execution format
+        type_coercion_map: Type conversions
+        output_transformer: Final SQL/parameter transformation hook
+        preserve_parameter_format: Maintain original parameter structure
+        needs_static_script_compilation: Embed parameters in SQL
     """
 
     __slots__ = (
@@ -275,7 +277,7 @@ class ParameterStyleConfig:
         output_transformer: Optional[Callable[[str, Any], tuple[str, Any]]] = None,
         ast_transformer: Optional[Callable[[Any, Any], tuple[Any, Any]]] = None,
     ) -> None:
-        """Initialize with complete compatibility.
+        """Initialize parameter style configuration.
 
         Args:
             default_parameter_style: Primary parameter style for parsing
@@ -289,7 +291,7 @@ class ParameterStyleConfig:
             allow_mixed_parameter_styles: Support mixed styles in single query
             preserve_parameter_format: Maintain original parameter structure
             preserve_original_params_for_many: Return original list of tuples for execute_many
-            ast_transformer: AST-based transformation hook for advanced SQL/parameter manipulation
+            ast_transformer: AST-based transformation hook for SQL/parameter manipulation
         """
         self.default_parameter_style = default_parameter_style
         self.supported_parameter_styles = (
@@ -338,12 +340,7 @@ class ParameterValidator:
     """Parameter validation and extraction.
 
     Extracts parameter information from SQL strings and determines
-    compatibility.
-
-    Features:
-    - Parameter extraction results
-    - Regex-based parameter detection
-    - Dialect-specific compatibility checking
+    compatibility with target dialects.
     """
 
     __slots__ = ("_parameter_cache",)
@@ -464,11 +461,6 @@ class ParameterConverter:
     Handles two-phase parameter processing:
     - Phase 1: Compatibility normalization
     - Phase 2: Execution format conversion
-
-    Features:
-    - Converts incompatible styles to canonical format
-    - Enables parsing of problematic parameter styles
-    - Handles parameter format changes (list ↔ dict, positional ↔ named)
     """
 
     __slots__ = ("_format_converters", "_placeholder_generators", "validator")
@@ -678,7 +670,7 @@ class ParameterConverter:
 
         return None, False
 
-    def _extract_param_value_single_style(self, param: ParameterInfo, parameters: Mapping) -> Any:
+    def _extract_param_value_single_style(self, param: ParameterInfo, parameters: Mapping) -> "tuple[Any, bool]":
         """Extract parameter value for single style parameters.
 
         Args:
@@ -686,18 +678,18 @@ class ParameterConverter:
             parameters: Parameter mapping
 
         Returns:
-            Parameter value or None if not found
+            Tuple of (value, found_flag) where found_flag indicates if parameter was found
         """
         if param.name and param.name in parameters:
-            return parameters[param.name]
+            return parameters[param.name], True
         if f"param_{param.ordinal}" in parameters:
-            return parameters[f"param_{param.ordinal}"]
+            return parameters[f"param_{param.ordinal}"], True
 
         ordinal_key = str(param.ordinal + 1)
         if ordinal_key in parameters:
-            return parameters[ordinal_key]
+            return parameters[ordinal_key], True
 
-        return None
+        return None, False
 
     def _preserve_original_format(self, param_values: "list[Any]", original_parameters: Any) -> Any:
         """Preserve the original parameter container format.
@@ -771,8 +763,8 @@ class ParameterConverter:
                         param_values.append(value)
             else:
                 for param in param_info:
-                    value = self._extract_param_value_single_style(param, parameters)
-                    if value is not None:
+                    value, found = self._extract_param_value_single_style(param, parameters)
+                    if found:
                         param_values.append(value)
 
             if preserve_parameter_format and original_parameters is not None:
@@ -911,15 +903,15 @@ class ParameterConverter:
 class ParameterProcessor:
     """Parameter processing engine.
 
-    This is the main entry point for the parameter processing system
-    that coordinates Phase 1 (compatibility) and Phase 2 (execution format).
+    Main entry point for the parameter processing system that coordinates
+    Phase 1 (compatibility) and Phase 2 (execution format).
 
     Processing Pipeline:
-    1. Type wrapping for compatibility (TypedParameter)
-    2. Driver-specific type coercions (type_coercion_map)
-    3. Phase 1: Normalization if needed
-    4. Phase 2: Execution format conversion if needed
-    5. Final output transformation (output_transformer)
+        1. Type wrapping for compatibility (TypedParameter)
+        2. Driver-specific type coercions (type_coercion_map)
+        3. Phase 1: Normalization if needed
+        4. Phase 2: Execution format conversion if needed
+        5. Final output transformation (output_transformer)
     """
 
     __slots__ = ("_cache", "_cache_size", "_converter", "_validator")
@@ -1001,14 +993,14 @@ class ParameterProcessor:
         dialect: Optional[str] = None,
         is_many: bool = False,
     ) -> "tuple[str, Any]":
-        """Complete parameter processing pipeline.
+        """Process parameters through the complete pipeline.
 
-        This method coordinates the entire parameter processing workflow:
-        1. Type wrapping for compatibility
-        2. Phase 1: Normalization if needed
-        3. Phase 2: Execution format conversion
-        4. Driver-specific type coercions
-        5. Final output transformation
+        Coordinates the entire parameter processing workflow:
+            1. Type wrapping for compatibility
+            2. Phase 1: Normalization if needed
+            3. Phase 2: Execution format conversion
+            4. Driver-specific type coercions
+            5. Final output transformation
 
         Args:
             sql: Raw SQL string
@@ -1077,7 +1069,7 @@ class ParameterProcessor:
     ) -> "tuple[str, Any]":
         """Get SQL normalized for parsing only (Phase 1 only).
 
-        This method performs only Phase 1 normalization to make SQL compatible
+        Performs only Phase 1 normalization to make SQL compatible
         with parsing, without converting to execution format.
 
         Args:
@@ -1101,8 +1093,8 @@ class ParameterProcessor:
     def _needs_execution_conversion(self, param_info: "list[ParameterInfo]", config: ParameterStyleConfig) -> bool:
         """Determine if execution format conversion is needed.
 
-        Preserves the original parameter style if it's supported by the execution environment,
-        otherwise converts to the default execution style.
+        Preserves the original parameter style if it's supported by the execution
+        environment, otherwise converts to the default execution style.
         """
         if not param_info:
             return False
@@ -1141,11 +1133,11 @@ class ParameterProcessor:
         """Determine the target execution style based on original styles and config.
 
         Logic:
-        1. If there's a single original style and it's in supported execution styles, use it
-        2. Otherwise, use the default execution style
-        3. If no default execution style, use the default parameter style
+            1. If there's a single original style and it's in supported execution styles, use it
+            2. Otherwise, use the default execution style
+            3. If no default execution style, use the default parameter style
 
-        This preserves the original parameter style when possible, only converting
+        Preserves the original parameter style when possible, only converting
         when necessary for execution compatibility.
         """
 
@@ -1179,8 +1171,16 @@ class ParameterProcessor:
         """
 
         def coerce_value(value: Any) -> Any:
+            # Skip coercion for None values to preserve NULL semantics
+            if value is None:
+                return value
+
             if isinstance(value, TypedParameter):
-                wrapped_value = value.value
+                wrapped_value: Any = value.value
+                # Skip coercion for None values even when wrapped
+                if wrapped_value is None:
+                    return wrapped_value
+
                 original_type = value.original_type
                 if original_type in type_coercion_map:
                     coerced = type_coercion_map[original_type](wrapped_value)
@@ -1236,7 +1236,7 @@ def is_iterable_parameters(obj: Any) -> bool:
 
 
 def wrap_with_type(value: Any, semantic_name: Optional[str] = None) -> Any:
-    """Public API for type wrapping - preserves current interface.
+    """Public API for type wrapping.
 
     Args:
         value: Value to potentially wrap

sqlspec/core/result.py

@@ -3,16 +3,10 @@
 This module provides result classes for handling SQL query execution results
 including regular results and Apache Arrow format results.
 
-Components:
-- StatementResult: Abstract base class for SQL results
-- SQLResult: Main implementation for regular results
-- ArrowResult: Arrow-based results for data interchange
-
-Features:
-- Consistent interface across all result types
-- Support for both regular and Arrow format results
-- Result metadata and statistics
-- Iterator support for result rows
+Classes:
+    StatementResult: Abstract base class for SQL results.
+    SQLResult: Standard implementation for regular results.
+    ArrowResult: Apache Arrow format results for data interchange.
 """
 
 from abc import ABC, abstractmethod
@@ -36,17 +30,17 @@ T = TypeVar("T")
 
 @mypyc_attr(allow_interpreted_subclasses=False)
 class StatementResult(ABC):
-    """Base class for SQL statement execution results.
+    """Abstract base class for SQL statement execution results.
 
     Provides a common interface for handling different types of SQL operation
-    results. Subclasses implement specific behavior for SELECT, INSERT/UPDATE/DELETE,
-    and script operations.
+    results. Subclasses implement specific behavior for SELECT, INSERT, UPDATE,
+    DELETE, and script operations.
 
-    Args:
+    Attributes:
         statement: The original SQL statement that was executed.
-        data: The result data from the operation (type varies by subclass).
-        rows_affected: Number of rows affected by the operation (if applicable).
-        last_inserted_id: Last inserted ID (if applicable).
+        data: The result data from the operation.
+        rows_affected: Number of rows affected by the operation.
+        last_inserted_id: Last inserted ID from INSERT operations.
         execution_time: Time taken to execute the statement in seconds.
         metadata: Additional metadata about the operation.
     """
@@ -131,10 +125,23 @@ class SQLResult(StatementResult):
     """Result class for SQL operations that return rows or affect rows.
 
     Handles SELECT, INSERT, UPDATE, DELETE operations. For DML operations with
-    RETURNING clauses, the returned data will be in `self.data`. The `operation_type`
-    attribute helps distinguish the nature of the operation.
-
-    For script execution, this class also tracks multiple statement results and errors.
+    RETURNING clauses, the returned data is stored in the data attribute.
+    The operation_type attribute indicates the nature of the operation.
+
+    For script execution, tracks multiple statement results and errors.
+
+    Attributes:
+        column_names: Names of columns in the result set.
+        error: Exception that occurred during execution.
+        errors: List of error messages for script execution.
+        has_more: Whether there are additional result pages available.
+        inserted_ids: List of IDs from INSERT operations.
+        operation_index: Index of operation in a script.
+        parameters: Parameters used for the query.
+        statement_results: Results from individual statements in a script.
+        successful_statements: Count of successful statements in a script.
+        total_count: Total number of rows in the complete result set.
+        total_statements: Total number of statements in a script.
     """
 
     __slots__ = (
@@ -175,7 +182,28 @@ class SQLResult(StatementResult):
         total_statements: int = 0,
         successful_statements: int = 0,
     ) -> None:
-        """Initialize SQL result."""
+        """Initialize SQL result.
+
+        Args:
+            statement: The original SQL statement that was executed.
+            data: The result data from the operation.
+            rows_affected: Number of rows affected by the operation.
+            last_inserted_id: Last inserted ID from the operation.
+            execution_time: Time taken to execute the statement in seconds.
+            metadata: Additional metadata about the operation.
+            error: Exception that occurred during execution.
+            operation_type: Type of SQL operation performed.
+            operation_index: Index of operation in a script.
+            parameters: Parameters used for the query.
+            column_names: Names of columns in the result set.
+            total_count: Total number of rows in the complete result set.
+            has_more: Whether there are additional result pages available.
+            inserted_ids: List of IDs from INSERT operations.
+            statement_results: Results from individual statements in a script.
+            errors: List of error messages for script execution.
+            total_statements: Total number of statements in a script.
+            successful_statements: Count of successful statements in a script.
+        """
         super().__init__(
             statement=statement,
             data=data,
@@ -205,7 +233,11 @@ class SQLResult(StatementResult):
 
     @property
     def operation_type(self) -> OperationType:
-        """Get operation type for this result."""
+        """Get operation type for this result.
+
+        Returns:
+            The type of SQL operation that produced this result.
+        """
         return self._operation_type
 
     def get_metadata(self, key: str, default: Any = None) -> Any:
@@ -252,7 +284,8 @@ class SQLResult(StatementResult):
         """Get the data from the result.
 
         For regular operations, returns the list of rows.
-        For script operations, returns a summary dictionary.
+        For script operations, returns a summary dictionary containing
+        execution statistics and results.
 
         Returns:
             List of result rows or script summary.
@@ -479,14 +512,12 @@ class SQLResult(StatementResult):
 class ArrowResult(StatementResult):
     """Result class for SQL operations that return Apache Arrow data.
 
-    This class is used when database drivers support returning results as
-    Apache Arrow format for data interchange, especially
-    useful for analytics workloads and data science applications.
+    Used when database drivers support returning results in Apache Arrow
+    format for data interchange. Suitable for analytics workloads and
+    data science applications.
 
-    Args:
-        statement: The original SQL statement that was executed.
-        data: The Apache Arrow Table containing the result data.
-        schema: Optional Arrow schema information.
+    Attributes:
+        schema: Arrow schema information for the result data.
     """
 
     __slots__ = ("schema",)