fix(python): Guard against dictionaries being passed to projection keywords

py-polars/polars/_utils/parse/expr.py

@@ -1,7 +1,7 @@
 from __future__ import annotations
 
 import contextlib
-from collections.abc import Iterable
+from collections.abc import Iterable, Mapping
 from typing import TYPE_CHECKING, Any
 
 import polars._reexport as pl
@@ -120,6 +120,18 @@ def _parse_inputs_as_iterable(
     if not inputs:
         return []
 
+    # Ensures that the outermost element cannot be a Dictionary (as an iterable)
+    if len(inputs) == 1 and isinstance(inputs[0], Mapping):
+        msg = (
+            "Cannot pass a dictionary as a single positional argument.\n"
+            "If you merely want the *keys*, use:\n"
+            "  • df.method(*your_dict.keys())\n"
+            "If you need the key value pairs, use one of:\n"
+            "  • unpack as keywords:    df.method(**your_dict)\n"
+            "  • build expressions:     df.method(expr.alias(k) for k, expr in your_dict.items())"
+        )
+        raise TypeError(msg)
+
     # Treat elements of a single iterable as separate inputs
     if len(inputs) == 1 and _is_iterable(inputs[0]):
         return inputs[0]

py-polars/tests/unit/dataframe/test_df.py

@@ -3224,3 +3224,29 @@ def test_nan_to_null() -> None:
     )
 
     assert_frame_equal(df1, df2)
+
+
+# Below 3 tests for https://github.com/pola-rs/polars/issues/17879
+
+
+def test_with_columns_dict_direct_typeerror() -> None:
+    data = {"a": pl.col("a") * 2}
+    df = pl.select(a=1)
+    with pytest.raises(
+        TypeError, match="Cannot pass a dictionary as a single positional argument"
+    ):
+        df.with_columns(data)
+
+
+def test_with_columns_dict_unpacking() -> None:
+    data = {"a": pl.col("a") * 2}
+    df = pl.select(a=1).with_columns(**data)
+    expected = pl.DataFrame({"a": [2]})
+    assert df.equals(expected)
+
+
+def test_with_columns_generator_alias() -> None:
+    data = {"a": pl.col("a") * 2}
+    df = pl.select(a=1).with_columns(expr.alias(name) for name, expr in data.items())
+    expected = pl.DataFrame({"a": [2]})
+    assert df.equals(expected)

py-polars/tests/unit/test_projections.py

@@ -356,7 +356,7 @@ def test_projection_join_names_9955() -> None:
         how="inner",
     )
 
-    q = q.select(batting.collect_schema())
+    q = q.select(*batting.collect_schema().keys())
 
     assert q.collect().schema == {
         "playerID": pl.String,