Skip to content

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

Merged
rly merged 2 commits into
devfrom
enh/herd-repr
Jun 23, 2026
Merged

Add HERD repr/_repr_html_ surfacing references as a flattened table#1510
rly merged 2 commits into
devfrom
enh/herd-repr

Conversation

@rly

@rly rly commented Jun 23, 2026

Copy link
Copy Markdown
Contributor

Motivation

Fixes #1508.

HERD inherits the generic Container._repr_html_, which renders its six child tables as nested collapsibles. For a HERD read back from a file these can appear empty at first glance, even though the data is present and accessible via to_dataframe() and the individual tables. The PyNWB HERD tutorial (NeurodataWithoutBorders/pynwb#2200) currently has to warn users about this. The underlying need was raised in NeurodataWithoutBorders/nwb-schema#652.

Solution

Add a HERD-specific __repr__ and _repr_html_ that show a one-line summary (table sizes) plus the flattened to_dataframe() view (one row per object/key/entity association). The display falls back gracefully:

  • empty HERD: shows "No external resource references." (to_dataframe raises when there are no object-key rows, so the helper guards on that);
  • closed backing file or any to_dataframe failure: the existing closed-file warning banner is preserved and the table is omitted rather than raising (a repr must never raise).

Display only; no change to stored data or table APIs.

Screenshot

The _repr_html_ of a populated HERD, rendered as a Jupyter output cell:

HERD repr_html rendered in a Jupyter output cell

How to test the behavior

Added test_repr_empty and test_repr_populated in tests/unit/common/test_resources.py (empty HERD reprs do not raise and say "No external resource references"; a populated HERD surfaces the summary line and the entity content in the HTML repr). Full tests/unit/common/test_resources.py passes (63 passed, 10 skipped).

Checklist

  • Did you update CHANGELOG.md with your changes?
  • Have you checked our Contributing document?
  • Have you ensured the PR clearly describes the problem and the solution?
  • Is your contribution compliant with our coding style? This will be checked during CI.
  • Have you checked to ensure that there aren't other open Pull Requests for the same change?
  • Have you included the relevant issue number using "Fix #XXX" notation where XXX is the issue number.

🤖 Generated with Claude Code

A HERD (especially one read back from a file) rendered its six child tables
as nested collapsibles that can appear empty in Jupyter. Add a HERD-specific
__repr__ and _repr_html_ that show a one-line summary plus the flattened
to_dataframe() view, falling back gracefully when there are no references
(to_dataframe raises when empty) or the backing file is closed.

Addresses #1508.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@codecov

codecov Bot commented Jun 23, 2026

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 93.33333% with 2 lines in your changes missing coverage. Please review.
✅ Project coverage is 93.19%. Comparing base (abd0a7f) to head (77e4530).
⚠️ Report is 5 commits behind head on dev.

Files with missing lines Patch % Lines
src/hdmf/common/resources.py 93.33% 2 Missing ⚠️
Additional details and impacted files
@@           Coverage Diff           @@
##              dev    #1510   +/-   ##
=======================================
  Coverage   93.19%   93.19%           
=======================================
  Files          41       41           
  Lines       10191    10221   +30     
  Branches     2107     2110    +3     
=======================================
+ Hits         9497     9525   +28     
- Misses        416      418    +2     
  Partials      278      278           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

@rly rly enabled auto-merge (squash) June 23, 2026 18:23
@rly rly merged commit 895a284 into dev Jun 23, 2026
20 of 27 checks passed
@rly rly deleted the enh/herd-repr branch June 23, 2026 18:27
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

HERD: add a custom repr/_repr_html_ so a read-back HERD does not appear empty

2 participants