miracle-acl 0.0.4-1

add_role(role)

Define a role.

• role: the role to define.

The role will have no permissions granted, but will appear in get_roles().

acl.add_role('admin')
acl.get_roles()  # -> {'admin'}

add_roles(roles)

Define multiple roles

• roles: An iterable of roles

acl.add_roles(['admin', 'root'])
acl.get_roles()  # -> {'admin', 'root'}

add_resource(resource)

Define a resource.

• resources: the resource to define.

The resource will have no permissions defined but will appear in get_resources().

acl.add_resource('blog')
acl.get_resources()  # -> {'blog'}

add_permission(resource, permission)

Define a permission on a resource.

• resource: the resource to define the permission on. Is created if was not previously defined.

• permission: the permission to define.

The defined permission is not granted to anyone, but will appear in get_permissions(resource).

acl.add_permission('blog', 'post')
acl.get_permissions('blog')  # -> {'post'}

add(structure)

Define the whole resource/permission structure with a single dict.

• structure: a dict that maps resources to an iterable of permissions.

acl.add({
    'blog': ['post'],
    'page': {'create', 'read', 'update', 'delete'},
})

remove_role(role)

Remove the role and its grants.

• role: the role to remove.

acl.remove_role('admin')

remove_resource(resource)

Remove the resource along with its grants and permissions.

• resource: the resource to remove.

acl.remove_resource('blog')

remove_permission(resource, permission)

Remove the permission from a resource.

• resource: the resource to remove the permission from.

• permission: the permission to remove.

The resource is not implicitly removed: it remains with an empty set of permissions.

acl.remove_permission('blog', 'post')

clear()

Remove all roles, resources, permissions and grants.

get_roles()

Get the set of defined roles.

acl.get_roles()  # -> {'admin', 'anonymous', 'registered'}

get_resources()

Get the set of defined resources, including those with empty permissions set.

acl.get_resources()  # -> {'blog', 'page', 'article'}

get_permissions(resource)

Get the set of permissions for a resource.

• resource: the resource to get the permissions for.

acl.get_permissions('page')  # -> {'create', 'read', 'update', 'delete'}

get()

Get the structure: hash of all resources mapped to their permissions.

Returns a dict: { resource: set(permission,...), ... }.

acl.get()  # -> { blog: {'post'}, page: {'create', ...} }

grant(role, resource, permission)

Grant a permission over resource to the specified role.

• role: The role to grant the access to

• resource: The resource to grant the access over

• permission: The permission to grant with

Roles, resources and permissions are implicitly created if missing.

acl.grant('admin', 'blog', 'delete')
acl.grant('anonymous', 'page', 'view')

grants(grants)

Add a structure of grants to the Acl.

• grants: A hash in the following form: { role: { resource: set(permission) } }.

acl.grants({
    'admin': {
        'blog': ['post'],
    },
    'anonymous': {
        'page': ['view']
    }
})

revoke(role, resource, permission)

Revoke a permission over a resource from the specified role.

acl.revoke('anonymous', 'page', 'view')
acl.revoke('user', 'account', 'delete')

revoke_all(role[, resource])

Revoke all permissions from the specified role for all resources. If the optional resource argument is provided - removes all permissions from the specified resource.

acl.revoke_all('anonymous', 'page')  # revoke all permissions from a single resource
acl.revoke_all('anonymous')  # revoke permissions from all resources

check(role, resource, permission)

Test whether the given role has access to the resource with the specified permission.

• role: The role to check

• resource: The protected resource

• permission: The required permission

Returns a boolean.

acl.check('admin', 'blog') # True
acl.check('anonymous', 'page', 'delete') # -> False

check_any(roles, resource, permission)

Test whether any of the given roles have access to the resource with the specified permission.

• roles: An iterable of roles.

When no roles are provided, returns False.

check_all(roles, resource, permission)

Test whether all of the given roles have access to the resource with the specified permission.

• roles: An iterable of roles.

When no roles are provided, returns False.

which_permissions(role, resource)

List permissions that the provided role has over the resource:

acl.which_permissions('admin', 'blog')  # -> {'post'}

which_permissions_any(roles, resource)

List permissions that any of the provided roles have over the resource:

acl.which_permissions_any(['anonymous', 'registered'], 'page')  # -> {'view'}

which_permissions_all(roles, resource)

List permissions that all of the provided roles have over the resource:

acl.which_permissions_all(['anonymous', 'registered'], 'page')  # -> {'view'}

which(role)

Collect grants that the provided role has:

acl.which('admin')  # -> { blog: {'post'} }

which_any(roles)

Collect grants that any of the provided roles have (union).

acl.which(['anonymous', 'registered'])  # -> { page: ['view'] }

which_all(roles)

Collect grants that all of the provided roles have (intersection):

acl.which(['anonymous', 'registered'])  # -> { page: ['view'] }

show()

Get all current grants.

Returns a dict { role: { resource: set(permission) } }.

acl.show()  # -> { admin: { blog: ['post'] } }