`StarExpression` has incorrect typing

[m15a]

What happens?

Another issue for type check.
According to the documentation, StarExpression accepts a list (not clearly stated though) as its parameter. However, the stub has the signature (line 1021 in _duckdb-stubs/__init__.pyi, the main branch)

def StarExpression(*, exclude: Expression | str | tuple[str]) -> Expression: ...

To Reproduce

In example.py:

import duckdb
import pandas as pd

df = pd.DataFrame({
    "a": [1, 2, 3, 4],
    "b": [True, None, False, True],
    "c": [42, 21, 13, 14]
})

star = duckdb.StarExpression(exclude = ['b'])
duckdb.df(df).select(star).show()

Then, run any type checker:

❯ uv run ty check example.py
error[invalid-argument-type]: Argument to function `StarExpression` is incorrect
  --> example.py:10:30
   |
 8 | })
 9 |
10 | star = duckdb.StarExpression(exclude = ['b'])
   |                              ^^^^^^^^^^^^^^^ Expected `Expression | str | tuple[str]`, found `list[Unknown | str]`
11 | duckdb.df(df).select(star).show()
   |
info: Matching overload defined here
    --> .venv/lib/python3.13/site-packages/_duckdb-stubs/__init__.pyi:1041:5
     |
1039 | def SQLExpression(expression: str) -> Expression: ...
1040 | @pytyping.overload
1041 | def StarExpression(*, exclude: Expression | str | tuple[str]) -> Expression: ...
     |     ^^^^^^^^^^^^^^    -------------------------------------- Parameter declared here
1042 | @pytyping.overload
1043 | def StarExpression() -> Expression: ...
     |
info: Non-matching overloads for function `StarExpression`:
info:   () -> Expression
info: rule `invalid-argument-type` is enabled by default

Found 1 diagnostic

OS:

aarch64_darwin

DuckDB Package Version:

1.4.2

Python Version:

3.13.9

Full Name:

Mitsuhiro Nacamura

Affiliation:

Nacamura Data Analysis

What is the latest build you tested with? If possible, we recommend testing with the latest nightly build.

I have tested with a stable release

Did you include all relevant data sets for reproducing the issue?

Yes

Did you include all code required to reproduce the issue?

• Yes, I have

Did you include all relevant configuration to reproduce the issue?

• Yes, I have

[OutSquareCapital]

now the type hint is Any. Type checkers won't complain but it's now useful for type safety, and anyway the documentation is incorrect in the sense that it should say an Iterable rather than a list.
Any non-Iterable argument will indeed be rejected.

From my understanding, the correct type should then be Iterable[str | Expression]

See below:

Code

from collections.abc import Sequence

import duckdb
import pyochain as pc


def _try_star(arg: object) -> None:
    def _name() -> str:
        repr = f"{type(arg).__name__}"
        if isinstance(arg, Sequence):
            repr += f"[{type(arg[0]).__name__}]"
        return f"*{repr}*"

    try:
        res = duckdb.StarExpression(exclude=arg)
        return print(f"- **Ok** with arg {_name()}: `{res}`")
    except Exception as e:
        return print(f"- **Error** with arg {_name()}: `{e}`")


def main() -> None:

    data = ["foo", "bar", "baz"]
    col_args = (duckdb.ColumnExpression(str(x)) for x in data)
    # custom object, Iterator protocol implemented.
    abc_arg = pc.Iter(data)

    col = duckdb.ColumnExpression("foo")
    _try_star(data)
    _try_star(col_args)
    _try_star(abc_arg)
    _try_star(6)
    _try_star([6])
    _try_star("x")
    _try_star([col])
    _try_star(col)


if __name__ == "__main__":
    main()

ouput

• Ok with arg list[str]: * EXCLUDE (foo, bar, baz)
• Ok with arg generator: * EXCLUDE (foo, bar, baz)
• Ok with arg Iter: * EXCLUDE (foo, bar, baz)
• Error with arg int: 'int' object is not iterable
• Error with arg list[int]: Only ColumnExpressions are accepted Expression types here
• Ok with arg str[str]: * EXCLUDE (x)
• Ok with arg list[Expression]: * EXCLUDE (foo)
• Error with arg Expression: '_duckdb.Expression' object is not iterable

[evertlammerts]

Fixed in #323.

[OutSquareCapital]

Same observation as I made in #209, list is too narrow.