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. Engine can be set while configuring a redmine object, after it’s set, there is nothing else to be done to use it, i.e. it will be used by Python-Redmine automatically while making requests to Redmine.

Engines

Sync

Default engine in Standard Edition. Requests are made in a sequential fashion, i.e. one 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 as follows:

  • key. API key used for authentication.

  • username. Username used for authentication.

  • password. Password used for authentication.

  • requests. Connection options.

  • impersonate. Username to impersonate.

  • ignore_response. If True no response processing will be done at all.

  • return_response. Whether to return response or None.

  • return_raw_response. Whether to return raw or json encoded response.

  • workers. How many workers to use. Available only in Pro Edition.

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)

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.

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.

process_response(response)

Processes response received from Redmine.

Parameters:

response (obj) – (required). Response object with response details.