Merge pull request #2 from swiftype/christopherjwang/add_document_index

Add index_document method to client

Author: Christopher Wang

README.rst

@@ -40,6 +40,20 @@ Instantiating a client
     >>> api_key = 'api-mu75psc5egt9ppzuycnc2mc3'
     >>> client = Client(account_host_key, api_key)
 
+Index document
+--------------
+
+.. code-block:: python
+
+    >>> engine_name = 'favorite-videos'
+    >>> documents = {
+          'id': 'INscMGmhmX4',
+          'url': 'https://www.youtube.com/watch?v=INscMGmhmX4',
+          'title': 'The Original Grumpy Cat',
+          'body': 'A wonderful video of a magnificent cat.'
+        }
+    >>> client.index_document(engine_name, document)
+    {'id': 'INscMGmhmX4'}
 
 Index documents
 ---------------

swiftype_app_search/client.py

@@ -32,16 +32,38 @@ def get_documents(self, engine_name, document_ids):
         data = json.dumps(document_ids)
         return self.swiftype_session.request('get', endpoint, data=data)
 
+    def index_document(self, engine_name, document):
+        """
+        Create or update a document for an engine. Raises
+        :class:`~swiftype_app_search.exceptions.InvalidDocument` when the document
+        is missing required fields, contains unsupported fields, or has
+        processing errors
+
+        :param engine_name: Name of engine to index documents into.
+        :param document: Hash representing a single document.
+        :return: dict processed document status
+        """
+        document_status = self.index_documents(engine_name, [document])[0]
+        errors = document_status['errors']
+        if errors:
+            raise InvalidDocument('; '.join(errors), document)
+
+        return {
+            key: document_status[key]
+            for key in document_status
+            if key != 'errors'
+        }
+
     def index_documents(self, engine_name, documents):
         """
         Create or update documents for an engine. Raises
-        :class:`~swiftype_app_search.exceptions.InvalidDocument` if any
-        documents do not have an `id`.
+        :class:`~swiftype_app_search.exceptions.InvalidDocument` when the document
+        is missing required fields or contains unsupported fields
 
         :param engine_name: Name of engine to index documents into.
         :param documents: Hashes representing documents.
-        :return: Array of hashes with keys of id and errors. Errors will be an
-        array of errors if the document could not be indexed successfully.
+        :return: Array of document status dictionaries. Errors will be present
+        in a document status with a key of `errors`.
         """
         self._raise_if_documents_invalid(documents)
 

tests/test_client.py

@@ -7,22 +7,40 @@
 class TestClient(TestCase):
 
     def setUp(self):
-        self.engine_name = 'engine_name'
+        self.engine_name = 'some-engine-name'
         self.client = Client('account_host_key', 'api_key')
 
         self.document_index_url = "{}/{}".format(
             self.client.swiftype_session.base_url,
             "engines/{}/documents".format(self.engine_name)
         )
 
+    def test_index_document_validation(self):
+        invalid_document = {'does': 'not have the id field'}
+        with self.assertRaises(InvalidDocument) as context:
+            self.client.index_documents(self.engine_name, [invalid_document])
+        self.assertEqual(str(context.exception), 'Missing required fields: id')
+        self.assertEqual(context.exception.document, invalid_document)
+
+    def test_index_document_processing_error(self):
+        invalid_document = {'id': 'something', 'bad': {'no': 'nested'}}
+        error = 'some processing error'
+        stubbed_return = [{'id': 'something', 'errors': [error]}]
+        with requests_mock.Mocker() as m:
+            m.register_uri('POST', self.document_index_url, json=stubbed_return, status_code=200)
+
+            with self.assertRaises(InvalidDocument) as context:
+                self.client.index_document(self.engine_name, invalid_document)
+                self.assertEqual(str(context.exception), error)
+
     def test_index_documents_validation(self):
         invalid_documents = [
             {
                 'does': 'not have the id field'
             }
         ]
         with self.assertRaises(InvalidDocument) as context:
-            self.client.index_documents('some engine name', invalid_documents)
+            self.client.index_documents(self.engine_name, invalid_documents)
         self.assertEqual(str(context.exception), 'Missing required fields: id')
         self.assertEqual(context.exception.document, invalid_documents[0])