Python Redmine PDF

Python Redmine Documentation
Release
Max Tepkeev
February 20, 2015

Contents
1 Features 3
2 Contacts and Support 5
3 Donations and Sponsorship 7
4 Copyright and License 9
5 Table of contents 11
5.1 Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
5.2 Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
5.3 Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
5.4 Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
5.5 Advanced Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
5.6 Frequently Asked Questions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
5.7 Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
5.8 License . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
5.9 Changelog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
Python Module Index 91
i
ii
Python Redmine Documentation, Release
Python Redmine is a library for communicating with a Redmine project management application. Redmine exposes
some of it’s 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 1
2 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
3
4 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.
5
6 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 doesn’t 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.
7
8 Chapter 3. Donations and Sponsorship

CHAPTER 4
Copyright and License
Python Redmine is licensed under Apache 2.0 license. Check the License for details.
9
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 can’t 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 it’s 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
Redmine’s 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 user’s regular login and password:
redmine = Redmine(’http://demo.redmine.org’, username=’foo’, password=’bar’)
• using user’s 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 Redmine’s date/datetime strings to Python’s 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 Python’s 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 doesn’t work for you and you receive strings instead of objects, you have a different datetime for-
matting 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 doesn’t exist, Python Redmine will raise an exception by default. Some-
times 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 Requests’s 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 project’s 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 Redmine’s REST API. All operations on the
resources are provided by the ResourceManager object which you usually don’t have to use directly. Not all resources
support every operation, if resource doesn’t 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 doesn’t support the
creation of some resources via REST API. You can read more about it in each resource’s 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 doesn’t 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

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 resource’s
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 it’s values Resource has as a list of tuples.
list(redmine.project.get(’vacation’))
Hint: Under some circumstances Redmine doesn’t 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 Resource-
Set 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’}]

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 don’t 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 doesn’t 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 it’s 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 doesn’t support
updates on some resources via REST API. You can read more about it in each resource’s 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 doesn’t support the deletion of some resources
via REST API. You can read more about it in each resource’s documentation.
>>> redmine.project.delete(1)
True
Warning: Deleted resources can’t 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 it’s 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.

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 issue’s 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 doesn’t 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 it’s 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

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 issue’s 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.

• 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 it’s 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 it’s 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 it’s id.
Returns True
>>> issue.watcher.remove(1)
True
5.4.2 Project
Manager
All operations on the project resource are provided via it’s 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 con-
figure redmine object.

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). Project’s parent project id.
• inherit_members (boolean) – (optional). If project inherits parent project’s 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 doesn’t 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 it’s id or identifier.
Parameters
• resource_id (integer or string) – (required). Project id or identifier.
– 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)

• 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
– 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). Project’s parent project id.
• inherit_members (boolean) – (optional). If project inherits parent project’s 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 it’s 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

Manager
All operations on the project membership resource are provided via it’s 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 doesn’t 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 it’s 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

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 it’s 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 it’s 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 doesn’t 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 it’s id.
Parameters
• resource_id (integer) – (required). Id of the user.
– 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

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 Re-
sourceSet 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

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 it’s 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 it’s 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 doesn’t 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 it’s 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

>>> 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 it’s 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 it’s manager. To get access to it you have to call redmine.news

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 it’s 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 doesn’t 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.


>>> 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 it’s 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 it’s 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 it’s 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 con-
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 version’s project.
• name (string) – (required). 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.
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 doesn’t 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 it’s 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 version’s 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.

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 it’s 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 it’s 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 con-
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 page’s 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 doesn’t 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 it’s title.
Parameters
• resource_id (string) – (required). Title of the wiki page.
• version (integer) – (optional). Version of the wiki page.
– attachments
>>> wiki_page = redmine.wiki_page.get(’Photos’, project_id=’vacation’, version=12, include=’attachmen
>>> wiki_page
<redmine.resources.WikiPage "Photos">

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 it’s 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 it’s 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.

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 it’s 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 it’s create/update methods, e.g. issue.
Read methods
get
Returns single attachment resource from the Redmine by it’s 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

5.4.12 Issue Status
Manager
All operations on the issue status resource are provided via it’s 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 it’s 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 con-
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>

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 it’s 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 it’s 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

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 category’s 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 doesn’t 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 it’s 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

>>> 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 it’s 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 it’s 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 it’s 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 it’s 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

>>> group = redmine.group.create(name=’Developers’, user_ids=[13, 15, 25])

>>> group
<redmine.resources.Group #8 "Developers">
new
Creates new empty group resource but doesn’t 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 it’s id.
Parameters
• resource_id (integer) – (required). Id of the group.
– 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


>>> group.name = ’Developers’
>>> group.user_ids = [13, 15, 25]
>>> group.save()
True
Delete methods
delete
Deletes single group resource from the Redmine by it’s 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 it’s id.
Returns True
>>> group.user.add(1)
True
remove
redmine.resources.Group.User.remove(user_id)
Removes a user from a group by it’s 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 it’s 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

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 it’s 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 con-
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 contact’s 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 doesn’t 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 it’s id.
Parameters

• resource_id (integer) – (required). Id of the contact.

– 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 contact’s 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

– 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 it’s 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 contact’s 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 contact’s 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 it’s 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

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 it’s 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 it’s 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 it’s 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.

Parameters
• project_id (integer or string) – (required). Id or identifier of deal’s 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 doesn’t 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 it’s id.
Parameters
• resource_id (integer) – (required). Id of the deal.
– 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 deal’s project.
• assigned_to_id (integer) – (optional). Get deals which are assigned to this user id.

• 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 it’s 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 it’s 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

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 it’s 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 category’s 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

5.4.25 CRM Query
Manager
All operations on the crm query resource are provided via it’s 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 con-
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.

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 won’t inherit from directly unless you
want to add support for a new resource which Python Redmine doesn’t 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’ # username comes from the POST request on form submit
password = ’qwerty’ # 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’ # username comes from the POST request on form submit
password = ’qwerty’ # 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 shouldn’t 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

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 it’s 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 doesn’t work
Your Redmine server is probably using https as the primary protocol and you’re trying to connect to it under http
protocol. Please use the https protocol and it should work.
The problem described above happens because when you’re 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 it’s 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 doesn’t exist exception
exception redmine.exceptions.ResourceNotFoundError
Requested resource doesn’t exist
exception redmine.exceptions.ConflictError
Resource version on the server is newer than client’s
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 doesn’t 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 doesn’t support the requested method, e.g. get()
exception redmine.exceptions.ResourceFilterError
Resource doesn’t 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 doesn’t have the requested attribute
exception redmine.exceptions.ReadonlyAttrError
Resource can’t set attribute that is read only
exception redmine.exceptions.VersionMismatchError(feature)
Feature isn’t supported on specified Redmine version
exception redmine.exceptions.ResourceVersionMismatchError
Resource isn’t supported on specified Redmine version
exception redmine.exceptions.ResultSetTotalCountError
ResultSet hasn’t been yet evaluated and cannot yield a total_count

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 can’t 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 doesn’t have CRM plugin enabled, an attempt to add/remove
Contact resource to/from it will lead to improper error message)
• Fixed: Issue #81 (Contact’s 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 Redmine’s own exception, i.e redmine.exceptions.JSONDecodeError)
• Fixed: Issue #76 (It was impossible to retrieve more than 100 resources for resources which don’t 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 weren’t 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 (IssueJournal’s notes attribute was converted to Note resource by mistake, bug was intro-
duced 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 ResourceSet’s 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)

• 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: ResourceSet’s get() method now supports a default keyword argument which is returned when
a requested Resource can’t 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 didn’t 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 it’s 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. new(),
create(), update(), delete(), get(), all(), filter()
• 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 re-
sources 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

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 doesn’t 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 wasn’t 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 didn’t work in some situations
• Fixed: Issue’s 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
– WikiPage
– Project
– Issue

• Changed: ResourceManager get() method now raises a ValidationError exception if required keyword
arguments aren’t 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
– 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
wasn’t 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 didn’t work
5.9.23 0.1.1 (2014-01-10)
• Added: Python 2.6 support

• Changed: WikiPage resource refresh() method now automatically determines it’s project_id
• Fixed: Resource representation, i.e. __repr__(), was broken in Python 2.7
• Fixed: dir() call on a resource object didn’t work in Python 3.2
5.9. Changelog 89
5.9.24 0.1.0 (2014-01-09)
• Initial release

Python Module Index
r
redmine.exceptions, 81
91
92 Python Module Index

Index
Symbols ResourceAttrError, 82
_Resource (class in redmine.resources), 79 ResourceBadMethodError, 82
__getattr__() (redmine.resources._Resource method), 79 ResourceError, 81
__init__() (redmine.resources._Resource method), 79 ResourceFilterError, 82
__setattr__() (redmine.resources._Resource method), 79 ResourceNoFieldsProvidedError, 82
ResourceNoFiltersProvidedError, 82
A ResourceNotFoundError, 82
AuthError, 82 ResourceRequirementsError, 83
ResourceSetFilterParamError, 82
B ResourceSetIndexError, 82
ResourceVersionMismatchError, 82
BaseRedmineError, 81
ResultSetTotalCountError, 82
C S
ConflictError, 82
save() (redmine.resources._Resource method), 79
CustomFieldValueError, 82
ServerError, 82
F T
FileUrlError, 83
ForbiddenError, 83 translate_params() (redmine.resources._Resource class
method), 79
I
ImpersonateError, 82
U
UnknownError, 82
J
V
JSONDecodeError, 83
ValidationError, 82
N 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 PDF

Diunggah oleh

Informasi Dokumen

Judul Asli

Hak Cipta

Format Tersedia

Bagikan dokumen Ini

Bagikan atau Tanam Dokumen

Opsi Berbagi

Apakah menurut Anda dokumen ini bermanfaat?

Apakah konten ini tidak pantas?

Hak Cipta:

Format Tersedia

Python Redmine PDF

Diunggah oleh

Hak Cipta:

Format Tersedia

Python Redmine Documentation

February 20, 2015

2 Contacts and Support 5

3 Donations and Sponsorship 7

4 Copyright and License 9

Python Module Index 91

>>> redmine = Redmine(’http://demo.redmine.org’, username=’foo’, password=’bar’)

• Supports 100% of Redmine API features

Contacts and Support

6 Chapter 2. Contacts and Support

Donations and Sponsorship

8 Chapter 3. Donations and Sponsorship

Copyright and License

10 Chapter 4. Copyright and License

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

12 Chapter 5. Table of contents

New in version 0.4.0.

New in version 0.3.1.

# somewhere in the code

redmine = Redmine(settings.REDMINE_URL, key=settings.REDMINE_KEY)

New in version 0.2.0.

New in version 0.4.0.

14 Chapter 5. Table of contents

New in version 0.1.0.

Returns requested Resource object either by integer id or by string identifier:

Note: Resource object provides 2 ways to introspect itself:

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

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

• filter. Returns a ResourceSet with requested resource ids:

16 Chapter 5. Table of contents

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.

New in version 0.4.0.

Updates a resource with given fields and saves it to the Redmine.

Saves the current state of a resource to the Redmine.

New in version 0.3.0.

Warning: Deleted resources can’t be restored. Use this method carefully.

Supported by Redmine starting from version 1.0

18 Chapter 5. Table of contents

Returns Issue resource object

Hint: New in version 0.4.0.

20 Chapter 5. Table of contents

– closed - closed issues

22 Chapter 5. Table of contents

• parent_issue_id (integer) – (optional). Parent issue id.

Parameters resource_id (integer) – (required). Issue id.

New in version 0.5.0.

Supported by Redmine starting from version 1.0

24 Chapter 5. Table of contents

Hint: New in version 0.4.0.

26 Chapter 5. Table of contents

Not supported by Redmine

5.4.3 Project Membership

Supported by Redmine starting from version 1.4

28 Chapter 5. Table of contents

>>> membership = redmine.project_membership.get(521)

Not supported by Redmine

30 Chapter 5. Table of contents

Supported by Redmine starting from version 1.1

Hint: New in version 0.4.0.

32 Chapter 5. Table of contents

Hint: New in version 1.0.0.