Adds support for async/await API calls (no deps)

**BREAKING**:
Drops support for python 2.7 and < 3.5 (it relies on asyncio (so 2.7 is out), and python versions below 3.5 have different behaviours regarding the thread pool, see: https://docs.python.org/3/library/asyncio-eventloop.html#asyncio.loop.run_in_executor).

I am suggesting this change for your consideration.
Backwards compatibility has been preserved by running the synchronous `kanboard.client.Kanboard.execute` method into an asyncio executor (for now, only the default executor can be used, but the event loop can be customised via Kanboard() ctor)

Basic usage is to use the coroutines mapped by method calls with the _async suffix.
Example: for a given kb object (of type Kanboard)
Synchronous: kb.create_project(name="My project")
Asynchronous: kb.create_project_async(name="My project")

Fixes #14

Signed-off-by: Antoine Mazeas <antoine@karthanis.net>

Author: karthanistyr

.gitignore

@@ -4,4 +4,5 @@
 *.eggs
 dist
 build
-MANIFEST
+MANIFEST
+__pycache__

.travis.yml

@@ -4,8 +4,6 @@ notifications:
 language: python
 
 python:
-  - '2.7'
-  - '3.4'
   - '3.5'
   - '3.6'
 

README.rst

@@ -18,7 +18,7 @@ Installation
     pip install kanboard
 
 
-This library is compatible with Python 2.7, 3.4, 3.5, 3.6, and 3.7.
+This library is compatible with Python 3.5, 3.6, and 3.7.
 
 Examples
 ========
@@ -27,6 +27,8 @@ Methods and arguments are the same as the JSON-RPC procedures described in the `
 
 Python methods are dynamically mapped to the API procedures. You must use named arguments.
 
+By default, the calls are made synchronously, meaning that they will block the program until completed.
+
 Create a new team project
 -------------------------
 
@@ -59,4 +61,33 @@ Create a new task
     project_id = kb.create_project(name='My project')
     task_id = kb.create_task(project_id=project_id, title='My task title')
 
+Asynchronous I/O
+================
+
+The client also exposes async/await style method calls. Similarly to the synchronous calls (see above), the method names are mapped to the API methods.
+To invoke an asynchronous call, the method name must be appended with `_async`: for example, a synchronous call to `create_project` can be made asynchronous by calling `create_project_async` instead.
+
+.. code-block:: python
+
+    import asyncio
+    from kanboard import Kanboard
+
+    kb = Kanboard('http://localhost/jsonrpc.php', 'jsonrpc', 'your_api_token')
+
+    loop = asyncio.get_event_loop()
+    project_id = loop.run_until_complete(kb.create_project_async(name='My project'))
+
+
+.. code-block:: python
+
+    import asyncio
+    from kanboard import Kanboard
+
+    async def call_within_function()
+      kb = Kanboard('http://localhost/jsonrpc.php', 'jsonrpc', 'your_api_token')
+      return await kb.create_project_async(name='My project')
+
+    loop = asyncio.get_event_loop()
+    project_id = loop.run_until_complete(call_within_function())
+
 See the `official API documentation <https://docs.kanboard.org/en/latest/api/index.html>`_ for the complete list of methods and arguments.

kanboard/client.py

@@ -22,16 +22,15 @@
 
 import json
 import base64
+import functools
+import asyncio
 
 from kanboard import exceptions
-
-try:
-    from urllib import request as http
-except ImportError:
-    import urllib2 as http
+from urllib import request as http
 
 
 DEFAULT_AUTH_HEADER = 'Authorization'
+ASYNC_FUNCNAME_MARKER = "_async"
 
 
 class Kanboard(object):
@@ -50,7 +49,13 @@ class Kanboard(object):
 
     """
 
-    def __init__(self, url, username, password, auth_header=DEFAULT_AUTH_HEADER, cafile=None):
+    def __init__(self,
+                 url,
+                 username,
+                 password,
+                 auth_header=DEFAULT_AUTH_HEADER,
+                 cafile=None,
+                 loop=asyncio.get_event_loop()):
         """
         Constructor
 
@@ -59,18 +64,35 @@ def __init__(self, url, username, password, auth_header=DEFAULT_AUTH_HEADER, caf
             username: API username or real username
             password: API token or user password
             auth_header: API HTTP header
-
+            cafile: path to a custom CA certificate
+            loop: an asyncio event loop. Default: asyncio.get_event_loop()
         """
         self._url = url
         self._username = username
         self._password = password
         self._auth_header = auth_header
         self._cafile = cafile
+        self._event_loop = loop
 
     def __getattr__(self, name):
-        def function(*args, **kwargs):
-            return self.execute(method=self._to_camel_case(name), **kwargs)
-        return function
+        if(self.is_async_method_name(name)):
+            async def function(*args, **kwargs):
+                return await self._event_loop.run_in_executor(
+                    None,
+                    functools.partial(self.execute, method=self._to_camel_case(self.get_funcname_from_async_name(name)), **kwargs))
+            return function
+        else:
+            def function(*args, **kwargs):
+                return self.execute(method=self._to_camel_case(name), **kwargs)
+            return function
+
+    @staticmethod
+    def is_async_method_name(funcname):
+        return funcname.endswith(ASYNC_FUNCNAME_MARKER)
+
+    @staticmethod
+    def get_funcname_from_async_name(funcname):
+        return funcname[:len(funcname) - len(ASYNC_FUNCNAME_MARKER)]
 
     @staticmethod
     def _to_camel_case(snake_str):

setup.py

@@ -32,7 +32,7 @@ def readme():
 
 setup(
     name='kanboard',
-    version='1.0.7',
+    version='1.1.0',
     description='Client library for Kanboard API',
     long_description=readme(),
     keywords='kanboard api client',
@@ -47,8 +47,6 @@ def readme():
         'Natural Language :: English',
         'License :: OSI Approved :: MIT License',
         'Programming Language :: Python',
-        'Programming Language :: Python :: 2.7',
-        'Programming Language :: Python :: 3.4',
         'Programming Language :: Python :: 3.5',
         'Programming Language :: Python :: 3.6',
         'Programming Language :: Python :: 3.7',

test-requirements.txt

@@ -1,2 +1 @@
 flake8
-mock

tests/test_kanboard.py

@@ -20,9 +20,10 @@
 # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 # THE SOFTWARE.
 
-import mock
-import sys
 import unittest
+from unittest import mock
+import types
+import warnings
 
 from kanboard import client
 from kanboard import exceptions
@@ -35,10 +36,17 @@ def setUp(self):
         self.client = client.Kanboard(self.url, 'username', 'password')
         self.request, self.urlopen = self._create_mocks()
 
+    def ignore_warnings(test_func):
+        def do_test(self, *args, **kwargs):
+            with warnings.catch_warnings():
+                warnings.simplefilter("ignore")
+                test_func(self, *args, **kwargs)
+        return do_test
+
     def test_api_call(self):
         body = b'{"jsonrpc": "2.0", "result": true, "id": 123}'
         self.urlopen.return_value.read.return_value = body
-        self.assertEquals(True, self.client.remote_procedure())
+        self.assertEqual(True, self.client.remote_procedure())
         self.request.assert_called_once_with(self.url,
                                              data=mock.ANY,
                                              headers=mock.ANY)
@@ -47,8 +55,10 @@ def test_custom_auth_header(self):
         self.client._auth_header = 'X-Auth-Header'
         body = b'{"jsonrpc": "2.0", "result": true, "id": 123}'
         self.urlopen.return_value.read.return_value = body
-        self.assertEquals(True, self.client.remote_procedure())
-        self.request.assert_called_once()
+        self.assertEqual(True, self.client.remote_procedure())
+        self.request.assert_called_once_with(self.url,
+                                             data=mock.ANY,
+                                             headers=mock.ANY)
         _, kwargs = self.request.call_args
         assert kwargs['headers']['X-Auth-Header'] == 'dXNlcm5hbWU6cGFzc3dvcmQ='
 
@@ -64,13 +74,31 @@ def test_application_error(self):
         with self.assertRaises(exceptions.KanboardClientException, msg='Internal error'):
             self.client.remote_procedure()
 
+    def test_async_method_call_recognised(self):
+        method_name = "some_method_async"
+        result = self.client.is_async_method_name(method_name)
+        self.assertTrue(result)
+
+    def test_standard_method_call_recognised(self):
+        method_name = "some_method"
+        result = self.client.is_async_method_name(method_name)
+        self.assertFalse(result)
+
+    def test_method_name_extracted_from_async_name(self):
+        expected_method_name = "some_method"
+        async_method_name = expected_method_name + "_async"
+        result = self.client.get_funcname_from_async_name(async_method_name)
+        self.assertEqual(expected_method_name, result)
+
+    # suppress a RuntimeWarning because coro is not awaited
+    # this is done on purpose
+    @ignore_warnings
+    def test_async_call_generates_coro(self):
+        method = self.client.my_method_async()
+        self.assertIsInstance(method, types.CoroutineType)
+
     @staticmethod
     def _create_mocks():
-        if sys.version_info[0] < 3:
-            urlopen_patcher = mock.patch('urllib2.urlopen')
-            request_patcher = mock.patch('urllib2.Request')
-        else:
-            request_patcher = mock.patch('urllib.request.Request')
-            urlopen_patcher = mock.patch('urllib.request.urlopen')
-
+        request_patcher = mock.patch('urllib.request.Request')
+        urlopen_patcher = mock.patch('urllib.request.urlopen')
         return request_patcher.start(), urlopen_patcher.start()