refactor(api)!: execute and to_pandas methods now require expr as positional-only

Author: cpcloud

ibis/backends/__init__.py

@@ -106,6 +106,7 @@ def _import_pyarrow():
     def to_pandas(
         self,
         expr: ir.Expr,
+        /,
         *,
         params: Mapping[ir.Scalar, Any] | None = None,
         limit: int | str | None = None,
@@ -1169,8 +1170,29 @@ def compile(
         """Compile an expression."""
         return self.compiler.to_sql(expr, params=params)
 
-    def execute(self, expr: ir.Expr) -> Any:
-        """Execute an expression."""
+    def execute(
+        self,
+        expr: ir.Expr,
+        /,
+        *,
+        params: Mapping[ir.Scalar, Any] | None = None,
+        limit: int | str | None = None,
+        **kwargs: Any,
+    ) -> pd.DataFrame | pd.Series | Any:
+        """Execute an Ibis expression and return a pandas `DataFrame`, `Series`, or scalar.
+
+        Parameters
+        ----------
+        expr
+            Ibis expression to execute.
+        params
+            Mapping of scalar parameter expressions to value.
+        limit
+            An integer to effect a specific row limit. A value of `None` means
+            no limit. The default is in `ibis/config.py`.
+        kwargs
+            Keyword arguments
+        """
 
     @abc.abstractmethod
     def create_table(

ibis/backends/bigquery/__init__.py

@@ -807,7 +807,15 @@ def to_pyarrow_batches(
             (_postprocess_arrow(b, colnames) for b in batch_iter),
         )
 
-    def execute(self, expr, params=None, limit="default", **kwargs):
+    def execute(
+        self,
+        expr: ir.Expr,
+        /,
+        *,
+        params: Mapping[ir.Scalar, Any] | None = None,
+        limit: int | str | None = None,
+        **kwargs: Any,
+    ) -> pd.DataFrame | pd.Series | Any:
         """Compile and execute the given Ibis expression.
 
         Compile and execute Ibis expression using this backend client

ibis/backends/clickhouse/__init__.py

@@ -399,6 +399,8 @@ def batcher(
     def execute(
         self,
         expr: ir.Expr,
+        /,
+        *,
         limit: str | None = "default",
         params: Mapping[ir.Scalar, Any] | None = None,
         external_tables: Mapping[str, pd.DataFrame] | None = None,

ibis/backends/datafusion/__init__.py

@@ -540,8 +540,18 @@ def to_pyarrow(self, expr: ir.Expr, **kwargs: Any) -> pa.Table:
         arrow_table = batch_reader.read_all()
         return expr.__pyarrow_result__(arrow_table)
 
-    def execute(self, expr: ir.Expr, **kwargs: Any):
-        batch_reader = self.to_pyarrow_batches(expr, **kwargs)
+    def execute(
+        self,
+        expr: ir.Expr,
+        /,
+        *,
+        params: Mapping[ir.Scalar, Any] | None = None,
+        limit: int | str | None = None,
+        **kwargs: Any,
+    ) -> pd.DataFrame | pd.Series | Any:
+        batch_reader = self.to_pyarrow_batches(
+            expr, params=params, limit=limit, **kwargs
+        )
         return expr.__pandas_result__(
             batch_reader.read_pandas(timestamp_as_object=True)
         )

ibis/backends/duckdb/__init__.py

@@ -1318,15 +1318,19 @@ def to_pyarrow(
     def execute(
         self,
         expr: ir.Expr,
-        params: Mapping | None = None,
-        limit: str | None = "default",
-        **_: Any,
-    ) -> Any:
+        /,
+        *,
+        params: Mapping[ir.Scalar, Any] | None = None,
+        limit: int | str | None = None,
+        **kwargs: Any,
+    ) -> pd.DataFrame | pd.Series | Any:
         """Execute an expression."""
         import pandas as pd
         import pyarrow.types as pat
 
-        table = self._to_duckdb_relation(expr, params=params, limit=limit).arrow()
+        table = self._to_duckdb_relation(
+            expr, params=params, limit=limit, **kwargs
+        ).arrow()
 
         df = pd.DataFrame(
             {

ibis/backends/flink/__init__.py

@@ -386,11 +386,32 @@ def _register_in_memory_table(self, op: ops.InMemoryTable) -> None:
     def _finalize_memtable(self, name: str) -> None:
         self.drop_view(name, temp=True, force=True)
 
-    def execute(self, expr: ir.Expr, **kwargs: Any) -> Any:
-        """Execute an expression."""
+    def execute(
+        self,
+        expr: ir.Expr,
+        /,
+        *,
+        params: Mapping[ir.Scalar, Any] | None = None,
+        limit: int | str | None = None,
+        **kwargs: Any,
+    ) -> pd.DataFrame | pd.Series | Any:
+        """Execute an Ibis expression and return a pandas `DataFrame`, `Series`, or scalar.
+
+        Parameters
+        ----------
+        expr
+            Ibis expression to execute.
+        params
+            Mapping of scalar parameter expressions to value.
+        limit
+            An integer to effect a specific row limit. A value of `None` means
+            no limit. The default is in `ibis/config.py`.
+        kwargs
+            Keyword arguments
+        """
         self._run_pre_execute_hooks(expr)
 
-        sql = self.compile(expr.as_table(), **kwargs)
+        sql = self.compile(expr.as_table(), params=params, **kwargs)
         df = self._table_env.sql_query(sql).to_pandas()
 
         return expr.__pandas_result__(df)

ibis/backends/mysql/__init__.py

@@ -368,13 +368,32 @@ def list_tables(
         return self._filter_with_like(map(itemgetter(0), out), like)
 
     def execute(
-        self, expr: ir.Expr, limit: str | None = "default", **kwargs: Any
-    ) -> Any:
-        """Execute an expression."""
+        self,
+        expr: ir.Expr,
+        /,
+        *,
+        params: Mapping[ir.Scalar, Any] | None = None,
+        limit: int | str | None = None,
+        **kwargs: Any,
+    ) -> pd.DataFrame | pd.Series | Any:
+        """Execute an Ibis expression and return a pandas `DataFrame`, `Series`, or scalar.
+
+        Parameters
+        ----------
+        expr
+            Ibis expression to execute.
+        params
+            Mapping of scalar parameter expressions to value.
+        limit
+            An integer to effect a specific row limit. A value of `None` means
+            no limit. The default is in `ibis/config.py`.
+        kwargs
+            Keyword arguments
+        """
 
         self._run_pre_execute_hooks(expr)
         table = expr.as_table()
-        sql = self.compile(table, limit=limit, **kwargs)
+        sql = self.compile(table, limit=limit, params=params, **kwargs)
 
         schema = table.schema()
 

ibis/backends/polars/__init__.py

@@ -450,6 +450,8 @@ def _to_dataframe(
     def execute(
         self,
         expr: ir.Expr,
+        /,
+        *,
         params: Mapping[ir.Expr, object] | None = None,
         limit: int | None = None,
         streaming: bool = False,

ibis/backends/pyspark/__init__.py

@@ -459,10 +459,12 @@ def raw_sql(self, query: str | sg.Expression, **kwargs: Any) -> Any:
     def execute(
         self,
         expr: ir.Expr,
-        params: Mapping | None = None,
-        limit: str | None = "default",
+        /,
+        *,
+        params: Mapping[ir.Scalar, Any] | None = None,
+        limit: int | str | None = None,
         **kwargs: Any,
-    ) -> Any:
+    ) -> pd.DataFrame | pd.Series | Any:
         """Execute an expression."""
 
         self._run_pre_execute_hooks(expr)

ibis/backends/sql/__init__.py

@@ -212,12 +212,31 @@ def drop_view(
     def execute(
         self,
         expr: ir.Expr,
-        params: Mapping | None = None,
-        limit: str | None = "default",
+        /,
+        *,
+        params: Mapping[ir.Scalar, Any] | None = None,
+        limit: int | str | None = None,
         **kwargs: Any,
-    ) -> Any:
-        """Execute an expression."""
+    ) -> pd.DataFrame | pd.Series | Any:
+        """Execute an Ibis expression and return a pandas `DataFrame`, `Series`, or scalar.
+
+        Parameters
+        ----------
+        expr
+            Ibis expression to execute.
+        params
+            Mapping of scalar parameter expressions to value.
+        limit
+            An integer to effect a specific row limit. A value of `None` means
+            no limit. The default is in `ibis/config.py`.
+        kwargs
+            Keyword arguments
 
+        Returns
+        -------
+        DataFrame | Series | scalar
+            The result of the expression execution.
+        """
         self._run_pre_execute_hooks(expr)
         table = expr.as_table()
         sql = self.compile(table, params=params, limit=limit, **kwargs)

ibis/expr/types/core.py

@@ -399,10 +399,11 @@ def get_backend(self) -> BaseBackend:
 
     def execute(
         self,
+        *,
         limit: int | str | None = "default",
         params: Mapping[ir.Value, Any] | None = None,
         **kwargs: Any,
-    ):
+    ) -> pd.DataFrame | pd.Series | Any:
         """Execute an expression against its backend if one exists.
 
         Parameters

ibis/expr/types/generic.py

@@ -19,6 +19,7 @@
 if TYPE_CHECKING:
     import datetime
     import uuid
+    from collections.abc import Mapping
 
     import pandas as pd
     import polars as pl
@@ -1330,29 +1331,31 @@ def desc(self, nulls_first: bool = False) -> ir.Value:
         """
         return ops.SortKey(self, ascending=False, nulls_first=nulls_first).to_expr()
 
-    def to_pandas(self, **kwargs) -> pd.Series:
-        """Convert an expression to a pandas or scalar object.
+    def to_pandas(
+        self,
+        *,
+        params: Mapping[ir.Scalar, Any] | None = None,
+        limit: int | str | None = None,
+        **kwargs: Any,
+    ) -> pd.Series | Any:
+        """Convert a table expression to a pandas DataFrame.
 
         Parameters
         ----------
+        params
+            Mapping of scalar parameter expressions to value.
+        limit
+            An integer to effect a specific row limit. A value of `None` means
+            no limit. The default is in `ibis/config.py`.
         kwargs
-            Same as keyword arguments to [`execute`](#ibis.expr.types.core.Expr.execute)
+            Keyword arguments
 
-        Examples
-        --------
-        >>> import ibis
-        >>> ibis.options.interactive = True
-        >>> t = ibis.examples.penguins.fetch()
-        >>> t.to_pandas(limit=5)
-          species     island  bill_length_mm  ...  body_mass_g     sex  year
-        0  Adelie  Torgersen            39.1  ...       3750.0    male  2007
-        1  Adelie  Torgersen            39.5  ...       3800.0  female  2007
-        2  Adelie  Torgersen            40.3  ...       3250.0  female  2007
-        3  Adelie  Torgersen             NaN  ...          NaN    None  2007
-        4  Adelie  Torgersen            36.7  ...       3450.0  female  2007
-        [5 rows x 8 columns]
+        Returns
+        -------
+        DataFrame
+            The result of executing the expression as a pandas DataFrame
         """
-        return self.execute(**kwargs)
+        return self.execute(params=params, limit=limit, **kwargs)
 
 
 @public

ibis/expr/types/relations.py

@@ -3580,15 +3580,33 @@ def sql(self, query: str, dialect: str | None = None) -> ir.Table:
         node = ops.SQLStringView(child=self.op(), query=query, schema=schema)
         return node.to_expr()
 
-    def to_pandas(self, **kwargs) -> pd.DataFrame:
+    def to_pandas(
+        self,
+        *,
+        params: Mapping[ir.Scalar, Any] | None = None,
+        limit: int | str | None = None,
+        **kwargs: Any,
+    ) -> pd.DataFrame:
         """Convert a table expression to a pandas DataFrame.
 
         Parameters
         ----------
+        expr
+            Ibis expression to execute.
+        params
+            Mapping of scalar parameter expressions to value.
+        limit
+            An integer to effect a specific row limit. A value of `None` means
+            no limit. The default is in `ibis/config.py`.
         kwargs
-            Same as keyword arguments to [`execute`](./expression-generic.qmd#ibis.expr.types.core.Expr.execute)
+            Keyword arguments
+
+        Returns
+        -------
+        DataFrame
+            The result of executing the expression as a pandas DataFrame
         """
-        return self.execute(**kwargs)
+        return self.execute(params=params, limit=limit, **kwargs)
 
     def cache(self) -> Table:
         """Cache the provided expression.