feat: Use _repr_html_ when native supports it

narwhals/_utils.py

@@ -1544,6 +1544,49 @@ def generate_repr(header: str, native_repr: str) -> str:
     )
 
 
+# NOTE: Unsure on how to test this reliably
+def generate_repr_html(
+    caption_text: Literal["Narwhals DataFrame", "Narwhals LazyFrame", "Narwhals Series"],
+    /,
+    native_html: str,
+) -> str | None:  # pragma: no cover
+    if caption_text == "Narwhals LazyFrame" and "LazyFrame" in native_html:
+        html = native_html.replace("LazyFrame", "LazyFrame.to_native()")
+        return f"{html}<p><b>{caption_text}</b></p>"
+    import io
+    import xml.etree.ElementTree as ET
+
+    style_css = (
+        ".dataframe caption { "
+        "caption-side: top; "
+        "text-align: center; "
+        "font-weight: bold; "
+        "padding-top: 8px;"
+        "}"
+    )
+    try:
+        tree = ET.parse(io.StringIO(native_html.replace("<style scoped>", "<style>")))  # noqa: S314
+    except (SyntaxError, TypeError):
+        return None
+    table = tree.find("table")
+    if table is None:
+        return None
+    caption = ET.Element("caption")
+    caption.text = caption_text
+    table.insert(0, caption)
+    style = tree.find("style")
+    if style is not None:
+        text_existing = style.text or ""
+        style.text = f"{text_existing}\n{style_css}"
+    else:
+        style = ET.Element("style")
+        style.text = style_css
+        tree.getroot().insert(0, style)
+    buf = io.BytesIO()
+    tree.write(buf, "utf-8", method="html")
+    return buf.getvalue().decode()
+
+
 def check_columns_exist(
     subset: Collection[str], /, *, available: Collection[str]
 ) -> ColumnNotFoundError | None:

narwhals/dataframe.py

@@ -24,9 +24,11 @@
 from narwhals._utils import (
     Implementation,
     Version,
+    _hasattr_static,
     check_columns_exist,
     flatten,
     generate_repr,
+    generate_repr_html,
     is_compliant_dataframe,
     is_compliant_lazyframe,
     is_eager_allowed,
@@ -698,6 +700,12 @@ def __array__(self, dtype: Any = None, copy: bool | None = None) -> _2DArray:  #
     def __repr__(self) -> str:  # pragma: no cover
         return generate_repr("Narwhals DataFrame", self.to_native().__repr__())
 
+    def _repr_html_(self) -> str | None:  # pragma: no cover
+        native: Any = self.to_native()
+        if _hasattr_static(native, "_repr_html_") and (html := native._repr_html_()):
+            return generate_repr_html("Narwhals DataFrame", html)
+        return None
+
     def __arrow_c_stream__(self, requested_schema: object | None = None) -> object:
         """Export a DataFrame via the Arrow PyCapsule Interface.
 
@@ -2446,6 +2454,12 @@ def __init__(self, df: Any, *, level: Literal["full", "lazy", "interchange"]) ->
     def __repr__(self) -> str:  # pragma: no cover
         return generate_repr("Narwhals LazyFrame", self.to_native().__repr__())
 
+    def _repr_html_(self) -> str | None:  # pragma: no cover
+        native: Any = self.to_native()
+        if _hasattr_static(native, "_repr_html_") and (html := native._repr_html_()):
+            return generate_repr_html("Narwhals LazyFrame", html)
+        return None
+
     @property
     def implementation(self) -> Implementation:
         """Return implementation of native frame.

narwhals/series.py

@@ -7,9 +7,11 @@
 from narwhals._utils import (
     Implementation,
     Version,
+    _hasattr_static,
     _validate_rolling_arguments,
     ensure_type,
     generate_repr,
+    generate_repr_html,
     is_compliant_series,
     is_eager_allowed,
     is_index_selector,
@@ -411,6 +413,12 @@ def pipe(self, function: Callable[[Any], Self], *args: Any, **kwargs: Any) -> Se
     def __repr__(self) -> str:  # pragma: no cover
         return generate_repr("Narwhals Series", self.to_native().__repr__())
 
+    def _repr_html_(self) -> str | None:  # pragma: no cover
+        native: Any = self.to_native()
+        if _hasattr_static(native, "_repr_html_") and (html := native._repr_html_()):
+            return generate_repr_html("Narwhals Series", html)
+        return None
+
     def __len__(self) -> int:
         return len(self._compliant_series)