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

sqlspec/adapters/psycopg/driver.py

@@ -1,25 +1,17 @@
-"""Enhanced PostgreSQL psycopg driver with CORE_ROUND_3 architecture integration.
-
-This driver implements the complete CORE_ROUND_3 architecture for PostgreSQL connections using psycopg3:
-- 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 PostgreSQL functionality
-
-Architecture Features:
-- Direct integration with sqlspec.core modules
-- Enhanced PostgreSQL parameter processing with advanced type coercion
-- PostgreSQL-specific features (COPY, arrays, JSON, advanced types)
-- Thread-safe unified caching system
-- MyPyC-optimized performance patterns
-- Zero-copy data access where possible
+"""PostgreSQL psycopg driver implementation.
+
+This driver provides PostgreSQL database connectivity using psycopg3:
+- SQL statement execution with parameter binding
+- Connection and transaction management
+- Row result processing with dictionary-based access
+- PostgreSQL-specific features (COPY, arrays, JSON types)
 
 PostgreSQL Features:
-- Advanced parameter styles ($1, %s, %(name)s)
-- PostgreSQL array support with optimized conversion
-- COPY operations with enhanced performance
+- Parameter styles ($1, %s, %(name)s)
+- PostgreSQL array support
+- COPY operations for bulk data transfer
 - JSON/JSONB type handling
-- PostgreSQL-specific error categorization
+- PostgreSQL-specific error handling
 """
 
 import io
@@ -44,7 +36,7 @@ if TYPE_CHECKING:
 
 logger = get_logger("adapters.psycopg")
 
-# PostgreSQL transaction status constants
+
 TRANSACTION_STATUS_IDLE = 0
 TRANSACTION_STATUS_ACTIVE = 1
 TRANSACTION_STATUS_INTRANS = 2
@@ -53,7 +45,7 @@ TRANSACTION_STATUS_UNKNOWN = 4
 
 
 def _convert_list_to_postgres_array(value: Any) -> str:
-    """Convert Python list to PostgreSQL array literal format with enhanced type handling.
+    """Convert Python list to PostgreSQL array literal format.
 
     Args:
         value: Python list to convert
@@ -64,13 +56,11 @@ def _convert_list_to_postgres_array(value: Any) -> str:
     if not isinstance(value, list):
         return str(value)
 
-    # Handle nested arrays and complex types
     elements = []
     for item in value:
         if isinstance(item, list):
             elements.append(_convert_list_to_postgres_array(item))
         elif isinstance(item, str):
-            # Escape quotes and handle special characters
             escaped = item.replace("'", "''")
             elements.append(f"'{escaped}'")
         elif item is None:
@@ -81,7 +71,6 @@ def _convert_list_to_postgres_array(value: Any) -> str:
     return f"{{{','.join(elements)}}}"
 
 
-# Enhanced PostgreSQL statement configuration using core modules with performance optimizations
 psycopg_statement_config = StatementConfig(
     dialect="postgres",
     pre_process_steps=None,
@@ -105,12 +94,7 @@ psycopg_statement_config = StatementConfig(
             ParameterStyle.NAMED_PYFORMAT,
             ParameterStyle.NUMERIC,
         },
-        type_coercion_map={
-            dict: to_json
-            # Note: Psycopg3 handles Python lists natively, so no conversion needed
-            # list: _convert_list_to_postgres_array,
-            # tuple: lambda v: _convert_list_to_postgres_array(list(v)),
-        },
+        type_coercion_map={dict: to_json},
         has_native_list_expansion=True,
         needs_static_script_compilation=False,
         preserve_parameter_format=True,
@@ -129,7 +113,7 @@ __all__ = (
 
 
 class PsycopgSyncCursor:
-    """Context manager for PostgreSQL psycopg cursor management with enhanced error handling."""
+    """Context manager for PostgreSQL psycopg cursor management."""
 
     __slots__ = ("connection", "cursor")
 
@@ -142,13 +126,13 @@ class PsycopgSyncCursor:
         return self.cursor
 
     def __exit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
-        _ = (exc_type, exc_val, exc_tb)  # Mark as intentionally unused
+        _ = (exc_type, exc_val, exc_tb)
         if self.cursor is not None:
             self.cursor.close()
 
 
 class PsycopgSyncExceptionHandler:
-    """Custom sync context manager for handling PostgreSQL psycopg database exceptions."""
+    """Context manager for handling PostgreSQL psycopg database exceptions."""
 
     __slots__ = ()
 
@@ -194,35 +178,19 @@ class PsycopgSyncExceptionHandler:
 
 
 class PsycopgSyncDriver(SyncDriverAdapterBase):
-    """Enhanced PostgreSQL psycopg synchronous driver with CORE_ROUND_3 architecture integration.
-
-    This driver leverages the complete core module system for maximum PostgreSQL performance:
+    """PostgreSQL psycopg synchronous driver.
 
-    Performance Improvements:
-    - 5-10x faster SQL compilation through single-pass processing
-    - 40-60% memory reduction through __slots__ optimization
-    - Enhanced caching for repeated statement execution
-    - Optimized PostgreSQL array and JSON handling
-    - Zero-copy parameter processing where possible
+    Provides synchronous database operations for PostgreSQL using psycopg3:
+    - SQL statement execution with parameter binding
+    - Transaction management (begin, commit, rollback)
+    - Result processing with column metadata
+    - PostgreSQL-specific features support
 
     PostgreSQL Features:
-    - Advanced parameter styles ($1, %s, %(name)s)
-    - PostgreSQL array support with optimized conversion
-    - COPY operations with enhanced performance
-    - JSON/JSONB type handling
-    - PostgreSQL-specific error categorization
-
-    Core Integration Features:
-    - sqlspec.core.statement for enhanced SQL processing
-    - sqlspec.core.parameters for optimized parameter handling
-    - sqlspec.core.cache for unified statement caching
-    - sqlspec.core.config for centralized configuration management
-
-    Compatibility:
-    - 100% backward compatibility with existing psycopg driver interface
-    - All existing PostgreSQL tests pass without modification
-    - Complete StatementConfig API compatibility
-    - Preserved cursor management and exception handling patterns
+    - Parameter styles ($1, %s, %(name)s)
+    - PostgreSQL arrays and JSON handling
+    - COPY operations for bulk data transfer
+    - PostgreSQL-specific error handling
     """
 
     __slots__ = ()
@@ -234,33 +202,28 @@ class PsycopgSyncDriver(SyncDriverAdapterBase):
         statement_config: "Optional[StatementConfig]" = None,
         driver_features: "Optional[dict[str, Any]]" = None,
     ) -> None:
-        # Enhanced configuration with global settings integration
         if statement_config is None:
             cache_config = get_cache_config()
-            enhanced_config = psycopg_statement_config.replace(
+            default_config = psycopg_statement_config.replace(
                 enable_caching=cache_config.compiled_cache_enabled,
-                enable_parsing=True,  # Default to enabled
-                enable_validation=True,  # Default to enabled
-                dialect="postgres",  # Use adapter-specific dialect
+                enable_parsing=True,
+                enable_validation=True,
+                dialect="postgres",
             )
-            statement_config = enhanced_config
+            statement_config = default_config
 
         super().__init__(connection=connection, statement_config=statement_config, driver_features=driver_features)
 
     def with_cursor(self, connection: PsycopgSyncConnection) -> PsycopgSyncCursor:
-        """Create context manager for PostgreSQL cursor with enhanced resource management."""
+        """Create context manager for PostgreSQL cursor."""
         return PsycopgSyncCursor(connection)
 
     def begin(self) -> None:
         """Begin a database transaction on the current connection."""
         try:
-            # psycopg3 has explicit transaction support
-            # If already in a transaction, this is a no-op
             if hasattr(self.connection, "autocommit") and not self.connection.autocommit:
-                # Already in manual commit mode, just ensure we're in a clean state
                 pass
             else:
-                # Start manual transaction mode
                 self.connection.autocommit = False
         except Exception as e:
             msg = f"Failed to begin transaction: {e}"
@@ -287,17 +250,15 @@ class PsycopgSyncDriver(SyncDriverAdapterBase):
         return PsycopgSyncExceptionHandler()
 
     def _handle_transaction_error_cleanup(self) -> None:
-        """Handle transaction cleanup after database errors to prevent aborted transaction states."""
+        """Handle transaction cleanup after database errors."""
         try:
-            # Check if connection is in a failed transaction state
             if hasattr(self.connection, "info") and hasattr(self.connection.info, "transaction_status"):
                 status = self.connection.info.transaction_status
-                # PostgreSQL transaction statuses: IDLE=0, ACTIVE=1, INTRANS=2, INERROR=3, UNKNOWN=4
+
                 if status == TRANSACTION_STATUS_INERROR:
                     logger.debug("Connection in aborted transaction state, performing rollback")
                     self.connection.rollback()
         except Exception as cleanup_error:
-            # If cleanup fails, log but don't raise - the original error is more important
             logger.warning("Failed to cleanup transaction state: %s", cleanup_error)
 
     def _try_special_handling(self, cursor: Any, statement: "SQL") -> "Optional[SQLResult]":
@@ -310,14 +271,12 @@ class PsycopgSyncDriver(SyncDriverAdapterBase):
         Returns:
             SQLResult if special handling was applied, None otherwise
         """
-        # Compile the statement to get the operation type
+
         statement.compile()
 
-        # Use the operation_type from the statement object
         if statement.operation_type in {"COPY_FROM", "COPY_TO"}:
             return self._handle_copy_operation(cursor, statement)
 
-        # No special handling needed - proceed with standard execution
         return None
 
     def _handle_copy_operation(self, cursor: Any, statement: "SQL") -> "SQLResult":
@@ -330,27 +289,21 @@ class PsycopgSyncDriver(SyncDriverAdapterBase):
         Returns:
             SQLResult with COPY operation results
         """
-        # Use the properly rendered SQL from the statement
+
         sql = statement.sql
 
-        # Get COPY data from parameters - handle both direct value and list format
         copy_data = statement.parameters
         if isinstance(copy_data, list) and len(copy_data) == 1:
             copy_data = copy_data[0]
 
-        # Use the operation_type from the statement
         if statement.operation_type == "COPY_FROM":
-            # COPY FROM STDIN - import data
             if isinstance(copy_data, (str, bytes)):
                 data_file = io.StringIO(copy_data) if isinstance(copy_data, str) else io.BytesIO(copy_data)
             elif hasattr(copy_data, "read"):
-                # Already a file-like object
                 data_file = copy_data
             else:
-                # Convert to string representation
                 data_file = io.StringIO(str(copy_data))
 
-            # Use context manager for COPY FROM (sync version)
             with cursor.copy(sql) as copy_ctx:
                 data_to_write = data_file.read() if hasattr(data_file, "read") else str(copy_data)  # pyright: ignore
                 if isinstance(data_to_write, str):
@@ -364,7 +317,6 @@ class PsycopgSyncDriver(SyncDriverAdapterBase):
             )
 
         if statement.operation_type == "COPY_TO":
-            # COPY TO STDOUT - export data
             output_data: list[str] = []
             with cursor.copy(sql) as copy_ctx:
                 output_data.extend(row.decode() if isinstance(row, bytes) else str(row) for row in copy_ctx)
@@ -372,13 +324,12 @@ class PsycopgSyncDriver(SyncDriverAdapterBase):
             exported_data = "".join(output_data)
 
             return SQLResult(
-                data=[{"copy_output": exported_data}],  # Wrap in list format for consistency
+                data=[{"copy_output": exported_data}],
                 rows_affected=0,
                 statement=statement,
                 metadata={"copy_operation": "TO_STDOUT"},
             )
 
-        # Regular COPY with file - execute normally
         cursor.execute(sql)
         rows_affected = max(cursor.rowcount, 0)
 
@@ -387,10 +338,14 @@ class PsycopgSyncDriver(SyncDriverAdapterBase):
         )
 
     def _execute_script(self, cursor: Any, statement: "SQL") -> "ExecutionResult":
-        """Execute SQL script using enhanced statement splitting and parameter handling.
+        """Execute SQL script with multiple statements.
+
+        Args:
+            cursor: Database cursor
+            statement: SQL statement containing multiple commands
 
-        Uses core module optimization for statement parsing and parameter processing.
-        PostgreSQL supports complex scripts with multiple statements.
+        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)
@@ -399,7 +354,6 @@ class PsycopgSyncDriver(SyncDriverAdapterBase):
         last_cursor = cursor
 
         for stmt in statements:
-            # Only pass parameters if they exist - psycopg treats empty containers as parameterized mode
             if prepared_parameters:
                 cursor.execute(stmt, prepared_parameters)
             else:
@@ -411,42 +365,47 @@ class PsycopgSyncDriver(SyncDriverAdapterBase):
         )
 
     def _execute_many(self, cursor: Any, statement: "SQL") -> "ExecutionResult":
-        """Execute SQL with multiple parameter sets using optimized PostgreSQL batch processing.
+        """Execute SQL with multiple parameter sets.
+
+        Args:
+            cursor: Database cursor
+            statement: SQL statement with parameter list
 
-        Leverages core parameter processing for enhanced PostgreSQL type handling.
+        Returns:
+            ExecutionResult with batch execution details
         """
         sql, prepared_parameters = self._get_compiled_sql(statement, self.statement_config)
 
-        # Handle empty parameter list case
         if not prepared_parameters:
-            # For empty parameter list, return a result with no rows affected
             return self.create_execution_result(cursor, rowcount_override=0, is_many_result=True)
 
         cursor.executemany(sql, prepared_parameters)
 
-        # PostgreSQL cursor.rowcount gives total affected rows
         affected_rows = cursor.rowcount if cursor.rowcount and cursor.rowcount > 0 else 0
 
         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 PostgreSQL data handling and performance optimization.
+        """Execute single SQL statement.
+
+        Args:
+            cursor: Database cursor
+            statement: SQL statement to execute
 
-        Uses core processing for optimal parameter handling and PostgreSQL result processing.
+        Returns:
+            ExecutionResult with statement execution details
         """
         sql, prepared_parameters = self._get_compiled_sql(statement, self.statement_config)
-        # Only pass parameters if they exist - psycopg treats empty containers as parameterized mode
+
         if prepared_parameters:
             cursor.execute(sql, prepared_parameters)
         else:
             cursor.execute(sql)
 
-        # Enhanced SELECT result processing for PostgreSQL
         if statement.returns_rows():
             fetched_data = cursor.fetchall()
             column_names = [col.name for col in cursor.description or []]
 
-            # PostgreSQL returns raw data - pass it directly like the old driver
             return self.create_execution_result(
                 cursor,
                 selected_data=fetched_data,
@@ -455,13 +414,12 @@ class PsycopgSyncDriver(SyncDriverAdapterBase):
                 is_select_result=True,
             )
 
-        # Enhanced non-SELECT result processing for PostgreSQL
         affected_rows = cursor.rowcount if cursor.rowcount and cursor.rowcount > 0 else 0
         return self.create_execution_result(cursor, rowcount_override=affected_rows)
 
 
 class PsycopgAsyncCursor:
-    """Async context manager for PostgreSQL psycopg cursor management with enhanced error handling."""
+    """Async context manager for PostgreSQL psycopg cursor management."""
 
     __slots__ = ("connection", "cursor")
 
@@ -474,13 +432,13 @@ class PsycopgAsyncCursor:
         return self.cursor
 
     async def __aexit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
-        _ = (exc_type, exc_val, exc_tb)  # Mark as intentionally unused
+        _ = (exc_type, exc_val, exc_tb)
         if self.cursor is not None:
             await self.cursor.close()
 
 
 class PsycopgAsyncExceptionHandler:
-    """Custom async context manager for handling PostgreSQL psycopg database exceptions."""
+    """Async context manager for handling PostgreSQL psycopg database exceptions."""
 
     __slots__ = ()
 
@@ -526,37 +484,20 @@ class PsycopgAsyncExceptionHandler:
 
 
 class PsycopgAsyncDriver(AsyncDriverAdapterBase):
-    """Enhanced PostgreSQL psycopg asynchronous driver with CORE_ROUND_3 architecture integration.
-
-    This async driver leverages the complete core module system for maximum PostgreSQL performance:
+    """PostgreSQL psycopg asynchronous driver.
 
-    Performance Improvements:
-    - 5-10x faster SQL compilation through single-pass processing
-    - 40-60% memory reduction through __slots__ optimization
-    - Enhanced caching for repeated statement execution
-    - Optimized PostgreSQL array and JSON handling
-    - Zero-copy parameter processing where possible
-    - Async-optimized resource management
+    Provides asynchronous database operations for PostgreSQL using psycopg3:
+    - Async SQL statement execution with parameter binding
+    - Async transaction management (begin, commit, rollback)
+    - Async result processing with column metadata
+    - PostgreSQL-specific features support
 
     PostgreSQL Features:
-    - Advanced parameter styles ($1, %s, %(name)s)
-    - PostgreSQL array support with optimized conversion
-    - COPY operations with enhanced performance
-    - JSON/JSONB type handling
-    - PostgreSQL-specific error categorization
+    - Parameter styles ($1, %s, %(name)s)
+    - PostgreSQL arrays and JSON handling
+    - COPY operations for bulk data transfer
+    - PostgreSQL-specific error handling
     - Async pub/sub support (LISTEN/NOTIFY)
-
-    Core Integration Features:
-    - sqlspec.core.statement for enhanced SQL processing
-    - sqlspec.core.parameters for optimized parameter handling
-    - sqlspec.core.cache for unified statement caching
-    - sqlspec.core.config for centralized configuration management
-
-    Compatibility:
-    - 100% backward compatibility with existing async psycopg driver interface
-    - All existing async PostgreSQL tests pass without modification
-    - Complete StatementConfig API compatibility
-    - Preserved async cursor management and exception handling patterns
     """
 
     __slots__ = ()
@@ -568,33 +509,28 @@ class PsycopgAsyncDriver(AsyncDriverAdapterBase):
         statement_config: "Optional[StatementConfig]" = None,
         driver_features: "Optional[dict[str, Any]]" = None,
     ) -> None:
-        # Enhanced configuration with global settings integration
         if statement_config is None:
             cache_config = get_cache_config()
-            enhanced_config = psycopg_statement_config.replace(
+            default_config = psycopg_statement_config.replace(
                 enable_caching=cache_config.compiled_cache_enabled,
-                enable_parsing=True,  # Default to enabled
-                enable_validation=True,  # Default to enabled
-                dialect="postgres",  # Use adapter-specific dialect
+                enable_parsing=True,
+                enable_validation=True,
+                dialect="postgres",
             )
-            statement_config = enhanced_config
+            statement_config = default_config
 
         super().__init__(connection=connection, statement_config=statement_config, driver_features=driver_features)
 
     def with_cursor(self, connection: "PsycopgAsyncConnection") -> "PsycopgAsyncCursor":
-        """Create async context manager for PostgreSQL cursor with enhanced resource management."""
+        """Create async context manager for PostgreSQL cursor."""
         return PsycopgAsyncCursor(connection)
 
     async def begin(self) -> None:
         """Begin a database transaction on the current connection."""
         try:
-            # psycopg3 has explicit transaction support
-            # If already in a transaction, this is a no-op
             if hasattr(self.connection, "autocommit") and not self.connection.autocommit:
-                # Already in manual commit mode, just ensure we're in a clean state
                 pass
             else:
-                # Start manual transaction mode
                 self.connection.autocommit = False
         except Exception as e:
             msg = f"Failed to begin transaction: {e}"
@@ -621,17 +557,15 @@ class PsycopgAsyncDriver(AsyncDriverAdapterBase):
         return PsycopgAsyncExceptionHandler()
 
     async def _handle_transaction_error_cleanup_async(self) -> None:
-        """Handle transaction cleanup after database errors to prevent aborted transaction states (async version)."""
+        """Handle async transaction cleanup after database errors."""
         try:
-            # Check if connection is in a failed transaction state
             if hasattr(self.connection, "info") and hasattr(self.connection.info, "transaction_status"):
                 status = self.connection.info.transaction_status
-                # PostgreSQL transaction statuses: IDLE=0, ACTIVE=1, INTRANS=2, INERROR=3, UNKNOWN=4
+
                 if status == TRANSACTION_STATUS_INERROR:
                     logger.debug("Connection in aborted transaction state, performing async rollback")
                     await self.connection.rollback()
         except Exception as cleanup_error:
-            # If cleanup fails, log but don't raise - the original error is more important
             logger.warning("Failed to cleanup transaction state: %s", cleanup_error)
 
     async def _try_special_handling(self, cursor: Any, statement: "SQL") -> "Optional[SQLResult]":
@@ -644,16 +578,15 @@ class PsycopgAsyncDriver(AsyncDriverAdapterBase):
         Returns:
             SQLResult if special handling was applied, None otherwise
         """
-        # Simple COPY detection - if the SQL starts with COPY and has FROM/TO STDIN/STDOUT
+
         sql_upper = statement.sql.strip().upper()
         if sql_upper.startswith("COPY ") and ("FROM STDIN" in sql_upper or "TO STDOUT" in sql_upper):
             return await self._handle_copy_operation_async(cursor, statement)
 
-        # No special handling needed - proceed with standard execution
         return None
 
     async def _handle_copy_operation_async(self, cursor: Any, statement: "SQL") -> "SQLResult":
-        """Handle PostgreSQL COPY operations using copy_expert (async version).
+        """Handle PostgreSQL COPY operations (async).
 
         Args:
             cursor: Psycopg async cursor object
@@ -662,31 +595,25 @@ class PsycopgAsyncDriver(AsyncDriverAdapterBase):
         Returns:
             SQLResult with COPY operation results
         """
-        # Use the properly rendered SQL from the statement
+
         sql = statement.sql
 
-        # Get COPY data from parameters - handle both direct value and list format
         copy_data = statement.parameters
         if isinstance(copy_data, list) and len(copy_data) == 1:
             copy_data = copy_data[0]
 
-        # Simple string-based direction detection
         sql_upper = sql.upper()
         is_stdin = "FROM STDIN" in sql_upper
         is_stdout = "TO STDOUT" in sql_upper
 
         if is_stdin:
-            # COPY FROM STDIN - import data
             if isinstance(copy_data, (str, bytes)):
                 data_file = io.StringIO(copy_data) if isinstance(copy_data, str) else io.BytesIO(copy_data)
             elif hasattr(copy_data, "read"):
-                # Already a file-like object
                 data_file = copy_data
             else:
-                # Convert to string representation
                 data_file = io.StringIO(str(copy_data))
 
-            # Use async context manager for COPY FROM
             async with cursor.copy(sql) as copy_ctx:
                 data_to_write = data_file.read() if hasattr(data_file, "read") else str(copy_data)  # pyright: ignore
                 if isinstance(data_to_write, str):
@@ -700,7 +627,6 @@ class PsycopgAsyncDriver(AsyncDriverAdapterBase):
             )
 
         if is_stdout:
-            # COPY TO STDOUT - export data
             output_data: list[str] = []
             async with cursor.copy(sql) as copy_ctx:
                 output_data.extend([row.decode() if isinstance(row, bytes) else str(row) async for row in copy_ctx])
@@ -708,13 +634,12 @@ class PsycopgAsyncDriver(AsyncDriverAdapterBase):
             exported_data = "".join(output_data)
 
             return SQLResult(
-                data=[{"copy_output": exported_data}],  # Wrap in list format for consistency
+                data=[{"copy_output": exported_data}],
                 rows_affected=0,
                 statement=statement,
                 metadata={"copy_operation": "TO_STDOUT"},
             )
 
-        # Regular COPY with file - execute normally
         await cursor.execute(sql)
         rows_affected = max(cursor.rowcount, 0)
 
@@ -723,10 +648,14 @@ class PsycopgAsyncDriver(AsyncDriverAdapterBase):
         )
 
     async def _execute_script(self, cursor: Any, statement: "SQL") -> "ExecutionResult":
-        """Execute SQL script using enhanced statement splitting and parameter handling.
+        """Execute SQL script with multiple statements (async).
+
+        Args:
+            cursor: Database cursor
+            statement: SQL statement containing multiple commands
 
-        Uses core module optimization for statement parsing and parameter processing.
-        PostgreSQL supports complex scripts with multiple statements.
+        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)
@@ -735,7 +664,6 @@ class PsycopgAsyncDriver(AsyncDriverAdapterBase):
         last_cursor = cursor
 
         for stmt in statements:
-            # Only pass parameters if they exist - psycopg treats empty containers as parameterized mode
             if prepared_parameters:
                 await cursor.execute(stmt, prepared_parameters)
             else:
@@ -747,42 +675,47 @@ class PsycopgAsyncDriver(AsyncDriverAdapterBase):
         )
 
     async def _execute_many(self, cursor: Any, statement: "SQL") -> "ExecutionResult":
-        """Execute SQL with multiple parameter sets using optimized PostgreSQL async batch processing.
+        """Execute SQL with multiple parameter sets (async).
+
+        Args:
+            cursor: Database cursor
+            statement: SQL statement with parameter list
 
-        Leverages core parameter processing for enhanced PostgreSQL type handling.
+        Returns:
+            ExecutionResult with batch execution details
         """
         sql, prepared_parameters = self._get_compiled_sql(statement, self.statement_config)
 
-        # Handle empty parameter list case
         if not prepared_parameters:
-            # For empty parameter list, return a result with no rows affected
             return self.create_execution_result(cursor, rowcount_override=0, is_many_result=True)
 
         await cursor.executemany(sql, prepared_parameters)
 
-        # PostgreSQL cursor.rowcount gives total affected rows
         affected_rows = cursor.rowcount if cursor.rowcount and cursor.rowcount > 0 else 0
 
         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 enhanced PostgreSQL async data handling and performance optimization.
+        """Execute single SQL statement (async).
 
-        Uses core processing for optimal parameter handling and PostgreSQL result processing.
+        Args:
+            cursor: Database cursor
+            statement: SQL statement to execute
+
+        Returns:
+            ExecutionResult with statement execution details
         """
         sql, prepared_parameters = self._get_compiled_sql(statement, self.statement_config)
-        # Only pass parameters if they exist - psycopg treats empty containers as parameterized mode
+
         if prepared_parameters:
             await cursor.execute(sql, prepared_parameters)
         else:
             await cursor.execute(sql)
 
-        # Enhanced SELECT result processing for PostgreSQL
         if statement.returns_rows():
             fetched_data = await cursor.fetchall()
             column_names = [col.name for col in cursor.description or []]
 
-            # PostgreSQL returns raw data - pass it directly like the old driver
             return self.create_execution_result(
                 cursor,
                 selected_data=fetched_data,
@@ -791,6 +724,5 @@ class PsycopgAsyncDriver(AsyncDriverAdapterBase):
                 is_select_result=True,
             )
 
-        # Enhanced non-SELECT result processing for PostgreSQL
         affected_rows = cursor.rowcount if cursor.rowcount and cursor.rowcount > 0 else 0
         return self.create_execution_result(cursor, rowcount_override=affected_rows)