Revert breaking changes to scratch API

Save for next major version bump

CHANGELOG.md

@@ -1,19 +1,14 @@
 # PyNWB Changelog
 
-## PyNWB 2.0.0 (Upcoming)
-
-### Breaking changes:
-- The 'notes' and 'table_description' arguments of `NWBFile.add_scratch(...)` are now replaced by a 'description'
-  argument that is required when a scalar, numpy.ndarray, list, tuple, or pandas.DataFrame is added to scratch. The
-  'notes' argument of `ScratchData.__init__(...)` is now replaced by the required 'description' argument for
-  consistency. Previously, 'notes' had a default value of empty string, which is not recommended. @rly (#1309)
+## PyNWB 1.5.0 (April 23, 2021)
 
 ### New features:
 - `NWBFile.add_scratch(...)` and `ScratchData.__init__(...)` now accept scalar data in addition to the currently
   accepted types. @rly (#1309)
 - Support `pathlib.Path` paths when opening files with `NWBHDF5IO`. @dsleiter (#1314)
-- Use HDMF 2.4.0. See the [HDMF 2.4.0 release notes](https://github.com/hdmf-dev/hdmf/releases/tag/2.4.0) for details.
+- Use HDMF 2.5.1. See the [HDMF release notes](https://github.com/hdmf-dev/hdmf/releases/tag/2.5.1) for details.
 - Support `driver='ros3'` in `NWBHDF5IO` for streaming NWB files directly from s3. @bendichter (#1331)
+........ TODO
 
 ## PyNWB 1.4.0 (August 12, 2020)
 

src/pynwb/core.py

@@ -1,4 +1,5 @@
 import numpy as np
+from warnings import warn
 
 from hdmf import Container, Data
 from hdmf.container import AbstractContainer, MultiContainerInterface as hdmf_MultiContainerInterface, Table
@@ -88,14 +89,39 @@ def extend(self, arg):
 @register_class('ScratchData', CORE_NAMESPACE)
 class ScratchData(NWBData):
 
-    __nwbfields__ = ('description',)
+    __nwbfields__ = ('description', )
 
     @docval({'name': 'name', 'type': str, 'doc': 'the name of this container'},
             {'name': 'data', 'type': ('scalar_data', 'array_data', 'data', Data), 'doc': 'the source of the data'},
-            {'name': 'description', 'type': str, 'doc': 'description of the data'})
+            {'name': 'notes', 'type': str,
+             'doc': 'notes about the data. This argument will be deprecated. Use description instead', 'default': ''},
+            {'name': 'description', 'type': str, 'doc': 'notes about the data', 'default': None})
     def __init__(self, **kwargs):
         call_docval_func(super().__init__, kwargs)
-        self.description = getargs('description', kwargs)
+        notes, description = getargs('notes', 'description', kwargs)
+        if notes != '':
+            warn('The `notes` argument of ScratchData.__init__ will be deprecated. Use description instead.',
+                 PendingDeprecationWarning)
+            if notes != '' and description != '':
+                raise ValueError('Cannot provide both notes and description to ScratchData.__init__. The description '
+                                 'argument is recommended.')
+            description = notes
+        if not description:
+            warn('ScratchData.description will be required in a future major release of PyNWB.',
+                 PendingDeprecationWarning)
+        self.description = description
+
+    @property
+    def notes(self):
+        warn('Use of ScratchData.notes will be deprecated. Use ScratchData.description instead.',
+             PendingDeprecationWarning)
+        return self.description
+
+    @notes.setter
+    def notes(self, value):
+        warn('Use of ScratchData.notes will be deprecated. Use ScratchData.description instead.',
+             PendingDeprecationWarning)
+        self.description = value
 
 
 class NWBTable(Table):

src/pynwb/file.py

@@ -674,29 +674,51 @@ def add_stimulus_template(self, timeseries):
              'type': ('scalar_data', np.ndarray, list, tuple, pd.DataFrame, DynamicTable, NWBContainer, ScratchData),
              'doc': 'The data to add to the scratch space.'},
             {'name': 'name', 'type': str,
-             'doc': ('The name of the data. Required only when passing in a scalar, numpy.ndarray, '
-                     'list, tuple, or pandas.DataFrame'),
+             'doc': 'The name of the data. Required only when passing in a scalar, numpy.ndarray, list, or tuple',
              'default': None},
+            {'name': 'notes', 'type': str,
+             'doc': ('Notes to add to the data. Only used when passing in numpy.ndarray, list, or tuple. This '
+                     'argument is not recommended. Use the `description` argument instead.'),
+             'default': None},
+            {'name': 'table_description', 'type': str,
+             'doc': ('Description for the internal DynamicTable used to store a pandas.DataFrame. This '
+                     'argument is not recommended. Use the `description` argument instead.'),
+             'default': ''},
             {'name': 'description', 'type': str,
              'doc': ('Description of the data. Required only when passing in a scalar, numpy.ndarray, '
                      'list, tuple, or pandas.DataFrame. Ignored when passing in an NWBContainer, '
                      'DynamicTable, or ScratchData object.'),
              'default': None})
     def add_scratch(self, **kwargs):
-        '''Add data to the scratch space.'''
-        data, name, description = getargs('data', 'name', 'description', kwargs)
+        '''Add data to the scratch space'''
+        data, name, notes, table_description, description = getargs('data', 'name', 'notes', 'table_description',
+                                                                    'description', kwargs)
+        if notes is not None or table_description != '':
+            warn('Use of the `notes` or `table_description` argument will be removed in a future version of PyNWB. '
+                 'Use the `description` argument instead.', PendingDeprecationWarning)
+            if description is not None:
+                raise ValueError('Cannot call add_scratch with (notes or table_description) and description')
+
         if isinstance(data, (str, int, float, bytes, np.ndarray, list, tuple, pd.DataFrame)):
             if name is None:
                 msg = ('A name is required for NWBFile.add_scratch when adding a scalar, numpy.ndarray, '
                        'list, tuple, or pandas.DataFrame as scratch data.')
                 raise ValueError(msg)
-            if description is None:
-                msg = ('A description is required for NWBFile.add_scratch when adding a scalar, numpy.ndarray, '
-                       'list, tuple, or pandas.DataFrame as scratch data.')
-                raise ValueError(msg)
             if isinstance(data, pd.DataFrame):
+                if table_description != '':
+                    description = table_description  # remove after deprecation
+                if description is None:
+                    msg = ('A description is required for NWBFile.add_scratch when adding a scalar, numpy.ndarray, '
+                           'list, tuple, or pandas.DataFrame as scratch data.')
+                    raise ValueError(msg)
                 data = DynamicTable.from_dataframe(df=data, name=name, table_description=description)
             else:
+                if notes is not None:
+                    description = notes  # remove after deprecation
+                if description is None:
+                    msg = ('A description is required for NWBFile.add_scratch when adding a scalar, numpy.ndarray, '
+                           'list, tuple, or pandas.DataFrame as scratch data.')
+                    raise ValueError(msg)
                 data = ScratchData(name=name, data=data, description=description)
         else:
             if name is not None:
@@ -707,8 +729,8 @@ def add_scratch(self, **kwargs):
                      'DynamicTable to scratch.')
         return self._add_scratch(data)
 
-    @docval({'name': 'name', 'type': str, 'help': 'the name of the object to get'},
-            {'name': 'convert', 'type': bool, 'help': 'return the original data, not the NWB object', 'default': True})
+    @docval({'name': 'name', 'type': str, 'doc': 'the name of the object to get'},
+            {'name': 'convert', 'type': bool, 'doc': 'return the original data, not the NWB object', 'default': True})
     def get_scratch(self, **kwargs):
         '''Get data from the scratch space'''
         name, convert = getargs('name', 'convert', kwargs)