Deprecate NWBGroupSpec.add_group, add_dataset

CHANGELOG.md

@@ -1,5 +1,10 @@
 # PyNWB Changelog
 
+## PyNWB 4.0.0 (Unreleased)
+
+## Changed
+- Deprecated `NWBGroupSpec.add_group` and `NWBGroupSpec.add_dataset`. Use `NWBGroupSpec.set_group`, `NWBGroupSpec.set_dataset`, or pass the group or dataset to the `NWBGroupSpec` constructor. @rly [#2138](https://github.com/NeurodataWithoutBorders/pynwb/issues/2138)
+
 ## PyNWB 3.1.3 (Unreleased)
 
 ### Added

src/pynwb/spec.py

@@ -1,4 +1,5 @@
 from copy import copy, deepcopy
+from warnings import warn
 
 from hdmf.spec import (LinkSpec, GroupSpec, DatasetSpec, SpecNamespace, NamespaceBuilder,
                        AttributeSpec, DtypeSpec, RefSpec)
@@ -190,6 +191,12 @@ def get_neurodata_type(self, **kwargs):
     @docval(*deepcopy(_group_docval))
     def add_group(self, **kwargs):
         ''' Add a new specification for a subgroup to this group specification '''
+        warn(
+            "NWBGroupSpec.add_group is deprecated and will be removed in PyNWB 5.0. "
+            "Use NWBGroupSpec.set_group instead.",
+            DeprecationWarning, 
+            stacklevel=2
+        )
         doc = kwargs.pop('doc')
         spec = NWBGroupSpec(doc, **kwargs)
         self.set_group(spec)
@@ -198,6 +205,12 @@ def add_group(self, **kwargs):
     @docval(*deepcopy(_dataset_docval))
     def add_dataset(self, **kwargs):
         ''' Add a new specification for a subgroup to this group specification '''
+        warn(
+            "NWBGroupSpec.add_dataset is deprecated and will be removed in PyNWB 5.0. "
+            "Use NWBGroupSpec.set_dataset instead.",
+            DeprecationWarning, 
+            stacklevel=2
+        )
         doc = kwargs.pop('doc')
         spec = NWBDatasetSpec(doc, **kwargs)
         self.set_dataset(spec)

tests/unit/test_spec.py

@@ -86,13 +86,14 @@ def test_add_group(self):
             linkable=True,
             name='Group1',
         )
-        spec.add_group(
-            doc='A test group',
-            neurodata_type_def='TimeSeries',
-            neurodata_type_inc='NWBData',
-            linkable=True,
-            name='Group2',
-        )
+        with self.assertWarns(DeprecationWarning):
+            spec.add_group(
+                doc='A test group',
+                neurodata_type_def='TimeSeries',
+                neurodata_type_inc='NWBData',
+                linkable=True,
+                name='Group2',
+            )
         self.assertEqual(len(spec.groups), 1)
         self.assertEqual(spec.groups[0].name, 'Group2')
         self.assertIsInstance(spec.groups[0], NWBGroupSpec)
@@ -105,14 +106,15 @@ def test_add_dataset(self):
             linkable=True,
             name='Group1',
         )
-        spec.add_dataset(
-            doc='A test dataset',
-            name='dataset1',
-            dtype='int',
-            shape=(None,),
-            dims=('time',),
-            quantity='?',
-        )
+        with self.assertWarns(DeprecationWarning):
+            spec.add_dataset(
+                doc='A test dataset',
+                name='dataset1',
+                dtype='int',
+                shape=(None,),
+                dims=('time',),
+                quantity='?',
+            )
         self.assertEqual(len(spec.datasets), 1)
         self.assertEqual(spec.datasets[0].name, 'dataset1')
         self.assertIsInstance(spec.datasets[0], NWBDatasetSpec)