Request Engines¶
Added 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.
- 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.