feat: Allow expressions as group_by keys

[FBruzzesi]

What type of PR is this? (check all applicable)

• 💾 Refactor
• ✨ Feature
• 🐛 Bug Fix
• 🔧 Optimization
• 📝 Documentation
• ✅ Test
• 🐳 Other

Related issues

• Closes [Enh]: Ability to use nw.col / Expr for .group_by #1385
• api: formalise expression expansion in group-by #2225 (comment)
• api: formalise expression expansion in group-by #2225 (comment)

Checklist

• Code follows style guide (ruff)
• Tests added
• Documented the changes

If you have comments or can explain your changes, please do so below

@MarcoGorelli there is one test failing - which is grouping by a pandas column with a boolean name (and similarly with integer name in scikit-lego)

@dangotbanned I am crying for help with the typing 🙈

Other comment will address in the code itself

[dangotbanned]

https://github.com/narwhals-dev/narwhals/actions/runs/14204180755/job/39797880528?pr=2325

@dangotbanned I am crying for help with the typing 🙈

@FBruzzesi 😂 I'll try taking a look soon

Update

Ah the issue is PolarsExpr isn't compliant

[dangotbanned]

#2325 (comment)

@FBruzzesi for polars (only) just add an Incomplete in places where you need to use CompliantExpr.

narwhals/narwhals/_polars/namespace.py

Lines 54 to 55 in 4d2b9d5

	# NOTE: `PolarsSeries`, `PolarsExpr` still have gaps
	when: Method[CompliantWhen[PolarsDataFrame, Incomplete, Incomplete]]

PolarsSeries and PolarsExpr are almost entirely defined using __getattr__ - which isn't enough to satisfy typing.

They essentially need something like this, but I've been putting off doing it since they have waaaaaay more methods 😔

narwhals/narwhals/_polars/dataframe.py

Lines 59 to 85 in 4d2b9d5

	class PolarsDataFrame:
	clone: Method[Self]
	collect: Method[CompliantDataFrame[Any, Any, Any]]
	drop_nulls: Method[Self]
	estimated_size: Method[int | float]
	explode: Method[Self]
	filter: Method[Self]
	gather_every: Method[Self]
	item: Method[Any]
	iter_rows: Method[Iterator[tuple[Any, ...]] | Iterator[Mapping[str, Any]]]
	is_unique: Method[PolarsSeries]
	join_asof: Method[Self]
	rename: Method[Self]
	row: Method[tuple[Any, ...]]
	rows: Method[Sequence[tuple[Any, ...]] | Sequence[Mapping[str, Any]]]
	sample: Method[Self]
	select: Method[Self]
	sort: Method[Self]
	to_arrow: Method[pa.Table]
	to_numpy: Method[_2DArray]
	to_pandas: Method[pd.DataFrame]
	unique: Method[Self]
	with_columns: Method[Self]
	# NOTE: `write_csv` requires an `@overload` for `str | None`
	# Can't do that here 😟
	write_csv: Method[Any]
	write_parquet: Method[None]

[dangotbanned]

#2325 (comment)

😨

[dangotbanned]

Great work @FBruzzesi 🎉

I've left some comments/suggestions, but nothing blocking.

This is an exciting step towards expressifying more of narwhals 🚀

[FBruzzesi]

Great work @FBruzzesi 🎉

I've left some comments/suggestions, but nothing blocking.

Thanks @dangotbanned - I am a bit short on time this week and the next - so apologies for my slow feedback loop.
I should have addressed all your comments/suggestion 😎

This is an exciting step towards expressifying more of narwhals 🚀

It definitly is - exciting times!

[dangotbanned]

#2325 (comment)

Thanks again @FBruzzesi

I'll leave open until the end of the day in case @MarcoGorelli wants time chime in - but otherwise I'll merge later ❤️

[MarcoGorelli]

thanks both, really amazing stuff!

i'll just trying breaking this a bit more, then i'd say we can ship it

[dangotbanned]

thanks both, really amazing stuff!

i'll just trying breaking this a bit more, then i'd say we can ship it

@MarcoGorelli wanted to check in to see if you were okay with me merging?

No worries at all if not!
I'm happy with holding off (#2325 (review)) if you still wanna strees-test some more 😅

[MarcoGorelli]

I reverted a change to an existing test - in general i'd suggest to just add a new test if you're testing something different

For anything this close to the library core and to expression parsing, please do wait for me to take a final look

Anyway, this looks great, thanks @FBruzzesi and @dangotbanned ! You have a lot to be proud of here. I'm certainly proud that all together we've arrived at such a simple-looking solution

type checking does pass in CI, but there is the occasional squiggly line in vscode. happy to resolve that separately though

[dangotbanned]

@MarcoGorelli would we be able to set up something to preserve co-authors?

I think I'm missing again 😔
8944823

[MarcoGorelli]

ah so sorry 😩 😳

the combination of 124 commit messages was too long so i removed the whole thing, but it looks like i should've kept the "co-authored by" part at the end for co-authors to show up

I'll be very careful to always do that in the future 👍