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 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', 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. redminelib.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. WikiPage:

from redminelib.resources import WikiPage

class CustomWikiPage(WikiPage):
    pass

Name

Python-Redmine converts underscore to camelcase when it tries to import the resource, which 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 resource_paths argument on Redmine object instantiation.

Methods and Attributes

All existing resources are derived from a BaseResource 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 redminelib.resources.BaseResource(manager, attributes)

Implementation of Redmine resource.

__getattr__(attr)

Returns the requested attribute and makes a conversion if needed.

__setattr__(attr, value)

Sets the requested attribute.

classmethod decode(attr, value, manager)

Decodes a single attr, value pair from Python representation to the needed Redmine representation.

Parameters:
  • attr (string) – (required). Attribute name.
  • value (any) – (required). Attribute value.
  • manager (managers.ResourceManager) – (required). Manager object.
classmethod encode(attr, value, manager)

Encodes a single attr, value pair retrieved from Redmine to the needed Python representation.

Parameters:
  • attr (string) – (required). Attribute name.
  • value (any) – (required). Attribute value.
  • manager (managers.ResourceManager) – (required). Manager object.
classmethod bulk_decode(attrs, manager)

Decodes resource data from Python representation to the needed Redmine representation.

Parameters:
  • attrs (dict) – (required). Attributes in the form of key, value pairs.
  • manager (managers.ResourceManager) – (required). Manager object.
classmethod bulk_encode(attrs, manager)

Encodes resource data retrieved from Redmine to the needed Python representation.

Parameters:
  • attrs (dict) – (required). Attributes in the form of key, value pairs.
  • manager (managers.ResourceManager) – (required). Manager object.
raw()

Returns resource data as it was received from Redmine.

refresh(itself=True, **params)

Reloads resource data from Redmine.

Parameters:
  • itself (bool) – (optional). Whether to refresh itself or return a new resource.
  • params (dict) – (optional). Parameters used for resource retrieval.
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.

pre_delete()

Tasks that should be done before deleting the Resource.

post_delete()

Tasks that should be done after deleting the Resource.

save()

Creates or updates a Resource.

delete(**params)

Deletes Resource from Redmine.

Parameters:params (dict) – (optional). Parameters used for resource deletion.
export(fmt, savepath=None, filename=None)

Exports Resource to requested format if Resource supports that.

Parameters:
  • fmt (string) – (required). Format to use for export, e.g. atom, csv, txt, pdf, html etc.
  • savepath (string) – (optional). Path where to save the file.
  • filename (string) – (optional). Name that will be used for the file.