Merge pull request #18 from swiftype/backfill

Backfilled various endpoint support

Author: JasonStoltz

README.md

@@ -94,6 +94,20 @@ The client can be configured to use a managed deploy by adjusting the `base_endp
 [{'id': 'INscMGmhmX4', 'errors': []}, {'id': 'JNDFojsd02', 'errors': []}]
 ```
 
+### Indexing: Updating documents (Partial Updates)
+
+```python
+>>> engine_name = 'favorite-videos'
+>>> documents = [
+    {
+      'id': 'INscMGmhmX4',
+      'title': 'Updated title'
+    }
+]
+
+>>> client.update_documents(engine_name, documents)
+```
+
 ### Get Documents
 
 ```python
@@ -102,6 +116,23 @@ The client can be configured to use a managed deploy by adjusting the `base_endp
 [{'id': 'INscMGmhmX4','url': 'https://www.youtube.com/watch?v=INscMGmhmX4','title': 'The Original Grumpy Cat','body': 'A wonderful video of a magnificent cat.'}]
 ```
 
+### List Documents
+```python
+>>> engine_name = 'favorite-videos'
+>>> client.list_documents(engine_name, current=1, size=20)
+{
+    'meta': {
+        'page': {
+        'current': 1,
+        'total_pages': 1,
+        'total_results': 2,
+        'size': 20
+        }
+    },
+    'results': [{'id': 'INscMGmhmX4','url': 'https://www.youtube.com/watch?v=INscMGmhmX4','title': 'The Original Grumpy Cat','body': 'A wonderful video of a magnificent cat.'}]
+}
+```
+
 ### Destroy Documents
 
 ```python
@@ -137,8 +168,8 @@ The client can be configured to use a managed deploy by adjusting the `base_endp
 ### Create an Engine
 
 ```python
->>> client.create_engine('favorite-videos')
-{'name': 'favorite-videos'}
+>>> client.create_engine('favorite-videos', 'en')
+{'name': 'favorite-videos', 'type': 'default', 'language': 'en'}
 ```
 
 ### Destroy an Engine
@@ -155,6 +186,40 @@ The client can be configured to use a managed deploy by adjusting the `base_endp
 {'meta': {'page': {'current': 1, 'total_pages': 1, 'total_results': 2, 'size': 10}, ...}, 'results': [...]}
 ```
 
+### Multi-Search
+
+```python
+>>> client.multi_search('favorite-videos', [{
+  'query': 'cat',
+  'options': { 'search_fields': { 'title': {} }}
+},{
+  'query': 'dog',
+  'options': { 'search_fields': { 'body': {} }}
+}])
+[{'meta': {...}, 'results': [...]}, {'meta': {...}, 'results': [...]}]
+```
+
+### Query Suggestion
+
+```python
+>>> client.query_suggestion('favorite-videos', 'cat', {
+  'size': 10,
+  'types': {
+    'documents': {
+      'fields': ['title']
+    }
+  }
+})
+{'results': {'documents': [{'suggestion': 'cat'}]}, 'meta': {'request_id': '390be384ad5888353e1b32adcfaaf1c9'}}
+```
+
+### Clickthrough Tracking
+
+```python
+>>> client.click(engine_name, {'query': 'cat', 'document_id': 'INscMGmhmX4'})
+```
+
+
 ### Create a Signed Search Key
 
 Creating a search key that will only search over the body field.

swiftype_app_search/__version__.py

@@ -1,6 +1,6 @@
 __title__ = 'swiftype_app_search'
 __description__ = 'An API client for Swiftype App Search'
 __url__ = 'https://github.com/swiftype/swiftype-app-search-python'
-__version__ = '0.4.0'
+__version__ = '0.5.0'
 __author__ = 'Swiftype'
 __author_email__ = 'eng@swiftype.com'

swiftype_app_search/client.py

@@ -35,6 +35,17 @@ def get_documents(self, engine_name, document_ids):
         data = json.dumps(document_ids)
         return self.swiftype_session.request('get', endpoint, data=data)
 
+    def list_documents(self, engine_name, current=1, size=20):
+        """
+        Lists all documents in engine.
+
+        :param current: Page of documents
+        :param size: Number of documents to return per page
+        :return: List of documemts.
+        """
+        data = { 'page': { 'current': current, 'size': size } }
+        return self.swiftype_session.request('get', "engines/{}/documents/list".format(engine_name), json=data)
+
     def index_document(self, engine_name, document):
         """
         Create or update a document for an engine. Raises
@@ -70,6 +81,20 @@ def index_documents(self, engine_name, documents):
 
         return self.swiftype_session.request('post', endpoint, data=data)
 
+    def update_documents(self, engine_name, documents):
+        """
+        Update a batch of documents for an engine.
+
+        :param engine_name: Name of engine to index documents into.
+        :param documents: Hashes representing documents.
+        :return: Array of document status dictionaries. Errors will be present
+        in a document status with a key of `errors`.
+        """
+        endpoint = "engines/{}/documents".format(engine_name)
+        data = json.dumps(documents)
+
+        return self.swiftype_session.request('patch', endpoint, data=data)
+
     def destroy_documents(self, engine_name, document_ids):
         """
         Destroys documents by id for an engine.
@@ -102,13 +127,16 @@ def get_engine(self, engine_name):
         """
         return self.swiftype_session.request('get', "engines/{}".format(engine_name))
 
-    def create_engine(self, engine_name):
+    def create_engine(self, engine_name, language=None):
         """
         Creates an engine with the specified name.
         :param engine_name: Name of the new engine.
-        :return: A dictionary corresponding to the name of the engine.
+        :param language: Language of the new engine.
+        :return: A dictionary corresponding to the new engine.
         """
         data = { 'name': engine_name }
+        if language is not None:
+            data['language'] = language
         return self.swiftype_session.request('post', 'engines', json=data)
 
     def destroy_engine(self, engine_name):
@@ -134,6 +162,57 @@ def search(self, engine_name, query, options=None):
         options['query'] = query
         return self.swiftype_session.request('get', endpoint, json=options)
 
+    def multi_search(self, engine_name, searches=None):
+        """
+        Run multiple searches for documents on a single request.
+        See https://swiftype.com/documentation/app-search/ for more details
+        on options and return values.
+
+        :param engine_name: Name of engine to search over.
+        :param options: Array of search options. ex. {query: String, options: Dict}
+        """
+
+        def build_options_from_search(search):
+            if 'options' in search:
+                options = search['options']
+            else:
+                options = {}
+            options['query'] = search['query']
+            return options
+
+        endpoint = "engines/{}/multi_search".format(engine_name)
+        options = {
+            'queries': list(map(build_options_from_search, searches))
+        }
+        return self.swiftype_session.request('get', endpoint, json=options)
+
+    def query_suggestion(self, engine_name, query, options=None):
+        """
+        Request Query Suggestions. See https://swiftype.com/documentation/app-search/ for more details
+        on options and return values.
+
+        :param engine_name: Name of engine to search over.
+        :param query: Query string to search for.
+        :param options: Dict of search options.
+        """
+        endpoint = "engines/{}/query_suggestion".format(engine_name)
+        options = options or {}
+        options['query'] = query
+        return self.swiftype_session.request('get', endpoint, json=options)
+
+    def click(self, engine_name, options):
+        """
+        Sends a click event to the Swiftype App Search Api, to track a click-through event.
+        See https://swiftype.com/documentation/app-search/ for more details
+        on options and return values.
+
+        :param engine_name: Name of engine to search over.
+        :param options: Dict of search options.
+        """
+        endpoint = "engines/{}/click".format(engine_name)
+        return self.swiftype_session.request_ignore_response('post', endpoint, json=options)
+
+
     @staticmethod
     def create_signed_search_key(api_key, api_key_name, options):
         """

swiftype_app_search/swiftype_request_session.py

@@ -33,8 +33,11 @@ def raise_if_error(self, response):
         response.raise_for_status()
 
     def request(self, http_method, endpoint, base_url=None, **kwargs):
+        return self.request_ignore_response(http_method, endpoint, base_url, **kwargs).json()
+
+    def request_ignore_response(self, http_method, endpoint, base_url=None, **kwargs):
         base_url = base_url or self.base_url
         url = "{}/{}".format(base_url, endpoint)
         response = self.session.request(http_method, url, **kwargs)
         self.raise_if_error(response)
-        return response.json()
+        return response

tests/test_client.py

@@ -71,6 +71,21 @@ def test_index_documents(self):
             response = self.client.index_documents(self.engine_name, [valid_document, other_document])
             self.assertEqual(response, expected_return)
 
+    def test_update_documents(self):
+        id = 'INscMGmhmX4'
+        valid_document = {'id': id}
+        other_document = { 'body': 'some value' }
+
+        expected_return = [
+            {'id': id, 'errors': []},
+            {'id': 'some autogenerated id', 'errors': []}
+        ]
+
+        with requests_mock.Mocker() as m:
+            m.register_uri('PATCH', self.document_index_url, json=expected_return, status_code=200)
+            response = self.client.update_documents(self.engine_name, [valid_document, other_document])
+            self.assertEqual(response, expected_return)
+
     def test_get_documents(self):
         id = 'INscMGmhmX4'
         expected_return = [
@@ -87,6 +102,29 @@ def test_get_documents(self):
             response = self.client.get_documents(self.engine_name, [id])
             self.assertEqual(response, expected_return)
 
+    def test_list_documents(self):
+        expected_return = {
+            'meta': {
+                'page': {'current': 1, 'total_results': 1, 'total_pages': 1, 'size': 20},
+                'results': [
+                    {'body': 'this is a test', 'id': '1'},
+                    {'body': 'this is also a test', 'id': '2'}
+                ]
+            }
+        }
+
+        with requests_mock.Mocker() as m:
+            url = "{}/engines/{}/documents/list".format(self.client.swiftype_session.base_url, self.engine_name)
+            m.register_uri('GET',
+                url,
+                additional_matcher=lambda x: x.text == '{"page": {"current": 1, "size": 20}}',
+                json=expected_return,
+                status_code=200
+            )
+
+            response = self.client.list_documents(self.engine_name)
+            self.assertEqual(response, expected_return)
+
     def test_destroy_documents(self):
         id = 'INscMGmhmX4'
         expected_return = [
@@ -147,12 +185,12 @@ def test_get_engine(self):
 
     def test_create_engine(self):
         engine_name = 'myawesomeengine'
-        expected_return = {'name': engine_name}
+        expected_return = {'name': engine_name, 'language': 'en'}
 
         with requests_mock.Mocker() as m:
             url = "{}/{}".format(self.client.swiftype_session.base_url, 'engines')
             m.register_uri('POST', url, json=expected_return, status_code=200)
-            response = self.client.create_engine(engine_name)
+            response = self.client.create_engine(engine_name, 'en')
             self.assertEqual(response, expected_return)
 
     def test_destroy_engine(self):
@@ -169,11 +207,47 @@ def test_destroy_engine(self):
 
     def test_search(self):
         query = 'query'
+        expected_return = { 'meta': {}, 'results': []}
 
         with requests_mock.Mocker() as m:
             url = "{}/{}".format(
                 self.client.swiftype_session.base_url,
                 "engines/{}/search".format(self.engine_name)
             )
-            m.register_uri('GET', url, json={}, status_code=200)
-            self.client.search(self.engine_name, query, {})
+            m.register_uri('GET', url, json=expected_return, status_code=200)
+            response = self.client.search(self.engine_name, query, {})
+            self.assertEqual(response, expected_return)
+
+    def test_multi_search(self):
+        expected_return = [{ 'meta': {}, 'results': []}, { 'meta': {}, 'results': []}]
+
+        with requests_mock.Mocker() as m:
+            url = "{}/{}".format(
+                self.client.swiftype_session.base_url,
+                "engines/{}/multi_search".format(self.engine_name)
+            )
+            m.register_uri('GET', url, json=expected_return, status_code=200)
+            response = self.client.multi_search(self.engine_name, {})
+            self.assertEqual(response, expected_return)
+
+    def test_query_suggestion(self):
+        query = 'query'
+        expected_return = { 'meta': {}, 'results': {}}
+
+        with requests_mock.Mocker() as m:
+            url = "{}/{}".format(
+                self.client.swiftype_session.base_url,
+                "engines/{}/query_suggestion".format(self.engine_name)
+            )
+            m.register_uri('GET', url, json=expected_return, status_code=200)
+            response = self.client.query_suggestion(self.engine_name, query, {})
+            self.assertEqual(response, expected_return)
+
+    def test_click(self):
+        with requests_mock.Mocker() as m:
+            url = "{}/{}".format(
+                self.client.swiftype_session.base_url,
+                "engines/{}/click".format(self.engine_name)
+            )
+            m.register_uri('POST', url, json={}, status_code=200)
+            self.client.click(self.engine_name, {'query': 'cat', 'document_id': 'INscMGmhmX4'})