Merge pull request #146 from MiraGeoscience/release/0.1.5

GEOPY-331 Release geoh5py 0.1.5

Author: andrewg-mira

.github/workflows/codeql-analysis.yml

@@ -0,0 +1,78 @@
+name: "CodeQL"
+
+on:
+  push:
+    branches:
+        - develop
+        - main
+        - code-ql
+        - release/**
+        - feature/**
+        - hotfix/**
+  pull_request:
+    # The branches below must be a subset of the branches above
+    branches:
+        - main
+  schedule:
+    - cron: '22 21 * * 2'
+
+jobs:
+  analyze:
+    name: Analyze
+    defaults:
+      run:
+        shell: bash
+    runs-on: windows-latest
+    env:
+      POETRY_VIRTUALENVS_CREATE: true
+      POETRY_VIRTUALENVS_IN_PROJECT: true
+    permissions:
+      actions: read
+      contents: read
+      security-events: write
+
+    steps:
+    - name: Checkout repository
+      uses: actions/checkout@v2
+    - name: Set up Python version
+      uses: actions/setup-python@v2
+      with:
+        python-version: '3.7'
+    - name: Get full Python version
+      id: full-python-version
+      run: echo ::set-output name=version::$(python -c "import sys; print('-'.join(str(v) for v in sys.version_info))")
+    - name: Install Poetry
+      run: curl -sSL https://raw.githubusercontent.com/python-poetry/poetry/master/get-poetry.py | python -
+    - name: Environment
+      run: echo "$HOME/.poetry/bin" >> $GITHUB_PATH
+    - name: Set up cache
+      uses: actions/cache@v2
+      id: cache
+      with:
+        path: .venv
+        key: venv-${{ runner.os }}-${{ steps.full-python-version.outputs.version }}-${{ hashFiles('**/poetry.lock') }}
+    - name: Ensure cache is healthy
+      if: steps.cache.outputs.cache-hit == 'true'
+      run: timeout 10s poetry run pip --version || rm -rf .venv
+    - name: Install dependencies
+      run: |
+        poetry install -vvv --no-root
+        POETRY_PYTHON=$(poetry run python -c "import shutil; print(shutil.which('python'))")
+        echo "CODEQL_PYTHON=$POETRY_PYTHON" >> $GITHUB_ENV
+
+    # Initializes the CodeQL tools for scanning.
+    - name: Initialize CodeQL
+      uses: github/codeql-action/init@v1
+      with:
+        languages: python
+        # Override the default behavior so that the action doesn't attempt
+        # to auto-install Python dependencies
+        setup-python-dependencies: false
+
+        # If you wish to specify custom queries, you can do so here or in a config file.
+        # By default, queries listed here will override any specified in a config file.
+        # Prefix the list here with "+" to use these queries and those in the config file.
+        # queries: ./path/to/local/query, your-org/your-repo/queries@main
+
+    - name: Perform CodeQL Analysis
+      uses: github/codeql-action/analyze@v1

.pre-commit-config.yaml

@@ -10,7 +10,7 @@ ci:
 
 repos:
 -   repo: https://github.com/psf/black
-    rev: 21.7b0
+    rev: 21.10b0
     hooks:
     -   id: black
         types: [text]
@@ -22,7 +22,7 @@ repos:
         types: [text]
         types_or: [python, pyi]
 -   repo: https://github.com/PyCQA/isort
-    rev: 5.9.2
+    rev: 5.9.3
     hooks:
     -   id: isort
         additional_dependencies: [toml] # to read config from pyproject.toml
@@ -35,25 +35,26 @@ repos:
         types: [text]
         types_or: [python, pyi]
 -   repo: https://github.com/PyCQA/flake8
-    rev: 3.9.2
+    rev: 4.0.1
     hooks:
     -   id: flake8
         types: [text]
         types_or: [python, pyi]
 -   repo: https://github.com/asottile/pyupgrade
-    rev: v2.23.0
+    rev: v2.29.0
     hooks:
     -   id: pyupgrade
         args: [--py37-plus]
         types: [text]
         types_or: [python, pyi]
 -   repo: https://github.com/pre-commit/mirrors-mypy
-    rev: v0.910
+    rev: v0.910-1
     hooks:
     -   id: mypy
         additional_dependencies: [types-toml]
         args: [--ignore-missing-imports, --scripts-are-modules, --show-error-context,
                --show-column-numbers]
+        exclude: geoh5py/interfaces/__init__\.py
 -   repo: local
     hooks:
     -   id: pylint

docs/conf.py

@@ -80,9 +80,9 @@
 project = "geoh5py"
 
 # The short X.Y version.
-version = "0.1.4"
+version = "0.1.5"
 # The full version, including alpha/beta/rc tags.
-release = "0.1.4"
+release = "0.1.5"
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.

docs/content/geoh5_format/analyst/objects.rst

@@ -1,3 +1,5 @@
+.. _analyst_objects:
+
 ANALYST Objects
 ===============
 

docs/content/release_notes.rst

@@ -1,6 +1,13 @@
 Release Notes
 =============
 
+Release 0.1.5 - 2021/11/05
+--------------------------
+
+- Fix for copying of direct-current survey.
+- Fix documentation.
+
+
 Release 0.1.4 - 2021/08/31
 --------------------------
 

docs/content/uijson_format/images/bool_param.png

@@ -0,0 +1,95 @@
+UI.JSON Format
+==============
+
+About
+^^^^^
+
+The **ui.json** format provides a User Interface (UI) between geoh5py and `Geoscience ANALYST Pro
+<http://www.mirageoscience.com/our-products/software-product/geoscience-analyst>`_. The file structure is built on an array of `JSON objects <https://json-schema.org/specification.html>`_, each representing a parameter that is used in a python script. An object contains members that control the style and behaviour of the UI. In general only a **label** and **value** member is required in each object, however as outlined below, there are many types of input and dependencies that can be drawn on throughout the file. On output from Geoscience ANALYST, the value and whether the parameter is enabled will be updated or added to each JSON. Extra objects in the JSON are allowed and are ignored, but written out by Geoscience ANALYST. In general, objects will be put in order that they are set in the JSON. The exception is data parameters that depend on object parameters. Placing those parameters in the same group will ensure that they are close in the UI.
+
+
+Input Objects
+^^^^^^^^^^^^^
+Within the **ui.json** file, each JSON object with **value** and **label** members will be considered a parameter to the UI. The following JSON objects could also be present:
+
+run_command ``str``
+    Name of python script excluding the .py extension (i.e., "run_me" for run_me.py) required for Geoscience ANALYST Pro to run on save or auto-load.
+conda_environment ``str``
+    Optional name of conda environment to activate when running the python script in *run_command*
+title ``str``
+    Optional title of user interface window
+
+Object Members
+^^^^^^^^^^^^^^
+Each JSON object with the following members become a parameter in the user interface. Each object must have the members ``label`` and ``value``. Each member will contribute to the appearence and behaviour within Geoscience ANALYST>. The possible members that can be given to all parameter objects are:
+
+label ``str``
+    Required string describing parameter. A colon will automatically be added within Geoscience ANALYST, so this should be omitted.
+value ``str``, ``int``, ``bool`` , or ``float``
+    This require member takes a different form, including empty, depending on the :ref:`parameter type <json_param_examples>`. The value is updated when written from Geoscience ANALYST.
+main ``bool``
+    If set to true, the parameter is shown in the first tab and will throw an error if not given and not optional. Optional parameters may be set to main. When main is not given or is false, the parameter will be under the *Optional Parameters* tab.
+tooltip ``str``
+   String describing the parameter in detail that appears when the mouse hovers over it.
+optional ``bool``
+    *true* or *false* on whether the parameter is optional. On output, check if *enabled* is set to true.
+enabled ``bool``
+    *true* or *false* if the parameter is enabled. The default is true. If a parameter is optional and not enabled, it will start as disabled (grey and inactive in the UI).
+group ``str``
+    Name of the group to which the parameter belongs. Adds a box and name around the parameters with the same case-sensitive group name.
+groupOptional ``bool``
+    If true, adds a checkbox in the top of the group box next to the name. The group parameters will be disabled if not checked. The initial statedpends on the **groupDependency** and **groupDependencyType** members and the **enabled** member of the group's parameters.
+dependency ``str``
+    The name of the object of which this object is dependent upon. The dependency parameter should be optional or boolean parameter (i.e., has a checkbox).
+dependencyType ``str``
+    What happens when the dependency member is checked. Options are ``enabled`` or ``disabled``
+groupDependency ``str``
+    The name of the object of which the group of the parameter is dependent upon. This member will also require the **groupOptional** member to be present and set to ``true``. Be sure that the object is not within the group.
+groupDependencyType ``str``
+    What happens when the group's dependency parameter is checked. Options are ``enabled`` or ``disabled``.
+
+
+.. _json_param_examples:
+
+Parameter Types
+^^^^^^^^^^^^^^^
+There are other JSON members that may be available or required based on the parameter type. The following sections define different parameter types that can be found in the **ui.json** format.
+
+ .. toctree::
+   :maxdepth: 1
+
+   json_objects.rst
+
+
+Exporting from Geoscience ANALYST
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+When a **ui.json** is saved with Geoscience ANALYST Pro, the following object members are updated or added:
+
+- The **value** member with the appropriate type
+- The **enabled** member ``bool`` for whether the parameter is enabled
+- The :ref:`Data parameter <data_parameter>` will also have updated **isValue** and **property** members. The **isValue** ``bool`` member is *true* if the **value** member was selected and *false* if the **property** member was selected.
+
+The following JSON objects will be written (and overwritten if given) upon export from Geoscience ANALYST Pro:
+
+- monitoring_directory ``str`` the absolute path of a monitoring directory. Workspace files written to this folder will be automatically processed by Geoscience ANALYST.
+- workspace_geoh5 ``str`` the absolute path to the current workspace (if previously saved) being used
+- geoh5 ``str`` the absolute path to the geoh5 written containing all the objects of the workspace within the parameters of the **ui.json**. One only needs to use this workspace along with the JSON file to access the objects with geoh5py.
+
+
+Tips on creating UIs
+^^^^^^^^^^^^^^^^^^^^
+Here are a few tips on creating good looking UIs:
+
+- Keep labels short and concise. Be consistent with capitalization and do not include the colons. Geoscience ANALYST will add colons and align them.
+- Write detailed tooltips.
+- Group related objects, but do not use a group if there are fewer than 3 objects.
+- The **main** member is for general, required parameters. Do not include this member with every object, unless there are only a handful of objects. Objects that are in the required parameters without a valid value will invoke an error when exporting or running from Geoscience ANALYST. "Non-main" members are designated to a second page under *Optional parameters*.
+- Utilize **optional** object members and dependencies. If a single workspace object input is optional, use the :ref:`Object parameter <object_parameter>` rather than two parameters with a dependency.
+
+
+External Links
+^^^^^^^^^^^^^^
+
+- `JSON Terminology <https://json-schema.org/specification.html>`_
+- `Universally Unique IDentifier (UUID) <https://en.wikipedia.org/wiki/Universally_unique_identifier>`_
+- `C++ JSON Library <https://github.com/nlohmann/JSON>`_