feat: Add HTML representation

.gitignore

@@ -19,6 +19,7 @@ __pycache__/
 # Test results (nunit/junit) and coverage
 /test-data/
 /*coverage*
+tests/repr_html_visual_test.html
 
 # jupyter
 .ipynb_checkpoints

.vscode/settings.json

@@ -1,5 +1,5 @@
 {
-    "[python][toml][json][jsonc]": {
+    "[python][javascript][toml][json][jsonc]": {
         "editor.formatOnSave": true,
         "editor.codeActionsOnSave": {
             "source.organizeImports": "explicit",
@@ -12,7 +12,7 @@
     "[toml]": {
         "editor.defaultFormatter": "tamasfe.even-better-toml",
     },
-    "[json][jsonc]": {
+    "[javascript][json][jsonc]": {
         "editor.defaultFormatter": "biomejs.biome",
     },
     "python.analysis.typeCheckingMode": "basic",

biome.jsonc

@@ -1,6 +1,18 @@
 {
-    "$schema": "https://biomejs.dev/schemas/2.1.1/schema.json",
+    "$schema": "https://biomejs.dev/schemas/2.3.12/schema.json",
     "formatter": { "useEditorconfig": true },
+    "linter": {
+        "rules": {
+            "complexity": {
+                "noForEach": "on",
+            },
+        },
+    },
+    "javascript": {
+        "formatter": {
+            "semicolons": "asNeeded",
+        },
+    },
     "overrides": [
         {
             "includes": ["./.vscode/*.json", "**/*.jsonc", "**/asv.conf.json"],

docs/release-notes/2236.feat.md

@@ -0,0 +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`

pyproject.toml

@@ -266,7 +266,7 @@ max-positional-args = 5
 
 [tool.codespell]
 skip = ".git,*.pdf,*.svg"
-ignore-words-list = "theis,coo,homogenous,GroupT"
+ignore-words-list = "theis,coo,homogenous,vart,GroupT"
 
 [tool.towncrier]
 package = "anndata"

src/anndata/_core/anndata.py

@@ -556,6 +556,64 @@ def __repr__(self) -> str:
         else:
             return self._gen_repr(self.n_obs, self.n_vars)
 
+    def _repr_html_(self) -> str | None:
+        """Rich HTML representation for Jupyter notebooks.
+
+        Returns an interactive HTML representation with:
+
+        - Foldable sections for each attribute (auto-collapse for large sections)
+        - Search/filter functionality across all fields
+        - Copy-to-clipboard buttons for field names
+        - Color visualization for categorical data with color palettes
+        - Serialization warnings for non-serializable types
+        - Memory usage and version information
+        - Dark mode support (auto-detects Jupyter/VS Code themes)
+        - Graceful degradation when JavaScript is disabled
+
+        The representation can be configured via :attr:`anndata.settings`:
+
+        - ``repr_html_enabled``: Enable/disable HTML repr (default: True)
+        - ``repr_html_fold_threshold``: Auto-fold sections with more entries (default: 5)
+        - ``repr_html_max_depth``: Max recursion depth for nested AnnData (default: 3)
+        - ``repr_html_max_items``: Max items to show per section (default: 200)
+        - ``repr_html_max_categories``: Max category values to display inline (default: 100)
+        - ``repr_html_unique_limit``: Max rows for unique count computation (default: 1M)
+        - ``repr_html_max_field_width``: Max width in pixels for field name column (default: 400)
+        - ``repr_html_type_width``: Width in pixels for type column (default: 220)
+
+        Examples
+        --------
+        Disable HTML representation globally:
+
+        >>> import anndata
+        >>> anndata.settings.repr_html_enabled = False
+
+        Temporarily change settings using context manager::
+
+            with anndata.settings.override(repr_html_fold_threshold=10):
+                display(adata)  # Sections fold only when >10 items
+
+        Returns
+        -------
+        str | None
+            HTML string if enabled, None otherwise (falls back to text repr).
+        """
+        if not settings.repr_html_enabled:
+            return None
+
+        try:
+            from anndata._repr import generate_repr_html
+
+            return generate_repr_html(self)
+        except Exception as e:  # noqa: BLE001
+            # Intentional broad catch: HTML repr should never crash the notebook
+            # Fall back to text repr if HTML generation fails, but log the error
+            warn(
+                f"HTML repr failed, falling back to text repr: {e}",
+                UserWarning,
+            )
+            return None
+
     def __eq__(self, other):
         """Equality testing"""
         msg = (