This is a pre-production deployment of Warehouse, however changes made here WILL affect the production instance of PyPI.
Latest Version Dependencies status unknown Test status unknown Test coverage unknown
Project Description

Miracle

Miracle is an ACL for Python that was designed to be well-structuted, simple yet exhaustive. It uses permissions defined on resources, and roles are 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 by miracle for NodeJS ;
  • Simple core
  • No restrictions on authorization entities
  • Unit-tested

Table of Contents

  • Define The Structure
    • Acl
    • Create
      • add_role(role)
      • add_roles(roles)
      • add_resource(resource)
      • add_permission(resource, permission)
      • add(structure)
    • Remove
      • remove_role(role)
      • remove_resource(resource)
      • remove_permission(resource, permission)
      • clear()
    • Get
      • get_roles()
      • get_resources()
      • get_permissions(resource)
      • get()
    • Export and Import
  • Authorize
    • Grant Permissions
      • grant(role, resource, permission)
      • grants(grants)
      • revoke(role, resource, permission)
      • revoke_all(role[, resource])
    • Check Permissions
      • check(role, resource, permission)
      • check_any(roles, resource, permission)
      • check_all(roles, resource, permission)
    • Show Grants
      • which_permissions(role, resource)
      • which_permissions_any(roles, resource)
      • which_permissions_all(roles, resource)
      • which(role)
      • which_any(roles)
      • which_all(roles)
      • show()

Define The Structure

Acl

To start using miracle, instantiate the Acl object:

from acl import Acl
acl = Acl()

The Acl object keeps track of your resources and permissions defined on them, handles grants over roles and provides utilities to manage them. When configured, you can check the access against the defined state.

Create

Methods from this section allow you to build the structure: list of roles, resources and permissions.

It’s not required that you have the structure defined before you start granting the access: the grant() method implicitly creates all resources and permissions that were not previously defined.

Start with defining the resources and permissions on them, then you can grant a role with 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 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

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

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', ...} }

Export and Import

The Acl class is picklable:

acl = miracle.Acl()
save = acl.__getstate__()

#...

acl = miracle.Acl()
acl.__setstate__(save)

Authorize

Grant Permissions

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 Permissions

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.

Show Grants

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'] } }
Release History

Release History

0.0.4-1

This version

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

0.0.4-0

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

0.0.3

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

0.0.2

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

0.0.1

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

Download Files

Download Files

TODO: Brief introduction on what you do with files - including link to relevant help section.

File Name & Checksum SHA256 Checksum Help Version File Type Upload Date
miracle_acl-0.0.4_1-py2-none-any.whl (9.9 kB) Copy SHA256 Checksum SHA256 2.7 Wheel Aug 14, 2014
miracle-acl-0.0.4-1.tar.gz (9.7 kB) Copy SHA256 Checksum SHA256 Source Aug 14, 2014

Supported By

WebFaction WebFaction Technical Writing Elastic Elastic Search Pingdom Pingdom Monitoring Dyn Dyn DNS HPE HPE Development Sentry Sentry Error Logging CloudAMQP CloudAMQP RabbitMQ Heroku Heroku PaaS Kabu Creative Kabu Creative UX & Design Fastly Fastly CDN DigiCert DigiCert EV Certificate Rackspace Rackspace Cloud Servers DreamHost DreamHost Log Hosting