feat(api): add ibis.sql to easily get a formatted SQL string

docs/api/expressions/top_level.md

@@ -28,6 +28,7 @@ These methods and objects are available directly in the `ibis` module.
 ::: ibis.or_
 ::: ibis.param
 ::: ibis.show_sql
+::: ibis.sql
 ::: ibis.random
 ::: ibis.range_window
 ::: ibis.row_number

ibis/common/pretty.py

@@ -49,6 +49,24 @@ def show_sql(
       t0.a * 2 AS c
     FROM t AS t0
     """
+    print(to_sql(expr, dialect=dialect), file=file)
+
+
+def to_sql(expr: ir.Expr, dialect: str | None = None) -> str:
+    """Return the formatted SQL string for an expression.
+
+    Parameters
+    ----------
+    expr
+        Ibis expression.
+    dialect
+        SQL dialect to use for compilation.
+
+    Returns
+    -------
+    str
+        Formatted SQL string
+    """
     import sqlglot
 
     # try to infer from a non-str expression or if not possible fallback to
@@ -87,4 +105,4 @@ def show_sql(
         write=write,
         pretty=True,
     )
-    print(pretty, file=file)
+    return pretty

ibis/expr/api.py

@@ -21,7 +21,7 @@
 import ibis.expr.schema as sch
 import ibis.expr.types as ir
 from ibis.backends.base import connect
-from ibis.common.pretty import show_sql
+from ibis.common.pretty import show_sql, to_sql
 from ibis.expr.deferred import Deferred
 from ibis.expr.random import random
 from ibis.expr.schema import Schema
@@ -208,6 +208,7 @@
     'Schema',
     'sequence',
     'show_sql',
+    'to_sql',
     'struct',
     'table',
     'time',