GitHub-only

WARNING: If you are reading this on GitHub, DON’T! Read the documentation at docs.plone.org so you have working references and proper formatting.

Groups

Create group

To create a new group, use api.group.create().

from plone import api
group = api.group.create(groupname='staff')

When you create groups, title, description, roles and groups are optional.

from plone import api

group = api.group.create(
    groupname='board_members',
    title='Board members',
    description='Just a description',
    roles=['Reader', ],
    groups=['Site Administrators', ],
)

Get group

To get a group by its name, use api.group.get().

from plone import api
group = api.group.get(groupname='staff')

Editing a group

Groups can be edited by using the group_tool. In this example, the title, description and roles are updated for the group ‘Staff’.

from plone import api
group_tool = api.portal.get_tool(name='portal_groups')
group_tool.editGroup(
    'staff',
    roles=['Editor', 'Reader'],
    title='Staff',
    description='Just a description',
)

Get all groups

You can also get all groups by using api.group.get_groups().

from plone import api
groups = api.group.get_groups()

Get user’s groups

Groups may be filtered by member. By passing the username parameter, api.group.get_groups() will return only the groups the user belongs to.

from plone import api
user = api.user.get(username='jane')
groups = api.group.get_groups(username='jane')

You can also pass the user directly to api.group.get_groups():

from plone import api user = api.user.get(username=’jane’) groups = api.group.get_groups(user=user)

Get group members

Use the api.user.get_users() method to get all the users that are members of a group.

from plone import api
members = api.user.get_users(groupname='staff')

Delete group

To delete a group, use api.group.delete() and pass in either the groupname or the group object you want to delete.

from plone import api
api.group.create(groupname='unwanted')
api.group.delete(groupname='unwanted')

unwanted = api.group.create(groupname='unwanted')
api.group.delete(group=unwanted)

Adding user to group

To add a user to a group, use the api.group.add_user() method. This method accepts either the groupname or the group object for the target group and the username or the user object you want to add to the group.

from plone import api

api.user.create(email='bob@plone.org', username='bob')
api.group.add_user(groupname='staff', username='bob')

Removing user from group

To remove a user from a group, use the api.group.remove_user() method. This also accepts either the groupname or the group object for the target group and either the username or the user object you want to remove from the group.

from plone import api
api.group.remove_user(groupname='staff', username='bob')

Get group roles

To find the roles assigned to a group, use the api.group.get_roles() method. By default it returns site-wide roles.

from plone import api
roles = api.group.get_roles(groupname='staff')

If you pass in a content object, it will return the local roles of the group in that particular context.

from plone import api
portal = api.portal.get()
folder = api.content.create(
    container=portal,
    type='Folder',
    id='folder_four',
    title='Folder Four',
)
roles = api.group.get_roles(groupname='staff', obj=portal['folder_four'])

If you pass in a content object and inherit=False, it will return only the local roles of the group on that particular object and ignore global roles.

api.group.grant_roles(
    groupname='staff', roles=['Contributor'], obj=portal['folder_four'])

roles = api.group.get_roles(
    groupname='staff', obj=portal['folder_four'], inherit=False)

Grant roles to group

To grant roles to a group, use the api.group.grant_roles() method. By default, roles are granted site-wide.

from plone import api
api.group.grant_roles(
    groupname='staff',
    roles=['Reviewer, SiteAdministrator'],
)

If you pass in a content object, roles will be assigned in that particular context.

from plone import api
portal = api.portal.get()
folder = api.content.create(
    container=portal, type='Folder', id='folder_five', title='Folder Five')
api.group.grant_roles(
    groupname='staff', roles=['Contributor'], obj=portal['folder_five'])

Revoke roles from group

To revoke roles already granted to a group, use the api.group.revoke_roles() method.

from plone import api
api.group.revoke_roles(
    groupname='staff', roles=['Reviewer, SiteAdministrator'])

If you pass in a content object, it will revoke roles granted in that particular context.

from plone import api
api.group.revoke_roles(
    groupname='staff', roles=['Contributor'], obj=portal['folder_five'])

Further reading

For more information on possible flags and complete options please see the full plone.api.group specification.