HSTools

A humble collection of HydroShare tools written in Python 3. The hstools library was originally a port of the CUAHSI JupyterHub utilities.hydroshare package modified to work on desktop computers. The goal is to provide a set of basic functions that simplify working with HydroShare data.

Libaray Installation

git clone https://github.com/Castronova/hstools.git
cd hstools
python setup.py install

Getting Started

After the libary is installed, it can be executed using the following command: hs. There are currently 6 options for interacting with HydroShare: get, add, create, delete, ls, and init. For detailed information about any of these add the --help flag after the options, e.g. $hs get --help.

$ hs
usage: hs [-h] {get,add,create,delete,ls,init} ...

HSTools is a humble collection of tools for interacting with data in the
HydroShare repository. It wraps the HydroShare REST API to provide simple
commands for working with resources.

positional arguments:
  {get,add,create,delete,ls,init}
    get                 Retrieve resource content from HydroShare
    add                 Add files to an existing HydroShare resource
    create              Create a new HydroShare resource
    delete              Delete a HydroShare resource
    list                List HydroShare resources that you own
    init                Initialize a connection with HydroShare

optional arguments:
  -h, --help            show this help message and exit

Initialize a Connection to HydroShare

Connect to HydroShare using the init option. This will create an authentication file for accessing HydroShare that is cached in your $HOME directory by default. This path can be changed using the -d flag. Note, this command only needs to be executed once.

$ hs init
Enter HydroShare Username: <username>
Enter HydroShare Password: <password>
Auth saved to: ~/.hs_auth

Create a HydroShare Resource

Create a new HydroShare resource using the create options.

$ hs create \
-a This is the abstract of my resource \
-t My resource Title \
-k keyword1 keyword2 keyword3 \
-f myfile.txt ./another/file.txt

List HydroShare Resources

Listing HydroShare resources using the ls options.

$ hs list

List files in long format

$ hs list -l

List the first 17 resources in long format

$ hs list -l -n 17

Filter resources by published

$ hs list -filter published=true

Download a HydroShare Resource

Downloading data from the HydroShare platform is done using globally unique identfiers (GUID). This GUIDs are defined for every HydroShare resource and can be aquired from a resources URL. The get option downloads the resource bagit archive and unzips it into a directory of your choosing.

$ hs get <hydroshare resource id>

Add Files to a HydroShare Resource

Add files to an existing HydroShare resource using the add option. This command allows you to optionally overwrite (--overwrite) files that already exist in a resource, which is helpful when updating content.

$ hs add <hydroshare resource id> -f my-file.txt my-other-file.txt

Deleting a HydroShare Resource

Delete an entire HydroShare resource using the delete option. This is useful for cleaning up your HydroShare workspace. BEWARE: THIS WILL PERMANENTLY DELETE YOUR HYDROSHARE RESOURCE DATA.

$ hs delete <hydroshare resource id>