Merge pull request #184 from prjemian/183-code-coverage

improve code coverage of unit tests
prjemian · Jan 1, 2022 · f99cfc3 · f99cfc3
2 parents 6e3a0e7 + 5742133
commit f99cfc3
Show file tree

Hide file tree

Showing 39 changed files with 1,050 additions and 1,419 deletions.
diff --git a/.landscape.yml b/.landscape.yml
@@ -4,33 +4,32 @@ strictness: medium
 max-line-length: 120
 autodetect: true
 requirements:
-  - pyRestTable
-  - PyGitHub>=1.32
-  - PyQt
-  - numpy
+  - coverage
+  - coveralls
+  - docopt
   - h5py
   - lxml
+  - numpy
+  - PyQt
+  - pyRestTable
   - requests
-  - coverage
-  - docopt
-  - coveralls
 ignore-paths:
+  - _installer.py
   - docs
+  - install_NXDL_file_sets.py
+  - punx/_version.py
   - punx/cache
   - punx/data
   - punx/ignore_now
   - versioneer.py
-  - punx/_version.py
-  - install_NXDL_file_sets.py
-  - _installer.py
 ignore-patterns:
-  - ^example/doc_.*\.py$
   - (^|/)docs(/|$)
+  - ^example/doc_.*\.py$
 python-targets:
   - 3
 pylint:
   disable:
-    - unused-argument
     - arguments-differ
-    - protected-access
     - cyclic-import
+    - protected-access
+    - unused-argument
diff --git a/docs/source/api/cache_manager.rst b/docs/source/api/cache_manager.rst
@@ -6,10 +6,10 @@ Cache : :mod:`cache_manager`
 Hierarchy:
 
 
+* :mod:`punx.main`
 * :mod:`punx.nxdl_manager`
 * :mod:`punx.schema_manager`
 * :mod:`punx.cache_manager`
-* :mod:`punx.github_handler`
 
 source code documentation
 *************************

diff --git a/docs/source/api/github_handler.rst b/docs/source/api/github_handler.rst
diff --git a/docs/source/cmd_install.rst b/docs/source/cmd_install.rst
@@ -0,0 +1,75 @@
+.. index:: install
+.. _cmd_install:
+
+User interface: subcommand: **install**
+##########################################
+
+**punx** keeps a local copy of the NeXus definition files.
+The originals of these files are located on GitHub.
+
+To *install* the local cache of NeXus definitions, run:
+
+..  code-block:: console
+
+    console> punx install
+
+    [INFO 2021-12-31 22:57:19.759 punx.main:248] cache_manager.download_file_set('main', '/home/prjemian/.config/punx', force=False)
+    Downloading file set: main to /home/prjemian/.config/punx/main ...
+    File set 'main' exists.  Will not replace.
+    ============= ====== =================== ======= ==================================================================
+    NXDL file set cache  date & time         commit  path                                                              
+    ============= ====== =================== ======= ==================================================================
+    a4fd52d       source 2016-11-19 01:07:45 a4fd52d /home/prjemian/Documents/projects/prjemian/punx/punx/cache/a4fd52d
+    v3.3          source 2017-07-12 10:41:12 9285af9 /home/prjemian/Documents/projects/prjemian/punx/punx/cache/v3.3   
+    v2018.5       source 2018-05-15 16:34:19 a3045fd /home/prjemian/Documents/projects/prjemian/punx/punx/cache/v2018.5
+    main          user   2021-12-17 13:09:18 041c2c0 /home/prjemian/.config/punx/main                                  
+    ============= ====== =================== ======= ==================================================================
+
+This shows the current cache was up to date.  Here's an example
+showing how the ``main`` file set can be updated:
+
+..  code-block:: console
+
+    console> punx install -u
+
+    [INFO 2021-12-31 23:00:19.343 punx.main:248] cache_manager.download_file_set('main', '/home/prjemian/.config/punx', force=True)
+    Downloading file set: main to /home/prjemian/.config/punx/main ...
+    Replacing existing file set 'main'
+    Requesting download from https://github.com/nexusformat/definitions/archive/main.zip
+    1 Extracted: definitions-main/applications/NXarchive.nxdl.xml
+    2 Extracted: definitions-main/applications/NXarpes.nxdl.xml
+    ...
+    108 Extracted: definitions-main/contributed_definitions/nxdlformat.xsl
+    109 Extracted: definitions-main/nxdl.xsd
+    110 Extracted: definitions-main/nxdlTypes.xsd
+    Created: /home/prjemian/.config/punx/definitions-main/__github_info__.json
+    Installed in directory: /home/prjemian/.config/punx/main
+    ============= ====== =================== ======= ==================================================================
+    NXDL file set cache  date & time         commit  path                                                              
+    ============= ====== =================== ======= ==================================================================
+    a4fd52d       source 2016-11-19 01:07:45 a4fd52d /home/prjemian/Documents/projects/prjemian/punx/punx/cache/a4fd52d
+    v3.3          source 2017-07-12 10:41:12 9285af9 /home/prjemian/Documents/projects/prjemian/punx/punx/cache/v3.3   
+    v2018.5       source 2018-05-15 16:34:19 a3045fd /home/prjemian/Documents/projects/prjemian/punx/punx/cache/v2018.5
+    main          user   2021-12-17 13:09:18 041c2c0 /home/prjemian/.config/punx/main                                  
+    ============= ====== =================== ======= ==================================================================
+
+
+.. rubric:: command line help
+
+..  code-block:: console
+
+    console> punx install -h
+    usage: punx install [-h] [-u] [file_set_list ...]
+
+    positional arguments:
+      file_set_list  name(s) of reference NeXus NXDL file set -- default main
+
+    optional arguments:
+      -h, --help     show this help message and exit
+      -u, --update   force existing file set to update from NeXus repository on GitHub
+
+
+Examples
+********
+
+--tba--
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -83,9 +83,7 @@
     github
     h5py
     lxml
-    PyGithub
     pyqt
-    PyQt4
     PyQt5
     pyRestTable
 """.split()
diff --git a/docs/source/configuration.rst b/docs/source/configuration.rst
@@ -6,34 +6,32 @@ User interface: subcommand: **configuration**
 #############################################
 
 The *configuration* subcommand shows the internal configuration
-of the ``punx`` program.  It shows a table with the available 
+of the ``punx`` program.  It shows a table with the available
 *NXDL file sets*.
 
 ::
 
    console> punx configuration
-   Locally-available versions of NeXus definitions (NXDL files)                 
-   ============= ======= ====== =================== ======= ==========================================
-   NXDL file set type    cache  date & time         commit  path                 
-   ============= ======= ====== =================== ======= ==========================================
-   a4fd52d       commit  source 2016-11-19 01:07:45 a4fd52d C:\source_path\punx\cache\a4fd52d
-   v2018.5       release source 2018-05-15 16:34:19 a3045fd C:\source_path\punx\src\punx\cache\v2018.5
-   v3.3          release source 2017-07-12 17:41:13 9285af9 C:\source_path\punx\src\punx\cache\v3.3   
-   9eab          commit  user   2016-10-19 17:58:51 9eab281 C:\user_path\AppData\Roaming\punx\9eab
-   master        branch  user   2018-05-16 02:07:48 2dc081e C:\user_path\AppData\Roaming\punx\master
-   ============= ======= ====== =================== ======= ==========================================
-   
-   default NXDL file set:  master
-
-
-An NXDL file set is the complete set of NXDL (XML) files that 
+   Locally-available versions of NeXus definitions (NXDL files)
+   ============= ====== =================== ======= =============================
+   NXDL file set cache  date & time         commit  path
+   ============= ====== =================== ======= =============================
+   a4fd52d       source 2016-11-19 01:07:45 a4fd52d /path/to/source/cache/a4fd52d
+   v3.3          source 2017-07-12 17:41:13 9285af9 /path/to/source/cache/v3.3
+   v2018.5       source 2018-05-15 16:34:19 a3045fd /path/to/source/cache/v2018.5
+   main          user   2021-12-17 21:09:18 041c2c0 /path/to/user/punx/main
+   ============= ====== =================== ======= =============================
+
+   default NXDL file set:  main
+
+
+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).
+Above, the user cache has a version of the GitHub *main* branch (
+the main branch contains the latest revisions by the developers on that date).
 
 .. index:: NXDL file set
 
@@ -43,7 +41,7 @@ An NXDL file set is *referenced* by one of the GitHub identifiers:
 identifier  example     description
 ==========  ==========  ==========================================
 commit      9eab        SHA-1 hash tag [#]_ that identifies a specific commit to the repository
-branch      master      name of a branch [#]_ in the repository
+branch      main        name of a branch [#]_ in the repository
 tag         Schema-3.4  name of a tag [#]_ in the repository
 release     v2018.5     name of a repository release [#]_
 ==========  ==========  ==========================================
@@ -52,35 +50,35 @@ release     v2018.5     name of a repository release [#]_
    A SHA-1 hash code is the unique identifier of a commit.
    It is a 40-character sequence of hexadecimals.
    It may be shortened to just the first characters which identify
-   it uniquely in the repository.  Three or four characters *may* be 
+   it uniquely in the repository.  Three or four characters *may* be
    unique (1:16^3 or 1:16^4) while
    seven characters are almost certain (1:16^7) to be a unique reference.
-   
+
    For example. the commit `9eab` may also be identified
    as `9eab281`, or by its full SHA-1 has
    `9eab2816e19440f8601fdf81ee972e330319c28f`
-   (https://github.com/nexusformat/definitions/commit/9eab281).  
+   (https://github.com/nexusformat/definitions/commit/9eab281).
    All point to the same commit on 2016-10-19 17:58:51.
 .. [#] branch: https://help.github.com/articles/about-branches/
 .. [#] tag: a user-provided text name for a commit
 .. [#] release: https://help.github.com/articles/about-releases/
 
 
-.. index:: 
+.. index::
    !ref
    NXDL file set, ref
 
-When a *ref* (a reference to a specific NXDL file set identifier) 
-is not provided, the default NXDL file set will be chosen as the one 
+When a *ref* (a reference to a specific NXDL file set identifier)
+is not provided, the default NXDL file set will be chosen as the one
 with the most recent date & time.  That date & time is provided by
 GitHub as the time the changes were to committed to the repository.
 
-.. index:: 
+.. index::
    source cache
    user cache
    cache, source
    cache, user
 
-NXDL file sets may be found in the *source cache* (as distributed 
-with the program) or in the *user cache* as maintained by the ``punx`` 
-:ref:`update` subcommand.  The full path to the file set is provided.
+NXDL file sets may be found in the *source cache* (as distributed
+with the program) or in the *user cache* as maintained by the ``punx``
+:ref:`cmd_install` subcommand.  The full path to the file set is provided.
diff --git a/docs/source/contents.rst b/docs/source/contents.rst
@@ -31,7 +31,6 @@ Source Code
    ~punx.nxdl_schema
    ~punx.schema_manager
    ~punx.cache_manager
-   ~punx.github_handler
 
 
 Indices and tables

diff --git a/docs/source/demo.rst b/docs/source/demo.rst
@@ -48,9 +48,3 @@ Problems when running the demo
 Sometimes, problems happen when running the demo.
 In this section are some common problems encountered and
 what was done to resolve them.
-
-
-Cannot reach GitHub
-~~~~~~~~~~~~~~~~~~~
-
-See :ref:`github_api_rate_limit_exceeded`
diff --git a/docs/source/install.rst b/docs/source/install.rst
@@ -56,24 +56,21 @@ pre-requisites using *conda* rather than *pip*.  The pre-requisites include:
 * h5py
 * lxml
 * numpy
-* Qt and PyQt (either v4 or v5)
+* Qt and PyQt (v5)
 * requests
-* PyGithub
 
 See your distribution's documentation for how to install these.  With Anaconda, use::
 
-    conda install h5py lxml numpy Qt=5 PyQt=5 requests 
-    pip install PyGitHub pyRestTable
+    conda install h5py lxml numpy Qt=5 PyQt=5 requests pyRestTable -c conda-forge
 
 ============  ===================================
 Package       URL
 ============  ===================================
-h5py          http://www.h5py.org
-lxml          http://lxml.de
-numpy         http://numpy.scipy.org
-PyGithub      https://github.com/PyGithub/PyGithub
-PyQt4         https://riverbankcomputing.com/software/pyqt/intro
-requests      http://docs.python-requests.org 
+h5py          https://www.h5py.org
+lxml          https://lxml.de
+numpy         https://numpy.scipy.org
+PyQt5         https://www.riverbankcomputing.com/software/pyqt/
+requests      https://docs.python-requests.org 
 ============  ===================================
 
 Optional Packages
@@ -82,7 +79,7 @@ Optional Packages
 ============  ===================================
 Package       URL
 ============  ===================================
-pyRestTable   http://pyresttable.readthedocs.io
+pyRestTable   https://pyresttable.readthedocs.io
 ============  ===================================
 
 The *pyRestTable* package is used for various reports in the punx application.

diff --git a/docs/source/overview.rst b/docs/source/overview.rst
@@ -12,7 +12,7 @@ command line help
 
    console> punx -h
    usage: punx [-h] [-v]
-               {configuration,demonstrate,structure,tree,update,validate} ...
+               {configuration,demonstrate,install,tree,validate} ...
    
    Python Utilities for NeXus HDF5 files version: 0.2.6 URL:
    https://prjemian.github.io/punx
@@ -24,12 +24,11 @@ command line help
    subcommand:
      valid subcommands
    
-     {configuration,demonstrate,structure,tree,update,validate}
+     {configuration,demonstrate,install,tree,validate}
        configuration       show configuration details of punx
        demonstrate         demonstrate HDF5 file validation
-       structure           (deprecated) use ``tree``
+       install             update the local cache of NeXus definitions
        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
@@ -46,7 +45,7 @@ Subcommands
    demo
    hierarchy
    tree
-   update
+   cmd_install
    validate
 
 **punx** uses a subcommand structure to provide several different modules under one
@@ -61,10 +60,8 @@ 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:`install <install>`       update the local cache of NeXus definitions
 :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
 =============================  ====================================================