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
Get user
User properties
Get currently logged-in user
Check if current user is anonymous
Get all users
Get group's users
Delete user
Get user roles
Get user permissions
Check user permission
Grant roles to user
Revoke roles from user
Further reading

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'],
)

                      