Workspaces API

Last Updated: August 6, 2014

The Workspaces API makes it easy for you to create directories for storing files that your app operates on. This can be a tricky task for a web application, because of the multi-user, simultaneous-connection environment of the web. The Workspaces API provides a simple mechanism for creating and managing a global workspace for your app and individual workspaces for each user of your app to prevent unwanted overwrites and file lock conflicts.

Get a Workspace

The Workspaces API adds two methods to your app class, get_app_workspace() and get_user_workspace(), that can be used to retrieve with the global app workspace and the user workspaces, respectively. To use the Workspace API methods, import your app class from the app configuration file (app.py) and call the appropriate method on that class. Explanations of the methods and example usage follows.

get_app_workspace

classmethod TethysAppBase.get_app_workspace()

Get the file workspace (directory) for the app.

Returns:An object representing the workspace.
Return type:tethys_apps.base.TethysWorkspace

Example:

import os
from my_first_app.app import MyFirstApp as app

def a_controller(request):
    """
    Example controller that uses get_app_workspace() method.
    """
    # Retrieve the workspace
    app_workspace = app.get_app_workspace()
    new_file_path = os.path.join(app_workspace.path, 'new_file.txt')

    with open(new_file_path, 'w') as a_file:
        a_file.write('...')

    context = {}

    return render(request, 'my_first_app/template.html', context)

get_user_workspace

classmethod TethysAppBase.get_user_workspace(user)

Get the file workspace (directory) for the given User.

Parameters:user (User or HttpRequest) -- User or request object.
Returns:An object representing the workspace.
Return type:tethys_apps.base.TethysWorkspace

Example:

import os
from my_first_app.app import MyFirstApp as app

def a_controller(request):
    """
    Example controller that uses get_user_workspace() method.
    """
    # Retrieve the workspace
    user_workspace = app.get_user_workspace(request.user)
    new_file_path = os.path.join(user_workspace.path, 'new_file.txt')

    with open(new_file_path, 'w') as a_file:
        a_file.write('...')

    context = {}

    return render(request, 'my_first_app/template.html', context)

Working with Workspaces

The two methods described above return a TethysWorkspace object that contains the path to the workspace and several convenience methods for working with the workspace. An explanation of the TethysWorkspace object and examples of it's usage is provided below.

TethysWorkspace Objects

class tethys_apps.base.TethysWorkspace(path)

Defines objects that represent file workspaces (directories) for apps and users.

path

The absolute path to the workspace directory. Cannot be overwritten.

Type:str
clear(exclude=[], exclude_files=False, exclude_directories=False)

Remove all files and directories in the workspace.

Parameters:
  • exclude (iterable) -- A list or tuple of file and directory names to exclude from clearing operation.
  • exclude_files (bool) -- Excludes all files from clearing operation when True. Defaults to False.
  • exclude_directories (bool) -- Excludes all directories from clearing operation when True. Defaults to False.

Examples:

# Clear everything
workspace.clear()

# Clear directories only
workspace.clear(exclude_files=True)

# Clear files only
workspace.clear(exclude_directories=True)

# Clear all but specified files and directories
workspace.clear(exclude=['file1.txt', '/full/path/to/directory1', 'directory2', '/full/path/to/file2.txt'])
directories(full_path=False)

Return a list of directories that are in the workspace.

Parameters:full_path (bool) -- Returns list of directories with full path names when True. Defaults to False.
Returns:A list of directories in the workspace.
Return type:list

Examples:

# List directory names
workspace.directories()

# List full path directory names
workspace.directories(full_path=True)
files(full_path=False)

Return a list of files that are in the workspace.

Parameters:full_path (bool) -- Returns list of files with full path names when True. Defaults to False.
Returns:A list of files in the workspace.
Return type:list

Examples:

# List file names
workspace.files()

# List full path file names
workspace.files(full_path=True)
remove(item)

Remove a file or directory from the workspace.

Parameters:item (str) -- Name of the item to remove from the workspace.

Examples:

workspace.remove('file.txt')
workspace.remove('/full/path/to/file.txt')
workspace.remove('relative/path/to/file.txt')
workspace.remove('directory')
workspace.remove('/full/path/to/directory')
workspace.remove('relative/path/to/directory')

Note: Though you can specify relative paths, the remove() method will not allow you to back into other directories using "../" or similar notation. Futhermore, absolute paths given must contain the path of the workspace to be valid.

Centralize Workspaces

The Workspaces API includes a command, collectworkspaces, for moving all workspaces to a central location and symbolically linking them back to the app project directories. This is especially useful for production where the administrator may want to locate workspace content on a mounted drive to optimize storage. A brief explanation of how to use this command will follow. Refer to the Command Line Interface documentation for details about the collectworkspaces command.

Setting

To enable centralized workspaces create a directory for the workspaces and specify its path in the settings.py file using the TETHYS_WORKSPACES_ROOT setting.

TETHYS_WORKSPACES_ROOT = '/var/www/tethys/workspaces'

Command

Run the collectworkspaces command to automatically move all of the workspace directories to the TETHYS_WORKSPACES_ROOT directory and symbolically link them back. You will need to run this command each time you install new apps.

$ tethys manage collectworkspaces

Tip

A convenience command is provided called collectall that can be used to run both the collectstatic and the collectworkspaces commands:

$ tethys manage collectall