From 9ad45ba370b3f6a3c7f5d23ff7911a49896f2172 Mon Sep 17 00:00:00 2001
From: dangotbanned <125183946+dangotbanned@users.noreply.github.com>
Date: Thu, 3 Jul 2025 14:01:17 +0100
Subject: [PATCH 1/6] feat: Use `_repr_html_` when native supports it

- Related #1702
- https://ipython.readthedocs.io/en/stable/config/integrating.html#rich-display
- https://github.com/pandas-dev/pandas/blob/22f12fc5d3f7fda3f198760204e7c13150c78581/pandas/core/frame.py#L1189-L1232
- https://github.com/pola-rs/polars/blob/8011fa34e0c5f1270ef52e2d3b0b2946bb2faa72/py-polars/polars/dataframe/frame.py#L1580-L1605
---
 narwhals/_utils.py    | 35 +++++++++++++++++++++++++++++++++++
 narwhals/dataframe.py |  8 ++++++++
 2 files changed, 43 insertions(+)

diff --git a/narwhals/_utils.py b/narwhals/_utils.py
index 788d82c1c0..d8ac60c834 100644
--- a/narwhals/_utils.py
+++ b/narwhals/_utils.py
@@ -1562,6 +1562,41 @@ def generate_repr(header: str, native_repr: str) -> str:
     )
 
 
+def generate_repr_html(header: str, native_html: str) -> str | None:
+    import io
+    import xml.etree.ElementTree as ET
+
+    style_css = (
+        ".dataframe caption { "
+        "caption-side: bottom; "
+        "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 = header
+    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:
diff --git a/narwhals/dataframe.py b/narwhals/dataframe.py
index b5acc9059c..aab6dfb43b 100644
--- a/narwhals/dataframe.py
+++ b/narwhals/dataframe.py
@@ -22,9 +22,11 @@
 )
 from narwhals._utils import (
     Implementation,
+    _hasattr_static,
     find_stacklevel,
     flatten,
     generate_repr,
+    generate_repr_html,
     is_compliant_dataframe,
     is_compliant_lazyframe,
     is_index_selector,
@@ -490,6 +492,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.
 

From 3769326ec3e4435f8e3815b70996f70e384e6678 Mon Sep 17 00:00:00 2001
From: dangotbanned <125183946+dangotbanned@users.noreply.github.com>
Date: Wed, 9 Jul 2025 16:58:49 +0100
Subject: [PATCH 2/6] feat: Support `pl.LazyFrame._repr_html_`

- `pandas` reuses the eager version
- `pyarrow` doesn't support
- `ibis` requires changing global config, so skipping that
- `dask` does have a `_repr_html_`, but doesn't parse well
---
 narwhals/_utils.py    | 7 ++++++-
 narwhals/dataframe.py | 6 ++++++
 2 files changed, 12 insertions(+), 1 deletion(-)

diff --git a/narwhals/_utils.py b/narwhals/_utils.py
index 08d73a77a5..e7645f7789 100644
--- a/narwhals/_utils.py
+++ b/narwhals/_utils.py
@@ -1579,7 +1579,12 @@ def generate_repr(header: str, native_repr: str) -> str:
     )
 
 
-def generate_repr_html(header: str, native_html: str) -> str | None:
+def generate_repr_html(
+    header: Literal["Narwhals DataFrame", "Narwhals LazyFrame"], native_html: str
+) -> str | None:
+    if header == "Narwhals LazyFrame" and "LazyFrame" in native_html:
+        html = native_html.replace("LazyFrame", "LazyFrame.to_native()")
+        return f"{html}<p><b>{header}</b></p>"
     import io
     import xml.etree.ElementTree as ET
 
diff --git a/narwhals/dataframe.py b/narwhals/dataframe.py
index 1137e259ed..4b3ce42db5 100644
--- a/narwhals/dataframe.py
+++ b/narwhals/dataframe.py
@@ -2241,6 +2241,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.

From ea42e8312d8a6527e986e59fd76fab312c9c8f21 Mon Sep 17 00:00:00 2001
From: dangotbanned <125183946+dangotbanned@users.noreply.github.com>
Date: Wed, 9 Jul 2025 17:02:02 +0100
Subject: [PATCH 3/6] chore: add note on testing

---
 narwhals/_utils.py | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/narwhals/_utils.py b/narwhals/_utils.py
index 39656aff2d..c8b353e834 100644
--- a/narwhals/_utils.py
+++ b/narwhals/_utils.py
@@ -1579,9 +1579,10 @@ def generate_repr(header: str, native_repr: str) -> str:
     )
 
 
+# NOTE: Unsure on how to test this reliably
 def generate_repr_html(
     header: Literal["Narwhals DataFrame", "Narwhals LazyFrame"], native_html: str
-) -> str | None:
+) -> str | None:  # pragma: no cover
     if header == "Narwhals LazyFrame" and "LazyFrame" in native_html:
         html = native_html.replace("LazyFrame", "LazyFrame.to_native()")
         return f"{html}<p><b>{header}</b></p>"

From 3748f2375c8fda23e63f5fea226b50367e5fd46e Mon Sep 17 00:00:00 2001
From: dangotbanned <125183946+dangotbanned@users.noreply.github.com>
Date: Wed, 9 Jul 2025 17:39:01 +0100
Subject: [PATCH 4/6] feat: Support `pl.Series._repr_html_`

- `pandas` only supports it for `pd.DataFrame`
---
 narwhals/_utils.py | 3 ++-
 narwhals/series.py | 8 ++++++++
 2 files changed, 10 insertions(+), 1 deletion(-)

diff --git a/narwhals/_utils.py b/narwhals/_utils.py
index c8b353e834..a2b316767a 100644
--- a/narwhals/_utils.py
+++ b/narwhals/_utils.py
@@ -1581,7 +1581,8 @@ def generate_repr(header: str, native_repr: str) -> str:
 
 # NOTE: Unsure on how to test this reliably
 def generate_repr_html(
-    header: Literal["Narwhals DataFrame", "Narwhals LazyFrame"], native_html: str
+    header: Literal["Narwhals DataFrame", "Narwhals LazyFrame", "Narwhals Series"],
+    native_html: str,
 ) -> str | None:  # pragma: no cover
     if header == "Narwhals LazyFrame" and "LazyFrame" in native_html:
         html = native_html.replace("LazyFrame", "LazyFrame.to_native()")
diff --git a/narwhals/series.py b/narwhals/series.py
index 9bbd6ed5a7..b4be693fbf 100644
--- a/narwhals/series.py
+++ b/narwhals/series.py
@@ -6,9 +6,11 @@
 
 from narwhals._utils import (
     Implementation,
+    _hasattr_static,
     _validate_rolling_arguments,
     ensure_type,
     generate_repr,
+    generate_repr_html,
     is_compliant_series,
     is_index_selector,
     supports_arrow_c_stream,
@@ -336,6 +338,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)
 

From 57e333d20ec1f51b3b044b2eedce01e40ac6e6f3 Mon Sep 17 00:00:00 2001
From: dangotbanned <125183946+dangotbanned@users.noreply.github.com>
Date: Sun, 3 Aug 2025 16:24:28 +0000
Subject: [PATCH 5/6] rename `header` -> `caption_text`

https://github.com/narwhals-dev/narwhals/pull/2776#discussion_r2216840450
---
 narwhals/_utils.py | 9 +++++----
 1 file changed, 5 insertions(+), 4 deletions(-)

diff --git a/narwhals/_utils.py b/narwhals/_utils.py
index 4e89d7281c..94577ad048 100644
--- a/narwhals/_utils.py
+++ b/narwhals/_utils.py
@@ -1544,12 +1544,13 @@ def generate_repr(header: str, native_repr: str) -> str:
 
 # NOTE: Unsure on how to test this reliably
 def generate_repr_html(
-    header: Literal["Narwhals DataFrame", "Narwhals LazyFrame", "Narwhals Series"],
+    caption_text: Literal["Narwhals DataFrame", "Narwhals LazyFrame", "Narwhals Series"],
+    /,
     native_html: str,
 ) -> str | None:  # pragma: no cover
-    if header == "Narwhals LazyFrame" and "LazyFrame" in native_html:
+    if caption_text == "Narwhals LazyFrame" and "LazyFrame" in native_html:
         html = native_html.replace("LazyFrame", "LazyFrame.to_native()")
-        return f"{html}<p><b>{header}</b></p>"
+        return f"{html}<p><b>{caption_text}</b></p>"
     import io
     import xml.etree.ElementTree as ET
 
@@ -1569,7 +1570,7 @@ def generate_repr_html(
     if table is None:
         return None
     caption = ET.Element("caption")
-    caption.text = header
+    caption.text = caption_text
     table.insert(0, caption)
     style = tree.find("style")
     if style is not None:

From 7758265b09d4323ea442314bd19f0591cfb1b79a Mon Sep 17 00:00:00 2001
From: dangotbanned <125183946+dangotbanned@users.noreply.github.com>
Date: Sun, 3 Aug 2025 16:50:58 +0000
Subject: [PATCH 6/6] change `caption-side` to `top`

Related https://github.com/narwhals-dev/narwhals/pull/2776#discussion_r2250045077
---
 narwhals/_utils.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/narwhals/_utils.py b/narwhals/_utils.py
index 94577ad048..0f43ae3e12 100644
--- a/narwhals/_utils.py
+++ b/narwhals/_utils.py
@@ -1556,7 +1556,7 @@ def generate_repr_html(
 
     style_css = (
         ".dataframe caption { "
-        "caption-side: bottom; "
+        "caption-side: top; "
         "text-align: center; "
         "font-weight: bold; "
         "padding-top: 8px;"