add options to skip response processing

Author: maxtepkeev

CHANGELOG.rst

@@ -12,6 +12,9 @@ Changelog
   for GUI like behaviour or iterable of elements with "all_gui" string and additional columns to export
 - Added support for special characters in WikiPage titles (`Issue #222 <https://github.com/maxtepkeev/python-redmine/
   issues/222>`__) (thanks to `Radek Czajka <https://github.com/rczajka>`__)
+- Added ``return_response`` and ``ignore_response`` parameters to engine which allow to skip response processing
+  and speed up the create/update/delete operation in case response body isn't needed (see
+  `docs <https://python-redmine.com/advanced/request_engines.html#session>`__ for details)
 
 **Changes**:
 
@@ -26,6 +29,7 @@ Changelog
 
 **Documentation**:
 
+- Introduced detailed parameter list for ``redmine.session``
 - Mentioned support for ``admin`` in User's resource create/update
 
 2.2.1 (2019-02-28)

docs/advanced/request_engines.rst

@@ -66,7 +66,17 @@ 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:
+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*.
 
 .. code-block:: python
 

docs/introduction.rst

@@ -96,6 +96,25 @@ a request to Redmine will be made to actually save the resource and finally a ``
 will be executed to run post create tasks if any. You can use any method you like, though it is
 recommended to use a ``new()`` method as the most advanced one.
 
+.. hint::
+
+   If there's no need to process response, one can use a ``redmine.session`` with either a ``return_response=False``
+   which doesn't return any response in a form of Resource object, but still validates it in case there were any
+   errors and raises an exception if needed or a ``ignore_response=True`` which totally ignores response even
+   if there were any errors. These attributes can save quite some processing time and if a response isn't needed
+   one is highly encouraged to use on of them:
+
+   .. code-block:: python
+
+      with redmine.session(return_response=False):
+          redmine.issue.create(project_id=123, subject='Vacation')
+
+      with redmine.session(return_response=False):
+          issue = redmine.issue.new()
+          issue.project_id = 123
+          issue.subject = 'Vacation'
+          issue.save()
+
 read
 ++++
 

redminelib/engines/base.py

@@ -17,11 +17,18 @@ def __init__(self, **options):
         :param string password: (optional). Password used for authentication.
         :param dict requests: (optional). Connection options.
         :param string impersonate: (optional). Username to impersonate.
+        :param bool ignore_response (optional). If True no response processing will be done at all.
+        :param bool return_response (optional). Whether to return response or None.
         :param bool return_raw_response (optional). Whether to return raw or json encoded responses.
         """
+        self.ignore_response = options.pop('ignore_response', False)
+        self.return_response = options.pop('return_response', True)
         self.return_raw_response = options.pop('return_raw_response', False)
         self.requests = dict(dict(headers={}, params={}, data={}), **options.get('requests', {}))
 
+        if self.ignore_response:
+            self.requests['stream'] = True
+
         if options.get('impersonate') is not None:
             self.requests['headers']['X-Redmine-Switch-User'] = options['impersonate']
 
@@ -132,6 +139,9 @@ def process_response(self, response):
 
         :param obj response: (required). Response object with response details.
         """
+        if self.ignore_response:
+            return None
+
         if response.history:
             r = response.history[0]
             if r.is_redirect and r.request.url.startswith('http://') and response.request.url.startswith('https://'):
@@ -140,7 +150,9 @@ def process_response(self, response):
         status_code = response.status_code
 
         if status_code in (200, 201, 204):
-            if self.return_raw_response:
+            if not self.return_response:
+                return None
+            elif self.return_raw_response:
                 return response
             elif not response.content.strip():
                 return True

redminelib/managers/base.py

@@ -158,6 +158,10 @@ def create(self, **fields):
         self.container = self.resource_class.container_create
         request = self._prepare_create_request(self.resource_class.query_create.formatter.unused_kwargs)
         response = self.redmine.engine.request(self.resource_class.http_method_create, url, data=request)
+
+        if response is None:
+            return None
+
         resource = self._process_create_response(request, response)
         self.url = self.redmine.url + self.resource_class.query_one.format(resource.internal_id, **fields)
         return resource
@@ -215,6 +219,10 @@ def update(self, resource_id, **fields):
         url = self._construct_update_url(query_update)
         request = self._prepare_update_request(self.resource_class.query_update.formatter.unused_kwargs)
         response = self.redmine.engine.request(self.resource_class.http_method_update, url, data=request)
+
+        if response is None:
+            return None
+
         return self._process_update_response(request, response)
 
     def _process_update_response(self, request, response):
@@ -260,6 +268,10 @@ def delete(self, resource_id, **params):
 
         request = self._prepare_delete_request(params)
         response = self.redmine.engine.request(self.resource_class.http_method_delete, url, params=request)
+
+        if response is None:
+            return None
+
         return self._process_delete_response(request, response)
 
     def _process_delete_response(self, request, response):

redminelib/resources/base.py

@@ -384,7 +384,11 @@ def save(self, **attrs):
             self.post_update()
         else:
             self.pre_create()
-            self._decoded_attrs = self.manager.create(**self._changes).raw()
+            resource = self.manager.create(**self._changes)
+
+            if resource is not None:
+                self._decoded_attrs = resource.raw()
+
             self.post_create()
 
         self._changes = {}

tests/test_engines.py

@@ -29,6 +29,17 @@ def test_successful_response_via_put_method(self):
         self.response.content = ''
         self.assertEqual(self.redmine.engine.request('put', self.url), True)
 
+    def test_returns_none_with_ignore_response_true(self):
+        with self.redmine.session(ignore_response=True):
+            self.assertEqual(self.redmine.engine.ignore_response, True)
+            self.assertEqual(self.redmine.engine.requests['stream'], True)
+            self.assertEqual(self.redmine.engine.request('post', self.url), None)
+
+    def test_returns_none_with_return_response_false(self):
+        with self.redmine.session(return_response=False):
+            self.assertEqual(self.redmine.engine.return_response, False)
+            self.assertEqual(self.redmine.engine.request('post', self.url), None)
+
     def test_session_not_implemented_exception(self):
         self.assertRaises(NotImplementedError, lambda: engines.BaseEngine())
 

tests/test_managers.py

@@ -136,6 +136,10 @@ def test_create_empty_resource(self):
         self.assertEqual(project._decoded_attrs, defaults)
         self.assertEqual(repr(project), '<redminelib.resources.Project #0 "">')
 
+    def test_create_resource_returns_none(self):
+        with self.redmine.session(return_response=False):
+            self.assertEqual(self.redmine.user.create(firstname='John', lastname='Smith'), None)
+
     def test_update_resource(self):
         self.response.content = ''
         manager = self.redmine.wiki_page
@@ -165,6 +169,10 @@ def test_update_resource_with_stream_uploads(self):
             self.assertEquals(len(w), 1)
             self.assertIs(w[0].category, exceptions.PerformanceWarning)
 
+    def test_update_resource_returns_none(self):
+        with self.redmine.session(return_response=False):
+            self.assertEqual(self.redmine.issue.update(1, subject='Bar'), None)
+
     def test_delete_resource(self):
         self.response.content = ''
         self.assertEqual(self.redmine.wiki_page.delete(b'\xcf\x86oo'.decode('utf-8'), project_id=1), True)
@@ -174,6 +182,10 @@ def test_delete_resource_returns_204(self):
         self.response.content = ''
         self.assertEqual(self.redmine.wiki_page.delete(b'\xcf\x86oo'.decode('utf-8'), project_id=1), True)
 
+    def test_delete_resource_returns_none(self):
+        with self.redmine.session(return_response=False):
+            self.assertEqual(self.redmine.user.delete(1), None)
+
     def test_resource_get_method_unsupported_exception(self):
         self.assertRaises(exceptions.ResourceBadMethodError, lambda: self.redmine.issue_journal.get(1))