Projectroles API Documentation¶
This document contains API documentation for the projectroles
app. Included
are functionalities and classes intended to be used by other applications.
NOTE: When viewing this document in GitLab critical content will by default be missing. Please click “display source” if you want to read this in GitLab.
Plugins¶
SODAR plugin point definitions and helper functions for plugin retrieval are detailed in this section.
Plugin point definitions and plugin API for apps based on projectroles
-
class
projectroles.plugins.
BackendPluginPoint
[source]¶ Projectroles plugin point for registering backend apps
-
class
projectroles.plugins.
ProjectAppPluginPoint
[source]¶ Projectroles plugin point for registering project specific apps
-
get_extra_data_link
(_extra_data, _name)[source]¶ Return a link for the given timeline label that stars with
"extra:"
.
-
get_object
(model, uuid)[source]¶ Return object based on the model class and the object’s SODAR UUID.
Parameters: - model – Object model class
- uuid – sodar_uuid of the referred object
Returns: Model object or None if not found
Raise: NameError if model is not found
-
get_object_link
(model_str, uuid)[source]¶ Return the URL for referring to a object used by the app, along with a label to be shown to the user for linking.
Parameters: - model_str – Object class (string)
- uuid – sodar_uuid of the referred object
Returns: Dict or None if not found
-
get_project_list_value
(column_id, project)[source]¶ Return a value for the optional additional project list column specific to a project.
Parameters: - column_id – ID of the column (string)
- project – Project object
Returns: String (may contain HTML) or None
-
get_statistics
()[source]¶ Return app statistics as a dict. Should take the form of {id: {label, value, url (optional), description (optional)}}.
Returns: Dict
-
get_taskflow_sync_data
()[source]¶ Return data for synchronizing taskflow operations.
Returns: List of dicts or None.
-
search
(search_term, user, search_type=None, keywords=None)[source]¶ Return app items based on a search term, user, optional type and optional keywords.
Parameters: - search_term – String
- user – User object for user initiating the search
- search_type – String
- keywords – List (optional)
Returns: Dict
-
update_cache
(name=None, project=None, user=None)[source]¶ Update cached data for this app, limitable to item ID and/or project.
Parameters: - name – Item name to limit update to (string, optional)
- project – Project object to limit update to (optional)
- user – User object to denote user triggering the update (optional)
-
urls
= []¶ App URLs (will be included in settings by djangoplugins)
-
-
class
projectroles.plugins.
RemoteSiteAppPlugin
[source]¶ Site plugin for remote site and project management
-
app_permission
= 'userprofile.update_remote'¶ Required permission for displaying the app
-
description
= 'Management of remote SODAR sites and remote project access'¶ Description string
-
entry_point_url_id
= 'projectroles:remote_sites'¶ Entry point URL ID
-
icon
= 'cloud'¶ FontAwesome icon ID string
-
name
= 'remotesites'¶ Name (slug-safe, used in URLs)
-
title
= 'Remote Site Access'¶ Title (used in templates)
-
urls
= []¶ App URLs (will be included in settings by djangoplugins)
-
-
class
projectroles.plugins.
SiteAppPluginPoint
[source]¶ Projectroles plugin point for registering site-wide apps
-
projectroles.plugins.
change_plugin_status
(name, status, plugin_type='app')[source]¶ Change the status of a selected plugin in the database.
Parameters: - name – Plugin name (string)
- status – Status (int, see djangoplugins)
- plugin_type – Type of plugin (“app”, “backend” or “site”)
Raise: ValueError if plugin_type is invalid or plugin with name not found
-
projectroles.plugins.
get_active_plugins
(plugin_type='project_app')[source]¶ Return active plugins of a specific type.
Parameters: plugin_type – “project_app”, “site_app” or “backend” (string) Returns: List or None Raise: ValueError if plugin_type is not recognized
Models¶
Projectroles models are used by other apps for project access and metadata management as well as linking objects to projects.
-
class
projectroles.models.
AppSetting
(*args, **kwargs)[source]¶ Project and users settings value.
The settings are defined in the “app_settings” member in a SODAR project app’s plugin. The scope of each setting can be either “USER” or “PROJECT”, defined for each setting in app_settings. Project AND user-specific settings or settings which don’t belong to either are are currently not supported.
-
exception
DoesNotExist
¶
-
exception
MultipleObjectsReturned
¶
-
app_plugin
¶ App to which the setting belongs
-
name
¶ Name of the setting
-
project
¶ Project to which the setting belongs
-
sodar_uuid
¶ AppSetting SODAR UUID
-
type
¶ Type of the setting
-
user
¶ Project to which the setting belongs
-
value
¶ Value of the setting
-
exception
-
class
projectroles.models.
AppSettingManager
[source]¶ Manager for custom table-level AppSetting queries
-
get_setting_value
(app_name, setting_name, project=None, user=None)[source]¶ Return value of setting_name for app_name in project or for user.
Note that either project or user must be None but not both.
Parameters: - app_name – App plugin name (string)
- setting_name – Name of setting (string)
- project – Project object or pk
- user – User object or pk
Returns: Value (string)
Raise: AppSetting.DoesNotExist if setting is not found
-
-
class
projectroles.models.
Project
(*args, **kwargs)[source]¶ A SODAR project. Can have one parent category in case of nested projects. The project must be of a specific type, of which “CATEGORY” and “PROJECT” are currently implemented. “CATEGORY” projects are used as containers for other projects
-
exception
DoesNotExist
¶
-
exception
MultipleObjectsReturned
¶
-
description
¶ Short project description
-
has_role
(user, include_children=False)[source]¶ Return whether user has roles in Project. If include_children is True, return True if user has roles in ANY child project
-
parent
¶ Parent category if nested, otherwise null
-
readme
¶ Project README (optional, supports markdown)
-
sodar_uuid
¶ Project SODAR UUID
-
submit_status
¶ Status of project creation
-
title
¶ Project title
-
type
¶ Type of project (“CATEGORY”, “PROJECT”)
-
exception
-
class
projectroles.models.
ProjectInvite
(*args, **kwargs)[source]¶ Invite which is sent to a non-logged in user, determining their role in the project.
-
exception
DoesNotExist
¶
-
exception
MultipleObjectsReturned
¶
-
active
¶ Status of the invite (False if claimed or revoked)
-
date_created
¶ DateTime of invite creation
-
date_expire
¶ Expiration of invite as DateTime
-
email
¶ Email address of the person to be invited
-
issuer
¶ User who issued the invite
-
message
¶ Message to be included in the invite email (optional)
-
project
¶ Project to which the person is invited
-
role
¶ Role assigned to the person
-
secret
¶ Secret token provided to user with the invite
-
sodar_uuid
¶ ProjectInvite SODAR UUID
-
exception
-
class
projectroles.models.
ProjectManager
[source]¶ Manager for custom table-level Project queries
-
find
(search_term, keywords=None, project_type=None)[source]¶ Return projects with a partial match in full title or, including titles of parent Project objects, or the description of the current object. Restrict to project type if project_type is set. :param search_term: Search term (string) :param keywords: Optional search keywords as key/value pairs (dict) :param project_type: Project type or None :return: List of Project objects
-
-
class
projectroles.models.
ProjectUserTag
(*args, **kwargs)[source]¶ Tag assigned by a user to a project
-
exception
DoesNotExist
¶
-
exception
MultipleObjectsReturned
¶
-
name
¶ Name of tag to be assigned
-
project
¶ Project to which the tag is assigned
-
sodar_uuid
¶ ProjectUserTag SODAR UUID
-
user
¶ User for whom the tag is assigned
-
exception
-
class
projectroles.models.
RemoteProject
(*args, **kwargs)[source]¶ Remote project relation
-
exception
DoesNotExist
¶
-
exception
MultipleObjectsReturned
¶
-
date_access
¶ DateTime of last access from/to remote site
-
level
¶ Project access level
-
project
¶ Related project object (if created locally)
-
project_uuid
¶ Related project UUID
-
site
¶ Related remote SODAR site
-
sodar_uuid
¶ RemoteProject relation UUID (local)
-
exception
-
class
projectroles.models.
RemoteSite
(*args, **kwargs)[source]¶ Remote SODAR site
-
exception
DoesNotExist
¶
-
exception
MultipleObjectsReturned
¶
-
description
¶ Site description
-
mode
¶ Site mode
-
name
¶ Site name
-
secret
¶ Secret token used to connect to the master site
-
sodar_uuid
¶ RemoteSite relation UUID (local)
-
url
¶ Site URL
-
exception
-
class
projectroles.models.
Role
(*args, **kwargs)[source]¶ Role definition, used to assign roles to projects in RoleAssignment
-
exception
DoesNotExist
¶
-
exception
MultipleObjectsReturned
¶
-
description
¶ Role description
-
name
¶ Name of role
-
exception
-
class
projectroles.models.
RoleAssignment
(*args, **kwargs)[source]¶ Assignment of an user to a role in a project. One role per user is allowed for each project. Roles of project owner and project delegate assignements might be limited (to PROJECTROLES_DELEGATE_LIMIT) per project.
-
exception
DoesNotExist
¶
-
exception
MultipleObjectsReturned
¶
-
project
¶ Project in which role is assigned
-
role
¶ Role to be assigned
-
sodar_uuid
¶ RoleAssignment SODAR UUID
-
user
¶ User for whom role is assigned
-
exception
-
class
projectroles.models.
RoleAssignmentManager
[source]¶ Manager for custom table-level RoleAssignment queries
-
class
projectroles.models.
SODARUser
(*args, **kwargs)[source]¶ SODAR compatible abstract user model
-
sodar_uuid
¶ User SODAR UUID
-
App Settings¶
Projectroles provides an API for getting or setting project and user specific settings.
-
class
projectroles.app_settings.
AppSettingAPI
[source]¶ -
classmethod
get_all_defaults
(scope)[source]¶ Get all default settings for a scope.
Parameters: scope – Returns:
-
classmethod
get_all_settings
(project=None, user=None)[source]¶ Return all setting values. If the value is not found, return the default.
Parameters: - project – Project object (can be None)
- user – User object (can be None)
Returns: Dict
Raise: ValueError if neither project nor user are set
-
classmethod
get_app_setting
(app_name, setting_name, project=None, user=None)[source]¶ Return app setting value for a project or an user. If not set, return default.
Parameters: - app_name – App name (string, must correspond to “name” in app plugin)
- setting_name – Setting name (string)
- project – Project object (can be None)
- user – User object (can be None)
Returns: String or None
Raise: KeyError if nothing is found with setting_name
-
classmethod
get_default_setting
(app_name, setting_name)[source]¶ Get default setting value from an app plugin.
Parameters: - app_name – App name (string, must correspond to “name” in app plugin)
- setting_name – Setting name (string)
Returns: Setting value (string, integer or boolean)
Raise: KeyError if nothing is found with setting_name
-
classmethod
get_setting_defs
(plugin, scope)[source]¶ Return app setting definitions of a specific scope from a plugin.
Parameters: - plugin – project app plugin object extending ProjectAppPluginPoint
- scope – PROJECT or USER
Returns: Dict
Raise: ValueError if scope is invalid
-
classmethod
set_app_setting
(app_name, setting_name, value, project=None, user=None, validate=True)[source]¶ Set value of an existing project or user settings. Creates the object if not found.
Parameters: - app_name – App name (string, must correspond to “name” in app plugin)
- setting_name – Setting name (string)
- value – Value to be set
- project – Project object (can be None)
- user – User object (can be None)
- validate – Validate value (bool, default=True)
Returns: True if changed, False if not changed
Raise: ValueError if validating and value is not accepted for setting type
Raise: ValueError if neither project nor user are set
Raise: KeyError if setting name is not found in plugin specification
-
classmethod
Common Template Tags¶
These tags can be included in templates with
{% load 'projectroles_common_tags' %}
.
Template tags provided by projectroles for use in other apps
Return True if backend app is available, else False
Return the SODAR Core version
Force wrapping of string
Return object class as string
Return display name from SODAR_CONSTANTS
Get full URL based on a local URL
Return link to object timeline events within project
Return info popover link icon
Return Project by sodar_uuid
Return link to project with a simple or full title
Return HTML version of the full project title including parents
Get remote project icon HTML
Return value of Django setting by name or None if it is not found. Return a Javascript-safe value if js=True.
Return User by username
Return standard HTML representation for a User object
Return string with search term highlighted
Markdown field rendering helper
Return the site version
Return True/False based on whether a static file exists
Return True/False based on whether a template exists
Utilities¶
General utility functions are stored in utils.py
.
-
projectroles.utils.
build_invite_url
(invite, request)[source]¶ Return invite URL for a project invitation.
Parameters: - invite – ProjectInvite object
- request – HTTP request
Returns: URL (string)
-
projectroles.utils.
build_secret
(length=32)[source]¶ Return secret string for e.g. public URLs.
Parameters: length – Length of string if specified, default value from settings Returns: Randomized secret (string)
-
projectroles.utils.
get_app_names
()[source]¶ Return list of names for locally installed non-django apps
-
projectroles.utils.
get_display_name
(key, title=False, count=1, plural=False)[source]¶ Return display name from SODAR_CONSTANTS.
Parameters: - key – Key in SODAR_CONSTANTS[‘DISPLAY_NAMES’] to return (string)
- title – Return name in title case if true (boolean, optional)
- count – Item count for returning plural form, overrides plural=False if not 1 (int, optional)
- plural – Return plural form if True, overrides count != 1 if True (boolean, optional)
Returns: String
-
projectroles.utils.
get_expiry_date
()[source]¶ Return expiry date based on current date + INVITE_EXPIRY_DAYS
Returns: DateTime object