Merge pull request #10 from Abbe98:0.7.0

0.7.0

README.md

@@ -1,6 +1,6 @@
 # KSamsök-PY
 
-KSamsök-PY is a Python library for the [K-Samsök(SOCH) API](http://www.ksamsok.se/in-english/). The K-Samsök aggregator has over 6.8 million cultural objects indexed from various sources.
+KSamsök-PY is a Python library for the [K-Samsök(SOCH) API](http://www.ksamsok.se/in-english/). The K-Samsök aggregator has over 7.5 million cultural objects indexed from various sources.
 
 ## Documentation
 
@@ -81,7 +81,7 @@ Requires an API key.
 
 The method `cql()`
 
- - query(`string`), the string to search for in K-Samsök.
+ - query(`string`), the query string for K-Samsök.
  - start(`int`), the result to start at, for returning the first result this should be set to 1.
  - hits(`int`), optional by default set to 60. The number of results to return (1-500).
 
@@ -90,6 +90,20 @@ The method `cql()`
 culturalSearch.cql('geoDataExists=n AND thumbnailExists=j AND itemType=foto', 0)
 ```
 
+#### GQL Queries Genertor
+
+Requires an API key.
+
+The genertor `cqlGenerator()` takes only one parameter and allows you to loop through the results:
+
+ - query(`string`), the query string to for K-Samsök.
+
+```python
+# Search for photos with coordinates and images.
+for item in culturalSearch.cql('geoDataExists=n AND thumbnailExists=j AND itemType=foto'):
+    print(item)
+```
+
 #### URI Format
 
 The `formatUri()` method can validate and convert SOCH URI/URL;s. `formatUri()` will return `False` if provided with a invalid URI. `formatUri()` has three parameters:
@@ -233,7 +247,7 @@ When KSamsök-PY does not have a method for a request you want to preform agains
 
 There are two `protected` methods that essential when extending `KSamsok`, `killXmlNamespaces()` and `parseRecord()` those are the same functions as `public` methods uses.
 
-To get started with see the [implementation of `search()`](https://github.com/Abbe98/ksamsok-py/blob/master/ksamsok/ksamsok.py#L179). Note that `KSamsok` parses and uses the "XML Presentation" format and not the RDF format provided by SOCH.
+To get started with see the [implementation of `cql()`](https://github.com/Abbe98/ksamsok-py/blob/master/ksamsok/ksamsok.py#L220). Note that `KSamsok` parses and uses the "XML Presentation" format and not the RDF format provided by SOCH.
 
 ### Advanced Usage: Custom Endpoint
 

ksamsok/ksamsok.py

@@ -217,15 +217,11 @@ def getObject(self, uri):
 
         return self.parseRecord(xml)
 
-    def search(self, text, start, hits, images = False):
+    def cql(self, query, start, hits = 60):
         self.requiresKey()
 
         # create the request URL
-        request_query = self.endpoint + 'ksamsok/api?x-api=' + self.key + '&method=search&hitsPerPage=' + str(hits) + '&startRecord=' + str(start) + '&query=text%3D"' + text + '"&recordSchema=presentation'
-
-        # if images = true add &thumbnailExists=j to url
-        if images:
-            request_query = request_query + '&thumbnailExists=j'
+        request_query = self.endpoint + 'ksamsok/api?x-api=' + self.key + '&method=search&hitsPerPage=' + str(hits) + '&startRecord=' + str(start) + '&query=' + query + '&recordSchema=presentation'
 
         r = requests.get(request_query)
         if not self.validHttpStatus(r.status_code):
@@ -245,54 +241,38 @@ def search(self, text, start, hits, images = False):
 
         return result
 
-    def cql(self, query, start, hits = 60):
+    def cqlGenerator(self, query):
         self.requiresKey()
 
-        # create the request URL
-        request_query = self.endpoint + 'ksamsok/api?x-api=' + self.key + '&method=search&hitsPerPage=' + str(hits) + '&startRecord=' + str(start) + '&query=' + query + '&recordSchema=presentation'
-
-        print(request_query)
-        r = requests.get(request_query)
-        if not self.validHttpStatus(r.status_code):
-            return False
+        start = 0
+        has_more = True
 
-        # remove all XML namespaces, and push the bytes to etree.XML
-        xml = etree.XML(str.encode(self.killXmlNamespaces(r.text)))
+        while has_more:
+            results = self.cql(query, start, 500)['records']
+            for item in results:
+                yield item
 
-        result = {}
-        hits = xml.xpath('/result/totalHits')
-        result['hits'] = hits[0].text if 0 < len(hits) else None
+            if len(results) < 500:
+                has_more = False
 
-        result['records'] = list()
-        records = xml.xpath('/result/records/record/pres_item')
-        for record in records:
-            result['records'].append((self.parseRecord(record)))
+            start += 500
 
-        return result
-
-    def geoSearch(self, west, south, east, north, start, hits = 60):
+    def search(self, text, start, hits, images = False):
         self.requiresKey()
 
-        # create the request URL
-        request_query = self.endpoint + 'ksamsok/api?x-api=' + self.key + '&method=search&hitsPerPage=' + str(hits) + '&startRecord=' + str(start) + '&query=boundingBox=/WGS84%20"' + str(west) + '%20' + str(south) + '%20' + str(east) + '%20' + str(north) + '"&recordSchema=presentation'
-
-        r = requests.get(request_query)
-        if not self.validHttpStatus(r.status_code):
-            return False
+        cql = 'text=' + text
+        # in erlier versions we added &thumbnailExists=j to url
+        if images:
+            cql = cql + ' AND thumbnailExists=j'
 
-        # remove all XML namespaces, and push the bytes to etree.XML
-        xml = etree.XML(str.encode(self.killXmlNamespaces(r.text)))
+        return self.cql(cql, start, hits)
 
-        result = {}
-        hits = xml.xpath('/result/totalHits')
-        result['hits'] = hits[0].text if 0 < len(hits) else None
+    def geoSearch(self, west, south, east, north, start, hits = 60):
+        self.requiresKey()
 
-        result['records'] = list()
-        records = xml.xpath('/result/records/record/pres_item')
-        for record in records:
-            result['records'].append((self.parseRecord(record)))
+        cql = 'boundingBox=/WGS84%20"' + str(west) + ' ' + str(south) + ' ' + str(east) + ' ' + str(north)
 
-        return result
+        return self.cql(cql, start, hits)
 
     def getRelations(self, uri):
         self.requiresKey()

setup.py

@@ -1,5 +1,5 @@
 from setuptools import setup
-version = '0.6.0'
+version = '0.7.0'
 repo = 'ksamsok-py'
 
 setup(