Python Redmine

Python Redmine Documentation
Release
Max Tepkeev
February 20, 2015
Contents
Features
Contacts and Support
Donations and Sponsorship
Copyright and License
Table of contents
5.1 Installation . . . . . . . . .
5.2 Configuration . . . . . . . .
5.3 Operations . . . . . . . . .
5.4 Resources . . . . . . . . . .
5.5 Advanced Usage . . . . . .
5.6 Frequently Asked Questions
5.7 Exceptions . . . . . . . . .
5.8 License . . . . . . . . . . .
5.9 Changelog . . . . . . . . .
Python Module Index
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
11
11
12
14
18
78
81
81
83
83
91
ii
Python Redmine Documentation, Release
Python Redmine is a library for communicating with a Redmine project management application. Redmine exposes
some of its data via REST API for which Python Redmine provides a simple but powerful Pythonic API inspired by
a well-known Django ORM:
>>> from redmine import Redmine
>>> redmine = Redmine(http://demo.redmine.org, username=foo, password=bar)
>>> project = redmine.project.get(vacation)
>>> project.id
30404
>>> project.identifier
vacation
>>> project.created_on
datetime.datetime(2013, 12, 31, 13, 27, 47)
>>> project.issues
<redmine.resultsets.ResourceSet object with Issue resources>
>>> project.issues[0]
<redmine.resources.Issue #34441 "Vacation">
>>> dir(project.issues[0])
[assigned_to, author, created_on, description, done_ratio,
due_date, estimated_hours, id, priority, project, relations,
start_date, status, subject, time_entries, tracker, updated_on]
>>> project.issues[0].subject
Vacation
>>> project.issues[0].time_entries
<redmine.resultsets.ResourceSet object with TimeEntry resources>
Contents
Contents
CHAPTER 1
Features
Supports 100% of Redmine API features

Supports Python 2.6 - 3.4, PyPy and PyPy3
Extensively documented
Provides ORM-style Pythonic API
Chapter 1. Features
CHAPTER 2
Contacts and Support
I will be glad to get your feedback, pull requests, issues, whatever. Feel free to contact me for any questions.
Chapter 2. Contacts and Support
CHAPTER 3
Donations and Sponsorship
If you like this project and want to support it you have 3 options:
1. Just give this project a star at the top of the GitHub repository. That doesnt cost you anything but makes the
author happier.
2. You can express your gratitude via Gratipay.
3. Become a sponsor. Contact me via tepkeev at gmail dot com if you are interested in becoming a
sponsor and we will discuss the terms and conditions.
Chapter 3. Donations and Sponsorship
CHAPTER 4
Copyright and License
Python Redmine is licensed under Apache 2.0 license. Check the License for details.
10
Chapter 4. Copyright and License
CHAPTER 5
Table of contents
5.1 Installation
5.1.1 Dependencies
Python Redmine relies heavily on great Requests library by Kenneth Reitz for all the http(s) calls.
5.1.2 Conflicts
Python Redmine cant be used together with PyRedmine because they both use same module name, i.e. redmine
which causes unexpected behaviour for both packages. That means that you have to uninstall PyRedmine before
installing Python Redmine.
5.1.3 PyPI
The recommended way to install is from Python Package Index (PyPI) with pip:
$ pip install python-redmine
or with easy_install:
$ easy_install python-redmine
If the PyPI is down, you can also install Python Redmine from one of its mirrors, e.g. from Crate.IO:
$ pip install -i http://simple.crate.io/ python-redmine
5.1.4 GitHub
Python Redmine is actively developed on GitHub. If you want to get latest development sources you have to clone the
repository:
$ git clone git://github.com/maxtepkeev/python-redmine.git
Once you have the sources, you can install it into your site-packages:
$ python setup.py install
You can also install latest stable development version via pip:
11
$ pip install git+https://github.com/maxtepkeev/python-redmine.git@master
5.2 Configuration
5.2.1 Redmine
To start making requests to Redmine you have to check the box Enable REST API in Administration -> Settings ->
Authentication and click the Save button.
Hint: Sometimes it is a good idea to create a special user in Redmine which will be used only for the calls to
Redmines REST API.
5.2.2 Parameters
Configuring Python Redmine is extremely easy, the first thing you have to do is to import the Redmine object, which
will represent the connection to Redmine server:
from redmine import Redmine
Location
Now you need to configure the Redmine object and pass it a few parameters. The only required parameter is the
Redmine location (without the forward slash in the end):
redmine = Redmine(http://demo.redmine.org)
Authentication
Most of the time, the API requires authentication. It can be done in 2 different ways:
using users regular login and password:
redmine = Redmine(http://demo.redmine.org, username=foo, password=bar)
using users API key which is a handy way to avoid putting a password in a script:
redmine = Redmine(http://demo.redmine.org, key=b244397884889a29137643be79c83f1d470c1e2fac)
The API key can be found on users account page when logged in, on the right-hand pane of the default layout.
Impersonation
As of Redmine 2.2.0, you can impersonate user through the REST API. It must be set to a user login, e.g. jsmith. This
only works when using the API with an administrator account, this will be ignored when using the API with a regular
user account.
redmine = Redmine(http://demo.redmine.org, impersonate=jsmith)
If the login specified does not exist or is not active, you will get an exception.
12
Chapter 5. Table of contents
Version
There are a lot of different Redmine versions out there and different versions support different resources and features.
To be sure that everything will work as expected you need to tell Python Redmine what version of Redmine do you
use:
redmine = Redmine(http://demo.redmine.org, version=2.3.3)
DateTime Formats
Python Redmine automatically converts Redmines date/datetime strings to Pythons date/datetime objects:
2013-12-31
-> datetime.date(2013, 12, 31)
2013-12-31T13:27:47Z -> datetime.datetime(2013, 12, 31, 13, 27, 47)
Starting from Python Redmine 0.7.0 the conversion also works backwards, i.e. you can use Pythons date/datetime
objects when setting resource attributes or in ResourceManager methods, e.g. filter():
datetime.date(2013, 12, 31)
-> 2013-12-31
datetime.datetime(2013, 12, 31, 13, 27, 47) -> 2013-12-31T13:27:47Z
If the conversion doesnt work for you and you receive strings instead of objects, you have a different datetime formatting than default. To make the conversion work you have to tell Redmine object what datetime formatting do you
use, e.g. if the string returned is 31.12.2013T13:27:47Z:
redmine = Redmine(http://demo.redmine.org, date_format=%d.%m.%Y, datetime_format=%d.%m.%YT%H:%M:
Exception Control
New in version 0.4.0.
If a requested attribute on a resource object doesnt exist, Python Redmine will raise an exception by default. Sometimes this may not be the desired behaviour. Python Redmine provides a way to control this type of exception.
You can completely turn it OFF for all resources:
redmine = Redmine(https://redmine.url, raise_attr_exception=False)
Or you can turn it ON only for some resources via a list or tuple of resource class names:
redmine = Redmine(https://redmine.url, raise_attr_exception=(Project, Issue, WikiPage))
Connection Options
Python Redmine uses Requests library for all the http(s) calls to Redmine server. Requests provides sensible default
connection options, but sometimes you may have a need to change them. For example if your Redmine server uses
SSL but the certificate is invalid you need to set a Requestss verify option to False:
redmine = Redmine(https://redmine.url, requests={verify: False})
Full list of available connection options can be found in the Requests documentation.
Hint: Storing settings right in the code is a bad habit. Instead store them in some configuration file and then import
them, for example if you use Django, you can create settings for Python Redmine in projects settings.py file and then
import them in the code, e.g.:
5.2. Configuration
13
# settings.py
REDMINE_URL = http://demo.redmine.org
REDMINE_KEY = b244397884889a29137643be79c83f1d470c1e2fac
# somewhere in the code
from django.conf import settings
from redmine import Redmine
redmine = Redmine(settings.REDMINE_URL, key=settings.REDMINE_KEY)
5.3 Operations
Now when you have configured your Redmine object, you can start making operations on the Redmine. Redmine has
a conception of resources, i.e. resource is an entity which can be used in Redmines REST API. All operations on the
resources are provided by the ResourceManager object which you usually dont have to use directly. Not all resources
support every operation, if resource doesnt support the requested operation, an exception will be thrown.
5.3.1 Create
Python Redmine provides 2 create operation methods: create and new. Unfortunately Redmine doesnt support the
creation of some resources via REST API. You can read more about it in each resources documentation.
create
Creates new resource with given fields and saves it to the Redmine.
>>> project = redmine.project.create(name=Vacation, identifier=vacation, description=foo, homep

>>> project
<redmine.resources.Project #123 "Vacation">
new
Creates new empty resource but doesnt save it to the Redmine. This is useful if you want to set some resource fields
later based on some condition(s) and only after that save it to the Redmine.
>>> project = redmine.project.new()
>>> project.name = Vacation
>>> project.identifier = vacation
>>> project.description = foo
>>> project.homepage = http://foo.bar
>>> project.is_public = True
>>> project.parent_id = 345
>>> project.inherit_members = True
>>> project.custom_fields = [{id: 1, value: foo}, {id: 2, value: bar}]
>>> project.save()
True
14
5.3.2 Read
Python Redmine provides 3 read operation methods: get, all and filter. Each of this methods support different
keyword arguments depending on the resource used and method called. You can read more about it in each resources
documentation.
get
Returns requested Resource object either by integer id or by string identifier:
>>> project.name
Vacation
>>> project[name] # You can access Resource attributes this way too
Vacation
Note: Resource object provides 2 ways to introspect itself:

dir(). Returns all the attributes Resource has as a list.
dir(redmine.project.get(vacation))
list(). Returns all the attributes with its values Resource has as a list of tuples.
list(redmine.project.get(vacation))
Hint: Under some circumstances Redmine doesnt return all the data about Resource, fortunately Resource object
provides a convenient refresh() method which will get all the available data:
redmine.project.get(vacation).refresh()
all
Returns a ResourceSet object that contains all the requested Resource objects:
>>> projects = redmine.project.all()
>>> projects
<redmine.resultsets.ResourceSet object with Project resources>
filter
Returns a ResourceSet object that contains Resource objects filtered by some condition(s):
>>> issues = redmine.issue.filter(project_id=vacation)
>>> issues
Hint: ResourceSet object supports limit and offset, i.e. if you need to get only some portion of Resource objects, in
the form of [offset:limit] or as keyword arguments:
5.3. Operations
15
redmine.project.all()[:135] # Returns only the first 135 projects

redmine.project.all(limit=135) # Returns only the first 135 projects
redmine.issue.filter(project_id=vacation)[10:3] # Returns only 3 issues starting from 10th
redmine.issue.filter(project_id=vacation, offset=10, limit=3) # Returns only 3 issues starting fro
Please note, that keyword arguments have a higher priority, e.g.:

redmine.project.all(limit=10)[:20]
# Returns 10 projects and not 20
Hint: ResourceSet object provides 5 helper methods get(), filter(), update(), delete() and values():
get. Returns a single resource from the ResourceSet by resource id:
redmine.project.all().get(30404, None)
# Returns None if a Resource is not found
filter. Returns a ResourceSet with requested resource ids:

redmine.project.all().filter((30404, 30405, 30406, 30407))
update. Updates fields of all resources in a ResourceSet with the given values and returns an updated ResourceSet object, e.g., the following assigns issues of a project vacation with ids of 30404 and 30405 to the user with
id of 547:
redmine.project.get(vacation).issues.filter((30404, 30405)).update(assigned_to_id=547)
delete. Deletes all resources in a ResourceSet, e.g. the following deletes all issues from the vacation project:
redmine.project.get(vacation).issues.delete()
values. Returns a ValuesResourceSet a ResourceSet subclass that returns dictionaries when used as an
iterable, rather than resource-instance objects. Each of those dictionaries represents a resource, with the keys
corresponding to the attribute names of resource objects. This example compares the dictionaries of values()
with the normal resource objects:
>>> list(redmine.issue_status.all(limit=1))
[<redmine.resources.IssueStatus #1 "New">]
>>> list(redmine.issue_status.all(limit=1).values())
[{id: 1, is_default: True, name: New}]
16
The values() method takes optional positional arguments, *fields, which specify field names to which resource
fields should be limited. If you specify the fields, each dictionary will contain only the field keys/values for the
fields you specify. If you dont specify the fields, each dictionary will contain a key and value for every field in
the resource:
>>> list(redmine.issue_status.all(limit=1).values())
[{id: 1, is_default: True, name: New}]
>>> list(redmine.issue_status.all(limit=1).values(id, name))
[{id: 1, name: New}]
ResourceSet object also provides some attributes:

limit. What limit value was used to retrieve this ResourceSet:
redmine.project.all().limit
offset. What offset value was used to retrieve this ResourceSet:

redmine.project.all().offset
total_count. How much resources of current resource type there are available in Redmine:
redmine.project.all().total_count
Note: ResourceSet object is lazy, i.e. it doesnt make any requests to Redmine when it is created and is evaluated
only when some of these conditions are met:
Iteration. A ResourceSet is iterable and it is evaluated when you iterate over it.
for project in redmine.project.all():
print(project.name)
len(). A ResourceSet is evaluated when you call len() on it and returns the length of the list.
len(redmine.project.all())
list(). Force evaluation of a ResourceSet by calling list() on it.

list(redmine.project.all())
Index. A ResourceSet is also evaluated when you request some of its Resources by index.
redmine.project.all()[0]
# Returns the first Resource in the ResourceSet
5.3.3 Update
Python Redmine provides 2 update operation methods: update and save. Unfortunately Redmine doesnt support
updates on some resources via REST API. You can read more about it in each resources documentation.
5.3. Operations
17
update
Updates a resource with given fields and saves it to the Redmine.
>>> redmine.project.update(1, name=Vacation, description=foo, homepage=http://foo.bar, is_publi

True
save
Saves the current state of a resource to the Redmine.
>>> project = redmine.project.get(1)
>>> project.save()
True
5.3.4 Delete
Resources can be deleted via delete method. Unfortunately Redmine doesnt support the deletion of some resources
via REST API. You can read more about it in each resources documentation.
>>> redmine.project.delete(1)
True
Warning: Deleted resources cant be restored. Use this method carefully.
5.4 Resources
5.4.1 Issue
Supported by Redmine starting from version 1.0
Manager
All operations on the issue resource are provided via its manager. To get access to it you have to call
redmine.issue where redmine is a configured redmine object. See the Configuration about how to configure
redmine object.
18
Create methods
create
redmine.managers.ResourceManager.create(**fields)
Creates new issue resource with given fields and saves it to the Redmine.
Parameters
project_id (integer or string) (required). Id or identifier of issues project.
subject (string) (required). Issue subject.
tracker_id (integer) (optional). Issue tracker id.
description (string) (optional). Issue description.
status_id (integer) (optional). Issue status id.
priority_id (integer) (optional). Issue priority id.
category_id (integer) (optional). Issue category id.
fixed_version_id (integer) (optional). Issue version id.
is_private (boolean) (optional). Whether issue is private.
assigned_to_id (integer) (optional). Issue will be assigned to this user id.
watcher_user_ids (list or tuple) (optional). User ids who will be watching this issue.
parent_issue_id (integer) (optional). Parent issue id.
start_date (string or date object) (optional). Issue start date.
due_date (string or date object) (optional). Issue end date.
estimated_hours (integer) (optional). Issue estimated hours.
done_ratio (integer) (optional). Issue done ratio.
custom_fields (list) (optional). Custom fields in the form of [{id: 1, value: foo}].
uploads (list or tuple)
path (required). Absolute path to the file that should be uploaded.
filename (optional). Name of the file after upload.
description (optional). Description of the file.
content_type (optional). Content type of the file.
Returns Issue resource object
>>> issue = redmine.issue.create(project_id=vacation, subject=Vacation, tracker_id=8, description

>>> issue
new
redmine.managers.ResourceManager.new()
Creates new empty issue resource but doesnt save it to the Redmine. This is useful if you want to set some
resource fields later based on some condition(s) and only after that save it to the Redmine. Valid attributes are
the same as for create method above.
5.4. Resources
19

>>> issue = redmine.issue.new()
>>> issue.project_id = vacation
>>> issue.subject = Vacation
>>> issue.tracker_id = 8
>>> issue.description = foo
>>> issue.status_id = 3
>>> issue.priority_id = 7
>>> issue.assigned_to_id = 123
>>> issue.watcher_user_ids = [123]
>>> issue.parent_issue_id = 345
>>> issue.start_date = date(2014, 1, 1)
>>> issue.due_date = date(2014, 2, 1)
>>> issue.estimated_hours = 4
>>> issue.done_ratio = 40
>>> issue.custom_fields = [{id: 1, value: foo}, {id: 2, value: bar}]
>>> issue.uploads = [{path: /absolute/path/to/file}, {path: /absolute/path/to/file2}]
>>> issue.save()
True
Read methods
get
redmine.managers.ResourceManager.get(resource_id, **params)
Returns single issue resource from the Redmine by its id.
Parameters
resource_id (integer) (required). Id of the issue.
include (string)
children
attachments
relations
changesets
journals
watchers
>>> issue = redmine.issue.get(34441, include=children,journals,watchers)
>>> issue
Hint: New in version 0.4.0.
Issue resource object provides you with on demand includes. On demand includes are the other resource objects
wrapped in a ResourceSet which are associated with an Issue resource object. Keep in mind that on demand includes
20
are retrieved in a separate request, that means that if the speed is important it is recommended to use get method with
a include keyword argument. The on demand includes provided by the Issue resource object are the same as in the
get method above:
>>> issue = redmine.issue.get(34441)
>>> issue.journals
<redmine.resultsets.ResourceSet object with IssueJournal resources>
Hint: Issue resource object provides you with some relations. Relations are the other resource objects wrapped in
a ResourceSet which are somehow related to an Issue resource object. The relations provided by the Issue resource
object are:
relations
time_entries
>>> issue.time_entries
all
redmine.managers.ResourceManager.all(**params)
Returns all issue resources from the Redmine.
Parameters
sort (string) (optional). Column to sort with. Append :desc to invert the order.
limit (integer) (optional). How much resources to return.
offset (integer) (optional). Starting from what resource to return the other resources.
Returns ResourceSet object
>>> issues = redmine.issue.all(sort=category:desc)
>>> issues
filter
redmine.managers.ResourceManager.filter(**filters)
Returns issue resources that match the given lookup parameters.
Parameters
project_id (integer or string) (optional). Id or identifier of issues project.
subproject_id (integer or string) (optional). Get issues from the subproject with the given
id. You can use project_id=X, subproject_id=!* to get only the issues of a given project and
none of its subprojects.
tracker_id (integer) (optional). Get issues from the tracker with the given id.
query_id (integer) (optional). Get issues for the given query id.
status_id (integer or string)
open - open issues
5.4. Resources
21
closed - closed issues

* - all issues
id - status id
assigned_to_id (integer) (optional). Get issues which are assigned to the given user id.
To get the issues assigned to the user whose credentials were used to access the API pass
me as a string.
cf_x (string) (optional). Get issues with the given value for custom field with an ID of x.
sort (string) (optional). Column to sort with. Append :desc to invert the order.
>>> issues = redmine.issue.filter(project_id=vacation, subproject_id=!*, created_on=><2012-03-01

>>> issues
Hint: You can also get issues from a project, tracker, issue status or user resource objects directly using issues
relation:
>>> project.issues
Update methods
update
redmine.managers.ResourceManager.update(resource_id, **fields)
Updates values of given fields of an issue resource and saves them to the Redmine.
Parameters
resource_id (integer) (required). Issue id.
project_id (integer) (optional). Issue project id.
subject (string) (optional). Issue subject.
tracker_id (integer) (optional). Issue tracker id.
description (string) (optional). Issue description.
notes (string) (optional). Issue journal note.
status_id (integer) (optional). Issue status id.
priority_id (integer) (optional). Issue priority id.
category_id (integer) (optional). Issue category id.
fixed_version_id (integer) (optional). Issue version id.
is_private (boolean) (optional). Whether issue is private.
assigned_to_id (integer) (optional). Issue will be assigned to this user id.
22
parent_issue_id (integer) (optional). Parent issue id.

start_date (string or date object) (optional). Issue start date.
due_date (string or date object) (optional). Issue end date.
estimated_hours (integer) (optional). Issue estimated hours.
done_ratio (integer) (optional). Issue done ratio.
uploads (list or tuple)
path (required). Absolute path to the file that should be uploaded.
filename (optional). Name of the file after upload.
description (optional). Description of the file.
content_type (optional). Content type of the file.
Returns True
>>> redmine.issue.update(1, project_id=1, subject=Vacation, tracker_id=8, description=foo, notes=

True
save
redmine.resources.Issue.save()
Saves the current state of an issue resource to the Redmine. Fields that can be changed are the same as for
update method above.
Returns True
>>> issue.project_id = 1
>>> issue.subject = Vacation
>>> issue.tracker_id = 8
>>> issue.description = foo
>>> issue.notes = A journal note
>>> issue.status_id = 3
>>> issue.priority_id = 7
>>> issue.assigned_to_id = 123
>>> issue.parent_issue_id = 345
>>> issue.start_date = date(2014, 1, 1)
>>> issue.due_date = date(2014, 2, 1)
>>> issue.estimated_hours = 4
>>> issue.done_ratio = 40
>>> issue.custom_fields = [{id: 1, value: foo}, {id: 2, value: bar}]
>>> issue.uploads = [{path: /absolute/path/to/file}, {path: /absolute/path/to/file2}]
>>> issue.save()
True
Delete methods
delete
redmine.managers.ResourceManager.delete(resource_id)
Deletes single issue resource from the Redmine by its id.
5.4. Resources
23
Parameters resource_id (integer) (required). Issue id.

Returns True
>>> redmine.issue.delete(1)
True
Watchers
Python Redmine provides 2 methods to work with issue watchers: add and remove.
add
redmine.resources.Issue.Watcher.add(user_id)
Adds a user to issue watchers list by its id.
Parameters user_id (integer) (required). User id.
Returns True
>>> issue.watcher.add(1)
True
remove
redmine.resources.Issue.Watcher.remove(user_id)
Removes a user from issue watchers list by its id.
Returns True
>>> issue.watcher.remove(1)
True
5.4.2 Project
Manager
All operations on the project resource are provided via its manager. To get access to it you have to call
redmine.project where redmine is a configured redmine object. See the Configuration about how to configure redmine object.
24
Create methods
create
Creates new project resource with given fields and saves it to the Redmine.
Parameters
name (string) (required). Project name.
identifier (string) (required). Project identifier.
description (string) (optional). Project description.
homepage (string) (optional). Project homepage url.
is_public (boolean) (optional). Whether project is public.
parent_id (integer) (optional). Projects parent project id.
inherit_members (boolean) (optional). If project inherits parent projects members.
tracker_ids (list) (optional). The ids of trackers for this project.
issue_custom_field_ids (list) (optional). The ids of issue custom fields for this project.
enabled_module_names (list) (optional). The names of enabled modules for this project
(Redmine >= 2.6.0 only).
Returns Project resource object
>>> project = redmine.project.create(name=Vacation, identifier=vacation, description=foo, homep

>>> project
new
Creates new empty project resource but doesnt save it to the Redmine. This is useful if you want to set some
>>> project = redmine.project.new()
>>> project.identifier = vacation
>>> project.tracker_ids = [1, 2]
>>> project.issue_custom_field_ids = [1, 2]
>>> project.enabled_module_names = [calendar, documents, files, gantt]
>>> project.save()
True
5.4. Resources
25
Read methods
get
Returns single project resource from the Redmine by its id or identifier.
Parameters
resource_id (integer or string) (required). Project id or identifier.
include (string)
trackers
issue_categories
enabled_modules (Redmine >= 2.6.0 only)
>>> project = redmine.project.get(vacation, include=trackers,issue_categories,enabled_modules)
>>> project
Project 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 Project resource object. Keep in mind that on demand includes
a include keyword argument. The on demand includes provided by the Project resource object are the same as in
the get method above:
>>> project.trackers
<redmine.resultsets.ResourceSet object with Tracker resources>
Hint: Project resource object provides you with some relations. Relations are the other resource objects wrapped in
a ResourceSet which are somehow related to a Project resource object. The relations provided by the Project resource
object are:
wiki_pages
memberships
issue_categories
versions
news
issues
time_entries (available from v1.0.0)
deals (available from v1.0.0 and only if CRM plugin is installed)
contacts (available from v1.0.0 and only if CRM plugin is installed)
26
deal_categories (available from v1.0.0 and only if CRM plugin 3.3.0 and higher is installed)
>>> project.issues
all
Returns all project resources from the Redmine.
Parameters
include (string)
trackers
issue_categories
enabled_modules
>>> projects = redmine.project.all(offset=10, limit=100)
>>> projects
<redmine.resultsets.ResourceSet object with Project resources>
filter
Not supported by Redmine

Update methods
update
Updates values of given fields of a project resource and saves them to the Redmine.
Parameters
resource_id (integer) (required). Project id.
name (string) (optional). Project name.
description (string) (optional). Project description.
homepage (string) (optional). Project homepage url.
is_public (boolean) (optional). Whether project is public.
parent_id (integer) (optional). Projects parent project id.
inherit_members (boolean) (optional). If project inherits parent projects members.
tracker_ids (list) (optional). The ids of trackers for this project.
5.4. Resources
27
issue_custom_field_ids (list) (optional). The ids of issue custom fields for this project.
enabled_module_names (list) (optional). The names of enabled modules for this project
(Redmine >= 2.6.0 only).
Returns True
>>> redmine.project.update(1, name=Vacation, description=foo, homepage=http://foo.bar, is_publi

True
save
redmine.resources.Project.save()
Saves the current state of a project resource to the Redmine. Fields that can be changed are the same as for
Returns True
>>> project = redmine.project.get(1)
>>> project.tracker_ids = [1, 2]
>>> project.issue_custom_field_ids = [1, 2]
>>> project.enabled_module_names = [calendar, documents, files, gantt]
>>> project.save()
True
Delete methods
delete
Deletes single project resource from the Redmine by its id or identifier.
Parameters resource_id (integer or string) (required). Project id or identifier.
Returns True
>>> redmine.project.delete(1)
True
5.4.3 Project Membership

28
Manager
All operations on the project membership resource are provided via its manager. To get access to it you have to call
redmine.project_membership where redmine is a configured redmine object. See the Configuration about
how to configure redmine object.
Create methods
create
Creates new project membership resource with given fields and saves it to the Redmine.
Parameters
project_id (integer or string) (required). Id or identifier of the project.
user_id (integer) (required). Id of the user to add to the project.
role_ids (list or tuple) (required). Role ids to add to the user in this project.
Returns ProjectMembership resource object
>>> membership = redmine.project_membership.create(project_id=vacation, user_id=1, role_ids=[1, 2])

>>> membership
<redmine.resources.ProjectMembership #123>
new
Creates new empty project membership resource but doesnt save it to the Redmine. This is useful if you want
to set some resource fields later based on some condition(s) and only after that save it to the Redmine. Valid
attributes are the same as for create method above.
>>> membership = redmine.project_membership.new()
>>> membership.project_id = vacation
>>> membership.user_id = 1
>>> membership.role_ids = [1, 2]
>>> membership.save()
True
Read methods
get
redmine.managers.ResourceManager.get(resource_id)
Returns single project membership resource from the Redmine by its id.
Parameters resource_id (integer) (required). Project membership id.
5.4. Resources
29
>>> membership = redmine.project_membership.get(521)

>>> membership
<redmine.resources.ProjectMembership #521>
all

filter
Returns project membership resources that match the given lookup parameters.
Parameters
project_id (integer or string) (required). Id or identifier of the project.
>>> memberships = redmine.project_membership.filter(project_id=vacation)
>>> memberships
<redmine.resultsets.ResourceSet object with ProjectMembership resources>
Hint: You can also get project memberships from a project resource object directly using memberships relation:
>>> project.memberships
<redmine.resultsets.ResourceSet object with ProjectMembership resources>
Update methods
update
Updates values of given fields of a project membership resource and saves them to the Redmine.
Parameters
resource_id (integer) (required). Project membership id.
role_ids (list or tuple) (required). Role ids to add to the user in this project.
Returns True
>>> redmine.project_membership.update(1, role_ids=[1, 2])
True
30
save
redmine.resources.ProjectMembership.save()
Saves the current state of a project membership resource to the Redmine. Fields that can be changed are the
same as for update method above.
Returns True
>>> membership = redmine.project_membership.get(1)
>>> membership.role_ids = [1, 2]
>>> membership.save()
True
Delete methods
delete
Deletes single project membership resource from the Redmine by its id.
Parameters resource_id (integer) (required). Project membership id.
Returns True
>>> redmine.project_membership.delete(1)
True
5.4.4 User
Manager
All operations on the user resource are provided via 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
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 (integer) (optional). Authentication mode id.
5.4. Resources
31
Returns User resource object
>>> user = redmine.user.create(login=jsmith, password=qwerty, firstname=John, lastname=Smith,

>>> user
<redmine.resources.User #32 "John Smith">
new
Creates new empty user resource but doesnt save it to the Redmine. This is useful if you want to set some
>>> 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.custom_fields = [{id: 1, value: foo}, {id: 2, value: bar}]
>>> user.save()
True
Read methods
get
Returns single user resource from the Redmine by its id.
Parameters
resource_id (integer) (required). Id of the user.
include (string)
memberships
groups
>>> user = redmine.user.get(17, include=memberships,groups)
>>> user
Hint: You can easily get the details of the user whose credentials were used to access the API:
>>> user = redmine.user.get(current)
>>> user

32
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
a include keyword argument. The 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
<redmine.resultsets.ResourceSet object with Group resources>
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:
issues
time_entries
deals (only available if CRM plugin is installed)
contacts (only available if CRM plugin is installed)
>>> user.issues
all
Returns all user resources from the Redmine.
Parameters
>>> users = redmine.user.all(offset=10, limit=100)
>>> users
<redmine.resultsets.ResourceSet object with User resources>
filter
Returns user resources that match the given lookup parameters.
5.4. Resources
33
Parameters
status (integer)
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 (integer) (optional). Get only users who are members of the given group.
>>> users = redmine.user.filter(offset=10, limit=100, status=3)
>>> users
Hint: You can also get users from a group resource object directly using users on demand includes:
>>> group = redmine.group.get(524)
>>> group.users
Update methods
update
Updates values of given fields of a user resource and saves them to the Redmine.
Parameters
resource_id (integer) (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.
auth_source_id (integer) (optional). Authentication mode id.
Returns True
>>> redmine.user.update(1, login=jsmith, password=qwerty, firstname=John, lastname=Smith, mai

True
34
save
redmine.resources.User.save()
Saves the current state of a user resource to the Redmine. Fields that can be changed are the same as for update
method above.
Returns True
>>> user.login = jsmith
>>> user.password = qwerty
>>> user.firstname = John
>>> user.lastname = Smith
>>> user.mail = john@smith.com
>>> user.auth_source_id = 1
>>> user.custom_fields = [{id: 1, value: foo}, {id: 2, value: bar}]
>>> user.save()
True
Delete methods
delete
Deletes single user resource from the Redmine by its id.
Parameters resource_id (integer) (required). User id.
Returns True
>>> redmine.user.delete(1)
True
5.4.5 Time Entry

Manager
All operations on the time entry resource are provided via its manager. To get access to it you have to call
redmine.time_entry where redmine is a configured redmine object. See the Configuration about how to
configure redmine object.
Create methods
create
Creates new time entry resource with given fields and saves it to the Redmine.
Parameters
issue_id or project_id (integer) (required). The issue id or project id to log time on.
5.4. Resources
35
hours (integer) (required). The number of spent hours.

spent_on (string or date object) (optional). The date the time was spent (current date if
not set).
activity_id (integer) (optional). The id of the time activity. This parameter is required
unless a default activity is defined in Redmine.
comments (string) (optional). Short description for the entry (255 characters max).
Returns TimeEntry resource object
>>> time_entry = redmine.time_entry.create(issue_id=123, spent_on=2014-01-14, hours=3, activity_id=

>>> time_entry
<redmine.resources.TimeEntry #12345>
new
Creates new empty time entry resource but doesnt save it to the Redmine. This is useful if you want to set some
>>> time_entry = redmine.time_entry.new()
>>> time_entry.issue_id = 123
>>> time_entry.spent_on = date(2014, 1, 14)
>>> time_entry.hours = 3
>>> time_entry.activity_id = 10
>>> time_entry.comments = hello
>>> time_entry.save()
True
Read methods
get
Returns single time entry resource from the Redmine by its id.
Parameters resource_id (integer) (required). Id of the time entry.
>>> time_entry = redmine.time_entry.get(374)
>>> time_entry
<redmine.resources.TimeEntry #374>
all
Returns all time entry resources from the Redmine.
Parameters
36
>>> time_entries = redmine.time_entry.all(offset=10, limit=100)
>>> time_entries
filter
Returns time entry resources that match the given lookup parameters.
Parameters
project_id (integer or string) (optional). Get time entries from the project with the given
id.
issue_id (integer) (optional). Get time entries from the issue with the given id.
user_id (integer) (optional). Get time entries for the user with the given id.
spent_on (string or date object) (optional). Redmine >= 2.3.0 only. Date when hours was
spent.
from_date (string or date object) (optional). New in version 0.4.0. Limit time entries
from this date.
to_date (string or date object) (optional). New in version 0.4.0. Limit time entries until
this date.
hours (string) (optional). Get only time entries that are =, >=, <= hours.
>>> time_entries = redmine.time_entry.filter(offset=10, limit=100, project_id=vacation, hours=>=8

>>> time_entries
Hint: You can also get time entries from an issue resource object and starting from 1.0.0 project and user resource
objects directly using time_entries relation:
>>> issue.time_entries
Update methods
update
Updates values of given fields of a time entry resource and saves them to the Redmine.
Parameters
5.4. Resources
37
resource_id (integer) (required). Time entry id.

issue_id or project_id (integer) (optional). The issue id or project id to log time on.
hours (integer) (optional). The number of spent hours.
spent_on (string or date object) (optional). The date the time was spent.
activity_id (integer) (optional). The id of the time activity.
comments (string) (optional). Short description for the entry (255 characters max).
Returns True
>>> redmine.time_entry.update(1, issue_id=123, spent_on=2014-01-14, hours=3, activity_id=10, commen

True
save
redmine.resources.TimeEntry.save()
Saves the current state of a time entry resource to the Redmine. Fields that can be changed are the same as for
Returns True
>>> time_entry = redmine.time_entry.get(1)
>>> time_entry.issue_id = 123
>>> time_entry.spent_on = date(2014, 1, 14)
>>> time_entry.hours = 3
>>> time_entry.activity_id = 10
>>> time_entry.comments = hello
>>> time_entry.save()
True
Delete methods
delete
Deletes single time entry resource from the Redmine by its id.
Parameters resource_id (integer) (required). Time entry id.
Returns True
>>> redmine.time_entry.delete(1)
True
5.4.6 News
Manager
All operations on the news resource are provided via its manager. To get access to it you have to call redmine.news
38
Create methods
Read methods
get

all
Returns all news resources from the Redmine.
Parameters
>>> news = redmine.news.all(offset=10, limit=100)
>>> news
<redmine.resultsets.ResourceSet object with News resources>
filter
Returns news resources that match the given lookup parameters.
Parameters
project_id (integer or string) (required). Id or identifier of news project.
>>> news = redmine.news.filter(project_id=vacation)
>>> news
Hint: You can also get news from a project resource object directly using news relation:
>>> project.news
Update methods
5.4. Resources
39
Delete methods
5.4.7 Issue Relation

Manager
All operations on the issue relation resource are provided via its manager. To get access to it you have to call
redmine.issue_relation where redmine is a configured redmine object. See the Configuration about how
to configure redmine object.
Create methods
create
Creates new issue relation resource with given fields and saves it to the Redmine.
Parameters
issue_id (integer) (required). Creates a relation for the issue of given id.
issue_to_id (integer) (required). Id of the related issue.
relation_type (string)
relates
duplicates
duplicated
blocks
blocked
precedes
follows
delay (integer) (optional). Delay in days for a precedes or follows relation.
Returns IssueRelation resource object
>>> relation = redmine.issue_relation.create(issue_id=12345, issue_to_id=54321, relation_type=preced

>>> relation
<redmine.resources.IssueRelation #667>
new
Creates new empty issue relation resource but doesnt save it to the Redmine. This is useful if you want to set
some resource fields later based on some condition(s) and only after that save it to the Redmine. Valid attributes
are the same as for create method above.
40

>>> relation = redmine.issue_relation.new()
>>> relation.issue_id = 12345
>>> relation.issue_to_id = 54321
>>> relation.relation_type = precedes
>>> relation.delay = 5
>>> relation.save()
True
Read methods
get
Returns single issue relation resource from the Redmine by its id.
Parameters resource_id (integer) (required). Id of the issue relation.
>>> relation = redmine.issue_relation.get(606)
>>> relation
<redmine.resources.IssueRelation #606>
all

filter
Returns issue relation resources that match the given lookup parameters.
Parameters
issue_id (integer) (required). Get relations from the issue with the given id.
>>> relations = redmine.issue_relation.filter(issue_id=6543)
>>> relations
<redmine.resultsets.ResourceSet object with IssueRelation resources>
Hint: You can also get issue relations from an issue resource object directly using relations relation:
>>> issue.relations
<redmine.resultsets.ResourceSet object with IssueRelation resources>
5.4. Resources
41
Update methods
Delete methods
delete
Deletes single issue relation resource from the Redmine by its id.
Parameters resource_id (integer) (required). Issue relation id.
Returns True
>>> redmine.issue_relation.delete(1)
True
5.4.8 Version
Manager
All operations on the version resource are provided via its manager. To get access to it you have to call
redmine.version where redmine is a configured redmine object. See the Configuration about how to configure redmine object.
Create methods
create
Creates new version resource with given fields and saves it to the Redmine.
Parameters
project_id (integer or string) (required). Id or identifier of versions project.
name (string) (required). Version name.
status (string)
open (default)
locked
closed
sharing (string)
none (default)
descendants
hierarchy
tree
42
system
due_date (string or date object) (optional). Expiration date.
description (string) (optional). Version description.
wiki_page_title (string) (optional). Version wiki page title.
Returns Version resource object
>>> version = redmine.version.create(project_id=vacation, name=Vacation, status=open, sharing=

>>> version
<redmine.resources.Version #235 "Vacation">
new
Creates new empty version resource but doesnt save it to the Redmine. This is useful if you want to set some
>>> version = redmine.version.new()
>>> version.project_id = vacation
>>> version.name = Vacation
>>> version.status = open
>>> version.sharing = none
>>> version.due_date = date(2014, 1, 30)
>>> version.description = my vacation
>>> version.wiki_page_title = Vacation
>>> version.save()
True
Read methods
get
Returns single version resource from the Redmine by its id.
Parameters resource_id (integer) (required). Id of the version.
>>> version = redmine.version.get(1)
>>> version
<redmine.resources.Version #1 "Release 1">
all
5.4. Resources
43
filter
Returns version resources that match the given lookup parameters.
Parameters
project_id (integer or string) (required). Id or identifier of versions project.
>>> versions = redmine.version.filter(project_id=vacation)
>>> versions
<redmine.resultsets.ResourceSet object with Versions resources>
Hint: You can also get versions from a project resource object directly using versions relation:
>>> project.versions
<redmine.resultsets.ResourceSet object with Version resources>
Update methods
update
Updates values of given fields of a version resource and saves them to the Redmine.
Parameters
resource_id (integer) (required). Version id.
name (string) (optional). Version name.
status (string)
open (default)
locked
closed
sharing (string)
none (default)
descendants
hierarchy
tree
system
due_date (string or date object) (optional). Expiration date.
description (string) (optional). Version description.
wiki_page_title (string) (optional). Version wiki page title.
44
Returns True
>>> redmine.version.update(1, name=Vacation, status=open, sharing=none, due_date=2014-01-30,
True
save
redmine.resources.Version.save()
Saves the current state of a version resource to the Redmine. Fields that can be changed are the same as for
Returns True
>>> version = redmine.version.get(1)
>>> version.name = Vacation
>>> version.status = open
>>> version.sharing = none
>>> version.due_date = date(2014, 1, 30)
>>> version.description = my vacation
>>> version.wiki_page_title = Vacation
>>> version.save()
True
Delete methods
delete
Deletes single version resource from the Redmine by its id.
Parameters resource_id (integer) (required). Version id.
Returns True
>>> redmine.version.delete(1)
True
5.4.9 Wiki Page

Manager
All operations on the wiki page resource are provided via its manager. To get access to it you have to call
redmine.wiki_page where redmine is a configured redmine object. See the Configuration about how to configure redmine object.
Create methods
create
Creates new wiki page resource with given fields and saves it to the Redmine.
5.4. Resources
45
Parameters
project_id (integer or string) (required). Id or identifier of wiki pages project.
title (string) (required). Title of the wiki page.
text (string) (required). Text of the wiki page.
comments (string) (optional). Comments of the wiki page.
Returns WikiPage resource object
>>> wiki_page = redmine.wiki_page.create(project_id=vacation, title=FooBar, text=foo, comments=

>>> wiki_page
<redmine.resources.WikiPage "FooBar">
new
Creates new empty wiki page resource but doesnt save it to the Redmine. This is useful if you want to set some
>>> wiki_page = redmine.wiki_page.new()
>>> wiki_page.project_id = vacation
>>> wiki_page.title = FooBar
>>> wiki_page.text = foo
>>> wiki_page.comments = bar
>>> wiki_page.save()
True
Read methods
get
Returns single wiki page resource from the Redmine by its title.
Parameters
resource_id (string) (required). Title of the wiki page.
version (integer) (optional). Version of the wiki page.
include (string)
attachments
>>> wiki_page = redmine.wiki_page.get(Photos, project_id=vacation, version=12, include=attachmen

>>> wiki_page
<redmine.resources.WikiPage "Photos">
46
WikiPage 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 WikiPage 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 a include keyword argument. The on demand includes provided by the WikiPage resource object are
the same as in the get method above:
>>> wiki_page = redmine.wiki_page.get(524)
>>> wiki_page.attachments
<redmine.resultsets.ResourceSet object with Attachment resources>
all

filter
Returns wiki page resources that match the given lookup parameters.
Parameters
>>> wiki_pages = redmine.wiki_page.filter(project_id=vacation)
>>> wiki_pages
<redmine.resultsets.ResourceSet object with WikiPage resources>
Hint: You can also get wiki pages from a project resource object directly using wiki_pages relation:
>>> project.wiki_pages
<redmine.resultsets.ResourceSet object with WikiPage resources>
Update methods
update
Updates values of given fields of a wiki page resource and saves them to the Redmine.
Parameters
5.4. Resources
47
title (string) (optional). Title of the wiki page.

text (string) (optional). Text of the wiki page.
comments (string) (optional). Comments of the wiki page.
Returns True
>>> redmine.wiki_page.update(Foo, project_id=vacation, title=FooBar, text=foo, comments=bar

True
save
redmine.resources.WikiPage.save()
Saves the current state of a wiki page resource to the Redmine. Fields that can be changed are the same as for
Returns True
>>> wiki_page = redmine.wiki_page.get(Foo, project_id=vacation)
>>> wiki_page.title = Bar
>>> wiki_page.text = bar
>>> wiki_page.comments = changed foo to bar
>>> wiki_page.save()
True
Delete methods
delete
redmine.managers.ResourceManager.delete(resource_id, **params)
Deletes single wiki page resource from the Redmine by its title.
Parameters
Returns True
>>> redmine.wiki_page.delete(Foo, project_id=1)
True
5.4.10 Query
Manager
All operations on the query resource are provided via its manager. To get access to it you have to call
redmine.query where redmine is a configured redmine object. See the Configuration about how to configure
redmine object.
48
Create methods
Read methods
get

all
Returns all query resources from the Redmine.
Parameters
>>> queries = redmine.query.all(offset=10, limit=100)
>>> queries
<redmine.resultsets.ResourceSet object with Query resources>
filter

Update methods
Delete methods
5.4.11 Attachment
Manager
All operations on the attachment resource are provided via its manager. To get access to it you have to call
redmine.attachment where redmine is a configured redmine object. See the Configuration about how to
5.4. Resources
49
Create methods
Not supported by Redmine. Some resources support adding attachments via its create/update methods, e.g. issue.
Read methods
get
Returns single attachment resource from the Redmine by its id.
Parameters resource_id (integer) (required). Id of the attachment.
Returns Attachment resource object
>>> attachment = redmine.attachment.get(76905)
>>> attachment
<redmine.resources.Attachment #76905 "1(a).png">
Attachment can be easily downloaded via the provided download() method which is a proxy to the
redmine.download() method which provides several options to control the saving process (see docs for details):
>>> attachment = redmine.attachment.get(76905)
>>> filepath = attachment.download(savepath=/usr/local/, filename=image.jpg)
>>> filepath
/usr/local/image.jpg
all

filter

Update methods
Delete methods
50
5.4.12 Issue Status

Manager
All operations on the issue status resource are provided via its manager. To get access to it you have to call
redmine.issue_status where redmine is a configured redmine object. See the Configuration about how
Create methods
Read methods
get

all
redmine.managers.ResourceManager.all()
Returns all issue status resources from the Redmine.
Parameters
>>> statuses = redmine.issue_status.all()
>>> statuses
<redmine.resultsets.ResourceSet object with IssueStatus resources>
IssueStatus resource object provides you with some relations. Relations are the other resource objects wrapped in a
ResourceSet which are somehow related to an IssueStatus resource object. The relations provided by the IssueStatus
resource object are:
issues
>>> statuses = redmine.issue_status.all()
>>> statuses[0]
<redmine.resources.IssueStatus #1 "New">
>>> statuses[0].issues
5.4. Resources
51
filter

Update methods
Delete methods
5.4.13 Tracker
Manager
All operations on the tracker resource are provided via its manager. To get access to it you have to call
redmine.tracker where redmine is a configured redmine object. See the Configuration about how to configure redmine object.
Create methods
Read methods
get

all
Returns all tracker resources from the Redmine.
Parameters
>>> trackers = redmine.tracker.all()
>>> trackers
<redmine.resultsets.ResourceSet object with Tracker resources>
52
Tracker resource object provides you with some relations. Relations are the other resource objects wrapped in a
ResourceSet which are somehow related to a Tracker resource object. The relations provided by the Tracker resource
object are:
issues
>>> trackers = redmine.tracker.all()
>>> trackers[0]
<redmine.resources.Tracker #1 "FooBar">
>>> trackers[0].issues
filter

Update methods
Delete methods
5.4.14 Enumeration
Manager
All operations on the enumeration resource are provided via its manager. To get access to it you have to call
redmine.enumeration where redmine is a configured redmine object. See the Configuration about how to
Create methods
5.4. Resources
53
Read methods
get

all

filter
Returns enumeration resources that match the given lookup parameters.
Parameters
resource (string)
issue_priorities
time_entry_activities
document_categories
>>> enumerations = redmine.enumeration.filter(resource=time_entry_activities)
>>> enumerations
<redmine.resultsets.ResourceSet object with Enumeration resources>
Update methods
Delete methods
5.4.15 Issue Category

Manager
All operations on the issue category resource are provided via its manager. To get access to it you have to call
redmine.issue_category where redmine is a configured redmine object. See the Configuration about how
54
Create methods
create
Creates new issue category resource with given fields and saves it to the Redmine.
Parameters
project_id (integer or string) (required). Id or identifier of issue categorys project.
name (string) (required). Issue category name.
assigned_to_id (integer) (optional). The id of the user assigned to the category (new
issues with this category will be assigned by default to this user).
Returns IssueCategory resource object
>>> category = redmine.issue_category.create(project_id=vacation, name=woohoo, assigned_to_id=13)

>>> category
<redmine.resources.IssueCategory #810 "woohoo">
new
Creates new empty issue category resource but doesnt save it to the Redmine. This is useful if you want to set
some resource fields later based on some condition(s) and only after that save it to the Redmine. Valid attributes
>>> category = redmine.issue_category.new()
>>> category.project_id = vacation
>>> category.name = woohoo
>>> category.assigned_to_id = 13
>>> category.save()
True
Read methods
get
Returns single issue category resource from the Redmine by its id.
Parameters resource_id (integer) (required). Id of the issue category.
>>> category = redmine.issue_category.get(794)
>>> category
<redmine.resources.IssueCategory #794 "Malibu">
all

5.4. Resources
55
filter
Returns issue category resources that match the given lookup parameters.
Parameters
project_id (integer or string) (required). Get issue categories from the project with the
given id, where id is either project id or project identifier.
>>> categories = redmine.issue_category.filter(project_id=vacation)
>>> categories
<redmine.resultsets.ResourceSet object with IssueCategory resources>
Hint: You can also get issue categories from a project resource object directly using issue_categories relation:
>>> project.issue_categories
<redmine.resultsets.ResourceSet object with IssueCategory resources>
Update methods
update
Updates values of given fields of an issue category resource and saves them to the Redmine.
Parameters
resource_id (integer) (required). Issue category id.
name (string) (optional). Issue category name.
assigned_to_id (integer) (optional). The id of the user assigned to the category (new
issues with this category will be assigned by default to this user).
Returns True
>>> redmine.issue_category.update(1, name=woohoo, assigned_to_id=13)
True
save
redmine.resources.IssueCategory.save()
Saves the current state of an issue category resource to the Redmine. Fields that can be changed are the same as
for update method above.
Returns True
56
>>> category = redmine.issue_category.get(1)

>>> category.name = woohoo
>>> category.assigned_to_id = 13
>>> category.save()
True
Delete methods
delete
redmine.managers.ResourceManager.delete(resource_id, **params)
Deletes single issue category resource from the Redmine by its id.
Parameters
resource_id (integer) (required). Issue category id.
reassign_to_id (integer) (optional). When there are issues assigned to the category you
are deleting, this parameter lets you reassign these issues to the category with given id.
Returns True
>>> redmine.issue_category.delete(1, reassign_to_id=2)
True
5.4.16 Role
Manager
All operations on the role resource are provided via its manager. To get access to it you have to call redmine.role
Create methods
Read methods
get
Returns single role resource from the Redmine by its id.
Parameters resource_id (integer) (required). Id of the role.
Returns Role resource object
>>> role = redmine.role.get(4)
>>> role
<redmine.resources.Role #4 "Waiter">
5.4. Resources
57
all
Returns all role resources from the Redmine.
Parameters
>>> roles = redmine.role.all()
>>> roles
<redmine.resultsets.ResourceSet object with Role resources>
filter

Update methods
Delete methods
5.4.17 Group
Manager
All operations on the group resource are provided via its manager. To get access to it you have to call
redmine.group where redmine is a configured redmine object. See the Configuration about how to configure
redmine object.
Create methods
create
Creates new group resource with given fields and saves it to the Redmine.
Parameters
name (string) (required). Group name.
user_ids (list or tuple) (optional). Ids of users who will be members of a group.
Returns Group resource object
58
>>> group = redmine.group.create(name=Developers, user_ids=[13, 15, 25])

>>> group
<redmine.resources.Group #8 "Developers">
new
Creates new empty group resource but doesnt save it to the Redmine. This is useful if you want to set some
>>> group = redmine.group.new()
>>> group.name = Developers
>>> group.user_ids = [13, 15, 25]
>>> group.save()
True
Read methods
get
Returns single group resource from the Redmine by its id.
Parameters
resource_id (integer) (required). Id of the group.
include (string)
memberships
users
>>> group = redmine.group.get(524, include=memberships,users)
>>> group
<redmine.resources.Group #524 "DESIGN">
Group 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 Group resource object. Keep in mind that on demand includes
a include keyword argument. The on demand includes provided by the Group resource object are the same as in
the get method above:
5.4. Resources
59

>>> group.users
all
Returns all group resources from the Redmine.
Parameters
>>> groups = redmine.group.all()
>>> groups
<redmine.resultsets.ResourceSet object with Group resources>
filter

Update methods
update
Updates values of given fields of a group resource and saves them to the Redmine.
Parameters
resource_id (integer) (required). Group id.
name (string) (optional). Group name.
user_ids (list or tuple) (optional). Ids of users who will be members of a group.
Returns True
>>> redmine.group.update(1, name=Developers, user_ids=[13, 15, 25])
True
save
redmine.resources.Group.save()
Saves the current state of a group resource to the Redmine. Fields that can be changed are the same as for
Returns True
60

>>> group.name = Developers
>>> group.user_ids = [13, 15, 25]
>>> group.save()
True
Delete methods
delete
Deletes single group resource from the Redmine by its id.
Parameters resource_id (integer) (required). Group id.
Returns True
>>> redmine.group.delete(1)
True
Users
Python Redmine provides 2 methods to work with group users: add and remove.
add
redmine.resources.Group.User.add(user_id)
Adds a user to a group by its id.
Returns True
>>> group.user.add(1)
True
remove
redmine.resources.Group.User.remove(user_id)
Removes a user from a group by its id.
Returns True
>>> group.user.remove(1)
True
5.4. Resources
61
5.4.18 Custom Field

Manager
All operations on the custom field resource are provided via its manager. To get access to it you have to call
redmine.custom_field where redmine is a configured redmine object. See the Configuration about how
Create methods
Read methods
get

all
Returns all custom field resources from the Redmine.
Parameters
>>> fields = redmine.custom_field.all()
>>> fields
<redmine.resultsets.ResourceSet object with CustomField resources>
filter

Update methods
Delete methods
62
5.4.19 Contact
Supported starting from version 1.0.0 and only available if CRM plugin is installed.
Hint: It is highly recommended to use CRM plugin 3.3.0 and higher because some bugs and inconsistencies in REST
API exists in older versions.
Manager
All operations on the contact resource are provided via its manager. To get access to it you have to call
redmine.contact where redmine is a configured redmine object. See the Configuration about how to configure redmine object.
Create methods
create
Creates new contact resource with given fields and saves it to the CRM plugin.
Parameters
project_id (integer or string) (required). Id or identifier of contacts project.
first_name (string) (required). Contact first name.
last_name (string) (optional). Contact last name.
middle_name (string) (optional). Contact middle name.
company (string) (optional). Contact company name.
phones (list) (optional). List of phone numbers.
emails (list) (optional). List of emails.
website (string) (optional). Contact website.
skype_name (string) (optional). Contact skype.
birthday (string or date object) (optional). Contact birthday.
background (string) (optional). Contact background.
job_title (string) (optional). Contact job title.
tag_list (list) (optional). List of tags.
is_company (boolean) (optional). Whether contact is a company.
assigned_to_id (integer) (optional). Contact will be assigned to this user id.
address_attributes (dict)
street1 - first line for the street details
street2 - second line for the street details
city - city
5.4. Resources
63
region - region (state)

postcode - ZIP code
country_code - country code as two-symbol abbreviation (e.g. US)
visibility (integer)
0 - project
1 - public
2 - private
Returns Contact resource object
>>> contact = redmine.contact.create(project_id=vacation, first_name=Ivan, last_name=Ivanov, mi

>>> contact
<redmine.resources.Contact #1 "Ivan Ivanov">
new
Creates new empty contact resource but doesnt save it to the CRM plugin. This is useful if you want to set some
resource fields later based on some condition(s) and only after that save it to the CRM plugin. Valid attributes
>>> contact = redmine.contact.new()

>>> contact.project_id = vacation
>>> contact.first_name = Ivan
>>> contact.last_name = Ivanov
>>> contact.middle_name = Ivanovich
>>> contact.company = Ivan Gmbh
>>> contact.phones = [1234567]
>>> contact.emails = [ivan@ivanov.com]
>>> contact.website = ivanov.com
>>> contact.skype_name = ivan.ivanov
>>> contact.birthday = 1980-10-21
>>> contact.background = some background here
>>> contact.job_title = CEO
>>> contact.tag_list = [vip, online]
>>> contact.is_company = False
>>> contact.address_attributes = {street1: foo, street2: bar, city: Moscow, postcode:
>>> contact.custom_fields = [{id: 1, value: foo}, {id: 2, value: bar}]
>>> contact.visibility = 0
>>> contact.save()
True
Read methods
get
Returns single contact resource from the CRM plugin by its id.
Parameters
64
resource_id (integer) (required). Id of the contact.

include (string)
notes
contacts
deals
issues
>>> contact = redmine.contact.get(12345, include=notes,contacts,deals,issues)
>>> contact
<redmine.resources.Contact #1 "Ivan Ivanov">
Hint: Contact 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 Contact 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 a include keyword argument. The on demand includes provided by the Contact resource object are
the same as in the get method above:
>>> contact = redmine.contact.get(12345)
>>> contact.issues
all
Returns all contact resources from the CRM plugin.
Parameters
>>> contacts = redmine.contact.all(offset=10, limit=100)
>>> contacts
<redmine.resultsets.ResourceSet object with Contact resources>
filter
Returns contact resources that match the given lookup parameters.
Parameters
project_id (integer or string) (optional). Id or identifier of contacts project.
assigned_to_id (integer) (optional). Get contacts which are assigned to this user id.
query_id (integer) (optional). Get contacts for the given query id.
search (string) (optional). Get contacts with the given search string.
5.4. Resources
65
tags (string) (optional). Get contacts with the given tags (separated by comma).
>>> contacts = redmine.contact.filter(project_id=vacation, assigned_to_id=123, search=Smith, tags

>>> contacts
Hint: You can also get contacts from a project and user resource objects directly using contacts relation:
>>> project.contacts
Update methods
update
Updates values of given fields of a contact resource and saves them to the CRM plugin.
Parameters
resource_id (integer) (required). Contact id.
first_name (string) (optional). Contact first name.
last_name (string) (optional). Contact last name.
middle_name (string) (optional). Contact middle name.
company (string) (optional). Contact company name.
phones (list) (optional). List of phone numbers.
emails (list) (optional). List of emails.
website (string) (optional). Contact website.
skype_name (string) (optional). Contact skype.
birthday (string or date object) (optional). Contact birthday.
background (string) (optional). Contact background.
job_title (string) (optional). Contact job title.
tag_list (list) (optional). List of tags.
is_company (boolean) (optional). Whether contact is a company.
assigned_to_id (integer) (optional). Contact will be assigned to this user id.
address_attributes (dict)
street1 - first line for the street details
street2 - second line for the street details
66
city - city
region - region (state)
postcode - ZIP code
country_code - country code as two-symbol abbreviation (e.g. US)
visibility (integer)
0 - project
1 - public
2 - private
Returns True
>>> redmine.contact.update(12345, first_name=Ivan, last_name=Ivanov, middle_name=Ivanovich, com

True
save
redmine.resources.Contact.save()
Saves the current state of a contact resource to the CRM plugin. Fields that can be changed are the same as for
Returns True

>>> contact.first_name = Ivan
>>> contact.last_name = Ivanov
>>> contact.middle_name = Ivanovich
>>> contact.company = Ivan Gmbh
>>> contact.phones = [1234567]
>>> contact.emails = [ivan@ivanov.com]
>>> contact.website = ivanov.com
>>> contact.skype_name = ivan.ivanov
>>> contact.birthday = 1980-10-21
>>> contact.background = some background here
>>> contact.job_title = CEO
>>> contact.tag_list = [vip, online]
>>> contact.is_company = False
>>> contact.address_attributes = {street1: foo, street2: bar, city: Moscow, postcode:
>>> contact.custom_fields = [{id: 1, value: foo}, {id: 2, value: bar}]
>>> contact.visibility = 0
>>> contact.save()
True
Delete methods
delete
Deletes single contact resource from the CRM plugin by its id.
Parameters resource_id (integer) (required). Contact id.
Returns True
5.4. Resources
67
>>> redmine.contact.delete(1)
True
Projects
Python Redmine provides 2 methods to work with contact projects: add and remove.
add
redmine.resources.Contact.Project.add(project_id)
Adds project to contacts project list.
Parameters project_id (integer or string) (required). Id or identifier of a project.
Returns True
>>> contact.project.add(vacation)
True
remove
redmine.resources.Contact.Project.remove(project_id)
Removes project from contacts project list.
Parameters project_id (integer or string) (required). Id or identifier of a project.
Returns True
>>> contact.project.remove(vacation)
True
5.4.20 Contact Tag

Supported starting from version 1.0.0 and only available if CRM plugin 3.4.0 and higher is installed.
Manager
All operations on the contact tag resource are provided via its manager. To get access to it you have to call
redmine.contact_tag where redmine is a configured redmine object. See the Configuration about how to
Create methods
Not supported by CRM plugin
68
Read methods
get

all
Returns all contact tag resources from the CRM plugin.
Parameters
>>> tags = redmine.contact_tag.all()
>>> tags
<redmine.resultsets.ResourceSet object with ContactTag resources>
filter

Update methods
Delete methods
5.4.21 Note
Manager
All operations on the note resource are provided via its manager. To get access to it you have to call redmine.note
Create methods
5.4. Resources
69
Read methods
get
Returns single note resource from the Redmine by its id.
Parameters resource_id (integer) (required). Id of the note.
Returns Note resource object
>>> note = redmine.note.get(12345)
>>> note
<redmine.resources.Note #12345>
all

filter

Update methods
Delete methods
5.4.22 Deal
Supported starting from version 1.0.0 and only available if CRM plugin is installed.
Hint: It is highly recommended to use CRM plugin 3.3.0 and higher because some bugs and inconsistencies in REST
API exists in older versions.
Manager
All operations on the deal resource are provided via its manager. To get access to it you have to call redmine.deal
Create methods
create
Creates new deal resource with given fields and saves it to the CRM plugin.
70
Parameters
project_id (integer or string) (required). Id or identifier of deals project.
name (string) (required). Deal name.
contact_id (integer) (optional). Deal contact id.
price (integer) (optional). Deal price.
currency (string) (optional). Deal currency.
probability (integer) (optional). Deal probability.
due_date (string or date object) (optional). Deal should be won by this date.
background (string) (optional). Deal background.
status_id (integer) (optional). Deal status id.
category_id (integer) (optional). Deal category id.
assigned_to_id (integer) (optional). Deal will be assigned to this user id.
Returns Deal resource object
>>> deal = redmine.deal.create(project_id=vacation, name=FooBar, contact_id=1, price=1000, curren

>>> deal
<redmine.resources.Deal #123>
new
Creates new empty deal resource but doesnt save it to the CRM plugin. This is useful if you want to set some
resource fields later based on some condition(s) and only after that save it to the CRM plugin. Valid attributes
>>> deal = redmine.deal.new()
>>> deal.project_id = vacation
>>> deal.name = FooBar
>>> deal.contact_id = 1
>>> deal.price = 1000
>>> deal.currency = EUR
>>> deal.probability = 80
>>> deal.due_date = date(2014, 12, 12)
>>> deal.background = some deal background
>>> deal.status_id = 1
>>> deal.category_id = 1
>>> deal.assigned_to_id = 12
>>> deal.custom_fields = [{id: 1, value: foo}, {id: 2, value: bar}]
>>> deal.save()
True
5.4. Resources
71
Read methods
get
Returns single deal resource from the CRM plugin by its id.
Parameters
resource_id (integer) (required). Id of the deal.
include (string)
notes
>>> deal = redmine.deal.get(123, include=notes)
>>> deal
<redmine.resources.Deal #123>
Hint: Deal 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 Deal resource object. Keep in mind that on demand includes
a include keyword argument. The on demand includes provided by the Deal resource object are the same as in the
get method above:
>>> deal = redmine.deal.get(123)
>>> deal.notes
<redmine.resultsets.ResourceSet object with Note resources>
all
Returns all deal resources from the CRM plugin.
Parameters
>>> deals = redmine.deal.all(limit=50)
>>> deals
<redmine.resultsets.ResourceSet object with Deal resources>
filter
Returns deal resources that match the given lookup parameters.
Parameters
project_id (integer or string) (optional). Id or identifier of deals project.
assigned_to_id (integer) (optional). Get deals which are assigned to this user id.
72
query_id (integer) (optional). Get deals for the given query id.
status_id (integer) (optional). Get deals which have this status id.
search (string) (optional). Get deals with the given search string.
>>> deals = redmine.deal.filter(project_id=vacation, assigned_to_id=123, status_id=1, search=Smith

>>> deals
Hint: You can also get deals from a project, user and deal status resource objects directly using deals relation:
>>> project.deals
Update methods
update
Updates values of given fields of a deal resource and saves them to the CRM plugin.
Parameters
resource_id (integer) (required). Deal id.
name (string) (optional). Deal name.
contact_id (integer) (optional). Deal contact id.
price (integer) (optional). Deal price.
currency (string) (optional). Deal currency.
probability (integer) (optional). Deal probability.
due_date (string or date object) (optional). Deal should be won by this date.
background (string) (optional). Deal background.
status_id (integer) (optional). Deal status id.
category_id (integer) (optional). Deal category id.
assigned_to_id (integer) (optional). Deal will be assigned to this user id.
Returns True
>>> redmine.deal.update(123, name=FooBar, contact_id=1, price=1000, currency=EUR, probability=80,

True
5.4. Resources
73
save
redmine.resources.Deal.save()
Saves the current state of a deal resource to the CRM plugin. Fields that can be changed are the same as for
Returns True
>>> deal = redmine.deal.get(123)
>>> deal.name = FooBar
>>> deal.contact_id = 1
>>> deal.price = 1000
>>> deal.currency = EUR
>>> deal.probability = 80
>>> deal.due_date = date(2014, 12, 12)
>>> deal.background = some deal background
>>> deal.status_id = 1
>>> deal.category_id = 1
>>> deal.assigned_to_id = 12
>>> deal.custom_fields = [{id: 1, value: foo}, {id: 2, value: bar}]
>>> deal.save()
True
Delete methods
delete
Deletes single deal resource from the CRM plugin by its id.
Parameters resource_id (integer) (required). Deal id.
Returns True
>>> redmine.deal.delete(123)
True
5.4.23 Deal Status

Manager
All operations on the deal status resource are provided via its manager. To get access to it you have to call
redmine.deal_status where redmine is a configured redmine object. See the Configuration about how to
Create methods
74
Read methods
get

all
Returns all deal status resources from the CRM plugin.
Parameters
>>> statuses = redmine.deal_status.all()
>>> statuses
<redmine.resultsets.ResourceSet object with DealStatus resources>
Hint: DealStatus resource object provides you with some relations. Relations are the other resource objects wrapped
in a ResourceSet which are somehow related to a DealStatus resource object. The relations provided by the DealStatus
deals
>>> statuses = redmine.deal_status.all()
>>> statuses[0]
<redmine.resources.DealStatus #1 "New">
>>> statuses[0].deals
filter

Update methods
Delete methods
5.4.24 Deal Category

5.4. Resources
75
Manager
All operations on the deal category resource are provided via its manager. To get access to it you have to call
redmine.deal_category where redmine is a configured redmine object. See the Configuration about how to
Create methods
Read methods
get

all

filter
Returns deal category resources that match the given lookup parameters.
Parameters
project_id (integer or string) (required). Id or identifier of deal categorys project.
>>> categories = redmine.deal_category.filter(project_id=vacation)
>>> categories
<redmine.resultsets.ResourceSet object with DealCategory resources>
Hint: You can also get deal categories from a project resource object directly using deal_categories relation:
>>> project.deal_categories
<redmine.resultsets.ResourceSet object with DealCategory resources>
Update methods
Delete methods
76
5.4.25 CRM Query

Manager
All operations on the crm query resource are provided via its manager. To get access to it you have to call
redmine.crm_query where redmine is a configured redmine object. See the Configuration about how to configure redmine object.
Create methods
Read methods
get

all

filter
Returns crm query resources that match the given lookup parameters.
Parameters
resource (string)
contact
deal
>>> queries = redmine.crm_query.filter(resource=contact)
>>> queries
<redmine.resultsets.ResourceSet object with CrmQuery resources>
Hint: CrmQuery resource object provides you with some relations. Relations are the other resource objects wrapped
in a ResourceSet which are somehow related to a CrmQuery resource object. The relations provided by the CrmQuery
deals
5.4. Resources
77
>>> queries = redmine.crm_query.filter(resource=deal)

>>> queries[0]
<redmine.resources.CrmQuery #10 "Deals by category">
>>> queries[0].deals
Update methods
Delete methods
5.5 Advanced Usage

5.5.1 Custom Resources
Sometimes there is a need to redefine a resource behaviour to achieve the needed goal. Python Redmine provides a
feature for such a case called custom resources. Basically this is just a normal class inheritance made especially for
Python Redmine.
Configuration
To take advantage of this feature you need to tell Python Redmine where to search for your custom resources. This
should be done with a custom_resource_paths argument passed to the Redmine object which accepts a list or
tuple of module paths which contain your custom resources:
redmine = Redmine(https://redmine.url, custom_resource_paths=(foo.bar, bar.baz, foo.baz))
Note: The ordering is very important. Python Redmine will search for the resources in this order:
1. foo.bar
2. bar.baz
3. foo.baz
4. redmine.resources
Existing Resources
The list of existing resource class names that can be inherited from is available here.
78
Creation
To create a custom resource choose which resource behavior you want to change, e.g. Project:
from redmine.resources import Project
class CustomProject(Project):
pass
Name
Python Redmine converts underscore to camelcase when it tries to import the resource, that means that it is important
to follow this convention to make everything work properly, e.g when you do:
custom_wiki_page = redmine.custom_wiki_page.get(Foo)
Python Redmine is searching for a resource class named CustomWikiPage in the modules defined via the
custom_resource_paths argument on Redmine object instantiation.
Methods and Attributes
All existing resources are derived from a _Resource class which you usually wont inherit from directly unless you
want to add support for a new resource which Python Redmine doesnt support. Below you will find methods and
attributes which can be redefined in your custom resource:
class redmine.resources._Resource(manager, attributes)
Implementation of Redmine resource
__init__(manager, attributes)
Accepts manager instance object and resource attributes dict
__getattr__(item)
Returns the requested attribute and makes a conversion if needed
__setattr__(item, value)
Sets the requested attribute
refresh(**params)
Reloads resource data from Redmine
pre_create()
Tasks that should be done before creating the resource
post_create()
Tasks that should be done after creating the resource
pre_update()
Tasks that should be done before updating the resource
post_update()
Tasks that should be done after updating the resource
save()
Creates or updates a resource
classmethod translate_params(params)
Translates internal param names to the real Redmine param names if needed
5.5. Advanced Usage
79
5.5.2 External Authentication

It is possible to use Python Redmine as a provider for external authentication based on the Redmine user database, e.g.
imagine you are making a website and you want to only authenticate your users if they provide the same login/password
they use to login to Redmine:
username = john
password = qwerty
# username comes from the POST request on form submit

# password comes from the POST request on form submit
user = Redmine(https://redmine.url, username=username, password=password).auth()
If authentication succeeded, user variable will contain details about the current user, if there was an error during
authentication proccess, an AuthError exception will be thrown.
If you need more control, for example you want to return your own error message, you can intercept AuthError
exception and do what you need, for example:
from redmine.exceptions import AuthError
username = john
password = qwerty
# username comes from the POST request on form submit

# password comes from the POST request on form submit
try:
user = Redmine(https://redmine.url, username=username, password=password).auth()
except AuthError:
raise Exception(Invalid login or password provided)
5.5.3 Working with Files

It is possible to use Python Redmine to upload/download files to/from Redmine. This document describes low-level
interfaces that Python Redmine provides, in most cases they shouldnt be used directly and high-level interfaces, e.g.
uploads parameter in Issue resource or download() method in Attachment resource should be used instead. To
get access to these low-level interfaces you have to call either redmine.upload() or redmine.download()
Upload
redmine.Redmine.upload(filepath)
Uploads file from filepath to Redmine and returns an assigned token which can then be used to attach the
uploaded file to some resource, e.g. Issue.
Parameters filepath (string) (optional). Local path to the file which should be uploaded.
Returns Token string
>>> token = redmine.upload(/usr/local/image.jpg)
>>> token
7167.ed1ccdb093229ca1bd0b043618d88743
Download
80
redmine.Redmine.download(url, savepath=None, filename=None)

Downloads file from Redmine and saves it to savepath or returns it as bytes.
Parameters
url (string) (required). A URL of the file which should be downloaded.
savepath (string) (optional). Local path where file should be saved.
filename (string) (optional). Filename which will be used for a file.
Returns String or Method
If a savepath argument is provided, then a file will be saved into the provided path with its own name, if a
filename argument is provided together with the savepath argument, then a file will be saved into the provided
path under the provided name and the resulting path to the file will be returned.
>>> filepath = redmine.download(https://redmine.url/foobar.jpg, savepath=/usr/local/, filename=i

>>> filepath
/usr/local/image.jpg
If only a url argument is provided, then a iter_content method will be returned which you can call with the needed
arguments to have full control over the iteration over the response data.
>>> iter_content = redmine.download(https://redmine.url/foobar.jpg)
>>> for chunk in iter_content(chunk_size=1024):
# do something with chunk
5.6 Frequently Asked Questions

5.6.1 Create/Update/Delete resource operations doesnt work
Your Redmine server is probably using https as the primary protocol and youre trying to connect to it under http
protocol. Please use the https protocol and it should work.
The problem described above happens because when youre trying to connect using the http protocol, your server
issues a redirect to the https which changes the request method, e.g. if your were trying to create/update/delete a
resource, then POST/PUT/DELETE is changing to GET which expectedly causes the create/update/delete operations
to fail.
The detailed explanation about why this happens is available here.
5.6.2 Can I use python-redmine with ChiliProject fork

Yes, you can. But keep in mind that ChiliProject is not actively developed and some features in REST API are missing,
not all filters will work, etc. Several problems are described in issues #37 and #38.
5.7 Exceptions
Python Redmine tries its best to provide human readable errors in all situations. This is the list of all exceptions that
Python Redmine can throw:
exception redmine.exceptions.BaseRedmineError(*args, **kwargs)
Base exception class for Redmine exceptions
5.6. Frequently Asked Questions
81
exception redmine.exceptions.ResourceError
Unsupported Redmine resource exception
exception redmine.exceptions.NoFileError
File doesnt exist exception
exception redmine.exceptions.ResourceNotFoundError
Requested resource doesnt exist
exception redmine.exceptions.ConflictError
Resource version on the server is newer than clients
exception redmine.exceptions.AuthError
Invalid authentication details
exception redmine.exceptions.ImpersonateError
Invalid impersonate login provided
exception redmine.exceptions.ServerError
Redmine internal error
exception redmine.exceptions.RequestEntityTooLargeError
Size of the request exceeds the capacity limit on the server
exception redmine.exceptions.UnknownError(code)
Redmine returned unknown error
exception redmine.exceptions.ValidationError(error)
Redmine validation errors occured on create/update resource
exception redmine.exceptions.ResourceSetIndexError
Index doesnt exist in the ResourceSet
exception redmine.exceptions.ResourceSetFilterParamError
Resource set filter method expects to receive either a list or tuple
exception redmine.exceptions.ResourceBadMethodError
Resource doesnt support the requested method, e.g. get()
exception redmine.exceptions.ResourceFilterError
Resource doesnt support requested filter(s)
exception redmine.exceptions.ResourceNoFiltersProvidedError
No filter(s) provided
exception redmine.exceptions.ResourceNoFieldsProvidedError
No field(s) provided
exception redmine.exceptions.ResourceAttrError
Resource doesnt have the requested attribute
exception redmine.exceptions.ReadonlyAttrError
Resource cant set attribute that is read only
exception redmine.exceptions.VersionMismatchError(feature)
Feature isnt supported on specified Redmine version
exception redmine.exceptions.ResourceVersionMismatchError
Resource isnt supported on specified Redmine version
exception redmine.exceptions.ResultSetTotalCountError
ResultSet hasnt been yet evaluated and cannot yield a total_count
82
exception redmine.exceptions.CustomFieldValueError
Custom fields should be passed as a list of dictionaries
exception redmine.exceptions.ResourceRequirementsError(requirements)
Resource requires specified Redmine plugin(s) to function
exception redmine.exceptions.FileUrlError
URL provided to download a file cant be parsed
exception redmine.exceptions.ForbiddenError
Requested resource is forbidden
exception redmine.exceptions.JSONDecodeError
Unable to decode received JSON
5.8 License
Copyright 2015 Max Tepkeev
Licensed under the Apache License, Version 2.0 (the License); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an
AS IS BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
License for the specific language governing permissions and limitations under the License.
5.9 Changelog
5.9.1 1.1.0 (2015-02-20)
Added: PyPy2/3 is now officially supported
Added: Introduced enabled_modules on demand include in Project resource
Fixed: Issue #78 (Redmine <2.5.2 returns only single tracker instead of a list of all available trackers when
requested from a CustomField resource which caused an Exception in Python Redmine, see this for details)
Fixed: Issue #80 (If a project is read-only or doesnt have CRM plugin enabled, an attempt to add/remove
Contact resource to/from it will lead to improper error message)
Fixed: Issue #81 (Contacts resource tag_list attribute was always splitted into single chars) (thanks to
Alexander Loechel)
5.9.2 1.0.3 (2015-02-03)

Fixed: Issue #72 (If an exception is raised during JSON decoding process, it should be catched and reraised as
Python Redmines own exception, i.e redmine.exceptions.JSONDecodeError)
Fixed: Issue #76 (It was impossible to retrieve more than 100 resources for resources which dont support
limit/offset natively by Redmine, i.e. this functionality is emulated by Python Redmine, e.g. WikiPage, Groups,
Roles etc)
5.8. License
83
5.9.3 1.0.2 (2014-11-13)

Fixed: Issue #55 (TypeError was raised during processing validation errors from Redmine when one of the
errors was returned as a list)
Fixed: Issue #59 (Raise ForbiddenError when a 403 is encountered) (thanks to Rick Harris)
Fixed: Issue #64 (Redmine and Resource classes werent picklable) (thanks to Rick Harris)
Fixed: A ResourceSet object with a limit=100, actually returned 125 Resource objects
5.9.4 1.0.1 (2014-09-23)

Fixed: Issue #50 (IssueJournals notes attribute was converted to Note resource by mistake, bug was introduced in v1.0.0)
5.9.5 1.0.0 (2014-09-22)

Added: Support for the CRM plugin resources:
Contact
ContactTag
Note
Deal
DealStatus
DealCategory
CrmQuery
Added: Introduced new relations for the following resource objects:
Project - time_entries, deals, contacts and deal_categories relations
User - issues, time_entries, deals and contacts relations
Tracker - issues relation
IssueStatus - issues relation
Added: Introduced a values() method in a ResourceSet which returns ValuesResourceSet a ResourceSet
subclass that returns dictionaries when used as an iterable, rather than resource-instance objects (see docs for
details)
Added: Introduced update() and delete() methods in a ResourceSet object which allow to bulk update
or bulk delete all resources in a ResourceSet object (see docs for details)
Fixed: It was impossible to use ResourceSets get() and filter() methods with WikiPage resource
Fixed: Several small fixes and enhancements here and there
5.9.6 0.9.0 (2014-09-11)

Added: Introduced support for file downloads (see docs for details)
Added: Introduced new _Resource.requirements class attribute where all Redmine plugins required by
resource should be listed (preparations to support non-native resources)
84
Added: New exceptions:

ResourceRequirementsError
Fixed: It was impossible to set a custom field of date/datetime type using date/datetime Python objects
Fixed: Issue #46 (A UnicodeEncodeError was raised in Python 2.x while trying to access a url property of a
WikiPage resource if it contained non-ascii characters)
5.9.7 0.8.4 (2014-08-08)

Added: Support for anonymous Attachment resource (i.e. attachment with id attr only)
Fixed: Issue #42 (It was impossible to create a Project resource via new() method)
5.9.8 0.8.3 (2014-08-01)

Fixed: Issue #39 (It was impossible to save custom_fields in User resource via new() method)
5.9.9 0.8.2 (2014-05-27)

Added: ResourceSets get() method now supports a default keyword argument which is returned when
a requested Resource cant be found in a ResourceSet and defaults to None, previously this was hardcoded to
None
Added: It is now possible to use getattr() with default value without raising a ResourceAttrError
when calling non-existent resource attribute, see Issue #30 for details (thanks to hsum)
Fixed: Issue #31 (Unlimited recursion was possible in some situations when on demand includes were used)
5.9.10 0.8.1 (2014-04-02)

RequestEntityTooLargeError
UnknownError
Fixed: Issue #27 (Project and Issue resources parent attribute was returned as a dict instead of being converted
to Resource object)
5.9.11 0.8.0 (2014-03-27)

Added: Introduced the detection of conflicting packages, i.e. if a conflicting package is found (PyRedmineWS
at this time is the only one), the installation procedure will be aborted and a warning message will be shown
with the detailed description of the problem
Added: Introduced new _Resource._members class attribute where all instance attributes which are not
started with underscore should be listed. This will resolve recursion issues in custom resources because of how
__setattr__() works in Python
Changed: _Resource.attributes renamed to _Resource._attributes
Fixed: Python Redmine was unable to upload any binary files
5.9. Changelog
85
Fixed: Issue #20 (Lowered Requests version requirements. Python Redmine now requires Requests starting
from 0.12.1 instead of 2.1.0 in previous versions)
Fixed: Issue #23 (File uploads via update() method didnt work)
5.9.12 0.7.2 (2014-03-17)

Fixed: Issue #19 (Resources obtained via filter() and all() methods have incomplete url attribute)
Fixed: Redmine server url with forward slash could cause errors in rare cases
Fixed: Python Redmine was incorrectly raising ResourceAttrError when trying to call repr() on a
News resource
5.9.13 0.7.1 (2014-03-14)

Fixed: Issue #16 (When a resource was created via a new() method, the next resource created after that
inherited all the attribute values of the previous resource)
5.9.14 0.7.0 (2014-03-12)

Added: WikiPage resource now automatically requests all of its available attributes from Redmine in case if
some of them are not available in an existent resource object
Added: Support for setting date/datetime resource attributes using date/datetime Python objects
Added: Support for using date/datetime Python objects in all ResourceManager methods, i.e.
create(), update(), delete(), get(), all(), filter()
new(),
Fixed: Issue #14 (Python Redmine was incorrectly raising ResourceAttrError when trying to call
repr(), str() and int() on resources, created via new() method)
5.9.15 0.6.2 (2014-03-09)

Fixed: Project resource status attribute was converted to IssueStatus resource by mistake
5.9.16 0.6.1 (2014-02-27)

Fixed: Issue #10 (Python Redmine was incorrectly raising ResourceAttrError while creating some resources via new() method)
5.9.17 0.6.0 (2014-02-19)

Added: Redmine.auth() shortcut for the case if we just want to check if user provided valid auth credentials,
can be used for user authentication on external resource based on Redmine user database (see docs for details)
Fixed: JSONDecodeError was raised in some Redmine versions during some create/update operations
(thanks to 0x55aa)
Fixed: User resource status attribute was converted to IssueStatus resource by mistake
86
5.9.18 0.5.0 (2014-02-09)

Added: An ability to create custom resources which allow to easily redefine the behaviour of existing resources
(see docs for details)
Added: An ability to add/remove watcher to/from issue (see docs for details)
Added: An ability to add/remove users to/from group (see docs for details)
5.9.19 0.4.0 (2014-02-08)

ConflictError
ReadonlyAttrError
ResultSetTotalCountError
CustomFieldValueError
Added: Update functionality via update() and save() methods for resources (see docs for details):
User
Group
IssueCategory
Version
TimeEntry
ProjectMembership
WikiPage
Project
Issue
Added: Limit/offset support via all() and filter() methods for resources that doesnt support that feature
via Redmine:
IssueRelation
Version
WikiPage
IssueStatus
Tracker
Enumeration
IssueCategory
Role
Group
CustomField
Added: On demand includes, e.g. in addition to redmine.group.get(1, include=users) users
for a group can also be retrieved on demand via group.users if include wasnt set (see docs for details)
5.9. Changelog
87
Added: total_count attribute to ResourceSet object which holds the total number of resources for the
current resource type available in Redmine (thanks to Andrei Avram)
Added: An ability to return None instead of raising a ResourceAttrError for all or selected resource
objects via raise_attr_exception kwarg on Redmine object (see docs for details or Issue #6)
Added: pre_create(), post_create(), pre_update(), post_update() resource object methods
which can be used to execute tasks that should be done before/after creating/updating the resource through
save() method
Added: Allow to create resources in alternative way via new() method (see docs for details)
Added: Allow daterange TimeEntry resource filtering via from_date and to_date keyword arguments
(thanks to Antoni Aloy)
Added: An ability to retrieve Issue version via version attribute in addition to fixed_version to be more
obvious
Changed: Documentation for resources rewritten from scratch to be more understandable
Fixed: Saving custom fields to Redmine didnt work in some situations
Fixed: Issues fixed_version attribute was retrieved as dict instead of Version resource object
Fixed: Resource relations were requested from Redmine every time instead of caching the result after first
request
Fixed: Issue #2 (limit/offset as keyword arguments were broken)
Fixed: Issue #5 (Version resource status attribute was converted to IssueStatus resource by mistake) (thanks
to Andrei Avram)
Fixed: A lot of small fixes, enhancements and refactoring here and there
5.9.20 0.3.1 (2014-01-23)

Added: An ability to pass Requests parameters as a dictionary via requests keyword argument on Redmine
initialization, i.e. Redmine(http://redmine.url, requests={}).
Fixed: Issue #1 (unable to connect to Redmine server with invalid ssl certificate).
5.9.21 0.3.0 (2014-01-18)

Added: Delete functionality via delete() method for resources (see docs for details):
User
Group
IssueCategory
Version
TimeEntry
IssueRelation
ProjectMembership
WikiPage
Project
Issue
88
Changed: ResourceManager get() method now raises a ValidationError exception if required keyword
arguments arent passed
5.9.22 0.2.0 (2014-01-16)

ServerError
NoFileError
ValidationError
VersionMismatchError
ResourceNoFieldsProvidedError
ResourceNotFoundError
Added: Create functionality via create() method for resources (see docs for details):
User
Group
IssueCategory
Version
TimeEntry
IssueRelation
ProjectMembership
WikiPage
Project
Issue
Added: File upload support, see upload() method in Redmine class
Added: Integer representation to all resources, i.e. __int__()
Added: Informal string representation to all resources, i.e. __str__()
Changed: Renamed version attribute to redmine_version in all resources to avoid name intersections
Changed: ResourceManager get() method now raises a ResourceNotFoundError exception if resource
wasnt found instead of returning None in previous versions
Changed: reimplemented fix for __repr__() from 0.1.1
Fixed: Conversion of issue priorities to enumeration resource object didnt work
5.9.23 0.1.1 (2014-01-10)

Added: Python 2.6 support
Changed: WikiPage resource refresh() method now automatically determines its project_id
Fixed: Resource representation, i.e. __repr__(), was broken in Python 2.7
Fixed: dir() call on a resource object didnt work in Python 3.2
5.9. Changelog
89
5.9.24 0.1.0 (2014-01-09)

Initial release
90
Python Module Index
r
redmine.exceptions, 81
91
92
Python Module Index
Index
Symbols
_Resource (class in redmine.resources), 79
__getattr__() (redmine.resources._Resource method), 79
__init__() (redmine.resources._Resource method), 79
__setattr__() (redmine.resources._Resource method), 79
A
AuthError, 82
B
BaseRedmineError, 81
C
ConflictError, 82
CustomFieldValueError, 82
F
FileUrlError, 83
ForbiddenError, 83
I
ImpersonateError, 82
J
JSONDecodeError, 83
ResourceAttrError, 82
ResourceBadMethodError, 82
ResourceError, 81
ResourceFilterError, 82
ResourceNoFieldsProvidedError, 82
ResourceNoFiltersProvidedError, 82
ResourceNotFoundError, 82
ResourceRequirementsError, 83
ResourceSetFilterParamError, 82
ResourceSetIndexError, 82
ResourceVersionMismatchError, 82
ResultSetTotalCountError, 82
S
save() (redmine.resources._Resource method), 79
ServerError, 82
T
translate_params() (redmine.resources._Resource class
method), 79
U
UnknownError, 82
V
ValidationError, 82
VersionMismatchError, 82
NoFileError, 82
P
post_create() (redmine.resources._Resource method), 79
post_update() (redmine.resources._Resource method), 79
pre_create() (redmine.resources._Resource method), 79
pre_update() (redmine.resources._Resource method), 79
R
ReadonlyAttrError, 82
redmine.exceptions (module), 81
refresh() (redmine.resources._Resource method), 79
RequestEntityTooLargeError, 82
93

Python Redmine

Uploaded by

Copyright:

Available Formats

Python Redmine

Uploaded by

Document Information

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Python Redmine

Uploaded by

Copyright:

Available Formats

What are the main features of Python Redmine?

What are the main features of Python Redmine?

What support is available for the project?

What support is available for the project?

Python Redmine Documentation

February 20, 2015

Contacts and Support

Donations and Sponsorship

Copyright and License

Python Module Index

Python Redmine Documentation, Release

Python Redmine Documentation, Release

Supports 100% of Redmine API features

Python Redmine Documentation, Release

Contacts and Support

Python Redmine Documentation, Release

Chapter 2. Contacts and Support

Donations and Sponsorship

Python Redmine Documentation, Release

Chapter 3. Donations and Sponsorship

Copyright and License

Python Redmine Documentation, Release

Chapter 4. Copyright and License

Python Redmine Documentation, Release

$ pip install git+https://github.com/maxtepkeev/python-redmine.git@master

Chapter 5. Table of contents

Python Redmine Documentation, Release

redmine = Redmine(http://demo.redmine.org, date_format=%d.%m.%Y, datetime_format=%d.%m.%YT%H:%M:

Python Redmine Documentation, Release

>>> project = redmine.project.create(name=Vacation, identifier=vacation, description=foo, homep

Chapter 5. Table of contents

Python Redmine Documentation, Release

Note: Resource object provides 2 ways to introspect itself:

Python Redmine Documentation, Release

redmine.project.all()[:135] # Returns only the first 135 projects

Please note, that keyword arguments have a higher priority, e.g.:

# Returns 10 projects and not 20

# Returns None if a Resource is not found

filter. Returns a ResourceSet with requested resource ids:

Chapter 5. Table of contents

Python Redmine Documentation, Release

ResourceSet object also provides some attributes:

offset. What offset value was used to retrieve this ResourceSet:

list(). Force evaluation of a ResourceSet by calling list() on it.

# Returns the first Resource in the ResourceSet

Python Redmine Documentation, Release

>>> redmine.project.update(1, name=Vacation, description=foo, homepage=http://foo.bar, is_publi

Warning: Deleted resources cant be restored. Use this method carefully.

Chapter 5. Table of contents

Python Redmine Documentation, Release

>>> issue = redmine.issue.create(project_id=vacation, subject=Vacation, tracker_id=8, description

Python Redmine Documentation, Release

Returns Issue resource object

Hint: New in version 0.4.0.

Chapter 5. Table of contents

Python Redmine Documentation, Release

Python Redmine Documentation, Release

closed - closed issues

>>> issues = redmine.issue.filter(project_id=vacation, subproject_id=!*, created_on=><2012-03-01

Chapter 5. Table of contents