Add Documentation

Docs for setup.py and nested uiplib modules

Fixes NITDgpOS#35

.coafile

@@ -5,3 +5,8 @@ use_spaces = true
 default_actions =
         SpaceConsistencyBear: ApplyPatchAction,
         PEP8Bear: ApplyPatchAction
+
+[Documentation]
+bears = PyDocStyleBear
+files = *.py, uiplib/**/*.py
+ignore = **/__init__.py

UIP

@@ -3,5 +3,4 @@ from uiplib.UIP import main
 
 
 if __name__ == "__main__":
-    sys.exit(main())  
-
+    sys.exit(main())

setup.py

@@ -1,3 +1,5 @@
+"""Module to perform build, package and install."""
+
 import sys
 import os
 import json
@@ -14,6 +16,7 @@
 
 
 def get_packages():
+    """Method to retrieve packages to be bundled."""
     base_dir = 'uiplib'
     packages = [base_dir]
     for (path, dirs, files) in os.walk(base_dir):
@@ -26,7 +29,8 @@ def get_packages():
     return packages
 
 
-def get_contents(filename):
+def get_requirements(filename):
+    """Method to get the requirements of the specified file."""
     file = open(filename, 'r').readlines()
     out = []
     for a in file:
@@ -55,9 +59,9 @@ def get_contents(filename):
         settings_file.write(json.dumps(file_data))
 
 requirements = []
-requirements += get_contents('requirements.txt')
+requirements += get_requirements('requirements.txt')
 if sys.platform.startswith('darwin'):
-    requirements += get_contents('mac-requirements.txt')
+    requirements += get_requirements('mac-requirements.txt')
 
 setup(
     # Name of application:

uiplib/GUI.py

@@ -1,3 +1,5 @@
+"""Module that builds the Graphical User Interface."""
+
 from uiplib.scheduler import scheduler
 from uiplib.setWallpaper import change_background
 from uiplib.utils.utils import update_settings, check_sites
@@ -11,14 +13,17 @@
 
 
 class Gallery(Frame):
+    """A view to show the pictures."""
 
     def __init__(self, master):
+        """Initialize the gallery."""
         Frame.__init__(self, master)
         self.image = None
         self.cv = None
         self.label = None
 
     def show_error(self):
+        """Method to display errors."""
         self.image = None
         self.cv = None
         self.label = Label(self, wraplength=150,
@@ -28,6 +33,7 @@ def show_error(self):
         self.label.pack(padx=50, pady=50)
 
     def set_image(self, imagePath):
+        """Method to set the image preview."""
         self.label = None
         width = 600
         height = 340
@@ -42,9 +48,10 @@ def set_image(self, imagePath):
 
 
 class MainWindow:
-    ''' The main window that houses the app '''
+    """The main window that houses the app."""
 
     def __init__(self, settings):
+        """Initialize the Main Window."""
         # configuration
         self.settings = settings
         # base window
@@ -61,13 +68,14 @@ def __init__(self, settings):
         self.create_ui()
 
     def create_ui(self):
-        ''' Method to initialize UI '''
+        """Method to initialize UI."""
         self.notebook = Notebook(self.root)
         self.notebook.pack()
         self.create_general_tab()
         self.create_settings_tab()
 
     def create_settings_tab(self):
+        """Method to create settings tab."""
         self.new_settings = {}
         settings_tab = Frame(self.notebook)
         self.notebook.add(settings_tab, text="Settings")
@@ -143,6 +151,7 @@ def create_settings_tab(self):
         apply_button.grid(row=6, column=1, pady=20, sticky=W)
 
     def create_general_tab(self):
+        """Method to create general tab."""
         general_width = 1000
         general_height = general_width*3/4
         general = Frame(self.notebook,
@@ -190,6 +199,7 @@ def create_general_tab(self):
             self.gallery.show_error()
 
     def show_progess(self, show):
+        """Method to display download progress."""
         if show:
             self.progressBar = Progressbar(self.headerFrame,
                                            orient=HORIZONTAL,
@@ -201,34 +211,41 @@ def show_progess(self, show):
             self.progressBar = None
 
     def push(self, x):
+        """Method to push onto UI Queue."""
         self.queue.push(x)
 
     def run(self):
+        """Method that runs the main event loop."""
         self.update_ui()
         # run the main event loop of UI
         self.root.mainloop()
 
     def update_ui(self):
+        """Method that updates UI periodically."""
         # update UI with data received
         while self.queue and not self.queue.empty():
             pass
         # update UI after every 200ms
         self.root.after(200, self.update_ui)
 
     def next_wallpaper(self):
+        """Preview next wallpaper."""
         self.index = (self.index + 1) % len(self.images)
         self.gallery.set_image(self.images[self.index])
 
     def prev_wallpaper(self):
+        """Preview previous wallpaper."""
         self.index -= 1
         self.gallery.set_image(self.images[self.index])
 
     def set_wallpaper(self):
+        """Set the wallpaper which is being previewed."""
         image = self.images[self.index]
         change_background(image)
 
     def toggle_subreddit(self, mainFrame):
-        if self.reddit.get() == True:
+        """Method to toggle the subreddit choice pane."""
+        if self.reddit.get():
             try:
                 self.sub_label.grid()
                 self.sub_entry.grid()
@@ -249,23 +266,28 @@ def toggle_subreddit(self, mainFrame):
             self.sub_entry.grid_remove()
 
     def download(self):
+        """Method to start download."""
         pass
 
     def flush(self):
+        """Method to flush all images."""
         print("Flush Clicked!")
 
     def update_images(self):
+        """Method to get images from directory."""
         directory = self.settings['pics-folder']
         files = os.listdir(directory)
         self.images = [os.path.join(directory, file) for file in files
                        if (file.endswith('.png') or file.endswith('.jpg'))]
 
     def file_open_helper(self):
+        """Open the dialog to choose where pictures are to be saved."""
         directory = filedialog.askdirectory()
         self.pics_folder.set(directory)
         self.root.update_idletasks()
 
     def handle_settings(self):
+        """Handler to update the settings file."""
         try:
             self.new_settings['pics-folder'] = self.pics_folder.get()
         except AttributeError as e:
@@ -295,5 +317,6 @@ def handle_settings(self):
         update_settings(self.new_settings)
 
     def retrieve_textbox_input(self, textbox):
+        """Handler to fetch the textbox input."""
         text_input = textbox.get("1.0", END)
         return text_input

uiplib/UIP.py

@@ -1,3 +1,5 @@
+"""Main UIP Module."""
+
 import sys
 import os
 import shutil
@@ -8,6 +10,7 @@
 
 
 def main():
+    """Main method of the UIP."""
     settingsParser = ParseSettings()
     settings = settingsParser.settings
     pid_file = os.path.join(HOME_DIR, 'daemon-uip.pid')
@@ -65,6 +68,7 @@ def main():
 
 
 def exit_UIP():
+    """Exit from UIP program."""
     pid_file = os.path.join(HOME_DIR, 'daemon-uip.pid')
     if os.path.exists(pid_file):
         send(pid_file, SIGTERM)

uiplib/scheduler.py

@@ -1,3 +1,5 @@
+"""Module that schedules the wallpaper change."""
+
 from uiplib.setWallpaper import change_background
 from uiplib.utils.utils import get_percentage
 from uiplib.scrape.onlineFetch import onlineFetch
@@ -18,8 +20,10 @@
 
 
 class scheduler():
+    """Class which schedules the wallpaper change."""
 
     def __init__(self, offline, pics_folder, timeout, website, count, service):
+        """Initialize the scheduler configuration."""
         self.website = website
         self.timeout = timeout
         self.directory = pics_folder
@@ -59,14 +63,14 @@ def __init__(self, offline, pics_folder, timeout, website, count, service):
             print("No downloaded images. Try again in online mode.")
 
     def change_random(self):
+        """Change the wallpaper to a random image."""
         filename = random.choice(os.listdir(self.directory))
         path = os.path.join(self.directory, filename)
         print("changing desktop wallpaper to: ", path)
         change_background(path)
 
     def kbhit(self):
-        ''' Returns True if keyboard character was hit, False otherwise.
-        '''
+        """Return True if keyboard character was hit, False otherwise."""
         if self.service:
             return False
         if os.name == 'nt':
@@ -76,16 +80,18 @@ def kbhit(self):
             return dr != []
 
     def getch(self):
-        ''' Returns a keyboard character after kbhit() has been called.
-            Should not be called in the same program as getarrow().
-        '''
+        """Return a keyboard character after kbhit() has been called.
+
+        Should not be called in the same program as getarrow().
+        """
         s = ''
         if os.name == 'nt':
             return msvcrt.getch().decode('utf-8')
         else:
             return sys.stdin.read(1)
 
     def changeCycle(self):
+        """Wallpaper change cycle."""
         uold, sold, cold, c, e = os.times()
         while True:
             if not self.kbhit():
@@ -105,7 +111,9 @@ def changeCycle(self):
                 time.sleep(0.1)
 
     def setStartTime(self, time):
+        """Set the start time."""
         self.time = time
 
     def deltaTime(self):
+        """Return the time difference."""
         return (time.time()-self.time)

uiplib/scrape/onlineFetch.py

@@ -1,16 +1,19 @@
+"""Module to fetch wallpapers."""
+
 from uiplib.scrape.scrape import get_images
 from threading import Thread
 
-# Class to create threads for get_images
-
 
 class onlineFetch(Thread):
+    """Generic thread module to download images."""
 
     def __init__(self, url, directory, count):
+        """Initialize the fetch thread."""
         Thread.__init__(self)
         self.url = url
         self.directory = directory
         self.count = count
 
     def run(self):
+        """Begin the download. Automatically called when a thread starts."""
         get_images(self.url, self.directory, self.count)