Merge ef7e4ed into f7e8a12

README.md

@@ -10,11 +10,13 @@
 
 The *punx* package provides these features:
 
-- Validate NeXus HDF5 data files
-- Choose the NeXus [release](https://github.com/nexusformat/definitions/releases) to use for validation
+- Display tree structure of _any_ HDF5 data file
+- Validate any HDF5 data file using NeXus definitions
 - Validate NeXus NXDL files
-- Display NeXus HDF5 data file structure
-- Display NeXus class hierarchy (stretch goal, graphical output)
+- Choose the NeXus definitions
+  [release](https://github.com/nexusformat/definitions/releases)
+  to use for validation
+<!-- - Display NeXus class hierarchy (stretch goal, graphical output) -->
 
 
 ## Package Details

docs/source/api/h5tree.rst

@@ -5,11 +5,6 @@ HDF5 Data File Tree Structure : :mod:`h5tree`
 
 Print the tree structure of any HDF5 file.
 
-:Note: The *tree* subcommand replaces the now-legacy *structure* subcommand and
-       also `replaces <https://github.com/prjemian/spec2nexus/issues/70>`_
-       the `h5toText` program from the 
-       `spec2nexus <https://github.com/prjemian/spec2nexus>`_ project.
-
 .. index:: examples; h5tree
 
 How to use **h5tree**
@@ -33,7 +28,7 @@ the help message:
       
       optional arguments:
         -h, --help            show this help message and exit
-        -a                    Do not print attributes of HDF5 file structure
+        -a                    Do not print attributes of HDF5 file tree structure
         -m MAX_ARRAY_ITEMS, --max_array_items MAX_ARRAY_ITEMS
                               maximum number of array items to be shown
 
@@ -71,5 +66,5 @@ source code documentation
 
 .. automodule:: punx.h5tree
     :members: 
-    :synopsis: Command line tool to print the structure of any HDF5 file
+    :synopsis: Command line tool to print the tree structure of any HDF5 file
 

docs/source/api/nxdltree.rst

@@ -5,8 +5,6 @@ NXDL Definition File Tree Structure : :mod:`nxdltree`
 
 Describe the tree structure of a NeXus Definition Language NXDL XML file.
 
-Note:  The *tree* subcommand replaces the now-legacy *structure* subcommand.
-
 ----
 
 source code documentation

docs/source/api/validate.rst

@@ -43,9 +43,10 @@ NeXus HDF5 Data Files
 ---------------------
 
 NeXus data files are HDF5 [#]_ and are validated against the suite of NXDL files
-using tools provided by this package.  The strategy is to compare the structure
-of the HDF file with the structure of the NXDL file(s) as specified by the
-``NX_class`` attributes of the various HDF groups in the data file.
+using tools provided by this package.  The strategy is to compare the tree
+structure of the HDF file with the tree structure of the NXDL file(s) as
+specified by the ``NX_class`` attributes of the various HDF groups in the data
+file.
 
 NeXus NXDL Definition Language Files
 ------------------------------------

docs/source/configuration.rst

@@ -26,14 +26,12 @@ of the ``punx`` program.  It shows a table with the available
    default NXDL file set:  master
 
 
-An NXDL file set is the complete set of NXDL (XML) files that 
-provide a version of the NeXus standard, including the XML Schema
-files that provide all the default and basic structures of the NXDL
-files.
-
-Above, the user cache has a version of the GitHub *master* branch (
-the master branch contains the latest
-revisions by the developers on that date).
+An NXDL file set is the complete set of NXDL (XML) files that provide a version
+of the NeXus standard, including the XML Schema files that provide all the
+default and basic structures of the NXDL files.
+
+Above, the user cache has a version of the GitHub *master* branch ( the master
+branch contains the latest revisions by the developers on that date).
 
 .. index:: NXDL file set
 

docs/source/index.rst

@@ -4,10 +4,14 @@ punx
 
 Python Utilities for NeXus HDF5 files: validation, structure, hierarchy
 
-* Validation of NeXus NXDL files
-* Validation of NeXus HDF5 data files
-* Display of NeXus HDF5 data file tree structure
-* Display of NeXus base class hierarchy (stretch goal, graphical output)
+* Display tree structure of _any_ HDF5 data file
+* Validate any HDF5 data file using NeXus definitions
+* Validate NeXus NXDL files
+* Choose the NeXus definitions
+  `release <https://github.com/nexusformat/definitions/releases>`_
+  to use for validation
+
+.. * Display NeXus class hierarchy (stretch goal, graphical output)
 
 NOTE: project is under initial construction
 
@@ -25,14 +29,22 @@ NOTE: project is under initial construction
 :version:   |version|
 :published: |today|
 
-Use these steps to :ref:`install <install>` and try the :ref:`demo <demo>`:
+Use these steps to :ref:`install <install>` and try the :ref:`demo <demo>`.  
+Either with ``pip``
 
 .. code-block:: console
    :linenos:
 
     pip install punx
     punx demo
 
+or, with ``conda``:
+
+.. code-block:: console
+   :linenos:
+
+    conda install punx -c conda-forge
+    punx demo
 
 .. toctree::
    :maxdepth: 2

docs/source/overview.rst

@@ -1,9 +1,9 @@
 Project Overview
 ################
 
-The **punx** program package is easy to use and has several useful modules.
-The first module to try is :ref:`demo <demo>`, which validates 
-and prints the structure of a NeXus HDF5 data file from the NeXus documentation.
+The **punx** program package is easy to use and has several useful modules. The
+first module to try is :ref:`demo <demo>`, which validates and prints the tree
+structure of a NeXus HDF5 data file from the NeXus documentation.
 
 command line help
 *****************
@@ -12,26 +12,25 @@ command line help
 
    console> punx -h
    usage: punx [-h] [-v]
-               {configuration,demonstrate,structure,tree,update,validate} ...
-   
+               {configuration,demonstrate,tree,update,validate} ...
+
    Python Utilities for NeXus HDF5 files version: 0.2.6 URL:
    https://prjemian.github.io/punx
-   
+
    optional arguments:
      -h, --help            show this help message and exit
      -v, --version         show program's version number and exit
-   
+
    subcommand:
      valid subcommands
-   
-     {configuration,demonstrate,structure,tree,update,validate}
+
+     {configuration,demonstrate,tree,update,validate}
        configuration       show configuration details of punx
        demonstrate         demonstrate HDF5 file validation
-       structure           (deprecated) use ``tree``
        tree                show tree structure of HDF5 or NXDL file
        update              update the local cache of NeXus definitions
        validate            validate a NeXus file
-   
+
    Note: It is only necessary to use the first two (or more) characters of any
    subcommand, enough that the abbreviation is unique. Such as: ``demonstrate``
    can be abbreviated to ``demo`` or even ``de``.
@@ -41,45 +40,42 @@ Subcommands
 
 .. toctree::
    :hidden:
-   
+
    configuration
    demo
-   hierarchy
    tree
    update
    validate
 
-**punx** uses a subcommand structure to provide several different modules under one
-identifiable program.  These are invoked using commands of the form::
+**punx** uses subcommands to provide several different modules under one
+identifiable program.  A subcommand is invoked using this form::
 
     punx <subcommand> <other parameters>
-    
+
 where *<subcommand>* is chosen from this table:
 
 =============================  ====================================================
 subcommand                     brief description
 =============================  ====================================================
 :ref:`configuration <config>`  show internal punx configuration
 :ref:`demonstrate <demo>`      demonstrate HDF5 file validation
-:ref:`hierarchy <hierarchy>`   show NeXus base class hierarchy (not implemented yet)
-:ref:`structure <tree>`        (deprecated) use :ref:`tree`
 :ref:`tree <tree>`             show tree structure of HDF5 or NXDL file
 :ref:`update <update>`         update the local cache of NeXus definitions
 :ref:`validate <validate>`     validate a NeXus file
 =============================  ====================================================
 
-and the *<other parameters>* are desribed by the help for each subcommand::
+Any ``*<other parameters>*`` are described by the help for each subcommand::
 
     punx <subcommand> -h
 
 Example [#]_ ::
 
    console> punx val -h
    usage: punx validate [-h] [--report REPORT] infile
-   
+
    positional arguments:
      infile           HDF5 or NXDL file name
-   
+
    optional arguments:
      -h, --help       show this help message and exit
      --report REPORT  select which validation findings to report, choices:
@@ -92,5 +88,5 @@ Example [#]_ ::
    subcommand, enough that the short version remains unique and could not be
    misinterpreted as another subcommand.  The program imposes a minimum limit
    of at least 2-characters.
-    
+
    Such as: ``demonstrate`` can be abbreviated to ``demo`` or even ``de``.

docs/source/tree.rst

@@ -19,7 +19,7 @@ show tree structure of HDF5 or NXDL file
    
    optional arguments:
      -h, --help            show this help message and exit
-     -a                    Do not print attributes of HDF5 file structure
+     -a                    Do not print attributes of HDF5 file tree structure
      -m MAX_ARRAY_ITEMS, --max_array_items MAX_ARRAY_ITEMS
                            maximum number of array items to be shown
 

punx/h5tree.py

@@ -57,7 +57,7 @@ def __init__(self, filename):
 
     def report(self, show_attributes=True):
         """
-        Return the structure of the HDF5 file in a list of strings.
+        Return the tree structure of the HDF5 file in a list of strings.
 
         The work of parsing the datafile is done in this method.
 
@@ -202,7 +202,9 @@ def _renderLinkedObject(self, obj, name, indentation="  "):
         return s
 
     def _renderDataset(self, dset, name, indentation="  "):
-        """return a [formatted_string] with the contents and structure of a dataset"""
+        """
+        Return a [formatted_string] with the contents and tree structure of a dataset.
+        """
         shape = dset.shape
         # dset.dtype.kind == 'S', nchar = dset.dtype.itemsize
         if self.isNeXus:

punx/main.py

@@ -22,7 +22,7 @@
 
     console> punx -h
     usage: punx [-h] [-v]
-                {configuration,demonstrate,structure,tree,update,validate} ...
+                {configuration,demonstrate,tree,update,validate} ...
 
     Python Utilities for NeXus HDF5 files version: 0.2.6 URL:
     https://prjemian.github.io/punx
@@ -34,10 +34,9 @@
     subcommand:
       valid subcommands
 
-      {configuration,demonstrate,structure,tree,update,validate}
+      {configuration,demonstrate,tree,update,validate}
         configuration       show configuration details of punx
         demonstrate         demonstrate HDF5 file validation
-        structure           structure command deprecated. Use ``tree`` instead
         tree                show tree structure of HDF5 or NXDL file
         update              update the local cache of NeXus definitions
         validate            validate a NeXus file
@@ -81,9 +80,6 @@
 ERROR = 40
 logger = utils.setup_logger(__name__, logging.INFO)
 
-# :see: https://docs.python.org/2/library/argparse.html#sub-commands
-# obvious 1st implementations are h5structure and update
-
 
 def exit_message(msg, status=None, exit_code=1):
     """
@@ -168,13 +164,6 @@ def func_hierarchy(args):
     # TODO: issue #1 & #10 show NeXus base class hierarchy from a given base class
 
 
-def func_structure(args):
-    "deprecated subcommand"
-    msg = "structure command deprecated.  Use ``tree`` instead"
-    print(ValueError(msg))
-    sys.exit(1)
-
-
 def func_tree(args):
     """print the tree structure of a NeXus HDF5 data file of NXDL XML file"""
     if args.infile.endswith(".nxdl.xml"):
@@ -367,23 +356,18 @@ def parse_command_line_arguments():
     #     p_sub.set_defaults(func=func_hierarchy)
     #     #p_sub.add_argument('something', type=bool, help='something help_text')
 
-    # --- subcommand: structure
-    help_text = "structure command deprecated.  Use ``tree`` instead"
-    p_sub = subcommand.add_parser("structure", help=help_text)
-    p_sub.set_defaults(func=func_structure)
-    p_sub.add_argument("infile", help="HDF5 or NXDL file name")
-
     # --- subcommand: tree
     help_text = "show tree structure of HDF5 or NXDL file"
     p_sub = subcommand.add_parser("tree", help=help_text)
+
     p_sub.set_defaults(func=func_tree)
     p_sub.add_argument("infile", help="HDF5 or NXDL file name")
     p_sub.add_argument(
         "-a",
         action="store_false",
         default=True,
         dest="show_attributes",
-        help="Do not print attributes of HDF5 file structure",
+        help="Do not print attributes of HDF5 file tree structure",
     )
     help_text = "maximum number of array items to be shown"
     p_sub.add_argument(