Jinja + MarkupSafe adoption for AnnData._repr_html_

docs/release-notes/2236.feat.md

@@ -1 +1 @@
-Add rich HTML representation for {class}`~anndata.AnnData` objects in Jupyter notebooks with foldable sections, search/filter, category color visualization, dark mode support, and configurable settings via {attr}`anndata.settings`
+Add rich HTML representation for {class}`~anndata.AnnData` objects in Jupyter notebooks with foldable sections, search/filter, category color visualization, dark mode support, and configurable settings via {attr}`anndata.settings`. Rendering is built on {mod}`jinja2` and {mod}`markupsafe` with autoescape-by-default; extension packages register {class}`~anndata._repr.TypeFormatter` / {class}`~anndata._repr.SectionFormatter` subclasses that return {class}`~anndata._repr.FormattedOutput` with {class}`markupsafe.Markup`-typed HTML fragments (`preview_markup`, `type_markup`, `expanded_markup`).

pyproject.toml

@@ -47,6 +47,8 @@ dependencies = [
     "zarr >=3.1",
     "typing-extensions; python_version<'3.13'",
     "scverse-misc>=0.0.3",
+    "jinja2>=3.1",
+    "markupsafe>=3.0",
 ]
 dynamic = [ "version" ]
 

src/anndata/_repr/__init__.py

@@ -68,6 +68,8 @@
 
     Example - format by Python type::
 
+        from markupsafe import Markup
+
         from anndata._repr import register_formatter, TypeFormatter, FormattedOutput
 
 
@@ -82,10 +84,27 @@ def format(self, obj, context):
                 return FormattedOutput(
                     type_name=f"MyArray {obj.shape}",
                     css_class="anndata-dtype--myarray",
-                    # preview_html provides HTML for the preview column (rightmost)
-                    preview_html=f'<span class="anndata-text--muted">({obj.n_items} items)</span>',
+                    # ``preview_markup`` takes trusted HTML. Build it with
+                    # ``Markup('<tag>{}</tag>').format(value)`` — MarkupSafe
+                    # autoescapes each non-``Markup`` arg at that boundary.
+                    preview_markup=Markup(
+                        '<span class="mypackage-summary">{} items</span>'
+                    ).format(obj.n_items),
                 )
 
+    **Preview contract**: if no custom HTML is needed, prefer the plain-text
+    ``preview`` field (autoescaped end-to-end). Use ``preview_markup`` when
+    you need custom structure. Three valid idioms:
+
+    - ``Markup('<tag>{}</tag>').format(value)`` — standard MarkupSafe pattern;
+      each non-``Markup`` arg is autoescaped.
+    - ``Markup(obj._repr_html_())`` — wrap trusted HTML from another package.
+    - ``get_macros().my_macro(value)`` — invoke a Jinja macro directly, which
+      also benefits from the engine's NUL-scrub finalize hook.
+
+    Never build HTML via ``Markup(f'...{value}...')`` — the f-string substitutes
+    ``value`` before ``Markup`` sees it, bypassing autoescape.
+
     **Error handling**: Formatters can signal errors in two ways:
 
     1. **Raise an exception** - The registry catches it, emits a warning with the
@@ -97,10 +116,12 @@ def format(self, obj, context):
        ``FormattedOutput(error="reason")`` directly. The row will be highlighted
        red and the error shown in the preview column.
 
-    When ``error`` is set, it takes precedence over ``preview`` and ``preview_html``.
+    When ``error`` is set, it takes precedence over ``preview`` and ``preview_markup``.
 
     Example - format by embedded type hint (for tagged data in uns)::
 
+        from markupsafe import Markup
+
         from anndata._repr import register_formatter, TypeFormatter, FormattedOutput
         from anndata._repr import extract_uns_type_hint
 
@@ -118,7 +139,9 @@ def format(self, obj, context):
                 hint, data = extract_uns_type_hint(obj)
                 return FormattedOutput(
                     type_name="config",
-                    preview_html="<span>Custom config preview</span>",
+                    preview_markup=Markup(
+                        '<span class="anndata-text--muted">{}</span>'
+                    ).format(data.get("name", "(unnamed)")),
                 )
 
     Data structure for type hints (works in any section)::
@@ -277,7 +300,7 @@ def _repr_html_(self):
         parts.append(
             render_section(
                 "items",
-                "\\n".join(entries),
+                Markup("\\n").join(entries),
                 n_items=len(self.items),
             )
         )
@@ -290,12 +313,12 @@ def _repr_html_(self):
 
     from anndata._repr import generate_repr_html, FormattedEntry, FormattedOutput
 
-    nested_html = generate_repr_html(adata, depth=1, max_depth=3)
+    # generate_repr_html already returns Markup; no Markup(...) wrap needed.
     entry = FormattedEntry(
         key="table",
         output=FormattedOutput(
             type_name=f"AnnData ({adata.n_obs} x {adata.n_vars})",
-            expanded_html=nested_html,  # Collapsible content below the row
+            expanded_markup=generate_repr_html(adata, depth=1, max_depth=3),
         ),
     )
 
@@ -321,7 +344,6 @@ def _repr_html_(self):
     DEFAULT_PREVIEW_ITEMS,
     DEFAULT_TYPE_WIDTH,
     DEFAULT_UNIQUE_LIMIT,
-    NOT_SERIALIZABLE_MSG,
 )
 
 # Documentation base URL
@@ -346,10 +368,6 @@ def get_section_doc_url(section: str) -> str:
     return f"{DOCS_BASE_URL}generated/anndata.AnnData.{section}.html"
 
 
-# Import main functionality
-# Inline styles for graceful degradation (from single source of truth)
-from .._repr_constants import STYLE_HIDDEN  # noqa: E402
-
 # Building blocks for packages that want to create their own _repr_html_
 # These allow reusing anndata's styling while building custom representations
 from .components import (  # noqa: E402
@@ -361,6 +379,7 @@ def get_section_doc_url(section: str) -> str:
     render_warning_icon,
 )
 from .css import get_css  # noqa: E402
+from .environment import get_macros  # noqa: E402
 from .html import (  # noqa: E402
     generate_repr_html,
     render_formatted_entry,
@@ -384,7 +403,6 @@ def get_section_doc_url(section: str) -> str:
 
 # HTML rendering helpers for building custom sections
 from .utils import (  # noqa: E402
-    escape_html,
     format_memory_size,
     format_number,
     validate_key,
@@ -402,9 +420,6 @@ def get_section_doc_url(section: str) -> str:
     "DEFAULT_UNIQUE_LIMIT",
     "DEFAULT_MAX_FIELD_WIDTH",
     "DEFAULT_TYPE_WIDTH",
-    "DOCS_BASE_URL",
-    "get_section_doc_url",
-    "NOT_SERIALIZABLE_MSG",
     # CSS dtype constants for custom formatters
     "CSS_DTYPE_NDARRAY",
     "CSS_DTYPE_ANNDATA",
@@ -425,12 +440,11 @@ def get_section_doc_url(section: str) -> str:
     # Building blocks for custom _repr_html_ implementations
     "get_css",
     "get_javascript",
-    "escape_html",
+    "get_macros",
     "format_number",
     "format_memory_size",
     "render_section",
     "render_formatted_entry",
-    "STYLE_HIDDEN",
     # UI component helpers
     "render_search_box",
     "render_copy_button",