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.

Installation

If you have the source directory of Girder, you can find the girder_client package within the clients/python directory. If you do not have the source directory of Girder, you can install the client via pip:

pip install girder-client

After installing the client via pip and if you are using bash, auto-completion can easily be enabled executing:

eval "$(_GIRDER_CLI_COMPLETE=source girder-client)"

For convenience, adding this line at the end of .bashrc will make sure auto-completion is always available.

For more details, see http://click.pocoo.org/6/bashcomplete/

The Command Line Interface

The girder_client package ships with a command-line utility that wraps some of its common functionality to make it easy to invoke operations without having to write any custom python scripts. If you have installed girder_client via pip, you can use the girder-client executable:

girder-client <arguments>

To see all available commands, run:

girder-client --help

For help with a specific command, run:

girder-client <command> --help

Specifying the Girder Instance

When constructing a Girder client, you must declare what instance of Girder you wish to connect to. The easiest way to do so is to pass the full URL to the REST API of the Girder instance you wish to connect to using the api-url argument to girder-client. For example:

girder-client --api-url http://localhost:8080/api/v1 <command> ...

Instead of using api-url argument, you may also specify the URL in parts, using the host argument, and optional scheme, port, and api-root args.

Specifying credentials

The recommended way is to generate an API key and specify the api-key argument.

girder-client --api-url https://girder.example.com:443/api/v1  --api-key abcdefghijklmopqrstuvwxyz012345678901234 ...

Setting the GIRDER_API_KEY environment variable is also supported:

export GIRDER_API_KEY=abcdefghijklmopqrstuvwxyz012345678901234
girder-client --api-url https://girder.example.com:443/api/v1 ...

The client also supports username and password args. If only the username is specified, the client will prompt the user to interactively input their password.

Disabling SSL verification

Specifying --no-ssl-verify allows to ignore SSL verification. This is usually required when using the client behind a proxy that is not configured to accept the certificate of the given host.

Specifying a custom SSL certificate

Specifying --certificate /path/to/custom_bundle.pem allows to use a custom “bundle” of Certificate Authority (CA) public keys (CA certs) for performing the SSL verification applied when the https scheme is associated with the API url.

By default, the carefully curated collection of Root Certificates from Mozilla is used. See https://pypi.python.org/pypi/certifi

Upload a local file hierarchy

To upload a folder hierarchy rooted at test_folder to the Girder Folder with id 54b6d41a8926486c0cbca367 (folder id can obtained from the URL):

girder-client upload 54b6d41a8926486c0cbca367 test_folder

When using the upload command, the default --parent-type, meaning the type of resource the local folder will be created under in Girder, is Folder, so the following are equivalent

girder-client upload 54b6d41a8926486c0cbca367 test_folder
girder-client upload 54b6d41a8926486c0cbca367 test_folder --parent-type folder

To upload that same local folder to a Collection or User, specify the parent type as follows

girder-client upload 54b6d41a8926486c0cbca459 test_folder --parent-type user

To see what local folders and files on disk would be uploaded without actually uploading anything, add the --dry-run flag

girder-client upload 54b6d41a8926486c0cbca367 test_folder --dry-run

To have leaf folders (those folders with no subfolders, only containing files) be uploaded to Girder as single Items with multiple Files, i.e. those leaf folders will be created as Items and all files within the leaf folders will be Files within those Items, add the --leaf-folders-as-items flag

girder-client upload 54b6d41a8926486c0cbca367 test_folder --leaf-folders-as-items

If you already have an existing Folder hierarchy in Girder which you have a superset of on your local disk (e.g. you previously uploaded a hierarchy to Girder and then added more folders and files to the hierarchy on disk), you can reuse the existing hierarchy in Girder, which will not create new Folders and Items for those that match folders and files on disk, by using the --reuse flag.

girder-client upload 54b6d41a8926486c0cbca367 test_folder --reuse

To include a blacklist of file patterns that will not be uploaded, pass a comma separated list to the --blacklist arg

girder-client upload 54b6d41a8926486c0cbca367 test_folder --blacklist .DS_Store

Note

The girder_client can upload to an S3 Assetstore when uploading to a Girder server that is version 1.3.0 or later.

Download a hierarchy of data into a local folder

Note

When downloading files, Girder writes them temporarily under the operating system’s temporary directory before moving them to their final destination. If you need the temporary files to be stored elsewhere, perhaps due to being on a different volume or device, simply set the TMPDIR environment variable to the desired location before invoking the download.

Folder

To download a Girder Folder hierarchy rooted at Folder id 54b6d40b8926486c0cbca364 under the local folder download_folder

girder-client download 54b6d40b8926486c0cbca364 download_folder

Collection

To download the Girder Folder hierarchies associated with a Girder Collection with id 57b5c9e58d777f126827f5a1 under the local folder download_folder

girder-client download --parent-type collection 57b5c9e58d777f126827f5a1 download_folder

User

To download the Girder Folder hierarchies associated with a Girder User with id 54f8ac238d777f69813604af under the local folder download_folder

girder-client download --parent-type user 54b6d40b8926486c0cbca364 download_folder

Item

To download the file(s) associated with a Girder Item with if 58b8eb798d777f0aef5d0f78 under the local folder download_folder:

girder-client download --parent-type item 8b8eb798d777f0aef5d0f78 download_folder

File

To download a specific file from girder with id 58b8eb798d777f0aef5d0f78 to the local file local_file

girder-client download --parent-type file 8b8eb798d777f0aef5d0f78  local_file

Auto-detecting parent-type

Both download and upload commands accept a --parent-type argument allowing the users to specify the type (folder, collection, user, or item) associated with the chosen object id.

If the argument is omitted, the client will conveniently try to autodetect the type by iteratively invoking the resource/%id/path?type=%type API end point and checking if a resource is found.

Note that relying on auto-detection incurs extra network requests, which will slow down the script, so it should be avoided for time-sensitive operations.

Synchronize local folder with a Folder hierarchy

If the download_folder is a local copy of a Girder Folder hierarchy rooted at Folder id 54b6d40b8926486c0cbca364, any change made to the Girder Folder remotely can be synchronized locally by

girder-client localsync 54b6d40b8926486c0cbca364 download_folder

This will only download new Items or Items that have been modified since the last download/localsync. Local files that are no longer present in the remote Girder Folder will not be removed. This command relies on a presence of metadata file .metadata-girder within download_folder, which is created upon girder-client download. If .metadata-girder is not present, localsync will fallback to download.

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.

Recursively inherit access control to a Folder’s descendants

This will take the access control and public value in the Girder Folder with id 54b43e9b8926486c0c06cb4f and copy those to all of the descendant Folders

import girder_client
gc = girder_client.GirderClient(apiUrl='https://data.kitware.com/api/v1')
gc.authenticate('username', 'password')
gc.inheritAccessControlRecursive('54b43e9b8926486c0c06cb4f')

Set callbacks for Folder and Item uploads

If you have a function you would like called upon the completion of an Item or Folder upload, you would do the following.

N.B. The Item callbacks are called after the Item is created and all Files are uploaded to the Item. The Folder callbacks are called after the Folder is created and all child Folders and Items are uploaded to the Folder.

import girder_client
gc = girder_client.GirderClient()

def folderCallback(folder, filepath):
    # assume we have a folderMetadata dict that has
    # filepath: metadata_dict_for_folder
    gc.addMetadataToFolder(folder['_id'], folderMetadata[filepath])

def itemCallback(item, filepath):
    # assume we have an itemMetadata dict that has
    # filepath: metadata_dict_for_item
    gc.addMetadataToItem(item['_id'], itemMetadata[filepath])

gc.authenticate('username', 'password')
gc.addFolderUploadCallback(folderCallback)
gc.addItemUploadCallback(itemCallback)
gc.upload(localFolder, parentId)

Further Examples and Function Level Documentation

exception girder_client.AuthenticationError[source]
class girder_client.GirderClient(host=None, port=None, apiRoot=None, scheme=None, apiUrl=None, cacheSettings=None, progressReporterCls=None)[source]

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

client = GirderClient(apiUrl='http://myhost:8080')
client.authenticate('myname', 'mypass')

folder_id = '53b714308926486402ac5aba'
item = client.createItem(folder_id, 'an item name', 'a description')
client.addMetadataToItem(item['_id'], {'metadatakey': 'metadatavalue'})
client.uploadFileToItem(item['_id'], 'path/to/your/file.txt')

r1 = client.getItem(item['_id'])
r2 = client.sendRestRequest('GET', 'item',
    {'folderId': folder_id, 'sortdir': '-1' })
r3 = client.sendRestRequest('GET', 'resource/search',
    {'q': 'aggregated','types': '["folder", "item"]'})
__init__(host=None, port=None, apiRoot=None, scheme=None, apiUrl=None, cacheSettings=None, progressReporterCls=None)[source]

Construct a new GirderClient object, given a host name and port number, as well as a username and password which will be used in all requests (HTTP Basic Auth). You can pass the URL in parts with the host, port, scheme, and apiRoot kwargs, or simply pass it in all as one URL with the apiUrl kwarg instead. If you pass apiUrl, the individual part kwargs will be ignored.

Parameters:
  • apiUrl – The full path to the REST API of a Girder instance, e.g. http://my.girder.com/api/v1.

  • host – A string containing the host name where Girder is running, the default value is ‘localhost’

  • port – The port number on which to connect to Girder, the default value is 80 for http: and 443 for https:

  • apiRoot – The path on the server corresponding to the root of the Girder REST API. If None is passed, assumes ‘/api/v1’.

  • scheme – A string containing the scheme for the Girder host, the default value is ‘http’; if you pass ‘https’ you likely want to pass 443 for the port

  • cacheSettings – Settings to use with the diskcache library, or None to disable caching.

  • progressReporterCls – the progress reporter class to instantiate. This class is expected to be a context manager with a constructor accepting label and length keyword arguments, an update method accepting a chunkSize argument and a class attribute reportProgress set to True (It can conveniently be initialized using sys.stdout.isatty()). This defaults to _NoopProgressReporter.

addFolderUploadCallback(callback)[source]

Saves a passed in callback function that will be called after each folder has completed. Multiple callback functions can be added, they will be called in the order they were added by calling this function. Callback functions will be called after a folder in Girder is created and all subfolders and items for that folder have completed uploading. Callback functions should take two parameters: - the folder in Girder - the full path to the local folder

Parameters:

callback – callback function to be called.

addItemUploadCallback(callback)[source]

Saves a passed in callback function that will be called after each item has completed. Multiple callback functions can be added, they will be called in the order they were added by calling this function. Callback functions will be called after an item in Girder is created and all files for that item have been uploaded. Callback functions should take two parameters: - the item in Girder - the full path to the local folder or file comprising the item

Parameters:

callback – callback function to be called.

addMetadataToCollection(collectionId, metadata)[source]

Takes a collection ID and a dictionary containing the metadata

Parameters:
  • collectionId – ID of the collection to set metadata on.

  • metadata – dictionary of metadata to set on collection.

addMetadataToFolder(folderId, metadata)[source]

Takes a 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, apiKey=None)[source]

Authenticate to Girder, storing the token that comes back to be used in future requests. This method can be used in two modes, either username and password authentication, or using an API key. Username example:

gc.authenticate(username='myname', password='mypass')

Note that you may also pass interactive=True and omit either the username or password argument to be prompted for them in the shell. The second mode is using an API key:

API keys can be created and managed on your user account page in the Girder web client, and can be used to provide limited access to the Girder web API.

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. This option only works in username/password mode, not API key mode.

  • apiKey (str) – Pass this to use an API key instead of username/password authentication.

createCollection(name, description='', public=False)[source]

Creates and returns a collection.

createFolder(parentId, name, description='', parentType='folder', public=None, reuseExisting=False, metadata=None)[source]

Creates and returns a folder.

Parameters:
  • parentId – The id of the parent resource to create the folder in.

  • name – The name of the folder.

  • description – A description of the folder.

  • parentType – One of (‘folder’, ‘user’, ‘collection’)

  • public – Whether the folder should be marked a public.

  • reuseExisting – Whether to return an existing folder if one with the same name exists.

  • metadata – JSON metadata to set on the folder.

createItem(parentFolderId, name, description='', reuseExisting=False, metadata=None)[source]

Creates and returns an item.

Parameters:
  • parentFolderId – the folder this item should be created in.

  • name – the item name.

  • description – a description of the item.

  • reuseExisting – whether to return an existing item if one with same name already exists.

  • metadata – JSON metadata to set on item.

createResource(path, params)[source]

Creates and returns a resource.

createUser(login, email, firstName, lastName, password, admin=None)[source]

Creates and returns a user.

delete(path, parameters=None, jsonResp=True)[source]

Convenience method to call sendRestRequest() with the ‘DELETE’ HTTP method.

downloadFile(fileId, path, created=None)[source]

Download a file to the given local path or file-like object.

Parameters:
  • fileId – The ID of the Girder file to download.

  • path – The path to write the file to, or a file-like object.

downloadFileAsIterator(fileId, chunkSize=65536)[source]

Download a file streaming the contents as an iterator.

Parameters:
  • fileId – The ID of the Girder file to download.

  • chunkSize – The chunk size to download the contents in.

Returns:

The request content iterator.

downloadFolderRecursive(folderId, dest, sync=False)[source]

Download a folder recursively from Girder into a local directory.

Parameters:
  • folderId (ObjectId or Unix-style path to the resource in Girder.) – Id of the Girder folder or resource path to download.

  • dest (str) – The local download destination.

  • sync (bool) – If True, check if item exists in local metadata cache and skip download provided that metadata is identical.

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.

downloadResource(resourceId, dest, resourceType='folder', sync=False)[source]

Download a collection, user, or folder recursively from Girder into a local directory.

Parameters:
  • resourceId (ObjectId or Unix-style path to the resource in Girder.) – ID or path of the resource to download.

  • dest (str) – The local download destination. Can be an absolute path or relative to the current working directory.

  • resourceType (str) – The type of resource being downloaded: ‘collection’, ‘user’, or ‘folder’.

  • sync (bool) – If True, check if items exist in local metadata cache and skip download if the metadata is identical.

get(path, parameters=None, jsonResp=True)[source]

Convenience method to call sendRestRequest() with the ‘GET’ HTTP method.

getCollection(collectionId)[source]

Retrieves a collection by its ID.

Parameters:

collectionId – A string containing the ID of the collection to retrieve from Girder.

static getDefaultPort(hostname, scheme)[source]

Get default port based on the hostname. Returns GirderClient.DEFAULT_HTTPS_PORT if scheme is https, otherwise returns GirderClient.DEFAULT_LOCALHOST_PORT if hostname is localhost, and finally returns GirderClient.DEFAULT_HTTP_PORT.

static getDefaultScheme(hostname)[source]

Get default scheme based on the hostname. Returns http if hostname is localhost otherwise returns https.

getFile(fileId)[source]

Retrieves a file by its ID.

Parameters:

fileId – A string containing the ID of the file to retrieve from Girder.

getFolder(folderId)[source]

Retrieves a folder by its ID.

Parameters:

folderId – A string containing the ID of the folder to retrieve from Girder.

getFolderAccess(folderId)[source]

Retrieves a folder’s access by its ID.

Parameters:

folderId – A string containing the ID of the folder to retrieve access for 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=None, property=None)[source]

Returns a resource based on id or None if no resource is found; if property is passed, returns that property value from the found resource.

getServerAPIDescription(useCached=True)[source]

Fetch server RESTful API description.

Parameters:

useCached (bool) – Whether to return the previously fetched value. Set to False to force a re-fetch of the description from the server.

Returns:

The API descriptions as a dict.

For example:

{
    "basePath": "/api/v1",
    "definitions": {},
    "host": "girder.example.com",
    "info": {
        "title": "Girder REST API",
        "version": "X.Y.Z"
    },
    "paths": {
        "/api_key": {
            "get": {
                "description": "Only site administrators [...]",
                "operationId": "api_key_listKeys",
                "parameters": [
                    {
                        "description": "ID of the user whose keys to list.",
                        "in": "query",
                        "name": "userId",
                        "required": false,
                        "type": "string"
                    },
                    ...
                ]
            }.
            ...
        }
    ...
    }
}
getServerVersion(useCached=True)[source]

Fetch server API version. By default, caches the version such that future calls to this function do not make another request to the server.

Parameters:

useCached (bool) – Whether to return the previously fetched value. Set to False to force a re-fetch of the version from the server.

Returns:

The API version as a list (e.g. ['1', '0', '0'])

getUser(userId)[source]

Retrieves a user by its ID.

Parameters:

userId – A string containing the ID of the user to retrieve from Girder.

inheritAccessControlRecursive(ancestorFolderId, access=None, public=None)[source]

Take the access control and public value of a folder and recursively copy that access control and public value to all folder descendants, replacing any existing access control on the descendant folders with that of the ancestor folder.

Parameters:
  • ancestorFolderId – Id of the Girder folder to copy access control from, to all of its descendant folders.

  • access – Dictionary Access control target, if None, will take existing access control of ancestor folder

  • public – Boolean public value target, if None, will take existing public value of ancestor folder

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 length. 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 size 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.

listCollection(limit=None, offset=None)[source]

This is a generator that will yield all collections in the system.

Parameters:
  • limit – If requesting a specific slice, the length of the slice.

  • offset – Starting offset into the list.

listFile(itemId, limit=None, offset=None)[source]

This is a generator that will yield files under the given itemId.

Parameters:
  • itemId – the item’s ID

  • limit – the result set size limit.

  • offset – the result offset.

listFolder(parentId, parentFolderType='folder', name=None, limit=None, offset=None)[source]

This is a generator that will yield a list of folders based on the filter parameters.

Parameters:
  • parentId – The parent’s ID.

  • parentFolderType – One of (‘folder’, ‘user’, ‘collection’).

  • name – query for exact name match of items.

  • limit – If requesting a specific slice, the length of the slice.

  • offset – Starting offset into the list.

listItem(folderId, text=None, name=None, limit=None, offset=None)[source]

This is a generator that will yield all items under a given folder.

Parameters:
  • folderId – the parent folder’s ID.

  • text – query for full text search of items.

  • name – query for exact name match of items.

  • limit – If requesting a specific slice, the length of the slice.

  • offset – Starting offset into the list.

listResource(path, params=None, limit=None, offset=None)[source]

This is a generator that will yield records using the given path and params until exhausted. Paging of the records is done internally, but can be overriden by manually passing a limit value to select only a single page. Passing an offset will work in both single-page and exhaustive modes.

listUser(limit=None, offset=None)[source]

This is a generator that will yield all users in the system.

Parameters:
  • limit – If requesting a specific slice, the length of the slice.

  • offset – Starting offset into the list.

loadLocalMetadata(dest)[source]

Reads item metadata from a local folder.

Parameters:

dest – The local download destination.

loadOrCreateFolder(folderName, parentId, parentType, metadata=None)[source]

Returns a folder in Girder with the given name under the given parent. If none exists yet, it will create it and return it.

Parameters:
  • folderName – the name of the folder to look up.

  • parentId – id of parent in Girder

  • parentType – one of (collection, folder, user)

  • metadata – JSON metadata string to set on folder.

Returns:

The folder that was found or created.

loadOrCreateItem(name, parentFolderId, reuseExisting=True, metadata=None)[source]

Create an item with the given name in the given parent folder.

Parameters:
  • name – The name of the item to load or create.

  • parentFolderId – id of parent folder in Girder

  • reuseExisting – boolean indicating whether to load an existing item of the same name in the same location, or create a new one.

  • metadata – JSON metadata string to set on item.

patch(path, parameters=None, data=None, json=None, jsonResp=True)[source]

Convenience method to call sendRestRequest() with the ‘PATCH’ HTTP method.

post(path, parameters=None, files=None, data=None, json=None, headers=None, jsonResp=True)[source]

Convenience method to call sendRestRequest() with the ‘POST’ HTTP method.

put(path, parameters=None, data=None, json=None, jsonResp=True)[source]

Convenience method to call sendRestRequest() with the ‘PUT’ HTTP method.

resourceLookup(path)[source]

Look up and retrieve resource in the data hierarchy by path.

Parameters:

path – The path of the resource. The path must be an absolute Unix path starting with either “/user/[user name]” or “/collection/[collection name]”.

saveLocalMetadata(dest)[source]

Dumps item metadata collected during a folder download.

Parameters:

dest – The local download destination.

sendRestRequest(method, path, parameters=None, data=None, files=None, json=None, headers=None, jsonResp=True, **kwargs)[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 that might need to be specially encoded or handled differently.

Parameters:
  • method (str) – The HTTP method to use in the request (GET, POST, etc.)

  • path (str) – A string containing the path elements for this request. Note that the path string should not begin or end with the path separator, ‘/’.

  • parameters (dict) – A dictionary mapping strings to strings, to be used as the key/value pairs in the request parameters.

  • data – A dictionary, bytes or file-like object to send in the body.

  • files (dict) – A dictionary of ‘name’ => file-like-objects for multipart encoding upload.

  • json (dict) – A JSON object to send in the request body.

  • headers (dict) – If present, a dictionary of headers to encode in the request.

  • jsonResp (bool) –

    Whether the response should be parsed as JSON. If False, the raw response object is returned. To get the raw binary content of the response, use the content attribute of the return value, e.g.

    resp = client.get('my/endpoint', jsonResp=False)
    print(resp.content)  # Raw binary content
    print(resp.headers)  # Dict of headers
    

session(session=None)[source]

Use a requests.Session object for all outgoing requests from GirderClient. If session isn’t passed into the context manager then one will be created and yielded. Session objects are useful for enabling persistent HTTP connections as well as partially applying arguments to many requests, such as headers.

Note: session is closed when the context manager exits, regardless of who created it.

with gc.session() as session:
    session.headers.update({'User-Agent': 'myapp 1.0'})

    for itemId in itemIds:
        gc.downloadItem(itemId, fh)

In the above example, each request will be executed with the User-Agent header while reusing the same TCP connection.

Parameters:

session – An existing requests.Session object, or None.

setFolderAccess(folderId, access, public)[source]

Sets the passed in access control document along with the public value to the target folder.

Parameters:
  • folderId – Id of the target folder.

  • access – JSON document specifying access control.

  • public – Boolean specificying the public value.

setResourceTimestamp(id, type, created=None, updated=None)[source]

Set the created or updated timestamps for a resource.

setToken(token)[source]

Set a token on the GirderClient instance. This is useful in the case where the client has already been given a valid token, such as a remote job.

Parameters:

token – A string containing the existing Girder token

transformFilename(name)[source]

Sanitize a resource name from Girder into a name that is safe to use as a filesystem path.

Parameters:

name (str) – The name to transform.

upload(filePattern, parentId, parentType='folder', leafFoldersAsItems=False, reuseExisting=False, blacklist=None, dryRun=False, reference=None)[source]

Upload a pattern of files.

This will recursively walk down every tree in the file pattern to create a hierarchy on the server under the parentId.

Parameters:
  • filePattern (str) – a glob pattern for files that will be uploaded, recursively copying any file folder structures. If this is a list or tuple each item in it will be used in turn.

  • parentId (ObjectId or Unix-style path to the resource in Girder.) – Id of the parent in Girder or resource path.

  • parentType (str) – one of (collection,folder,user), default of folder.

  • leafFoldersAsItems (bool) – bool whether leaf folders should have all files uploaded as single items.

  • reuseExisting (bool) – bool whether to accept an existing item of the same name in the same location, or create a new one instead.

  • dryRun (bool) – Set this to True to print out what actions would be taken, but do not actually communicate with the server.

  • reference (str) – Option reference to send along with the upload.

uploadFile(parentId, stream, name, size, parentType='item', progressCallback=None, reference=None, mimeType=None)[source]

Uploads a file into an item or folder.

Parameters:
  • parentId (str) – The ID of the folder or item to upload into.

  • stream (file-like) – Readable stream object.

  • name (str) – The name of the file to create.

  • size (str) – The length of the file. This must be exactly equal to the total number of bytes that will be read from stream, otherwise the upload will fail.

  • parentType (str) – ‘item’ or ‘folder’.

  • progressCallback (callable) – If passed, will be called after each chunk with progress information. It passes a single positional argument to the callable which is a dict of information about progress.

  • reference (str) – optional reference to send along with the upload.

  • mimeType (str or None) – MIME type to set on the file. Attempts to guess if not explicitly passed.

Returns:

The file that was created on the server.

uploadFileContents(fileId, stream, size, reference=None)[source]

Uploads the contents of an existing file.

Parameters:
  • fileId – ID of file to update

  • stream (file-like) – Readable stream object.

  • size (str) – The length of the file. This must be exactly equal to the total number of bytes that will be read from stream, otherwise the upload will fail.

  • reference (str) – optional reference to send along with the upload.

uploadFileToFolder(folderId, filepath, reference=None, mimeType=None, filename=None, progressCallback=None)[source]

Uploads a file to a folder, creating a new item in the process. If the file has 0 bytes, no uploading will be performed, and no item will be created.

Parameters:
  • folderId – ID of parent folder for file.

  • filepath – path to file on disk.

  • reference (str) – optional reference to send along with the upload.

  • mimeType (str or None) – MIME type for the file. Will be guessed if not passed.

  • filename – path with filename used in Girder. Defaults to basename of filepath.

  • progressCallback (callable) – If passed, will be called after each chunk with progress information. It passes a single positional argument to the callable which is a dict of information about progress.

Returns:

the file that was created.

uploadFileToItem(itemId, filepath, reference=None, mimeType=None, filename=None, progressCallback=None)[source]

Uploads a file to an item, in chunks. If ((the file already exists in the item with the same name and size) 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.

  • reference (str) – optional reference to send along with the upload.

  • mimeType (str or None) – MIME type for the file. Will be guessed if not passed.

  • filename – path with filename used in Girder. Defaults to basename of filepath.

  • progressCallback (callable) – If passed, will be called after each chunk with progress information. It passes a single positional argument to the callable which is a dict of information about progress.

Returns:

the file that was created.

uploadStreamToFolder(folderId, stream, filename, size, reference=None, mimeType=None, progressCallback=None)[source]

Uploads a file-like object to a folder, creating a new item in the process. If the file has 0 bytes, no uploading will be performed, and no item will be created.

Parameters:
  • folderId – ID of parent folder for file.

  • stream – Readable stream object.

  • filename – Filename used for Girder only.

  • size – The length of the file. This must be exactly equal to the total number of bytes that will be read from stream, otherwise the upload will fail.

  • reference – optional reference to send along with the upload.

  • mimeType – MIME type for the file.

  • progressCallback – If passed, will be called after each chunk with progress information. It passes a single positional argument to the callable which is a dict of information about progress.

exception girder_client.HttpError(status, text, url, method, response=None)[source]

Raised if the server returns an error status code from a request. @deprecated This will be removed in a future release of Girder. Raisers of this exception should instead raise requests.HTTPError manually or through another mechanism such as requests.Response.raise_for_status.

__init__(status, text, url, method, response=None)[source]

Initialize RequestException with request and response objects.

exception girder_client.IncompleteResponseError(message, expected, received, response=None)[source]
__init__(message, expected, received, response=None)[source]

Initialize RequestException with request and response objects.

exception girder_client.IncorrectUploadLengthError(message, upload=None)[source]
__init__(message, upload=None)[source]