Tidied up the user stuff. Added docstrings and documentation

Author: rogersmark

README

@@ -0,0 +1,38 @@
+Introduction
+=====================
+
+pyzootool wraps the API of http://www.zootool.com. It's currently still very early in development, and not quite everything works.
+
+What Works 
+=====================
+
+- Grabbing items by uid
+- Grabbing items by popularity
+- Grabbing items by username
+- Getting information on a user
+- Getting list of followers that a user has
+- Getting list of friends that a user has
+
+What Doesn't Work
+=====================
+
+- Authentication and anything that needs it
+- Adding items to zootool.com
+
+Examples
+=====================
+
+Here's a few examples of what you can do with this tool::
+
+	from pyzootool import controller
+	zoocontrol = controller.ZooControl(apikey=YOUR_API_KEY)
+	
+	## User information
+	followers = zoocontrol.user.get_user_followers('username')
+	friends = zoocontrol.user.get_user_friends('username')
+	userinfo = zoocontrol.user.get_userinfo('username')
+	
+	## Items
+	popular_items = zoocontrol.item.get_popular('week')
+	user_items = zoocontrol.item.get_items_by_user('username')
+	item = zoocontrol.item.get_item('uid')

README.rst

@@ -13,4 +13,4 @@ def __init__(self, apikey, username=None, password=None):
             ## TODO: Implement this
             self.auth = auth.ZooAuth(self.api_key, username, password)
         self.item = items.ZooItem(self.apikey, self.http)
-        #self.user = users.ZooUser(self.apikey, self.http)
+        self.user = users.ZooUser(self.apikey, self.http)

pyzootool/controller.py

@@ -6,9 +6,15 @@
 class ZooItemResult():
 
     def __init__(self, json_data):
+        """
+        Takes a SINGLE json object. Do *not* pass arrays of json data in.
+        """
         self.parse_results(json_data)
 
     def parse_results(self, json_data):
+        """
+        Maps out the json data fields to variables
+        """
         self.uid = json_data['uid']
         self.title = json_data['title']
         self.url = json_data['url']
@@ -22,11 +28,25 @@ def parse_results(self, json_data):
 class ZooItem():
 
     def __init__(self, apikey, http):
+        """
+        Arguments: 
+            apikey - ZooTool apikey
+            http - httplib2 http connection
+        """
         self.apikey = apikey
         self.http = http
 
-        
     def get_item(self, item_id):
+        """
+        Argument:
+            item_id - unique identifier of item
+            
+        Returns:
+            result - ZooItemResult
+            
+        Takes in a uid, calls to the ZooTool api to get the JSON objects.
+        Returns a parsed json result in the form of a ZooItemResult object.
+        """
         values = {'uid': item_id, 'apikey': self.apikey}
         url = "%s/api/items/info/?%s" % (
             ROOT_URL, urllib.urlencode(values)
@@ -37,13 +57,45 @@ def get_item(self, item_id):
         return result
 
     def get_popular(self, pop_type):
+        """
+        Argument:
+            pop_type - Valid options are 'week', 'year', 'all', 'today'
+            
+        Returns:
+            zoo_results - ZooItemResult
+            
+        Takes in the popular sorting option. Returns an array of ZooItemResults
+        """
         values = {'type': pop_type, 'apikey': self.apikey }
         url = "%s/api/items/popular/?%s" % (
             ROOT_URL, urllib.urlencode(values)
         )
         resp, content = self.http.request(url)
         json_data = json.loads(content)
         zoo_results = []
+        for item in json_data:
+            result = ZooItemResult(item)
+            zoo_results.append(result)
+        return zoo_results
+        
+    def get_items_by_user(self, username):
+        """
+        Arguement:
+            username - user we should grab items from
+            
+        Returns:
+            zoo_results - Array of ZooItemResults
+            
+        Takes in a username, calls ZooTool API and receives JSON data. Kicks
+        back an array of ZooItemResults
+        """
+        values = {'username': username, 'apikey': self.apikey}
+        url = "%s/api/users/items/?%s" % (
+            ROOT_URL, urllib.urlencode(values)
+        )
+        resp, content = self.http.request(url)
+        json_data = json.loads(content)
+        zoo_results = []
         for item in json_data:
             result = ZooItemResult(item)
             zoo_results.append(result)

pyzootool/items.py

@@ -0,0 +1,96 @@
+import json
+import urllib
+
+from pyzootool import ROOT_URL
+
+class ZooUserResult():
+    
+    def __init__(self, json_data):
+        """
+        Takes a SINGLE json data object. Do not pass an array in
+        """
+        self.parse_results(json_data)
+        
+    def parse_results(self, json_data):
+        """
+        Maps out the json data fields to variables
+        """
+        print json_data
+        self.username = json_data['username']
+        self.website = json_data['website']
+        self.avatar = json_data['avatar']
+        self.profile = json_data['profile']
+        
+class ZooUser():
+    """
+    TODO:
+        This whole class
+    """
+    
+    def __init__(self, apikey, http):
+        """
+        Arguments: 
+            apikey - ZooTool apikey
+            http - httplib2 http connection
+        """
+        self.apikey = apikey
+        self.http = http
+        
+    def get_userinfo(self, username):
+        """
+        Argument:
+            username - name of user you wish to get info on
+            
+        Returns:
+            result - ZooUserResult
+        
+        Takes in a username, calls ZooTool API and gets json data
+        """
+        values = {'username': username, 'apikey': self.apikey}
+        url = "%s/api/users/info/?%s" % (ROOT_URL, urllib.urlencode(values))
+        resp, content = self.http.request(url)
+        json_data = json.loads(content)
+        result = ZooUserResult(json_data)
+        
+    def get_user_friends(self, username):
+        """
+        Argument:
+            username - name of user you wish to get info on
+            
+        Returns:
+            zoo_results - Array of ZooUserResult
+        
+        Takes in a username, calls ZooTool API and gets json data
+        """
+        values = {'username': username, 'apikey': self.apikey}
+        url = "%s/api/users/friends/?%s" % (ROOT_URL, urllib.urlencode(values))
+        resp, content = self.http.request(url)
+        json_data = json.loads(content)
+        zoo_results = []
+        for item in json_data:
+            result = ZooUserResult(item)
+            zoo_results.append(result)
+        if zoo_results:
+            return zoo_results
+        else:
+            raise AttributeError("No Results Found")
+        
+    def get_user_followers(self, username):
+        """
+        Argument:
+            username - name of user you wish to get info on
+
+        Returns:
+            zoo_results - Array of ZooUserResult
+
+        Takes in a username, calls ZooTool API and gets json data
+        """
+        values = {'username': username, 'apikey': self.apikey}
+        url = "%s/api/users/followers/?%s" % (ROOT_URL, urllib.urlencode(values))
+        resp, content = self.http.request(url)
+        json_data = json.loads(content)
+        zoo_results = []
+        for item in json_data:
+            result = ZooUserResult(item)
+            zoo_results.append(result)
+        return zoo_results