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.

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_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 the given timeline label that stars with "extra:".

get_object(model, uuid)

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)

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, 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

get_taskflow_sync_data()

Return data for synchronizing taskflow operations.

Returns

List of dicts or None.

handle_project_update(project, old_data)

Perform actions to handle project update. # NOTE: This is a WIP feature to be altered/expanded in a later release

Parameters

• project – Current project (Project)

• old_data – Old project data prior to update (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 = []

App URLs (will be included in settings by djangoplugins)

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

Projectroles plugin point for registering site-wide apps

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

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

Returns

Dict

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.

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

description

Short project description

full_title

Full project title with parent path (auto-generated)

get_all_roles(inherited=True)

Return all RoleAssignments for the project, including inherited owner rights from parent categories.

Parameters

inherited – Include inherited owners (bool, default=True)

Returns

List

get_children(flat=False)

Return child objects for the Project sorted by title.

Parameters

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

Returns

Iterable of Project

get_delegates(exclude_inherited=False)

Return RoleAssignments for delegates

get_depth()

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

get_members()

Return RoleAssignments for members of project excluding owner and delegates.

get_owner()

Return RoleAssignment for owner (without inherited owners) or None if not set.

get_owners(inherited_only=False)

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

Parameters

inherited_only – Only show inherited owners if True (bool)

Returns

List

get_parents()

Return an array of parent projects in inheritance order

get_source_site()

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

has_public_children()

Return True if the project has any children with public guest access.

has_role(user, include_children=False)

Return whether user has roles in Project. If include_children is True, return True if user has roles in ANY child project. Returns True if user inherits owner permissions from a parent category, or if public access is allowed for the project.

is_delegate(user)

Return True if user is delegate in this project.

is_owner(user)

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

is_owner_or_delegate(user)

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

is_remote()

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

is_revoked()

Return True if remote access has been revoked for the project

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_public(public=True)

Helper for setting value of public_guest_access

sodar_uuid

Project SODAR UUID

submit_status

Status of project creation

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.ProjectUserTag(*args, **kwargs)

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

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

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

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

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.RoleAssignmentManager(*args, **kwargs)

Manager for custom table-level RoleAssignment queries

get_assignment(user, project)

Return assignment of user to project, or None if not found

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

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

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

projectroles.models.assign_user_group(sender, user, **kwargs)

Signal for user group assignment

projectroles.models.handle_ldap_login(sender, user, **kwargs)

Signal for LDAP login handling

App Settings

Projectroles provides an API for getting or setting project and user specific settings.

class projectroles.app_settings.AppSettingAPI

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

Delete app setting.

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)

classmethod get_all_defaults(scope, post_safe=False)

Get all default settings for a scope.

Parameters

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

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

Returns

Dict

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_all_settings(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_app_setting(app_name, setting_name, project=None, user=None, post_safe=False)

Return app setting value for a project or an 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_default_setting(app_name, setting_name, 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)

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

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

Returns

Dict

classmethod get_setting_def(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 extending ProjectAppPluginPoint

• app_name – Name of the app plugin (string)

Returns

Dict

Raise

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

classmethod get_setting_defs(scope, plugin=False, app_name=False, user_modifiable=False)

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

Parameters

• scope – PROJECT, USER or PROJECT_USER

• plugin – project app plugin object extending ProjectAppPluginPoint

• app_name – Name of the app plugin (string)

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

Returns

Dict

Raise

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

classmethod set_app_setting(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(setting_type, setting_value, setting_options)

Validate setting value according to its type.

Parameters

• setting_type – Setting type

• setting_value – Setting value

• setting_options – Setting options (can be None)

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, 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_as, title=False)

Return display name for role assignment

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: projectroles.views.ProjectAccessMixin, rest_framework.permissions.BasePermission

Mixin for providing a 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.

has_permission(request, view)

Override has_permission() for checking auth and project permission

class projectroles.views_api.SODARAPIVersioning

Bases: rest_framework.versioning.AcceptHeaderVersioning

Accept header versioning class for SODAR API views

class projectroles.views_api.SODARAPIRenderer

Bases: rest_framework.renderers.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 projectroles.views_api.SODARAPIVersioning

class projectroles.views_api.SODARAPIBaseProjectMixin

Bases: projectroles.views.ProjectAccessMixin, projectroles.views_api.SODARAPIBaseMixin

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

class projectroles.views_api.APIProjectContextMixin

Bases: projectroles.views.ProjectAccessMixin

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

class projectroles.views_api.SODARAPIGenericProjectMixin

Bases: projectroles.views_api.APIProjectContextMixin, projectroles.views_api.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 the project object, change lookup_field into “sodar_uuid”

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.SODARBaseAjaxView(**kwargs)

Bases: rest_framework.views.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: rules.contrib.views.PermissionRequiredMixin, projectroles.views_ajax.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: projectroles.views.ProjectAccessMixin, projectroles.views_ajax.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: rest_framework.serializers.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: projectroles.serializers.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: projectroles.serializers.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: projectroles.serializers.SODARModelSerializer

Serializer for the user model used in SODAR Core based sites