[cathleeny]

What type of PR is this?

• Bug Fix

Description

Why: Since 4.0.4 (#559), inline parameters (use_inline_params=True) render every Python sequence as an ARRAY(...) literal. The WHERE x IN %(ids)s pattern documented in docs/parameters.md therefore renders as x IN ARRAY(1,2,3), which Spark rejects with PARSE_SYNTAX_ERROR, and that blocks users moving from 3.x.

Change: A sequence whose marker directly follows IN or NOT IN renders as a parenthesised list, (1,2,3), again. Everywhere else it stays an ARRAY(...) literal, including IN (%(p)s) where the caller wrote the parentheses. That keeps the inline writes to ARRAY columns added in #559 working. Because x IN ARRAY(...) never parses, no query that runs today renders differently.

To find which markers follow IN, the operation is formatted once with placeholder values through the same % formatting that inject_parameters uses. That keeps positional markers and %% aligned with the real substitution, and malformed operations raise the same errors as before. docs/parameters.md now notes that the marker must directly follow IN.

Scope notes:

• Rendering happens in Cursor._prepare_inline_parameters before backend dispatch, so the fix covers the Thrift, SEA and kernel backends. The kernel receives the already-rendered SQL and does no SQL-text interpolation of its own.
• Unchanged:
  • An empty sequence still renders IN (). Spark rejects that (PARSE_SYNTAX_ERROR, or INVALID_SQL_SYNTAX.EMPTY_IN_PREDICATE since SPARK-54634), the same as on 3.x.
  • Nested sequences inside an IN list stay ARRAY literals, so multi-column (a, b) IN %s with a list of tuples is not restored to its 3.x rendering.
  • A marker separated from IN by a comment, and positional queries that also use %d-style markers, keep the ARRAY rendering.
• An earlier community PR (Fix inline list parameter rendering for IN clauses #773) rendered every top-level sequence as (...). That would break the inline ARRAY inserts covered by test_primitive_single[INLINE-ARRAYS] and test_inline_recursive_complex_type, so this change only targets the IN position.

How is this tested?

• Unit tests

• E2E Tests

• Manually

• Unit:

  • TestInClauseSequenceRendering covers named and positional markers, NOT IN, escaped strings, nested sequences, %%, and a lowercase in followed by a newline. It also pins ARRAY rendering for INSERT ... VALUES, function arguments and IN (%(p)s), and checks that a malformed operation still raises the same TypeError.
  • test_execute_inline_sequence_after_in_renders_as_list goes through Cursor.execute. It failed on main with IN ARRAY(1,2,3).
  • The full unit suite passes (1278 tests), and black and mypy are clean on src.

• E2E: test_inline_sequence_in_clause covers named, positional and NOT IN cases against range(5). I have not run it locally because it needs warehouse credentials.

• Manual: On a Databricks SQL warehouse, the SQL these cases render to returned the expected rows, and 2 IN ARRAY(1,2,3) failed with PARSE_SYNTAX_ERROR.

Related Tickets & Documents

Fixes #629
ES-2336977

This pull request and its description were written by Isaac.