From c358e37ce2360e21ffd121fb5ef52a0adca88752 Mon Sep 17 00:00:00 2001
From: prql-bot <107324867+prql-bot@users.noreply.github.com>
Date: Thu, 2 Jul 2026 07:42:20 +0000
Subject: [PATCH] fix: sync prqlc Python type stub with binding signatures

The .pyi stub drifted from the actual PyO3 signatures since #4333:
- rq_to_sql accepts an optional CompileOptions, but the stub declared
  only rq_to_sql(rq_json: str)
- CompileOptions.__init__ accepts color and display kwargs, absent from
  the stub

ty (run in CI via nox) checks user/test code against these stubs, so
passing options to rq_to_sql or color/display to CompileOptions was
flagged as a type error despite working at runtime.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 .../prqlc-python/python/prqlc/__init__.pyi    |  6 +++--
 .../prqlc-python/python/tests/test_all.py     | 22 +++++++++++++++++++
 2 files changed, 26 insertions(+), 2 deletions(-)

diff --git a/prqlc/bindings/prqlc-python/python/prqlc/__init__.pyi b/prqlc/bindings/prqlc-python/python/prqlc/__init__.pyi
index 191f50b721cc..0a9d6e3502c6 100644
--- a/prqlc/bindings/prqlc-python/python/prqlc/__init__.pyi
+++ b/prqlc/bindings/prqlc-python/python/prqlc/__init__.pyi
@@ -5,15 +5,17 @@ class CompileOptions:
         self,
         *,
         format: bool = True,
-        target: str = "sql.any",
         signature_comment: bool = True,
+        target: str = "sql.any",
+        color: bool = False,
+        display: str = "plain",
     ) -> None: ...
 
 def compile(prql_query: str, options: Optional[CompileOptions] = None) -> str: ...
 def prql_to_pl(prql_query: str) -> str: ...
 def pl_to_rq(pl_json: str) -> str: ...
 def pl_to_prql(pl_json: str) -> str: ...
-def rq_to_sql(rq_json: str) -> str: ...
+def rq_to_sql(rq_json: str, options: Optional[CompileOptions] = None) -> str: ...
 def get_targets() -> List[str]: ...
 
 __version__: str
diff --git a/prqlc/bindings/prqlc-python/python/tests/test_all.py b/prqlc/bindings/prqlc-python/python/tests/test_all.py
index bcd814438c9e..c169417d5dc8 100644
--- a/prqlc/bindings/prqlc-python/python/tests/test_all.py
+++ b/prqlc/bindings/prqlc-python/python/tests/test_all.py
@@ -84,6 +84,28 @@ def test_compile_options() -> None:
     )
 
 
+def test_rq_to_sql_options() -> None:
+    """
+    `rq_to_sql` accepts an optional `CompileOptions`, and `CompileOptions`
+    accepts `color` and `display`. These calls exercise the full public
+    signatures so the type stub stays in sync with the binding (checked by
+    `ty` in CI).
+    """
+    rq = prqlc.pl_to_rq(prqlc.prql_to_pl("from employees | take 3"))
+
+    options = prqlc.CompileOptions(
+        format=False,
+        signature_comment=False,
+        target="sql.sqlite",
+        color=False,
+        display="plain",
+    )
+    assert prqlc.rq_to_sql(rq, options) == "SELECT * FROM employees LIMIT 3"
+
+    # `options` is optional and defaults to None.
+    assert prqlc.rq_to_sql(rq)
+
+
 def test_debug_functions() -> None:
     prql_query = "from invoices | select { id, customer_id }"