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[source]¶
Projectroles plugin point for registering backend apps
- get_extra_data_link(_extra_data, _name)[source]¶
Return a link for timeline label starting with ‘extra-‘
- get_object(model, uuid)[source]¶
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
- 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 timeline label starting with ‘extra-‘
- get_object(model, uuid)[source]¶
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)[source]¶
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)[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
user – User object (current user)
- Returns
String (may contain HTML), integer 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.
- handle_project_update(project, old_data)[source]¶
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)[source]¶
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)[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 = '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[source]¶
Projectroles plugin point for registering site-wide apps
- get_extra_data_link(_extra_data, _name)[source]¶
Return a link for timeline label starting with ‘extra-‘
- get_messages(user=None)[source]¶
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)[source]¶
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
- 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', custom_order=False)[source]¶
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)[source]¶
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)[source]¶
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)[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
- 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)[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 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)[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
- full_title¶
Full project title with parent path (auto-generated)
- get_all_roles(inherited=True)[source]¶
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)[source]¶
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_owners(inherited_only=False)[source]¶
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
- has_public_children¶
Whether project has children with public access (auto-generated)
- has_role(user, include_children=False, check_owner=True)[source]¶
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_owner(user)[source]¶
Return True if user is owner in this project or inherits ownership from a parent category.
- is_owner_or_delegate(user)[source]¶
Return True if user is either an owner or a delegate in this project. Includes inherited owner relationships.
- parent¶
Parent category if nested, otherwise null
- public_guest_access¶
Public guest access
- 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”)
- 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
- class projectroles.models.ProjectManager(*args, **kwargs)[source]¶
Manager for custom table-level Project queries
- find(search_terms, 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.
- 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)[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
- 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)
- 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
- user_display¶
RemoteSite’s link visibilty for users
- 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
- 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
- class projectroles.models.RoleAssignmentManager(*args, **kwargs)[source]¶
Manager for custom table-level RoleAssignment queries
- class projectroles.models.SODARUser(*args, **kwargs)[source]¶
SODAR compatible abstract user model. Use this on your SODAR Core based site.
- save(*args, **kwargs)[source]¶
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.
- 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 delete_setting(app_name, setting_name, project=None, user=None)[source]¶
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)[source]¶
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()[source]¶
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)[source]¶
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)[source]¶
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)[source]¶
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()[source]¶
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)[source]¶
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)[source]¶
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)[source]¶
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)[source]¶
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)[source]¶
Return True if backend app is available, else False
- projectroles.templatetags.projectroles_common_tags.core_version()[source]¶
Return the SODAR Core version
- projectroles.templatetags.projectroles_common_tags.force_wrap(s, length)[source]¶
Force wrapping of string
- projectroles.templatetags.projectroles_common_tags.get_app_setting(app_name, setting_name, project=None, user=None)[source]¶
Get a project/user specific app setting from AppSettingAPI
- projectroles.templatetags.projectroles_common_tags.get_backend_include(backend_name, include_type='js')[source]¶
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)[source]¶
Return object class as string
- projectroles.templatetags.projectroles_common_tags.get_display_name(key, title=False, count=1, plural=False)[source]¶
Return display name from SODAR_CONSTANTS
- projectroles.templatetags.projectroles_common_tags.get_django_setting(name, default=None, js=False)[source]¶
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)[source]¶
Get full URL based on a local URL
- projectroles.templatetags.projectroles_common_tags.get_history_dropdown(obj, project=None)[source]¶
Return link to object timeline events within project
- projectroles.templatetags.projectroles_common_tags.get_info_link(content, html=False)[source]¶
Return info popover link icon
- projectroles.templatetags.projectroles_common_tags.get_project_by_uuid(sodar_uuid)[source]¶
Return Project by sodar_uuid
- projectroles.templatetags.projectroles_common_tags.get_project_link(project, full_title=False, request=None)[source]¶
Return link to project with a simple or full title
- projectroles.templatetags.projectroles_common_tags.get_project_title_html(project)[source]¶
Return HTML version of the full project title including parents
- projectroles.templatetags.projectroles_common_tags.get_remote_icon(project, request)[source]¶
Get remote project icon HTML
- projectroles.templatetags.projectroles_common_tags.get_role_display_name(role_as, title=False)[source]¶
Return display name for role assignment
- projectroles.templatetags.projectroles_common_tags.get_user_by_username(username)[source]¶
Return User by username
- projectroles.templatetags.projectroles_common_tags.get_user_html(user)[source]¶
Return standard HTML representation for a User object
- projectroles.templatetags.projectroles_common_tags.get_visible_projects(projects, can_view_hidden_projects=False)[source]¶
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)[source]¶
Return string with search term highlighted
- projectroles.templatetags.projectroles_common_tags.render_markdown(raw_markdown)[source]¶
Markdown field rendering helper
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
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[source]¶
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.
Project type can be restricted to PROJECT_TYPE_CATEGORY or PROJECT_TYPE_PROJECT by setting the project_type attribute in the view.
Base API View Mixins¶
- class projectroles.views_api.SODARAPIBaseMixin[source]¶
Base SODAR API mixin to be used by external SODAR Core based sites
- versioning_class¶
- class projectroles.views_api.SODARAPIBaseProjectMixin[source]¶
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.
Project type can be restricted to PROJECT_TYPE_CATEGORY or PROJECT_TYPE_PROJECT by setting the project_type attribute in the view.
- class projectroles.views_api.APIProjectContextMixin[source]¶
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[source]¶
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”
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)[source]¶
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)[source]¶
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.
- class projectroles.views_ajax.SODARBaseProjectAjaxView(**kwargs)[source]¶
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)[source]¶
Bases:
rest_framework.serializers.ModelSerializer
Base serializer for any SODAR model with a sodar_uuid field
- post_save(obj)[source]¶
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
- class projectroles.serializers.SODARProjectModelSerializer(*args, **kwargs)[source]¶
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.
- class projectroles.serializers.SODARNestedListSerializer(*args, **kwargs)[source]¶
Bases:
projectroles.serializers.SODARModelSerializer
Serializer to display nested SODAR models as dicts with sodar_uuid as key.
- class projectroles.serializers.SODARUserSerializer(*args, **kwargs)[source]¶
Bases:
projectroles.serializers.SODARModelSerializer
Serializer for the user model used in SODAR Core based sites