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

sqlspec/adapters/bigquery/driver.py

@@ -50,7 +50,11 @@ _BQ_TYPE_MAP: dict[type, tuple[str, Optional[str]]] = {
 def _get_bq_param_type(value: Any) -> tuple[Optional[str], Optional[str]]:
     """Determine BigQuery parameter type from Python value.
 
-    Returns the appropriate BigQuery type for common Python types.
+    Args:
+        value: Python value to determine BigQuery type for
+
+    Returns:
+        Tuple of (parameter_type, array_element_type)
     """
     if value is None:
         return ("STRING", None)
@@ -88,7 +92,11 @@ _BQ_PARAM_CREATOR_MAP: dict[str, Any] = {
 def _create_bq_parameters(parameters: Any) -> "list[Union[ArrayQueryParameter, ScalarQueryParameter]]":
     """Create BigQuery QueryParameter objects from parameters.
 
-    Handles both dict-style (named) and list-style (positional) parameters.
+    Args:
+        parameters: Dict of named parameters or list of positional parameters
+
+    Returns:
+        List of BigQuery QueryParameter objects
     """
     if not parameters:
         return []
@@ -170,7 +178,16 @@ class BigQueryCursor:
         return self.connection
 
     def __exit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
-        _ = (exc_type, exc_val, exc_tb)
+        """Clean up cursor resources including active QueryJobs."""
+        if self.job is not None:
+            try:
+                # Cancel the job if it's still running to free up resources
+                if self.job.state in {"PENDING", "RUNNING"}:
+                    self.job.cancel()
+                # Clear the job reference
+                self.job = None
+            except Exception:
+                logger.exception("Failed to cancel BigQuery job during cursor cleanup")
 
 
 class BigQueryExceptionHandler:
@@ -258,7 +275,12 @@ class BigQueryDriver(SyncDriverAdapterBase):
         return BigQueryExceptionHandler()
 
     def _copy_job_config_attrs(self, source_config: QueryJobConfig, target_config: QueryJobConfig) -> None:
-        """Copy non-private attributes from source config to target config."""
+        """Copy non-private attributes from source config to target config.
+
+        Args:
+            source_config: Configuration to copy attributes from
+            target_config: Configuration to copy attributes to
+        """
         for attr in dir(source_config):
             if attr.startswith("_"):
                 continue
@@ -276,7 +298,17 @@ class BigQueryDriver(SyncDriverAdapterBase):
         connection: Optional[BigQueryConnection] = None,
         job_config: Optional[QueryJobConfig] = None,
     ) -> QueryJob:
-        """Execute a BigQuery job with configuration support."""
+        """Execute a BigQuery job with configuration support.
+
+        Args:
+            sql_str: SQL string to execute
+            parameters: Query parameters
+            connection: Optional BigQuery connection override
+            job_config: Optional job configuration
+
+        Returns:
+            QueryJob object representing the executed job
+        """
         conn = connection or self.connection
 
         final_job_config = QueryJobConfig()
@@ -294,7 +326,14 @@ class BigQueryDriver(SyncDriverAdapterBase):
 
     @staticmethod
     def _rows_to_results(rows_iterator: Any) -> list[dict[str, Any]]:
-        """Convert BigQuery rows to dictionary format."""
+        """Convert BigQuery rows to dictionary format.
+
+        Args:
+            rows_iterator: BigQuery rows iterator
+
+        Returns:
+            List of dictionaries representing the rows
+        """
         return [dict(row) for row in rows_iterator]
 
     def _try_special_handling(self, cursor: "Any", statement: "SQL") -> "Optional[SQLResult]":
@@ -316,7 +355,12 @@ class BigQueryDriver(SyncDriverAdapterBase):
     def _transform_ast_with_literals(self, sql: str, parameters: Any) -> str:
         """Transform SQL AST by replacing placeholders with literal values.
 
-        Uses AST transformation instead of string manipulation.
+        Args:
+            sql: SQL string to transform
+            parameters: Parameters to embed as literals
+
+        Returns:
+            Transformed SQL string with literals embedded
         """
         if not parameters:
             return sql
@@ -367,7 +411,14 @@ class BigQueryDriver(SyncDriverAdapterBase):
         return transformed_ast.sql(dialect="bigquery")
 
     def _create_literal_node(self, value: Any) -> "exp.Expression":
-        """Create a SQLGlot literal expression from a Python value."""
+        """Create a SQLGlot literal expression from a Python value.
+
+        Args:
+            value: Python value to convert to SQLGlot literal
+
+        Returns:
+            SQLGlot expression representing the literal value
+        """
         if value is None:
             return exp.Null()
         if isinstance(value, bool):
@@ -389,6 +440,13 @@ class BigQueryDriver(SyncDriverAdapterBase):
         """Execute SQL script with statement splitting and parameter handling.
 
         Parameters are embedded as static values for script execution compatibility.
+
+        Args:
+            cursor: BigQuery cursor object
+            statement: SQL statement to execute
+
+        Returns:
+            ExecutionResult with script execution details
         """
         sql, prepared_parameters = self._get_compiled_sql(statement, self.statement_config)
         statements = self.split_script_statements(sql, statement.statement_config, strip_trailing_semicolon=True)
@@ -414,6 +472,13 @@ class BigQueryDriver(SyncDriverAdapterBase):
         BigQuery doesn't support traditional execute_many with parameter batching.
         Instead, we generate a script with multiple INSERT statements using
         AST transformation to embed literals safely.
+
+        Args:
+            cursor: BigQuery cursor object
+            statement: SQL statement to execute with multiple parameter sets
+
+        Returns:
+            ExecutionResult with batch execution details
         """
 
         parameters_list = statement.parameters
@@ -441,7 +506,12 @@ class BigQueryDriver(SyncDriverAdapterBase):
     def _execute_statement(self, cursor: Any, statement: "SQL") -> ExecutionResult:
         """Execute single SQL statement with BigQuery data handling.
 
-        Handles parameter processing and BigQuery result processing.
+        Args:
+            cursor: BigQuery cursor object
+            statement: SQL statement to execute
+
+        Returns:
+            ExecutionResult with query results and metadata
         """
         sql, parameters = self._get_compiled_sql(statement, self.statement_config)
         cursor.job = self._run_query_job(sql, parameters, connection=cursor)

sqlspec/adapters/duckdb/driver.py

@@ -1,17 +1,4 @@
-"""DuckDB driver implementation.
-
-This driver provides:
-- SQL compilation with single-pass processing
-- Memory-efficient design with __slots__
-- Statement caching for repeated execution
-- Backward compatibility with existing functionality
-
-Features:
-- Integration with sqlspec.core modules
-- Parameter processing with type coercion
-- DuckDB resource management
-- Multi-parameter style support
-"""
+"""DuckDB driver implementation."""
 
 from typing import TYPE_CHECKING, Any, Final, Optional
 
@@ -80,7 +67,11 @@ class DuckDBCursor:
 
 
 class DuckDBExceptionHandler:
-    """Custom sync context manager for handling DuckDB database exceptions."""
+    """Context manager for handling DuckDB database exceptions.
+
+    Catches DuckDB-specific exceptions and converts them to appropriate
+    SQLSpec exception types for consistent error handling.
+    """
 
     __slots__ = ()
 
@@ -126,33 +117,14 @@ class DuckDBExceptionHandler:
 
 
 class DuckDBDriver(SyncDriverAdapterBase):
-    """DuckDB driver implementation.
-
-    This driver uses the core module system for SQL processing:
-
-    Features:
-    - SQL compilation with single-pass processing
-    - Memory-efficient design with __slots__
-    - Statement caching for repeated execution
-    - Parameter processing with type coercion
-    - DuckDB resource management
-
-    Core Integration:
-    - sqlspec.core.statement for SQL processing
-    - sqlspec.core.parameters for parameter handling
-    - sqlspec.core.cache for statement caching
-    - sqlspec.core.config for configuration management
-
-    DuckDB Support:
-    - Multi-parameter style support (QMARK, NUMERIC, NAMED_DOLLAR)
-    - Script execution with statement splitting
-    - Batch operations with row counting
-    - DuckDB-specific exception handling
-
-    Compatibility:
-    - Backward compatibility with existing DuckDB driver interface
-    - StatementConfig API compatibility
-    - Transaction management patterns
+    """Synchronous DuckDB database driver.
+
+    Provides SQL statement execution, transaction management, and result handling
+    for DuckDB databases. Supports multiple parameter styles including QMARK,
+    NUMERIC, and NAMED_DOLLAR formats.
+
+    The driver handles script execution, batch operations, and integrates with
+    the sqlspec.core modules for statement processing and caching.
     """
 
     __slots__ = ()
@@ -177,34 +149,45 @@ class DuckDBDriver(SyncDriverAdapterBase):
         super().__init__(connection=connection, statement_config=statement_config, driver_features=driver_features)
 
     def with_cursor(self, connection: "DuckDBConnection") -> "DuckDBCursor":
-        """Create context manager for DuckDB cursor."""
+        """Create context manager for DuckDB cursor.
+
+        Args:
+            connection: DuckDB connection instance
+
+        Returns:
+            DuckDBCursor context manager instance
+        """
         return DuckDBCursor(connection)
 
     def handle_database_exceptions(self) -> "AbstractContextManager[None]":
-        """Handle database-specific exceptions and wrap them appropriately."""
+        """Handle database-specific exceptions and wrap them appropriately.
+
+        Returns:
+            Context manager that catches and converts DuckDB exceptions
+        """
         return DuckDBExceptionHandler()
 
     def _try_special_handling(self, cursor: Any, statement: SQL) -> "Optional[SQLResult]":
         """Handle DuckDB-specific special operations.
 
-        DuckDB doesn't have special operations like PostgreSQL COPY,
-        so this always returns None to proceed with standard execution.
+        DuckDB does not require special operation handling, so this method
+        returns None to indicate standard execution should proceed.
 
         Args:
             cursor: DuckDB cursor object
             statement: SQL statement to analyze
 
         Returns:
-            None for standard execution (no special operations)
+            None to indicate no special handling required
         """
         _ = (cursor, statement)
         return None
 
     def _is_modifying_operation(self, statement: SQL) -> bool:
-        """Check if the SQL statement is a modifying operation.
+        """Check if the SQL statement modifies data.
 
-        Uses both AST-based detection (when available) and SQL text analysis
-        to identify operation type.
+        Determines if a statement is an INSERT, UPDATE, or DELETE operation
+        using AST analysis when available, falling back to text parsing.
 
         Args:
             statement: SQL statement to analyze
@@ -223,8 +206,8 @@ class DuckDBDriver(SyncDriverAdapterBase):
     def _execute_script(self, cursor: Any, statement: SQL) -> "ExecutionResult":
         """Execute SQL script with statement splitting and parameter handling.
 
-        Uses core module for statement parsing and parameter processing.
-        Handles DuckDB script execution requirements with parameter support.
+        Parses multi-statement scripts and executes each statement sequentially
+        with the provided parameters.
 
         Args:
             cursor: DuckDB cursor object
@@ -250,8 +233,8 @@ class DuckDBDriver(SyncDriverAdapterBase):
     def _execute_many(self, cursor: Any, statement: SQL) -> "ExecutionResult":
         """Execute SQL with multiple parameter sets using batch processing.
 
-        Uses DuckDB's executemany for batch operations with
-        row counting for both modifying and non-modifying operations.
+        Uses DuckDB's executemany method for batch operations and calculates
+        row counts for both data modification and query operations.
 
         Args:
             cursor: DuckDB cursor object
@@ -281,8 +264,8 @@ class DuckDBDriver(SyncDriverAdapterBase):
     def _execute_statement(self, cursor: Any, statement: SQL) -> "ExecutionResult":
         """Execute single SQL statement with data handling.
 
-        Uses core processing for parameter handling and result processing.
-        Handles both SELECT queries and non-SELECT operations.
+        Executes a SQL statement with parameter binding and processes the results.
+        Handles both data-returning queries and data modification operations.
 
         Args:
             cursor: DuckDB cursor object

sqlspec/adapters/oracledb/driver.py

@@ -1,26 +1,4 @@
-"""Enhanced Oracle driver with CORE_ROUND_3 architecture integration.
-
-This driver implements the complete CORE_ROUND_3 architecture for Oracle Database connections:
-- 5-10x faster SQL compilation through single-pass processing
-- 40-60% memory reduction through __slots__ optimization
-- Enhanced caching for repeated statement execution
-- Complete backward compatibility with existing Oracle functionality
-
-Architecture Features:
-- Direct integration with sqlspec.core modules
-- Enhanced Oracle parameter processing with QMARK/COLON conversion
-- Thread-safe unified caching system
-- MyPyC-optimized performance patterns
-- Zero-copy data access where possible
-- Both sync and async context management
-
-Oracle Features:
-- Parameter style conversion (QMARK to NAMED_COLON/POSITIONAL_COLON)
-- Oracle-specific type coercion and data handling
-- Enhanced error categorization for Oracle database errors
-- Transaction management with automatic commit/rollback
-- Support for both sync and async execution modes
-"""
+"""Oracle Driver"""
 
 import logging
 from typing import TYPE_CHECKING, Any, Optional
@@ -53,20 +31,18 @@ __all__ = (
 )
 
 
-# Enhanced Oracle statement configuration using core modules with performance optimizations
 oracledb_statement_config = StatementConfig(
     dialect="oracle",
     parameter_config=ParameterStyleConfig(
-        default_parameter_style=ParameterStyle.POSITIONAL_COLON,  # Oracle's :1, :2 style
+        default_parameter_style=ParameterStyle.POSITIONAL_COLON,
         supported_parameter_styles={ParameterStyle.NAMED_COLON, ParameterStyle.POSITIONAL_COLON, ParameterStyle.QMARK},
-        default_execution_parameter_style=ParameterStyle.POSITIONAL_COLON,  # Keep Oracle's native :1, :2
+        default_execution_parameter_style=ParameterStyle.POSITIONAL_COLON,
         supported_execution_parameter_styles={ParameterStyle.NAMED_COLON, ParameterStyle.POSITIONAL_COLON},
         type_coercion_map={},
         has_native_list_expansion=False,
         needs_static_script_compilation=True,
         preserve_parameter_format=True,
     ),
-    # Core processing features enabled for performance
     enable_parsing=True,
     enable_validation=True,
     enable_caching=True,
@@ -75,7 +51,7 @@ oracledb_statement_config = StatementConfig(
 
 
 class OracleSyncCursor:
-    """Sync context manager for Oracle cursor management with enhanced error handling."""
+    """Sync context manager for Oracle cursor management."""
 
     __slots__ = ("connection", "cursor")
 
@@ -94,7 +70,7 @@ class OracleSyncCursor:
 
 
 class OracleAsyncCursor:
-    """Async context manager for Oracle cursor management with enhanced error handling."""
+    """Async context manager for Oracle cursor management."""
 
     __slots__ = ("connection", "cursor")
 
@@ -113,7 +89,7 @@ class OracleAsyncCursor:
 
 
 class OracleSyncExceptionHandler:
-    """Custom sync context manager for handling Oracle database exceptions."""
+    """Context manager for handling Oracle database exceptions in synchronous operations."""
 
     __slots__ = ()
 
@@ -160,7 +136,7 @@ class OracleSyncExceptionHandler:
 
 
 class OracleAsyncExceptionHandler:
-    """Custom async context manager for handling Oracle database exceptions."""
+    """Context manager for handling Oracle database exceptions in asynchronous operations."""
 
     __slots__ = ()
 
@@ -222,21 +198,26 @@ class OracleSyncDriver(SyncDriverAdapterBase):
         statement_config: "Optional[StatementConfig]" = None,
         driver_features: "Optional[dict[str, Any]]" = None,
     ) -> None:
-        # Configure with default settings
         if statement_config is None:
             cache_config = get_cache_config()
-            enhanced_config = oracledb_statement_config.replace(
+            statement_config = oracledb_statement_config.replace(
                 enable_caching=cache_config.compiled_cache_enabled,
                 enable_parsing=True,
                 enable_validation=True,
                 dialect="oracle",
             )
-            statement_config = enhanced_config
 
         super().__init__(connection=connection, statement_config=statement_config, driver_features=driver_features)
 
     def with_cursor(self, connection: OracleSyncConnection) -> OracleSyncCursor:
-        """Create sync context manager for Oracle cursor with enhanced resource management."""
+        """Create context manager for Oracle cursor.
+
+        Args:
+            connection: Oracle database connection
+
+        Returns:
+            Context manager for cursor operations
+        """
         return OracleSyncCursor(connection)
 
     def handle_database_exceptions(self) -> "AbstractContextManager[None]":
@@ -260,10 +241,16 @@ class OracleSyncDriver(SyncDriverAdapterBase):
         return None
 
     def _execute_script(self, cursor: Any, statement: "SQL") -> "ExecutionResult":
-        """Execute SQL script using enhanced statement splitting and parameter handling.
+        """Execute SQL script with statement splitting and parameter handling.
 
-        Uses core module optimization for statement parsing and parameter processing.
         Parameters are embedded as static values for script execution compatibility.
+
+        Args:
+            cursor: Oracle cursor object
+            statement: SQL script statement to execute
+
+        Returns:
+            Execution result containing statement count and success information
         """
         sql, prepared_parameters = self._get_compiled_sql(statement, self.statement_config)
         statements = self.split_script_statements(sql, statement.statement_config, strip_trailing_semicolon=True)
@@ -280,9 +267,17 @@ class OracleSyncDriver(SyncDriverAdapterBase):
         )
 
     def _execute_many(self, cursor: Any, statement: "SQL") -> "ExecutionResult":
-        """Execute SQL with multiple parameter sets using optimized Oracle batch processing.
+        """Execute SQL with multiple parameter sets using Oracle batch processing.
+
+        Args:
+            cursor: Oracle cursor object
+            statement: SQL statement with multiple parameter sets
+
+        Returns:
+            Execution result with affected row count
 
-        Leverages core parameter processing for enhanced Oracle type handling and parameter conversion.
+        Raises:
+            ValueError: If no parameters are provided
         """
         sql, prepared_parameters = self._get_compiled_sql(statement, self.statement_config)
 
@@ -299,9 +294,14 @@ class OracleSyncDriver(SyncDriverAdapterBase):
         return self.create_execution_result(cursor, rowcount_override=affected_rows, is_many_result=True)
 
     def _execute_statement(self, cursor: Any, statement: "SQL") -> "ExecutionResult":
-        """Execute single SQL statement with enhanced Oracle data handling and performance optimization.
+        """Execute single SQL statement with Oracle data handling.
 
-        Uses core processing for optimal parameter handling and Oracle result processing.
+        Args:
+            cursor: Oracle cursor object
+            statement: SQL statement to execute
+
+        Returns:
+            Execution result containing data for SELECT statements or row count for others
         """
         sql, prepared_parameters = self._get_compiled_sql(statement, self.statement_config)
         cursor.execute(sql, prepared_parameters or {})
@@ -324,14 +324,18 @@ class OracleSyncDriver(SyncDriverAdapterBase):
 
     # Oracle transaction management
     def begin(self) -> None:
-        """Begin a database transaction with enhanced error handling.
+        """Begin a database transaction.
 
         Oracle handles transactions automatically, so this is a no-op.
         """
         # Oracle handles transactions implicitly
 
     def rollback(self) -> None:
-        """Rollback the current transaction with enhanced error handling."""
+        """Rollback the current transaction.
+
+        Raises:
+            SQLSpecError: If rollback fails
+        """
         try:
             self.connection.rollback()
         except oracledb.Error as e:
@@ -339,7 +343,11 @@ class OracleSyncDriver(SyncDriverAdapterBase):
             raise SQLSpecError(msg) from e
 
     def commit(self) -> None:
-        """Commit the current transaction with enhanced error handling."""
+        """Commit the current transaction.
+
+        Raises:
+            SQLSpecError: If commit fails
+        """
         try:
             self.connection.commit()
         except oracledb.Error as e:
@@ -363,21 +371,26 @@ class OracleAsyncDriver(AsyncDriverAdapterBase):
         statement_config: "Optional[StatementConfig]" = None,
         driver_features: "Optional[dict[str, Any]]" = None,
     ) -> None:
-        # Configure with default settings
         if statement_config is None:
             cache_config = get_cache_config()
-            enhanced_config = oracledb_statement_config.replace(
+            statement_config = oracledb_statement_config.replace(
                 enable_caching=cache_config.compiled_cache_enabled,
                 enable_parsing=True,
                 enable_validation=True,
                 dialect="oracle",
             )
-            statement_config = enhanced_config
 
         super().__init__(connection=connection, statement_config=statement_config, driver_features=driver_features)
 
     def with_cursor(self, connection: OracleAsyncConnection) -> OracleAsyncCursor:
-        """Create async context manager for Oracle cursor."""
+        """Create context manager for Oracle cursor.
+
+        Args:
+            connection: Oracle database connection
+
+        Returns:
+            Context manager for cursor operations
+        """
         return OracleAsyncCursor(connection)
 
     def handle_database_exceptions(self) -> "AbstractAsyncContextManager[None]":
@@ -404,6 +417,13 @@ class OracleAsyncDriver(AsyncDriverAdapterBase):
         """Execute SQL script with statement splitting and parameter handling.
 
         Parameters are embedded as static values for script execution compatibility.
+
+        Args:
+            cursor: Oracle cursor object
+            statement: SQL script statement to execute
+
+        Returns:
+            Execution result containing statement count and success information
         """
         sql, prepared_parameters = self._get_compiled_sql(statement, self.statement_config)
         statements = self.split_script_statements(sql, statement.statement_config, strip_trailing_semicolon=True)
@@ -420,7 +440,18 @@ class OracleAsyncDriver(AsyncDriverAdapterBase):
         )
 
     async def _execute_many(self, cursor: Any, statement: "SQL") -> "ExecutionResult":
-        """Execute SQL with multiple parameter sets using Oracle batch processing."""
+        """Execute SQL with multiple parameter sets using Oracle batch processing.
+
+        Args:
+            cursor: Oracle cursor object
+            statement: SQL statement with multiple parameter sets
+
+        Returns:
+            Execution result with affected row count
+
+        Raises:
+            ValueError: If no parameters are provided
+        """
         sql, prepared_parameters = self._get_compiled_sql(statement, self.statement_config)
 
         # Parameter validation for executemany
@@ -436,7 +467,15 @@ class OracleAsyncDriver(AsyncDriverAdapterBase):
         return self.create_execution_result(cursor, rowcount_override=affected_rows, is_many_result=True)
 
     async def _execute_statement(self, cursor: Any, statement: "SQL") -> "ExecutionResult":
-        """Execute single SQL statement with Oracle data handling."""
+        """Execute single SQL statement with Oracle data handling.
+
+        Args:
+            cursor: Oracle cursor object
+            statement: SQL statement to execute
+
+        Returns:
+            Execution result containing data for SELECT statements or row count for others
+        """
         sql, prepared_parameters = self._get_compiled_sql(statement, self.statement_config)
         await cursor.execute(sql, prepared_parameters or {})
 
@@ -465,7 +504,11 @@ class OracleAsyncDriver(AsyncDriverAdapterBase):
         # Oracle handles transactions implicitly
 
     async def rollback(self) -> None:
-        """Rollback the current transaction."""
+        """Rollback the current transaction.
+
+        Raises:
+            SQLSpecError: If rollback fails
+        """
         try:
             await self.connection.rollback()
         except oracledb.Error as e:
@@ -473,7 +516,11 @@ class OracleAsyncDriver(AsyncDriverAdapterBase):
             raise SQLSpecError(msg) from e
 
     async def commit(self) -> None:
-        """Commit the current transaction."""
+        """Commit the current transaction.
+
+        Raises:
+            SQLSpecError: If commit fails
+        """
         try:
             await self.connection.commit()
         except oracledb.Error as e: