Added rewrite rule property accessor with docstring example and documentation

- rewrite test case in DesignDocumentTests

Author: emlaver

CHANGES.rst

@@ -2,6 +2,7 @@
 ==================
 - [NEW] Added support for Cloudant Search execution.
 - [NEW] Added support for Cloudant Search index management.
+- [NEW] Added ``rewrites`` accessor property for URL rewriting.
 
 2.0.3 (2016-06-03)
 ==================

src/cloudant/design_document.py

@@ -47,6 +47,44 @@ def __init__(self, database, document_id=None):
         self.setdefault('views', dict())
         self.setdefault('indexes', dict())
 
+    @property
+    def rewrites(self):
+        """
+        Provides an accessor property to a list of dictionaries with rewrite
+        rules in the locally cached DesignDocument.  Each rule for URL rewriting
+        is a JSON object with four fields: ``from``, ``to``, ``method``,
+        and ``query``.
+
+        Note: Requests that match the rewrite rules must have a URL path that
+        starts with ``/$DATABASE/_design/doc/_rewrite``.
+
+        Rewrite rule example:
+
+        .. code-block:: python
+
+            # Add the rule to ``rewrites`` and save the design document
+            ddoc = DesignDocument(self.db, '_design/ddoc001')
+            ddoc['rewrites'] = [
+                {"from": "/old/topic",
+                 "to": "/new/",
+                 "method": "GET",
+                 "query": {}
+                 }
+            ]
+            ddoc.save()
+
+        Once the rewrite rule is saved to the remote database, the GET
+        request URL ``/$DATABASE/_design/doc/_rewrite/old/topic?k=v`` would be
+        rewritten as ``/$DATABASE/_design/doc/_rewrite/new?k=v``.
+
+        For more details on URL rewriting, see the `rewrite rules
+        documentation <https://docs.cloudant.com/design_documents.html
+        #rewrite-rules>`_.
+
+        :returns: List of dictionaries containing rewrite rules as key/value
+        """
+        return self.get('rewrites')
+
     @property
     def views(self):
         """

tests/unit/design_document_tests.py

@@ -1035,5 +1035,31 @@ def test_get_search_index(self):
                 '{"store": true}); }\n}'}
         )
 
+    def test_rewrite_rule(self):
+        """
+        Test that design document URL is rewritten to the expected test document.
+        """
+        ddoc = DesignDocument(self.db, '_design/ddoc001')
+        ddoc['rewrites'] = [
+            {"from": "",
+             "to": "/../../rewrite_doc",
+             "method": "GET",
+             "query": {}
+             }
+        ]
+        self.assertIsInstance(ddoc.rewrites, list)
+        self.assertIsInstance(ddoc.rewrites[0], dict)
+        ddoc.save()
+        doc = Document(self.db, 'rewrite_doc')
+        doc.save()
+        resp = self.client.r_session.get('/'.join([ddoc.document_url, '_rewrite']))
+        self.assertEquals(
+            resp.json(),
+            {
+                '_id': 'rewrite_doc',
+                '_rev': doc['_rev']
+            }
+        )
+
 if __name__ == '__main__':
     unittest.main()