Fully documenting github.py

hackathon_starter/hackathon/scripts/github.py

@@ -1,6 +1,6 @@
 '''
-github.py contains a handful of methods
-for interacting with Github data.
+github.py contains a handful of methods for interacting 
+with Github data and returning the responses as JSON.
 '''
 
 import requests
@@ -13,149 +13,268 @@ import simplejson as json
 API_BASE_URL = 'https://api.github.com/users/DrkSephy'
 
 def getUserData(clientID, clientSecret):
-	'''Get generic Github User data.'''
-	url = API_BASE_URL + '?' + clientID + '&' + clientSecret
-	req = requests.get(url)
-	jsonList = []
-	jsonList.append(json.loads(req.content))
-	parsedData = []
-	userData = {}
-	for data in jsonList: 
-		userData['name'] = data['name']
-		userData['blog'] = data['blog']
-		userData['email'] = data['email']
-		userData['public_gists'] = data['public_gists']
-		userData['public_repos'] = data['public_repos']
-		userData['avatar_url'] = data['avatar_url']
-		userData['followers'] = data['followers']
-		userData['following'] = data['following']
-	parsedData.append(userData)
-
-	return parsedData
-	
+    '''
+    Returns data found on a Github User's public profile. 
+    This includes information such as number of followers,
+    e-mail, number of repositories and more. 
 
-def getUserRepositories(clientID, clientSecret):
-	'''Get a list of all repositories owned by a User.'''
+    Parameters:
+        clientID: String 
+            - The clientID from registering this application
+              on Github.
+        clientSecret: String
+            - The clientSecret from registering this application
+            on Github.
+
+    Returns: 
+        parsedData: Dictionary
+            - A dictionary containing the following data:
+                - userData['name']
+                    - The user's public name on Github
+                - userData['blog']
+                    - Link to the user's blog on Github
+                - userData['email']
+                    - The user's public e-mail on Github
+                - userData['public_gists']
+                    - The number of the user's public gists 
+                - userData['public_repos']
+                    - The number of public repositories owned
+                - userData['avatar_url']
+                    - Link to user's public avatar 
+                - userData['followers']
+                    - Number of followers 
+                - userData['following']
+                    - Number of users being followed
+    '''
+    url = API_BASE_URL + '?' + clientID + '&' + clientSecret
+    req = requests.get(url)
+    jsonList = []
+    jsonList.append(json.loads(req.content))
+    parsedData = []
+    userData = {}
+    for data in jsonList: 
+        userData['name'] = data['name']
+        userData['blog'] = data['blog']
+        userData['email'] = data['email']
+        userData['public_gists'] = data['public_gists']
+        userData['public_repos'] = data['public_repos']
+        userData['avatar_url'] = data['avatar_url']
+        userData['followers'] = data['followers']
+        userData['following'] = data['following']
+    parsedData.append(userData)
 
-	pageNumber = 1
+    return parsedData
+    
+
+def getUserRepositories(clientID, clientSecret):
+    '''
+    Returns a list of all the public repositories 
+    owned by a User. 
 
+    Parameters:
+        clientID: String 
+            - The clientID from registering this application
+              on Github.
+        clientSecret: String.
+            - The clientSecret from registering this application
+            on Github.
 
-	jsonList = []
-	repositories = []
+    Returns:
+        repositories: List 
+            - A list containing all public repository names 
+              belonging to a user.
+    '''
+    pageNumber = 1
+    jsonList = []
+    repositories = []
 
-	while True:
-		req = requests.get('https://api.github.com/users/DrkSephy/repos?page=' + str(pageNumber) + '&' + clientID + '&' + clientSecret)
-		jsonList.append(json.loads(req.content))
-		if len(json.loads(req.content)) < 30:
-			break
-		elif len(json.loads(req.content)) >= 30:
-			pageNumber += 1
+    while True:
+        req = requests.get('https://api.github.com/users/DrkSephy/repos?page=' + str(pageNumber) + '&' + clientID + '&' + clientSecret)
+        jsonList.append(json.loads(req.content))
+        if len(json.loads(req.content)) < 30:
+            break
+        elif len(json.loads(req.content)) >= 30:
+            pageNumber += 1
 
-	
-	for data in jsonList:
-		for datum in data:
-			repositories.append(datum['name'])
-			
-	return repositories
+    
+    for data in jsonList:
+        for datum in data:
+            repositories.append(datum['name'])
+            
+    return repositories
 
 def getForkedRepositories(clientID, clientSecret):
-	'''Get a list of all forked repositories by a user.'''
-	
-	pageNumber = 1
+    '''
+    Returns a list of all the public forked repositories 
+    owned by a User. 
 
-	
-	jsonList = []
+    Parameters:
+        clientID: String 
+            - The clientID from registering this application
+              on Github.
+        clientSecret: String.
+            - The clientSecret from registering this application
+            on Github.
 
-	
-	forkedRepositories = []
+    Returns:
+        forkedRepositories: List 
+            - A list containing all forked repository names 
+              belonging to a user.
+    '''
+    
+    pageNumber = 1
+    jsonList = []
+    forkedRepositories = []
  
-	while True:
-		req = requests.get('https://api.github.com/users/DrkSephy/repos?page=' + str(pageNumber) + '&' + clientID + '&' + clientSecret)
-		jsonList.append(json.loads(req.content))
-		if len(json.loads(req.content)) < 30:
-			break
-		elif len(json.loads(req.content)) >= 30:
-			pageNumber += 1
+    while True:
+        req = requests.get('https://api.github.com/users/DrkSephy/repos?page=' + str(pageNumber) + '&' + clientID + '&' + clientSecret)
+        jsonList.append(json.loads(req.content))
+        if len(json.loads(req.content)) < 30:
+            break
+        elif len(json.loads(req.content)) >= 30:
+            pageNumber += 1
 
 
-	forkedRepos = {}
-	for data in jsonList:
-		for datum in data:
-			if datum['fork'] == True:
-				forkedRepos['name'] = datum['name']
-				forkedRepositories.append(forkedRepos)
-				forkedRepos = {}
+    forkedRepos = {}
+    for data in jsonList:
+        for datum in data:
+            if datum['fork'] == True:
+                forkedRepos['name'] = datum['name']
+                forkedRepositories.append(forkedRepos)
+                forkedRepos = {}
 
-	return forkedRepositories
+    return forkedRepositories
 
 def getTopContributedRepositories(repos, clientID, clientSecret):
-	'''Get a list of all commits for each repository owned.'''
+    '''
+    Returns a list containing the commit totals for all 
+    repositories owned by a user. 
 
-	jsonList = []
-	for repo in repos:
-		req = requests.get('https://api.github.com/repos/DrkSephy/' + repo + '/stats/contributors' + '?' + clientID + '&' + clientSecret)
-		jsonList.append(json.loads(req.content))
+    Parameters:
+        clientID: String 
+            - The clientID from registering this application
+              on Github.
+        clientSecret: String
+            - The clientSecret from registering this application
+            on Github.
 
-	parsedData = []
+    Returns: 
+        parsedData: Dictionary
+            - A dictionary containing the following data:
+                - commits['author']
+                    - The name of the committer
+                - commits['total']
+                    - Total commit count for a user in a repository
+                - commits['repo_name']
+                    - The name of the repository being tallied
+    '''
+    jsonList = []
+    for repo in repos:
+        req = requests.get('https://api.github.com/repos/DrkSephy/' + repo + '/stats/contributors' + '?' + clientID + '&' + clientSecret)
+        jsonList.append(json.loads(req.content))
 
-	indexNumber = -1
-	for item in jsonList:
-		indexNumber += 1
-		commits = {}
-		for data in item:
-			if data['author']['login'] == 'DrkSephy':
-				commits['author'] = data['author']['login']
-				commits['total'] = data['total']
-				commits['repo_name'] = repos[indexNumber]
-				parsedData.append(commits)
+    parsedData = []
 
-	return parsedData
+    indexNumber = -1
+    for item in jsonList:
+        indexNumber += 1
+        commits = {}
+        for data in item:
+            if data['author']['login'] == 'DrkSephy':
+                commits['author'] = data['author']['login']
+                commits['total'] = data['total']
+                commits['repo_name'] = repos[indexNumber]
+                parsedData.append(commits)
+
+    return parsedData
 
 def filterCommits(data):
-	'''Returns the top 10 committed repositories.'''
-
-	maxCommits = []
-	for i in range(1, 10):
-		maxCommitedRepo = max(data, key=lambda x:x['total'])
-		maxCommits.append(maxCommitedRepo)
-		index = data.index(maxCommitedRepo)
-		data.pop(index)
-	return maxCommits
-	
-	
+    '''
+    Returns the top 10 committed repositories.
+
+    Parameters: 
+        data: List
+            - A list containing commit counts for all
+            of a user's public repositories
+
+    Returns:
+        maxCommits: List
+            - A list containing the top ten repositories 
+            with the maximum number of commits by a user
+    '''
+
+    maxCommits = []
+    for i in range(1, 10):
+        maxCommitedRepo = max(data, key=lambda x:x['total'])
+        maxCommits.append(maxCommitedRepo)
+        index = data.index(maxCommitedRepo)
+        data.pop(index)
+    return maxCommits
+    
+    
 def getStarGazerCount(clientID, clientSecret):
-	'''Get Stargazer counts for all repositories.'''
-	
-	pageNumber = 1
-	jsonList = []
-	stargazers = []
-	while True:
-		req = requests.get('https://api.github.com/users/DrkSephy/repos?page=' + str(pageNumber) + '&' + clientID + '&' + clientSecret)
-		jsonList.append(json.loads(req.content))
-		if len(json.loads(req.content)) < 30:
-			break
-		elif len(json.loads(req.content)) >= 30:
-			pageNumber += 1
-
-
-	for data in jsonList:
-		for datum in data:
-			starData = {}
-			starData['stargazers_count'] = datum['stargazers_count']
-			starData['name'] = datum['name']
-			stargazers.append(starData)
-			
-	return stargazers
+    '''
+    Returns a list number of stargazers for each
+    of a user's public repositories.  
+
+    Parameters:
+        clientID: String 
+            - The clientID from registering this application
+              on Github.
+        clientSecret: String
+            - The clientSecret from registering this application
+            on Github.
+
+    Returns: 
+        stargazers: Dictionary
+            - A dictionary containing the following data:
+                - starData['stargazers_count']
+                    - The number of stargazers for a given repository
+                - starData['name']
+                    - The name of the repository being observed
+    '''
+    pageNumber = 1
+    jsonList = []
+    stargazers = []
+    while True:
+        req = requests.get('https://api.github.com/users/DrkSephy/repos?page=' + str(pageNumber) + '&' + clientID + '&' + clientSecret)
+        jsonList.append(json.loads(req.content))
+        if len(json.loads(req.content)) < 30:
+            break
+        elif len(json.loads(req.content)) >= 30:
+            pageNumber += 1
+
+
+    for data in jsonList:
+        for datum in data:
+            starData = {}
+            starData['stargazers_count'] = datum['stargazers_count']
+            starData['name'] = datum['name']
+            stargazers.append(starData)
+            
+    return stargazers
 
 def filterStarGazerCount(data):
-	'''Return top 10 starred repositories.'''
-	maxStars= []
-	for i in range(1, 10):
-		maxStarGazers = max(data, key=lambda x:x['stargazers_count'])
-		maxStars.append(maxStarGazers)
-		index = data.index(maxStarGazers)
-		data.pop(index)
-	return maxStars
+    '''
+    Returns the top 10 stargazed repositories.
+
+    Parameters: 
+        data: List
+            - A list containing stargazer counts for all
+            of a user's public repositories
+
+    Returns:
+        maxStars: List
+            - A list containing the top ten repositories 
+            with the maximum number of stargazers
+    '''
+    maxStars= []
+    for i in range(1, 10):
+        maxStarGazers = max(data, key=lambda x:x['stargazers_count'])
+        maxStars.append(maxStarGazers)
+        index = data.index(maxStarGazers)
+        data.pop(index)
+    return maxStars