1. Introduction¶

1.1. Workflow¶

The following workflow is assumed:

1. A yaml configuration file defines the tool’s input parameters. The configuration file is saved alongside the HEC-DSS .dss file.
2. The toolbox.Tool is sub-classed to define the tool. The method toolbox.Tool.main() includes the task logic (e.g. importing data, creating plots, etc.).
3. The tool is run using the toolbox.Tool.run() method.

1.2. Example toolbox¶

Example of a HEC-DSS script using the toolbox.Tool:

# name=Example tool
# displayinmenu=true
# displaytouser=true
# displayinselector=true

import toolbox as tb
import voluptuous as v
from some_module import do_something

class ExampleTool(tb.Tool):
    refreshCatalogue = 1  # Update catalogue when completed
    schema = v.Schema({
        'folder': unicode,
        'files': [
            unicode
        ],
        'site': unicode
    }, required=True)

    def main(self):
        do_something(self.config, self.dssFilePath)
        self.message = "Test tool successfully completed."

tool = ExampleTool()
tool.run()

The above code should be saved in a file like this %APPDATA%/Roaming/HEC/HEC-DSSVue/scripts/example_tool.py for it to show up in the HEC-DSSVue Script menu and toolbar.

The corresponding configuration file, for example input.yml, could look like this.

folder: C:\some\folder
files:
 - file 1.txt
 - file 2.txt

site: Site name
...

The configuration file is first validated using the schema attribute. This uses the voluptuous library for validation.

The user is prompted to select the configuration file when running the tool. Alternatively, the tool can be created like this:

tool = ExampleTool(configFileName, fullPathToDssFile)

This would be suitable for unattended execution of the tool.

1.3. “Fixing” the HEC-DSSVue configuration¶

HEC-DSSVue scripts are saved in the %APPDATA%/Roaming/HEC/HEC-DSSVue/scripts folder. Scripts in this folder can be run directly from HEC-DSSVue window.

All scripts are executed within the HEC-DSSVue application (Java-based) using an embedded Python interpreter, Jython 2.2 (a very old version). Install the Jython upgrade for HEC-DSSVue to upgrade to the most recent stable version of Jython. This will also modify the Python search path to include the scripts folder.

1.4. Debugging in HEC-DSSVue¶

To make debugging scripts in HEC-DSSVue easier, the Java console window can be shown when starting HEC-DSSVue by setting showConsole true in the %programfiles(x86)%/HEC/HEC-DSSVue/HEC-DSSVue.config file. Java and Jython errors will be displayed in this window.

Alternatively the console output can be inspected from the HEC-DSSVue menu Advanced ‣ Console Output....