groups are used to bundle users, so that you can assign permissions and roles easily to a group instead of assigning them separately to each user.

To register, edit or delete groups and their related data, your plugin needs to inherit from GwUsersPattern

Register a new group

from groundwork_users.patterns import GwUsersPattern

class MyGroupPlugin(GwUsersPattern):
    # Plugin initialisation, no group related stuff here
    def __init__(self, app, *args, **kwargs): = "MyGroupPlugin
        super(MyUserPlugin, self).__init__(app, *args, **kwargs)

    def activate(self):
        # Register a new group
        self.groups.register("my_group", "my own group description")

You can also assign users, permission and roles during group registration:

class MyGroupPlugin(GwUsersPattern):
     def activate(self):
        # Register a user
        user = self.users.register("test_user", "", "my_password")

        # Get a permissions
        permission = self.permissions.get("my_permission")[0]

        # Register a role
        role = self.roles.register("my_role", permissions=[permission])

        # Register a new group
        self.groups.register("my_group", "my own group description",

Updating an existing group

class MyGroupPlugin(GwUsersPattern):

    def change_group(self, group_name):
        group = self.groups.get(group_name)
        if group is None:
            self.log.error("Group {0} does not exist".format(group_name))

        # Make changes on the group model = "new_name"

        new_permissions = self.permissions.get("some_new_permissions")
        group.permissions = group.permissions + new_permissions  # Add the new permissions to the existing ones

        # Commit the change

Deleting a group

class MyGroupPlugin(GwUsersPattern):
    def deactivate(self):

Getting groups

class MyGroupPlugin(GwUsersPattern):

    def activate(self):
        # Get a group by name
        groups = self.groups.get("my_group")
        if groups is not None:
            group = groups[0]


get() always returns a list, if groups were found or None, if no group was found. Even if only a single group is found a list is returned!

You can use additional key-word arguments to filter for groups. Each given keyword is passed to the sqlalchemy filter function and therefore must be part of the user database model:

# Filter by plugin_name, which has registered the group
groups = self.groups.get(plugin_name="MyGroupPlugin")

# Filter by an user
users = self.users.get("my_user")
groups = self.groups.get(users=[users])

Groups database model

Below you can see the currently used database model for a group object:

    class Group(Base):
        Class/Table for storing groups.
        __tablename__ = "group"
        id = Column(Integer(), primary_key=True)
        name = Column(Text(255), unique=True)
        description = Column(Text(2048))
        plugin_name = Column(Text())
        users = relationship('User', secondary=groups_users,
                             backref=backref('groups', lazy='dynamic'))
        roles = relationship('Role', secondary=roles_groups,
                             backref=backref('groups', lazy='dynamic'))
        permissions = relationship('Permission', secondary=permissions_groups,
                                   backref=backref('groups', lazy='dynamic'))