Binder

hsclient HydroShare Python Client Basic Resource Operation Examples


The following code snippets show examples for how to use the hsclient HydroShare Python Client for performing basic resource operations.

Install the hsclient Python Client

The hsclient Python Client for HydroShare may not be installed by default in your Python environment, so it has to be installed first before you can work with it. Use the following command to install hsclient via the Python Package Index (PyPi).

!pip install hsclient

Authenticating with HydroShare

Before you start interacting with resources in HydroShare you will need to authenticate. To authenticate with HydroShare, you can either specify your username and password or you can call the sign_in() function, which will prompt you to input your username and password.

from hsclient import HydroShare

username = 'username'
password = 'password'
hs = HydroShare(username, password)

In most cases you will not want anyone to see your username and password, so you can also call the sign_in() function to be prompted for your username and password. This is better to use if you are sharing a Jupyter Notebook.

from hsclient import HydroShare

hs = HydroShare()
hs.sign_in()

Basic Resource Operations

Create a New Empty Resource

A "resource" is a container for your content in HydroShare. Think of it as a "working directory" into which you are going to organize the code and/or data you are using and want to share. The following code can be used to create a new, empty resource within which you can create content and metadata.

This code creates a new resource in HydroShare. It also creates an in-memory object representation of that resource in your local environmment that you can then manipulate with further code.

# Create the new, empty resource
new_resource = hs.create()

# Get the HydroShare identifier for the new resource
res_identifier = new_resource.resource_id
print(f'The HydroShare Identifier for your new resources is: {res_identifier}')

# Construct a hyperlink to access the HydroShare landing page for the new resource
print(f'Your new resource is available at: {new_resource.metadata.url}')

Retrieving an Existing Resource

If you want to work on an existing resource rather than creating a new one, you can retrieve an existing resource using its HydroShare identifier. The resource identifier is passed as a string. The resource's metadata is retrieved and loaded into memory.

# Get an existing resource using its identifier
existing_resource = hs.resource(res_identifier)
print(f'Just retrieved the resource with ID: {res_identifier}')

Deleting a Resource

If you want to delete a resource you are currently working with, you can just call the delete() function on that resource. This will delete your local copy of the resource and the resource in HydroShare.

new_resource.delete()

Alternatively, if you know the HydroShare identifier of the resource you want to delete, you can use it to delete the resource.

# Delete the resource using its identifier
hs.resource(res_identifier).delete()
print(f'Deleted resource with ID: {res_identifier}')

Download an Entire Resource

HydroShare allows you to download an entire resource as a zipped file that uses the BagIt packaging standard. You can identify the resource you want to download using its HydroShare identifier. When you call the download() function on the resource, you can pass a path where you want to save the zipped file. Leaving the path blank downloads the files to the directory.

This example downloads the HydroShare resource containing these example Jupyter Notebooks.

# Get the resource you want to download using its identifier
res_identifier = '7561aa12fd824ebb8edbee05af19b910'
res = hs.resource(res_identifier)

# Download the resource as a zipped Bagit file
# Pass in a file path if you want to download to a particular location
res.download()