Tethys Quotas API

Last Updated: March 2019

Tethys Quotas allows portal admins to set-up, manage and enforce storage, compute-time and other resource quotas on users, apps and other entities. The portal admins can declare a quota's defaults and state (i.e. active/inactive) and change it at anytime to meet the needs of the portal. They can also set entity specific quotas if the need arises (an entity can be a Tethys App or a User). For example, if there is a portal default quota on user workspace storage of 5 GB but there is a specific user who needs double that to complete their workflows, an admin can go into that user's settings and change their user-specific quota to 10 GB.

Built-in Quotas

Custom quotas can be created, but by default Tethys includes two built-in quotas: User Workspace Quotas and App Workspace Quotas.

Tip

See Creating Custom Quotas for information on how to remove quotas and/or add custom quotas.

Admin Pages

For information on how to manage the built-in quotas see Manage App Storage and Manage User Storage

ResourceQuotaHandler

class tethys_quotas.handlers.base.ResourceQuotaHandler(entity, *args, **kwargs)

Defines one or more ResourceQuotas. Also houses logic to check quota.

codename

unique codename for quota, used to look up specific quotas easily (e.g. ‘workspace_storage’).

Type:

str

name

human friendly name of resource quota (e.g.: "Workspace Storage").

Type:

str

description

more detailed description of the quota resource (e.g.: "Storage limit on workspaces.").

Type:

str

default

default value (e.g. 10).

Type:

int

units

units of the quota (e.g.: "GB").

Type:

str

help

help text to display when quota is exceeded.

Type:

str

applies_to

list of dot-paths to the entities to which this quota will apply. Any of “django.contrib.auth.models.User” or “tethys_apps.models.TethysApp”.

Type:

list<str>

__init__

constructor

Type:

entity, args, kwargs

entity

the entity to evaluate.

Type:

auth.User or TethysApp

check()

Checks if entity use is at/below/above quota. Uses get_resource_available() to compute the current use of the resource.

Returns:

True if entity use is at or below quota and False if entity use is above the quota.

Return type:

Boolean

abstract get_current_use(*args, **kwargs)

Abstract method to be implemented by child classes. Should calculate/retrieve the current use of the resource (Int).

Creating Custom Quotas

To create a custom quota you will have to create a new quota handler class. Your new handler class will have to inherit from the ResourceQuotaHandler class. Follow the pattern in the built-in handler class, WorkspaceQuotaHandler (located at src/tethys_quotas/handlers/workspace.py).

Important

The abstract method, get_current_use, which needs to be overridden in any custom quota handler class, is essential as it holds the logic for what the quota is measuring (time, storage, etc.).

To load a custom quota, append the classpath to the RESOURCE_QUOTA_HANDLERS section of the portal_config.yml file (see snippet of portal_config.yml below).

# RESOURCE QUOTAS TO INSTALL
RESOURCE_QUOTA_HANDLERS:
  - tethys_quotas.handlers.workspace.WorkspaceQuotaHandler

Figure 1. portal_config.yml file showing the RESOURCE_QUOTA_HANDLERS section.

Note

Delete or comment out classpath strings in the portal_config.yml file to remove certain quota types from the portal.

Enforcing Quotas

Using the @app_workspace or @user_workspace decorators will automatically enforce the built in workspace quotas. To enforce a custom quota, the @enforce_quota decorator must be used. Within the decorator initialization, pass in the respective codename of the quota you wish to enforce.

# Import the enforce_quota decorator
from tethys_sdk.quotas import enforce_quota
...

# Enforce the desired quota (taken from the Dam Inventory Tutorial)
@enforce_quota('user_dam_quota')
@permission_required('add_dams')
def add_dam(request):
    """
    Controller for the Add Dam page.
    """
    ...

Figure 2. Example usage of @enforce_quota, taken from the Dam Inventory Tutorial.

The @enforce_quota decorator will check to make sure the desired quota hasn't been met. If the quota has been met the user will be rerouted to an error page displaying the quota's help text.

Quotas API

A few helper functions have been added with Tethys Quotas to help developers integrate quotas within their apps.

get_quota

tethys_quotas.utilities.get_quota(entity, codename)

Gets the quota value

Parameters:

  • entity (User or TethysApp) -- the entity on which to perform quota check.

  • codename (str) -- codename of the Quota to get

Returns:

Dictionary with two keys: quota(int) - value of quota, units(str) - units of value, if applicable # noqa: E501

Return type:

dict (quota, units)

get_resource_available

tethys_quotas.utilities.get_resource_available(entity, codename)

Checks the quantity of resources remaining before the quota is met

Parameters:

  • entity (User or TethysApp) -- the entity on which to check.

  • codename (str) -- codename of the Quota to check

Returns:

Dictionary with two keys: resource_available(int) - amount of resource remaining, units(str) - units of amount, if applicable # noqa: E501

Return type:

dict (resource_available, units)

passes_quota

tethys_quotas.utilities.passes_quota(entity, codename, raise_on_false=True)

Checks to see if the quota has been exceeded or not

Parameters:

  • entity (User or TethysApp) -- the entity on which to check.

  • codename (str) -- codename of the Quota to check

  • raise_on_false (bool) -- raise error if entity does not pass quota.

Returns:

False if the entity has exceeded the quota, otherwise True.

Additional Resources

For more information and examples on how to use the Tethys Quotas API (including creating and enforcing custom quotas) see the Quotas Concepts tutorial.