[ckan-changes] commit/ckan: dread: [lib][xs]: Added some doc strings and comments.

[Bitbucket]

1 new changeset in ckan:

http://bitbucket.org/okfn/ckan/changeset/1996b0439e81/
changeset:   1996b0439e81
user:        dread
date:        2011-09-09 11:50:45
summary:     [lib][xs]: Added some doc strings and comments.
affected #:  1 file (512 bytes)

--- a/ckan/lib/search/common.py	Wed Sep 07 17:56:47 2011 +0100
+++ b/ckan/lib/search/common.py	Fri Sep 09 10:50:45 2011 +0100
@@ -73,8 +73,14 @@
 
 class SearchQuery(object):
     """
-    A query is ... when you ask the search engine things. SearchQuery is intended 
-    to be used for only one query, i.e. it sets state. Definitely not thread-safe.
+    Provides a way to perform a search query operation.
+
+    Derive from this class and provide a _run function suitable for
+    performing the query using a particular search backend e.g. SOLR.
+
+    Instantiation should be only used for one query.
+
+    Methods may all raise SearchError for the caller to handle.
     """
     
     def __init__(self, backend):
@@ -84,9 +90,9 @@
     
     @property
     def open_licenses(self):
-        # backend isn't exactly the very best place to put these, but they stay
-        # there persistently. 
-        # TODO: figure out if they change during run-time. 
+        # Cache of which licenses are 'open'.
+        # The list doesn't change during run-time.
+        # TODO: Move this to a better place in the code.
         if not hasattr(self.backend, '_open_licenses'):
             self.backend._open_licenses = []
             for license in model.Package.get_license_register().values():
@@ -103,6 +109,10 @@
                 self.results = [getattr(entity, attr_name) for entity in self.results]
     
     def run(self, query=None, terms=[], fields={}, facet_by=[], options=None, **kwargs):
+        '''Perform the search query.
+
+        May raise SearchError.
+        '''
         if options is None:
             options = QueryOptions(**kwargs) 
         else:
@@ -118,9 +128,17 @@
         return {'results': self.results, 'count': self.count}
         
     def _run(self):
+        '''Override this method to perform an actual query of a search index.
+
+        Errors:
+        * raise SearchError for any error
+        '''
+        # TODO: Split SearchError to differentiate between invalid parameters
+        #       and external search server not responding, say.
         raise SearchError("SearchQuery._run() not implemented!")
         
-    # convenience, allows to query(..)
+    # convenience
+    # allows you to query(..)
     __call__ = run

Repository URL: https://bitbucket.org/okfn/ckan/

--

This is a commit notification from bitbucket.org. You are receiving
this because you have the service enabled, addressing the recipient of
this email.