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.

Users

Create user

To create a new user, use api.user.create(). If your portal is configured to use emails as usernames, you just need to pass in the email of the new user.

from plone import api
user = api.user.create(email='alice@plone.org')

Otherwise, you also need to pass in the username of the new user.

user = api.user.create(email='jane@plone.org', username='jane')

To set user properties when creating a new user, pass in a properties dict.

properties = dict(
    fullname='Bob',
    location='Munich',
)
user = api.user.create(
    username='bob',
    email='bob@plone.org',
    properties=properties,
)

Besides user properties you can also specify a password for the new user. Otherwise a random 8-character alphanumeric password will be generated.

user = api.user.create(
    username='noob',
    email='noob@plone.org',
    password='secret',
)

Get user

You can get a user with api.user.get().

from plone import api
user = api.user.get(username='bob')

User properties

Users have various properties set on them. This is how you get and set them, using the underlying APIs:

from plone import api
user = api.user.get(username='bob')
user.setMemberProperties(mapping={ 'location': 'Neverland', })
location = user.getProperty('location')

Get currently logged-in user

Getting the currently logged-in user is easy with api.user.get_current().

from plone import api
current = api.user.get_current()

Check if current user is anonymous

Sometimes you need to trigger or display some piece of information only for logged-in users. It’s easy to use api.user.is_anonymous() to do a basic check for it.

from plone import api
if not api.user.is_anonymous():
    trigger = False
trigger = True

Get all users

Get all users in your portal with api.user.get_users().

from plone import api
users = api.user.get_users()

Get group’s users

If you set the groupname parameter, then api.user.get_users() will return only users that are members of this group.

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

Delete user

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

from plone import api
api.user.create(username='unwanted', email='unwanted@example.org')
api.user.delete(username='unwanted')

unwanted = api.user.create(username='unwanted', email='unwanted@example.org')
api.user.delete(user=unwanted)

Get user roles

The api.user.get_roles() method is used for getting a user’s roles. By default it returns site-wide roles.

from plone import api
roles = api.user.get_roles(username='jane')

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

from plone import api
portal = api.portal.get()
blog = api.content.create(container=portal, type='Document', id='blog', title='My blog')
roles = api.user.get_roles(username='jane', obj=portal['blog'])

Get user permissions

The api.user.get_permissions() method is used for getting user’s permissions. By default it returns site root permissions.

from plone import api
mike = api.user.create(email='mike@plone.org', username='mike')
permissions = api.user.get_permissions(username='mike')

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

from plone import api
portal = api.portal.get()
folder = api.content.create(container=portal, type='Folder', id='folder_two', title='Folder Two')
permissions = api.user.get_permissions(username='mike', obj=portal['folder_two'])

Check user permission

Instead of getting all user permissions, you can check a single permission using the api.user.has_permission() method. By default it checks the permission on the site root.

from plone import api
adam = api.user.create(email='adam@plone.org', username='adam')
can_view = api.user.has_permission('View', username='adam')

If you pass in a content object, it will check the permission in that particular context.

from plone import api
portal = api.portal.get()
folder = api.content.create(container=portal, type='Folder', id='folder_hp', title='Folder')
can_view = api.user.has_permission('View', username='adam', obj=folder)

Grant roles to user

The api.user.grant_roles() allows us to grant a list of roles to the user.

from plone import api
api.user.grant_roles(username='jane',
    roles=['Reviewer', 'SiteAdministrator']
)

If you pass a content object or folder, the roles are granted only on that context and not site-wide. But all site-wide roles will also be returned by api.user.get_roles() for this user on the given context.

from plone import api
folder = api.content.create(container=portal, type='Folder', id='folder_one', title='Folder One')
api.user.grant_roles(username='jane',
    roles=['Editor', 'Contributor'],
    obj=portal['folder_one']
)

Revoke roles from user

The api.user.revoke_roles() allows us to revoke a list of roles from the user.

from plone import api
api.user.revoke_roles(username='jane', roles=['SiteAdministrator'])

If you pass a context object the local roles for that context will be removed.

from plone import api
folder = api.content.create(
    container=portal,
    type='Folder',
    id='folder_three',
    title='Folder Three'
)
api.user.grant_roles(
    username='jane',
    roles=['Editor', 'Contributor'],
    obj=portal['folder_three'],
)
api.user.revoke_roles(
    username='jane',
    roles=['Editor'],
    obj=portal['folder_three'],
)

Further reading

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