`DuckDBPyRelation.aggregate` has incorrect typing

[m15a]

What happens?

According to the documentation, DuckDBPyRelation.aggregate() accepts str or list[Expression] as the aggr_expr parameter. However, the stub has the signature (line 453 in _duckdb-stubs/__init__.pyi, the main branch)

def aggregate(self, aggr_expr: Expression | str, group_expr: Expression | str = "") -> DuckDBPyRelation

To Reproduce

For example, type checking the following code fails (duckdb 1.4.2). In example.py:

import duckdb as dd
import pandas as pd
from duckdb import ColumnExpression as col
from duckdb import FunctionExpression as fn

cats = dd.from_df(pd.DataFrame({"family": [1, 1], "name": ["nyan", "meow"]}))
dogs = dd.from_df(pd.DataFrame({"family": [1, 2], "name": ["woof", "wan"]}))

print(
    cats.union(dogs)
    .aggregate(
        [
            col("family"),
            fn("list", col("name")).alias("names"),
        ],
        "family",
    )
)

❯ uv run ty check example.py
error[invalid-argument-type]: Argument to bound method `aggregate` is incorrect
  --> example.py:12:9
   |
10 |       cats.union(dogs)
11 |       .aggregate(
12 | /         [
13 | |             col("family"),
14 | |             fn("list", col("name")).alias("names"),
15 | |         ],
   | |_________^ Expected `Expression | str`, found `list[Unknown | Expression]`
16 |           "family",
17 |       )
   |
info: Method defined here
   --> .venv/lib/python3.13/site-packages/_duckdb-stubs/__init__.pyi:464:9
    |
462 |     def __getitem__(self, name: str) -> DuckDBPyRelation: ...
463 |     def __len__(self) -> int: ...
464 |     def aggregate(self, aggr_expr: Expression | str, group_expr: Expression | str = "") -> DuckDBPyRelation: ...
    |         ^^^^^^^^^       --------------------------- Parameter declared here
465 |     def any_value(
466 |         self, column: str, groups: str = "", window_spec: str = "", projected_columns: str = ""
    |
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