Refactor DataFrame formatter to replace repr_rows with max_rows and update related validations

Author: kosiew

docs/source/user-guide/dataframe/rendering.rst

@@ -58,7 +58,7 @@ You can customize how DataFrames are rendered by configuring the formatter:
         max_height=300,            # Maximum height in pixels
         max_memory_bytes=2097152,  # Maximum memory for rendering (2MB)
         min_rows_display=20,       # Minimum number of rows to display
-        repr_rows=10,              # Number of rows to display in __repr__
+        max_rows=10,               # Maximum rows to display in __repr__
         enable_cell_expansion=True,# Allow expanding truncated cells
         custom_css=None,           # Additional custom CSS
         show_truncation_message=True, # Show message when data is truncated
@@ -191,7 +191,7 @@ You can control how much data is displayed and how much memory is used for rende
     configure_formatter(
         max_memory_bytes=4 * 1024 * 1024,  # 4MB maximum memory for display
         min_rows_display=50,               # Always show at least 50 rows
-        repr_rows=20                       # Show 20 rows in __repr__ output
+        max_rows=20                        # Show 20 rows in __repr__ output
     )
 
 These parameters help balance comprehensive data display against performance considerations.

python/datafusion/dataframe_formatter.py

@@ -126,8 +126,9 @@ class DataFrameHtmlFormatter:
         max_width: Maximum width of the HTML table in pixels
         max_height: Maximum height of the HTML table in pixels
         max_memory_bytes: Maximum memory in bytes for rendered data (default: 2MB)
-        min_rows_display: Minimum number of rows to display (must be <= repr_rows)
-        repr_rows: Default number of rows to display in repr output
+        min_rows_display: Minimum number of rows to display (must be <= max_rows)
+        max_rows: Maximum number of rows to display in repr output
+        repr_rows: Deprecated alias for max_rows
         enable_cell_expansion: Whether to add expand/collapse buttons for long cell
           values
         custom_css: Additional CSS to include in the HTML output
@@ -144,7 +145,8 @@ def __init__(
         max_height: int = 300,
         max_memory_bytes: int = 2 * 1024 * 1024,  # 2 MB
         min_rows_display: int = 10,
-        repr_rows: int = 10,
+        max_rows: int = 10,
+        repr_rows: int | None = None,
         enable_cell_expansion: bool = True,
         custom_css: str | None = None,
         show_truncation_message: bool = True,
@@ -165,9 +167,11 @@ def __init__(
             Maximum memory in bytes for rendered data.
         min_rows_display : int, default 10
             Minimum number of rows to display. Must be less than or equal to
-            ``repr_rows``.
-        repr_rows : int, default 10
-            Default number of rows to display in repr output.
+            ``max_rows``.
+        max_rows : int, default 10
+            Maximum number of rows to display in repr output.
+        repr_rows : int, optional
+            Deprecated alias for ``max_rows``. Use ``max_rows`` instead.
         enable_cell_expansion : bool, default True
             Whether to allow cells to expand when clicked.
         custom_css : str, optional
@@ -184,7 +188,7 @@ def __init__(
         ------
         ValueError
             If max_cell_length, max_width, max_height, max_memory_bytes,
-            min_rows_display, or repr_rows is not a positive integer.
+            min_rows_display or max_rows is not a positive integer.
         TypeError
             If enable_cell_expansion, show_truncation_message, or use_shared_styles is
             not a boolean,
@@ -198,10 +202,19 @@ def __init__(
         _validate_positive_int(max_height, "max_height")
         _validate_positive_int(max_memory_bytes, "max_memory_bytes")
         _validate_positive_int(min_rows_display, "min_rows_display")
-        _validate_positive_int(repr_rows, "repr_rows")
 
-        if min_rows_display > repr_rows:
-            msg = "min_rows_display must be less than or equal to repr_rows"
+        if repr_rows is not None and repr_rows != max_rows:
+            msg = "Specify only max_rows (repr_rows is deprecated)"
+            raise ValueError(msg)
+
+        if repr_rows is not None:
+            _validate_positive_int(repr_rows, "repr_rows")
+            max_rows = repr_rows
+
+        _validate_positive_int(max_rows, "max_rows")
+
+        if min_rows_display > max_rows:
+            msg = "min_rows_display must be less than or equal to max_rows"
             raise ValueError(msg)
 
         # Validate boolean parameters
@@ -224,7 +237,9 @@ def __init__(
         self.max_height = max_height
         self.max_memory_bytes = max_memory_bytes
         self.min_rows_display = min_rows_display
-        self.repr_rows = repr_rows
+        self.max_rows = max_rows
+        # Backwards-compatible alias
+        self.repr_rows = max_rows
         self.enable_cell_expansion = enable_cell_expansion
         self.custom_css = custom_css
         self.show_truncation_message = show_truncation_message
@@ -665,6 +680,7 @@ def configure_formatter(**kwargs: Any) -> None:
         "max_height",
         "max_memory_bytes",
         "min_rows_display",
+        "max_rows",
         "repr_rows",
         "enable_cell_expansion",
         "custom_css",

python/tests/test_dataframe.py

@@ -1458,15 +1458,15 @@ def test_html_formatter_memory(df, clean_formatter_state):
     assert "data truncated" not in html_output.lower()
 
 
-def test_html_formatter_repr_rows(df, clean_formatter_state):
-    configure_formatter(min_rows_display=2, repr_rows=2)
+def test_html_formatter_max_rows(df, clean_formatter_state):
+    configure_formatter(min_rows_display=2, max_rows=2)
     html_output = df._repr_html_()
 
     tr_count = count_table_rows(html_output)
     # Table should have header row (1) + 2 data rows = 3 rows
     assert tr_count == 3
 
-    configure_formatter(min_rows_display=2, repr_rows=3)
+    configure_formatter(min_rows_display=2, max_rows=3)
     html_output = df._repr_html_()
 
     tr_count = count_table_rows(html_output)
@@ -1498,16 +1498,16 @@ def test_html_formatter_validation():
     with pytest.raises(ValueError, match="min_rows_display must be a positive integer"):
         DataFrameHtmlFormatter(min_rows_display=-5)
 
-    with pytest.raises(ValueError, match="repr_rows must be a positive integer"):
-        DataFrameHtmlFormatter(repr_rows=0)
+    with pytest.raises(ValueError, match="max_rows must be a positive integer"):
+        DataFrameHtmlFormatter(max_rows=0)
 
-    with pytest.raises(ValueError, match="repr_rows must be a positive integer"):
-        DataFrameHtmlFormatter(repr_rows=-10)
+    with pytest.raises(ValueError, match="max_rows must be a positive integer"):
+        DataFrameHtmlFormatter(max_rows=-10)
 
     with pytest.raises(
-        ValueError, match="min_rows_display must be less than or equal to repr_rows"
+        ValueError, match="min_rows_display must be less than or equal to max_rows"
     ):
-        DataFrameHtmlFormatter(min_rows_display=5, repr_rows=4)
+        DataFrameHtmlFormatter(min_rows_display=5, max_rows=4)
 
 
 def test_configure_formatter(df, clean_formatter_state):
@@ -1520,7 +1520,7 @@ def test_configure_formatter(df, clean_formatter_state):
     max_height = 30
     max_memory_bytes = 3 * MB
     min_rows_display = 2
-    repr_rows = 2
+    max_rows = 2
     enable_cell_expansion = False
     show_truncation_message = False
     use_shared_styles = False
@@ -1533,7 +1533,7 @@ def test_configure_formatter(df, clean_formatter_state):
     assert formatter_default.max_height != max_height
     assert formatter_default.max_memory_bytes != max_memory_bytes
     assert formatter_default.min_rows_display != min_rows_display
-    assert formatter_default.repr_rows != repr_rows
+    assert formatter_default.max_rows != max_rows
     assert formatter_default.enable_cell_expansion != enable_cell_expansion
     assert formatter_default.show_truncation_message != show_truncation_message
     assert formatter_default.use_shared_styles != use_shared_styles
@@ -1545,7 +1545,7 @@ def test_configure_formatter(df, clean_formatter_state):
         max_height=max_height,
         max_memory_bytes=max_memory_bytes,
         min_rows_display=min_rows_display,
-        repr_rows=repr_rows,
+        max_rows=max_rows,
         enable_cell_expansion=enable_cell_expansion,
         show_truncation_message=show_truncation_message,
         use_shared_styles=use_shared_styles,
@@ -1556,7 +1556,7 @@ def test_configure_formatter(df, clean_formatter_state):
     assert formatter_custom.max_height == max_height
     assert formatter_custom.max_memory_bytes == max_memory_bytes
     assert formatter_custom.min_rows_display == min_rows_display
-    assert formatter_custom.repr_rows == repr_rows
+    assert formatter_custom.max_rows == max_rows
     assert formatter_custom.enable_cell_expansion == enable_cell_expansion
     assert formatter_custom.show_truncation_message == show_truncation_message
     assert formatter_custom.use_shared_styles == use_shared_styles

src/dataframe.rs

@@ -74,16 +74,16 @@ pub struct FormatterConfig {
     pub max_bytes: usize,
     /// Minimum number of rows to display (default: 10)
     pub min_rows: usize,
-    /// Number of rows to include in __repr__ output (default: 10)
-    pub repr_rows: usize,
+    /// Maximum number of rows to include in __repr__ output (default: 10)
+    pub max_rows: usize,
 }
 
 impl Default for FormatterConfig {
     fn default() -> Self {
         Self {
             max_bytes: 2 * 1024 * 1024, // 2MB
             min_rows: 10,
-            repr_rows: 10,
+            max_rows: 10,
         }
     }
 }
@@ -103,12 +103,12 @@ impl FormatterConfig {
             return Err("min_rows must be a positive integer".to_string());
         }
 
-        if self.repr_rows == 0 {
-            return Err("repr_rows must be a positive integer".to_string());
+        if self.max_rows == 0 {
+            return Err("max_rows must be a positive integer".to_string());
         }
 
-        if self.min_rows > self.repr_rows {
-            return Err("min_rows must be less than or equal to repr_rows".to_string());
+        if self.min_rows > self.max_rows {
+            return Err("min_rows must be less than or equal to max_rows".to_string());
         }
 
         Ok(())
@@ -153,12 +153,18 @@ fn build_formatter_config_from_python(formatter: &Bound<'_, PyAny>) -> PyResult<
     let default_config = FormatterConfig::default();
     let max_bytes = get_attr(formatter, "max_memory_bytes", default_config.max_bytes);
     let min_rows = get_attr(formatter, "min_rows_display", default_config.min_rows);
-    let repr_rows = get_attr(formatter, "repr_rows", default_config.repr_rows);
+    let max_rows = get_attr(formatter, "max_rows", default_config.max_rows);
+    let repr_rows = get_attr(formatter, "repr_rows", max_rows);
+    let max_rows = if repr_rows != max_rows {
+        repr_rows
+    } else {
+        max_rows
+    };
 
     let config = FormatterConfig {
         max_bytes,
         min_rows,
-        repr_rows,
+        max_rows,
     };
 
     // Return the validated config, converting String error to PyErr
@@ -1344,7 +1350,7 @@ async fn collect_record_batches_to_display(
     let FormatterConfig {
         max_bytes,
         min_rows,
-        repr_rows,
+        max_rows,
     } = config;
 
     let partitioned_stream = df.execute_stream_partitioned().await?;
@@ -1355,7 +1361,7 @@ async fn collect_record_batches_to_display(
     let mut has_more = false;
 
     // ensure minimum rows even if memory/row limits are hit
-    while (size_estimate_so_far < max_bytes && rows_so_far < repr_rows) || rows_so_far < min_rows {
+    while (size_estimate_so_far < max_bytes && rows_so_far < max_rows) || rows_so_far < min_rows {
         let mut rb = match stream.next().await {
             None => {
                 break;
@@ -1385,8 +1391,8 @@ async fn collect_record_batches_to_display(
                 }
             }
 
-            if rows_in_rb + rows_so_far > repr_rows {
-                rb = rb.slice(0, repr_rows - rows_so_far);
+            if rows_in_rb + rows_so_far > max_rows {
+                rb = rb.slice(0, max_rows - rows_so_far);
                 has_more = true;
             }