chore: Rename call_kwargs to scalar_kwargs (#2555)

MarcoGorelli · dangotbanned · web-flow · commit ff493ff33fe8 · 2025-05-18T10:31:39.000+01:00
---------

Co-authored-by: Dan Redding &lt;125183946+dangotbanned@users.noreply.github.com&gt;
diff --git a/narwhals/_arrow/expr.py b/narwhals/_arrow/expr.py
@@ -22,6 +22,7 @@
     from narwhals._compliant.typing import AliasNames
     from narwhals._compliant.typing import EvalNames
     from narwhals._compliant.typing import EvalSeries
+    from narwhals._compliant.typing import ScalarKwargs
     from narwhals._expression_parsing import ExprMetadata
     from narwhals.typing import RankMethod
     from narwhals.utils import Version
@@ -41,7 +42,7 @@ def __init__(
         alias_output_names: AliasNames | None,
         backend_version: tuple[int, ...],
         version: Version,
-        call_kwargs: dict[str, Any] | None = None,
+        scalar_kwargs: ScalarKwargs | None = None,
         implementation: Implementation | None = None,
     ) -> None:
         self._call = call
@@ -52,7 +53,7 @@ def __init__(
         self._alias_output_names = alias_output_names
         self._backend_version = backend_version
         self._version = version
-        self._call_kwargs = call_kwargs or {}
+        self._scalar_kwargs = scalar_kwargs or {}
         self._metadata: ExprMetadata | None = None
 
     @classmethod
diff --git a/narwhals/_arrow/group_by.py b/narwhals/_arrow/group_by.py
@@ -85,7 +85,8 @@ def agg(self, *exprs: ArrowExpr) -> ArrowDataFrame:
 
             function_name = self._leaf_name(expr)
             if function_name in {"std", "var"}:
-                option: Any = pc.VarianceOptions(ddof=expr._call_kwargs["ddof"])
+                assert "ddof" in expr._scalar_kwargs  # noqa: S101
+                option: Any = pc.VarianceOptions(ddof=expr._scalar_kwargs["ddof"])
             elif function_name in {"len", "n_unique"}:
                 option = pc.CountOptions(mode="all")
             elif function_name == "count":
diff --git a/narwhals/_compliant/expr.py b/narwhals/_compliant/expr.py
@@ -59,6 +59,7 @@
     from narwhals._compliant.typing import AliasNames
     from narwhals._compliant.typing import EvalNames
     from narwhals._compliant.typing import EvalSeries
+    from narwhals._compliant.typing import ScalarKwargs
     from narwhals._expression_parsing import ExprKind
     from narwhals._expression_parsing import ExprMetadata
     from narwhals.dtypes import DType
@@ -342,7 +343,7 @@ class EagerExpr(
     Protocol38[EagerDataFrameT, EagerSeriesT],
 ):
     _call: EvalSeries[EagerDataFrameT, EagerSeriesT]
-    _call_kwargs: dict[str, Any]
+    _scalar_kwargs: ScalarKwargs
 
     def __init__(
         self,
@@ -355,7 +356,7 @@ def __init__(
         implementation: Implementation,
         backend_version: tuple[int, ...],
         version: Version,
-        call_kwargs: dict[str, Any] | None = None,
+        scalar_kwargs: ScalarKwargs | None = None,
     ) -> None: ...
 
     def __call__(self, df: EagerDataFrameT) -> Sequence[EagerSeriesT]:
@@ -376,7 +377,7 @@ def _from_callable(
         evaluate_output_names: EvalNames[EagerDataFrameT],
         alias_output_names: AliasNames | None,
         context: _FullContext,
-        call_kwargs: dict[str, Any] | None = None,
+        scalar_kwargs: ScalarKwargs | None = None,
     ) -> Self:
         return cls(
             func,
@@ -387,7 +388,7 @@ def _from_callable(
             implementation=context._implementation,
             backend_version=context._backend_version,
             version=context._version,
-            call_kwargs=call_kwargs,
+            scalar_kwargs=scalar_kwargs,
         )
 
     @classmethod
@@ -408,7 +409,7 @@ def _reuse_series(
         method_name: str,
         *,
         returns_scalar: bool = False,
-        call_kwargs: dict[str, Any] | None = None,
+        scalar_kwargs: ScalarKwargs | None = None,
         **expressifiable_args: Any,
     ) -> Self:
         """Reuse Series implementation for expression.
@@ -420,7 +421,7 @@ def _reuse_series(
             method_name: name of method.
             returns_scalar: whether the Series version returns a scalar. In this case,
                 the expression version should return a 1-row Series.
-            call_kwargs: non-expressifiable args which we may need to reuse in `agg` or `over`,
+            scalar_kwargs: non-expressifiable args which we may need to reuse in `agg` or `over`,
                 such as `ddof` for `std` and `var`.
             expressifiable_args: keyword arguments to pass to function, which may
                 be expressifiable (e.g. `nw.col('a').is_between(3, nw.col('b')))`).
@@ -429,7 +430,7 @@ def _reuse_series(
             self._reuse_series_inner,
             method_name=method_name,
             returns_scalar=returns_scalar,
-            call_kwargs=call_kwargs or {},
+            scalar_kwargs=scalar_kwargs or {},
             expressifiable_args=expressifiable_args,
         )
         return self._from_callable(
@@ -438,7 +439,7 @@ def _reuse_series(
             function_name=f"{self._function_name}->{method_name}",
             evaluate_output_names=self._evaluate_output_names,
             alias_output_names=self._alias_output_names,
-            call_kwargs=call_kwargs,
+            scalar_kwargs=scalar_kwargs,
             context=self,
         )
 
@@ -459,11 +460,11 @@ def _reuse_series_inner(
         *,
         method_name: str,
         returns_scalar: bool,
-        call_kwargs: dict[str, Any],
+        scalar_kwargs: ScalarKwargs,
         expressifiable_args: dict[str, Any],
     ) -> Sequence[EagerSeriesT]:
         kwargs = {
-            **call_kwargs,
+            **scalar_kwargs,
             **{
                 name: df._evaluate_expr(value) if self._is_expr(value) else value
                 for name, value in expressifiable_args.items()
@@ -513,7 +514,7 @@ def _reuse_series_namespace(
             function_name=f"{self._function_name}->{series_namespace}.{method_name}",
             evaluate_output_names=self._evaluate_output_names,
             alias_output_names=self._alias_output_names,
-            call_kwargs=self._call_kwargs,
+            scalar_kwargs=self._scalar_kwargs,
             context=self,
         )
 
@@ -537,7 +538,7 @@ def func(df: EagerDataFrameT) -> list[EagerSeriesT]:
             backend_version=self._backend_version,
             implementation=self._implementation,
             version=self._version,
-            call_kwargs=self._call_kwargs,
+            scalar_kwargs=self._scalar_kwargs,
         )
 
     def cast(self, dtype: DType | type[DType]) -> Self:
@@ -627,10 +628,14 @@ def median(self) -> Self:
         return self._reuse_series("median", returns_scalar=True)
 
     def std(self, *, ddof: int) -> Self:
-        return self._reuse_series("std", returns_scalar=True, call_kwargs={"ddof": ddof})
+        return self._reuse_series(
+            "std", returns_scalar=True, scalar_kwargs={"ddof": ddof}
+        )
 
     def var(self, *, ddof: int) -> Self:
-        return self._reuse_series("var", returns_scalar=True, call_kwargs={"ddof": ddof})
+        return self._reuse_series(
+            "var", returns_scalar=True, scalar_kwargs={"ddof": ddof}
+        )
 
     def skew(self) -> Self:
         return self._reuse_series("skew", returns_scalar=True)
@@ -747,7 +752,7 @@ def alias_output_names(names: Sequence[str]) -> Sequence[str]:
             backend_version=self._backend_version,
             implementation=self._implementation,
             version=self._version,
-            call_kwargs=self._call_kwargs,
+            scalar_kwargs=self._scalar_kwargs,
         )
 
     def is_unique(self) -> Self:
@@ -1087,7 +1092,7 @@ def _from_callable(self, func: AliasName, /, *, alias: bool = True) -> EagerExpr
             backend_version=expr._backend_version,
             implementation=expr._implementation,
             version=expr._version,
-            call_kwargs=expr._call_kwargs,
+            scalar_kwargs=expr._scalar_kwargs,
         )
 
 
diff --git a/narwhals/_compliant/selectors.py b/narwhals/_compliant/selectors.py
@@ -5,7 +5,6 @@
 import re
 from functools import partial
 from typing import TYPE_CHECKING
-from typing import Any
 from typing import Collection
 from typing import Iterable
 from typing import Iterator
@@ -49,6 +48,7 @@
     from narwhals._compliant.typing import CompliantSeriesOrNativeExprAny
     from narwhals._compliant.typing import EvalNames
     from narwhals._compliant.typing import EvalSeries
+    from narwhals._compliant.typing import ScalarKwargs
     from narwhals.dtypes import DType
     from narwhals.typing import TimeUnit
     from narwhals.utils import Implementation
@@ -226,7 +226,7 @@ class CompliantSelector(
     _implementation: Implementation
     _backend_version: tuple[int, ...]
     _version: Version
-    _call_kwargs: dict[str, Any]
+    _scalar_kwargs: ScalarKwargs
 
     @classmethod
     def from_callables(
@@ -245,7 +245,7 @@ def from_callables(
         obj._implementation = context._implementation
         obj._backend_version = context._backend_version
         obj._version = context._version
-        obj._call_kwargs = {}
+        obj._scalar_kwargs = {}
         return obj
 
     @property
diff --git a/narwhals/_compliant/typing.py b/narwhals/_compliant/typing.py
@@ -4,6 +4,7 @@
 from typing import Any
 from typing import Callable
 from typing import Sequence
+from typing import TypedDict
 from typing import TypeVar
 
 if TYPE_CHECKING:
@@ -21,8 +22,25 @@
     from narwhals._compliant.namespace import EagerNamespace
     from narwhals._compliant.series import CompliantSeries
     from narwhals._compliant.series import EagerSeries
+    from narwhals.typing import FillNullStrategy
     from narwhals.typing import NativeFrame
     from narwhals.typing import NativeSeries
+    from narwhals.typing import RankMethod
+
+    class ScalarKwargs(TypedDict, total=False):
+        """Non-expressifiable args which we may need to reuse in `agg` or `over`."""
+
+        center: int
+        ddof: int
+        descending: bool
+        limit: int | None
+        method: RankMethod
+        min_samples: int
+        n: int
+        reverse: bool
+        strategy: FillNullStrategy | None
+        window_size: int
+
 
 __all__ = [
     "AliasName",
diff --git a/narwhals/_compliant/when_then.py b/narwhals/_compliant/when_then.py
@@ -25,6 +25,7 @@
     from typing_extensions import TypeAlias
 
     from narwhals._compliant.typing import EvalSeries
+    from narwhals._compliant.typing import ScalarKwargs
     from narwhals.typing import NonNestedLiteral
     from narwhals.utils import Implementation
     from narwhals.utils import Version
@@ -91,7 +92,7 @@ class CompliantThen(CompliantExpr[FrameT, SeriesT], Protocol38[FrameT, SeriesT,
     _implementation: Implementation
     _backend_version: tuple[int, ...]
     _version: Version
-    _call_kwargs: dict[str, Any]
+    _scalar_kwargs: ScalarKwargs
 
     @classmethod
     def from_when(
@@ -113,7 +114,7 @@ def from_when(
         obj._implementation = when._implementation
         obj._backend_version = when._backend_version
         obj._version = when._version
-        obj._call_kwargs = {}
+        obj._scalar_kwargs = {}
         return obj
 
     def otherwise(self, otherwise: IntoExpr[SeriesT, ExprT], /) -> ExprT:
diff --git a/narwhals/_dask/expr.py b/narwhals/_dask/expr.py
@@ -30,6 +30,7 @@
     from narwhals._compliant.typing import AliasNames
     from narwhals._compliant.typing import EvalNames
     from narwhals._compliant.typing import EvalSeries
+    from narwhals._compliant.typing import ScalarKwargs
     from narwhals._dask.dataframe import DaskLazyFrame
     from narwhals._dask.namespace import DaskNamespace
     from narwhals._expression_parsing import ExprKind
@@ -60,9 +61,7 @@ def __init__(
         alias_output_names: AliasNames | None,
         backend_version: tuple[int, ...],
         version: Version,
-        # Kwargs with metadata which we may need in group-by agg
-        # (e.g. `ddof` for `std` and `var`).
-        call_kwargs: dict[str, Any] | None = None,
+        scalar_kwargs: ScalarKwargs | None = None,
     ) -> None:
         self._call = call
         self._depth = depth
@@ -71,7 +70,7 @@ def __init__(
         self._alias_output_names = alias_output_names
         self._backend_version = backend_version
         self._version = version
-        self._call_kwargs = call_kwargs or {}
+        self._scalar_kwargs = scalar_kwargs or {}
         self._metadata: ExprMetadata | None = None
 
     def __call__(self, df: DaskLazyFrame) -> Sequence[dx.Series]:
@@ -97,7 +96,7 @@ def func(df: DaskLazyFrame) -> list[dx.Series]:
             alias_output_names=self._alias_output_names,
             backend_version=self._backend_version,
             version=self._version,
-            call_kwargs=self._call_kwargs,
+            scalar_kwargs=self._scalar_kwargs,
         )
 
     @classmethod
@@ -155,7 +154,7 @@ def _with_callable(
         call: Callable[..., dx.Series],
         /,
         expr_name: str = "",
-        call_kwargs: dict[str, Any] | None = None,
+        scalar_kwargs: ScalarKwargs | None = None,
         **expressifiable_args: Self | Any,
     ) -> Self:
         def func(df: DaskLazyFrame) -> list[dx.Series]:
@@ -178,7 +177,7 @@ def func(df: DaskLazyFrame) -> list[dx.Series]:
             alias_output_names=self._alias_output_names,
             backend_version=self._backend_version,
             version=self._version,
-            call_kwargs=call_kwargs,
+            scalar_kwargs=scalar_kwargs,
         )
 
     def _with_alias_output_names(self, func: AliasNames | None, /) -> Self:
@@ -190,7 +189,7 @@ def _with_alias_output_names(self, func: AliasNames | None, /) -> Self:
             alias_output_names=func,
             backend_version=self._backend_version,
             version=self._version,
-            call_kwargs=self._call_kwargs,
+            scalar_kwargs=self._scalar_kwargs,
         )
 
     def __add__(self, other: Any) -> Self:
@@ -321,14 +320,14 @@ def std(self, ddof: int) -> Self:
         return self._with_callable(
             lambda _input: _input.std(ddof=ddof).to_series(),
             "std",
-            call_kwargs={"ddof": ddof},
+            scalar_kwargs={"ddof": ddof},
         )
 
     def var(self, ddof: int) -> Self:
         return self._with_callable(
             lambda _input: _input.var(ddof=ddof).to_series(),
             "var",
-            call_kwargs={"ddof": ddof},
+            scalar_kwargs={"ddof": ddof},
         )
 
     def skew(self) -> Self:
@@ -626,11 +625,11 @@ def func(df: DaskLazyFrame) -> Sequence[dx.Series]:
                             msg = "Safety check failed, please report a bug."
                             raise AssertionError(msg)
                         res_native = grouped.transform(
-                            dask_function_name, **self._call_kwargs
+                            dask_function_name, **self._scalar_kwargs
                         ).to_frame(output_names[0])
                     else:
                         res_native = grouped[list(output_names)].transform(
-                            dask_function_name, **self._call_kwargs
+                            dask_function_name, **self._scalar_kwargs
                         )
                 result_frame = df._with_native(
                     res_native.rename(columns=dict(zip(output_names, aliases)))
diff --git a/narwhals/_dask/group_by.py b/narwhals/_dask/group_by.py
@@ -115,7 +115,7 @@ def agg(self, *exprs: DaskExpr) -> DaskLazyFrame:
             # e.g. `agg(nw.mean('a'))`
             agg_fn = self._remap_expr_name(self._leaf_name(expr))
             # deal with n_unique case in a "lazy" mode to not depend on dask globally
-            agg_fn = agg_fn(**expr._call_kwargs) if callable(agg_fn) else agg_fn
+            agg_fn = agg_fn(**expr._scalar_kwargs) if callable(agg_fn) else agg_fn
             simple_aggregations.update(
                 (alias, (output_name, agg_fn))
                 for alias, output_name in zip(aliases, output_names)
diff --git a/narwhals/_pandas_like/expr.py b/narwhals/_pandas_like/expr.py
diff --git a/narwhals/_pandas_like/group_by.py b/narwhals/_pandas_like/group_by.py
