Package: miracle-acl
MiracleMiracle is an ACL for Python that was designed to be well-structuted,
simple yet exhaustive. It usespermissionsdefined onresources, androlesare granted with the access to them.To be a universal tool, it does not include any special cases, does not
force you to persist and does not insist on any formats or conventions.Maximum flexibility and total control. Enjoy! :)Highlights:Inspired bymiraclefor NodeJS ;Simple coreNo restrictions on authorization entitiesUnit-testedTable of ContentsDefine The StructureAclCreateadd_role(role)add_roles(roles)add_resource(resource)add_permission(resource, permission)add(structure)Removeremove_role(role)remove_resource(resource)remove_permission(resource, permission)clear()Getget_roles()get_resources()get_permissions(resource)get()Export and ImportAuthorizeGrant Permissionsgrant(role, resource, permission)grants(grants)revoke(role, resource, permission)revoke_all(role[, resource])Check Permissionscheck(role, resource, permission)check_any(roles, resource, permission)check_all(roles, resource, permission)Show Grantswhich_permissions(role, resource)which_permissions_any(roles, resource)which_permissions_all(roles, resource)which(role)which_any(roles)which_all(roles)show()Define The StructureAclTo start using miracle, instantiate theAclobject:fromaclimportAclacl=Acl()TheAclobject keeps track of yourresourcesandpermissionsdefined on them, handlesgrantsoverrolesand provides utilities to
manage them. When configured, you can check the access against the
defined state.CreateMethods from this section allow you to build thestructure: list of
roles, resources and permissions.It’s not required that you have the structure defined before you start
granting the access: thegrant()method implicitly creates all
resources and permissions that were not previously defined.Start with defining theresourcesandpermissionson them, then you
can grant arolewith the access to some permissions on a resource.For roles, resources & permissions, any hashable objects will do.add_role(role)Define a role.role: the role to define.The role will have no permissions granted, but will appear inget_roles().acl.add_role('admin')acl.get_roles()# -> {'admin'}add_roles(roles)Define multiple rolesroles: An iterable of rolesacl.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 inget_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 inget_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'},})Removeremove_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.Getget_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 thestructure: hash of all resources mapped to their permissions.Returns a dict:{ resource:set(permission,...),... }.acl.get()# -> { blog: {'post'}, page: {'create', ...} }Export and ImportTheAclclass is picklable:acl=miracle.Acl()save=acl.__getstate__()#...acl=miracle.Acl()acl.__setstate__(save)AuthorizeGrant Permissionsgrant(role, resource, permission)Grant a permission over resource to the specified role.role: The role to grant the access toresource: The resource to grant the access overpermission: The permission to grant withRoles, 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
optionalresourceargument is provided - removes all permissions
from the specified resource.acl.revoke_all('anonymous','page')# revoke all permissions from a single resourceacl.revoke_all('anonymous')# revoke permissions from all resourcesCheck Permissionscheck(role, resource, permission)Test whether the given role has access to the resource with the
specified permission.role: The role to checkresource: The protected resourcepermission: The required permissionReturns a boolean.acl.check('admin','blog')# Trueacl.check('anonymous','page','delete')# -> Falsecheck_any(roles, resource, permission)Test whetheranyof 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 whetherallof the given roles have access to the resource with
the specified permission.roles: An iterable of roles.When no roles are provided, returns False.Show Grantswhich_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'] } }