users package

The users package manages the models and the API about users, groups and capabilities. Note that this package does not specify permissions for objects. Actual permissions are handled at the UI level.

The main concepts are:

  • A User is what you think it is; something that you can login as.
  • A Group is a collection of users. Note that a user can belong to multiple groups. A group has capabilities.
  • A Capability is a “granted permission”. You can think of it like a piece of paper saying, ie. “you can create new attachments”.
    • Its action is a composition of Create, Read, Update, Delete (it follows the CRUD model).
    • A domain is a regular expression that must “match” to the description of an object. ie. /cars/* means “every car”, while /cars/*/tires/ means “the tires of every car”

This also means that a user has no capability (directly). It just belongs to groups, which, in turn, have capabilities.

The rationale behind what a Capability is may seem baroque, but there are several advantages to it:

  • it is decoupled from the actual domains used by the UI
  • the regular expression make it possible to create groups that can operate on everything (*).
class users.SqliteFKDatabase(database, pragmas=None, *args, **kwargs)[source]

Bases: peewee.SqliteDatabase

SqliteDatabase with foreignkey support enabled

initialize_connection(conn)[source]
users.create_tables(database)[source]

Create all tables in the given database

users.gen_crypt_context(salt_size=None, rounds=None)[source]
users.init_db(dbURL, pwd_salt_size=None, pwd_rounds=None)[source]

Initialize users database

initialize database and create necessary tables to handle users oprations.

Parameters:dbURL – database url, as described in init_proxy()
users.init_proxy(dbURL)[source]

Instantiate proxy to the database

Parameters:dbURL

the url describing connection parameters to the choosen database. The url must have format explained in the Peewee url documentation.

examples:
  • sqlite: sqlite:///my_database.db
  • postgres: postgresql://postgres:my_password@localhost:5432/my_database
  • mysql: mysql://user:passwd@ip:port/my_db
users.populate_with_defaults()[source]

Create user admin and grant him all permission

If the admin user already exists the function will simply return

Submodules

exception users.api.ConflictException[source]

Bases: exceptions.Exception

exception users.api.NotFoundException[source]

Bases: exceptions.Exception

users.api.add_capability(domain, action, simplified=True)[source]
users.api.add_capability_to_group(capID, groupID)[source]
users.api.add_group(name)[source]
users.api.add_user(name, password)[source]
users.api.add_user_to_group(userID, groupID)[source]
users.api.delete_capability(capID)[source]
users.api.delete_group(id)[source]
users.api.delete_user(id)[source]
users.api.get_anonymous_user()[source]
users.api.get_capabilities()[source]
users.api.get_capabilities_of_group(groupID)[source]
users.api.get_capability(capID)[source]
users.api.get_group(id=None, name=None)[source]
users.api.get_groups()[source]
users.api.get_groups_of_user(userID)[source]
users.api.get_groups_with_capability(capID)[source]
users.api.get_user(id=None, name=None)[source]
users.api.get_users()[source]
users.api.get_users_in_group(groupID)[source]
users.api.is_anonymous(user)[source]
users.api.remove_capability_from_group(capID, groupID)[source]
users.api.remove_user_from_group(userID, groupID)[source]
users.api.update_capability(id, updates)[source]
users.api.update_group(id, updates)[source]
users.api.update_user(id, updates)[source]
class users.models.Action[source]

Bases: int

Actions utiliy class

You can use this class attributes to compose the actions bitmask::
bitmask = Action.CREATE | Action.DELETE
The following actions are supported:
  • CREATE
  • READ
  • UPDATE
  • DELETE
ACTIONS = ['CREATE', 'READ', 'UPDATE', 'DELETE']
CREATE = 1
DELETE = 8
READ = 2
UPDATE = 4
classmethod action_bitmask(action)[source]

return the bitmask associated withe the given action name

classmethod from_list(actions)[source]

convert list of actions into the corresponding bitmask

to_list()[source]

convert an actions bitmask into a list of action strings

class users.models.ActionField(null=False, index=False, unique=False, verbose_name=None, help_text=None, db_column=None, default=None, choices=None, primary_key=False, sequence=None, constraints=None, schema=None)[source]

Bases: peewee.IntegerField

db_field = 'action'
db_value(value)[source]
python_value(value)[source]
class users.models.BaseModel(*args, **kwargs)[source]

Bases: peewee.Model

DoesNotExist

alias of BaseModelDoesNotExist

id = <peewee.PrimaryKeyField object>
to_dict()[source]
class users.models.Capability(*args, **kwargs)[source]

Bases: users.models.BaseModel

Capability model

A capability is composed by a domain and an action. It represent the possibility to perform a specific set of actions on the resources described by the domain

domain

is a regular expression that describe all the resources involved in the capability. You can use simToReg() and regToSim() utility function to easily manipulate domain regular expressions.

action

an ActionField what can be done on domain

DoesNotExist

alias of CapabilityDoesNotExist

action = <users.models.ActionField object>
domain = <peewee.CharField object>
groups = <playhouse.fields.ManyToManyField object>
grouptocapability_set

Back-reference to expose related objects as a SelectQuery.

id = <peewee.PrimaryKeyField object>
match(dom, act)[source]

Check if the given domain and act are allowed by this capability

match_action(act)[source]

Check if the given act is allowed from this capability

match_domain(dom)[source]

Check if the given dom is included in this capability domain

classmethod regToSim(reg)[source]

Convert regular expression to simplified domain expression

classmethod simToReg(sim)[source]

Convert simplified domain expression to regular expression

to_dict()[source]
class users.models.Group(*args, **kwargs)[source]

Bases: users.models.BaseModel

Group model

A group has a set of capabilities and a number of users belonging to it. It’s an handy way of grouping users with the same capability.

DoesNotExist

alias of GroupDoesNotExist

can(domain, action)[source]
capabilities = <playhouse.fields.ManyToManyField object>
grouptocapability_set

Back-reference to expose related objects as a SelectQuery.

id = <peewee.PrimaryKeyField object>
name = <peewee.CharField object>
to_dict()[source]
users = <playhouse.fields.ManyToManyField object>
usertogroup_set

Back-reference to expose related objects as a SelectQuery.

class users.models.GroupToCapability(*args, **kwargs)[source]

Bases: users.models.BaseModel

DoesNotExist

alias of GroupToCapabilityDoesNotExist

capability = <peewee.ForeignKeyField object>
capability_id = None
group = <peewee.ForeignKeyField object>
group_id = None
class users.models.User(**kargs)[source]

Bases: users.models.BaseModel

User model

DoesNotExist

alias of UserDoesNotExist

can(domain, action)[source]

Can perform action on the given domain.

capabilities
groups = <playhouse.fields.ManyToManyField object>
id = <peewee.PrimaryKeyField object>
name = <peewee.CharField object>
pwd_hash = <peewee.CharField object>
set_password(password)[source]

set user password

Generate random salt, derivate the given password using pbkdf2 algorith and store a summarizing string in pwd_hash. For hash format refer to passlib documentation.

to_dict()[source]
usertogroup_set

Back-reference to expose related objects as a SelectQuery.

verify_password(password)[source]

Check if the given password is the same stored for this user

class users.models.UserToGroup(*args, **kwargs)[source]

Bases: users.models.BaseModel

DoesNotExist

alias of UserToGroupDoesNotExist

group = <peewee.ForeignKeyField object>
group_id = None
user = <peewee.ForeignKeyField object>
user_id = None