Add HERD repr/_repr_html_ surfacing references as a flattened table (#1510)

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: rly

CHANGELOG.md

@@ -3,6 +3,7 @@
 ## HDMF 6.0.3 (Upcoming)
 
 ### Enhancements
+- Added a `HERD`-specific `__repr__` and `_repr_html_` that surface the references as a flattened table, so a `HERD` (especially one read back from a file) no longer appears empty in its default display. @rly [#1510](https://github.com/hdmf-dev/hdmf/pull/1510)
 - `HERD.add_ref` now defaults `key` to the value of a scalar string `attribute` when `key` is not provided, removing the redundant argument in the common case. @rly [#1511](https://github.com/hdmf-dev/hdmf/pull/1511)
 
 ### Fixed

src/hdmf/common/resources.py

@@ -987,6 +987,50 @@ def to_dataframe(self, **kwargs):
         # return the result
         return result_df
 
+    def __flattened_dataframe_or_none(self):
+        """Return the flattened ``to_dataframe()`` view, or None when there are no references.
+
+        ``to_dataframe`` raises when the HERD holds no object-key relationships and may fail if the
+        backing file is closed. The repr methods use this helper so they never raise on display.
+        """
+        if len(self.object_keys) == 0:
+            return None
+        try:
+            return self.to_dataframe()
+        except Exception:
+            return None
+
+    def __summary_line(self):
+        """Return a one-line summary of the table sizes."""
+        return ("%d key(s), %d entity(ies), %d object(s), %d file(s)"
+                % (len(self.keys), len(self.entities), len(self.objects), len(self.files)))
+
+    def __repr__(self):
+        cls = self.__class__
+        template = "%s %s.%s at 0x%d" % (self.name, cls.__module__, cls.__name__, id(self))
+        template += "\n  " + self.__summary_line()
+        df = self.__flattened_dataframe_or_none()
+        if df is not None and len(df) > 0:
+            template += "\n" + repr(df)
+        return template
+
+    def _repr_html_(self):
+        """Generate an HTML representation that surfaces the references as a flattened table."""
+        header_text = self.name if self.name == self.__class__.__name__ else \
+            f"{self.name} ({self.__class__.__name__})"
+        html_repr = self.css_style + self.js_script
+        html_repr += "<div class='container-wrap'>"
+        html_repr += f"<div class='container-header'><div class='xr-obj-type'><h3>{header_text}</h3></div></div>"
+        html_repr += self._closed_file_warning_html()
+        html_repr += f"<p class='container-fields'>{self.__summary_line()}</p>"
+        df = self.__flattened_dataframe_or_none()
+        if df is None or len(df) == 0:
+            html_repr += "<p class='container-fields'>No external resource references.</p>"
+        else:
+            html_repr += df.to_html()
+        html_repr += "</div>"
+        return html_repr
+
     @docval({'name': 'path', 'type': str, 'doc': 'The path to the zip file.'})
     def to_zip(self, **kwargs):
         """

tests/unit/common/test_resources.py

@@ -131,6 +131,27 @@ def test_to_dataframe(self):
                                           'entities_idx': 'uint32'})
         pd.testing.assert_frame_equal(result_df, expected_df)
 
+    def test_repr_empty(self):
+        er = HERD()
+        # repr and HTML repr must not raise on an empty HERD (to_dataframe raises when empty)
+        self.assertIn('0 key(s)', repr(er))
+        html = er._repr_html_()
+        self.assertIn('No external resource references', html)
+
+    def test_repr_populated(self):
+        er = HERD()
+        er.add_ref(file=HERDManagerContainer(name='file'),
+                   container=Container(name='Container'),
+                   key='Mus musculus',
+                   entity_id='NCBI_TAXON:10090',
+                   entity_uri='http://x')
+        text = repr(er)
+        self.assertIn('1 key(s), 1 entity(ies), 1 object(s), 1 file(s)', text)
+        # the HTML repr surfaces the flattened table content
+        html = er._repr_html_()
+        self.assertIn('NCBI_TAXON:10090', html)
+        self.assertIn('http://x', html)
+
     def test_assert_external_resources_equal(self):
         file = HERDManagerContainer(name='file')
         ref_container_1 = Container(name='Container_1')