User

Supported by Redmine starting from version 1.1

Manager

All operations on the User resource are provided by its manager. To get access to it you have to call redmine.user where redmine is a configured redmine object. See the Configuration about how to configure redmine object.

Create methods

create

redminelib.managers.ResourceManager.create(**fields)

Creates new User resource with given fields and saves it to the Redmine.

Parameters:

  • login (string) – (required). User login.

  • password (string) – (optional). User password.

  • firstname (string) – (required). User name.

  • lastname (string) – (required). User surname.

  • mail (string) – (required). User email.

  • auth_source_id (int) – (optional). Authentication mode id.

  • mail_notification (string) – (optional). Type of mail notification, one of:

    • all

    • selected

    • only_my_events

    • only_assigned

    • only_owner

    • none

  • notified_project_ids (list) – (optional). Project IDs for a “selected” mail notification type.

  • must_change_passwd (bool) – (optional). Whether user must change password.

  • generate_password (bool) – (optional). Whether to generate password for the user.

  • send_information (bool) – (optional). Whether to send account information to the user.

  • custom_fields (list) – (optional). Custom fields as [{‘id’: 1, ‘value’: ‘foo’}].

  • admin (bool) – (optional). Whether to give admin privileges to the user, requires Redmine >= 4.0.0.

Returns:

Resource object

>>> user = redmine.user.create(
...     login='jsmith',
...     password='qwerty',
...     firstname='John',
...     lastname='Smith',
...     mail='john@smith.com',
...     auth_source_id=1,
...     mail_notification='selected',
...     notified_project_ids=[1, 2],
...     must_change_passwd=True,
...     custom_fields=[{'id': 1, 'value': 'foo'}, {'id': 2, 'value': 'bar'}]
... )
>>> user
<redminelib.resources.User #32 "John Smith">

new

redminelib.managers.ResourceManager.new()

Creates new empty User resource but saves it to the Redmine only when save() is called, also calls pre_create() and post_create() methods of the Resource object. Valid attributes are the same as for create() method above.

Returns:

Resource object

>>> user = redmine.user.new()
>>> user.login = 'jsmith'
>>> user.password = 'qwerty'
>>> user.firstname = 'John
>>> user.lastname = 'Smith'
>>> user.mail = 'john@smith.com'
>>> user.auth_source_id = 1
>>> user.mail_notification = 'selected'
>>> user.notified_project_ids = [1, 2]
>>> user.must_change_passwd = True
>>> user.custom_fields = [{'id': 1, 'value': 'foo'}, {'id': 2, 'value': 'bar'}]
>>> user.save()
<redminelib.resources.User #32 "John Smith">

Read methods

get

redminelib.managers.ResourceManager.get(resource_id, **params)

Returns single User resource from Redmine by its id.

Parameters:

  • resource_id (int) – (required). Id of the user.

  • include (list) – (optional). Fetches associated data in one call. Accepted values:

    • memberships

    • groups

Returns:

Resource object

>>> user = redmine.user.get(17, include=['memberships', 'groups'])
>>> user
<redminelib.resources.User #17 "John Smith">

Hint

You can easily get the details of the user whose credentials were used to access the API:

>>> user = redmine.user.get('current')
>>> user
<redminelib.resources.User #17 "John Smith">

Hint

User resource object provides you with on demand includes. On demand includes are the other resource objects wrapped in a ResourceSet which are associated with a User resource object. Keep in mind that on demand includes are retrieved in a separate request, that means that if the speed is important it is recommended to use get() method with include keyword argument. On demand includes provided by the User resource object are the same as in the get() method above:

>>> user = redmine.user.get(17)
>>> user.groups
<redminelib.resultsets.ResourceSet object with Group resources>

Hint

User resource object provides you with some relations. Relations are the other resource objects wrapped in a ResourceSet which are somehow related to a User resource object. The relations provided by the User resource object are:

  • time_entries

  • issues (alias to issues_assigned)

  • issues_assigned (requires Python-Redmine v2.5.0)

  • issues_authored (requires Python-Redmine v2.5.0)

  • deals (requires Pro Edition and CRM plugin)

  • contacts (requires Pro Edition and CRM plugin)

  • invoices (requires Pro Edition and Invoices plugin >= 4.1.3)

  • expenses (requires Pro Edition and Invoices plugin >= 4.1.3)

  • products (requires Pro Edition and Products plugin >= 2.1.5)

  • orders (requires Pro Edition and Products plugin >= 2.1.5)

>>> user = redmine.user.get(17)
>>> user.issues
<redminelib.resultsets.ResourceSet object with Issue resources>

all

redminelib.managers.ResourceManager.all(**params)

Returns all User resources from Redmine.

Parameters:

  • limit (int) – (optional). How much resources to return.

  • offset (int) – (optional). Starting from what resource to return the other resources.

Returns:

ResourceSet object

>>> users = redmine.user.all(offset=10, limit=100)
>>> users
<redminelib.resultsets.ResourceSet object with User resources>

filter

redminelib.managers.ResourceManager.filter(**filters)

Returns User resources that match the given lookup parameters.

Parameters:

  • status (int) – (optional). Get only users with given status. One of:

    • 0 - anonymous

    • 1 - active (default)

    • 2 - registered

    • 3 - locked

  • name (string) – (optional). Filter users on their login, firstname, lastname and mail. If the pattern contains a space, it will also return users whose firstname match the first word or lastname match the second word.

  • group_id (int) – (optional). Get only members of the given group.

  • limit (int) – (optional). How much resources to return.

  • offset (int) – (optional). Starting from what resource to return the other resources.

Returns:

ResourceSet object

>>> users = redmine.user.filter(offset=10, limit=100, status=3)
>>> users
<redminelib.resultsets.ResourceSet object with User resources>

Hint

You can also get users from a Group resource object directly using users on demand includes:

>>> group = redmine.group.get(524)
>>> group.users
<redminelib.resultsets.ResourceSet object with User resources>

Update methods

update

redminelib.managers.ResourceManager.update(resource_id, **fields)

Updates values of given fields of a User resource and saves them to the Redmine.

Parameters:

  • resource_id (int) – (required). User id.

  • login (string) – (optional). User login.

  • password (string) – (optional). User password.

  • firstname (string) – (optional). User name.

  • lastname (string) – (optional). User surname.

  • mail (string) – (optional). User email.

  • status (int) – (optional). User status, one of:

    • 1 - active

    • 2 - registered

    • 3 - locked

  • auth_source_id (int) – (optional). Authentication mode id.

  • mail_notification (string) – (optional). Type of mail notification, one of:

    • all

    • selected

    • only_my_events

    • only_assigned

    • only_owner

    • none

  • notified_project_ids (list) – (optional). Project IDs for a “selected” mail notification type.

  • must_change_passwd (bool) – (optional). Whether user must change password.

  • generate_password (bool) – (optional). Whether to generate password for the user.

  • send_information (bool) – (optional). Whether to send account information to the user.

  • custom_fields (list) – (optional). Custom fields as [{‘id’: 1, ‘value’: ‘foo’}].

  • admin (bool) – (optional). Whether to give admin privileges to the user, requires Redmine >= 4.0.0.

Returns:

True

>>> redmine.user.update(
...     1,
...     login='jsmith',
...     password='qwerty',
...     firstname='John',
...     lastname='Smith',
...     mail='john@smith.com',
...     status=3,
...     auth_source_id=1,
...     mail_notification='selected',
...     notified_project_ids=[1, 2],
...     must_change_passwd=True,
...     custom_fields=[{'id': 1, 'value': 'foo'}, {'id': 2, 'value': 'bar'}]
... )
True

Hint

By default Python-Redmine uses /users/ID API endpoint which requires admin privileges, it is also possible to use /my/account endpoint which doesn’t by using me as an ID (requires Redmine >= 4.1.0):

>>> redmine.user.update('me', firstname='John')
True

save

redminelib.resources.User.save(**attrs)

Saves the current state of a User resource to the Redmine. Attrs that can be changed are the same as for update() method above.

Returns:

Resource object

>>> user = redmine.user.get(1)
>>> user.login = 'jsmith'
>>> user.password = 'qwerty'
>>> user.firstname = 'John'
>>> user.lastname = 'Smith'
>>> user.mail = 'john@smith.com'
>>> user.status = 3
>>> user.auth_source_id = 1
>>> user.mail_notification = 'selected'
>>> user.notified_project_ids = [1, 2]
>>> user.must_change_passwd = True
>>> user.custom_fields = [{'id': 1, 'value': 'foo'}, {'id': 2, 'value': 'bar'}]
>>> user.save()
<redminelib.resources.User #1 "John Smith">

Added in version 2.1.0: Alternative syntax was introduced.

>>> user = redmine.user.get(1).save(
...     login='jsmith',
...     password='qwerty',
...     firstname='John',
...     lastname='Smith',
...     mail='john@smith.com',
...     status=3,
...     auth_source_id=1,
...     mail_notification='selected',
...     notified_project_ids=[1, 2],
...     must_change_passwd=True,
...     custom_fields=[{'id': 1, 'value': 'foo'}, {'id': 2, 'value': 'bar'}]
... )
>>> user
<redminelib.resources.User #1 "John Smith">

Delete methods

delete

redminelib.managers.ResourceManager.delete(resource_id)

Deletes single User resource from Redmine by its id.

Parameters:

resource_id (int) – (required). User id.

Returns:

True

>>> redmine.user.delete(1)
True
redminelib.resources.User.delete()

Deletes current User resource object from Redmine.

Returns:

True

>>> user = redmine.user.get(1)
>>> user.delete()
True

Export

Added in version 2.3.0.

redminelib.resultsets.ResourceSet.export(fmt, savepath=None, filename=None, columns=None, encoding='UTF-8')

Exports a resource set of User resources in one of the following formats: csv

Parameters:

  • fmt (string) – (required). Format to use for export.

  • savepath (string) – (optional). Path where to save the file.

  • filename (string) – (optional). Name that will be used for the file.

  • columns (iterable or string) – (optional). Iterable of column names or “all” string for all available columns or “all_gui” string for GUI like behaviour or iterable of elements with “all_gui” string and additional columns to export.

  • encoding – (optional). Encoding that will be used for the result file.

Returns:

String or Object

>>> users = redmine.user.all()
>>> users.export('csv', savepath='/home/jsmith', filename='users.csv', columns='all')
'/home/jsmith/users.csv'