Remove option to validate against ns file, update docs (#1397)

Author: rly

CHANGELOG.md

@@ -55,7 +55,9 @@
   be provided in place of ``data``. ``OpticalSeries.__init__`` now makes ``data`` optional. However, this has the
   side effect of moving the position of ``data`` to later in the argument list, which may break code that relies
   on positional arguments for ``OpticalSeries.__init__``. @rly (#1274)
-- Fixed `setup.py` not being able to import `versioneer` when installing in an embedded Python environment. @ikhramts (#1395)
+- Fixed `setup.py` not being able to import `versioneer` when installing in an embedded Python environment. @ikhramts
+  (#1395)
+- Removed broken option to validate against a given namespace file and updated associated documentation. @rly (#1397)
 
 ## PyNWB 1.5.1 (May 24, 2021)
 

docs/source/validation.rst

@@ -3,42 +3,47 @@
 Validating NWB files
 ====================
 
-Validating NWB files is handled by a command-line tool available in :py:mod:`~pynwb`. The validator can be invoked like so:
+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
 
-This will validate the file ``test.nwb`` against the *core* NWB specification. In case of success the output looks like
+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 is:
 
 .. code-block:: text
 
-  Validating test.nwb against cached namespace information using namespace core.
+  Validating test.nwb against cached namespace information using namespace 'core'.
    - no errors found.
 
-and the program exit code is ``0``. On error the program exit code is ``1`` and
-the list of errors is outputted.
+and the program exit code is ``0``. On error, the program exit code is ``1`` and the list of errors is outputted.
 
-If possible the file is validated against the cached namespace specification
-read from the file itself. This can be tweaked with the command line options given below.
+If the file contains NWB extensions, then the above validation command will validate the file ``test.nwb`` against
+all extensions in the file and the core NWB specification.
 
-CURRENTLY BROKEN!!!
+To validate against only one NWB extension that is cached within the file, use the ``-n`` flag.
+For example, the following command will validate against the "ndx-my-extension" namespace that is cached
+within the ``test.nwb`` file.
 
-Validating against other specifications i.e. extensions
-can be done using the ``-p`` and ``-n`` flags. For example, the following command will validate against the specifications referenced in the namespace
-file ``mylab.namespace.yaml`` in addition to the core specification.
+.. code-block:: bash
+
+  python -m 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 -p mylab.namespace.yaml test.nwb
+  python -m pynwb.validate --no-cached-namespace test.nwb
 
-.. Last updated 2/2020
+.. Last updated 8/13/2021
 .. code-block:: text
 
   $python -m pynwb.validate --help
-  usage: validate.py [-h] [-p NSPATH] [-n NS] [-lns]
-                     [--cached-namespace | --no-cached-namespace]
-                     paths [paths ...]
+  usage: validate.py [-h] [-n NS] [-lns] [--cached-namespace | --no-cached-namespace] paths [paths ...]
 
   Validate an NWB file
 
@@ -47,14 +52,14 @@ file ``mylab.namespace.yaml`` in addition to the core specification.
 
   optional arguments:
     -h, --help            show this help message and exit
-    -p NSPATH, --nspath NSPATH
-                          the path to the namespace YAML file
     -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).
     --no-cached-namespace
                           Don't use the cached namespace.
 
-  use --nspath to validate against an extension. If --ns is not specified,
-  validate against all namespaces in namespace file.
+  If --ns is not specified, validate against all namespaces in the NWB file.
+
+Validation against a namespace that is not cached within the schema is not currently possible but is a planned
+feature.

src/pynwb/validate.py

@@ -29,13 +29,12 @@ def _validate_helper(**kwargs):
 def main():  # noqa: C901
 
     ep = """
-    use --nspath to validate against an extension. If --ns is not specified,
-    validate against all namespaces in namespace file.
+    If --ns is not specified, validate against all namespaces in the NWB file.
     """
 
     parser = ArgumentParser(description="Validate an NWB file", epilog=ep)
     parser.add_argument("paths", type=str, nargs='+', help="NWB file paths")
-    parser.add_argument('-p', '--nspath', type=str, help="the path to the namespace YAML file")
+    # parser.add_argument('-p', '--nspath', type=str, help="the path to the namespace YAML file")
     parser.add_argument("-n", "--ns", type=str, help="the namespace to validate against")
     parser.add_argument("-lns", "--list-namespaces", dest="list_namespaces",
                         action='store_true', help="List the available namespaces and exit.")
@@ -50,15 +49,16 @@ def main():  # noqa: C901
     args = parser.parse_args()
     ret = 0
 
-    if args.nspath:
-        if not os.path.isfile(args.nspath):
-            print("The namespace file {} is not a valid file.".format(args.nspath), file=sys.stderr)
-            sys.exit(1)
-
-        if args.cached_namespace:
-            print("Turning off validation against cached namespace information "
-                  "as --nspath was passed.", file=sys.stderr)
-            args.cached_namespace = False
+    # TODO Validation against a specific namespace file is currently broken. See pynwb#1396
+    # if args.nspath:
+    #     if not os.path.isfile(args.nspath):
+    #         print("The namespace file {} is not a valid file.".format(args.nspath), file=sys.stderr)
+    #         sys.exit(1)
+    #
+    #     if args.cached_namespace:
+    #         print("Turning off validation against cached namespace information "
+    #               "as --nspath was passed.", file=sys.stderr)
+    #         args.cached_namespace = False
 
     for path in args.paths:
 
@@ -87,17 +87,17 @@ def main():  # noqa: C901
                 specloc = "pynwb namespace information"
                 print("The file {} has no cached namespace information. "
                       "Falling back to {}.".format(path, specloc), file=sys.stderr)
-        elif args.nspath:
-            catalog = NamespaceCatalog(NWBGroupSpec, NWBDatasetSpec, NWBNamespace)
-            namespaces = catalog.load_namespaces(args.nspath)
-
-            if len(namespaces) == 0:
-                print("Could not load namespaces from file {}.".format(args.nspath), file=sys.stderr)
-                sys.exit(1)
-
-            tm = TypeMap(catalog)
-            manager = BuildManager(tm)
-            specloc = "--nspath namespace information"
+        # elif args.nspath:
+        #     catalog = NamespaceCatalog(NWBGroupSpec, NWBDatasetSpec, NWBNamespace)
+        #     namespaces = catalog.load_namespaces(args.nspath)
+        #
+        #     if len(namespaces) == 0:
+        #         print("Could not load namespaces from file {}.".format(args.nspath), file=sys.stderr)
+        #         sys.exit(1)
+        #
+        #     tm = TypeMap(catalog)
+        #     manager = BuildManager(tm)
+        #     specloc = "--nspath namespace information"
         else:
             manager = None
             namespaces = [CORE_NAMESPACE]