Warn if writing a file without the appropriate extension (#1978)

* add warning for non nwb extension

* add tests and update test filenames

* update CHANGELOG.md

* Remove comment in tests

Author: stephprince

CHANGELOG.md

@@ -9,6 +9,9 @@
 - Fixed bug in how `ElectrodeGroup.__init__` validates its `position` argument. @oruebel [#1770](https://github.com/NeurodataWithoutBorders/pynwb/pull/1770)
 - Changed `SpatialSeries.reference_frame` from required to optional as specified in the schema. @rly [#1986](https://github.com/NeurodataWithoutBorders/pynwb/pull/1986)
 
+### Enhancements and minor changes`
+- Added warning when writing files with `NWBHDF5IO` without the `.nwb` extension. @stephprince [#1978](https://github.com/NeurodataWithoutBorders/pynwb/pull/1978)
+
 ## PyNWB 2.8.2 (September 9, 2024)
 
 ### Enhancements and minor changes

src/pynwb/__init__.py

@@ -397,6 +397,10 @@ def __init__(self, **kwargs):
         if mode in io_modes_that_create_file or manager is not None or extensions is not None:
             load_namespaces = False
 
+        if mode in io_modes_that_create_file and not str(path).endswith('.nwb'):
+            warn(f"The file path provided: {path} does not end in '.nwb'. "
+                 "It is recommended that NWB files using the HDF5 backend use the '.nwb' extension.", UserWarning)
+
         if load_namespaces:
             tm = get_type_map()
             super().load_namespaces(tm, path, file=file_obj, driver=driver, aws_region=aws_region)

tests/integration/hdf5/test_file_copy.py

@@ -9,8 +9,8 @@
 class TestFileCopy(TestCase):
 
     def setUp(self):
-        self.path1 = "test_a.h5"
-        self.path2 = "test_b.h5"
+        self.path1 = "test_a.nwb"
+        self.path2 = "test_b.nwb"
 
     def tearDown(self):
         if os.path.exists(self.path1):

tests/integration/hdf5/test_io.py

@@ -313,7 +313,7 @@ def setUp(self):
         self.nwbfile = NWBFile(session_description='a',
                                identifier='b',
                                session_start_time=datetime(1970, 1, 1, 12, tzinfo=tzutc()))
-        self.path = "test_pynwb_io_hdf5_h5dataIO.h5"
+        self.path = "test_pynwb_io_hdf5_h5dataIO.nwb"
 
     def tearDown(self):
         remove_test_file(self.path)
@@ -428,7 +428,7 @@ def setUp(self):
         self.nwbfile = NWBFile(session_description='a test NWB File',
                                identifier='TEST123',
                                session_start_time=datetime(1970, 1, 1, 12, tzinfo=tzutc()))
-        self.path = "test_pynwb_io_nwbhdf5.h5"
+        self.path = "test_pynwb_io_nwbhdf5.nwb"
 
     def tearDown(self):
         remove_test_file(self.path)
@@ -532,6 +532,23 @@ def test_round_trip_with_pathlib_path(self):
             read_file = io.read()
             self.assertContainerEqual(read_file, self.nwbfile)
 
+    def test_warn_for_nwb_extension(self):
+        """Creating a file with an extension other than .nwb should raise a warning"""
+        pathlib_path = Path(self.path).with_suffix('.h5')
+
+        with self.assertWarns(UserWarning):
+            with NWBHDF5IO(pathlib_path, 'w') as io:
+                io.write(self.nwbfile)
+        with self.assertWarns(UserWarning):
+            with NWBHDF5IO(str(pathlib_path), 'w') as io:
+                io.write(self.nwbfile)
+
+        # should not warn on read or append
+        with NWBHDF5IO(str(pathlib_path), 'r') as io:
+            io.read()
+        with NWBHDF5IO(str(pathlib_path), 'a') as io:
+            io.read()
+
     def test_can_read_current_nwb_file(self):
         with NWBHDF5IO(self.path, 'w') as io:
             io.write(self.nwbfile)

tests/unit/test_icephys_metadata_tables.py

@@ -82,7 +82,7 @@ def setUp(self):
             sweep_number=np.uint64(15)
         )
         self.nwbfile.add_acquisition(self.response)
-        self.path = 'test_icephys_meta_intracellularrecording.h5'
+        self.path = 'test_icephys_meta_intracellularrecording.nwb'
 
     def tearDown(self):
         remove_test_file(self.path)
@@ -1037,7 +1037,7 @@ class NWBFileTests(TestCase):
     """
     def setUp(self):
         warnings.simplefilter("always")  # Trigger all warnings
-        self.path = 'test_icephys_meta_intracellularrecording.h5'
+        self.path = 'test_icephys_meta_intracellularrecording.nwb'
 
     def tearDown(self):
         remove_test_file(self.path)