apache · timsaucer · May 5, 2025 · Apr 27, 2025 · Apr 27, 2025 · Apr 27, 2025
diff --git a/docs/source/user-guide/dataframe.rst b/docs/source/user-guide/dataframe.rst
@@ -75,13 +75,17 @@ You can customize how DataFrames are rendered in HTML by configuring the formatt
 
     # Change the default styling
     configure_formatter(
-        max_rows=50,           # Maximum number of rows to display
-        max_width=None,        # Maximum width in pixels (None for auto)
-        theme="light",         # Theme: "light" or "dark" 
-        precision=2,           # Floating point precision
-        thousands_separator=",", # Separator for thousands
-        date_format="%Y-%m-%d", # Date format
-        truncate_width=20      # Max width for string columns before truncating
+        max_cell_length=25,        # Maximum characters in a cell before truncation
+        max_width=1000,            # Maximum width in pixels
+        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__
+        enable_cell_expansion=True,# Allow expanding truncated cells
+        custom_css=None,           # Additional custom CSS
+        show_truncation_message=True, # Show message when data is truncated
+        style_provider=None,       # Custom styling provider
+        use_shared_styles=True     # Share styles across tables
     )
 
 The formatter settings affect all DataFrames displayed after configuration.
@@ -113,6 +117,25 @@ For advanced styling needs, you can create a custom style provider:
     # Apply the custom style provider
     configure_formatter(style_provider=MyStyleProvider())
 
+Performance Optimization with Shared Styles
+-------------------------------------------
+The ``use_shared_styles`` parameter (enabled by default) optimizes performance when displaying 
+multiple DataFrames in notebook environments:
+
+ .. code-block:: python
+    from datafusion.html_formatter import StyleProvider, configure_formatter
+    # Default: Use shared styles (recommended for notebooks)
+    configure_formatter(use_shared_styles=True)
+
+    # Disable shared styles (each DataFrame includes its own styles)
+    configure_formatter(use_shared_styles=False)
+
+When ``use_shared_styles=True``:
+- CSS styles and JavaScript are included only once per notebook session
+- This reduces HTML output size and prevents style duplication
+- Improves rendering performance with many DataFrames
+- Applies consistent styling across all DataFrames
+
 Creating a Custom Formatter
 ---------------------------
 
@@ -177,3 +200,18 @@ You can also use a context manager to temporarily change formatting settings:
 
     # Back to default formatting
     df.show()
+
+Memory and Display Controls
+---------------------------
+
+You can control how much data is displayed and how much memory is used for rendering:
+
+ .. code-block:: python
+
+    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
+    )
+
+These parameters help balance comprehensive data display against performance considerations.
diff --git a/python/datafusion/html_formatter.py b/python/datafusion/html_formatter.py
@@ -27,6 +27,36 @@
 )
 
 
+def _validate_positive_int(value: Any, param_name: str) -> None:
+    """Validate that a parameter is a positive integer.
+
+    Args:
+        value: The value to validate
+        param_name: Name of the parameter (used in error message)
+
+    Raises:
+        ValueError: If the value is not a positive integer
+    """
+    if not isinstance(value, int) or value <= 0:
+        msg = f"{param_name} must be a positive integer"
+        raise ValueError(msg)
+
+
+def _validate_bool(value: Any, param_name: str) -> None:
+    """Validate that a parameter is a boolean.
+
+    Args:
+        value: The value to validate
+        param_name: Name of the parameter (used in error message)
+
+    Raises:
+        TypeError: If the value is not a boolean
+    """
+    if not isinstance(value, bool):
+        msg = f"{param_name} must be a boolean"
+        raise TypeError(msg)
+
+
 @runtime_checkable
 class CellFormatter(Protocol):
     """Protocol for cell value formatters."""
@@ -91,6 +121,9 @@ class DataFrameHtmlFormatter:
         max_cell_length: Maximum characters to display in a cell before truncation
         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
+        repr_rows: Default number of rows to display in repr output
         enable_cell_expansion: Whether to add expand/collapse buttons for long cell
           values
         custom_css: Additional CSS to include in the HTML output
@@ -108,6 +141,9 @@ def __init__(
         max_cell_length: int = 25,
         max_width: int = 1000,
         max_height: int = 300,
+        max_memory_bytes: int = 2 * 1024 * 1024,  # 2 MB
+        min_rows_display: int = 20,
+        repr_rows: int = 10,
         enable_cell_expansion: bool = True,
         custom_css: Optional[str] = None,
         show_truncation_message: bool = True,
@@ -124,6 +160,12 @@ def __init__(
             Maximum width of the displayed table in pixels.
         max_height : int, default 300
             Maximum height of the displayed table in pixels.
+        max_memory_bytes : int, default 2097152 (2MB)
+            Maximum memory in bytes for rendered data.
+        min_rows_display : int, default 20
+            Minimum number of rows to display.
+        repr_rows : int, default 10
+            Default number of rows to display in repr output.
         enable_cell_expansion : bool, default True
             Whether to allow cells to expand when clicked.
         custom_css : str, optional
@@ -139,7 +181,8 @@ def __init__(
         Raises:
         ------
         ValueError
-            If max_cell_length, max_width, or max_height is not a positive integer.
+            If max_cell_length, max_width, max_height, max_memory_bytes,
+            min_rows_display, or repr_rows is not a positive integer.
         TypeError
             If enable_cell_expansion, show_truncation_message, or use_shared_styles is
             not a boolean,
@@ -148,27 +191,17 @@ def __init__(
             protocol.
         """
         # Validate numeric parameters
-
-        if not isinstance(max_cell_length, int) or max_cell_length <= 0:
-            msg = "max_cell_length must be a positive integer"
-            raise ValueError(msg)
-        if not isinstance(max_width, int) or max_width <= 0:
-            msg = "max_width must be a positive integer"
-            raise ValueError(msg)
-        if not isinstance(max_height, int) or max_height <= 0:
-            msg = "max_height must be a positive integer"
-            raise ValueError(msg)
+        _validate_positive_int(max_cell_length, "max_cell_length")
+        _validate_positive_int(max_width, "max_width")
+        _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")
 
         # Validate boolean parameters
-        if not isinstance(enable_cell_expansion, bool):
-            msg = "enable_cell_expansion must be a boolean"
-            raise TypeError(msg)
-        if not isinstance(show_truncation_message, bool):
-            msg = "show_truncation_message must be a boolean"
-            raise TypeError(msg)
-        if not isinstance(use_shared_styles, bool):
-            msg = "use_shared_styles must be a boolean"
-            raise TypeError(msg)
+        _validate_bool(enable_cell_expansion, "enable_cell_expansion")
+        _validate_bool(show_truncation_message, "show_truncation_message")
+        _validate_bool(use_shared_styles, "use_shared_styles")
 
         # Validate custom_css
         if custom_css is not None and not isinstance(custom_css, str):
@@ -183,6 +216,9 @@ def __init__(
         self.max_cell_length = max_cell_length
         self.max_width = max_width
         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.enable_cell_expansion = enable_cell_expansion
         self.custom_css = custom_css
         self.show_truncation_message = show_truncation_message
@@ -597,6 +633,9 @@ def configure_formatter(**kwargs: Any) -> None:
         **kwargs: Formatter configuration parameters like max_cell_length,
                  max_width, max_height, enable_cell_expansion, etc.
 
+    Raises:
+        ValueError: If any invalid parameters are provided
+
     Example:
         >>> from datafusion.html_formatter import configure_formatter
         >>> configure_formatter(
@@ -606,6 +645,31 @@ def configure_formatter(**kwargs: Any) -> None:
         ...     use_shared_styles=True
         ... )
     """
+    # Valid parameters accepted by DataFrameHtmlFormatter
+    valid_params = {
+        "max_cell_length",
+        "max_width",
+        "max_height",
+        "max_memory_bytes",
+        "min_rows_display",
+        "repr_rows",
+        "enable_cell_expansion",
+        "custom_css",
+        "show_truncation_message",
+        "style_provider",
+        "use_shared_styles",
+    }
+
+    # Check for invalid parameters
+    invalid_params = set(kwargs) - valid_params
+    if invalid_params:
+        msg = (
+            f"Invalid formatter parameters: {', '.join(invalid_params)}. "
+            f"Valid parameters are: {', '.join(valid_params)}"
+        )
+        raise ValueError(msg)
+
+    # Create and set formatter with validated parameters
     set_formatter(DataFrameHtmlFormatter(**kwargs))