Autodocumentation of the Communities module

Models

Models for Community package.

class concord.communities.models.BaseCommunityModel(*args, **kwargs)

The base community model is the abstract type for all communities. Much of its logic is contained in customfields.RoleField and customfields.RoleHandler.

get_condition(leadership_type)

Gets the condition set on the leadership type specified.

get_condition_data(leadership_type, info='all')

Uses the change data saved in the mock actions to instantiate the condition and permissions that will be created and get their info, to be used in forms

get_name()

Get name of community.

get_owner()

Communities own themselves by default, although subtypes may differ.

has_condition(leadership_type)

Returns True if community has a condition set on owner or on governor, depending on the leadership_type passed in.

has_governor_condition()

Returns True if community has a governor condition, False if not.

has_owner_condition()

Returns True if community has an owner condition, False if not.

class concord.communities.models.Community(*args, **kwargs)

A community is, at heart, a collection of users. Communities govern resources that determine how these users interact, either moderating discussion spaces, like a community forum, setting restrictions on membership lists, or by setting access rules for resources owned by the community, such as saying only admins may edit data added to a dataset.

exception DoesNotExist

exception MultipleObjectsReturned

class concord.communities.models.DefaultCommunity(*args, **kwargs)

Every user has a default community of which they are the BDFL. (They can theoretically give someone else power over their default community, but we should probably prevent that on the backend.)

We’re almost always accessing this through the related_name. We have the user, and we want to know what community to stick our object in.

exception DoesNotExist

exception MultipleObjectsReturned

concord.communities.models.create_default_community(sender, instance, created, **kwargs)

Creates default community for a user when a new user is created.

State Changes

Community state changes.

class concord.communities.state_changes.AddGovernorRoleStateChange(role_name)

State change to add governor role to Community.

description_past_tense()

Returns the description of the state change object, in past tense.

description_present_tense()

Returns the description of the state change object, in present tense.

classmethod get_allowable_targets()

Returns the classes that an action of this type may target.

implement(actor, target)

Method that carries out the change of state.

validate(actor, target)

Method to check whether the data provided to a change object in an action is valid for the change object. Optional exclude_fields tells us not to validate the given field.

class concord.communities.state_changes.AddGovernorStateChange(governor_pk)

State change to add governor to Community.

description_past_tense()

Returns the description of the state change object, in past tense.

description_present_tense()

Returns the description of the state change object, in present tense.

classmethod get_allowable_targets()

Returns the classes that an action of this type may target.

implement(actor, target)

Method that carries out the change of state.

class concord.communities.state_changes.AddLeadershipConditionStateChange(*, condition_type, condition_data, permission_data, leadership_type)

State change to add leadership condition to Community.

apply_actions_to_conditions(action_list, target)

Apply actions to condtions.

description_past_tense()

Returns the description of the state change object, in past tense.

description_present_tense()

Returns the description of the state change object, in present tense.

generate_mock_actions(actor, target)

Helper method with template generation logic, since we’re using it in both validate and implement.

classmethod get_allowable_targets()

Returns the classes that an action of this type may target.

get_template_description(mock_action_list)

Get ‘plain English’ description of template.

implement(actor, target)

Method that carries out the change of state.

validate(actor, target)

Method to check whether the data provided to a change object in an action is valid for the change object. Optional exclude_fields tells us not to validate the given field.

class concord.communities.state_changes.AddMembersStateChange(member_pk_list, self_only=False)

State change to add members to Community.

classmethod check_configuration_is_valid(configuration)

Used primarily when setting permissions, this method checks that the supplied configuration is a valid one. By contrast, check_configuration checks a specific action against an already-validated configuration.

description_past_tense()

Returns the description of the state change object, in past tense.

description_present_tense()

Returns the description of the state change object, in present tense.

classmethod get_allowable_targets()

Returns the classes that an action of this type may target.

classmethod get_configurable_fields()

Gets the fields of a change object which may be configured when used in a Permission model.

classmethod get_configured_field_text(configuration)

Gets additional text for permissions item instance descriptions from configured fields.

implement(actor, target)

Method that carries out the change of state.

validate(actor, target)

Method to check whether the data provided to a change object in an action is valid for the change object. Optional exclude_fields tells us not to validate the given field.

class concord.communities.state_changes.AddOwnerRoleStateChange(role_name)

State change to add owner role to Community.

description_past_tense()

Returns the description of the state change object, in past tense.

description_present_tense()

Returns the description of the state change object, in present tense.

classmethod get_allowable_targets()

Returns the classes that an action of this type may target.

implement(actor, target)

Method that carries out the change of state.

validate(actor, target)

Method to check whether the data provided to a change object in an action is valid for the change object. Optional exclude_fields tells us not to validate the given field.

class concord.communities.state_changes.AddOwnerStateChange(owner_pk)

State change to add owner to Community.

description_past_tense()

Returns the description of the state change object, in past tense.

description_present_tense()

Returns the description of the state change object, in present tense.

classmethod get_allowable_targets()

Returns the classes that an action of this type may target.

implement(actor, target)

Method that carries out the change of state.

class concord.communities.state_changes.AddPeopleToRoleStateChange(role_name, people_to_add)

State change to add people to role in Community.

check_configuration(action, permission)

All configurations must pass for the configuration check to pass.

classmethod check_configuration_is_valid(configuration)

Used primarily when setting permissions, this method checks that the supplied configuration is a valid one. By contrast, check_configuration checks a specific action against an already-validated configuration.

description_past_tense()

Returns the description of the state change object, in past tense.

description_present_tense()

Returns the description of the state change object, in present tense.

classmethod get_allowable_targets()

Returns the classes that an action of this type may target.

classmethod get_configurable_fields()

Gets the fields of a change object which may be configured when used in a Permission model.

classmethod get_uninstantiated_description(**configuration_kwargs)

Takes in an arbitrary number of configuration kwargs and uses them to create a description. Does not reference fields passed on init.

implement(actor, target)

Method that carries out the change of state.

is_conditionally_foundational(action)

If role_name is owner or governor role, should should be treated as a conditional change.

validate(actor, target)

Method to check whether the data provided to a change object in an action is valid for the change object. Optional exclude_fields tells us not to validate the given field.

class concord.communities.state_changes.AddRoleStateChange(role_name)

State change to add role to Community.

description_past_tense()

Returns the description of the state change object, in past tense.

description_present_tense()

Returns the description of the state change object, in present tense.

classmethod get_allowable_targets()

Returns the classes that an action of this type may target.

implement(actor, target)

Method that carries out the change of state.

validate(actor, target)

Method to check whether the data provided to a change object in an action is valid for the change object. Optional exclude_fields tells us not to validate the given field.

class concord.communities.state_changes.ChangeNameStateChange(name)

State change to change name of Community.

description_past_tense()

Returns the description of the state change object, in past tense.

description_present_tense()

Returns the description of the state change object, in present tense.

classmethod get_allowable_targets()

Returns the classes that an action of this type may target.

implement(actor, target)

Method that carries out the change of state.

class concord.communities.state_changes.RemoveGovernorRoleStateChange(role_name)

State change to remove governor role from Community.

description_past_tense()

Returns the description of the state change object, in past tense.

description_present_tense()

Returns the description of the state change object, in present tense.

classmethod get_allowable_targets()

Returns the classes that an action of this type may target.

implement(actor, target)

Method that carries out the change of state.

class concord.communities.state_changes.RemoveGovernorStateChange(governor_pk)

State change to remove governor from Community.

description_past_tense()

Returns the description of the state change object, in past tense.

description_present_tense()

Returns the description of the state change object, in present tense.

classmethod get_allowable_targets()

Returns the classes that an action of this type may target.

implement(actor, target)

Method that carries out the change of state.

class concord.communities.state_changes.RemoveLeadershipConditionStateChange(*, leadership_type)

State change to remove leadership condition from Community.

description_past_tense()

Returns the description of the state change object, in past tense.

description_present_tense()

Returns the description of the state change object, in present tense.

classmethod get_allowable_targets()

Returns the classes that an action of this type may target.

implement(actor, target)

Method that carries out the change of state.

class concord.communities.state_changes.RemoveMembersStateChange(member_pk_list, self_only=False)

State change to remove members from Community.

classmethod check_configuration_is_valid(configuration)

Used primarily when setting permissions, this method checks that the supplied configuration is a valid one. By contrast, check_configuration checks a specific action against an already-validated configuration.

description_past_tense()

Returns the description of the state change object, in past tense.

description_present_tense()

Returns the description of the state change object, in present tense.

classmethod get_allowable_targets()

Returns the classes that an action of this type may target.

classmethod get_configurable_fields()

Gets the fields of a change object which may be configured when used in a Permission model.

implement(actor, target)

Method that carries out the change of state.

validate(actor, target)

If any of the members to be removed are an owner or governor (either directly, or through being in an owner or governor role) the action is not valid.

class concord.communities.state_changes.RemoveOwnerRoleStateChange(role_name)

State change to remove owner role from Community.

description_past_tense()

Returns the description of the state change object, in past tense.

description_present_tense()

Returns the description of the state change object, in present tense.

classmethod get_allowable_targets()

Returns the classes that an action of this type may target.

implement(actor, target)

Method that carries out the change of state.

validate(actor, target)

If removing the owner role would leave the group with no owners, the action is invalid.

class concord.communities.state_changes.RemoveOwnerStateChange(owner_pk)

State change remove owner from Community.

description_past_tense()

Returns the description of the state change object, in past tense.

description_present_tense()

Returns the description of the state change object, in present tense.

classmethod get_allowable_targets()

Returns the classes that an action of this type may target.

implement(actor, target)

Method that carries out the change of state.

validate(actor, target)

If removing the owner would leave the group with no owners, the action is invalid.

class concord.communities.state_changes.RemovePeopleFromRoleStateChange(role_name, people_to_remove)

State change to remove people from role in Community.

description_past_tense()

Returns the description of the state change object, in past tense.

description_present_tense()

Returns the description of the state change object, in present tense.

classmethod get_allowable_targets()

Returns the classes that an action of this type may target.

implement(actor, target)

Method that carries out the change of state.

is_conditionally_foundational(action)

If role_name is owner or governor role, should should be treated as a conditional change.

validate(actor, target)

When removing people from a role, we must check that doing so does not leave us without any owners.

class concord.communities.state_changes.RemoveRoleStateChange(role_name)

State change to remove role from Community.

description_past_tense()

Returns the description of the state change object, in past tense.

description_present_tense()

Returns the description of the state change object, in present tense.

classmethod get_allowable_targets()

Returns the classes that an action of this type may target.

implement(actor, target)

Method that carries out the change of state.

role_in_permissions(permission, actor)

Checks for role in permission and returns True if it exists. Checks in permissions which are nested on this permission as well.

validate(actor, target)

A role cannot be deleted without removing it from the permissions it’s referenced in, and without removing it from owner and governor roles if it is there.

Client

Client for Community models.

class concord.communities.client.CommunityClient(actor=None, target=None)

The target of a community client, if a target is required, is always a community model. As with all Concord clients, a target must be set for all methods not explicitly grouped as target-less methods.

add_governor(*, governor_pk: int) → Tuple[int, Any]

Add governor to community.

add_governor_role(*, governor_role: str) → Tuple[int, Any]

Add governor role tocommunity.

add_leadership_condition(*, condition_type, leadership_type, condition_data=None, permission_data=None)

Add condition to leadership type (owners or governors).

add_members(member_pk_list: list) → Tuple[int, Any]

Add members to community.

add_owner(*, owner_pk: int) → Tuple[int, Any]

Add owner tocommunity.

add_owner_role(*, owner_role: str) → Tuple[int, Any]

Add owner role to community.

add_people_to_role(*, role_name: str, people_to_add: list) → Tuple[int, Any]

Add people to role in community.

add_role(*, role_name: str) → Tuple[int, Any]

Add role to community.

change_name(*, new_name: str) → Tuple[int, Any]

Change name of community.

community_model

alias of concord.communities.models.Community

create_community(*, name: str) → concord.communities.models.Community

Creates a Community (or class descended from Community model) with actor as creator. Creates some additional structures by default but this can be overriden with bare=True.

get_communities()

Gets all communities with the model type specified on the client.

get_communities_for_user(user_pk, split=False)

Given a supplied user_pk, gets all communities the associated user is a part of. If arg ‘split’ is true, separates communities the user is a leader of from those they’re not a leader of.

get_community(*, community_name: str = None, community_pk: str = None) → concord.communities.models.Community

Takes either community name or PK and returns Community object. If both are supplied, returns Community object corresponding to community_pk.

get_condition_data(leadership_type, info='all') → dict

Gets condition data for conditions set on owners and governors.

get_custom_roles()

Gets all custom roles set on the community.

get_governance_info_as_text()

Gets governance info about the community as text.

get_governorship_info(shorten_roles=False) → dict

Get the governors of the community.

get_members() → list

Gets all members of the community as list of user instances.

get_owner(*, owned_object: django.db.models.base.Model) → concord.communities.models.Community

Gets the owner of the owned object, which should always be a community.

get_ownership_info(shorten_roles=False) → dict

Get the owners of the community.

get_role_names()

Get just the role names set on a community (no info on who has the roles).

get_roles()

Get all roles set on the community.

get_users_given_role(*, role_name: str)

Given the role name, get the users who have that role.

has_foundational_authority(*, actor) → bool

Returns True if actor has foundational authority, otherwise False.

has_governing_authority(*, actor) → bool

Returns True if actor has governing authority, otherwise False.

has_role_in_community(*, role: str, actor_pk: int) → bool

Returns True if actor has specific role in community. otherwise False.

remove_governor(*, governor_pk: int) → Tuple[int, Any]

Remove governor from community.

remove_governor_role(*, governor_role: str) → Tuple[int, Any]

Remove governor role from community.

remove_leadership_condition(*, leadership_type)

Remove condition from leadership type (owners or governors).

remove_members(member_pk_list: list) → Tuple[int, Any]

Remove members from community.

remove_owner(*, owner_pk: int) → Tuple[int, Any]

Remove owner from community.

remove_owner_role(*, owner_role: str) → Tuple[int, Any]

Remove owner role from community.

remove_people_from_role(*, role_name: str, people_to_remove: list) → Tuple[int, Any]

Remove people from role in community.

remove_role(*, role_name: str) → Tuple[int, Any]

Remove role from community.

set_target(target)

Sets target of the client. Accepts either a target model or the target’s pk and ct and fetches, in which case it fetches the model from the Database. Target must be a permissioned model.

set_target_community(*, community_name: str = None, community_pk: str = None)

Sets target community given a name or pk. If the user already has the community object, it can be set directly using the parent method set_target.

update_governors(*, new_governor_data)

Takes in a list of governors, adds those that are missing and removes those that are no longer there.

update_owners(*, new_owner_data)

Takes in a list of owners, adds those that are missing and removes those that are no longer there.

update_role_membership(*, role_data)

Takes in a list of roles with members, adds any missing members and adds any which are missing from community.

update_roles(*, role_data)

Takes in a list of roles and adds any which are missing from community.

Custom Fields

Defines customfields used in Community.

class concord.communities.customfields.RoleField(*args, **kwargs)

This custom field allows us to access the methods and validation of the RoleHandler object.

db_type(connection)

Return the database column data type for this field, for the provided connection.

deconstruct()

Return enough information to recreate the field as a 4-tuple:

• The name of the field on the model, if contribute_to_class() has been run.

• The import path of the field, including the class:e.g. django.db.models.IntegerField This should be the most portable version, so less specific may be better.

• A list of positional arguments.

• A dict of keyword arguments.

Note that the positional or keyword arguments must contain values of the following types (including inner values of collection types):

• None, bool, str, int, float, complex, set, frozenset, list, tuple, dict

• UUID

• datetime.datetime (naive), datetime.date

• top-level classes, top-level functions - will be referenced by their full import path

• Storage instances - these have their own deconstruct() method

This is because the values here must be serialized into a text format (possibly new Python code, possibly JSON) and these are the only types with encoding handlers defined.

There’s no need to return the exact way the field was instantiated this time, just ensure that the resulting field is the same - prefer keyword arguments over positional ones, and omit parameters with their default values.

get_prep_value(value)

Perform preliminary non-db specific value checks and conversions.

to_python(value)

Convert the input value into the expected Python data type, raising django.core.exceptions.ValidationError if the data can’t be converted. Return the converted value. Subclasses should override this.

class concord.communities.customfields.RoleHandler(*, members=None, owners=None, governors=None, custom_roles=None)

Every community has a list of roles, which are set community-wide. People with the relevant permissions can add and remove roles, and add or remove people from roles.

There are three protected names which cannot be used: owners, governors, and members.

A person cannot be added as owner, governor or custom role unless they’re already a member.

add_governor(pk)

Add governor given pk.

add_governor_role(role_name)

Add role as governor role given role_name.

add_member(pk)

Adds a member given member pk.

add_members(pk_list)

Adds a list of members given a list of pks.

add_owner(pk)

Add owner as governor given pk.

add_owner_role(role_name)

Add role as owner role given role_name.

add_people_to_role(role_name, people_to_add)

Add people to custom role. Protected roles are handled separately.

add_role(role_name)

Checks if role passed in already exists and, if not, adds to the list of roles. Roles that differ only by capitalization are not allowed.

get_custom_role_names()

Gets the names of custom roles only, but not protected roles.

get_custom_roles()

Gets custom roles only, but not protected roles.

get_governors(actors_only=False)

Gets all governors.

get_members()

Gets all members.

get_owners(actors_only=False)

Gets all owners.

get_role_names()

Gets names of all roles, including protected roles.

get_roles()

Gets all roles, including protected roles.

get_roles_given_user(pk)

Gets all roles in the group, given a user’s pk.

Note that this doesn’t catch when a user is owner/governor through custom roles.

get_users_given_role(role_name)

Gets all users with a given role.

has_governors()

Returns true if any governor is set on community, otherwise false.

has_specific_role(role_name, pk)

Checks whether a given user, specified by pk, has a role on the community, specified by role_name.

initialize_with_creator(creator)

To be valid, the RoleHandler must have at least one member and one owner. The most common use case is that the creator of a community is the only member and only owner upon initialization, which this help method allows us to accomplish. We also add the creator to the governors as well. Most commonly used after RoleHandler is initialized with no data passed in.

is_governor(pk)

Checks if user is an governor. Not a pure boolean since it’s helpful to know which (if any) role matched for permission pipeline logging.

is_member(pk)

Returns True if pk passed in is member, False if not.

is_owner(pk)

Checks if user is an owner. Not a pure boolean since it’s helpful to know which (if any) role matched for permission pipeline logging.

is_role(role_name)

Returns True if role_name passed in is a role on the community, False if not.

overwrite_roles(role_dict)

This method overwites existing roles and should only be used by the system, not the user.

remove_governor(pk)

Remove governor given pk.

remove_governor_role(role_name)

Remove role as governor role given role_name.

remove_member(pk)

Remove member given pk.

remove_members(pk_list)

Remove members given list of pks.

remove_owner(pk)

Remove owner given pk.

remove_owner_role(role_name)

Add role as owner role given role_name.

remove_people_from_role(role_name, people_to_remove)

Remove people from custom role. Protected roles are handled separately.

remove_role(role_name)

Removes the role passed in unless it is a protected role.

validate_custom_roles(custom_roles)

Custom roles dict should look like:

{ ‘knights’: [1,2,3], ‘rooks’: [2,3,4] }

All items in each list must correspond to members pks.

validate_governors(governors)

Governors dict should look like:

{ ‘actors’: [1,2,3], ‘roles’: [‘knights’, ‘bishops’, ‘rooks’] }

All actors must be members and all roles must be a protected role or custom role.

validate_members(members)

Members should be a list of integers. For now, we do not check that these are real users.

validate_owners(owners)

Owners dict should look like:

{ ‘actors’: [1,2,3], ‘roles’: [‘knights’, ‘bishops’, ‘rooks’] }

All actors must be members and all roles must be a protected role or custom role.

validate_role_handler()

Validates role handler by calling individual validate methods and verifying there’s at least one owner.

concord.communities.customfields.parse_role_handler_data(role_handler_data)

Parse role handler data when de-serializing.

Utilities