Add ExplainFormat enum and format option to DataFrame.explain()

Extend the existing explain() method with an optional format parameter
instead of adding a separate explain_with_options() method. This keeps
the API simple while exposing all upstream ExplainOption functionality.

Available formats: indent (default), tree, pgjson, graphviz.

The ExplainFormat enum is exported from the top-level datafusion module.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: timsaucer

crates/core/src/dataframe.rs

@@ -804,9 +804,25 @@ impl PyDataFrame {
     }
 
     /// Print the query plan
-    #[pyo3(signature = (verbose=false, analyze=false))]
-    fn explain(&self, py: Python, verbose: bool, analyze: bool) -> PyDataFusionResult<()> {
-        let df = self.df.as_ref().clone().explain(verbose, analyze)?;
+    #[pyo3(signature = (verbose=false, analyze=false, format=None))]
+    fn explain(
+        &self,
+        py: Python,
+        verbose: bool,
+        analyze: bool,
+        format: Option<&str>,
+    ) -> PyDataFusionResult<()> {
+        let explain_format = match format {
+            Some(f) => f
+                .parse::<datafusion::common::format::ExplainFormat>()
+                .map_err(|e| PyDataFusionError::Common(e.to_string()))?,
+            None => datafusion::common::format::ExplainFormat::Indent,
+        };
+        let opts = datafusion::logical_expr::ExplainOption::default()
+            .with_verbose(verbose)
+            .with_analyze(analyze)
+            .with_format(explain_format);
+        let df = self.df.as_ref().clone().explain_with_options(opts)?;
         print_dataframe(py, df)
     }
 

python/datafusion/__init__.py

@@ -47,6 +47,7 @@
 from .dataframe import (
     DataFrame,
     DataFrameWriteOptions,
+    ExplainFormat,
     InsertOp,
     ParquetColumnOptions,
     ParquetWriterOptions,
@@ -82,6 +83,7 @@
     "DataFrameWriteOptions",
     "Database",
     "ExecutionPlan",
+    "ExplainFormat",
     "Expr",
     "InsertOp",
     "LogicalPlan",

python/datafusion/dataframe.py

@@ -65,6 +65,25 @@
 from enum import Enum
 
 
+class ExplainFormat(Enum):
+    """Output format for explain plans.
+
+    Controls how the query plan is rendered in :py:meth:`DataFrame.explain`.
+    """
+
+    INDENT = "indent"
+    """Default indented text format."""
+
+    TREE = "tree"
+    """Tree-style visual format with box-drawing characters."""
+
+    PGJSON = "pgjson"
+    """PostgreSQL-compatible JSON format for use with visualization tools."""
+
+    GRAPHVIZ = "graphviz"
+    """Graphviz DOT format for graph rendering."""
+
+
 # excerpt from deltalake
 # https://github.com/apache/datafusion-python/pull/981#discussion_r1905619163
 class Compression(Enum):
@@ -918,16 +937,24 @@ def join_on(
         exprs = [ensure_expr(expr) for expr in on_exprs]
         return DataFrame(self.df.join_on(right.df, exprs, how))
 
-    def explain(self, verbose: bool = False, analyze: bool = False) -> None:
+    def explain(
+        self,
+        verbose: bool = False,
+        analyze: bool = False,
+        format: ExplainFormat | None = None,
+    ) -> None:
         """Print an explanation of the DataFrame's plan so far.
 
         If ``analyze`` is specified, runs the plan and reports metrics.
 
         Args:
             verbose: If ``True``, more details will be included.
             analyze: If ``True``, the plan will run and metrics reported.
+            format: Output format for the plan. Defaults to
+                :py:attr:`ExplainFormat.INDENT`.
         """
-        self.df.explain(verbose, analyze)
+        fmt = format.value if format is not None else None
+        self.df.explain(verbose, analyze, fmt)
 
     def logical_plan(self) -> LogicalPlan:
         """Return the unoptimized ``LogicalPlan``.

python/tests/test_dataframe.py

@@ -3632,3 +3632,25 @@ def test_sort_by():
     df = ctx.from_pydict({"a": [3, 1, 2]})
     result = df.sort_by(column("a")).collect()[0]
     assert result.column(0).to_pylist() == [1, 2, 3]
+
+
+def test_explain_with_format(capsys):
+    from datafusion import ExplainFormat
+
+    ctx = SessionContext()
+    df = ctx.from_pydict({"a": [1]})
+
+    # Default format works
+    df.explain()
+    captured = capsys.readouterr()
+    assert "plan_type" in captured.out
+
+    # Tree format produces box-drawing characters
+    df.explain(format=ExplainFormat.TREE)
+    captured = capsys.readouterr()
+    assert "\u250c" in captured.out or "plan_type" in captured.out
+
+    # Verbose + analyze still works with format
+    df.explain(verbose=True, analyze=True, format=ExplainFormat.INDENT)
+    captured = capsys.readouterr()
+    assert "plan_type" in captured.out