Added support for retreiving 'mentions' in search results that show w…

…here hits came from in the document's text. Also added a test that passes. Fixes #42.

documentcloud/__init__.py

@@ -144,6 +144,7 @@ def _get_search_page(self, query, page, per_page):
             'q': query,
             'page': page,
             'per_page': per_page,
+            'mentions': 3,
         }
         data = self.fetch(u'search.json', params)
         return data.get("documents")
@@ -370,6 +371,7 @@ class Document(BaseAPIObject):
     def __init__(self, d):
         self.__dict__ = d
         self.resources = Resource(d.get("resources"))
+        self.mentions = [Mention(i) for i in d.get("mentions", [])] or None
         self.created_at = dateparser(d.get("created_at"))
         self.updated_at = dateparser(d.get("updated_at"))
 
@@ -740,6 +742,16 @@ def __init__(self, top, right, bottom, left):
         self.left = left
 
 
+class Mention(BaseAPIObject):
+    """
+    A mention of a search found in the document.
+    """
+    def __unicode__(self):
+        return unicode("%s: %s" % (self.page, self.text[:50]))
+
+
+
+
 class Project(BaseAPIObject):
     """
     A project returned by the API.

test.py

@@ -17,7 +17,7 @@
 from documentcloud import DocumentCloud
 from documentcloud import CredentialsMissingError, DuplicateObjectError
 from documentcloud import CredentialsFailedError, DoesNotExistError
-from documentcloud import Annotation, Document, Project, Section, Entity
+from documentcloud import Annotation, Document, Project, Section, Entity, Mention
 from private_settings import DOCUMENTCLOUD_USERNAME, DOCUMENTCLOUD_PASSWORD
 
 #
@@ -157,6 +157,13 @@ def test_get_entities(self):
         obj = self.public_client.documents.get(self.test_id)
         self.assertEqual(type(obj.entities[0]), Entity)
 
+    def test_get_mentions(self):
+        """
+        Test whether mentions exist.
+        """
+        obj = self.public_client.documents.search(self.test_search)[0]
+        self.assertEqual(type(obj.mentions[0]), Mention)
+
     def test_get_put(self):
         """
         Test whether we can put random noise to all the editable fields.