refactor(driver): extract qc_prepare to consolidate sync/async duplication

Move eligibility checks and preparation logic from qc_lookup into new
qc_prepare method in _common.py. This eliminates ~15 lines of duplicated
logic between sync and async implementations.

Before: qc_lookup in both _common.py and _async.py contained identical
eligibility checking, cache lookup, rebinding, and statement building.

After: qc_prepare does all preparation work, qc_lookup becomes a thin
wrapper that calls qc_prepare then qc_execute.

Chapter 3 of driver-arch-cleanup_20260203 PRD.

Author: cofin

sqlspec/driver/_async.py

@@ -305,26 +305,19 @@ async def dispatch_special_handling(self, cursor: Any, statement: "SQL") -> "SQL
     async def qc_lookup(
         self, statement: str, params: "tuple[Any, ...] | list[Any]"
     ) -> "SQLResult | None":
-        if not self._qc_enabled:
-            return None
-        if self.statement_config.parameter_config.needs_static_script_compilation:
-            return None
-        cached = self._qc.get(statement)
-        if cached is None:
-            return None
-        if cached.param_count != len(params):
-            return None
-        if isinstance(params, list) and params and isinstance(params[0], (tuple, list, dict)) and len(params) > 1:
-            return None
+        """Attempt fast-path execution for cached query (async).
 
-        rebound_params = self.qc_rebind(params, cached)
-        compiled_sql = cached.compiled_sql
-        output_transformer = self.statement_config.output_transformer
-        if output_transformer:
-            compiled_sql, rebound_params = output_transformer(compiled_sql, rebound_params)
+        Args:
+            statement: Raw SQL string.
+            params: Query parameters.
 
-        fast_statement = self.qc_build(statement, params, cached, rebound_params)
-        return await self.qc_execute(fast_statement, compiled_sql, rebound_params)
+        Returns:
+            SQLResult if cache hit and execution succeeds, None otherwise.
+        """
+        prep = self.qc_prepare(statement, params)
+        if prep is None:
+            return None
+        return await self.qc_execute(*prep)
 
     async def qc_execute(self, statement: "SQL", sql: str, params: Any) -> "SQLResult":
         _ = (sql, params)

sqlspec/driver/_common.py

@@ -1002,13 +1002,24 @@ def qc_build(
         )
         return statement
 
-    def qc_lookup(
+    def qc_prepare(
         self, statement: str, params: "tuple[Any, ...] | list[Any]"
-    ) -> "SQLResult | None":
+    ) -> "tuple[SQL, str, Any] | None":
+        """Prepare fast-path execution if cache hit.
+
+        Args:
+            statement: Raw SQL string.
+            params: Query parameters (tuple or list).
+
+        Returns:
+            Tuple of (SQL object, compiled SQL, bound params) if cache hit,
+            None if cache miss or ineligible.
+        """
         if not self._qc_enabled:
             return None
         if self.statement_config.parameter_config.needs_static_script_compilation:
             return None
+
         cached = self._qc.get(statement)
         if cached is None:
             return None
@@ -1019,12 +1030,30 @@ def qc_lookup(
 
         rebound_params = self.qc_rebind(params, cached)
         compiled_sql = cached.compiled_sql
+
         output_transformer = self.statement_config.output_transformer
         if output_transformer:
             compiled_sql, rebound_params = output_transformer(compiled_sql, rebound_params)
 
         fast_statement = self.qc_build(statement, params, cached, rebound_params)
-        return cast("SQLResult", self.qc_execute(fast_statement, compiled_sql, rebound_params))
+        return fast_statement, compiled_sql, rebound_params
+
+    def qc_lookup(
+        self, statement: str, params: "tuple[Any, ...] | list[Any]"
+    ) -> "SQLResult | None":
+        """Attempt fast-path execution for cached query.
+
+        Args:
+            statement: Raw SQL string.
+            params: Query parameters.
+
+        Returns:
+            SQLResult if cache hit and execution succeeds, None otherwise.
+        """
+        prep = self.qc_prepare(statement, params)
+        if prep is None:
+            return None
+        return cast("SQLResult", self.qc_execute(*prep))
 
     def qc_execute(self, statement: "SQL", sql: str, params: Any) -> "SQLResult | Awaitable[SQLResult]":
         raise NotImplementedError