Skip to content

fix: sync prqlc Python type stub with binding signatures#6058

Open
prql-bot wants to merge 1 commit into
mainfrom
fix/python-stub-signatures
Open

fix: sync prqlc Python type stub with binding signatures#6058
prql-bot wants to merge 1 commit into
mainfrom
fix/python-stub-signatures

Conversation

@prql-bot

@prql-bot prql-bot commented Jul 2, 2026

Copy link
Copy Markdown
Collaborator

Problem

Found during the nightly survey. The Python type stub prqlc/bindings/prqlc-python/python/prqlc/__init__.pyi has drifted from the actual PyO3 binding signatures since #4333 ("Add display option to compile, allow specifying colors"):

  • rq_to_sql accepts an optional CompileOptions in the binding (pub fn rq_to_sql(rq_json: &str, options: Option<CompileOptions>)), but the stub declared only rq_to_sql(rq_json: str) -> str.
  • CompileOptions.__init__ accepts color and display keyword arguments (the PyO3 #[new] signature is (*, format, signature_comment, target, color, display)), but the stub listed only format, target, signature_comment.

This repo runs ty check in CI (via the typing nox session in test-python.yaml), which validates user and test code against these stubs. So prqlc.rq_to_sql(rq, options) or prqlc.CompileOptions(color=..., display=...) — both valid at runtime — were flagged as type errors against the stale stub.

Solution

Update the stub to match the binding:

  • rq_to_sql(rq_json: str, options: Optional[CompileOptions] = None) -> str
  • add color: bool = False and display: str = "plain" to CompileOptions.__init__ (keyword-only, ordered to match the Rust #[new] signature)

Testing

Added test_rq_to_sql_options to test_all.py, which calls rq_to_sql with a CompileOptions (constructed with color/display) and asserts the SQL output. This exercises the full public signatures, so ty check fails against the old stub and passes against the fixed one.

Verified locally by building the wheel (maturin build) and running the suite:

  • With the pre-fix stub, ty check reports 3 diagnostics (too-many-positional-arguments on rq_to_sql, plus unexpected-kwarg errors on CompileOptions).
  • With the fix, both pytest (4 passed) and ty check ("All checks passed!") are green.

Note for maintainers

convert_options in prqlc/bindings/prqlc-python/src/lib.rs currently hardcodes color: false, ignoring the color field the constructor accepts. This PR only surfaces the parameter in the stub to match the constructor — it doesn't change that behavior. If color is meant to be non-functional in the Python binding, dropping it from the constructor (rather than the stub) would be the alternative; that's a maintainer call, so I left the behavior untouched here.


Found via the automated nightly code-quality survey.

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>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant