Upgrade validation methods

CHANGELOG.md

@@ -2,13 +2,22 @@
 
 ## PyNWB 3.0.0 (Upcoming)
 
+### Breaking changes
+- The validation methods have been updated with multiple breaking changes. @stephprince [#1911](https://github.com/NeurodataWithoutBorders/pynwb/pull/1911)
+   - The behavior of `pynwb.validate(io=...)` now matches the behavior of `pynwb.validate(path=...)`. In previous pynwb versions, `pynwb.validate(io=...)` did not use the cached namespaces during validation. To obtain the same behavior as in previous versions, you can update the function call to `pynwb.validate(io=..., used_cached_namespaces=False)`
+   - The validate module has been renamed to `validation.py`. The validate method can be 
+   imported using `import pynwb; pynwb.validate` or `from pynwb.validation import validate`
+
 ### Enhancements and minor changes
 - Added support for NWB schema 2.8.0. @rly [#2001](https://github.com/NeurodataWithoutBorders/pynwb/pull/2001)
   - Removed `SpatialSeries.bounds` field that was not functional. This will be fixed in a future release. @rly [#1907](https://github.com/NeurodataWithoutBorders/pynwb/pull/1907), [#1996](https://github.com/NeurodataWithoutBorders/pynwb/pull/1996)
   - Added support for `NWBFile.was_generated_by` field. @stephprince [#1924](https://github.com/NeurodataWithoutBorders/pynwb/pull/1924)
   - Added support for `model_number`, `model_name`, and `serial_number` fields to `Device`. @stephprince [#1997](https://github.com/NeurodataWithoutBorders/pynwb/pull/1997)
   - Deprecated `EventWaveform` neurodata type. @rly [#1940](https://github.com/NeurodataWithoutBorders/pynwb/pull/1940)
   - Deprecated `ImageMaskSeries` neurodata type. @rly [#1941](https://github.com/NeurodataWithoutBorders/pynwb/pull/1941)
+- Added enhancements to the validation CLI. @stephprince [#1911](https://github.com/NeurodataWithoutBorders/pynwb/pull/1911)
+  - Added an entry point for the validation module. You can now use `pynwb-validate "file.nwb"`.
+  - Added the `--json-file-path` CLI argument to output validation results in a machine readable format.
 
 ## PyNWB 2.8.3 (November 19, 2024)
 

docs/source/validation.rst

@@ -3,12 +3,21 @@
 Validating NWB files
 ====================
 
+.. note:: 
+
+  The pynwb validation CLI checks for structural compliance of NWB files with the NWB schema. 
+  It is recommended to use the `NWBInspector CLI <https://nwbinspector.readthedocs.io/en/dev/>`_ 
+  for more comprehensive validation of both structural compliance with the NWB schema and 
+  compliance of data with NWB best practices. The NWBInspector runs both PyNWB validation as 
+  described here and additional data checks.
+
+
 Validating NWB files is handled by a command-line tool available in :py:mod:`~pynwb`.
 The validator can be invoked like so:
 
 .. code-block:: bash
 
-  python -m pynwb.validate test.nwb
+  pynwb-validate test.nwb
 
 If the file contains no NWB extensions, then this command will validate the file ``test.nwb`` against the
 *core* NWB specification. On success, the output will be:
@@ -29,35 +38,36 @@ within the ``test.nwb`` file.
 
 .. code-block:: bash
 
-  python -m pynwb.validate -n ndx-my-extension test.nwb
+  pynwb-validate -n ndx-my-extension test.nwb
 
 To validate against the version of the **core** NWB specification that is included with the installed version of
 PyNWB, use the ``--no-cached-namespace`` flag. This can be useful in validating files against newer or older versions
 of the **core** NWB specification that are installed with newer or older versions of PyNWB.
 
 .. code-block:: bash
 
-  python -m pynwb.validate --no-cached-namespace test.nwb
+  pynwb-validate --no-cached-namespace test.nwb
 
 .. Last updated 8/13/2021
 .. code-block:: text
 
-  $python -m pynwb.validate --help
-  usage: validate.py [-h] [-n NS] [-lns] [--cached-namespace | --no-cached-namespace] paths [paths ...]
+  $pynwb-validate --help
+  usage: pynwb-validate [-h] [-lns] [-n NS] [--json-file-path JSON_FILE_PATH] [--no-cached-namespace] paths [paths ...]
 
   Validate an NWB file
 
   positional arguments:
     paths                 NWB file paths
 
-  optional arguments:
+  options:
     -h, --help            show this help message and exit
-    -n NS, --ns NS        the namespace to validate against
     -lns, --list-namespaces
                           List the available namespaces and exit.
-    --cached-namespace    Use the cached namespace (default).
+    -n NS, --ns NS        the namespace to validate against
+    --json-file-path JSON_FILE_PATH
+                          Write json output to this location.
     --no-cached-namespace
-                          Don't use the cached namespace.
+                          Use the PyNWB loaded namespace (true) or use the cached namespace (false; default).
 
   If --ns is not specified, validate against all namespaces in the NWB file.
 

pyproject.toml

@@ -48,6 +48,9 @@ dynamic = ["version"] # the build backend will compute the version dynamically f
 "Homepage" = "https://github.com/NeurodataWithoutBorders/pynwb"
 "Bug Tracker" = "https://github.com/NeurodataWithoutBorders/pynwb/issues"
 
+[project.scripts]
+pynwb-validate = "pynwb.validation_cli:validation_cli"
+
 [tool.hatch.version]
 source = "vcs"
 
@@ -111,7 +114,7 @@ line-length = 120
 "docs/gallery/*" = ["E402", "T201"]
 "src/*/__init__.py" = ["F401"]
 "src/pynwb/_version.py" = ["T201"]
-"src/pynwb/validate.py" = ["T201"]
+"src/pynwb/validation_cli.py" = ["T201"]
 "scripts/*" = ["T201"]
 
 # "test_gallery.py" = ["T201"] # Uncomment when test_gallery.py is created

src/pynwb/__init__.py

@@ -23,7 +23,7 @@
 CORE_NAMESPACE = 'core'
 
 from .spec import NWBDatasetSpec, NWBGroupSpec, NWBNamespace  # noqa E402
-from .validate import validate  # noqa: F401, E402
+from .validation import validate  # noqa: F401, E402
 
 try:
     # see https://effigies.gitlab.io/posts/python-packaging-2023/
@@ -354,6 +354,27 @@
     return __TYPE_MAP.get_dt_container_cls(neurodata_type, namespace)
 
 
+@docval({'name': 'path', 'type': str, 'doc': 'the neurodata_type to get the NWBContainer class for'},
+        {"name": "method", "type": str, "doc": "the method to use when opening the file", 'default': None},
+        is_method=False)
+def _get_backend(path: str, method: str = None):
+    if method == "ros3":
+        return NWBHDF5IO  # TODO - add additional conditions for other streaming methods
+
+    try:
+        from hdmf_zarr import NWBZarrIO
+        backend_io_classes = [NWBHDF5IO, NWBZarrIO]
+    except ImportError:
+        backend_io_classes = [NWBHDF5IO]
+
+    backend_options = [b for b in backend_io_classes if b.can_read(path=path)]
+    if len(backend_options) == 0:
+        raise ValueError(f"Could not find an IO to read the file '{path}'. If you are trying to read "
+                         f"a Zarr file, make sure you have hdmf-zarr installed.")
+    else:
+        return backend_options[0]
+
+
 class NWBHDF5IO(_HDF5IO):
 
     @staticmethod

src/pynwb/testing/testh5io.py

@@ -163,12 +163,12 @@ def getContainer(self, nwbfile):
     def validate(self):
         """ Validate the created files """
         if os.path.exists(self.filename):
-            errors, _ = pynwb_validate(paths=[self.filename])
+            errors = pynwb_validate(path=self.filename)
             if errors:
                 raise Exception("\n".join(errors))
 
         if os.path.exists(self.export_filename):
-            errors, _ = pynwb_validate(paths=[self.export_filename])
+            errors = pynwb_validate(path=self.export_filename)
             if errors:
                 raise Exception("\n".join(errors))
 
@@ -366,11 +366,11 @@ def roundtripExportContainer(self, cache_spec=True):
     def validate(self):
         """Validate the created files."""
         if os.path.exists(self.filename):
-            errors, _ = pynwb_validate(paths=[self.filename])
+            errors = pynwb_validate(path=self.filename)
             if errors:
                 raise Exception("\n".join(errors))
 
         if os.path.exists(self.export_filename):
-            errors, _ = pynwb_validate(paths=[self.export_filename])
+            errors = pynwb_validate(path=self.export_filename)
             if errors:
                 raise Exception("\n".join(errors))