Add link_resources and get_external_resources to HERDManager

Move linked HERD functionality from NWBFile to HERDManager base class
so any HERDManager subclass can manage a secondary linked HERD alongside
the primary one.

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

Author: rly

CHANGELOG.md

@@ -3,7 +3,7 @@
 ## HDMF Unreleased
 
 ### Enhancements
-- Made `HERDManager` an abstract interface (ABC) with an abstract `external_resources` property. Subclasses must now declare `external_resources` in their `__fields__` to satisfy the interface. Updated `__gather_fields` to allow auto-generated properties to override inherited abstract properties. @rly [#1431](https://github.com/hdmf-dev/hdmf/pull/1431)
+- Made `HERDManager` an abstract interface (ABC) with an abstract `external_resources` property. Subclasses must now declare `external_resources` in their `__fields__` to satisfy the interface. Updated `__gather_fields` to allow auto-generated properties to override inherited abstract properties. Added `link_resources` and `get_external_resources` methods to `HERDManager` for managing a linked HERD separate from the primary one. @rly [#1431](https://github.com/hdmf-dev/hdmf/pull/1431)
 
 ## HDMF 5.0.1 (March 16, 2026)
 

src/hdmf/container.py

@@ -54,6 +54,10 @@ class MyFile(HERDManager, Container):
     external resources.
     """
 
+    def __init__(self, **kwargs):
+        super().__init__(**kwargs)
+        self._linked_external_resources = None
+
     @property
     @abstractmethod
     def external_resources(self):
@@ -64,6 +68,29 @@ def external_resources(self):
     def external_resources(self, val):
         pass
 
+    def link_resources(self, external_resources):
+        """Link an external HERD object as the external resources for this container.
+
+        The linked HERD will not be written on export; the original HERD
+        (if any) is preserved in the exported file. Use
+        ``get_external_resources(linked=True)`` to access the linked HERD.
+        """
+        self._linked_external_resources = external_resources
+
+    def get_external_resources(self, linked=False):
+        """Return the HERD external resources object for this container.
+
+        Parameters
+        ----------
+        linked : bool, optional
+            If True, return the linked HERD set via ``link_resources``.
+            If False (default), return the HERD set via ``__init__`` or the
+            ``external_resources`` attribute.
+        """
+        if linked:
+            return self._linked_external_resources
+        return self.external_resources
+
 
 class AbstractContainer(metaclass=ExtenderMeta):
     # The name of the class attribute that subclasses use to autogenerate properties

tests/unit/test_container.py

@@ -60,6 +60,36 @@ def test_mixin_external_resources_is_child(self):
         self.assertIn(er, container.children)
         self.assertIs(er.parent, container)
 
+    def test_link_resources(self):
+        """Test linking an external HERD object."""
+        container = ContainerWithHERD(name='test')
+        linked_herd = HERD()
+        container.link_resources(linked_herd)
+        self.assertIs(container.get_external_resources(linked=True), linked_herd)
+
+    def test_get_external_resources_default(self):
+        """Test get_external_resources returns the primary HERD by default."""
+        container = ContainerWithHERD(name='test')
+        er = HERD()
+        container.external_resources = er
+        self.assertIs(container.get_external_resources(), er)
+        self.assertIs(container.get_external_resources(linked=False), er)
+
+    def test_get_external_resources_linked_default_none(self):
+        """Test get_external_resources(linked=True) returns None when no linked HERD is set."""
+        container = ContainerWithHERD(name='test')
+        self.assertIsNone(container.get_external_resources(linked=True))
+
+    def test_link_resources_does_not_affect_primary(self):
+        """Test that linking a HERD does not overwrite the primary external_resources."""
+        container = ContainerWithHERD(name='test')
+        primary = HERD()
+        linked = HERD()
+        container.external_resources = primary
+        container.link_resources(linked)
+        self.assertIs(container.get_external_resources(), primary)
+        self.assertIs(container.get_external_resources(linked=True), linked)
+
 
 class TestContainer(TestCase):