python-redmine 1.0.3

Library for communicating with a Redmine project management application

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>

Features

• Supports 100% of Redmine API features

• Supports Python 2.6 - 3.4

• Extensively documented

• Provides ORM-style Pythonic API

Dependencies

Python Redmine relies heavily on great Requests library by Kenneth Reitz for all the http(s) calls.

Installation

To install Python Redmine, simply:

$ pip install python-redmine

or:

$ easy_install python-redmine

Documentation

Documentation is available at http://python-redmine.readthedocs.org.

Contacts and Support

I will be glad to get your feedback, pull requests, issues, whatever. Feel free to contact me for any questions.

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.

Copyright and License

Python Redmine is licensed under Apache 2.0 license. Check the LICENSE for details.

Changelog

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)

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

1.0.1 (2014-09-23)

• Fixed: Issue #50 (IssueJournal’s notes attribute was converted to Note resource by mistake, bug was introduced in v1.0.0)

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

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)

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)

0.8.3 (2014-08-01)

• Fixed: Issue #39 (It was impossible to save custom_fields in User resource via new() method)

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)

0.8.1 (2014-04-02)

• Added: New exceptions:

  • RequestEntityTooLargeError

  • UnknownError

• Fixed: Issue #27 (Project and Issue resources parent attribute was returned as a dict instead of being converted to Resource object)

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

• 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)

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

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)

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)

0.6.2 (2014-03-09)

• Fixed: Project resource status attribute was converted to IssueStatus resource by mistake

0.6.1 (2014-02-27)

• Fixed: Issue #10 (Python Redmine was incorrectly raising ResourceAttrError while creating some resources via new() method)

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

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)

0.4.0 (2014-02-08)

• Added: New exceptions:

  • 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)

• 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

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).

0.3.0 (2014-01-18)

• Added: Delete functionality via delete() method for resources (see docs for details):

  • User

  • Group

  • IssueCategory

  • Version

  • TimeEntry

  • IssueRelation

  • ProjectMembership

  • WikiPage

  • Project

  • Issue

• Changed: ResourceManager get() method now raises a ValidationError exception if required keyword arguments aren’t passed

0.2.0 (2014-01-16)

• Added: New exceptions:

  • ServerError

  • NoFileError

  • ValidationError

  • VersionMismatchError

  • ResourceNoFieldsProvidedError

  • ResourceNotFoundError

• Added: Create functionality via create() method for resources (see docs for details):

  • User

  • Group

  • IssueCategory

  • Version

  • TimeEntry

  • IssueRelation

  • ProjectMembership

  • WikiPage

  • Project

  • Issue

• Added: File upload support, see upload() method in Redmine class

• Added: Integer representation to all resources, i.e. __int__()

• Added: Informal string representation to all resources, i.e. __str__()

• Changed: Renamed version attribute to redmine_version in all resources to avoid name intersections

• Changed: ResourceManager get() method now raises a ResourceNotFoundError exception if resource 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

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

0.1.0 (2014-01-09)

• Initial release