feat(Responses): add responses api, fixes #6

MichaelSolati · MichaelSolati · commit aeb12487030a · 2019-06-28T17:26:49.000-07:00
diff --git a/.travis.yml b/.travis.yml
@@ -1,12 +1,6 @@
 language: python
 matrix:
   include:
-    - python: 3.3
-      dist: trusty
-      sudo: false
-    - python: 3.4
-      dist: trusty
-      sudo: false
     - python: 3.5
       dist: trusty
       sudo: false
diff --git a/README.md b/README.md
@@ -12,6 +12,7 @@ Python Client wrapper for [Typeform API](https://developer.typeform.com/)
 - [Reference](#reference)
   - [Create Client](#typeformapi_key)
   - [Forms](#forms)
+  - [Responses](#responses)
 
 ## Installation
 
@@ -56,67 +57,95 @@ pip install typeform
 Client returns the following properties:
 
 - `forms`
+- `responses`
 
 Each one of them encapsulates the operations related to it (like listing, updating, deleting the resource).
 
 ### Forms
 
-#### `forms.create(data={})`
+#### `forms.create(data: dict = {})`
 
 Creates a form. Returns `dict` of created form. [See docs](https://developer.typeform.com/create/reference/create-form/).
 
 ```python
 forms = Typeform('<api_key>').forms
-forms.create({ 'title': 'Hello World' })
+result: dict = forms.create({ 'title': 'Hello World' })
 ```
 
-#### `forms.delete('Form ID')`
+#### `forms.delete(uid: str)`
 
-Deletes the form with the given form_id and all of the form's responses. Return a `str` based on success of deletion, `OK` on success, otherwise an error message. [See docs](https://developer.typeform.com/create/reference/delete-form/).
+Deletes the form with the given form_id and all of the form's responses. Returns a `str` based on success of deletion, `OK` on success, otherwise an error message. [See docs](https://developer.typeform.com/create/reference/delete-form/).
 
 ```python
 forms = Typeform('<api_key>').forms
-forms.delete('abc123') # OK
+result: str = forms.delete('abc123')
 ```
 
-#### `forms.get('Form ID')`
+#### `forms.get(uid: str)`
 
 Retrieves a form by the given form_id. Includes any theme and images attached to the form as references. [See docs](https://developer.typeform.com/create/reference/retrieve-form/).
 
 ```python
 forms = Typeform('<api_key>').forms
-forms.get('abc123')
+result: dict = forms.get('abc123')
 ```
 
-#### `forms.list()`
+#### `forms.list(page: int = None, pageSize: int = None, search: str = None, workspaceId: str = None)`
 
 Retrieves a list of JSON descriptions for all forms in your Typeform account (public and private). Forms are listed in reverse-chronological order based on the last date they were modified. [See docs](https://developer.typeform.com/create/reference/retrieve-form/).
 
 ```python
 forms = Typeform('<api_key>').forms
-forms.list()
+result: dict = forms.list()
 ```
 
-#### `forms.update('Form ID', data={}, patch=False)`
+#### `forms.update(uid: str, patch: bool = False, data: dict = {})`
 
-Updates an existing form. Defaults to `put`. `put` will return the modified form as a `dict` object. `patch` will return a `str` based on success of change, `OK` on success, otherwise an error message. [See `put` docs](https://developer.typeform.com/create/reference/update-form/) or [`patch` docs](https://developer.typeform.com/create/reference/update-form-patch/).
+Updates an existing form. Defaults to `put`. `put` will return the modified form as a `dict` object. `patch` will Returns a `str` based on success of change, `OK` on success, otherwise an error message. [See `put` docs](https://developer.typeform.com/create/reference/update-form/) or [`patch` docs](https://developer.typeform.com/create/reference/update-form-patch/).
 
-#### `forms.messages.get('Form ID')`
+```python
+forms = Typeform('<api_key>').forms
+result: dict = forms.update('abc123', { 'title': 'Hello World, Again' })
+result: str = forms.update('abc123', { 'title': 'Hello World, Again' }, patch=True)
+```
+
+#### `forms.messages.get(uid: str)`
 
 Retrieves the customizable messages for a form (specified by form_id) using the form's specified language. You can format messages with bold (*bold*) and italic (_italic_) text. HTML tags are forbidden. [See docs](https://developer.typeform.com/create/reference/retrieve-custom-form-messages/).
 
 ```python
 forms = Typeform('<api_key>').forms
-forms.messages.get('abc123')
+result: dict = forms.messages.get('abc123')
 ```
 
-#### `forms.messages.update('Form ID', data={})`
+#### `forms.messages.update(uid: str, data={})`
 
-Specifies new values for the customizable messages in a form (specified by form_id). You can format messages with bold (*bold*) and italic (_italic_) text. HTML tags are forbidden. Return a `str` based on success of change, `OK` on success, otherwise an error message. [See docs](https://developer.typeform.com/create/reference/update-custom-messages/).
+Specifies new values for the customizable messages in a form (specified by form_id). You can format messages with bold (*bold*) and italic (_italic_) text. HTML tags are forbidden. Returns a `str` based on success of change, `OK` on success, otherwise an error message. [See docs](https://developer.typeform.com/create/reference/update-custom-messages/).
 
 ```python
 forms = Typeform('<api_key>').forms
-forms.messages.update('abc123', {
-    'label.buttonHint.default': 'New Button Hint'
+result: str = forms.messages.update('abc123', {
+  'label.buttonHint.default': 'New Button Hint'
 })
 ```
+
+### Responses
+
+#### `responses.list(uid: str, pageSize: int = None, since: str = None, until: str = None, after: str = None, before: str = None, includedResponseIds: str = None, completed: bool = None, sort: str = None, query: str = None, fields: List[str] = None)`
+
+Returns form responses and date and time of form landing and submission. [See docs](https://developer.typeform.com/responses/reference/retrieve-responses/).
+
+```python
+responses = Typeform('<api_key>').responses
+result: dict = responses.list('abc123')
+```
+
+#### `responses.delete(uid: str, includedTokens: Union[str, List[str]])`
+
+Delete responses to a form. You must specify the `included_tokens` parameter. Returns a `str` based on success of deletion, `OK` on success, otherwise an error message. [See docs](https://developer.typeform.com/responses/reference/delete-responses/).
+
+```python
+responses = Typeform('<api_key>').responses
+result: str = responses.delete('abc123' 'token1')
+result: str = responses.delete('abc123' ['token2', 'token3'])
+```
diff --git a/requirements-dev.txt b/requirements-dev.txt
@@ -2,5 +2,5 @@ coverage
 coveralls
 flake8
 flake8-quotes
-requests-mock
-setuptools
+requests
+requests-mock
diff --git a/requirements.txt b/requirements.txt
diff --git a/setup.py b/setup.py
@@ -29,8 +29,6 @@
         'License :: OSI Approved :: MIT License',
         'Operating System :: OS Independent',
         'Programming Language :: Python :: 3',
-        'Programming Language :: Python :: 3.3',
-        'Programming Language :: Python :: 3.4',
         'Programming Language :: Python :: 3.5',
         'Programming Language :: Python :: 3.6',
         'Programming Language :: Python :: 3.7',
diff --git a/typeform/__init__.py b/typeform/__init__.py
@@ -1,4 +1,5 @@
 from .forms import Forms
+from .responses import Responses
 from .client import Client
 
 __all__ = ['Typeform']
@@ -7,11 +8,16 @@
 class Typeform:
     """Typeform API client"""
 
-    def __init__(self, token, headers: dict = {}):
+    def __init__(self, token: str, headers: dict = {}):
         """Constructor for Typeform API client"""
         client = Client(token, headers=headers)
         self.__forms = Forms(client)
+        self.__responses = Responses(client)
 
     @property
     def forms(self) -> Forms:
         return self.__forms
+
+    @property
+    def responses(self) -> Responses:
+        return self.__responses
diff --git a/typeform/client.py b/typeform/client.py
@@ -9,7 +9,7 @@
 class Client(object):
     """TypeForm API HTTP client"""
 
-    def __init__(self, token, headers: dict = {}):
+    def __init__(self, token: str, headers: dict = {}):
         """Constructor for TypeForm API client"""
         self.__headers = mergeDict({
             'Content-Type': 'application/json',
@@ -21,7 +21,6 @@ def request(self, method: str, url: str, data: any = {}, params: dict = {}, head
         requestUrl = buildUrlWithParams((API_BASE_URL + url), params)
         requestHeaders = mergeDict(self.__headers, headers)
         requestData = ''
-
         if type(data) is dict:
             requestData = json.dumps(data) if len(data.keys()) > 0 else ''
 
diff --git a/typeform/forms.py b/typeform/forms.py
@@ -13,7 +13,7 @@ def __init__(self, client: Client):
     def messages(self):
         return self.__messages
 
-    def create(self, data={}) -> dict:
+    def create(self, data: dict = {}) -> dict:
         """Creates a form"""
         return self.__client.request('post', '/forms', data=data)
 
@@ -40,7 +40,7 @@ def list(self, page: int = None, pageSize: int = None, search: str = None, works
             'workspace_id': workspaceId
         })
 
-    def update(self, uid: str, patch=False, data: any = {}) -> typing.Union[str, dict]:
+    def update(self, uid: str, data: dict = {}, patch: bool = False) -> typing.Union[str, dict]:
         """
         Updates an existing form.
         Defaults to `put`.
diff --git a/typeform/responses.py b/typeform/responses.py
@@ -0,0 +1,40 @@
+import typing
+from .client import Client
+
+
+class Responses:
+    """Typeform Responses API client"""
+
+    def __init__(self, client: Client):
+        """Constructor for Typeform Responses class"""
+        self.__client = client
+
+    def list(
+        self, uid: str, pageSize: int = None, since: str = None, until: str = None,
+        after: str = None, before: str = None, includedResponseIds: str = None,
+        completed: bool = None, sort: str = None, query: str = None, fields: typing.List[str] = None
+    ) -> dict:
+        """
+        Returns form responses and date and time of form landing and submission.
+        """
+        return self.__client.request('get', '/forms/%s/responses' % uid, params={
+            'page_size': pageSize or None,
+            'since': since or None,
+            'until': until,
+            'after': after,
+            'before': before,
+            'included_response_ids': includedResponseIds,
+            'completed': completed,
+            'sort': sort,
+            'query': query,
+            'fields': fields
+        })
+
+    def delete(self, uid: str, includedTokens: typing.Union[str, typing.List[str]]) -> str:
+        """
+        Delete responses to a form. You must specify the `included_tokens`/`includedTokens` parameter.
+        Return a `str` based on success of deletion, `OK` on success, otherwise an error message.
+        """
+        return self.__client.request('delete', '/forms/%s/responses' % uid, params={
+            'included_tokens': includedTokens
+        })
diff --git a/typeform/test/test_client.py b/typeform/test/test_client.py
@@ -22,12 +22,6 @@ def test_client_pass_headers(self):
 
             history = m.request_history
             self.assertEqual(history[0].url, API_BASE_URL+'/forms')
-            self.assertEqual(history[0].headers, {
-                'User-Agent': 'python-requests/2.21.0',
-                'Accept-Encoding': 'gzip, deflate',
-                'Accept': 'application/json',
-                'Connection': 'keep-alive',
-                'Content-Type': 'application/json',
-                'Authorization': 'bearer %s' % TOKEN,
-                'Accepts': 'application/json'
-            })
+            self.assertEqual(history[0].headers.pop('Content-Type'), 'application/json')
+            self.assertEqual(history[0].headers.pop('Accepts'), 'application/json')
+            self.assertEqual(history[0].headers.pop('Authorization'), 'bearer %s' % TOKEN)
diff --git a/typeform/test/test_responses.py b/typeform/test/test_responses.py
@@ -0,0 +1,99 @@
+from unittest import TestCase
+import requests_mock
+import urllib.parse
+
+from .fixtures import TOKEN
+
+from typeform import Typeform
+from typeform.constants import API_BASE_URL
+
+
+class ResponsesTestCase(TestCase):
+    def setUp(self):
+        self.forms = Typeform(TOKEN).forms
+        self.responses = Typeform(TOKEN).responses
+        form = self.forms.create({
+            'title': 'title'
+        })
+        self.formID = form.get('id')
+
+    def tearDown(self):
+        list = self.forms.list()
+        forms = list.get('items', [])
+        for form in forms:
+            self.forms.delete(form.get('id'))
+
+    def test_list_returns_method_and_path(self):
+        """
+        get all responses has the correct method and path
+        """
+        with requests_mock.mock() as m:
+            url = API_BASE_URL+'/forms/'+self.formID+'/responses'
+            m.get(url, json={})
+            self.responses.list(self.formID)
+
+            history = m.request_history
+            self.assertEqual(history[0].url, url)
+            self.assertEqual(history[0].method, 'GET')
+
+    def test_list_correct_params(self):
+        """
+        paramters are sent correctly
+        """
+        with requests_mock.mock() as m:
+            url = API_BASE_URL+'/forms/'+self.formID+'/responses'
+            m.get(url, json={})
+            self.responses.list(
+                self.formID, pageSize='100', since='2000-01-01T00:00:00Z', completed=True, fields=['1', '2']
+            )
+
+            history = m.request_history
+            query = history[0].url.split('?')[1]
+            params = dict(urllib.parse.parse_qs(query))
+
+            self.assertEqual(params.pop('page_size')[0], '100')
+            self.assertEqual(params.pop('since')[0], '2000-01-01T00:00:00Z')
+            self.assertEqual(params.pop('completed')[0], 'true')
+            self.assertEqual(params.pop('fields')[0], '1,2')
+
+    def test_list_fetches_responses(self):
+        """
+        get all responses does not throw an error
+        """
+        result = self.responses.list(self.formID)
+        self.assertEqual(result.pop('total_items'), 0)
+
+    def test_list_fetches_responses_with_params(self):
+        """
+        get all responses does not throw an error with paramters
+        """
+        result = self.responses.list(
+            self.formID, pageSize=100, since='2000-01-01T00:00:00Z', completed=True, fields=['1', '2']
+        )
+        self.assertEqual(result.pop('total_items'), 0)
+
+    def test_delete_one_token_returns_method_and_path(self):
+        """
+        delete response has the correct method and path when deleting one token
+        """
+        with requests_mock.mock() as m:
+            url = API_BASE_URL+'/forms/'+self.formID+'/responses?included_tokens=1'
+            m.delete(url, json={})
+            self.responses.delete(self.formID, includedTokens='1')
+
+            history = m.request_history
+            self.assertEqual(history[0].url, url)
+            self.assertEqual(history[0].method, 'DELETE')
+
+    def test_delete_multiple_token_returns_method_and_path(self):
+        """
+        delete response has the correct method and path when deleting multiple tokens
+        """
+        with requests_mock.mock() as m:
+            url = API_BASE_URL+'/forms/'+self.formID+'/responses?included_tokens=1%2C2%2C3'
+            m.delete(url, json={})
+            self.responses.delete(self.formID, includedTokens=['1', '2', '3'])
+
+            history = m.request_history
+            self.assertEqual(history[0].url, url)
+            self.assertEqual(history[0].method, 'DELETE')
diff --git a/typeform/utils.py b/typeform/utils.py
@@ -10,7 +10,18 @@ def cleanDict(x: dict = {}) -> dict:
     result = {}
     for key in x:
         if x[key] is not None:
-            result[key] = x[key]
+            # Check If List
+            if isinstance(x[key], (list,)):
+                result[key] = ','.join(x[key])
+            # Check If Boolean
+            elif isinstance(x[key], (bool)):
+                if x[key] is True:
+                    result[key] = 'true'
+                else:
+                    result[key] = 'false'
+            # Everything Else (Strings/Numbers)
+            else:
+                result[key] = x[key]
     return result
 
 
