Merge pull request #192 from cloudant/188-support-geospatial-indexes

Cloudant Geo property in design_document.py

Author: emlaver

CHANGES.rst

@@ -4,6 +4,7 @@
 - [NEW] Added support for Cloudant Search index management.
 - [NEW] Added support for managing and querying list functions.
 - [NEW] Added ``rewrites`` accessor property for URL rewriting.
+- [NEW] Added ``st_indexes`` accessor property for Cloudant Geospatial indexes.
 - [NEW] Added support for DesignDocument ``_info`` and ``_search_info`` endpoints.
 - [NEW] Added support for a custom ``requests.HTTPAdapter`` to be configured using an optional ``adapter`` arg e.g.
   ``Cloudant(USERNAME, PASSWORD, account=ACCOUNT_NAME, adapter=Replay429Adapter())``.

src/cloudant/design_document.py

@@ -48,6 +48,46 @@ def __init__(self, database, document_id=None):
         for prop in self._nested_object_names:
             self.setdefault(prop, dict())
 
+    @property
+    def st_indexes(self):
+        """
+        Provides an accessor property to the Cloudant Geospatial
+        (a.k.a. Cloudant Geo) indexes dictionary in the locally cached
+        DesignDocument.  Each Cloudant Geo index is a JSON object within the
+        ``st_indexes`` containing an index name and a javascript function.
+
+        Note: To make it easier to work with Cloudant Geo documents, it is best
+        practice to create a separate design document specifically for
+        Cloudant Geo indexes.
+
+        Geospatial index example:
+
+        .. code-block:: python
+
+            # Add the Cloudant Geo index to ``st_indexes`` and save the design document
+            ddoc = DesignDocument(self.db, '_design/ddoc001')
+            ddoc['st_indexes'] = {
+                'geoidx': {
+                    'index': 'function(doc) { '
+                             'if (doc.geometry && doc.geometry.coordinates) { '
+                             'st_index(doc.geometry);}} '
+                }
+            }
+            ddoc.save()
+
+        Once the Cloudant Geo index is saved to the remote database, you can
+        query the index with a GET request.  To issue a request against the
+        ``_geo`` endpoint, see the steps outlined in the `endpoint access
+        documentation <getting_started.html#endpoint-access>`_.
+
+        For more details, see the `Cloudant Geospatial
+        documentation <https://docs.cloudant.com/geo.html>`_.
+
+        :return: Dictionary containing Cloudant Geo names and index objects
+            as key/value
+        """
+        return self.get('st_indexes')
+
     @property
     def lists(self):
         """

tests/unit/design_document_tests.py

@@ -1352,5 +1352,58 @@ def test_get_list_function(self):
             'html += \'</ol></body></html>\'; return html; }); }'
         )
 
+    @unittest.skipUnless(
+        os.environ.get('RUN_CLOUDANT_TESTS') is not None,
+        'Skipping Cloudant specific Cloudant Geo tests'
+    )
+    def test_geospatial_index(self):
+        """
+        Test retrieval and query of Cloudant Geo indexes from the DesignDocument.
+        """
+        ddoc = DesignDocument(self.db, '_design/ddoc001')
+        ddoc['st_indexes'] = {
+                'geoidx': {
+                    'index': 'function(doc) { '
+                             'if (doc.geometry && doc.geometry.coordinates) { '
+                             'st_index(doc.geometry);}} '
+                }
+        }
+        ddoc.save()
+        ddoc_remote = DesignDocument(self.db, '_design/ddoc001')
+        self.assertNotEqual(ddoc_remote, ddoc)
+        ddoc_remote.fetch()
+        self.assertEqual(ddoc_remote, {
+            '_id': '_design/ddoc001',
+            '_rev': ddoc['_rev'],
+            'st_indexes': ddoc['st_indexes'],
+            'indexes': {},
+            'views': {},
+            'lists': {}
+        })
+        # Document with geospatial point
+        geodoc = Document(self.db, 'doc001')
+        geodoc['type'] = 'Feature'
+        geodoc['geometry'] = {
+          "type": "Point",
+          "coordinates": [
+            -71.1,
+            42.3
+          ]
+        }
+        geodoc.save()
+        # Geospatial query for a well known point
+        geo_result = self.client.r_session.get('/'.join([ddoc_remote.document_url,
+                                            '_geo',
+                                            'geoidx?g=point(-71.1%2042.3)'])).json()
+        self.assertIsNotNone(geo_result['bookmark'])
+        geo_result.pop('bookmark')
+        self.assertEqual(geo_result,
+                         {'rows': [
+                             {'id': 'doc001',
+                              'geometry':
+                                  {'type': 'Point',
+                                   'coordinates': [-71.1, 42.3]}}]
+                         })
+
 if __name__ == '__main__':
     unittest.main()