Python Client and Girder CLI

In addition to the web clients, Girder comes with a python client library and a CLI to allow for programmatic interaction with a Girder server, and also to workaround limitations of the web client. For example, the python CLI makes it much easier to upload a large, nested hierarchy of data from a local directory to Girder, and also makes it much easier to download a large, nested hierarchy of data from Girder to a local directory.

The Command Line Interface

<<< Mike please document >>>

The Python Client Library

For those wishing to write their own python scripts that interact with Girder, we recommend using the Girder python client library, documented below.

class girder_client.GirderClient(host='localhost', port=8080, apiRoot=None)[source]

A class for interacting with the Girder RESTful API. Some simple examples of how to use this class follow:

client = GirderClient('myhost', 9000)
client.authenticate('myname', 'mypass')

itemId = client.createitem(folderId, 'an item name', 'a description')
client.addMetadataToItem(itemId, {'metadatakey': 'metadatavalue'})
client.uploadFileToItem(itemId, 'path/to/your/file.txt')

r1 = client.getItem('52e935037bee0436e29a7130')
r2 = client.sendRestRequest('GET', 'item',
    {'folderId': '52e97b2b7bee0436e29a7142', 'sortdir': '-1' })
r3 = client.sendRestRequest('GET', 'resource/search',
    {'q': 'aggregated','types': '["folder", "item"]'})
addMetadataToFolder(folderId, metadata)[source]

Takes an folder ID and a dictionary containing the metadata

Parameters:
  • folderId – ID of the folder to set metadata on.
  • metadata – dictionary of metadata to set on folder.
addMetadataToItem(itemId, metadata)[source]

Takes an item ID and a dictionary containing the metadata

Parameters:
  • itemId – ID of the item to set metadata on.
  • metadata – dictionary of metadata to set on item.
authenticate(username=None, password=None, interactive=False)[source]

Authenticate to Girder, storing the token that comes back to be used in future requests.

Parameters:
  • username – A string containing the username to use in basic authentication.
  • password – A string containing the password to use in basic authentication.
  • interactive – If you want the user to type their username or password in the shell rather than passing it in as an argument, set this to True. If you pass a username in interactive mode, the user will only be prompted for a password.
createFolder(parentId, parentType, name, description)[source]

Creates and returns an folder

Parameters:parentType – One of (‘folder’, ‘user’, ‘collection’)
createItem(parentFolderId, name, description)[source]

Creates and returns an item.

createResource(path, params)[source]

Creates and returns a resource.

downloadFile(fileId, path)[source]

Download a file to the given local path.

Parameters:
  • fileId – The ID of the Girder file to download.
  • path – The local path to write the file to.
downloadFolderRecursive(folderId, dest)[source]

Download a folder recursively from Girder into a local directory.

Parameters:
  • folderId – Id of the Girder folder to download.
  • dest – The local download destination.
downloadItem(itemId, dest, name=None)[source]

Download an item from Girder into a local folder. Each file in the item will be placed into the directory specified by the dest parameter. If the item contains multiple files or a single file with a different name than the item, the item will be created as a directory under dest and the files will become files within that directory.

Parameters:
  • itemId – The Id of the Girder item to download.
  • dest – The destination directory to write the item into.
  • name – If the item name is known in advance, you may pass it here which will save a lookup to the server.
file_chunker(filepath, filesize=None)[source]

Generator returning chunks of a file in MAX_CHUNK_SIZE increments.

Parameters:
  • filepath – path to file on disk.
  • filesize – size of file on disk if known.
getFolder(folderId)[source]

Retrieves a folder by its ID.

Parameters:folderId – A string containing the ID of the folder to retrieve from Girder.
getItem(itemId)[source]

Retrieves a item by its ID.

Parameters:itemId – A string containing the ID of the item to retrieve from Girder.
getResource(path, id)[source]

Loads a resource by id or None if no resource is returned.

isFileCurrent(itemId, filename, filepath)[source]

Tests whether the passed in filepath exists in the item with itemId, with a name of filename, and with the same contents as the file at filepath. Returns a tuple (file_id, current) where file_id = id of the file with that filename under the item, or None if no such file exists under the item. current = boolean if the file with that filename under the item has the same contents as the file at filepath.

Parameters:
  • itemId – ID of parent item for file.
  • filename – name of file to look for under the parent item.
  • filepath – path to file on disk.
listFolder(parentId, parentFolderType='folder')[source]

Retrieves a folder set from this parent ID.

Parameters:
  • parentId – The parent’s ID.
  • parentFolderType – One of (‘folder’, ‘user’, ‘collection’).
listItem(folderId, text=None)[source]

Retrieves a item set from this folder ID.

Parameters:
  • folderId – the parent folder’s ID.
  • text – query for full text search of items, optional.
listResource(path, params)[source]

search for a list of resources based on params.

sendRestRequest(method, path, parameters=None, data=None, files=None)[source]

This method looks up the appropriate method, constructs a request URL from the base URL, path, and parameters, and then sends the request. If the method is unknown or if the path is not found, an exception is raised, otherwise a JSON object is returned with the Girder response.

This is a convenience method to use when making basic requests that do not involve multipart file data which might need to be specially encoded or handled differently.

Parameters:
  • method – One of ‘GET’, ‘POST’, ‘PUT’, or ‘DELETE’
  • path – A string containing the path elements for this request. Note that the path string should not begin or end with the path separator, ‘/’.
  • parameters – A dictionary mapping strings to strings, to be used as the key/value pairs in the request parameters
sha512_hasher(filepath)[source]

Returns sha512 hash of passed in file.

Parameters:filepath – path to file on disk.
uploadFileToItem(itemId, filepath)[source]

Uploads a file to an item, in chunks. If ((the file already exists in the item with the same name and sha512) or (if the file has 0 bytes), no uploading will be performed.

Parameters:
  • itemId – ID of parent item for file.
  • filepath – path to file on disk.