grainy.core

core functionality

Functions

int_flags

def int_flags(flags, mapper=[(4, 'c'), (1, 'r'), (2, 'u'), (8, 'd')])

Converts string permission flags into integer permission flags as specified in const.PERM_STRING_MAP

Arguments

  • flags (str): one or more flags For example: "crud" or "ru" or "r"
  • mapper (list=const.PERM_STRING_MAP): a list containing tuples mapping int permission flag to string permission flag. If not specified will default to const.PERM_STRING_MAP.

Returns

int

Classes

Applicator

Applicator(builtins.object)

Handles application of permissions to a dataset contained in a dict

Any data that is not permissioned to be read will be removed during application of permissions.

Methods

__init__

def __init__(self, pset)

Initialize self. See help(type(self)) for accurate signature.

apply

def apply(self, data, path=None)

Apply permissions in this set to the provided data, effectively removing all keys from it are not permissioned to be viewed

Arguments

  • data (dict)

Returns

dict: cleaned data

Namespace

Namespace(builtins.object)

Object representing a permissioning namespace

Instanced Attributes

These attributes / properties will be available on instances of the class

  • keys (list<str>): namespace keys
  • length (int): namespace key length, number of keys in the namespace
  • value (str): namespace

Methods

__eq__

def __eq__(self, other)

Return self==value.

__hash__

def __hash__(self)

Return hash(self).

__init__

def __init__(self, value, strip=True)

Arguments

  • value (list<str>|str): can either be a list containing namespace keys or a str with keys delimited by the . character

__str__

def __str__(self)

Return str(self).

container

def container(self, data=None)

Creates a dict built from the keys of this namespace

Example
self.value = "a.b.c"

container, tail = self.container()
#{"a":{"b":{"c":{}}}, {}

container, tail = self.container({"d":123})
#{"a":{"b":{"c":{"d":123}}}, {"d":123}

Keyword Arguments

  • data (dict): use this as root dict

Returns

tuple(<dict>,<dict>): a tuple containing the root of the generated dict as the first element and the tail of the generated dict as the second element

match

def match(self, keys, partial=True)

Check if the value of this namespace is matched by keys

Wildcards

You can use the * character as a wildcard match for keys

Examples
ns = Namespace("a.b.c")
ns.match(["a"]) #True
ns.match(["a","b"]) #True
ns.match(["a","b","c"]) #True
ns.match(["a","*","c"]) #True
ns.match(["b","b","c"]) #False

Arguments

  • keys (list): list of keys

Keyword Arguments

  • partial (bool=True): allow partial matching

Returns

bool: True if matched, False if not

set

def set(self, value, strip=True)

Set the namespace value

This is called automatically during init

Arguments

  • value (list<str>|str): can either be a list containing namespace keys or a str with keys delimited by the . character

NamespaceKeyApplicator

NamespaceKeyApplicator(grainy.core.Applicator)

Applicator that looks for permission namespaces from a specified field in the dict it is scanning

Methods

apply

def apply(self, data, **kwargs)

Apply permissions in this set to the provided data, effectively removing all keys from it are not permissioned to be viewed

Arguments

  • data (dict)

Returns

dict: cleaned data

Permission

Permission(builtins.object)

Permission object defined by a namespace and a permission bitmask

Instanced Attributes

These attributes / properties will be available on instances of the class

  • namespace (Namespace)
  • value (int): permission mask

Methods

__eq__

def __eq__(self, other)

Return self==value.

__init__

def __init__(self, namespace, value)

Arguments

  • namespace (str|Namespace)
  • value (int): permission mask

check

def check(self, level)

Check if permission mask contains the specified permission level

Arguments

  • level (int): permission flag

Returns

bool: True if flag is contained in mask, False if not

has_value

def has_value(self)

Check that value has been set

Returns

bool: True if value has been set, False if not

PermissionSet

PermissionSet(builtins.object)

Holds a set of Namespaces and permissions to run permission checks on

Can also be applied to a data dict to remove keys that are not accessible according the permissions in the set

Instanced Attributes

These attributes / properties will be available on instances of the class

  • index (dict): permission index
  • namespaces (@property): list of all namespaces registered in this permission set
  • permissions (dict): permissions in this set
  • read_access_map (dict)

Methods

__init__

def __init__(self, rules=None)

Keyword Arguments

  • rules (list<Permission>|dict<str,int>): list of Permission objects or dict of namspace(str):permission(int) pairs

apply

def apply(self, data, path=None, applicator=None)

Apply permissions in this set to the provided data, effectively removing all keys from it are not permissioned to be viewed

Arguments

  • data (dict)

Keyword Arguments

  • applicator (Applicator=None): allows you to specify the applicator instance to use. If none is specified an instance of Applicator will be used.

Returns

dict: cleaned data

check

def check(self, namespace, level, explicit=False)

Checks if the permset has permission to the specified namespace at the specified level

Arguments

  • namespace (str): permissioning namespace
  • level (int): permission flag, PERM_READ for example

Keyword Arguments

  • explicit (bool=False): require explicitly set permissions to the provided namespace

Returns

bool: True if permissioned False if not

expand

def expand(self, namespace, explicit=False, index=None, path=None, length=0, exact=False)

Expands "?" parts of a namespace into a list of namespaces

Arguments

  • namespace (str): permissioning namespace

Returns

  • list: list of namespaces

expandable

def expandable(self, namespace)

Returns whether or not the submitted namespace is expandable.

An expandable namespace is any namespace that contains "?" keys.

Arguments

  • namespace (str): permissioning namespace

Returns

  • bool

get_permissions

def get_permissions(self, namespace, explicit=False)

Returns the permissions level for the specified namespace

Arguments

  • namespace (str): permissioning namespace

Keyword Arguments

  • explicit (bool=False): require explicitly set permissions to the provided namespace

Returns

int: permission mask

update

def update(self, permissions, override=True)

Update the permissionset with a dict of namespace:permission pairs

Examples
pset.update(
  {
    "a" : const.PERM_READ,
    "b" : Permission("b", const.PERM_RW)
  }
)

Arguments

  • permissions (dict): dict mapping namespaces (str) to permission (Permission or int)
  • override (bool=True): if True will override existing namespaces if they exist

update_index

def update_index(self)

Regenerates the permission index for this set

Called everytime a rule is added / removed / modified in the set