API Documentation

RESTful API

Clients access Girder servers uniformly via its RESTful web API. By providing a single, stable, consistent web API, it is possible to write multiple interchangeable clients using different technologies.

When a Girder instance is deployed, it typically also serves a page that uses Swagger to document all available RESTful endpoints in the web API and also provide an easy way for users to execute those endpoints with parameters of their choosing. In this way, the Swagger page is just the simplest and lightest client application for Girder. This page is served out of the path /api under the root path of your Girder instance.

Internal Python API

Models

In Girder, the model layer is responsible for actually interacting with the underlying database. Model classes are where the documents representing resources are actually saved, retrieved, and deleted from the DBMS. Validation of the resource documents is also done in the model layer, and is invoked each time a document is about to be saved.

Typically, there is a model class for each resource type in the system. These models are loaded as singletons for efficiency, but you should use them like normal objects. For example, to use the list method of the Group model:

from girder.models.group import Group
groups = Group().list(user=self.getCurrentUser())

All models that require the standard access control semantics should extend the AccessControlledModel class. Otherwise, they should extend the Model class.

All model classes must have an initialize method in which they declare the name of their corresponding Mongo collection, as well as any collection indexes they require. For example, to make a model whose documents live in a collection called cat_collection and ensure that the name key is indexed on that collection, you would use the following initialize method:

from girder.models.model_base import Model

class Cat(Model):
    def initialize(self):
        self.name = 'cat_collection'
        self.ensureIndex('name')

Model Helper Functions

girder.models.getDbConfig()[source]

Get the database configuration values from the cherrypy config.

girder.models.getDbConnection(uri=None, replicaSet=None, autoRetry=True, quiet=False, **kwargs)[source]

Get a MongoClient object that is connected to the configured database. We lazy-instantiate a module-level singleton, the MongoClient objects manage their own connection pools internally. Any extra kwargs you pass to this method will be passed through to the MongoClient.

Parameters:
  • uri – if specified, connect to this mongo db rather than the one in the config.
  • replicaSet – if uri is specified, use this replica set.
  • autoRetry (bool) – if this connection should automatically retry operations in the event of an AutoReconnect exception. If you’re testing the connection, set this to False. If disabled, this also will not cache the mongo client, so make sure to only disable if you’re testing a connection.
  • quiet (bool) – if true, don’t logprint warnings and success.

Model Base

class girder.models.model_base.AccessControlledModel[source]

Any model that has access control requirements should inherit from this class. It enforces permission checking in the load() method and provides convenient methods for testing and requiring user permissions. It also provides methods for setting access control policies on the resource.

copyAccessPolicies(src, dest, save=False)[source]

Copies the set of access control policies from one document to another.

Parameters:
  • src (dict) – The source document to copy policies from.
  • dest (dict) – The destination document to copy policies onto.
  • save (bool) – Whether to save the destination document after copying.
Returns:

The modified destination document.

filter(doc, user, additionalKeys=None)[source]

Filter this model for the given user according to the user’s access level. Also adds the special _accessLevel field to the document to indicate the user’s highest access level. This filters a single document that the user has at least read access to. For filtering a set of documents, see filterResultsByPermission().

Parameters:
  • doc (dict or None) – The document of this model type to be filtered.
  • user (dict or None) – The current user for whom we are filtering.
  • additionalKeys (list, tuple, or None) – Any additional keys that should be included in the document for this call only.
Returns:

The filtered document (dict).

filterResultsByPermission(cursor, user, level, limit=0, offset=0, removeKeys=(), flags=None)[source]

Given a database result cursor, this generator will yield only the results that the user has the given level of access and specified access flags on, respecting the limit and offset specified.

Parameters:
  • cursor – The database cursor object from “find()”.
  • user (dict or None) – The user to check policies against.
  • level (AccessType) – The access level.
  • limit (int) – Maximum number of documents to return
  • offset (int) – The offset into the results
  • removeKeys (list) – List of keys that should be removed from each matching document.
  • flags (flag identifier, or a list/set/tuple of them) – A flag or set of flags to test.
findWithPermissions(query=None, offset=0, limit=0, timeout=None, fields=None, sort=None, user=None, level=0, **kwargs)[source]

Search the collection by a set of parameters, only returning results that the combined user and level have permission to access. Passes any extra kwargs through to the underlying pymongo.collection.find function.

Parameters:
  • query (dict) – The search query (see general MongoDB docs for “find()”)
  • offset (int) – The offset into the results
  • limit (int) – Maximum number of documents to return
  • timeout (int) – Cursor timeout in ms. Default is no timeout.
  • fields (str, list, set, or tuple) – A mask for filtering result documents by key, or None to return the full document, passed to MongoDB find() as the projection param. This is a string or iterable of strings to be included from the document, or dict for an inclusion or exclusion projection`.
  • sort (List of (key, order) tuples.) – The sort order.
  • user (dict or None) – The user to check policies against.
  • level (AccessType) – The access level. Explicitly passing None skips doing permissions checks.
Returns:

A pymongo Cursor or CommandCursor. If a CommandCursor, it has been augmented with a count function.

getAccessLevel(doc, user)[source]

Return the maximum access level for a given user on a given object. This can be useful for alerting the user which set of actions they are able to perform on the object in advance of trying to call them.

Parameters:
  • doc – The object to check access on.
  • user – The user to get the access level for.
Returns:

The max AccessType available for the user on the object.

getFullAccessList(doc)[source]

Return an object representing the full access list on this document. This simply includes the names of the users and groups with the ACL.

If the document contains references to users or groups that no longer exist, they are simply removed from the ACL, and the modified ACL is persisted at the end of this method if any removals occurred.

Parameters:doc (dict) – The document whose ACL to return.
Returns:A dict containing users and groups keys.
hasAccess(doc, user=None, level=0)[source]

This method looks through the object’s permission set and determines whether the user has the given permission level on the object.

Parameters:
  • doc (dict) – The document to check permission on.
  • user (dict) – The user to check against.
  • level (AccessType) – The access level.
Returns:

Whether the access is granted.

hasAccessFlags(doc, user=None, flags=None)[source]

Test whether a specific user has a given set of access flags on the given resource. Returns True only if the user has all of the flags by virtue of either group membership, public flags, or explicit access granted to the user.

Parameters:
  • doc (dict) – The resource to test access on.
  • user (dict or None) – The user to check against.
  • flags – A flag or set of flags to test.
list(user=None, limit=0, offset=0, sort=None)[source]

Return a list of documents that are visible to a user.

Parameters:
  • user (dict or None) – The user to filter for
  • limit (int) – Maximum number of documents to return
  • offset (int) – The offset into the results
  • sort (List of (key, order) tuples) – The sort order
load(id, level=2, user=None, objectId=True, force=False, fields=None, exc=False)[source]

Override of Model.load to also do permission checking.

Parameters:
  • id (str or ObjectId) – The id of the resource.
  • level (AccessType) – The required access type for the object.
  • user (dict or None) – The user to check access against.
  • objectId (bool) – Whether the id should be coerced to ObjectId type.
  • force (bool) – If you explicitly want to circumvent access checking on this resource, set this to True.
  • fields (list or dict) – A mask for filtering result documents by key, or None to return the full document, passed to MongoDB find() as the projection param.
  • exc (bool) – If not found, throw a ValidationException instead of returning None.
Raises:

ValidationException – If an invalid ObjectId is passed.

Returns:

The matching document, or None if no match exists.

prefixSearch(query, user=None, filters=None, limit=0, offset=0, sort=None, fields=None, level=0, prefixSearchFields=None)[source]

Custom override of Model.prefixSearch to also force permission-based filtering. The parameters are the same as Model.prefixSearch.

Parameters:
  • query (str) – The prefix string to look for
  • user (dict or None) – The user to apply permission filtering for.
  • filters (dict) – Any additional query operators to apply.
  • limit (int) – Maximum number of documents to return
  • offset (int) – The offset into the results
  • sort (List of (key, order) tuples.) – The sort order.
  • fields (str, list, set, or tuple) – A mask for filtering result documents by key, or None to return the full document, passed to MongoDB find() as the projection param. This is a string or iterable of strings to be included from the document, or dict for an inclusion or exclusion projection`.
  • level (girder.constants.AccessType) – The access level to require.
  • prefixSearchFields – To override the model’s prefixSearchFields attribute for this invocation, pass an alternate iterable.
Returns:

A pymongo cursor. It is left to the caller to build the results from the cursor.

requireAccess(doc, user=None, level=0)[source]

This wrapper just provides a standard way of throwing an access denied exception if the access check fails.

requireAccessFlags(doc, user=None, flags=None)[source]

Provides a standard way of throwing an access exception if a flag access check fails.

setAccessList(doc, access, save=False, user=None, force=False)[source]

Set the entire access control list to the given value. This also saves the resource in its new state to the database.

Parameters:
  • doc (dict) – The resource to update.
  • access (dict) – The new access control list to set on the object.
  • save (boolean) – Whether to save after updating.
  • user (dict) – The user performing the update. This is used to control updating of access flags that require admin permission to enable.
  • force (bool) – Set this to True to set the flags regardless of the passed in user’s permissions.
Returns:

The updated resource.

setGroupAccess(doc, group, level, save=False, flags=None, currentUser=None, force=False)[source]

Set group-level access on the resource.

Parameters:
  • doc (dict) – The resource document to set access on.
  • group (dict) – The group to grant or remove access to.
  • level (AccessType or None) – What level of access the group should have. Set to None to remove all access for this group.
  • save (bool) – Whether to save the object to the database afterward. Set this to False if you want to wait to save the document for performance reasons.
  • flags (specific flag identifier, or a list/tuple/set of them) – List of access flags to grant to the group.
  • currentUser (dict or None) – The user performing this action. Only required if attempting to set admin-only flags on the resource.
  • force (bool) – Set this to True to set the flags regardless of the passed in currentUser’s permissions (only matters if flags are passed).
Returns:

The updated resource document.

setPublic(doc, public, save=False)[source]

Set the flag for public read access on the object.

Parameters:
  • doc (dict) – The document to update permissions on.
  • public (bool) – Flag for public read access.
  • save (bool) – Whether to save the object to the database afterward. Set this to False if you want to wait to save the document for performance reasons.
Returns:

The updated resource document.

setPublicFlags(doc, flags, user=None, append=False, save=False, force=False)[source]

Set access flags that are granted on this resource to anonymous users. This means any user, whether anonymous or logged in, will receive all of the specified permissions. This also validates that the user attempting to set the flags has permission to do so. Any flags that are invalid or that the user is not authorized to enable will be discarded from the list.

Parameters:
  • doc (dict) – The document to update access flags on.
  • flags (flag identifier, or a list/set/tuple of them) – Flags or set of flags to add.
  • user (dict) – The user performing this action.
  • append (bool) – Whether to append to the list or replace it.
  • save (bool) – Whether to save the document to the database afterward.
  • force (bool) – Set this to True to set the flags regardless of the passed in user’s permissions.
setUserAccess(doc, user, level, save=False, flags=None, currentUser=None, force=False)[source]

Set user-level access on the resource.

Parameters:
  • doc (dict) – The resource document to set access on.
  • user (dict) – The user to grant or remove access to.
  • level (AccessType or None) – What level of access the user should have. Set to None to remove all access for this user.
  • save (bool) – Whether to save the object to the database afterward. Set this to False if you want to wait to save the document for performance reasons.
  • flags (specific flag identifier, or a list/tuple/set of them) – List of access flags to grant to the group.
  • currentUser – The user performing this action. Only required if attempting to set admin-only flags on the resource.
  • force (bool) – Set this to True to set the flags regardless of the passed in currentUser’s permissions (only matters if flags are passed).
Returns:

The modified resource document.

textSearch(query, user=None, filters=None, limit=0, offset=0, sort=None, fields=None, level=0)[source]

Custom override of Model.textSearch to also force permission-based filtering. The parameters are the same as Model.textSearch.

Parameters:
  • query (str) – The text query. Will be stemmed internally.
  • user (dict or None) – The user to apply permission filtering for.
  • filters (dict) – Any additional query operators to apply.
  • limit (int) – Maximum number of documents to return
  • offset (int) – The offset into the results
  • sort (List of (key, order) tuples) – The sort order
  • fields (str, list, set, or tuple) – A mask for filtering result documents by key, or None to return the full document, passed to MongoDB find() as the projection param. This is a string or iterable of strings to be included from the document, or dict for an inclusion or exclusion projection`.
  • level (girder.constants.AccessType) – The access level to require.
class girder.models.model_base.Model[source]

Model base class. Models are responsible for abstracting away the persistence layer. Each collection in the database should have its own model. Methods that deal with database interaction belong in the model layer.

ensureIndex(index)[source]

Like ensureIndices, but declares just a single index rather than a list of them.

ensureIndices(indices)[source]

Subclasses should call this with a list of strings representing fields that should be indexed in the database if there are any. Otherwise, it is not necessary to call this method. Elements of the list may also be a list or tuple, where the second element is a dictionary that will be passed as kwargs to the pymongo create_index call.

ensureTextIndex(index, language='english')[source]

Call this during initialize() of the subclass if you want your model to have a full-text searchable index. Each collection may have zero or one full-text index.

Parameters:language (str) – The default_language value for the text index, which is used for stemming and stop words. If the text index should not use stemming and stop words, set this param to ‘none’.
exposeFields(level, fields)[source]

Expose model fields to users with the given access level. Subclasses should call this in their initialize method to declare what fields should be exposed to what access levels if they are using the default filter implementation in this class. Since filtered fields are sets, this method is idempotent.

Parameters:
  • level (AccessType) – The required access level for the field.
  • fields (str, list, set, or tuple) – A field or list of fields to expose for that level.
filter(doc, user=None, additionalKeys=None)[source]

Filter this model for the given user. This is a default implementation that assumes this model has no notion of access control, and simply allows all keys under READ access level, and conditionally allows any keys assigned to SITE_ADMIN level.

Parameters:
  • doc (dict or None) – The document of this model type to be filtered.
  • user (dict or None) – The current user for whom we are filtering.
  • additionalKeys (list, tuple, set, or None) – Any additional keys that should be included in the document for this call only.
Returns:

The filtered document (dict).

filterDocument(doc, allow=None)[source]

This method will filter the given document to make it suitable to output to the user.

Parameters:
  • doc (dict) – The document to filter.
  • allow (List of strings) – The whitelist of fields to allow in the output document.
find(query=None, offset=0, limit=0, timeout=None, fields=None, sort=None, **kwargs)[source]

Search the collection by a set of parameters. Passes any extra kwargs through to the underlying pymongo.collection.find function.

Parameters:
  • query (dict) – The search query (see general MongoDB docs for “find()”)
  • offset (int) – The offset into the results
  • limit (int) – Maximum number of documents to return
  • timeout (int) – Cursor timeout in ms. Default is no timeout.
  • fields (str, list, set, or tuple) – A mask for filtering result documents by key, or None to return the full document, passed to MongoDB find() as the projection param. This is a string or iterable of strings to be included from the document, or dict for an inclusion or exclusion projection`.
  • sort (List of (key, order) tuples.) – The sort order.
Returns:

A pymongo database cursor.

findOne(query=None, fields=None, **kwargs)[source]

Search the collection by a set of parameters. Passes any kwargs through to the underlying pymongo.collection.find_one function.

Parameters:
  • query (dict) – The search query (see general MongoDB docs for “find()”)
  • fields (str, list, set, or tuple) – A mask for filtering result documents by key, or None to return the full document, passed to MongoDB find() as the projection param. This is a string or iterable of strings to be included from the document, or dict for an inclusion or exclusion projection`.
  • sort (List of (key, order) tuples.) – The sort order.
Returns:

the first object that was found, or None if none found.

hideFields(level, fields)[source]

Hide a field, i.e. make sure it is not exposed via the default filtering method. Since the filter uses a white list, it is only ever necessary to call this for fields that were added previously with exposeFields().

Parameters:
  • level (AccessType) – The access level to remove the fields from.
  • fields (str, list, set, or tuple) – The field or fields to remove from the white list.
increment(query, field, amount, **kwargs)[source]

This is a specialization of the update method that atomically increments a field by a given amount. Additional kwargs are passed directly through to update.

Parameters:
  • query (dict) – The search query for documents to update, see general MongoDB docs for “find()”
  • field (str) – The name of the field in the document to increment.
  • amount (int or float) – The amount to increment the field by.
initialize()[source]

Subclasses should override this and set the name of the collection as self.name. Also, they should set any indexed fields that they require.

load(id, objectId=True, fields=None, exc=False)[source]

Fetch a single object from the database using its _id field.

Parameters:
  • id (string or ObjectId) – The value for searching the _id field.
  • objectId (bool) – Whether the id should be coerced to ObjectId type.
  • fields (str, list, set, or tuple) – A mask for filtering result documents by key, or None to return the full document, passed to MongoDB find() as the projection param. This is a string or iterable of strings to be included from the document, or dict for an inclusion or exclusion projection`.
  • exc (bool) – Whether to raise a ValidationException if there is no document with the given id.
Returns:

The matching document, or None.

prefixSearch(query, offset=0, limit=0, sort=None, fields=None, filters=None, prefixSearchFields=None, **kwargs)[source]

Search for documents in this model’s collection by a prefix string. The fields that will be searched based on this prefix must be set as the prefixSearchFields attribute of this model, which must be an iterable. Elements of this iterable must be either a string representing the field name, or a 2-tuple in which the first element is the field name, and the second element is a string representing the regex search options.

Parameters:
  • query (str) – The prefix string to look for
  • offset (int) – The offset into the results
  • limit (int) – Maximum number of documents to return
  • sort (List of (key, order) tuples.) – The sort order.
  • fields (str, list, set, or tuple) – A mask for filtering result documents by key, or None to return the full document, passed to MongoDB find() as the projection param. This is a string or iterable of strings to be included from the document, or dict for an inclusion or exclusion projection`.
  • filters (dict) – Any additional query operators to apply.
  • prefixSearchFields – To override the model’s prefixSearchFields attribute for this invocation, pass an alternate iterable.
Returns:

A pymongo cursor. It is left to the caller to build the results from the cursor.

reconnect()[source]

Reconnect to the database and rebuild indices if necessary. Users should typically not have to call this method.

remove(document, **kwargs)[source]

Delete an object from the collection; must have its _id set.

Parameters:document – the item to remove.
removeWithQuery(query)[source]

Remove all documents matching a given query from the collection. For safety reasons, you may not pass an empty query.

Parameters:query (dict) – The search query for documents to delete, see general MongoDB docs for “find()”
save(document, validate=True, triggerEvents=True)[source]

Create or update a document in the collection. This triggers two events; one prior to validation, and one prior to saving. Either of these events may have their default action prevented.

Parameters:
  • document (dict) – The document to save.
  • validate (bool) – Whether to call the model’s validate() before saving.
  • triggerEvents – Whether to trigger events for validate and pre- and post-save hooks.
subtreeCount(doc)[source]

Return the size of the subtree rooted at the given document. In general, if this contains items or folders, it will be the count of the items and folders in all containers. If it does not, it will be 1. This returns the absolute size of the subtree, it does not filter by permissions.

Parameters:doc (dict) – The root of the subtree.
textSearch(query, offset=0, limit=0, sort=None, fields=None, filters=None, **kwargs)[source]

Perform a full-text search against the text index for this collection.

Parameters:
  • query (str) – The text query. Will be stemmed internally.
  • offset (int) – The offset into the results
  • limit (int) – Maximum number of documents to return
  • sort (List of (key, order) tuples.) – The sort order.
  • fields (str, list, set, or tuple) – A mask for filtering result documents by key, or None to return the full document, passed to MongoDB find() as the projection param. This is a string or iterable of strings to be included from the document, or dict for an inclusion or exclusion projection`.
  • filters (dict) – Any additional query operators to apply.
Returns:

A pymongo cursor. It is left to the caller to build the results from the cursor.

update(query, update, multi=True)[source]

This method should be used for updating multiple documents in the collection. This is useful for things like removing all references in this collection to a document that is being deleted from another collection.

For updating a single document, use the save() model method instead.

Parameters:
  • query (dict) – The search query for documents to update, see general MongoDB docs for “find()”
  • update (dict) – The update specifier.
  • multi (bool) – Whether to update a single document, or all matching documents.
Returns:

A pymongo UpdateResult object.

validate(doc)[source]

Models should implement this to validate the document before it enters the database. It must return the document with any necessary filters applied, or throw a ValidationException if validation of the document fails.

Parameters:doc (dict) – The document to validate before saving to the collection.
validateKeys(keys)[source]

Validate a set of keys to make sure they are able to be used in the database. This enforces MongoDB rules about key names. @TODO Add recurse=True argument if keys is a dict.

Parameters:keys (iterable) – An iterable of keys to validate.
Raises:ValidationException

API Key

class girder.models.api_key.ApiKey[source]

This model represents API keys corresponding to users.

createApiKey(user, name, scope=None, days=None, active=True)[source]

Create a new API key for a user.

Parameters:
  • user (dict) – The user who owns the API key.
  • name – A human readable name for the API key
  • days (float or int) – The lifespan of the session in days. If not passed, uses the database setting for cookie lifetime. Note that this is a maximum duration; clients may request tokens with a shorter lifetime than this value.
  • scope (str, list of str, or set of str) – Scope or list of scopes this API key grants. By default, will grant tokens provided full access on behalf of the user.
  • active – Whether this key is active.
Returns:

The API key document that was created.

createToken(key, days=None)[source]

Create a token using an API key.

Parameters:
  • key (str) – The API key (the key itself, not the full document).
  • days (float or None) – You may request a token duration up to the token duration of the API key itself, or pass None to use the API key duration.
initialize()[source]

Subclasses should override this and set the name of the collection as self.name. Also, they should set any indexed fields that they require.

list(user, limit=0, offset=0, sort=None)[source]

List API keys for a given user.

Parameters:
  • user (dict) – The user whose keys to list.
  • limit – Result limit.
  • offset – Result offset.
  • sort – The sort structure to pass to pymongo.
Return type:

iterable of API keys for the user.

remove(doc)[source]

Delete an object from the collection; must have its _id set.

Parameters:document – the item to remove.
validate(doc)[source]

Models should implement this to validate the document before it enters the database. It must return the document with any necessary filters applied, or throw a ValidationException if validation of the document fails.

Parameters:doc (dict) – The document to validate before saving to the collection.

User

class girder.models.user.User[source]

This model represents the users of the system.

adminApprovalRequired(user)[source]

Returns True if the registration policy requires admin approval and this user is pending approval.

authenticate(login, password, otpToken=None)[source]

Validate a user login via username and password. If authentication fails, a AccessException is raised.

Parameters:
  • login (str) – The user’s login or email.
  • password (str) – The user’s password.
  • otpToken (str or bool or None) – A one-time password for the user. If “True”, then the one-time password (if required) is assumed to be concatenated to the password.
Returns:

The corresponding user if the login was successful.

Return type:

dict

canLogin(user)[source]

Returns True if the user is allowed to login, e.g. email verification is not needed and admin approval is not needed.

countFolders(user, filterUser=None, level=None)[source]

Returns the number of top level folders under this user. Access checking is optional; to circumvent access checks, pass level=None.

Parameters:
  • user – The user whose top level folders to count.
  • filterUser (dict or None) – If performing access checks, the user to check against.
  • level – The required access level, or None to return the raw top-level folder count.
createUser(login, password, firstName, lastName, email, admin=False, public=True)[source]

Create a new user with the given information. The user will be created with the default “Public” and “Private” folders.

Parameters:
  • admin (bool) – Whether user is global administrator.
  • public (bool) – Whether user is publicly visible.
Returns:

The user document that was created.

emailVerificationRequired(user)[source]

Returns True if email verification is required and this user has not yet verified their email address.

fileList(doc, user=None, path='', includeMetadata=False, subpath=True, data=True)[source]

This function generates a list of 2-tuples whose first element is the relative path to the file from the user’s folders root and whose second element depends on the value of the data flag. If data=True, the second element will be a generator that will generate the bytes of the file data as stored in the assetstore. If data=False, the second element is the file document itself.

Parameters:
  • doc – the user to list.
  • user – a user used to validate data that is returned.
  • path – a path prefix to add to the results.
  • includeMetadata – if True and there is any metadata, include a result which is the JSON string of the metadata. This is given a name of metadata[-(number).json that is distinct from any file within the item.
  • subpath – if True, add the user’s name to the path.
  • data (bool) – If True return raw content of each file as stored in the assetstore, otherwise return file document.
filter(doc, user, additionalKeys=None)[source]

Filter this model for the given user according to the user’s access level. Also adds the special _accessLevel field to the document to indicate the user’s highest access level. This filters a single document that the user has at least read access to. For filtering a set of documents, see filterResultsByPermission().

Parameters:
  • doc (dict or None) – The document of this model type to be filtered.
  • user (dict or None) – The current user for whom we are filtering.
  • additionalKeys (list, tuple, or None) – Any additional keys that should be included in the document for this call only.
Returns:

The filtered document (dict).

getAdmins()[source]

Helper to return a cursor of all site-admin users. The number of site admins is assumed to be small enough that we will not need to page the results for now.

hasPassword(user)[source]

Returns whether or not the given user has a password stored in the database. If not, it is expected that the user will be authenticated by an external service.

Parameters:user (dict) – The user to test.
Returns:bool
initialize()[source]

Subclasses should override this and set the name of the collection as self.name. Also, they should set any indexed fields that they require.

initializeOtp(user)[source]

Initialize the use of one-time passwords with this user.

This does not save the modified user model.

Parameters:user – The user to modify.
Returns:The new OTP keys, each in KeyUriFormat.
Return type:dict
remove(user, progress=None, **kwargs)[source]

Delete a user, and all references to it in the database.

Parameters:
search(text=None, user=None, limit=0, offset=0, sort=None)[source]

List all users. Since users are access-controlled, this will filter them by access policy.

Parameters:
  • text – Pass this to perform a full-text search for users.
  • user – The user running the query. Only returns users that this user can see.
  • limit – Result limit.
  • offset – Result offset.
  • sort – The sort structure to pass to pymongo.
Returns:

Iterable of users.

setPassword(user, password, save=True)[source]

Change a user’s password.

Parameters:
  • user – The user whose password to change.
  • password – The new password. If set to None, no password will be stored for this user. This should be done in cases where an external system is responsible for authenticating the user.
subtreeCount(doc, includeItems=True, user=None, level=None)[source]

Return the size of the user’s folders. The user is counted as well.

Parameters:
  • doc – The user.
  • includeItems (bool) – Whether to include items in the subtree count, or just folders.
  • user – If filtering by permission, the user to filter against.
  • level (AccessLevel) – If filtering by permission, the required permission level.
updateSize(doc)[source]

Recursively recomputes the size of this user and its underlying folders and fixes the sizes as needed.

Parameters:doc (dict) – The user.
validate(doc)[source]

Validate the user every time it is stored in the database.

Token

class girder.models.token.Token[source]

This model stores session tokens for user authentication.

addScope(token, scope)[source]

Add a scope to this token. If the token already has the scope, this is a no-op.

clearForApiKey(apiKey)[source]

Delete all tokens corresponding to an API key.

createToken(user=None, days=None, scope=None, apiKey=None)[source]

Creates a new token. You can create an anonymous token (such as for CSRF mitigation) by passing “None” for the user argument.

Parameters:
  • user (dict) – The user to create the session for.
  • days (float or int) – The lifespan of the session in days. If not passed, uses the database setting for cookie lifetime.
  • scope (str or list of str) – Scope or list of scopes this token applies to. By default, will create a user authentication token.
  • apiKey (dict) – If this token is being created via an API key, pass it so that we can record the provenance for cleanup and auditing.
Returns:

The token document that was created.

getAllowedScopes(token)[source]

Return the list of allowed scopes for a given token.

hasScope(token, scope)[source]

Test whether the given token has the given set of scopes. Use this rather than comparing manually, since this method is backward compatible with tokens that do not contain a scope field.

Parameters:
  • token (dict) – The token object.
  • scope (str or list of str) – A scope or set of scopes that will be tested as a subset of the given token’s allowed scopes.
initialize()[source]

Subclasses should override this and set the name of the collection as self.name. Also, they should set any indexed fields that they require.

requireScope(token, scope)[source]

Raise an error if given set of scopes are not included.

Parameters:
  • token (dict) – The token object.
  • scope (str or list of str) – A scope or set of scopes that will be tested as a subset of the given token’s allowed scopes.
validate(doc)[source]

Models should implement this to validate the document before it enters the database. It must return the document with any necessary filters applied, or throw a ValidationException if validation of the document fails.

Parameters:doc (dict) – The document to validate before saving to the collection.

Group

class girder.models.group.Group[source]

Groups are simply groups of users. The primary use of grouping users is to simplify access control for resources in the system, but they can be used for other purposes that require groupings of users as well.

Group membership is stored in the database on the user document only; there is no “users” field in this model. This is to optimize for the most common use case for querying membership, which involves checking access control policies, which is always done relative to a specific user. The task of querying all members within a group is much less common and typically only performed on a single group at a time, so doing a find on the indexed group list in the user collection is sufficiently fast.

Users with READ access on the group can see the group and its members. Users with WRITE access on the group can add and remove members and change the name or description. Users with ADMIN access can promote group members to grant them WRITE or ADMIN access, and can also delete the entire group.

This model uses a custom implementation of the access control methods, because it uses only a subset of its capabilities and provides a more optimized implementation for that subset. Specifically: read access is implied by membership in the group or having an invitation to join the group, so we don’t store read access in the access document as normal. Another constraint is that write and admin access on the group can only be granted to members of the group. Also, group permissions are not allowed on groups for the sake of simplicity.

addUser(group, user, level=0)[source]

Add the user to the group. Records membership in the group in the user document, and also grants the specified access level on the group itself to the user. Any group member has at least read access on the group. If the user already belongs to the group, this method can be used to change their access level within it.

createGroup(name, creator, description='', public=True)[source]

Create a new group. The creator will be given admin access to it.

Parameters:
  • name (str) – The name of the folder.
  • description (str) – Description for the folder.
  • public (bool) – Whether the group is publicly visible.
  • creator (dict) – User document representing the creator of the group.
Returns:

The group document that was created.

getAccessLevel(doc, user)[source]

Return the maximum access level for a given user on the group.

Parameters:
  • doc – The group to check access on.
  • user – The user to get the access level for.
Returns:

The max AccessType available for the user on the object.

getFullRequestList(group)[source]

Return the set of all outstanding requests, filled in with the login and full names of the corresponding users.

Parameters:group (dict) – The group to get requests for.
getInvites(group, limit=0, offset=0, sort=None)[source]

Return a page of outstanding invitations to a group. This is simply a list of users invited to the group currently.

Parameters:
  • group – The group to find invitations for.
  • limit – Result set size limit.
  • offset – Offset into the results.
  • sort – The sort field.
getMembers(group, offset=0, limit=0, sort=None)[source]

Return the list of all users who belong to this group.

Parameters:
  • group – The group to list members on.
  • offset – Offset into the result set of users.
  • limit – Result set size limit.
  • sort – Sort parameter for the find query.
Returns:

List of user documents.

hasAccess(doc, user=None, level=0)[source]

This overrides the default AccessControlledModel behavior for checking access to perform an optimized subset of the access control behavior.

Parameters:
  • doc (dict) – The group to check permission on.
  • user (dict) – The user to check against.
  • level (AccessType) – The access level.
Returns:

Whether the access is granted.

initialize()[source]

Subclasses should override this and set the name of the collection as self.name. Also, they should set any indexed fields that they require.

inviteUser(group, user, level=0)[source]

Invite a user to join the group. Inviting them automatically grants the user read access to the group so that they can see it. Once they accept the invitation, they will be given the specified level of access.

If the user has requested an invitation to this group, calling this will accept their request and add them to the group at the access level specified.

joinGroup(group, user)[source]

This method either accepts an invitation to join a group, or if the given user has not been invited to the group, this will create an invitation request that moderators and admins may grant or deny later.

listMembers(group, offset=0, limit=0, sort=None)[source]

List members of the group.

remove(group, **kwargs)[source]

Delete a group, and all references to it in the database.

Parameters:group (dict) – The group document to delete.
removeUser(group, user)[source]

Remove the user from the group. If the user is not in the group but has an outstanding invitation to the group, the invitation will be revoked. If the user has requested an invitation, calling this will deny that request, thereby deleting it.

setGroupAccess(doc, group, level, save=False)[source]

Set group-level access on the resource.

Parameters:
  • doc (dict) – The resource document to set access on.
  • group (dict) – The group to grant or remove access to.
  • level (AccessType or None) – What level of access the group should have. Set to None to remove all access for this group.
  • save (bool) – Whether to save the object to the database afterward. Set this to False if you want to wait to save the document for performance reasons.
  • flags (specific flag identifier, or a list/tuple/set of them) – List of access flags to grant to the group.
  • currentUser (dict or None) – The user performing this action. Only required if attempting to set admin-only flags on the resource.
  • force (bool) – Set this to True to set the flags regardless of the passed in currentUser’s permissions (only matters if flags are passed).
Returns:

The updated resource document.

setUserAccess(doc, user, level, save=False)[source]

This override is used because we only need to augment the access field in the case of WRITE access and above since READ access is implied by membership or invitation.

updateGroup(group)[source]

Updates a group.

Parameters:group (dict) – The group document to update
Returns:The group document that was edited.
validate(doc)[source]

Models should implement this to validate the document before it enters the database. It must return the document with any necessary filters applied, or throw a ValidationException if validation of the document fails.

Parameters:doc (dict) – The document to validate before saving to the collection.

Collection

class girder.models.collection.Collection[source]

Collections are the top level roots of the data hierarchy. They are used to group and organize data that is meant to be shared amongst users.

countFolders(collection, user=None, level=None)[source]

Returns the number of top level folders under this collection. Access checking is optional; to circumvent access checks, pass level=None.

Parameters:
  • collection (dict) – The collection.
  • user (dict or None) – If performing access checks, the user to check against.
  • level – The required access level, or None to return the raw top-level folder count.
createCollection(name, creator=None, description='', public=True, reuseExisting=False)[source]

Create a new collection.

Parameters:
  • name (str) – The name of the collection. Must be unique.
  • description (str) – Description for the collection.
  • public (bool) – Public read access flag.
  • creator (dict) – The user who is creating this collection.
  • reuseExisting (bool) – If a collection with the given name already exists return that collection rather than creating a new one.
Returns:

The collection document that was created.

deleteMetadata(collection, fields)[source]

Delete metadata on an collection. A ValidationException is thrown if the metadata field names contain a period (‘.’) or begin with a dollar sign (‘$’).

Parameters:
  • collection (dict) – The collection to delete metadata from.
  • fields – An array containing the field names to delete from the collection’s meta field
Returns:

the collection document

fileList(doc, user=None, path='', includeMetadata=False, subpath=True, mimeFilter=None, data=True)[source]

This function generates a list of 2-tuples whose first element is the relative path to the file from the collection’s root and whose second element depends on the value of the data flag. If data=True, the second element will be a generator that will generate the bytes of the file data as stored in the assetstore. If data=False, the second element is the file document itself.

Parameters:
  • doc – the collection to list.
  • user – a user used to validate data that is returned.
  • path – a path prefix to add to the results.
  • includeMetadata – if True and there is any metadata, include a result which is the JSON string of the metadata. This is given a name of metadata[-(number).json that is distinct from any file within the item.
  • subpath – if True, add the collection’s name to the path.
  • mimeFilter (list or tuple) – Optional list of MIME types to filter by. Set to None to include all files.
  • data (bool) – If True return raw content of each file as stored in the assetstore, otherwise return file document.
filter(doc, user=None, additionalKeys=None)[source]

Overrides the parent filter method to add an empty meta field (if it doesn’t exist) to the returned collection.

hasCreatePrivilege(user)[source]

Tests whether a given user has the authority to create collections on this instance. This is based on the collection creation policy settings. By default, only admins are allowed to create collections.

Parameters:user – The user to test.
Returns:bool
initialize()[source]

Subclasses should override this and set the name of the collection as self.name. Also, they should set any indexed fields that they require.

load(id, level=2, user=None, objectId=True, force=False, fields=None, exc=False)[source]

Calls AccessControlMixin.load, and if no meta field is present, adds an empty meta field and saves.

Takes the same parameters as girder.models.model_base.AccessControlMixin.load().

remove(collection, progress=None, **kwargs)[source]

Delete a collection recursively.

Parameters:
setAccessList(doc, access, save=False, recurse=False, user=None, progress=<girder.utility.progress.ProgressContext object>, setPublic=None, publicFlags=None, force=False)[source]

Overrides AccessControlledModel.setAccessList to add a recursive option. When recurse=True, this will set the access list on all subfolders to which the given user has ADMIN access level. Any subfolders that the given user does not have ADMIN access on will be skipped.

Parameters:
  • doc (collection) – The collection to set access settings on.
  • access (dict) – The access control list.
  • save (bool) – Whether the changes should be saved to the database.
  • recurse (bool) – Whether this access list should be propagated to all folders underneath this collection.
  • user – The current user (for recursive mode filtering).
  • progress (girder.utility.progress.ProgressContext) – Progress context to update.
  • setPublic (bool or None) – Pass this if you wish to set the public flag on the resources being updated.
  • publicFlags (flag identifier str, or list/set/tuple of them, or None) – Pass this if you wish to set the public flag list on resources being updated.
  • force (bool) – Set this to True to set the flags regardless of the passed in user’s permissions.
setMetadata(collection, metadata, allowNull=False)[source]

Set metadata on an collection. A ValidationException is thrown in the cases where the metadata JSON object is badly formed, or if any of the metadata keys contains a period (‘.’).

Parameters:
  • collection (dict) – The collection to set the metadata on.
  • metadata (dict) – A dictionary containing key-value pairs to add to the collection’s meta field
  • allowNull – Whether to allow null values to be set in the collection’s metadata. If set to False or omitted, a null value will cause that metadata field to be deleted.
Returns:

the collection document

subtreeCount(doc, includeItems=True, user=None, level=None)[source]

Return the size of the folders within the collection. The collection is counted as well.

Parameters:
  • doc – The collection.
  • includeItems (bool) – Whether items should be included in the count.
  • user – If filtering by permission, the user to filter against.
  • level (AccessLevel) – If filtering by permission, the required permission level.
updateCollection(collection)[source]

Updates a collection.

Parameters:collection (dict) – The collection document to update
Returns:The collection document that was edited.
updateSize(doc)[source]

Recursively recomputes the size of this collection and its underlying folders and fixes the sizes as needed.

Parameters:doc (dict) – The collection.
validate(doc)[source]

Models should implement this to validate the document before it enters the database. It must return the document with any necessary filters applied, or throw a ValidationException if validation of the document fails.

Parameters:doc (dict) – The document to validate before saving to the collection.

Folder

class girder.models.folder.Folder[source]

Folders are used to store items and can also store other folders in a hierarchical way, like a directory on a filesystem. Every folder has its own set of access control policies, but by default the access control list is inherited from the folder’s parent folder, if it has one. Top-level folders are ones whose parent is a user or a collection.

childFolders(parent, parentType, user=None, limit=0, offset=0, sort=None, filters=None, **kwargs)[source]

This generator will yield child folders of a user, collection, or folder, with access policy filtering. Passes any kwargs to the find function.

Parameters:
  • parent – The parent object.
  • parentType ('user', 'folder', or 'collection') – The parent type.
  • user – The user running the query. Only returns folders that this user can see.
  • limit – Result limit.
  • offset – Result offset.
  • sort – The sort structure to pass to pymongo.
  • filters – Additional query operators.
childItems(folder, limit=0, offset=0, sort=None, filters=None, **kwargs)[source]

Generator function that yields child items in a folder. Passes any kwargs to the find function.

Parameters:
  • folder – The parent folder.
  • limit – Result limit.
  • offset – Result offset.
  • sort – The sort structure to pass to pymongo.
  • filters – Additional query operators.
clean(folder, progress=None, **kwargs)[source]

Delete all contents underneath a folder recursively, but leave the folder itself.

Parameters:
copyFolder(srcFolder, parent=None, name=None, description=None, parentType=None, public=None, creator=None, progress=None, firstFolder=None)[source]

Copy a folder, including all child items and child folders.

Parameters:
  • srcFolder (dict) – the folder to copy.
  • parent (dict) – The parent document. Must be a folder, user, or collection.
  • name (str) – The name of the new folder. None to copy the original name.
  • description (str) – Description for the new folder. None to copy the original description.
  • parentType (str) – What type the parent is: (‘folder’ | ‘user’ | ‘collection’)
  • public (bool, None, or 'original'.) – Public read access flag. None to inherit from parent, ‘original’ to inherit from original folder.
  • creator (dict) – user representing the creator of the new folder.
  • progress (girder.utility.progress.ProgressContext or None.) – a progress context to record process on.
  • firstFolder – if not None, the first folder copied in a tree of folders.
Returns:

the new folder document.

copyFolderComponents(srcFolder, newFolder, creator, progress, firstFolder=None)[source]

Copy the items, subfolders, and extended data of a folder that was just copied.

Parameters:
  • srcFolder (dict) – the original folder.
  • newFolder (dict) – the new folder.
  • creator (dict) – user representing the creator of the new folder.
  • progress (girder.utility.progress.ProgressContext or None.) – a progress context to record process on.
  • firstFolder – if not None, the first folder copied in a tree of folders.
Returns:

the new folder document.

countFolders(folder, user=None, level=None)[source]

Returns the number of subfolders within the given folder. Access checking is optional; to circumvent access checks, pass level=None.

Parameters:
  • folder (dict) – The parent folder.
  • user (dict or None) – If performing access checks, the user to check against.
  • level – The required access level, or None to return the raw subfolder count.
countItems(folder)[source]

Returns the number of items within the given folder.

createFolder(parent, name, description='', parentType='folder', public=None, creator=None, allowRename=False, reuseExisting=False)[source]

Create a new folder under the given parent.

Parameters:
  • parent (dict) – The parent document. Should be a folder, user, or collection.
  • name (str) – The name of the folder.
  • description (str) – Description for the folder.
  • parentType (str) – What type the parent is: (‘folder’ | ‘user’ | ‘collection’)
  • public (bool or None to inherit from parent) – Public read access flag.
  • creator (dict) – User document representing the creator of this folder.
  • allowRename (bool) – if True and a folder or item of this name exists, automatically rename the folder.
  • reuseExisting (bool) – If a folder with the given name already exists under the given parent, return that folder rather than creating a new one.
Returns:

The folder document that was created.

deleteMetadata(folder, fields)[source]

Delete metadata on a folder. A ValidationException is thrown if the metadata field names contain a period (‘.’) or begin with a dollar sign (‘$’).

Parameters:
  • folder (dict) – The folder to delete metadata from.
  • fields – An array containing the field names to delete from the folder’s meta field
Returns:

the folder document

fileList(doc, user=None, path='', includeMetadata=False, subpath=True, mimeFilter=None, data=True)[source]

This function generates a list of 2-tuples whose first element is the relative path to the file from the folder’s root and whose second element depends on the value of the data flag. If data=True, the second element will be a generator that will generate the bytes of the file data as stored in the assetstore. If data=False, the second element is the file document itself.

Parameters:
  • doc – The folder to list.
  • user – The user used for access.
  • path (str) – A path prefix to add to the results.
  • includeMetadata (bool) – if True and there is any metadata, include a result which is the JSON string of the metadata. This is given a name of metadata[-(number).json that is distinct from any file within the folder.
  • subpath (bool) – if True, add the folder’s name to the path.
  • mimeFilter (list or tuple) – Optional list of MIME types to filter by. Set to None to include all files.
  • data (bool) – If True return raw content of each file as stored in the assetstore, otherwise return file document.
Returns:

Iterable over files in this folder, where each element is a tuple of (path name of the file, stream function with file data or file object).

Return type:

generator(str, func)

filter(doc, user=None, additionalKeys=None)[source]

Overrides the parent filter method to add an empty meta field (if it doesn’t exist) to the returned folder.

getSizeRecursive(folder)[source]

Calculate the total size of the folder by recursing into all of its descendant folders.

initialize()[source]

Subclasses should override this and set the name of the collection as self.name. Also, they should set any indexed fields that they require.

isOrphan(folder)[source]

Returns True if this folder is orphaned (its parent is missing).

Parameters:folder (dict) – The folder to check.
load(id, level=2, user=None, objectId=True, force=False, fields=None, exc=False)[source]

We override load in order to ensure the folder has certain fields within it, and if not, we add them lazily at read time.

Parameters:
  • id (string or ObjectId) – The id of the resource.
  • user (dict or None) – The user to check access against.
  • level (AccessType) – The required access type for the object.
  • force (bool) – If you explicitly want to circumvent access checking on this resource, set this to True.
move(folder, parent, parentType)[source]

Move the given folder from its current parent to another parent object. Raises an exception if folder is an ancestor of parent.

Parameters:
  • folder (dict) – The folder to move.
  • parent – The new parent object.
  • parentType (str) – The type of the new parent object (user, collection, or folder).
parentsToRoot(folder, curPath=None, user=None, force=False, level=0)[source]

Get the path to traverse to a root of the hierarchy.

Parameters:folder (dict) – The folder whose root to find
Returns:an ordered list of dictionaries from root to the current folder
remove(folder, progress=None, **kwargs)[source]

Delete a folder recursively.

Parameters:
setAccessList(doc, access, save=False, recurse=False, user=None, progress=<girder.utility.progress.ProgressContext object>, setPublic=None, publicFlags=None, force=False)[source]

Overrides AccessControlledModel.setAccessList to add a recursive option. When recurse=True, this will set the access list on all subfolders to which the given user has ADMIN access level. Any subfolders that the given user does not have ADMIN access on will be skipped.

Parameters:
  • doc (girder.models.folder) – The folder to set access settings on.
  • access (dict) – The access control list.
  • save (bool) – Whether the changes should be saved to the database.
  • recurse (bool) – Whether this access list should be propagated to all subfolders underneath this folder.
  • user – The current user (for recursive mode filtering).
  • progress (girder.utility.progress.ProgressContext) – Progress context to update.
  • setPublic (bool or None) – Pass this if you wish to set the public flag on the resources being updated.
  • publicFlags (flag identifier str, or list/set/tuple of them, or None) – Pass this if you wish to set the public flag list on resources being updated.
  • force (bool) – Set this to True to set the flags regardless of the passed in user’s permissions.
setMetadata(folder, metadata, allowNull=False)[source]

Set metadata on a folder. A ValidationException is thrown in the cases where the metadata JSON object is badly formed, or if any of the metadata keys contains a period (‘.’).

Parameters:
  • folder (dict) – The folder to set the metadata on.
  • metadata (dict) – A dictionary containing key-value pairs to add to the folder’s meta field
  • allowNull – Whether to allow null values to be set in the item’s metadata. If set to False or omitted, a null value will cause that metadata field to be deleted.
Returns:

the folder document

subtreeCount(folder, includeItems=True, user=None, level=None)[source]

Return the size of the subtree rooted at the given folder. Includes the root folder in the count.

Parameters:
  • folder (dict) – The root of the subtree.
  • includeItems (bool) – Whether to include items in the subtree count, or just folders.
  • user – If filtering by permission, the user to filter against.
  • level (AccessLevel) – If filtering by permission, the required permission level.
updateFolder(folder)[source]

Updates a folder.

Parameters:folder (dict) – The folder document to update
Returns:The folder document that was edited.
updateSize(doc)[source]

Recursively recomputes the size of this folder and its underlying folders and fixes the sizes as needed.

Parameters:doc (dict) – The folder.
validate(doc, allowRename=False)[source]

Validate the name and description of the folder, ensure that it is associated with a valid parent and that it has a unique name.

Parameters:
  • doc – the folder document to validate.
  • allowRename – if True and a folder or item exists with the same name, rename the folder so that it is unique.
Returns:

the validated folder document

Item

class girder.models.item.Item[source]

Items are leaves in the data hierarchy. They can contain 0 or more files within them, and can also contain arbitrary metadata.

childFiles(item, limit=0, offset=0, sort=None, **kwargs)[source]

Returns child files of the item. Passes any kwargs to the find function.

Parameters:
  • item – The parent item.
  • limit – Result limit.
  • offset – Result offset.
  • sort – The sort structure to pass to pymongo.
copyItem(srcItem, creator, name=None, folder=None, description=None)[source]

Copy an item, including duplicating files and metadata.

Parameters:
  • srcItem (dict) – the item to copy.
  • creator – the user who will own the copied item.
  • name (str) – The name of the new item. None to copy the original name.
  • folder – The parent folder of the new item. None to store in the same folder as the original item.
  • description (str) – Description for the new item. None to copy the original description.
Returns:

the new item.

createItem(name, creator, folder, description='', reuseExisting=False)[source]

Create a new item. The creator will be given admin access to it.

Parameters:
  • name (str) – The name of the item.
  • description (str) – Description for the item.
  • folder – The parent folder of the item.
  • creator (dict) – User document representing the creator of the item.
  • reuseExisting (bool) – If an item with the given name already exists under the given folder, return that item rather than creating a new one.
Returns:

The item document that was created.

deleteMetadata(item, fields)[source]

Delete metadata on an item. A ValidationException is thrown if the metadata field names contain a period (‘.’) or begin with a dollar sign (‘$’).

Parameters:
  • item (dict) – The item to delete metadata from.
  • fields – An array containing the field names to delete from the item’s meta field
Returns:

the item document

fileList(doc, user=None, path='', includeMetadata=False, subpath=True, mimeFilter=None, data=True)[source]

This function generates a list of 2-tuples whose first element is the relative path to the file from the item’s root and whose second element depends on the value of the data flag. If data=True, the second element will be a generator that will generate the bytes of the file data as stored in the assetstore. If data=False, the second element will be the file document itself.

Parameters:
  • doc – The item to list.
  • user – A user used to validate data that is returned. This isn’t used, but is present to be consistent across all model implementations of fileList.
  • path (str) – A path prefix to add to the results.
  • includeMetadata (bool) – If True and there is any metadata, include a result which is the JSON string of the metadata. This is given a name of metadata[-(number).json that is distinct from any file within the item.
  • subpath (bool) – If True and the item has more than one file, any metadata, or the sole file is not named the same as the item, then the returned paths include the item name.
  • mimeFilter (list or tuple) – Optional list of MIME types to filter by. Set to None to include all files.
  • data (bool) – If True return raw content of each file as stored in the assetstore, otherwise return file document.
Returns:

Iterable over files in this item, where each element is a tuple of (path name of the file, stream function with file data or file object).

Return type:

generator(str, func)

filter(doc, user=None, additionalKeys=None)[source]

Overrides the parent filter method to add an empty meta field (if it doesn’t exist) to the returned folder.

initialize()[source]

Subclasses should override this and set the name of the collection as self.name. Also, they should set any indexed fields that they require.

isOrphan(item)[source]

Returns True if this item is orphaned (its folder is missing).

Parameters:item (dict) – The item to check.
load(id, level=2, user=None, objectId=True, force=False, fields=None, exc=False)[source]

Calls AccessControlMixin.load while doing some auto-correction.

Takes the same parameters as girder.models.model_base.AccessControlMixin.load().

move(item, folder)[source]

Move the given item from its current folder into another folder.

Parameters:
  • item (dict) – The item to move.
  • folder (dict.) – The folder to move the item into.
parentsToRoot(item, user=None, force=False)[source]

Get the path to traverse to a root of the hierarchy.

Parameters:
  • item (dict) – The item whose root to find
  • user (dict or None) – The user making the request (not required if force=True).
  • force (bool) – Set to True to skip permission checking. If False, the returned models will be filtered.
Returns:

an ordered list of dictionaries from root to the current item

recalculateSize(item)[source]

Recalculate the item size based on the files that are in it. If this is different than the recorded size, propagate the changes. :param item: The item to recalculate the size of. :returns: the recalculated size in bytes

remove(item, **kwargs)[source]

Delete an item, and all references to it in the database.

Parameters:item (dict) – The item document to delete.
setMetadata(item, metadata, allowNull=False)[source]

Set metadata on an item. A ValidationException is thrown in the cases where the metadata JSON object is badly formed, or if any of the metadata keys contains a period (‘.’).

Parameters:
  • item (dict) – The item to set the metadata on.
  • metadata (dict) – A dictionary containing key-value pairs to add to the items meta field
  • allowNull – Whether to allow null values to be set in the item’s metadata. If set to False or omitted, a null value will cause that metadata field to be deleted.
Returns:

the item document

updateItem(item)[source]

Updates an item.

Parameters:item (dict) – The item document to update
Returns:The item document that was edited.
updateSize(doc)[source]

Recomputes the size of this item and its underlying files and fixes the sizes as needed.

Parameters:doc (dict) – The item.
validate(doc)[source]

Models should implement this to validate the document before it enters the database. It must return the document with any necessary filters applied, or throw a ValidationException if validation of the document fails.

Parameters:doc (dict) – The document to validate before saving to the collection.

Setting

class girder.models.setting.Setting[source]

This model represents server-wide configuration settings as key/value pairs.

get(key)[source]

Retrieve a setting by its key.

Parameters:key (str) – The key identifying the setting.
getDefault(key)[source]

Retrieve the system default for a value.

Parameters:key (str) – The key identifying the setting.
Returns:The default value if the key is present in both SettingKey and referenced in SettingDefault; otherwise None.
initialize()[source]

Subclasses should override this and set the name of the collection as self.name. Also, they should set any indexed fields that they require.

reconnect()[source]

Reconnect to the database and rebuild indices if necessary. If a unique index on key does not exist, make one, first discarding any extant index on key and removing duplicate keys if necessary.

set(key, value)[source]

Save a setting. If a setting for this key already exists, this will replace the existing value.

Parameters:
  • key (str) – The key identifying the setting.
  • value – The object to store for this setting.
Returns:

The document representing the saved Setting.

unset(key)[source]

Remove the setting for this key. If no such setting exists, this is a no-op.

Parameters:key (str) – The key identifying the setting to be removed.
validate(doc)[source]

This method is in charge of validating that the setting key is a valid key, and that for that key, the provided value is valid. It first allows plugins to validate the setting, but if none of them can, it assumes it is a core setting and does the validation here.

Assetstore

class girder.models.assetstore.Assetstore[source]

This model represents an assetstore, an abstract repository of Files.

addComputedInfo(assetstore)[source]

Add all runtime-computed properties about an assetstore to its document.

Parameters:assetstore (dict) – The assetstore object.
getCurrent()[source]

Returns the current assetstore. If none exists, this will raise a 500 exception.

importData(assetstore, parent, parentType, params, progress, user, **kwargs)[source]

Calls the importData method of the underlying assetstore adapter.

initialize()[source]

Subclasses should override this and set the name of the collection as self.name. Also, they should set any indexed fields that they require.

list(limit=0, offset=0, sort=None)[source]

List all assetstores.

Parameters:
  • limit – Result limit.
  • offset – Result offset.
  • sort – The sort structure to pass to pymongo.
Returns:

List of users.

remove(assetstore, **kwargs)[source]

Delete an assetstore. If there are any files within this assetstore, a validation exception is raised.

Parameters:assetstore (dict) – The assetstore document to delete.
validate(doc)[source]

Models should implement this to validate the document before it enters the database. It must return the document with any necessary filters applied, or throw a ValidationException if validation of the document fails.

Parameters:doc (dict) – The document to validate before saving to the collection.

File

class girder.models.file.File[source]

This model represents a File, which is stored in an assetstore.

copyFile(srcFile, creator, item=None)[source]

Copy a file so that we don’t need to duplicate stored data.

Parameters:
  • srcFile (dict) – The file to copy.
  • creator – The user copying the file.
  • item – a new item to assign this file to (optional)
Returns:

a dict with the new file.

createFile(creator, item, name, size, assetstore, mimeType=None, saveFile=True, reuseExisting=False, assetstoreType=None)[source]

Create a new file record in the database.

Parameters:
  • item – The parent item.
  • creator – The user creating the file.
  • assetstore – The assetstore this file is stored in.
  • name (str) – The filename.
  • size (int) – The size of the file in bytes.
  • mimeType (str) – The mimeType of the file.
  • saveFile (bool) – if False, don’t save the file, just return it.
  • reuseExisting (bool) – If a file with the same name already exists in this location, return it rather than creating a new file.
  • assetstoreType (str or tuple) – If a model other than assetstore will be used to initialize the assetstore adapter for this file, use this parameter to specify it. If it’s a core model, pass its string name. If it’s a plugin model, use a 2-tuple of the form (modelName, pluginName).
createLinkFile(name, parent, parentType, url, creator, size=None, mimeType=None, reuseExisting=False)[source]

Create a file that is a link to a URL, rather than something we maintain in an assetstore.

Parameters:
  • name (str) – The local name for the file.
  • parent (girder.models.folder or girder.models.item) – The parent object for this file.
  • parentType (str) – The parent type (folder or item)
  • url – The URL that this file points to
  • creator (dict) – The user creating the file.
  • size (int) – The size of the file in bytes. (optional)
  • mimeType (str) – The mimeType of the file. (optional)
  • reuseExisting (bool) – If a file with the same name already exists in this location, return it rather than creating a new file.
download(file, offset=0, headers=True, endByte=None, contentDisposition=None, extraParameters=None)[source]

Use the appropriate assetstore adapter for whatever assetstore the file is stored in, and call downloadFile on it. If the file is a link file rather than a file in an assetstore, we redirect to it.

Parameters:
  • file – The file to download.
  • offset (int) – The start byte within the file.
  • headers (bool) – Whether to set headers (i.e. is this an HTTP request for a single file, or something else).
  • endByte (int or None) – Final byte to download. If None, downloads to the end of the file.
  • contentDisposition (str or None) – Content-Disposition response header disposition-type value.
getAssetstoreAdapter(file)[source]

Return the assetstore adapter for the given file. Return None if the file has no assetstore.

getGirderMountFilePath(file, validate=True)[source]

If possible, get the path of the file on a local girder mount.

Parameters:
  • file – The file document.
  • validate – if True, check if the path exists and raise an exception if it does not.
Returns:

a girder mount path to the file or None if no such path is available.

getLocalFilePath(file)[source]

If an assetstore adapter supports it, return a path to the file on the local file system.

Parameters:file – The file document.
Returns:a local path to the file or None if no such path is known.
initialize()[source]

Subclasses should override this and set the name of the collection as self.name. Also, they should set any indexed fields that they require.

isOrphan(file)[source]

Returns True if this file is orphaned (its item or attached entity is missing).

Parameters:file (dict) – The file to check.
open(file)[source]

Use this to expose a Girder file as a python file-like object. At the moment, this is a read-only interface, the equivalent of opening a system file with 'rb' mode. This can also be used as a context manager, e.g.:

>>> with File().open(file) as fh:
>>>    while True:
>>>        chunk = fh.read(CHUNK_LEN)
>>>        if not chunk:
>>>            break

Using it this way will automatically close the file handle for you when the with block is left.

Parameters:file (dict) – A Girder file document.
Returns:A file-like object containing the bytes of the file.
Return type:girder.utility.abstract_assetstore_adapter.FileHandle
propagateSizeChange(item, sizeIncrement, updateItemSize=True)[source]

Propagates a file size change (or file creation) to the necessary parents in the hierarchy. Internally, this records subtree size in the item, the parent folder, and the root node under which the item lives. Should be called anytime a new file is added, a file is deleted, or a file size changes.

Parameters:
  • item (dict) – The parent item of the file.
  • sizeIncrement (int) – The change in size to propagate.
  • updateItemSize – Whether the item size should be updated. Set to False if you plan to delete the item immediately and don’t care to update its size.
remove(file, updateItemSize=True, **kwargs)[source]

Use the appropriate assetstore adapter for whatever assetstore the file is stored in, and call deleteFile on it, then delete the file record from the database.

Parameters:
  • file – The file document to remove.
  • updateItemSize – Whether to update the item size. Only set this to False if you plan to delete the item and do not care about updating its size.
updateFile(file)[source]

Call this when changing properties of an existing file, such as name or MIME type. This causes the updated stamp to change, and also alerts the underlying assetstore adapter that file information has changed.

updateSize(file)[source]

Returns the size of this file. Does not currently check the underlying assetstore to verify the size.

Parameters:file (dict) – The file.
validate(doc)[source]

Models should implement this to validate the document before it enters the database. It must return the document with any necessary filters applied, or throw a ValidationException if validation of the document fails.

Parameters:doc (dict) – The document to validate before saving to the collection.

Upload

class girder.models.upload.Upload[source]

This model stores temporary records for uploads that have been approved but are not yet complete, so that they can be uploaded in chunks of arbitrary size. The chunks must be uploaded in order.

cancelUpload(upload)[source]

Discard an upload that is in progress. This asks the assetstore to discard the data, then removes the item from the upload database.

Parameters:upload (dict) – The upload document to remove.
createUpload(user, name, parentType, parent, size, mimeType=None, reference=None, assetstore=None, attachParent=False, save=True)[source]

Creates a new upload record, and creates its temporary file that the chunks will be written into. Chunks should then be sent in order using the _id of the upload document generated by this method.

Parameters:
  • user (dict) – The user performing the upload.
  • name (str) – The name of the file being uploaded.
  • parentType (str ('folder' or 'item')) – The type of the parent being uploaded into.
  • parent (dict.) – The document representing the parent.
  • size (int) – Total size in bytes of the whole file.
  • mimeType (str) – The mimeType of the file.
  • reference (str) – An optional reference string that will be sent to the data.process event.
  • assetstore – An optional assetstore to use to store the file. If unspecified, the current assetstore is used.
  • attachParent (boolean) – if True, instead of creating an item within the parent or giving the file an itemId, set itemId to None and set attachedToType and attachedToId instead (using the values passed in parentType and parent). This is intended for files that shouldn’t appear as direct children of the parent, but are still associated with it.
  • save (boolean) – if True, save the document after it is created.
Returns:

The upload document that was created.

createUploadToFile(file, user, size, reference=None, assetstore=None)[source]

Creates a new upload record into a file that already exists. This should be used when updating the contents of a file. Deletes any previous file content from the assetstore it was in. This will upload into the current assetstore rather than assetstore the file was previously contained in.

Parameters:
  • file – The file record to update.
  • user – The user performing this upload.
  • size – The size of the new file contents.
  • reference (str) – An optional reference string that will be sent to the data.process event.
  • assetstore – An optional assetstore to use to store the file. If unspecified, the current assetstore is used.
finalizeUpload(upload, assetstore=None)[source]

This should only be called manually in the case of creating an empty file, i.e. one that has no chunks.

Parameters:
  • upload (dict) – The upload document.
  • assetstore (dict) – If known, the containing assetstore for the upload.
Returns:

The file object that was created.

getTargetAssetstore(modelType, resource, assetstore=None)[source]

Get the assetstore for a particular target resource, i.e. where new data within the resource should be stored. In Girder core, this is always just the current assetstore, but plugins may override this behavior to allow for more granular assetstore selection.

Parameters:
  • modelType – the type of the resource that will be stored.
  • resource – the resource to be stored.
  • assetstore – if specified, the preferred assetstore where the resource should be located. This may be overridden.
Returns:

the selected assetstore.

handleChunk(upload, chunk, filter=False, user=None)[source]

When a chunk is uploaded, this should be called to process the chunk. If this is the final chunk of the upload, this method will finalize the upload automatically.

This method will return EITHER an upload or a file document. If this is the final chunk of the upload, the upload is finalized and the created file document is returned. Otherwise, it returns the upload document with the relevant fields modified.

Parameters:
  • upload (dict) – The upload document to update.
  • chunk (file) – The file object representing the chunk that was uploaded.
  • filter (bool) – Whether the model should be filtered. Only affects behavior when returning a file model, not the upload model.
  • user (dict or None) – The current user. Only affects behavior if filter=True.
initialize()[source]

Subclasses should override this and set the name of the collection as self.name. Also, they should set any indexed fields that they require.

list(limit=0, offset=0, sort=None, filters=None)[source]

Search for uploads or simply list all visible uploads.

Parameters:
  • limit – Result set size limit.
  • offset – Offset into the results.
  • sort – The sort direction.
  • filters – if not None, a dictionary that can contain ids that must match the uploads, plus an minimumAge value.
moveFileToAssetstore(file, user, assetstore, progress=<girder.utility.progress.ProgressContext object>)[source]

Move a file from whatever assetstore it is located in to a different assetstore. This is done by downloading and re-uploading the file.

Parameters:
  • file – the file to move.
  • user – the user that is authorizing the move.
  • assetstore – the destination assetstore.
  • progress – optional progress context.
Returns:

the original file if it is not moved, or the newly ‘uploaded’ file if it is.

requestOffset(upload)[source]

Requests the offset that should be used to resume uploading. This makes the request from the assetstore adapter.

untrackedUploads(action='list', assetstoreId=None)[source]

List or discard any uploads that an assetstore knows about but that our database doesn’t have in it.

Parameters:
  • action (str) – ‘delete’ to discard the untracked uploads, anything else to just return with a list of them.
  • assetstoreId (str) – if present, only include untracked items from the specified assetstore.
Returns:

a list of items that were removed or could be removed.

uploadFromFile(obj, size, name, parentType=None, parent=None, user=None, mimeType=None, reference=None, assetstore=None, attachParent=False)[source]

This method wraps the entire upload process into a single function to facilitate “internal” uploads from a file-like object. Example:

size = os.path.getsize(filename)

with open(filename, 'rb') as f:
    Upload().uploadFromFile(f, size, filename, 'item', parentItem, user)
Parameters:
  • obj (file-like) – The object representing the content to upload.
  • size (int) – The total size of the file.
  • name (str) – The name of the file to create.
  • parentType (str) – The type of the parent: “folder” or “item”.
  • parent (dict) – The parent (item or folder) to upload into.
  • user (dict) – The user who is creating the file.
  • mimeType (str) – MIME type of the file.
  • reference (str) – An optional reference string that will be sent to the data.process event.
  • assetstore – An optional assetstore to use to store the file. If unspecified, the current assetstore is used.
  • attachParent (boolean) – if True, instead of creating an item within the parent or giving the file an itemId, set itemId to None and set attachedToType and attachedToId instead (using the values passed in parentType and parent). This is intended for files that shouldn’t appear as direct children of the parent, but are still associated with it.
validate(doc)[source]

Models should implement this to validate the document before it enters the database. It must return the document with any necessary filters applied, or throw a ValidationException if validation of the document fails.

Parameters:doc (dict) – The document to validate before saving to the collection.

Notification

class girder.models.notification.Notification[source]

This model is used to represent a notification that should be streamed to a specific user in some way. Each notification contains a type field indicating what kind of notification it is, a userId field indicating which user the notification should be sent to, a data field representing the payload of the notification, a time field indicating the time at which the event happened, and an optional expires field indicating at what time the notification should be deleted from the database.

createNotification(type, data, user, expires=None, token=None)[source]

Create a generic notification.

Parameters:
  • type (str) – The notification type.
  • data – The notification payload.
  • user (dict) – User to send the notification to.
  • expires (datetime.datetime) – Expiration date (for transient notifications).
  • token (dict) – Set this if the notification should correspond to a token instead of a user.
get(user, since=None, token=None, sort=None)[source]

Get outstanding notifications for the given user.

Parameters:
  • user – The user requesting updates. None to use the token instead.
  • since (datetime) – Limit results to entities that have been updated since a certain timestamp.
  • token – if the user is None, the token requesting updated.
  • sort – Sort field for the database query.
initProgress(user, title, total=0, state='active', current=0, message='', token=None, estimateTime=True, resource=None, resourceName=None)[source]

Create a “progress” type notification that can be updated anytime there is progress on some task. Progress records that are not updated for more than one hour will be deleted. The “time” field of a progress record indicates the time the task was started.

Parameters:
  • user – the user associated with this notification. If this is None, a session token must be specified.
  • title (str) – The title of the task. This should not change over the course of the task. (e.g. ‘Deleting folder “foo”’)
  • total (int, long, or float) – Some numeric value representing the total task length. By convention, setting this <= 0 means progress on this task is indeterminate.
  • state (ProgressState enum value.) – Represents the state of the underlying task execution.
  • current (int, long, or float) – Some numeric value representing the current progress of the task (relative to total).
  • message (str) – Message corresponding to the current state of the task.
  • token – if the user is None, associate this notification with the specified session token.
  • estimateTime – if True, generate an estimate of the total time the task will take, if possible. If False, never generate a time estimate.
  • resource – a partial or complete resource that the notification is associated with. This must at a minimum include the id of the resource.
  • resourceName – the type of resource the notification is associated with.
initialize()[source]

Subclasses should override this and set the name of the collection as self.name. Also, they should set any indexed fields that they require.

updateProgress(record, save=True, **kwargs)[source]

Update an existing progress record.

Parameters:
  • record (dict) – The existing progress record to update.
  • total (int, long, or float) – Some numeric value representing the total task length. By convention, setting this <= 0 means progress on this task is indeterminate. Generally this shouldn’t change except in cases where progress on a task switches between indeterminate and determinate state.
  • state (ProgressState enum value.) – Represents the state of the underlying task execution.
  • current (int, long, or float) – Some numeric value representing the current progress of the task (relative to total).
  • increment (int, long, or float) – Amount to increment the progress by. Don’t pass both current and increment together, as that behavior is undefined.
  • message (str) – Message corresponding to the current state of the task.
  • expires (datetime) – Set a custom (UTC) expiration time on the record. Default is one hour from the current time.
  • save (bool) – Whether to save the record to the database.
validate(doc)[source]

Models should implement this to validate the document before it enters the database. It must return the document with any necessary filters applied, or throw a ValidationException if validation of the document fails.

Parameters:doc (dict) – The document to validate before saving to the collection.
class girder.models.notification.ProgressState[source]

Enum of possible progress states for progress records.

Web API Endpoints

Base Classes and Helpers

girder.api.access.admin(fun, scope=None, cookie=False)[source]

REST endpoints that require administrator access should be wrapped in this decorator.

Parameters:
  • fun (callable) – A REST endpoint.
  • scope (str or list of str or None) – To also expose this endpoint for certain token scopes, pass those scopes here. If multiple are passed, all will be required.
  • cookie (bool) – if True, this rest endpoint allows the use of a cookie for authentication. If this is specified on routes that can alter the system (those other than HEAD and GET), it can expose an application to Cross-Site Request Forgery (CSRF) attacks.
girder.api.access.public(fun, scope=None, cookie=False)[source]

Functions that allow any client access, including those that haven’t logged in should be wrapped in this decorator.

Parameters:
  • fun (callable) – A REST endpoint.
  • scope (str or list of str or None) – The scope or list of scopes required for this token.
  • cookie (bool) – if True, this rest endpoint allows the use of a cookie for authentication. If this is specified on routes that can alter the system (those other than HEAD and GET), it can expose an application to Cross-Site Request Forgery (CSRF) attacks.
girder.api.access.token(fun, scope=None, required=False, cookie=False)[source]

REST endpoints that require a token, but not necessarily a user authentication token, should use this access decorator.

Parameters:
  • fun (callable) – A REST endpoint.
  • scope (str or list of str or None) – The scope or list of scopes required for this token.
  • required (bool) – Whether all of the passed scope are required to access the endpoint at all.
  • cookie (bool) – if True, this rest endpoint allows the use of a cookie for authentication. If this is specified on routes that can alter the system (those other than HEAD and GET), it can expose an application to Cross-Site Request Forgery (CSRF) attacks.
girder.api.access.user(fun, scope=None, cookie=False)[source]

REST endpoints that require a logged-in user should be wrapped with this access decorator.

Parameters:
  • fun (callable) – A REST endpoint.
  • scope (str or list of str or None) – To also expose this endpoint for certain token scopes, pass those scopes here. If multiple are passed, all will be required.
  • cookie (bool) – if True, this rest endpoint allows the use of a cookie for authentication. If this is specified on routes that can alter the system (those other than HEAD and GET), it can expose an application to Cross-Site Request Forgery (CSRF) attacks.
class girder.api.describe.ApiDocs(templatePath=None)[source]

This serves up the Swagger page.

class girder.api.describe.Describe[source]
class girder.api.describe.Description(summary)[source]

This class provides convenient chainable semantics to allow api route handlers to describe themselves to the documentation. A route handler function can apply the girder.api.describe.describeRoute decorator to itself (called with an instance of this class) in order to describe itself.

asDict()[source]

Returns this description object as an appropriately formatted dict

deprecated()[source]

Mark the route as deprecated.

errorResponse(reason='A parameter was invalid.', code=400)[source]

This helper will build an errorResponse declaration for you. Many endpoints will be able to use the default parameter values for one of their responses.

Parameters:
  • reason (str, list, or tuple) – The reason or list of reasons why the error occurred.
  • code (int) – HTTP status code.
jsonParam(name, description, paramType='query', dataType='string', required=True, default=None, requireObject=False, requireArray=False, schema=None)[source]

Specifies a parameter that should be processed as JSON.

Parameters:
  • requireObject (bool) – Whether the value must be a JSON object / Python dict.
  • requireArray (bool) – Whether the value must be a JSON array / Python list.
  • schema (dict) – A JSON schema that will be used to validate the parameter value. If this is passed, it overrides any requireObject or requireArray values that were passed.
modelParam(name, description=None, model=None, destName=None, paramType='path', plugin='_core', level=None, required=True, force=False, exc=True, requiredFlags=None, **kwargs)[source]

This should be used in lieu of param if the parameter is a model ID and the model should be loaded and passed into the route handler. For example, if you have a route like GET /item/:id, you could do:

>>> from girder.models.item import Item
>>> modelParam('id', model=Item, level=AccessType.READ)

Which would cause the id parameter in the path to be mapped to an item model parameter named item, and ensure that the calling user has at least READ access on that item. For parameters passed in the query string or form data, for example a request like POST /item?folderId=..., you must specify the paramType.

>>> modelParam('folderId', 'The ID of the parent folder.', model=Folder,
...            level=AccessType.WRITE, paramType='query')

Note that in the above example, model is omitted; in this case, the model is inferred to be 'folder' from the parameter name 'folderId'.

Parameters:
  • name (str) – The name passed in via the request, e.g. ‘id’.
  • description (str) – The description of the parameter. If not passed, defaults to “The ID of the <model>.”
  • destName (str) – The kwarg name after model loading, e.g. ‘folder’. Defaults to the value of the model parameter.
  • paramType – how is the parameter sent. One of ‘query’, ‘path’, ‘body’, ‘header’, or ‘formData’.
  • model (class or str) – The model class to use for loading, or a name, e.g. ‘folder’. If not passed, defaults to stripping the last two characters from the name, such that e.g. ‘folderId’ would make the model become ‘folder’.
  • plugin (str) – Plugin name, if loading a plugin model. Only used when the model param is a string rather than a class.
  • level (AccessType) – Access level, if this is an access controlled model.
  • required (bool) – Whether this parameter is required.
  • force (bool) – Force loading of the model (skip access check).
  • exc (bool) – Whether an exception should be raised for a nonexistent resource.
  • requiredFlags (str or list/set/tuple of str or None) – Access flags that are required on the object being loaded.
pagingParams(defaultSort, defaultSortDir=1, defaultLimit=50)[source]

Adds the limit, offset, sort, and sortdir parameter documentation to this route handler.

Parameters:
  • defaultSort (str) – The default field used to sort the result set.
  • defaultSortDir (int) – Sort order: -1 or 1 (desc or asc)
  • defaultLimit (int) – The default page size.
param(name, description, paramType='query', dataType='string', required=True, enum=None, default=None, strip=False, lower=False, upper=False)[source]

This helper will build a parameter declaration for you. It has the most common options as defaults, so you won’t have to repeat yourself as much when declaring the APIs.

Note that we could expose more parameters from the Parameter Object spec, for example: format, allowEmptyValue, minimum, maximum, pattern, uniqueItems.

Parameters:
  • name – name of the parameter used in the REST query.
  • description – explanation of the parameter.
  • paramType – how is the parameter sent. One of ‘query’, ‘path’, ‘body’, ‘header’, or ‘formData’.
  • dataType – the data type expected in the parameter. This is one of ‘integer’, ‘long’, ‘float’, ‘double’, ‘string’, ‘byte’, ‘binary’, ‘boolean’, ‘date’, ‘dateTime’, ‘password’, or ‘file’.
  • required – True if the request will fail if this parameter is not present, False if the parameter is optional.
  • enum (list) – a fixed list of possible values for the field.
  • strip (bool) – For string types, set this to True if the string should be stripped of white space.
  • lower (bool) – For string types, set this to True if the string should be converted to lowercase.
  • upper (bool) – For string types, set this to True if the string should be converted to uppercase.
girder.api.docs.addModel(name, model, resources=None, silent=False)[source]

Add a model to the Swagger documentation.

Parameters:
  • resources – The type(s) of resource(s) to add the model to. New resource types may be implicitly defined, with the expectation that routes will be added for them at some point. If no resources are passed, the model will be exposed for every resource type
  • resources – str or tuple/list[str]
  • name (str) – The name of the model.
  • model (dict) – The model to add.
  • silent (bool) – Set this to True to suppress warnings.

Warning

This is a low-level API which does not validate the format of model. See the Swagger Model documentation for a complete specification of the correct format for model.

Changed in version The: syntax and behavior of this function was modified after v1.3.2. The previous implementation did not include a resources parameter.

girder.api.docs.addRouteDocs(resource, route, method, info, handler)[source]

This is called for route handlers that have a description attr on them. It gathers the necessary information to build the swagger documentation, which is consumed by the docs.Describe endpoint.

Parameters:
  • resource (str) – The name of the resource, e.g. “item”
  • route (tuple[str]) – The route to describe.
  • method (str) – The HTTP method for this route, e.g. “POST”
  • info (dict) – The information representing the API documentation, typically from girder.api.describe.Description.asDict.
  • handler (function) – The actual handler method for this route.
girder.api.docs.removeRouteDocs(resource, route, method, info, handler)[source]

Remove documentation for a route handler.

Parameters:
  • resource (str) – The name of the resource, e.g. “item”
  • route (tuple[str]) – The route to describe.
  • method (str) – The HTTP method for this route, e.g. “POST”
  • info (dict) – The information representing the API documentation.
  • handler (function) – The actual handler method for this route.
class girder.api.filter_logging.RegexLoggingFilter(name='')[source]

Check log messages against a list of compiled regular expressions. If any of them match, throttle logs.

filter(record)[source]

Determine if the specified record is to be logged.

Is the specified record to be logged? Returns 0 for no, nonzero for yes. If deemed appropriate, the record may be modified in-place.

girder.api.filter_logging.addLoggingFilter(regex, frequency=None, duration=None)[source]

Add a regular expression to the logging filter. If the regular expression matches a registered regex exactly, just update the frequency value.

Parameters:
  • regex – a regular expression to match against log messages. For matching cherrypy endpoint logging, this should probably be something like ‘GET /api/v1/item/[0-9a-fA-F]+/download[/ ?#]’. More generally, a value like GET (/[^/ ?#]+)*/item/[^/ ?#]+/download[/ ?#] would be agnostic to the api_root.
  • frequency – either None to never log matching log messages, or an integer, where one log message is emitted out of the specified number.
  • duration – either None to not log based on elapsed time, or a float value of seconds between logging.
girder.api.filter_logging.removeLoggingFilter(regex)[source]

Remove a regular expression from the logging filter.

Parameters:regex – the regular expression to remove.
Returns:True if a filter was removed.
class girder.api.rest.Prefix[source]

Utility class used to provide api prefixes.

class girder.api.rest.Resource[source]

All REST resources should inherit from this class, which provides utilities for adding resources/routes to the REST API.

boolParam(key, params, default=None)[source]

Coerce a parameter value from a str to a bool.

Parameters:
  • key (str) – The parameter key to test.
  • params (dict) – The request parameters.
  • default (bool or None) – The default value if no key is passed.
deleteAuthTokenCookie()[source]

Helper method to kill the authentication cookie

ensureTokenScopes(scope)[source]

Ensure that the token passed to this request is authorized for the designated scope or set of scopes. Raises an AccessException if not.

Parameters:scope (str or list of str) – A scope or set of scopes that is required.
getBodyJson()[source]

Bound wrapper for girder.api.rest.getBodyJson().

getCurrentToken()[source]

Returns the current valid token object that was passed via the token header or parameter, or None if no valid token was passed.

getCurrentUser(returnToken=False)[source]

Returns the currently authenticated user based on the token header or parameter.

Parameters:returnToken (bool) – Whether we should return a tuple that also contains the token.
Returns:The user document from the database, or None if the user is not logged in or the token is invalid or expired. If returnToken=True, returns a tuple of (user, token).
getPagingParameters(params, defaultSortField=None, defaultSortDir=1)[source]

Pass the URL parameters into this function if the request is for a list of resources that should be paginated. It will return a tuple of the form (limit, offset, sort) whose values should be passed directly into the model methods that are finding the resources. If the client did not pass the parameters, this always uses the same defaults of limit=50, offset=0, sort=’name’, sortdir=SortDir.ASCENDING=1.

Parameters:
  • params (dict) – The URL query parameters.
  • defaultSortField (str or None) – If the client did not pass a ‘sort’ parameter, set this to choose a default sort field. If None, the results will be returned unsorted.
  • defaultSortDir (girder.constants.SortDir) – Sort direction.
getParamJson(name, params, default=None)[source]

Bound wrapper for girder.api.rest.getParamJson().

getRouteHandler(method, route)[source]

Get the handler method for a given method and route.

Parameters:
  • method (str) – The HTTP method, e.g. ‘GET’, ‘POST’, ‘PUT’
  • route (tuple[str]) – The route, as a list of path params relative to the resource root, exactly as it was passed to the route method.
Returns:

The handler method for the route.

Return type:

Function

Raises:

Exception, when no route can be found.

handleRoute(method, path, params)[source]

Match the requested path to its corresponding route, and calls the handler for that route with the appropriate kwargs. If no route matches the path requested, throws a RestException.

This method fires two events for each request if a matching route is found. The names of these events are derived from the route matched by the request. As an example, if the user calls GET /api/v1/item/123, the following two events would be fired:

rest.get.item/:id.before

would be fired prior to calling the default API function, and

rest.get.item/:id.after

would be fired after the route handler returns. The query params are passed in the info of the before and after event handlers as event.info[‘params’], and the matched route tokens are passed in as dict items of event.info, so in the previous example event.info would also contain an ‘id’ key with the value of 123. For endpoints with empty sub-routes, the trailing slash is omitted from the event name, e.g.:

rest.post.group.before

Note

You will normally not need to call this method directly, as it is called by the internals of this class during the routing process.

Parameters:
  • method (str) – The HTTP method of the current request.
  • path (tuple[str]) – The path params of the request.
removeRoute(method, route, resource=None)[source]

Remove a route from the handler and documentation.

Parameters:
  • method (str) – The HTTP method, e.g. ‘GET’, ‘POST’, ‘PUT’
  • route (tuple[str]) – The route, as a list of path params relative to the resource root. Elements of this list starting with ‘:’ are assumed to be wildcards.
  • resource – the name of the resource at the root of this route.
requireAdmin(user, message=None)[source]

Calling this on a user will ensure that they have admin rights. If not, raises an AccessException.

Parameters:
  • user (dict.) – The user to check admin flag on.
  • message (str or None) – The exception message.
Raises:

AccessException – If the user is not an administrator.

requireParams(required, provided=None)[source]

This method has two modes. In the first mode, this takes two parameters, the first being a required parameter or list of them, and the second the dictionary of parameters that were passed. If the required parameter does not appear in the passed parameters, a ValidationException is raised.

The second mode of operation takes only a single parameter, which is a dict mapping required parameter names to passed in values for those params. If the value is None, a ValidationException is raised. This mode works well in conjunction with the autoDescribeRoute decorator, where the parameters are not all contained in a single dictionary.

Parameters:
  • required (list, tuple, or str) – An iterable of required params, or if just one is required, you can simply pass it as a string.
  • provided (dict) – The list of provided parameters.
route(method, route, handler, nodoc=False, resource=None)[source]

Define a route for your REST resource.

Parameters:
  • method (str) – The HTTP method, e.g. ‘GET’, ‘POST’, ‘PUT’, ‘PATCH’
  • route (tuple[str]) – The route, as a list of path params relative to the resource root. Elements of this list starting with ‘:’ are assumed to be wildcards.
  • handler (function) – The method to be called if the route and method are matched by a request. Wildcards in the route will be expanded and passed as kwargs with the same name as the wildcard identifier.
  • nodoc (bool) – If your route intentionally provides no documentation, set this to True to disable the warning on startup.
  • resource – The name of the resource at the root of this route. The resource instance (self) can also be passed. This allows the mount path to be looked up. This allows a resource to be mounted at a prefix.
sendAuthTokenCookie(user=None, scope=None, token=None, days=None)[source]

Helper method to send the authentication cookie

setRawResponse(*args, **kwargs)[source]

Bound alias for girder.api.rest.setRawResponse.

girder.api.rest.boundHandler(fun, ctx=None)[source]

This decorator allows unbound functions to be conveniently added as route handlers to existing girder.api.rest.Resource instances. With no arguments, this uses a shared, generic Resource instance as the context. If you need a specific instance, pass that as the ctx arg, for instance if you need to reference the resource name or any other properties specific to a Resource subclass.

Plugins that add new routes to existing API resources are encouraged to use this to gain access to bound convenience methods like self.getCurrentUser, etc.

Parameters:
  • fun (callable) – A REST endpoint.
  • ctx (Resource or None) – A Resource instance, to be bound to fun.
girder.api.rest.disableAuditLog(fun)[source]

If calls to a REST route should not be logged in the audit log, decorate it with this function.

girder.api.rest.endpoint(fun)[source]

REST HTTP method endpoints should use this decorator. It converts the return value of the underlying method to the appropriate output format and sets the relevant response headers. It also handles RestExceptions, which are 400-level exceptions in the REST endpoints, AccessExceptions resulting from access denial, and also handles any unexpected errors using 500 status and including a useful traceback in those cases.

If you want a streamed response, simply return a generator function from the inner method.

girder.api.rest.ensureTokenScopes(token, scope)[source]

Call this to validate a token scope for endpoints that require tokens other than a user authentication token. Raises an AccessException if the required scopes are not allowed by the given token.

Parameters:
  • token (dict) – The token object used in the request.
  • scope (str or list of str) – The required scope or set of scopes.
girder.api.rest.getApiUrl(url=None, preferReferer=False)[source]

In a request thread, call this to get the path to the root of the REST API. The returned path does not end in a forward slash.

Parameters:
  • url – URL from which to extract the base URL. If not specified, uses the server root system setting. If that is not specified, uses cherrypy.url()
  • preferReferer – if no url is specified, this is true, and this is in a cherrypy request that has a referer header that contains the api string, use that referer as the url.
girder.api.rest.getBodyJson(allowConstants=False)[source]

For requests that are expected to contain a JSON body, this returns the parsed value, or raises a girder.api.rest.RestException for invalid JSON.

Parameters:allowConstants (bool) – Whether the keywords Infinity, -Infinity, and NaN should be allowed. These keywords are valid JavaScript and will parse to the correct float values, but are not valid in strict JSON.
girder.api.rest.getCurrentToken(allowCookie=None)[source]

Returns the current valid token object that was passed via the token header or parameter, or None if no valid token was passed.

Parameters:allowCookie (bool) – Normally, authentication via cookie is disallowed to protect against CSRF attacks. If you want to expose an endpoint that can be authenticated with a token passed in the Cookie, set this to True. This should only be used on read-only operations that will not make any changes to data on the server, and only in cases where the user agent behavior makes passing custom headers infeasible, such as downloading data to disk in the browser. In the event that allowCookie is not explicitly passed, it will default to False unless the access.cookie decorator is used.
girder.api.rest.getCurrentUser(returnToken=False)[source]

Returns the currently authenticated user based on the token header or parameter.

Parameters:returnToken (bool) – Whether we should return a tuple that also contains the token.
Returns:the user document from the database, or None if the user is not logged in or the token is invalid or expired. If returnToken=True, returns a tuple of (user, token).
girder.api.rest.getParamJson(name, params, default=None)[source]

For parameters that are expected to be specified as JSON, use this to parse them, or raises a RestException if parsing fails.

Parameters:
  • name (str) – The param name.
  • params (dict) – The dictionary of parameters.
  • default – The default value if no such param was passed.
girder.api.rest.getUrlParts(url=None)[source]

Calls urllib.parse.urlparse on a URL.

Parameters:url (str or None) – A URL, or None to use the current request’s URL.
Returns:The URL’s separate components.
Return type:urllib.parse.ParseResult

Note

This is compatible with both Python 2 and 3.

girder.api.rest.iterBody(length=65536, strictLength=False)[source]

This is a generator that will read the request body a chunk at a time and yield each chunk, abstracting details of the underlying HTTP server. This function works regardless of whether the body was sent with a Content-Length or using Transfer-Encoding: chunked, but the behavior is slightly different in each case.

If Content-Length is provided, the length parameter is used to read the body in chunks up to size length. This will block until end of stream or the specified number of bytes is ready.

If Transfer-Encoding: chunked is used, the length parameter is ignored by default, and the generator yields each chunk that is sent in the request regardless of its length. However, if strictLength is set to True, it will block until length bytes have been read or the end of the request.

Parameters:
  • length (int) – Max buffer size to read per iteration if the request has a known Content-Length.
  • strictLength (bool) – If the request is chunked, set this to True to block until length bytes have been read or end-of-stream.
class girder.api.rest.loadmodel(map=None, model=None, plugin='_core', level=None, force=False, exc=True, requiredFlags=None, **kwargs)[source]

This is a decorator that can be used to load a model based on an ID param. For access controlled models, it will check authorization for the current user. The underlying function is called with a modified set of keyword arguments that is transformed by the “map” parameter of this decorator. Any additional kwargs will be passed to the underlying model’s load.

Parameters:
  • map (dict or None) – Map of incoming parameter name to corresponding model arg name. If None is passed, this will map the parameter named “id” to a kwarg named the same as the “model” parameter.
  • model (str) – The model name, e.g. ‘folder’
  • plugin (str) – Plugin name, if loading a plugin model.
  • level (AccessType) – Access level, if this is an access controlled model.
  • force (bool) – Force loading of the model (skip access check).
  • exc (bool) – Whether an exception should be raised for a nonexistent resource.
  • requiredFlags (str or list/set/tuple of str or None) – Access flags that are required on the object being loaded.
girder.api.rest.rawResponse(fun)[source]

This is a decorator that can be placed on REST route handlers, and is equivalent to calling setRawResponse() in the handler body.

girder.api.rest.requireAdmin(user, message=None)[source]

Calling this on a user will ensure that they have admin rights. If not, raises an AccessException.

Parameters:
  • user (dict.) – The user to check admin flag on.
  • message (str or None) – The exception message.
Raises:

AccessException – If the user is not an administrator.

girder.api.rest.setContentDisposition(filename, disposition='attachment', setHeader=True)[source]

Set the content disposition header to either inline or attachment, and specify a filename that is properly escaped. See developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Disposition, tools.ietf.org/html/rfc2183, tools.ietf.org/html/rfc6266, and tools.ietf.org/html/rfc5987 for specifications and details.

Parameters:
  • filename – the filename to add to the content disposition header.
  • disposition – either ‘inline’ or ‘attachment’. None is the same as ‘attachment’. Any other value skips setting the content disposition header.
  • setHeader – if False, return the value that would be set to the Content-Disposition header, but do not set it.
Returns:

the content-disposition header value.

girder.api.rest.setCurrentUser(user)[source]

Explicitly set the user for the current request thread. This can be used to enable specialized auth behavior on a per-request basis.

Parameters:user (dict or None) – The user to set as the current user of this request.
girder.api.rest.setRawResponse(val=True)[source]

Normally, non-streaming responses go through a serialization process in accordance with the “Accept” request header. Endpoints that wish to return a raw response without using a streaming response should call this, or use its bound version on the Resource class, or add the rawResponse decorator on the REST route handler function.

Parameters:val (bool) – Whether the return value should be sent raw.
girder.api.rest.setResponseHeader(header, value)[source]

Set a response header to the given value.

Parameters:
  • header (str) – The header name.
  • value (str) – The value for the header.

Utility

class girder.utility.JsonEncoder(*, skipkeys=False, ensure_ascii=True, check_circular=True, allow_nan=True, sort_keys=False, indent=None, separators=None, default=None)[source]

This extends the standard json.JSONEncoder to allow for more types to be sensibly serialized. This is used in Girder’s REST layer to serialize route return values when JSON is requested.

default(obj)[source]

Implement this method in a subclass such that it returns a serializable object for o, or calls the base implementation (to raise a TypeError).

For example, to support arbitrary iterators, you could implement default like this:

def default(self, o):
    try:
        iterable = iter(o)
    except TypeError:
        pass
    else:
        return list(iterable)
    # Let the base class default method raise the TypeError
    return JSONEncoder.default(self, o)
class girder.utility.RequestBodyStream(stream, size=None)[source]

Wraps a cherrypy request body into a more abstract file-like object.

getSize()[source]

Returns the size of the body data wrapped by this class. For multipart encoding, this is the size of the part. For sending as the body, this is the Content-Length header.

girder.utility.camelcase(value)[source]

Convert a module name or string with underscores and periods to camel case.

Parameters:value (str) – the string to convert
Returns:the value converted to camel case.
girder.utility.genToken(length=64)[source]

Use this utility function to generate a random string of a desired length.

girder.utility.mkdir(path, mode=511, recurse=True, existOk=True)[source]

Create a new directory or ensure a directory already exists.

Parameters:
  • path (str) – The directory to create.
  • mode (int) – The mode (permission mask) prior to applying umask.
  • recurse (bool) – Whether intermediate missing dirs should be created.
  • existOk (bool) – Set to True to suppress the error if the dir exists.
girder.utility.optionalArgumentDecorator(baseDecorator)[source]

This decorator can be applied to other decorators, allowing the target decorator to be used either with or without arguments.

The target decorator is expected to take at least 1 argument: the function to be wrapped. If additional arguments are provided by the final implementer of the target decorator, they will be passed to the target decorator as additional arguments.

For example, this may be used as:

@optionalArgumentDecorator
def myDec(fun, someArg=None):
    ...

@myDec
def a(...):
    ...

@myDec()
def a(...):
    ...

@myDec(5)
def a(...):
    ...

@myDec(someArg=5)
def a(...):
    ...
Parameters:baseDecorator (callable) – The target decorator.
girder.utility.parseTimestamp(x, naive=True)[source]

Parse a datetime string using the python-dateutil package.

If no timezone information is included, assume UTC. If timezone information is included, convert to UTC.

If naive is True (the default), drop the timezone information such that a naive datetime is returned.

girder.utility.toBool(val)[source]

Coerce a string value to a bool. Meant to be used to parse HTTP parameters, which are always sent as strings. The following string values will be interpreted as True:

  • 'true'
  • 'on'
  • '1'
  • 'yes'

All other strings will be interpreted as False. If the given param is not passed at all, returns the value specified by the default arg. This function is case-insensitive.

Parameters:val (str) – The value to coerce to a bool.
class girder.utility.abstract_assetstore_adapter.AbstractAssetstoreAdapter(assetstore)[source]

This defines the interface to be used by all assetstore adapters.

cancelUpload(upload)[source]

This is called when an upload has been begun and it should be abandoned. It must clean up temporary files, chunks, or whatever other information the assetstore contains.

capacityInfo()[source]

Assetstore types that are able to report how much free and/or total capacity they have should override this method. Default behavior is to report both quantities as unknown.

Returns:A dict with ‘free’ and ‘total’ keys whose values are either bytes (ints) or None for an unknown quantity.
checkUploadSize(upload, chunkSize)[source]

Check if the upload is valid based on the chunk size. If this raises an exception, then the caller should clean up and reraise the exception.

Parameters:
  • upload – the dictionary of upload information. The received and size values are used.
  • chunkSize (a non-negative integer or None if unknown.) – the chunk size that needs to be validated.
copyFile(srcFile, destFile)[source]

This method copies the necessary fields and data so that the destination file contains the same data as the source file.

Parameters:
  • srcFile (dict) – The original File document.
  • destFile (dict) – The File which should have the data copied to it.
Returns:

A dict with the destination file.

deleteFile(file)[source]

This is called when a File is deleted to allow the adapter to remove the data from within the assetstore. This method should not modify or delete the file object, as the caller will delete it afterward.

Parameters:file (dict) – The File document about to be deleted.
downloadFile(file, offset=0, headers=True, endByte=None, contentDisposition=None, extraParameters=None, **kwargs)[source]

This method is in charge of returning a value to the RESTful endpoint that can be used to download the file. This should either return a generator function that yields the bytes of the file (which will stream the file directly), or modify the response headers and raise a cherrypy.HTTPRedirect.

Parameters:
  • file (dict) – The file document being downloaded.
  • offset (int) – Offset in bytes to start the download at.
  • headers (bool) – Flag for whether headers should be sent on the response.
  • endByte (int or None) – Final byte to download. If None, downloads to the end of the file.
  • contentDisposition (str or None) – Value for Content-Disposition response header disposition-type value.
static fileIndexFields()[source]

Default behavior is that no additional file fields need to be indexed within the database.

fileUpdated(file)[source]

This is called when the file document has been changed. Any assetstore implementation that needs to do anything when the file document changes should override this method.

Parameters:file (dict) – The updated file document.
finalizeUpload(upload, file)[source]

Call this once the last chunk has been processed. This method does not need to delete the upload document as that will be deleted by the caller afterward. This method may augment the File document, and must return the File document.

Parameters:
  • upload (dict) – The upload document.
  • file (dict) – The file document that was created.
Returns:

The file document with optional modifications.

findInvalidFiles(progress=<girder.utility.progress.ProgressContext object>, filters=None, checkSize=True, **kwargs)[source]

Finds and yields any invalid files in the assetstore. It is left to the caller to decide what to do with them.

Parameters:
  • progress (girder.utility.progress.ProgressContext) – Pass a progress context to record progress.
  • filters (dict or None) – Additional query dictionary to restrict the search for files. There is no need to set the assetstoreId in the filters, since that is done automatically.
  • checkSize (bool) – Whether to make sure the size of the underlying data matches the size of the file.
getChunkSize(chunk)[source]

Given a chunk that is either a file-like object or a string, attempt to determine its length. If it is a file-like object, then this relies on being able to use fstat.

Parameters:chunk (a file-like object or a string) – the chunk to get the size of
Returns:the length of the chunk if known, or None.
getLocalFilePath(file)[source]

If an assetstore adapter supports it, return a path to the file on the local file system. Otherwise, raise an exception.

Parameters:file (dict) – The file document.
Returns:a local path to the file.
Return type:str
importData(parent, parentType, params, progress, user, **kwargs)[source]

Assetstores that are capable of importing pre-existing data from the underlying storage medium can implement this method.

Parameters:
  • parent – The parent object to import into.
  • parentType (str) – The model type of the parent object (folder, user, or collection).
  • params (dict) – Additional parameters required for the import process. Typically includes an importPath field representing a root path on the underlying storage medium.
  • progress (girder.utility.progress.ProgressContext) – Object on which to record progress if possible.
  • user (dict or None) – The Girder user performing the import.
initUpload(upload)[source]

This must be called before any chunks are uploaded to do any additional behavior and optionally augment the upload document. The method must return the upload document. Default behavior is to simply return the upload document unmodified.

Parameters:upload (dict) – The upload document to optionally augment.
open(file)[source]

Exposes a Girder file as a python file-like object. At the moment, this is a read-only interface, the equivalent of opening a system file with ‘rb’ mode.

Parameters:file (dict) – A Girder file document.
Returns:A file-like object containing the bytes of the file.
Return type:FileHandle
requestOffset(upload)[source]

Request the offset for resuming an interrupted upload. Default behavior simply returns the ‘received’ field of the upload document. This method exists because in some cases, such as when the server crashes, it’s possible that the received field is not accurate, so adapters may implement this to provide the actual next byte required.

setContentHeaders(file, offset, endByte, contentDisposition=None)[source]

Sets the Content-Length, Content-Disposition, Content-Type, and also the Content-Range header if this is a partial download.

Parameters:
  • file – The file being downloaded.
  • offset (int) – The start byte of the download.
  • endByte (int) – The end byte of the download (non-inclusive).
  • contentDisposition (str or None) – Content-Disposition response header disposition-type value, if None, Content-Disposition will be set to ‘attachment; filename=$filename’.
shouldImportFile(path, params)[source]

This is a helper used during the import process to determine if a file located at the specified path should be imported, based on the request parameters. Exclusion takes precedence over inclusion.

Parameters:
  • path (str) – The path of the file.
  • params (dict) – The request parameters.
Return type:

bool

untrackedUploads(knownUploads=(), delete=False)[source]

List and optionally discard uploads that are in the assetstore but not in the known list.

Parameters:
  • knownUploads (list) – a list of upload dictionaries of all known incomplete uploads.
  • delete (bool) – if True, delete any unknown uploads.
Returns:

a list of unknown uploads.

uploadChunk(upload, chunk)[source]

Call this method to process each chunk of an upload.

Parameters:
  • upload (dict) – The upload document to update.
  • chunk (file) – The file object representing the chunk that was uploaded.
Returns:

Must return the upload document with any optional changes.

static validateInfo(doc)[source]

Adapters may implement this if they need to perform any validation steps whenever the assetstore info is saved to the database. It should return the document with any necessary alterations in the success case, or throw an exception if validation fails.

class girder.utility.abstract_assetstore_adapter.FileHandle(file, adapter)[source]

This is the base class that is returned for the file-like API into Girder file objects. The open method of assetstore implementations is responsible for returning an instance of this class or one of its subclasses. This base class implementation is returned by the abstract assetstore adapter, and does not leverage any details of the assetstore implementations.

These file handles are stateful, and therefore not safe for concurrent access. If used by multiple threads, mutexes should be used.

Parameters:
read(size=None)[source]

Read size bytes from the file data.

Parameters:size (int) – The number of bytes to read from the current position. The actual number returned could be less than this if the end of the file is reached. An empty response indicates that the file has been completely consumed. If None or negative, read to the end of the file.
Return type:bytes
class girder.utility.acl_mixin.AccessControlMixin[source]

This mixin is intended to be used for resources which aren’t access controlled by default, but resolve their access controls through other resources. As such, the overridden methods retain the same parameters and only alter functionality related to access control resolution.

resourceColl corresponds to the resource collection that needs to be used for resolution, for example the Item model has a resourceColl of folder.

resourceParent corresponds to the field in which the parent resource belongs, so for an item it would be the folderId.

filterResultsByPermission(cursor, user, level, limit=0, offset=0, removeKeys=(), flags=None)[source]

Yields filtered results from the cursor based on the access control existing for the resourceParent.

Takes the same parameters as girder.models.model_base.AccessControlledModel.filterResultsByPermission().

findWithPermissions(query=None, offset=0, limit=0, timeout=None, fields=None, sort=None, user=None, level=0, aggregateSort=None, **kwargs)[source]

Search the collection by a set of parameters, only returning results that the combined user and level have permission to access. Passes any extra kwargs through to the underlying pymongo.collection.find function.

Parameters:
  • query (dict) – The search query (see general MongoDB docs for “find()”)
  • offset (int) – The offset into the results
  • limit (int) – Maximum number of documents to return
  • timeout (int) – Cursor timeout in ms. Default is no timeout.
  • fields (str, list of strings or tuple of strings for fields to be included from the document, or dict for an inclusion or exclusion projection.) – A mask for filtering result documents by key, or None to return the full document, passed to MongoDB find() as the projection param.
  • sort (List of (key, order) tuples.) – The sort order.
  • user (dict or None) – The user to check policies against.
  • level (AccessType) – The access level. Explicitly passing None skips doing permissions checks.
  • aggregateSort (List of (key, order) tuples.) – A sort order to use if sort is None and an aggregation is used.
Returns:

A pymongo Cursor, CommandCursor, or an iterable. If a CommandCursor, it has been augmented with a count function.

hasAccess(resource, user=None, level=0)[source]

Determines if a user has access to a resource based on their access to the resourceParent.

Takes the same parameters as girder.models.model_base.AccessControlledModel.hasAccess().

hasAccessFlags(doc, user=None, flags=None)[source]

See the documentation of AccessControlledModel.hasAccessFlags, which this wraps.

load(id, level=2, user=None, objectId=True, force=False, fields=None, exc=False)[source]

Calls Model.load on the current item, and then attempts to load the resourceParent which the user must have access to in order to load this model.

Takes the same parameters as girder.models.model_base.AccessControlledModel.load().

prefixSearch(query, user=None, filters=None, limit=0, offset=0, sort=None, fields=None, level=0, prefixSearchFields=None)[source]

Custom override of Model.prefixSearch to also force permission-based filtering. The parameters are the same as Model.prefixSearch.

Parameters:
requireAccess(doc, user=None, level=0)[source]

This wrapper just provides a standard way of throwing an access denied exception if the access check fails.

requireAccessFlags(doc, user=None, flags=None)[source]

See the documentation of AccessControlledModel.requireAccessFlags, which this wraps.

girder.utility.assetstore_utilities.fileIndexFields()[source]

This will return a set of all required index fields from all of the different assetstore types.

girder.utility.assetstore_utilities.getAssetstoreAdapter(assetstore, instance=True)[source]

This is a factory method that will return the appropriate assetstore adapter for the specified assetstore. The returned object will conform to the interface of the AbstractAssetstoreAdapter.

Parameters:
  • assetstore (dict) – The assetstore document used to instantiate the adapter.
  • instance (bool) – Whether to return an instance of the adapter or the class. If you are performing validation, set this to False to avoid throwing unwanted exceptions during instantiation.
Returns:

An adapter descending from AbstractAssetstoreAdapter

girder.utility.assetstore_utilities.setAssetstoreAdapter(storeType, cls)[source]

This updates the internal assetstore adapter table with either a new entry, or a modification to an existing entry. Subsequent calls to getAssetstoreAdapter() will return the modified class (or instance thereof), allowing for dynamic updating of assetstore behavior at runtime.

Parameters:
  • storeType (enum | any) – The assetstore type to create/modify.
  • cls (AbstractAssetstoreAdapter) – The new assetstore adapter class to install in the table. This should be an adapter descending from AbstractAssetstoreAdapter.
class girder.utility.filesystem_assetstore_adapter.FilesystemAssetstoreAdapter(assetstore)[source]

This assetstore type stores files on the filesystem underneath a root directory. Files are named by their SHA-512 hash, which avoids duplication of file content.

Parameters:assetstore (dict) – The assetstore to act on.
cancelUpload(upload)[source]

Delete the temporary files associated with a given upload.

capacityInfo()[source]

For filesystem assetstores, we just need to report the free and total space on the filesystem where the assetstore lives.

deleteFile(file)[source]

Deletes the file from disk if it is the only File in this assetstore with the given sha512. Imported files are not actually deleted.

downloadFile(file, offset=0, headers=True, endByte=None, contentDisposition=None, extraParameters=None, **kwargs)[source]

Returns a generator function that will be used to stream the file from disk to the response.

static fileIndexFields()[source]

File documents should have an index on their sha512 field, as well as whether or not they are imported.

finalizeUpload(upload, file)[source]

Moves the file into its permanent content-addressed location within the assetstore. Directory hierarchy yields 256^2 buckets.

findInvalidFiles(progress=<girder.utility.progress.ProgressContext object>, filters=None, checkSize=True, **kwargs)[source]

Goes through every file in this assetstore and finds those whose underlying data is missing or invalid. This is a generator function – for each invalid file found, a dictionary is yielded to the caller that contains the file, its absolute path on disk, and a reason for invalid, e.g. “missing” or “size”.

Parameters:
  • progress (girder.utility.progress.ProgressContext) – Pass a progress context to record progress.
  • filters (dict or None) – Additional query dictionary to restrict the search for files. There is no need to set the assetstoreId in the filters, since that is done automatically.
  • checkSize (bool) – Whether to make sure the size of the underlying data matches the size of the file.
fullPath(file)[source]

Utility method for constructing the full (absolute) path to the given file.

getLocalFilePath(file)[source]

Return a path to the file on the local file system.

Parameters:file – The file document.
Returns:a local path to the file or None if no such path is known.
importData(parent, parentType, params, progress, user, leafFoldersAsItems)[source]

Assetstores that are capable of importing pre-existing data from the underlying storage medium can implement this method.

Parameters:
  • parent – The parent object to import into.
  • parentType (str) – The model type of the parent object (folder, user, or collection).
  • params (dict) – Additional parameters required for the import process. Typically includes an importPath field representing a root path on the underlying storage medium.
  • progress (girder.utility.progress.ProgressContext) – Object on which to record progress if possible.
  • user (dict or None) – The Girder user performing the import.
importFile(item, path, user, name=None, mimeType=None, **kwargs)[source]

Import a single file from the filesystem into the assetstore.

Parameters:
  • item (dict) – The parent item for the file.
  • path (str) – The path on the local filesystem.
  • user (dict) – The user to list as the creator of the file.
  • name (str) – Name for the file. Defaults to the basename of path.
  • mimeType (str) – MIME type of the file if known.
Returns:

The file document that was created.

initUpload(upload)[source]

Generates a temporary file and sets its location in the upload document as tempFile. This is the file that the chunks will be appended to.

requestOffset(upload)[source]

Returns the size of the temp file.

uploadChunk(upload, chunk)[source]

Appends the chunk into the temporary file.

static validateInfo(doc)[source]

Makes sure the root field is a valid absolute path and is writeable. It also conveniently update the root field replacing the initial component by the user home directory running the server if it matches ~ or ~user.

class girder.utility.gridfs_assetstore_adapter.GridFsAssetstoreAdapter(assetstore)[source]

This assetstore type stores files within MongoDB using the GridFS data model.

cancelUpload(upload)[source]

Delete all of the chunks associated with a given upload.

deleteFile(file)[source]

Delete all of the chunks in the collection that correspond to the given file.

downloadFile(file, offset=0, headers=True, endByte=None, contentDisposition=None, extraParameters=None, **kwargs)[source]

Returns a generator function that will be used to stream the file from the database to the response.

static fileIndexFields()[source]

Default behavior is that no additional file fields need to be indexed within the database.

finalizeUpload(upload, file)[source]

Grab the final state of the checksum and set it on the file object, and write the generated UUID into the file itself.

initUpload(upload)[source]

Creates a UUID that will be used to uniquely link each chunk to

requestOffset(upload)[source]

The offset will be the CHUNK_SIZE * total number of chunks in the database for this file. We return the max of that and the received count because in testing mode we are uploading chunks that are smaller than the CHUNK_SIZE, which in practice will not work.

uploadChunk(upload, chunk)[source]

Stores the uploaded chunk in fixed-sized pieces in the chunks collection of this assetstore’s database.

static validateInfo(doc)[source]

Validate the assetstore – make sure we can connect to it and that the necessary indexes are set up.

girder.utility.mail_utils.addTemplateDirectory(dir, prepend=False)[source]

Adds a directory to the search path for mail templates. This is useful for plugins that have their own set of mail templates.

Parameters:
  • dir (str) – The directory to add to the template lookup path.
  • prepend (bool) – If True, adds this directory at the beginning of the path so that it will override any existing templates with the same name. Otherwise appends to the end of the lookup path.
girder.utility.mail_utils.getEmailUrlPrefix()[source]

Return the URL prefix for links back to the server. This is the link to the server root, so Girder-level path information and any query parameters or fragment value should be appended to this value.

girder.utility.mail_utils.renderTemplate(name, params=None)[source]

Renders one of the HTML mail templates located in girder/mail_templates.

Parameters:
  • name – The name of the file inside girder/mail_templates to render.
  • params (dict) – The parameters to pass when rendering the template.
Returns:

The rendered template as a string of HTML.

girder.utility.mail_utils.sendMail(subject, text, to, bcc=None)[source]

Send an email asynchronously.

Parameters:
  • subject (str) – The subject line of the email.
  • text (str) – The body of the email.
  • to (list) – The list of recipient email addresses.
  • bcc (list or None) – Recipient email addresses that should be specified using the Bcc header.
girder.utility.mail_utils.sendMailIndividually(subject, text, to)[source]

Send emails asynchronously to all recipients individually.

girder.utility.mail_utils.sendMailSync(subject, text, to, bcc=None)[source]

Send an email synchronously.

girder.utility.mail_utils.sendMailToAdmins(subject, text)[source]

Send an email asynchronously to site admins.

girder.utility.mail_utils.validateEmailAddress(address)[source]

Determines whether a string is a valid email address.

This implements the grammar from 4.10.5.1.5 of the HTML Standard.

Parameters:address (str) – The string to test.
Return type:bool
class girder.utility.model_importer.ModelImporter[source]

Any class that wants to have convenient model importing semantics should extend/mixin this class.

static model(model, plugin='_core')[source]

Call this to get the instance of the specified model. It will be lazy-instantiated.

Parameters:
  • model (string) – The name of the model to get. This must have been registered using the registerModel() method.
  • plugin (str) – Plugin identifier (if this is a plugin model).
Returns:

The instantiated model, which is a singleton.

static registerModel(model, cls, plugin='_core')[source]

Use this method to register a model class to a name. Using this, it can be referenced via the model method of this class.

Parameters:

This module contains utility methods for parsing girder path strings.

girder.utility.path.decode(token)[source]

Un-escape special characters in a token from a path representation.

Parameters:token (str) – The token to decode
Returns:The decoded string
Return type:str
girder.utility.path.encode(token)[source]

Escape special characters in a token for path representation.

Parameters:token (str) – The token to encode
Returns:The encoded string
Return type:str
girder.utility.path.getResourceName(type, doc)[source]

Get the name of a resource that can be put in a path,

Parameters:
  • type (str) – the resource model type.
  • doc (dict) – the resource document.
Returns:

the name of the resource.

Return type:

str

girder.utility.path.getResourcePath(type, doc, user=None, force=False)[source]

Get the path for a resource.

Parameters:
  • type (str) – the resource model type.
  • doc (dict) – the resource document.
  • user (dict or None) – user with correct privileges to access path
  • force (bool) – if True, don’t validate the access.
Returns:

the path to the resource.

Return type:

str

girder.utility.path.join(tokens)[source]

Join a list of tokens into an encoded path string.

Parameters:tokens – A list of tokens
Returns:The encoded path string
Return type:str
girder.utility.path.lookUpPath(path, user=None, filter=True, force=False)[source]

Look up a resource in the data hierarchy by path.

Parameters:
  • path – path of the resource
  • user – user with correct privileges to access path
  • filter (bool) – Whether the returned model should be filtered.
  • force (bool) – if True, don’t validate the access.
girder.utility.path.lookUpToken(token, parentType, parent)[source]

Find a particular child resource by name or throw an exception.

Parameters:
  • token – the name of the child resource to find
  • parentType – the type of the parent to search
  • parent – the parent resource
Returns:

the child resource

girder.utility.path.split(path)[source]

Split an encoded path string into decoded tokens.

Parameters:path (str) – An encoded path string
Returns:A list of decoded tokens
Return type:list
class girder.utility.progress.ProgressContext(on, interval=0.5, **kwargs)[source]

This class is a context manager that can be used to update progress in a way that rate-limits writes to the database and guarantees a flush when the context is exited. This is a no-op if “on” is set to False, which is meant as a convenience for callers. Any additional kwargs passed to this constructor are passed through to the initProgress method of the notification model.

Parameters:
  • on (bool) – Whether to record progress.
  • interval (int or float) – Minimum time interval at which to write updates to the database, in seconds.
  • user (dict) – The user creating this progress.
  • title (str) – The title for the task being tracked.
update(force=False, **kwargs)[source]

Update the underlying progress record. This will only actually save to the database if at least self.interval seconds have passed since the last time the record was written to the database. Accepts the same kwargs as Notification.updateProgress.

Parameters:force (bool) – Whether we should force the write to the database. Use only in cases where progress may be indeterminate for a long time.
girder.utility.progress.setResponseTimeLimit(duration=600, onlyExtend=True)[source]

If we are currently within a cherrypy response, extend the time limit. By default, cherrypy (version < 12.0) responses will timeout after 300 seconds, so any activity which can take longer should call this function.

Note that for cherrypy responses that include streaming generator functions, such as downloads, the timeout is only relevant until the first yield is reached. As such, long running generator responses do not generally need to call this function.

@deprecated - remove this function once we pin to CherryPy >= 12.0

Parameters:
  • duration – additional duration in seconds to allow for the response.
  • onlyExtend – if True, only ever increase the timeout. If False, the new duration always replaces the old one.
class girder.utility.s3_assetstore_adapter.S3AssetstoreAdapter(assetstore)[source]

This assetstore type stores files on S3. It is responsible for generating HMAC-signed messages that authorize the client to communicate directly with the S3 server where the files are stored.

cancelUpload(upload)[source]

Delete the temporary files associated with a given upload.

deleteFile(file)[source]

We want to queue up files to be deleted asynchronously since it requires an external HTTP request per file in order to delete them, and we don’t want to wait on that.

Files that were imported as pre-existing data will not actually be deleted from S3, only their references in Girder will be deleted.

downloadFile(file, offset=0, headers=True, endByte=None, contentDisposition=None, extraParameters=None, **kwargs)[source]

When downloading a single file with HTTP, we redirect to S3. Otherwise, e.g. when downloading as part of a zip stream, we connect to S3 and pipe the bytes from S3 through the server to the user agent.

fileUpdated(file)[source]

On file update, if the name or the MIME type changed, we must update them accordingly on the S3 key so that the file downloads with the correct name and content type.

finalizeUpload(upload, file)[source]

Call this once the last chunk has been processed. This method does not need to delete the upload document as that will be deleted by the caller afterward. This method may augment the File document, and must return the File document.

Parameters:
  • upload (dict) – The upload document.
  • file (dict) – The file document that was created.
Returns:

The file document with optional modifications.

importData(parent, parentType, params, progress, user, **kwargs)[source]

Assetstores that are capable of importing pre-existing data from the underlying storage medium can implement this method.

Parameters:
  • parent – The parent object to import into.
  • parentType (str) – The model type of the parent object (folder, user, or collection).
  • params (dict) – Additional parameters required for the import process. Typically includes an importPath field representing a root path on the underlying storage medium.
  • progress (girder.utility.progress.ProgressContext) – Object on which to record progress if possible.
  • user (dict or None) – The Girder user performing the import.
initUpload(upload)[source]

Build the request required to initiate an authorized upload to S3.

requestOffset(upload)[source]

Request the offset for resuming an interrupted upload. Default behavior simply returns the ‘received’ field of the upload document. This method exists because in some cases, such as when the server crashes, it’s possible that the received field is not accurate, so adapters may implement this to provide the actual next byte required.

untrackedUploads(knownUploads=None, delete=False)[source]

List and optionally discard uploads that are in the assetstore but not in the known list.

Parameters:
  • knownUploads (list) – a list of upload dictionaries of all known incomplete uploads.
  • delete (bool) – if True, delete any unknown uploads.
Returns:

a list of unknown uploads.

uploadChunk(upload, chunk)[source]

Rather than processing actual bytes of the chunk, this will generate the signature required to upload the chunk. Clients that do not support direct-to-S3 upload can pass the chunk via the request body as with other assetstores, and Girder will proxy the data through to S3.

Parameters:chunk – This should be a JSON string containing the chunk number and S3 upload ID. If a normal chunk file-like object is passed, we will send the data to S3.
static validateInfo(doc)[source]

Makes sure the root field is a valid absolute path and is writeable.

girder.utility.s3_assetstore_adapter.makeBotoConnectParams(accessKeyId, secret, service=None, region=None, inferCredentials=False)[source]

Create a dictionary of values to pass to the boto connect_s3 function.

Parameters:
  • accessKeyId – the S3 access key ID
  • secret – the S3 secret key
  • service – alternate service URL
  • region – the AWS region name of the bucket (if not “us-east-1”)
  • inferCredentials – Whether or not Boto should infer the credentials without directly using accessKeyId and secret.
Returns:

boto connection parameter dictionary.

girder.utility.search.addSearchMode(mode, handler)[source]

Register a search mode.

New searches made for the registered mode will call the handler function. The handler function must take parameters: query, types, user, level, limit, offset, and return the search results.

Parameters:
  • mode (str) – A search mode identifier.
  • handler (function) – A search mode handler function.
girder.utility.search.getSearchModeHandler(mode)[source]

Get the handler function for a search mode

Parameters:mode (str) – A search mode identifier.
Returns:A search mode handler function, or None.
Return type:function or None
girder.utility.search.removeSearchMode(mode)[source]

Remove a search mode.

This will fail gracefully (returning False) if no search mode mode was registered.

Parameters:mode (str) – A search mode identifier.
Returns:Whether the search mode was actually removed.
Return type:bool
girder.utility.server.configureServer(mode=None, plugins=None, curConfig=None)[source]

Function to setup the cherrypy server. It configures it, but does not actually start it.

Parameters:
  • mode (string) – The server mode to start in.
  • plugins – If you wish to start the server with a custom set of plugins, pass this as a list of plugins to load. Otherwise, all installed plugins will be loaded.
  • curConfig – The configuration dictionary to update.
girder.utility.server.loadRouteTable(reconcileRoutes=False)[source]

Retrieves the route table from Girder and reconciles the state of it with the current application state.

Reconciliation ensures that every enabled plugin has a route by assigning default routes for plugins that have none, such as newly-enabled plugins.

Returns:The non empty routes (as a dict of name -> route) to be mounted by CherryPy during Girder’s setup phase.
girder.utility.server.setup(mode=None, plugins=None, curConfig=None)[source]

Configure and mount the Girder server and plugins under the appropriate routes.

See ROUTE_TABLE setting.

Parameters:
  • mode (string) – The server mode to start in.
  • plugins – List of plugins to enable.
  • curConfig – The config object to update.
girder.utility.server.staticFile(path, contentType=None)[source]

Helper function to serve a static file. This should be bound as the route object, i.e. info[‘serverRoot’].route_name = staticFile(‘…’)

Parameters:
  • path (str) – The path of the static file to serve from this route.
  • contentType – The MIME type of the static file. If set to None, the content type wll be guessed by the file extension of the ‘path’ argument.
class girder.utility.setting_utilities.default(key)[source]

Create a decorator indicating that the wrapped function is responsible for providing the default value for the given key or set of keys.

Parameters:key (str or iterable of str) – The key(s) that this function validates.
girder.utility.setting_utilities.getDefaultFunction(key)[source]

Retrieve the default value function for the given key. Returns None if none is registered.

girder.utility.setting_utilities.getValidator(key)[source]

Retrieve the validator function for the given key. Returns None if none is registered.

girder.utility.setting_utilities.registerDefaultFunction(key, fn)[source]

Register a default value function for a given setting key.

Parameters:
  • key (str) – The setting key.
  • fn (callable) – The function that will return the default value for this key.
girder.utility.setting_utilities.registerValidator(key, fn, replace=False)[source]

Register a validator for a given setting key.

Parameters:
  • key (str) – The setting key.
  • fn (callable) – The function that will validate this key.
  • replace (bool) – If a validator already exists for this key, set this to True to replace the existing validator. The default is to add the new validator in addition to running the old validation function.
class girder.utility.setting_utilities.validator(key, replace=False)[source]

Create a decorator indicating that the wrapped function is responsible for validating the given key or set of keys. For example,

>>> @validator('my_plugin.setting_key')
>>> def validateMySetting(doc):
>>>     if not doc['value']:
>>>         raise ValidationException('This key must not be empty.')
Parameters:
  • key (str or iterable of str) – The key(s) that this function validates.
  • replace (bool) – If a validator already exists for this key, set this to True to replace the existing validator. The default is to add the new validator in addition to running the old validation function.
class girder.utility.system.StatusMonitor[source]

Register the status of each thread.

unregister()[source]

Unregister the current thread.

girder.utility.system.formatSize(sizeBytes)[source]

Format a size in bytes into a human-readable string with metric unit prefixes.

Parameters:sizeBytes – the size in bytes to format.
Returns:the formatted size string.
girder.utility.system.getStatus(mode='basic', user=None)[source]

Get a dictionary of status information regarding the Girder server.

Parameters:
  • mode – ‘basic’ returns values available to any anonymous user. ‘quick’ returns only values that are cheap to acquire. ‘slow’ provides all of that information and adds additional
  • user – a user record. Must have admin access to get anything other than basic mode.
Returns:

a status dictionary.

class girder.utility.webroot.Webroot(templatePath=None)[source]

The webroot endpoint simply serves the main index HTML file.

class girder.utility.webroot.WebrootBase(templatePath)[source]

Serves a template file in response to GET requests.

This will typically be the base class of any non-API endpoints.

setTemplatePath(templatePath)[source]

Set the path to a template file to render instead of the default template.

The default template remains available so that custom templates can inherit from it. To do so, save the default template filename from the templateFilename attribute before calling this function, pass it as a variable to the custom template using updateHtmlVars(), and reference that variable in an <%inherit> directive like:

<%inherit file=”${context.get(‘defaultTemplateFilename’)}”/>
updateHtmlVars(vars)[source]

If any of the variables in the index html need to change, call this with the updated set of variables to render the template with.

This module is essentially a subset of the python zipfile module that has been modified to allow it to read arbitrary streams (using generators) as input, instead of only accepting files. It also streams the output using generators.

Example of creating and consuming a streaming zip:

zip = ziputil.ZipGenerator(‘TopLevelFolder’)

for data in zip.addFile(lambda: ‘hello world’, ‘hello.txt’):
yield data

yield zip.footer()

class girder.utility.ziputil.ZipGenerator(rootPath='', compression=0)[source]

This class can be used to create a streaming zip file that consumes from one generator and writes to another.

addFile(generator, path)[source]

Generates data to add a file at the given path in the archive. :param generator: Generator function that will yield the file contents. :type generator: function :param path: The path within the archive for this entry. :type path: str

footer()[source]

Once all zip files have been added with addFile, you must call this to get the footer of the archive.

Constants

Constants should be defined here.

class girder.constants.AccessType[source]

Represents the level of access granted to a user or group on an AccessControlledModel. Having a higher access level on a resource also confers all of the privileges of the lower levels.

Semantically, READ access on a resource means that the user can see all the information pertaining to the resource, but cannot modify it.

WRITE access usually means the user can modify aspects of the resource.

ADMIN access confers total control; the user can delete the resource and also manage permissions for other users on it.

class girder.constants.AssetstoreType[source]

All possible assetstore implementation types.

class girder.constants.CoreEventHandler[source]

This enum represents handler identifier strings for core event handlers. If you wish to unbind a core event handler, use one of these as the handlerName argument. Unbinding core event handlers can be used to disable certain default functionalities.

girder.constants.STATIC_PREFIX = '/home/docs/checkouts/readthedocs.org/user_builds/girder/envs/v3.0.4/share/girder'

The local directory containing the static content.

class girder.constants.TerminalColor[source]

Provides a set of values that can be used to color text in the terminal.

class girder.constants.TokenScope[source]

Constants for core token scope strings. Token scopes must not contain spaces, since many services accept scope lists as a space-separated list of strings.

classmethod describeScope(scopeId, name, description, admin=False)[source]

Register a description of a scope.

Parameters:
  • scopeId (str) – The unique identifier string for the scope.
  • name (str) – A short human readable name for the scope.
  • description (str) – A more complete description of the scope.
  • admin (bool) – If this scope only applies to admin users, set to True.
girder.constants.registerAccessFlag(key, name, description=None, admin=False)[source]

Register a new access flag in the set of ACCESS_FLAGS available on data in the hierarchy. These are boolean switches that can be used to control access to specific functionality on specific resoruces.

Parameters:
  • key (str) – The unique identifier for this access flag.
  • name (str) – Human readable name for this permission (displayed in UI).
  • description (str) – Human readable longer description for the flag.
  • admin – Set this to True to only allow site admin users to set this flag. If True, the flag will only appear in the list for site admins. This can be useful for flags with security considerations.

Events

This module contains the Girder events framework. It maintains a global mapping of events to listeners, and contains utilities for callers to handle or trigger events identified by a name.

Listeners should bind to events by calling:

girder.events.bind('event.name', 'my.handler', handlerFunction)

And events should be fired in one of two ways; if the event should be handled synchronously, fire it with:

girder.events.trigger('event.name', info)

And if the event should be handled asynchronously, use:

girder.events.daemon.trigger('event.name', info, callback)

For obvious reasons, the asynchronous method does not return a value to the caller. Instead, the caller may optionally pass the callback argument as a function to be called when the task is finished. That callback function will receive the Event object as its only argument.

class girder.events.AsyncEventsThread[source]

This class is used to execute the pipeline for events asynchronously. This should not be invoked directly by callers; instead, they should use girder.events.daemon.trigger().

run()[source]

Loops over all queued events. If the queue is empty, this thread gets put to sleep until someone calls trigger() on it with a new event to dispatch.

stop()[source]

Gracefully stops this thread. Will finish the currently processing event before stopping.

trigger(eventName=None, info=None, callback=None)[source]

Adds a new event on the queue to trigger asynchronously.

Parameters:
  • eventName – The event name to pass to the girder.events.trigger
  • info – The info object to pass to girder.events.trigger
  • callback – Optional callable to be called upon completion of all bound event handlers. It takes one argument, which is the event object itself.
class girder.events.Event(name, info, asynchronous=False)[source]

An Event object is created when an event is triggered. It is passed to each of the listeners of the event, which have a chance to add information to the event, and also optionally stop the event from being further propagated to other listeners, and also optionally instruct the caller that it should not execute its default behavior.

addResponse(response)[source]

Listeners that wish to return data back to the caller who triggered this event should call this to append their own response to the event.

Parameters:response – The response value, which can be any type.
preventDefault()[source]

This can be used to instruct the triggerer of the event that the default behavior it would normally perform should not be performed. The semantics of this action are specific to the context of the event being handled, but a common use of this method is for a plugin to provide an alternate behavior that will replace the normal way the event is handled by the core system.

stopPropagation()[source]

Listeners should call this on the event they were passed in order to stop any other listeners to the event from being executed.

class girder.events.ForegroundEventsDaemon[source]

This is the implementation used for girder.events.daemon if the config file chooses to disable using the background thread for the daemon. It executes all bound handlers in the current thread, and provides no-op start() and stop() implementations to remain compatible with the API of AsyncEventsThread.

girder.events.bind(eventName, handlerName, handler)[source]

Bind a listener (handler) to the event identified by eventName. It is convention that plugins will use their own name as the handlerName, so that the trigger() caller can see which plugin(s) responded to the event.

Parameters:
  • eventName (str) – The name that identifies the event.
  • handlerName (str) – The name that identifies the handler calling bind().
  • handler (function) – The function that will be called when the event is fired. It must accept a single argument, which is the Event that was created by trigger(). This function should not return a value; any data that it needs to pass back to the triggerer should be passed via the addResponse() method of the Event.
girder.events.bound(eventName, handlerName, handler)[source]

A context manager to temporarily bind an event handler within its scope.

Parameters are the same as those to girder.events.bind().

girder.events.trigger(eventName, info=None, pre=None, asynchronous=False, daemon=False)[source]

Fire an event with the given name. All listeners bound on that name will be called until they are exhausted or one of the handlers calls the stopPropagation() method on the event.

Parameters:
  • eventName (str) – The name that identifies the event.
  • info – The info argument to pass to the handler function. The type of this argument is opaque, and can be anything.
  • pre (function or None) – A function that will be executed prior to the handler being executed. It will receive a dict with a “handler” key, (the function), “info” key (the info arg to this function), and “eventName” and “handlerName” values.
  • asynchronous (bool) – Whether this event is executing on the background thread (True) or on the request thread (False).
  • daemon (bool) – Whether this was triggered via girder.events.daemon.
girder.events.unbind(eventName, handlerName)[source]

Removes the binding between the event and the given listener.

Parameters:
  • eventName (str) – The name that identifies the event.
  • handlerName (str) – The name that identifies the handler calling bind().
girder.events.unbindAll()[source]

Clears the entire event map. All bound listeners will be unbound.

Warning

This will also disable internal event listeners, which are necessary for normal Girder functionality. This function should generally never be called outside of testing.

Exceptions

exception girder.exceptions.AccessException(message, extra=None)[source]

Represents denial of access to a resource.

exception girder.exceptions.FilePathException(message='No assetstore adapter', identifier=None)[source]

Thrown when a file path is requested and cannot be returned.

exception girder.exceptions.GirderBaseException[source]

A class from which all Girder exceptions are based.

exception girder.exceptions.GirderException(message, identifier=None)[source]

Represents a general exception that might occur in regular use. From the user perspective, these are failures, but not catastrophic ones. An identifier can be passed, which allows receivers to check the exception without relying on the text of the message. It is recommended that identifiers are a dot-separated string consisting of the originating python module and a distinct error. For example, ‘girder.model.assetstore.no-current-assetstore’.

exception girder.exceptions.NoAssetstoreAdapter(message='No assetstore adapter')[source]

Raised when no assetstore adapter is available.

exception girder.exceptions.ResourcePathNotFound(message, field=None)[source]

A special case of ValidationException representing the case when the resource at a given path does not exist.

exception girder.exceptions.RestException(message, code=400, extra=None)[source]

Throw a RestException in the case of any sort of incorrect request (i.e. user/client error). Login and permission failures should set a 403 code; almost all other validation errors should use status 400, which is the default.

exception girder.exceptions.ValidationException(message, field=None)[source]

Represents validation failure in the model layer. Raise this with a message and an optional field property. If one of these is thrown in the model during a REST request, it will respond as a 400 status.

Logging

class girder.LogFormatter(fmt=None, datefmt=None, style='%')[source]

Custom formatter that adds useful information about the request to the logs when an exception happens. Cherrypy access logs are passed through without change.

format(record, *args, **kwargs)[source]

Format the specified record as text.

The record’s attribute dictionary is used as the operand to a string formatting operation which yields the returned string. Before formatting the dictionary, a couple of preparatory steps are carried out. The message attribute of the record is computed using LogRecord.getMessage(). If the formatting string uses the time (as determined by a call to usesTime(), formatTime() is called to format the event time. If there is exception information, it is formatted using formatException() and appended to the message.

formatException(exc)[source]

Format and return the specified exception information as a string.

This default implementation just uses traceback.print_exception()

class girder.LogLevelFilter(min, max)[source]

Filter log records based on whether they are between a min and max level.

class girder.StreamToLogger(stream, logger, level)[source]

Redirect a file-like stream to a logger.

girder.getLogPaths()[source]

Return the paths to the error and info log files. These are returned as a dict with “error” and “info” keys that point to the respective file, as well as a “root” key pointing to the log root directory.

girder.logprint(*args, **kwargs)[source]

Send a message to both stdout and the appropriate logs. This behaves like Python3’s print statement, plus takes additional named parameters:

Parameters:
  • level – the log level. This determines which log handlers will store the log message. The log is always sent to stdout.
  • color – one of the constants.TerminalColor values or None.
  • exc_info – None to not print exception information. True for the last exception, or a tuple of exception information.

Plugins

This module defines functions for registering, loading, and querying girder plugins.

class girder.plugin.GirderPlugin(entrypoint)[source]

This is a base class for describing a girder plugin. A plugin is registered by adding an entrypoint under the namespace girder.plugin. This entrypoint should return a class derived from this class.

Example ::

class Cats(GirderPlugin):

def load(self, info):

# load dependent plugins girder.plugin.getPlugin(‘pets’).load(info)

import rest # register new rest endpoints, etc.

CLIENT_SOURCE_PATH = None

The path of the plugin’s web client source code. This path is given relative to the python package. This property is used to link the web client source into the staging area while building in development mode. When this value is None it indicates there is no web client component.

DISPLAY_NAME = None

This is the named displayed to users on the plugin page. Unlike the entrypoint name used internally, this name can be an arbitrary string.

description

Return the plugin description defaulting to the classes docstring.

displayName

Return a user-friendly plugin name (defaults to the entrypoint name).

loaded

Return true if this plugin has been loaded.

name

Return the plugin name defaulting to the entrypoint name.

npmPackages()[source]

Return a dictionary of npm packages -> versions for building the plugin client.

By default, this dictionary will be assembled from the CLIENT_SOURCE_PATH property by inspecting the package.json file in the indicated directory. Plugins can override this method customize the behaivor for advanced usage.

url

Return a url reference to the plugin (usually a readthedocs page).

version

Return the version of the plugin automatically determined from setup.py.

girder.plugin.allPlugins()[source]

Return a list of all detected plugins.

girder.plugin.getPlugin(name)[source]

Return a plugin configuration object or None if the plugin is not found.

girder.plugin.loadedPlugins()[source]

Return a list of successfully loaded plugins.

girder.plugin.registerPluginWebroot(webroot, name)[source]

Adds a webroot to the global registry for plugins based on the plugin name.

Python Client

See Python Client and Girder CLI

Web client

Documentation for Girder’s web client library is built and hosted by esdoc and can be found here.