Projectroles Django API Documentation

This document contains the Django API documentation for the projectroles app. Included are functionalities and classes intended to be used by other applications when building a SODAR Core based Django site.

Base UI View Classes

Base mixins and classes for building UI views can be found in projectroles.views.

class projectroles.views.LoginRequiredMixin

Bases: AccessMixin

Override of Django LoginRequiredMixin to handle anonymous access and kiosk mode.

class projectroles.views.LoggedInPermissionMixin

Bases: PermissionRequiredMixin

Mixin for handling redirection for both unlogged users and authenticated users without permissions.

add_no_perm_message()

Add Django in the UI if handle_no_permission() fails. This can be overridden to implement specific logic in a view if e.g. a different message should be displayed depending on the referring view.

handle_no_permission()

Handle no permission and redirect user. If custom message is specified using self.login_message, it will be displayed.

has_permission()

Override for this mixin also to work with admin users without a permission object.

no_perm_message = None

No permission message custom override

no_perm_message_level = 'error'

No permission message Django messages level

class projectroles.views.ProjectAccessMixin

Bases: object

Mixin for providing access to a Project object from request kwargs

get_project(request=None, kwargs=None)

Return SODAR Project object based or None if not found, based on the current request and view kwargs. If arguments are not provided, uses self.request and/or self.kwargs.

Parameters:

• request – Request object (optional)

• kwargs – View kwargs (optional)

Returns:

Object of project_class or None if not found

project_class

Model class to use for projects. Can be overridden by e.g. a proxy model

alias of Project

class projectroles.views.ProjectPermissionMixin

Bases: PermissionRequiredMixin, ProjectAccessMixin

Mixin for providing a Project object and queryset for permission checking.

get_permission_object()

Override this method to provide the object to check for permission against. By default uses self.get_object() as provided by SingleObjectMixin. Returns None if there’s no get_object method.

get_queryset(*args, **kwargs)

Override get_queryset() to filter down to the currently selected object.

has_permission()

Overrides for project permission access

class projectroles.views.ProjectContextMixin

Bases: HTTPRefererMixin, PluginContextMixin, ProjectAccessMixin

Mixin for adding context data to Project base view and other views extending it. Includes HTTPRefererMixin for correct referer URL.

class projectroles.views.PluginContextMixin

Bases: ContextMixin

Mixin for adding plugin list to context data

class projectroles.views.InvalidFormMixin

Bases: object

Mixin for UI improvements in invalid form failure. Recommended to be used with long forms spanning multiple screen heights.

form_invalid(form, **kwargs)

Override form_invalid() to add Django message on form failure

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

Projectroles plugin point for registering backend apps

get_api()

Return API entry point object.

get_extra_data_link(_extra_data, _name)

Return a link for timeline label starting with ‘extra-’

get_object(model, uuid)

Return object based on a 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)

Return URL referring to an 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_statistics()

Return backend statistics as a dict. Should take the form of {id: {label, value, url (optional), description (optional)}}.

Returns:

Dict

class projectroles.plugins.ProjectAppPluginPoint

Projectroles plugin point for registering project specific apps

get_extra_data_link(_extra_data, _name)

Return a link for timeline label starting with ‘extra-’

get_object(model, uuid)

Return object based on a 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)

Return URL referring to an 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, user)

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

• user – User object (current user)

Returns:

String (may contain HTML), integer or None

get_statistics()

Return app statistics as a dict. Should take the form of {id: {label, value, url (optional), description (optional)}}.

Returns:

Dict

search(search_terms, user, search_type=None, keywords=None)

Return app items based on one or more search terms, user, optional type and optional keywords.

Parameters:

• search_terms – Search terms to be joined with the OR operator (list of strings)

• user – User object for user initiating the search

• search_type – String

• keywords – List (optional)

Returns:

Dict

update_cache(name=None, project=None, user=None)

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 = []

UI URLs

validate_form_app_settings(app_settings, project=None, user=None)

Validate app settings form data and return a dict of errors.

Parameters:

• app_settings – Dict of app settings

• project – Project object or None

• user – User object or None

Returns:

dict in format of {setting_name: ‘Error string’}

class projectroles.plugins.ProjectModifyPluginMixin

Mixin for project plugin API extensions for additional actions to be performed for project and role modifications. Used if e.g. updating external resources based on SODAR Core projects.

Add this into your project app or backend plugin if you want to implement additional modification features. It is not supported on site app plugins.

perform_owner_transfer(project, new_owner, old_owner, old_owner_role, request=None)

Perform additional actions to finalize project ownership transfer.

Parameters:

• project – Project object

• new_owner – SODARUser object for new owner

• old_owner – SODARUser object for previous owner

• old_owner_role – Role object for new role of previous owner

• request – Request object or None

perform_project_archive(project)

Perform additional actions to finalize project archiving or unarchiving. The state being applied can be derived from the project.archive attr.

Parameters:

project – Project object (Project)

perform_project_modify(project, action, project_settings, old_data=None, old_settings=None, request=None)

Perform additional actions to finalize project creation or update.

Parameters:

• project – Current project object (Project)

• action – Action to perform (CREATE or UPDATE)

• project_settings – Project app settings (dict)

• old_data – Old project data in case of an update (dict or None)

• old_settings – Old app settings in case of update (dict or None)

• request – Request object or None

perform_project_setting_update(app_name, setting_name, value, old_value, project=None, user=None)

Perform additional actions when updating a single app setting with PROJECT scope.

Parameters:

• app_name – Name of app plugin for the setting, “projectroles” is used for projectroles settings (string)

• setting_name – Setting name (string)

• value – New value for setting

• old_value – Previous value for setting

• project – Project object or None

• user – User object or None

perform_project_sync(project)

Synchronize existing projects to ensure related data exists when the syncmodifyapi management comment is called. Should mostly be used in development when the development databases have been e.g. modified or recreated.

Parameters:

project – Current project object (Project)

perform_role_delete(role_as, request=None)

Perform additional actions to finalize role assignment deletion.

Parameters:

• role_as – RoleAssignment object

• request – Request object or None

perform_role_modify(role_as, action, old_role=None, request=None)

Perform additional actions to finalize role assignment creation or update.

Parameters:

• role_as – RoleAssignment object

• action – Action to perform (CREATE or UPDATE)

• old_role – Role object for previous role in case of an update

• request – Request object or None

revert_owner_transfer(project, new_owner, old_owner, old_owner_role, request=None)

Revert project ownership transfer if errors have occurred in other apps.

Parameters:

• project – Project object

• new_owner – SODARUser object for new owner

• old_owner – SODARUser object for previous owner

• old_owner_role – Role object for new role of previous owner

• request – Request object or None

revert_project_archive(project)

Revert project archiving or unarchiving if errors have occurred in other apps. The state being originally set can be derived from the project.archive attr.

Parameters:

project – Project object (Project)

revert_project_modify(project, action, project_settings, old_data=None, old_settings=None, request=None)

Revert project creation or update if errors have occurred in other apps.

Parameters:

• project – Current project object (Project)

• action – Action which was performed (CREATE or UPDATE)

• project_settings – Project app settings (dict)

• old_data – Old project data in case of update (dict or None)

• old_settings – Old app settings in case of update (dict or None)

• request – Request object or None

revert_project_setting_update(app_name, setting_name, value, old_value, project=None, user=None)

Revert updating a single app setting with PROJECT scope if errors have occurred in other apps.

Parameters:

• app_name – Name of app plugin for the setting, “projectroles” is used for projectroles settings (string)

• setting_name – Setting name (string)

• value – New value for setting

• old_value – Previous value for setting

• project – Project object or None

• user – User object or None

revert_role_delete(role_as, request=None)

Revert role assignment deletion deletion if errors have occurred in other apps.

Parameters:

• role_as – RoleAssignment object

• request – Request object or None

revert_role_modify(role_as, action, old_role=None, request=None)

Revert role assignment creation or update if errors have occurred in other apps.

Parameters:

• role_as – RoleAssignment object

• action – Action which was performed (CREATE or UPDATE)

• old_role – Role object for previous role in case of an update

• request – Request object or None

class projectroles.plugins.RemoteSiteAppPlugin

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 = 'mdi:cloud-sync'

Iconify icon

name = 'remotesites'

Name (used as plugin ID)

title = 'Remote Site Access'

Title (used in templates)

urls = []

UI URLs

class projectroles.plugins.SiteAppPluginPoint

Projectroles plugin point for registering site-wide apps

get_extra_data_link(_extra_data, _name)

Return a link for timeline label starting with ‘extra-’

get_messages(user=None)

Return a list of messages to be shown to users.

Parameters:

user – User object (optional)

Returns:

List of dicts or and empty list if no messages

get_object(model, uuid)

Return object based on a 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)

Return URL referring to an 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_statistics()

Return app statistics as a dict. Should take the form of {id: {label, value, url (optional), description (optional)}}.

Returns:

Dict

validate_form_app_settings(app_settings, user=None)

Validate app settings form data and return a dict of errors.

Parameters:

• app_settings – Dict of app settings

• user – User object or None

Returns:

dict in format of {setting_name: ‘Error string’}

projectroles.plugins.change_plugin_status(name, status, plugin_type='app')

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', custom_order=False)

Return active plugins of a specific type.

Parameters:

• plugin_type – “project_app”, “site_app” or “backend” (string)

• custom_order – Order by plugin_ordering for project apps (boolean)

Returns:

List or None

Raise:

ValueError if plugin_type is not recognized

projectroles.plugins.get_app_plugin(plugin_name, plugin_type=None)

Return active app plugin.

Parameters:

• plugin_name – Plugin name (string)

• plugin_type – Plugin type (string or None for all types)

Returns:

Plugin object or None if not found

projectroles.plugins.get_backend_api(plugin_name, force=False, **kwargs)

Return backend API object. NOTE: May raise an exception from plugin.get_api().

Parameters:

• plugin_name – Plugin name (string)

• force – Return plugin regardless of status in ENABLED_BACKEND_PLUGINS

• kwargs – Optional kwargs for API

Returns:

Plugin object or None if not found

Models

Projectroles models are used by other apps for project access and metadata management as well as linking objects to projects.

Models for the projectroles app

class projectroles.models.AppSetting(*args, **kwargs)

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

get_value()

Return value of the setting in the format specified in ‘type’

name

Name of the setting

project

Project to which the setting belongs

save(*args, **kwargs)

Version of save() to convert ‘value’ data according to ‘type’

sodar_uuid

AppSetting SODAR UUID

type

Type of the setting

user

Project to which the setting belongs

user_modifiable

Setting visibility in forms

value

Value of the setting

value_json

Optional JSON value for the setting

class projectroles.models.AppSettingManager(*args, **kwargs)

Manager for custom table-level AppSetting queries

get_setting_value(app_name, setting_name, project=None, user=None)

Return value of setting_name for app_name in project or for user.

Note that project and/or user must be set.

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)

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

archive

Project is archived (read-only)

description

Short project description

full_title

Full project title with parent path (auto-generated)

get_children(flat=False)

Return child objects for a Category, sorted by full title.

Parameters:

flat – Return all children recursively as a flat list (bool)

Returns:

QuerySet

get_delegates(inherited=True, inherited_only=False)

Return RoleAssignments for delegates. Excludes delegates with an inherited owner role.

Parameters:

• inherited – Include inherited roles (bool)

• inherited_only – Return only inherited roles (bool)

Returns:

List

get_depth()

Return depth of project in the project tree structure (root=0)

get_log_title(full_title=False)

Return a logger-friendly title for the project.

Parameters:

full_title – Display full title if True (boolean)

Returns:

String

get_members(inherited=True)

Return RoleAssignments for members of project excluding owner and delegates.

Parameters:

inherited – Include inherited roles (boolean)

Returns:

List of RoleAssignments

get_owner()

Return RoleAssignment for local (non-inherited) owner or None if not set.

Returns:

QuerySet

get_owners(inherited=True, inherited_only=False)

Return RoleAssignments for project owner as well as possible inherited owners from parent projects.

Parameters:

• inherited – Include inherited roles (bool)

• inherited_only – Return only inherited roles (bool)

Returns:

List

get_parents()

Return a list of parent projects in inheritance order.

Returns:

List of Project objects

get_role(user, inherited_only=False)

Return the currently active role for user, or None if not available. Returns the highest ranked role including inherited roles. In case of multiple roles of the same level in the hierarchy, the lowest one is returned.

Parameters:

• user – User object

• inherited_only – Only return an inherited role if True (boolean, default=False)

Returns:

RoleAssignment object or None

get_roles(user=None, inherited=True, inherited_only=False, min_rank=None, max_rank=None)

Return project role assignments.

Parameters:

• user – Limit to user (User object or None)

• inherited – Include inherited roles (bool)

• inherited_only – Return only inherited roles (bool)

• min_rank – Limit roles to minimum rank (integer or None)

• max_rank – Limit roles to maximum rank (integer or None)

Returns:

List of RoleAssignment objects

Raise:

ValueError If inheritance arguments conflict

get_roles_by_rank(role_name, inherited=True, inherited_only=False)

Return RoleAssignments for specific role name. Will also include custom roles of identical rank once role customization is implemented (see issue #288).

Parameters:

• role_name – Name of role (string)

• inherited – Include inherited roles (bool)

• inherited_only – Return only inherited roles (bool)

Returns:

List

get_source_site()

Return source site or None if this is a locally defined project.

Returns:

RemoteProject object or None

has_public_children

Whether project has children with public access (auto-generated)

has_role(user)

Return whether user has roles in Project. Returns True if user has local role, inherits a role from a parent category, or if public guest access is enabled for the project.

Parameters:

user – User object

Returns:

Boolean

has_role_in_children(user)

Return True if user has a role in any of the children in the project. Also returns true if public guest access is true for any child.

Parameters:

user – User object

Returns:

Boolean

is_delegate(user)

Return True if user is delegate in this project or inherits delegate status from a parent category.

Returns:

Boolean

is_owner(user)

Return True if user is owner in this project or inherits ownership from a parent category.

Returns:

Boolean

is_owner_or_delegate(user)

Return True if user is either an owner or a delegate in this project. Includes inherited assignments.

Returns:

Boolean

is_remote()

Return True if current project has been retrieved from a remote SODAR site.

Returns:

Boolean

is_revoked()

Return True if remote access has been revoked for the project.

Returns:

Boolean

parent

Parent category if nested, otherwise null

public_guest_access

Public guest access

readme

Project README (optional, supports markdown)

save(*args, **kwargs)

Custom validation and field populating for Project

set_archive(status=True)

Helper for setting archive value. Raises ValidationError for categories.

set_public(public=True)

Helper for setting value of public_guest_access

sodar_uuid

Project SODAR UUID

title

Project title

type

Type of project (“CATEGORY”, “PROJECT”)

class projectroles.models.ProjectInvite(*args, **kwargs)

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

class projectroles.models.ProjectManager(*args, **kwargs)

Manager for custom table-level Project queries

find(search_terms, keywords=None, project_type=None)

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.

Parameters:

• search_terms – Search terms (list)

• keywords – Optional search keywords as key/value pairs (dict)

• project_type – Project type or None

Returns:

QuerySet of Project objects

class projectroles.models.RemoteProject(*args, **kwargs)

Remote project relation

exception DoesNotExist

exception MultipleObjectsReturned

date_access

DateTime of last access from/to remote site

get_project()

Get the related Project object

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)

class projectroles.models.RemoteSite(*args, **kwargs)

Remote SODAR site

exception DoesNotExist

exception MultipleObjectsReturned

description

Site description

get_access_date()

Return date of latest project access by remote site

get_url()

Return sanitized site URL

mode

Site mode

name

Site name

save(*args, **kwargs)

Version of save() to include custom validation

secret

Secret token used to connect to the master site

sodar_uuid

RemoteSite relation UUID (local)

url

Site URL

user_display

RemoteSite’s link visibilty for users

class projectroles.models.Role(*args, **kwargs)

Role definition, used to assign roles to projects in RoleAssignment

exception DoesNotExist

exception MultipleObjectsReturned

description

Role description

name

Name of role

project_types

Allowed project types for the role

rank

Role rank for determining role hierarchy

class projectroles.models.RoleAssignment(*args, **kwargs)

Assignment of an user to a role in a project. One local assignment per user is allowed for each project.

One local project owner assignment is allowed for a project. Local project delegate assignements might be limited using PROJECTROLES_DELEGATE_LIMIT.

Inherited role assignments can be accessed via the Project model API, e.g. Project.get_roles().

exception DoesNotExist

exception MultipleObjectsReturned

project

Project in which role is assigned

role

Role to be assigned

save(*args, **kwargs)

Version of save() to include custom validation for RoleAssignment

sodar_uuid

RoleAssignment SODAR UUID

user

User for whom role is assigned

class projectroles.models.SODARUser(*args, **kwargs)

SODAR compatible abstract user model. Use this on your SODAR Core based site.

get_form_label(email=False)

Return user label with full name, username and optional email.

Parameters:

email – Return email if True (boolean, default=False)

Returns:

String

get_full_name()

Return full name or username if not set

save(*args, **kwargs)

Save the current instance. Override this in a subclass if you want to control the saving process.

The ‘force_insert’ and ‘force_update’ parameters can be used to insist that the “save” must be an SQL insert or update (or equivalent for non-SQL backends), respectively. Normally, they should not be set.

set_group()

Set user group based on user name.

sodar_uuid

User SODAR UUID

update_full_name()

Update full name of user.

Returns:

String

update_ldap_username()

Update username for an LDAP user.

Returns:

String

projectroles.models.get_role_project_type_default()

Return default value for Role.project_type

App Settings

Projectroles provides an API for getting or setting project and user specific settings. The API can be invoked as follows:

from projectroles.app_settings import AppSettingAPI
app_settings = AppSettingAPI()

class projectroles.app_settings.AppSettingAPI

classmethod delete(app_name, setting_name, project=None, user=None)

Delete one or more app setting objects. In case of a PROJECT_USER setting, can be used to delete all settings related to project.

Parameters:

• app_name – App name (string, must equal “name” in app plugin)

• setting_name – Setting name (string)

• project – Project object to delete setting from (optional)

• user – User object to delete setting from (optional)

Raise:

ValueError with invalid project/user args

classmethod delete_by_scope(scope, project=None, user=None)

Delete all app settings within a given scope for a project and/or user.

Parameters:

• scope – Setting scope (string)

• project – Project object to delete setting from

• user – User object to delete setting from

Raise:

ValueError if scope, project or user are incorrect

classmethod get(app_name, setting_name, project=None, user=None, post_safe=False)

Return app setting value for a project or a user. If not set, return default.

Parameters:

• app_name – App name (string, must equal “name” in app plugin)

• setting_name – Setting name (string)

• project – Project object (optional)

• user – User object (optional)

• post_safe – Whether a POST safe value should be returned (bool)

Returns:

String or None

Raise:

KeyError if nothing is found with setting_name

classmethod get_all(project=None, user=None, post_safe=False)

Return all setting values. If the value is not found, return the default.

Parameters:

• project – Project object (optional)

• user – User object (optional)

• post_safe – Whether POST safe values should be returned (bool)

Returns:

Dict

Raise:

ValueError if neither project nor user are set

classmethod get_all_defs()

Return app setting definitions for projectroles and all active app plugins in a dictionary with the app name as key.

Returns:

Dict

classmethod get_default(app_name, setting_name, project=None, user=None, post_safe=False)

Get default setting value from an app plugin.

Parameters:

• app_name – App name (string, must equal “name” in app plugin)

• setting_name – Setting name (string)

• project – Project object (optional)

• user – User object (optional)

• post_safe – Whether a POST safe value should be returned (bool)

Returns:

Setting value (string, integer or boolean)

Raise:

ValueError if app plugin is not found

Raise:

KeyError if nothing is found with setting_name

classmethod get_defaults(scope, project=None, user=None, post_safe=False)

Get all default settings for a scope.

Parameters:

• scope – Setting scope (PROJECT, USER or PROJECT_USER)

• project – Project object (optional)

• user – User object (optional)

• post_safe – Whether POST safe values should be returned (bool)

Returns:

Dict

classmethod get_definition(name, plugin=None, app_name=None)

Return definition for a single app setting, either based on an app name or the plugin object.

Parameters:

• name – Setting name

• plugin – Plugin object or None

• app_name – Name of the app plugin (string or None)

Returns:

Dict

Raise:

ValueError if neither app_name nor plugin are set or if setting is not found in plugin

classmethod get_definitions(scope, plugin=None, app_name=None, user_modifiable=False)

Return app setting definitions of a specific scope from a plugin.

Parameters:

• scope – PROJECT, USER or PROJECT_USER

• plugin – Plugin object or None

• app_name – Name of the app plugin (string or None)

• user_modifiable – Only return non-superuser modifiable settings if True (boolean)

Returns:

Dict

Raise:

ValueError if scope is invalid or if neither app_name nor plugin are set

classmethod get_projectroles_defs()

Return projectroles settings definitions. If it exists, get value from settings.PROJECTROLES_APP_SETTINGS_TEST for testing modifications.

Returns:

Dict

classmethod set(app_name, setting_name, value, project=None, user=None, validate=True)

Set value of an existing project or user settings. Creates the object if not found.

Parameters:

• app_name – App name (string, must equal “name” in app plugin)

• setting_name – Setting name (string)

• value – Value to be set

• project – Project object (optional)

• user – User object (optional)

• 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 validate(setting_type, setting_value, setting_options, project=None, user=None)

Validate setting value according to its type.

Parameters:

• setting_type – Setting type

• setting_value – Setting value

• setting_options – Setting options (can be None)

• project – Project object (optional)

• user – User object (optional)

Raise:

ValueError if setting_type or setting_value is invalid

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

projectroles.templatetags.projectroles_common_tags.check_backend(name)

Return True if backend app is available and enabled, else False

projectroles.templatetags.projectroles_common_tags.core_version()

Return the SODAR Core version

projectroles.templatetags.projectroles_common_tags.force_wrap(s, length)

Force wrapping of string

projectroles.templatetags.projectroles_common_tags.get_app_setting(app_name, setting_name, project=None, user=None)

Get a project/user specific app setting from AppSettingAPI

projectroles.templatetags.projectroles_common_tags.get_backend_include(backend_name, include_type='js')

Return import string for backend app Javascript or CSS. Returns empty string if not found.

projectroles.templatetags.projectroles_common_tags.get_class(obj, lower=False)

Return object class as string

projectroles.templatetags.projectroles_common_tags.get_display_name(key, title=False, count=1, plural=False)

Return display name from SODAR_CONSTANTS

projectroles.templatetags.projectroles_common_tags.get_django_setting(name, default=None, js=False)

Return value of Django setting by name or the default value if the setting is not found. Return a Javascript-safe value if js=True.

projectroles.templatetags.projectroles_common_tags.get_full_url(request, url)

Get full URL based on a local URL

projectroles.templatetags.projectroles_common_tags.get_history_dropdown(obj, project=None)

Return link to object timeline events within project

projectroles.templatetags.projectroles_common_tags.get_info_link(content, html=False)

Return info popover link icon

projectroles.templatetags.projectroles_common_tags.get_project_by_uuid(sodar_uuid)

Return Project by sodar_uuid

projectroles.templatetags.projectroles_common_tags.get_project_link(project, full_title=False, request=None)

Return link to project with a simple or full title

projectroles.templatetags.projectroles_common_tags.get_project_title_html(project)

Return HTML version of the full project title including parents

projectroles.templatetags.projectroles_common_tags.get_remote_icon(project, request)

Get remote project icon HTML

projectroles.templatetags.projectroles_common_tags.get_role_display_name(role, project, title=False)

Return display name for role assignment.

Parameters:

• role – Role object

• project – Project object for context (to support inheritance)

• title – Return in title case if True (boolean)

projectroles.templatetags.projectroles_common_tags.get_user_by_username(username)

Return User by username

projectroles.templatetags.projectroles_common_tags.get_user_html(user)

Return standard HTML representation for a User object

projectroles.templatetags.projectroles_common_tags.get_visible_projects(projects, can_view_hidden_projects=False)

Return all projects that are either visible by user display or by view hidden permission.

projectroles.templatetags.projectroles_common_tags.highlight_search_term(item, terms)

Return string with search term highlighted

projectroles.templatetags.projectroles_common_tags.render_markdown(raw_markdown)

Markdown field rendering helper

projectroles.templatetags.projectroles_common_tags.site_version()

Return the site version

projectroles.templatetags.projectroles_common_tags.static_file_exists(path)

Return True/False based on whether a static file exists

projectroles.templatetags.projectroles_common_tags.template_exists(path)

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)

Return invite URL for a project invitation.

Parameters:

• invite – ProjectInvite object

• request – HTTP request

Returns:

URL (string)

projectroles.utils.build_secret(length=32)

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()

Return list of names for locally installed non-django apps

projectroles.utils.get_display_name(key, title=False, count=1, plural=False)

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()

Return expiry date based on current date + INVITE_EXPIRY_DAYS

Returns:

DateTime object

projectroles.utils.get_user_display_name(user, inc_user=False)

Return full name of user for displaying.

Parameters:

• user – User object

• inc_user – Include user name if true (boolean)

Returns:

String

Base REST API View Classes

Base view classes and mixins for building REST APIs can be found in projectroles.views_api.

Permissions / Versioning / Rendering

class projectroles.views_api.SODARAPIProjectPermission

Bases: ProjectAccessMixin, BasePermission

Mixin for providing basic project permission checking for API views with a single permission_required attribute. Also works with Knox token based views.

This must be used in the permission_classes attribute in order for token authentication to work.

Requires implementing either permission_required or get_permission_required() in the view.

Project type can be restricted to PROJECT_TYPE_CATEGORY or PROJECT_TYPE_PROJECT, as defined in SODAR constants, by setting the project_type attribute in the view.

has_permission(request, view)

Override has_permission() for checking auth and project permission

class projectroles.views_api.SODARAPIVersioning

Bases: AcceptHeaderVersioning

Accept header versioning class for SODAR API views

class projectroles.views_api.SODARAPIRenderer

Bases: JSONRenderer

SODAR API JSON renderer with a site-specific media type retrieved from Django settings.

Base API View Mixins

class projectroles.views_api.SODARAPIBaseMixin

Base SODAR API mixin to be used by external SODAR Core based sites

versioning_class

alias of SODARAPIVersioning

class projectroles.views_api.SODARAPIBaseProjectMixin

Bases: ProjectAccessMixin, SODARAPIBaseMixin

API view mixin for the base DRF APIView class with project permission checking, but without serializers and other generic view functionality.

Project type can be restricted to PROJECT_TYPE_CATEGORY or PROJECT_TYPE_PROJECT, as defined in SODAR constants, by setting the project_type attribute in the view.

class projectroles.views_api.APIProjectContextMixin

Bases: ProjectAccessMixin

Mixin to provide project context and queryset for generic API views. Can be used both in SODAR and SODAR Core API base views.

If your model doesn’t have a direct “project” relation, set queryset_project_field in the implementing class to query based on e.g. a nested foreignkey relation.

class projectroles.views_api.SODARAPIGenericProjectMixin

Bases: APIProjectContextMixin, SODARAPIBaseProjectMixin

API view mixin for generic DRF API views with serializers, SODAR project context and permission checkin.

Unless overriding permission_classes with their own implementation, the user MUST supply a permission_required attribute.

Replace lookup_url_kwarg with your view’s url kwarg (SODAR project compatible model name in lowercase).

If the lookup is done via a foreign key, change the lookup_field attribute of your class into foreignkey__sodar_uuid, e.g. project__sodar_uuid for lists.

If your object(s) don’t have a direct project relation, update the queryset_project_field to point to the field, e.g. someothermodel__project.

class projectroles.views_api.ProjectQuerysetMixin

Mixin for overriding the default queryset with one which allows us to lookup a Project object directly.

Base Ajax API View Classes

Base view classes and mixins for building Ajax API views can be found in projectroles.views_ajax.

class projectroles.views_ajax.SODARBaseAjaxMixin

Bases: object

Base Ajax mixin with permission class retrieval. To be used if another base class instead of SODARBaseAjaxView is needed.

The allow_anonymous property can be used to control whether anonymous users should access an Ajax view when PROJECTROLES_ALLOW_ANONYMOUS==True.

class projectroles.views_ajax.SODARBaseAjaxView(**kwargs)

Bases: SODARBaseAjaxMixin, APIView

Base Ajax view with Django session authentication.

No permission classes or mixins used, you will have to supply your own if using this class directly.

class projectroles.views_ajax.SODARBasePermissionAjaxView(**kwargs)

Bases: PermissionRequiredMixin, SODARBaseAjaxView

Base Ajax view with permission checks, to be used e.g. in site apps with no project context.

User-based perms such as is_superuser can be used with this class.

handle_no_permission()

Override handle_no_permission() to provide 403

class projectroles.views_ajax.SODARBaseProjectAjaxView(**kwargs)

Bases: ProjectAccessMixin, SODARBaseAjaxView

Base Ajax view with SODAR project permission checks

Base Serializers

Base serializers for SODAR Core compatible models are available in projectroles.serializers.

class projectroles.serializers.SODARModelSerializer(*args, **kwargs)

Bases: ModelSerializer

Base serializer for any SODAR model with a sodar_uuid field

post_save(obj)

Function to call at the end of a custom save() method. Ensures the returning of sodar_uuid in object creation POST responses.

Parameters:

obj – Object created in save()

Returns:

obj

save(**kwargs)

Override save() to ensure sodar_uuid is included for object creation POST responses.

to_representation(instance)

Override to_representation() to ensure sodar_uuid is included for object creation POST responses.

class projectroles.serializers.SODARProjectModelSerializer(*args, **kwargs)

Bases: SODARModelSerializer

Base serializer for SODAR models with a project relation.

The project field is read only because it is retrieved through the object reference in the URL.

create(validated_data)

Override create() to add project into validated data

to_representation(instance)

Override to_representation() to ensure the project value is included in responses.

class projectroles.serializers.SODARNestedListSerializer(*args, **kwargs)

Bases: SODARModelSerializer

Serializer to display nested SODAR models as dicts with sodar_uuid as key.

to_representation(instance)

Override to_representation() to pop project from a nested list representation, where the project context is already known in the topmost model.

class projectroles.serializers.SODARUserSerializer(*args, **kwargs)

Bases: SODARModelSerializer

Serializer for the user model used in SODAR Core based sites