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 decorators, that can be used to retrieve with the global app workspace and the user workspaces, respectively. To use the Workspace API methods, import the appropriate method from tethys_sdk.workspaces. Explanations of the decorators and example usage follows.
@app_workspace¶
- workspace.app_workspace()¶
Decorator: Get the file workspace (directory) for the app.
- Returns
An object representing the workspace.
- Return type
Example:
import os from my_first_app.app import MyFirstApp as app from tethys_sdk.workspaces import app_workspace @app_workspace def a_controller(request, app_workspace): """ Example controller that uses @app_workspace() decorator. """ 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)
@user_workspace¶
- workspace.user_workspace()¶
Decorator: Get the file workspace (directory) for the given User.
- Returns
An object representing the workspace.
- Return type
Example:
import os from my_first_app.app import MyFirstApp as app from tethys_sdk.workspaces import user_workspace @user_workspace def a_controller(request, user_workspace): """ Example controller that uses @user_workspace() decorator. """ 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 portal_config.yml
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
Handling Workspace Clearing¶
Users and portal administrators are able to clear their user and app workspaces through pages in the Tethys Portal. The app class provides methods to allow the app developer to customize how the app handles clearing user/app workspaces. Override these methods in your app class to handle workspaces clearing appropriately in your app. When a workspace is cleared through the portal admin pages or user profile pages, the appropriate 'pre-delete' method is called, the workspace is cleared, and then the appropriate 'post-delete' method is called.
- classmethod TethysAppBase.pre_delete_app_workspace()
Override this method to pre-process the app workspace before it is emptied
- classmethod TethysAppBase.post_delete_app_workspace()
Override this method to post-process the app workspace after it is emptied
- classmethod TethysAppBase.pre_delete_user_workspace(user)
Override this method to pre-process a user's workspace before it is emptied
- Parameters
user (User, required) -- User that requested to clear their workspace
- classmethod TethysAppBase.post_delete_user_workspace(user)
Override this method to post-process a user's workspace after it is emptied
- Parameters
user (User, required) -- User that requested to clear their workspace