StarExpression has incorrect typing

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

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

Fixed in #323.

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

Fix multiple stub issues (#323)

Navigation Menu

Repository navigation

`StarExpression` has incorrect typing #210

What happens?

To Reproduce

OS:

DuckDB Package Version:

Python Version:

Full Name:

Affiliation:

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

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

Did you include all code required to reproduce the issue?

Did you include all relevant configuration to reproduce the issue?

Code

ouput

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

StarExpression has incorrect typing #210

Description

What happens?

To Reproduce

OS:

DuckDB Package Version:

Python Version:

Full Name:

Affiliation:

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

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

Did you include all code required to reproduce the issue?

Did you include all relevant configuration to reproduce the issue?

Activity

OutSquareCapital commented on Feb 12, 2026

Code

ouput

evertlammerts commented on Feb 17, 2026

OutSquareCapital commented on Feb 17, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions

`StarExpression` has incorrect typing #210