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

Register a new user

from groundwork_users.patterns import GwUsersPattern

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

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

If you already have registered some permissions, roles, Groups or domains you can use them during the registration process:

class MyUserPlugin(GwUsersPattern):

    def activate(self, ):
        user_roles = self.roles.get("my_role")
        user_permissions = self.permission.get("my_permission")
        user_groups = self.roles.get("my_group")
        user_domain ="my_domain")

        user = self.users.register(user_name="new_user",
                                   full_name="New User",
                                   description="My new user for tests",

Update an existing user

To update an existing user you can use the Users database model and commit the change to the database after changes has been made:

class MyUserPlugin(GwUsersPattern):

    def change_user(self, user_name):
        user = self.users.get(user_name)
        if user is None:
            self.log.error("User {0} does not exist".format(user_name))

        # Make a change on the user model
        user.full_name = "My new user name"

        # Commit the change

Deleting a user

class MyUserPlugin(GwUsersPattern):

    def deactivate(self):
        # Let's delete our test user from database, if the plugin gets deactivated

Getting users

For searching and filter users you can use the get() function:

class MyUserPlugin(GwUsersPattern):

    def activate(self):
        # Get a user by user_name
        users = self.users.get("new_user")
        if users is not None:
            user = users[0]


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

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

# Filter by full name
users = self.users.get(full_name="user")

# Filter by active status
users = self.users.get(active = True)

# Filter my multiple values
roles = self.roles.get("my_role")
users = self.users.get(active = True, roles=roles)

User database model

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

    class User(Base, UserMixin):
        Class/Table for storing single users.
        The following columns are needed by the flask-security extension:
        * confirmed_at
        * last_login_at
        * current_login_at
        * last_login_ip
        * current_login_ip
        * login_count
        __tablename__ = "user"
        id = Column(Integer, primary_key=True)
        email = Column(Text(255), unique=True)
        full_name = Column(Text(255))
        password = Column(Text(255))
        user_name = Column(Text(255), unique=True)
        description = Column(Text(2048))
        page = Column(Text(255))
        plugin_name = Column(Text(255))
        active = Column(Boolean())
        confirmed_at = Column(DateTime())
        last_login_at = Column(DateTime())
        current_login_at = Column(DateTime())
        last_login_ip = Column(Text(255))
        current_login_ip = Column(Text(255))
        login_count = Column(Integer)
        roles = relationship('Role', secondary=roles_users,
                             backref=backref('users', lazy='dynamic'))
        permissions = relationship('Permission', secondary=permissions_users,
                                   backref=backref('users', lazy='dynamic'))
        domain_id = Column(Integer, ForeignKey(''))
        domain = relationship("Domain", backref="users")