From 0929d772518a7b6cd4f58130a9983773f029cc75 Mon Sep 17 00:00:00 2001
From: Is Isilon <wassname@wassname.org>
Date: Wed, 3 Feb 2016 17:42:34 +0800
Subject: [PATCH] Added docstrings and site options

---
 README.md            |  2 +-
 compleat/__init__.py | 11 +++++++++--
 compleat/cli.py      |  2 +-
 compleat/query.py    | 14 ++++++++++++++
 4 files changed, 25 insertions(+), 4 deletions(-)

diff --git a/README.md b/README.md
index 76e4c07..7866d16 100644
--- a/README.md
+++ b/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
diff --git a/compleat/__init__.py b/compleat/__init__.py
index b982d0b..cadf95f 100644
--- a/compleat/__init__.py
+++ b/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)
diff --git a/compleat/cli.py b/compleat/cli.py
index 987bf41..0cbe868 100644
--- a/compleat/cli.py
+++ b/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)
diff --git a/compleat/query.py b/compleat/query.py
index 5119dd1..9afa950 100644
--- a/compleat/query.py
+++ b/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")