Merge pull request #156 from GrappigPanda/issue-124

Fixes #124: Added docstrings to everything.

Author: Ian C

pyg/Pygemony.py

@@ -8,6 +8,9 @@
 
 
 class Pygemony(object):
+    """
+    The main driver of pygemony, pulls the seperate pieces together.
+    """
     def __init__(self, user=None, token=None, owner=None, repo=None):
         # todo_found contains a list of the following layout:
         # ['file_path', 'line_number', 'todo_message', 'md5 of todo']
@@ -17,23 +20,14 @@ def __init__(self, user=None, token=None, owner=None, repo=None):
         # TODO(ian): Add support for parsing more than one file type
         self.language = self.lookup_language()
 
-    def find_end_comment(self, f):
-        # TODO(ian): Remove this function as we no longer support multiline TODO
-        todo_content = []
-        x = f
-        count = 0
-        for line in x.readlines():
-            todo_content.append(line)
-            if self.language.multi_comment[1] in line:
-                return todo_content
-
-            if count > 20:
-                return None
-
-            todo_content.append(line)
-            count += 1
-
     def _sanitize_todo_line(self, lines):
+        """
+        Strips tab, newline, and comment characters form the TODO line.
+
+        :param str lines: The found line containing a TODO
+        :rtype: str
+        :return: The sanitized TODO line.
+        """
         # We're mainly aiming to remove newlines and tab characters here.
         lines = lines.replace('\n', '')
         while '    ' in lines or '\t' in lines:
@@ -44,23 +38,55 @@ def _sanitize_todo_line(self, lines):
 
     @staticmethod
     def hash_todo(todo_content, file_name):
+        """
+        Hashes the TODO line with the file name
+
+        :param str todo_content: The line in the file containing TODO
+        :param str file_name: The file name containing the TODO line.
+        :rtype: str
+        :return: The MD5 hash of the `todo_content` and `file_name`
+        """
         m = hashlib.md5()
         m.update('{0}-{1}'.format(todo_content, file_name))
         return str(m.hexdigest())
 
     def parse_for_todo(self, f, file_):
+        """
+        Searches (line-by-line) through a file's content and and looks for
+            lines containing TODO.
+
+        :param file_handle f: The handle to the file that is currently being
+            searched
+        :param str file_: The name of the file currently being searched
+        """
         for i, line in enumerate(f.readlines()):
             if "TODO" in line and self._starts_with_comment(line):
                 line = self._sanitize_todo_line(line)
                 self.todo_found.append([file_, i, line, self.hash_todo(line, file_)])
 
     def parse_by_extension(self, files):
+        """
+        Parses the list of the directory for files with an acceptable
+        extension. The extension is determined by data returned from github on
+        the languages used in the project.
+
+        :param list files: The list of all files in the current repository
+        :rtype: generator(str)
+        :return: Generates a list of acceptable-to-parse files.
+        """
         for lang in self.language:
             for ext in lang.file_exts:
                 for file_ in fn_filter(files, ext):
                     yield file_
 
     def find_all_files(self, root):
+        """
+        Walks the current repository directory and determines viable files
+
+        :param str root: The root directory
+        :rtype: list
+        :return: The list of files found and determined to be viable.
+        """
         files_found = []
 
         for roots, _, files in walk(root):
@@ -73,6 +99,12 @@ def find_all_files(self, root):
         return files_found
 
     def file_handler(self):
+        """
+        Handles IO with the file
+
+        :rtype: list
+        :return: The list of files found
+        """
         # First we need to remove any non-text files
         files_found = self.find_all_files('./')
         # TODO(ian): filter() over files to parse out by mimetype
@@ -96,10 +128,20 @@ def file_handler(self):
         return files_found
 
     def run(self):
+        """
+        Starts the process of finding TODOs
+        """
         self.file_handler()
         self.github.commit(self.todo_found)
 
     def lookup_language(self):
+        """
+        Constructs langauge classes based on what is found in github data.
+        
+        :rtype: list
+        :return: A list of language classes that will be found in a github
+            repo.
+        """
         lang_map = {'cpp': LanguageCPP,
                     'python': LanguagePython,
                     'javascript': LanguageJavascript,
@@ -114,12 +156,28 @@ def lookup_language(self):
         return [lang_map[str(langs[0][0]).lower()]()]
 
     def _starts_with_comment(self, line):
+        """
+        Verifies a line (containing the word TODO) starts with a comment, if it
+        does, we deem it to be commit-viable.
+        
+        :param str line: The line that contains "TODO"
+
+        :rtype: bool
+        :return: True if line starts with a comment (is a valid TODO statement)
+        """
         comments = self._create_comment_start_list()
         for comment in comments:
             if line.startswith(comment):
                 return True
 
     def _create_comment_start_list(self):
+        """
+        Create a list of comments from each language class associated with the
+            current repo.
+
+        :rtype: list
+        :return: A list of strings containing all line-start comments.
+        """
         comments = []
         for lang in self.language:
             comments.append(lang.single_comment)

pyg/github.py

@@ -3,6 +3,10 @@
 
 
 class GithubAPIManager(object):
+    """
+    Handles authorization and everything else done with the github api.
+    """
+
     # repo_location = grappigpanda/pygemony.py
     def __init__(self, user, token, owner, repo):
         self.is_authed = False
@@ -27,13 +31,27 @@ def __init__(self, user, token, owner, repo):
 
 
     def login(self):
+        """
+        Logs the user in.
+
+        :rtype: gh.repository
+        :return: github3.login()
+        """
         try:
             return github3.login(self.user, self.token)
         except github3.models.GitHubError as e:
             print "Failed to login due to {}".format(e)
         return None
 
     def _save_submitted_todo(self, issue):
+        """
+        Writes the TODO issue information (the hashed info) to the
+        `.pyg-submitted` file.
+
+        :param list issue: A list containing info about the found TODO
+        :rtype: bool
+        :return: True on successful write, False if the issue exists already.
+        """
         if not path.isfile('./.pyg-submitted'):
             with open('./.pyg-submitted', 'a+') as f:
                 f.write("""
@@ -53,6 +71,13 @@ def _save_submitted_todo(self, issue):
             return True
 
     def commit(self, todo_found):
+        """
+        Creates a github issue per TODO found. 
+
+
+        :param list todo_found: A list containing information about the found
+            TODO
+        """
         # TODO(ian): Assign issues if () in line. (ian), for example
         for issue in todo_found:
             if self._save_submitted_todo(issue):
@@ -61,31 +86,67 @@ def commit(self, todo_found):
                                         body=self._construct_issue_body(issue))
 
     def get_languages(self):
+        """
+        Iterates through the languages used in the project and yields the
+        language.
+
+        :rtype: generator(str)
+        :return: A generator for the languages used in the project
+        """
         for i in self.curr_repo.iter_languages():
             yield i
 
     def _get_repo_owner(self):
+        """
+        Gets the repo owner from the gitconfig.
+
+        :rtype: tuple
+        :return: The (repo, owner) of the repo from the git config.
+        """
         # TODO(ian): Remove the magic directory!
         with open('./.git/config', 'r+') as f:
             for line in f.readlines():
                 if 'url = ' in line:
                     return line.split('github.com/')[-1].split('/')
 
     def get_repo(self):
+        """
+        Reads the repo name from the git config
+
+        :rtype: str
+        :return: The repo's name
+        """
         return self._get_repo_owner()[1]
 
     def get_owner(self):
+        """
+        Reads the repo owner's name from the git config
+
+        :rtype: str
+        :return: The repo owner's name
+        """
         return self._get_repo_owner()[0]
 
     @staticmethod
     def _construct_issue_body(issue):
+        """
+        Constructs the issue body that is posted in the github issue.
+
+        :rtype: str
+        :return: The issue body, html formatted.
+        """
         # TODO(ian): Move all @staticmethods to a seperate class
         sz = 'File Location: {}<br>Line Number: {}'.format(issue[0], issue[1])
         sz += '<br> This message was auto-generated by Pygemony: '
         sz += '<a href="http://github.com/GrappigPanda/pygemony">Github</a>'
         return sz
 
     def _pprint(self, issue):
+        """
+        Prints information to the screen about creating commits
+
+        :param list issue: A list of information about the found TODO.
+        """
         msg = "Committing to repo: {}"
         msg += "\n\tFile Name: {}:{}\n\tTodo Message:{}"
         print msg.format(self.repo, issue[0], issue[1], issue[2])

pyg/utils.py

@@ -1,6 +1,13 @@
 from mimetypes import guess_type
 
 def get_git_info():
+    """
+    Parses the git info and returns a tuple containg the owner and repo
+
+    :deprecated:
+    :rtype: tuple
+    :return: (owner name, repo name)
+    """
     repo = ''
     with open('.git/config') as f:
         for line in f.readlines():
@@ -12,4 +19,12 @@ def get_git_info():
 
 
 def detect_mimetype(file_):
+    """
+    Detects the provided file's mimetype. Used to determine if we should read
+        the file line-by-line.
+
+    :param str file_: The name of the file to guess the mimetype of
+    :rtype: str
+    :return: The mimetype of the file provided
+    """
     return guess_type(file_)