Small refactor to HERDManager

CHANGELOG.md

@@ -13,6 +13,7 @@
 
 ### Changed
 - Changed error for attempting to overwrite an existing specification into a warning that any specification redefinitions will be ignored. @stephprince [#1309](https://github.com/hdmf-dev/hdmf/pull/1309)
+- Deprecated the experimental `HERDManager.link_resources` and `HERDManager.link_external_resources` and added the property `HERDManager.external_resources` to support downstream API function overloading. @mavaylon1, @rly [#1292](https://github.com/hdmf-dev/hdmf/pull/1292)
 
 
 ## HDMF 4.1.0 (May 28, 2025)

src/hdmf/backends/io.py

@@ -64,7 +64,7 @@ def read(self, **kwargs):
             try:
                 self.herd = HERD.from_zip(path=self.herd_path)
                 if isinstance(container, HERDManager):
-                    container.link_resources(herd=self.herd)
+                    container.external_resources = self.herd
             except FileNotFoundError:
                 msg = "File not found at {}. HERD not added.".format(self.herd_path)
                 warn(msg)

src/hdmf/container.py

@@ -16,6 +16,7 @@
 
 from .term_set import TermSet, TermSetWrapper
 
+
 def _set_exp(cls):
     """Set a class as being experimental"""
     cls._experimental = True
@@ -33,7 +34,7 @@ def _exp_warn_msg(cls):
 
 class HERDManager:
     """
-    This class manages whether to set/attach an instance of HERD to the subclass.
+    When this class is used as a mixin for a Container, it enables setting and getting an instance of HERD.
     """
 
     @docval({'name': 'herd', 'type': 'HERD',
@@ -42,11 +43,31 @@ def link_resources(self, **kwargs):
         """
         Method to attach an instance of HERD in order to auto-add terms/references to data.
         """
-        self._herd = kwargs['herd']
+        msg = (
+            "link_resources is deprecated and will be removed in HDMF 5.0. "
+            "Use the external_resources property instead."
+        )
+        warn(msg, DeprecationWarning, stacklevel=2)
+        self.external_resources = kwargs['herd']
 
     def get_linked_resources(self):
+        msg = (
+            "get_linked_resources is deprecated and will be removed in HDMF 5.0. "
+            "Use the external_resources property instead."
+        )
+        warn(msg, DeprecationWarning, stacklevel=2)
+        return self.external_resources
+
+    @property
+    def external_resources(self):
         return self._herd if hasattr(self, "_herd") else None
 
+    @external_resources.setter
+    def external_resources(self, herd):
+        if hasattr(self, "_herd"):
+            warn("Reassigning external_resources may lead to unexpected behavior.")
+        self._herd = herd
+
 
 class AbstractContainer(metaclass=ExtenderMeta):
     # The name of the class attribute that subclasses use to autogenerate properties

tests/unit/common/test_resources.py

@@ -309,7 +309,7 @@ def test_add_ref_container_data(self):
         terms = TermSet(term_schema_path='tests/unit/example_test_term_set.yaml')
         er = HERD()
         em = HERDManagerContainer()
-        em.link_resources(er)
+        em.external_resources = er
 
         # create children and add parent
         col1 = VectorData(
@@ -332,7 +332,7 @@ def test_add_ref_container_attr(self):
         terms = TermSet(term_schema_path='tests/unit/example_test_term_set.yaml')
         er = HERD()
         em = HERDManagerContainer()
-        em.link_resources(er)
+        em.external_resources = er
 
         # create children and add parent
         col1 = VectorData(

tests/unit/test_container.py

@@ -25,14 +25,31 @@ def __init__(self, **kwargs):
 
 
 class TestHERDManager(TestCase):
-    def test_link_and_get_resources(self):
+    def test_get_and_set_resources(self):
         em = HERDManager()
         er = HERD()
 
-        em.link_resources(er)
-        er_get = em.get_linked_resources()
+        em.external_resources = er
+        self.assertEqual(em.external_resources, er)
+
+        er_get = em.external_resources
         self.assertEqual(er, er_get)
 
+    def test_link_resources_deprecated(self):
+        em = HERDManager()
+        er = HERD()
+        with self.assertWarns(DeprecationWarning):
+            em.link_resources(herd=er)
+        self.assertEqual(em.external_resources, er)
+
+    def test_get_linked_resources_deprecated(self):
+        em = HERDManager()
+        er = HERD()
+        em.external_resources = er
+        with self.assertWarns(DeprecationWarning):
+            herd = em.get_linked_resources()
+        self.assertEqual(herd, er)
+
 
 class TestContainer(TestCase):
 

tests/unit/test_io_hdf5_h5tools.py

@@ -1081,7 +1081,7 @@ def test_io_read_herd(self):
         with HDF5IO(self.path, manager=self.manager, mode='r', herd_path='./HERD.zip') as io:
             container = io.read()
             self.assertIsInstance(io.herd, HERD)
-            self.assertIsInstance(container.get_linked_resources(), HERD)
+            self.assertIsInstance(container.external_resources, HERD)
         self.remove_er_files()
 
     def test_io_read_herd_file_warn(self):