Autodocumentation of the Permissions (permission_resources) module¶

Models¶

Permission Resource models.

class concord.permission_resources.models.PermissionsItem(*args, **kwargs)¶

Permission items contain data for who may change the state of the linked object in a given way.

content_type, object_id, permitted object -> specify what object the permission is set on change_type -> specifies what action the permission covers

actors -> individually listed people roles -> reference to roles specified in community

If someone matches an actor OR a role they have the permission. actors are checked first.

exception DoesNotExist¶

exception MultipleObjectsReturned¶

actor_in_permission(actor)¶: Check if actor is in the permission, either as individual or as role. Returns Boolean plus the role if in permission via role, otherwise returns None.

add_role_to_permission(*, role: str)¶: Add a role to the permission.

change_display_string()¶: Helper method for displaying the change element of permissions.

display_string()¶: Helper method for displaying permissions.

get_actors(as_instances=False)¶: Get the actors that have the permission.

get_all_context_keys()¶: Helper method to get context keys for the change type.

get_change_fields()¶: Helper method used to get a list of required fields for init of this permission’s change type.

get_change_type()¶: Get the ChangeType (short version) of the permission.

get_condition_data(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_configuration()¶: Get the configuration of the permissoin.

get_configured_field_data()¶: Get the field data corresponding to the configuration.

get_name()¶: Get permission name.

get_nested_objects()¶

Gets objects that the model is nested within.

Nested objects are often things like the owner of instance or, for example, a forum that a post is posted within.

Called by the permissions pipeline in permissions.py.

get_permitted_object()¶: Gets the permitted object, that is the permissioned model that the permission is set on.

get_roles()¶: Get the roles that have the permission.

get_state_change_object()¶: Get the state change object associated with the change_type of the permission.

has_condition()¶: Returns True if PermissionsItem has condition, otherwise False.

has_role(*, role: str)¶: Check if a given role has the permission.

match_actor(actor_pk)¶: Determines if actor in the permission. If inverse is toggled, returns the oppposite - such that they would NOT match if they’re listed in an inverse permission.

match_change_type(change_type)¶: Checks if the given change type matches the PermissionItem’s change_type.

remove_role_from_permission(*, role: str)¶: Remove a role from the permission.

set_configuration(configuration_dict)¶: Set the configuration of the permission.

set_fields(*, owner=None, permitted_object=None, anyone=None, change_type=None, inverse=None, actors=None, roles=None, configuration=None)¶: Helper method to make it easier to save permissions fields in the format our model expects.

concord.permission_resources.models.delete_empty_permission(sender, instance, created, **kwargs)¶: Toggle is_active so it is only true when there are actors or roles set on the permission.

State Changes¶

Get state changes for permissions resources.

class concord.permission_resources.state_changes.AddActorToPermissionStateChange(*, actor_to_add: str)¶

State change to add an actor to a permission.

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_settable_classes()¶: Returns the classes that a permission with this change type may be set on. This overlaps with allowable targets, but also includes classes that allowable targets may be nested on. Most likely called by the validate method in AddPermissionStateChange.

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.permission_resources.state_changes.AddPermissionConditionStateChange(*, condition_type, condition_data, permission_data)¶

State change to add a condition to a permission.

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, permission)¶: Helper method with template generation logic, since we’re using it in both validate and implement. The actions below are stored within the template, and copied+instantiated when a separate action triggers the permission to do so.

classmethod get_allowable_targets()¶: Returns the classes that an action of this type may target.

classmethod get_settable_classes()¶: Returns the classes that a permission with this change type may be set on. This overlaps with allowable targets, but also includes classes that allowable targets may be nested on. Most likely called by the validate method in AddPermissionStateChange.

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.permission_resources.state_changes.AddPermissionStateChange(change_type, actors, roles, configuration=None, anyone=False, inverse=False)¶

State change to add a permission to something.

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.

implement(actor, target)¶: Method that carries out the change of state.

input_target¶: alias of concord.permission_resources.models.PermissionsItem

is_conditionally_foundational(action)¶: Some state changes are only foundational in certain conditions. Those state changes override this method to apply logic and determine whether a specific instance is foundational or not.

validate(actor, target)¶: We need to check configuration of permission is valid. Also need to check that the given permission can be set on the target.

class concord.permission_resources.state_changes.AddRoleToPermissionStateChange(*, role_name: str)¶

State change to add a role to a permission.

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_settable_classes()¶: Returns the classes that a permission with this change type may be set on. This overlaps with allowable targets, but also includes classes that allowable targets may be nested on. Most likely called by the validate method in AddPermissionStateChange.

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.permission_resources.state_changes.ChangeInverseStateChange(*, change_to: bool)¶

State change to toggle the inverse field of a permission.

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_settable_classes()¶: Returns the classes that a permission with this change type may be set on. This overlaps with allowable targets, but also includes classes that allowable targets may be nested on. Most likely called by the validate method in AddPermissionStateChange.

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.permission_resources.state_changes.ChangePermissionConfigurationStateChange(*, configurable_field_name: str, configurable_field_value: str)¶

State change to change the configuration of a permission.

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_settable_classes()¶: Returns the classes that a permission with this change type may be set on. This overlaps with allowable targets, but also includes classes that allowable targets may be nested on. Most likely called by the validate method in AddPermissionStateChange.

implement(actor, target)¶: Method that carries out the change of state.

class concord.permission_resources.state_changes.DisableAnyoneStateChange¶

State change which takes a permission that has ‘anyone’ enabled, so anyone can take it, and disables it so only the roles and actors specified can take it..

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_settable_classes()¶: Returns the classes that a permission with this change type may be set on. This overlaps with allowable targets, but also includes classes that allowable targets may be nested on. Most likely called by the validate method in AddPermissionStateChange.

implement(actor, target)¶: Method that carries out the change of state.

class concord.permission_resources.state_changes.EditTemplateStateChange(template_object_id, field_name, new_field_data)¶

State change to edit a template.

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_settable_classes()¶: Returns the classes that a permission with this change type may be set on. This overlaps with allowable targets, but also includes classes that allowable targets may be nested on. Most likely called by the validate method in AddPermissionStateChange.

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.permission_resources.state_changes.EnableAnyoneStateChange¶

State change to set a permission so anyone can take it.

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_settable_classes()¶: Returns the classes that a permission with this change type may be set on. This overlaps with allowable targets, but also includes classes that allowable targets may be nested on. Most likely called by the validate method in AddPermissionStateChange.

implement(actor, target)¶: Method that carries out the change of state.

class concord.permission_resources.state_changes.RemoveActorFromPermissionStateChange(*, actor_to_remove: str)¶

State change to remove an actor from a permission.

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_settable_classes()¶: Returns the classes that a permission with this change type may be set on. This overlaps with allowable targets, but also includes classes that allowable targets may be nested on. Most likely called by the validate method in AddPermissionStateChange.

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.permission_resources.state_changes.RemovePermissionConditionStateChange¶

State change to remove a condition from a permission.

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_settable_classes()¶: Returns the classes that a permission with this change type may be set on. This overlaps with allowable targets, but also includes classes that allowable targets may be nested on. Most likely called by the validate method in AddPermissionStateChange.

implement(actor, target)¶: Method that carries out the change of state.

class concord.permission_resources.state_changes.RemovePermissionStateChange¶

State change to remove a permission from something.

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_settable_classes()¶: Returns the classes that a permission with this change type may be set on. This overlaps with allowable targets, but also includes classes that allowable targets may be nested on. Most likely called by the validate method in AddPermissionStateChange.

implement(actor, target)¶: Method that carries out the change of state.

class concord.permission_resources.state_changes.RemoveRoleFromPermissionStateChange(*, role_name: str)¶

State change to remove a role from a permission.

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_settable_classes()¶: Returns the classes that a permission with this change type may be set on. This overlaps with allowable targets, but also includes classes that allowable targets may be nested on. Most likely called by the validate method in AddPermissionStateChange.

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.

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.

Client¶

Client for permissions

class concord.permission_resources.client.PermissionResourceClient(actor=None, target=None)¶

Client for interacting with Permission resources. Target is usually the PermissionedModel that we’re setting permissions on, but is occasionally the PermissionedModel itself.

actor_satisfies_permission(*, actor, permission: concord.permission_resources.models.PermissionsItem) → bool¶: Returns True if given actor satisfies given permission.

add_actor_to_permission(*, actor: str) → Tuple[int, Any]¶: Add actor to permission.

add_condition_to_permission(*, condition_type, condition_data=None, permission_data=None)¶: Add a condition to the permission.

add_permission(*, permission_type: str, permission_actors: list = None, permission_roles: list = None, permission_configuration: dict = None, anyone=False) → Tuple[int, Any]¶: Add permission to target.

add_role_to_permission(*, role_name: str) → Tuple[int, Any]¶: Add role to permission.

change_configuration_of_permission(*, configurable_field_name: str, configurable_field_value: str) → Tuple[int, Any]¶: Change the configuration of the permission.

change_inverse_field_of_permission(*, change_to: bool) → Tuple[int, Any]¶: Toggle the inverse field on the permission.

get_all_permissions() → concord.permission_resources.models.PermissionsItem¶: Get all permissions on the client target.

get_all_permissions_in_db()¶: Gets all permissions in the DB. We should swap this out with getting all permissions in a group plus all of its owned objects but for now, this is what we have.

get_condition_data(info='all') → dict¶: Get condition data on the target.

get_permission(*, pk: int) → concord.permission_resources.models.PermissionsItem¶: Gets permissions item given pk.

get_permissions_associated_with_actor(actor: int) → List[concord.permission_resources.models.PermissionsItem]¶: Given an actor, get all permissions on the target they are listed as an individual actor within.

get_permissions_associated_with_role_for_target(*, role_name: str) → List[concord.permission_resources.models.PermissionsItem]¶: Get any permissions on the target associated with the given role.

get_permissions_for_role(*, role_name)¶: Given a role, get all permissions associated with it.

get_permissions_on_object(*, target_object: django.db.models.base.Model) → concord.permission_resources.models.PermissionsItem¶: Given a target object, get all permissions set on it.

get_roles_associated_with_permission(*, permission_pk: int)¶: Given a permission, get all roles set on it.

get_settable_permissions(return_format='tuples') → List[Tuple[str, str]]¶: Gets a list of permissions it is possible to set on the target, in various formats

get_settable_permissions_for_model(model_class)¶: Given a model class (or, optionally, an instance of a model class), gets the state change objects which may be set on that model via a permission.

get_specific_permissions(*, change_type: str) → concord.permission_resources.models.PermissionsItem¶: Get all permissions on the client target matching the given change_type.

give_anyone_permission()¶: Make it so everyone has the permission.

has_permission(client, method_name, parameters, exclude_conditional=False)¶: Checks results of running a given (mock) action through the permissions pipeline. Note that this says nothing about whether the given action is valid, as the validate step is called separately.

remove_actor_from_permission(*, actor: str) → Tuple[int, Any]¶: Remove actor from permission.

remove_anyone_from_permission()¶: Remove the ability for everyone to have the permission.

remove_condition_from_permission()¶: Remove a condition from the permission.

remove_permission() → Tuple[int, Any]¶: Remove permission from target.

remove_role_from_permission(*, role_name: str) → Tuple[int, Any]¶: Remove role from permission.

update_actors_on_permission(*, actor_data, permission)¶: Given a list of actors, updates the given permission to match those actors.

update_configuration(*, configuration_dict: dict, permission)¶: Given a dict with the new configuration for a permission, change individual fields as needed.

update_roles_on_permission(*, role_data, permission)¶: Given a list of roles, updates the given permission to match those roles.

Custom Fields¶

Custom Fields used by Permission Resource models.

class concord.permission_resources.customfields.ActorList(actor_list=None)¶

This custom object allows us to preferentially manipulate our actors as a list of PKs, so we don’t have to constantly query the DB. If pks and instances are not identical, the pk_list is assumed authoritative.

actor_in_list(actor)¶: Checks if a given actor is in the actor list.

add_actors(actors)¶: If actors are User instances, add to instance_list and pk_list; if pks, add only to pk_list.

as_instances()¶: Get actors as instances, checking first to make sure the list of instances is the same length as pks.

as_pks()¶: Get actors as pk.

is_empty()¶: Returns true if there’s no actors in lists.

lists_are_equivalent()¶: Helper method to check that pk_list and instance_list are equivalent.

remove_actors(actors, strict=True)¶: If actors are user instances, remove from instance_list and pk_list; if pks, remove only from pk_list. If strict is true, all actors to be removed MUST be in the pk_list.

class concord.permission_resources.customfields.ActorListField(*args, **kwargs)¶

This custom field allows us to access a list of user objects or a list of user pks, depending on our needs.

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.permission_resources.customfields.RoleList(role_list=None)¶

Helper object to manage roles set in permission.

add_roles(role_list)¶: Add roles to role_list.

get_roles()¶: Gets role list.

is_empty()¶: Returns True if role_list is empty.

remove_roles(role_list)¶: Remove roles from role_list.

role_name_in_list(role_name)¶: Returns true if given role_name in role list.

class concord.permission_resources.customfields.RoleListField(*args, **kwargs)¶

This custom field allows us to access our list of role pairs.

db_type(connection)¶: Return the database column data type for this field, for the provided connection.