Request Engines

New in version 2.0.0.

Python-Redmine has an extensible and customizable request engine system that allows to define how requests to Redmine are made. Basically a request engine is a Python class that inherits from redminelib.engines.BaseEngine class and redefines a few methods to achieve the needed behaviour.

Engines

Sync

Default engine in Standard Edition. Requests are made in a sequantial fashion, i.e. ony by one. There is nothing to do to use it, but just for the purpose of example, this is how we can explicitly ask Python-Redmine to use it:

from redminelib import engines, Redmine

redmine = Redmine('https://redmine.url', engine=engines.SyncEngine)

Thread

Available only in Pro Edition.

Default engine in Pro Edition. Requests are made in an asynchronous fashion using Python threads. The amount of threads is calculated by Python-Redmine automatically, but can be adjusted manually passing workers argument to the Redmine class:

from redminelib import engines, Redmine

redmine = Redmine('https://redmine.url', engine=engines.ThreadEngine, workers=4)

Process

Available only in Pro Edition.

Requests are made in an asynchronous fashion using Python processes. The amount of processes is calculated by Python-Redmine automatically, but can be adjusted manually passing workers argument to the Redmine class:

from redminelib import engines, Redmine

redmine = Redmine('https://redmine.url', engine=engines.ProcessEngine, workers=4)

Note

Please keep in mind that currently only read operations are possible using async engines, all other types of operations, i.e. create/update/delete are made using sync engine.

Session

Sometimes there is a need to change engine/connection options only for one or few requests. Python-Redmine provides a convenient session() context manager for that. Options that can be redefined are all keyword arguments accepted by Redmine class:

with redmine.session(workers=24):
    issues = redmine.issue.all()
    projects = redmine.project.all()

with redmine.session(username='jsmith', password='secret'):
    issue = redmine.issue.create(project_id=123, subject='foo')

Custom Engine

It is possible to create additional engines if needed. To do that, create a class and inherit it from engines.BaseEngine class. The only methods that must be implemented are create_session() and process_bulk_request(), please see code of engines.BaseEngine for details. Below you will find methods and attributes which can be redefined in your custom engine:

class redminelib.engines.BaseEngine(**options)
static create_session(**params)

Creates a session object that will be used to make requests to Redmine.

Parameters:params (dict) – (optional). Session params.
static construct_request_kwargs(method, headers, params, data)

Constructs kwargs that will be used in all requests to Redmine.

Parameters:
  • method (string) – (required). HTTP verb to use for the request.
  • headers (dict) – (required). HTTP headers to send with the request.
  • params (dict) – (required). Params to send in the query string.
  • data (dict, bytes or file-like object) – (required). Data to send in the body of the request.
request(method, url, headers=None, params=None, data=None, return_raw=False)

Makes a single request to Redmine and returns processed response.

Parameters:
  • method (string) – (required). HTTP verb to use for the request.
  • url (string) – (required). URL of the request.
  • headers (dict) – (optional). HTTP headers to send with the request.
  • params (dict) – (optional). Params to send in the query string.
  • data (dict, bytes or file-like object) – (optional). Data to send in the body of the request.
  • return_raw (bool) – (optional). Whether to return raw or json encoded response.
bulk_request(method, url, container, **params)

Makes needed preparations before launching the active engine’s request process.

Parameters:
  • method (string) – (required). HTTP verb to use for the request.
  • url (string) – (required). URL of the request.
  • container (string) – (required). Key in the response that should be used to access retrieved resources.
  • params (dict) – (optional). Params that should be used for resource retrieval.
process_bulk_request(method, url, container, bulk_params)

Makes several requests in blocking or non-blocking fashion depending on the engine.

Parameters:
  • method (string) – (required). HTTP verb to use for the request.
  • url (string) – (required). URL of the request.
  • container (string) – (required). Key in the response that should be used to access retrieved resources.
  • bulk_params (list) – (required). Params that should be used for resource retrieval.
static process_response(response, return_raw=False)

Processes response received from Redmine.

Parameters:
  • response (obj) – (required). Response object with response details.
  • return_raw (bool) – (optional). Whether to return raw or json encoded response.