Added docstrings and site options

README.md

@@ -59,7 +59,7 @@ Note: `compleat.suggest()` also accepts an optional `lang` parameter, which is "
 ['bonoloto', 'bonus', 'bon jovi', 'bones', 'bonsai']
 ```
 
-Note: `compleat.suggest()` also accepts an optional `site` parameter, which is "" (Google) by default. Others include `bo` for google books, `i` for google images, and `yt` for youtube.
+Note: `compleat.suggest()` also accepts an optional `site` parameter, which is "" (Google) by default. Others include `bo` for google books, `i` for google images, and `yt` for youtube, as well as `n` for news, `pr`, `sh` for shopping, `v` for videos.
 
 ```python
 >>> import compleat

compleat/__init__.py

@@ -1,7 +1,14 @@
+"""
+compleat
+
+Fetch autocomplete suggestions from Google Search. Use responsibly. Not affiliated with Google.
+"""
+
 from .query import Query
 
 VERSION = (0, 0, 2)
-__version__ = ".".join(map(str,VERSION))
+__version__ = ".".join(map(str, VERSION))
 
-def suggest(query_string, lang="en", site="",):
+
+def suggest(query_string, lang="en", site="", ):
     return Query(query_string, lang, site)

compleat/cli.py

@@ -56,7 +56,7 @@ def log_query(query_string, lang):
     template = u"{lang}: {query}\n"
     msg = template.format(lang=lang, query=query_string)
     sys.stderr.write(msg)
-    
+
 def exec_query(query_string, lang):
     time.sleep(args.wait)
     log_query(query_string, lang)

compleat/query.py

@@ -6,6 +6,14 @@ import datetime
 import random
 
 class Query(object):
+    """
+    Query object representing autocomplete suggestions from Google Search.
+
+    @methods:
+    - suggestions: an array of dicts with fields: 'relevance', 'text', 'title', 'type'
+    - meta: dict with fields: lang, query, uuid, site, timestamp
+
+    """
     URL_TEMPLATE = "http://suggestqueries.google.com/complete/search?client=chrome&hl={lang}&q={query}&ds={site}"
     def __init__(self, query, lang="en", site=""):
         self.query = query
@@ -16,6 +24,12 @@ class Query(object):
         req = requests.get(self.url, headers={'User-Agent': requests.utils.default_user_agent() + '/r=' + self.rand})
         self.response = req.json()
 
+    def __repr__(self):
+        return '<compleat.query.Query: %s, results=%s >' % (self.meta, len(self.suggestions))
+
+    def __str__(self):
+        return 'Query: %s, results %s, time=%s' % (self.meta['query'], len(self.suggestions), self.meta['timestamp'])
+
     @property
     def url(self):
         encoded = self.query.encode("utf-8")