proknow.Roles

Roles

class proknow.Roles.Roles(proknow, requestor)

This class should be used to interact with the roles in a ProKnow organization. It is instantiated for you as an attribute of the proknow.ProKnow.ProKnow class.

create(name, description, permissions)

Creates a new role.

Parameters:

name (str) – The name of the role.
description (str) – The description of the role.
permissions (dict) – A dictionary of permissions. Note that the permissions dictionary does not have to include all permissions.

Returns:

A representation of the created item.

Return type:

proknow.Roles.RoleItem

Raises:

AssertionError – If the input parameters are invalid.
proknow.Exceptions.HttpError – If the HTTP request generated an error.

Example

This example creates a new role called “Renaming Rule Maintainer”:

from proknow import ProKnow

pk = ProKnow('https://example.proknow.com', credentials_file="./credentials.json")
pk.roles.create("Renaming Rule Maintainer", "Role description", {
    "renaming_rules_search": True,
    "renaming_rules_update": True,
    "renaming_rules_execute": True,
    "structure_set_templates_read": True
})

delete(role_id)

Deletes a role.

Parameters:

role_id (str) – The id of the role to delete.

Raises:

AssertionError – If the input parameters are invalid.
proknow.Exceptions.HttpError – If the HTTP request generated an error.

Example

If you know the role id, you can delete the role directly using this method:

from proknow import ProKnow

pk = ProKnow('https://example.proknow.com', credentials_file="./credentials.json")
pk.roles.delete('5c463a6c040068100c7f665acad17ac4')

find(predicate=None, **props)

Finds the first role that matches the input paramters.

Note

For more information on how to use this method, see Using Find Methods.

Parameters:

predicate (func) – A function that is passed a role as input and which should return a bool indicating whether the role is a match.
**props – A dictionary of keyword arguments that may include any role attribute. These arguments are considered in turn to find matching roles.

Returns:

A representation of the matching role.

Return type:

proknow.Roles.RoleItem

Raises:

proknow.Exceptions.HttpError – If the HTTP request generated an error.

get(role_id)

Gets a role.

Parameters:: role_id (str) – The id of the role to get.
Returns:: An object representing a role in the organization
Return type:: proknow.Roles.RoleItem
Raises:: proknow.Exceptions.HttpError – If the HTTP request generated an error.

Example

If you know the role id, you can get the role directly using this method:

from proknow import ProKnow

pk = ProKnow('https://example.proknow.com', credentials_file="./credentials.json")
renaming_rule_maintainer = pk.roles.get('5c463a6c040068100c7f665acad17ac4')

query()

Queries for roles.

Returns:: A list of proknow.Roles.RoleSummary objects, each representing a summarized role in the organization.
Return type:: list
Raises:: proknow.Exceptions.HttpError – If the HTTP request generated an error.

Example

This example queries the roles and prints the name of each role:

from proknow import ProKnow

pk = ProKnow('https://example.proknow.com', credentials_file="./credentials.json")
for role in pk.roles.query():
    print(role.name)

RoleSummary

class proknow.Roles.RoleSummary(roles, role)

This class represents a summary view of a role. It’s instantiated by the proknow.Roles.Roles.query() method to represent each of the roles returned in a query result.

id

The id of the role (readonly).

Type:: str

name

The name of the role (readonly).

Type:: str

description

The description of the role (readonly).

Type:: str

data

The summary representation of the role as returned from the API (readonly).

Type:: dict

get()

Gets the complete representation of the role.

Returns:: An object representing a role in the organization
Return type:: proknow.Roles.RoleItem
Raises:: proknow.Exceptions.HttpError – If the HTTP request generated an error.

Example

The following example shows how to turn a list of RoleSummary objects into a list of RoleItem objects:

from proknow import ProKnow

pk = ProKnow('https://example.proknow.com', credentials_file="./credentials.json")
roles = [role.get() for role in pk.roles.query()]

RoleItem

class proknow.Roles.RoleItem(roles, role)

This class represents a role. It’s instantiated by the proknow.Roles.Roles class as a complete representation of a role.

id

The id of the role (readonly).

Type:: str

name

The name of the role.

Type:: str

description

The description of the role.

Type:: str

permissions

The dictionary of role permissions.

Type:: dict

data

The complete representation of the role as returned from the API (readonly).

Type:: dict

delete()

Deletes the role.

Raises:: proknow.Exceptions.HttpError – If the HTTP request generated an error.

Example

The following example shows how to find a role by its name and delete it:

from proknow import ProKnow

pk = ProKnow('https://example.proknow.com', credentials_file="./credentials.json")
renaming_rule_maintainer = pk.roles.find(name='Renaming Rule Maintainer').get()
renaming_rule_maintainer.delete()

save()

Saves the changes made to a role.

Raises:: proknow.Exceptions.HttpError – If the HTTP request generated an error.

Example

The following example shows how to find a role by its name, modify a permission, and save it:

from proknow import ProKnow

pk = ProKnow('https://example.proknow.com', credentials_file="./credentials.json")
renaming_rule_maintainer = pk.roles.find(name='Renaming Rule Maintainer').get()
renaming_rule_maintainer.name = "new renaming rule maintainer name"
renaming_rule_maintainer.permissions["collections_read"] = True
renaming_rule_maintainer.save()