Permalink
Browse files

improve formatting of inline documentation

  • Loading branch information...
1 parent 62d5c28 commit 222121fa07a8fda2676e9bff15836e842833ee31 @lavelle committed Feb 10, 2013
Showing with 31 additions and 42 deletions.
  1. +5 −15 clipcloud.py
  2. +17 −18 gridformat.py
  3. +9 −9 settings.py
View
@@ -9,18 +9,18 @@
from settings import *
-def clipcloud():
+def main():
"""
Wrapper around the rest of the program's functionality.
Receives the command line parameters and passes them on to be processed.
Also does some other stuff that needs to be done every time the program runs.
"""
- # Create the folder for storing screenshots if it doesnt exist.
+ # Create the folder for storing screenshots if it doesn't exist
if not os.path.exists(SCREENSHOT_PATH):
os.makedirs(SCREENSHOT_PATH)
- # Create the folder for storing temporary files if it doesnt exist.
+ # Create the folder for storing temporary files if it doesn't exist
if not os.path.exists(TMP_PATH):
os.makedirs(TMP_PATH)
@@ -82,20 +82,10 @@ def clipcloud():
default=1)
history_parser.set_defaults(func=history)
- # finally parse all arguments run the relevant function
+ # Finally parse all the arguments
args = parser.parse_args()
+ # Run the relevant function
args.func(args)
-
-def main():
- # If program execution time is being measured, call the main function from a timer
- # if TIMER_ACTIVATED:
- # from timeit import Timer
- # t = Timer('clipcloud.clipcloud()', 'import clipcloud')
- # print t.timeit(number=1)
- # Otherwise just call it
- # else:
- clipcloud()
-
if __name__ == '__main__':
main()
View
@@ -1,22 +1,21 @@
def format_grid(grid, divider_positions=[], truncatable_column=None):
"""
- Format a 2d array of values in to a well-formatted, aligned gridstring
+ Create a string that displays a 2D array of values in a formatted and aligned table
- Arguments:
- - grid: A rectangular 2d array of values
- - divider_positions: an array of integers specifying the rows of the grid to add dividers
- to defaults to no dividers
- - truncatable_column: An integer specifying a column whose data can be sensibly truncated
+ grid - A rectangular 2D array of values
+ divider_positions - An array of integers specifying the indices of the rows of the grid
+ to add dividers to. Defaults to no dividers.
+ truncatable_column - The index of a column whose data can be sensibly truncated
- Returns: The grid as a nicely formatted string, with padding, dividers and
+ Returns the grid as a nicely formatted string, with padding, dividers and
truncation if it is wider than the terminal window
"""
- # find the longest cell in each column so the minimum width is known
+ # Find the longest cell in each column so the minimum width is known
widths = [max([len(cell) for cell in row]) for row in zip(*grid)]
total = sum(widths)
- # try to determine the width of the user's terminal window in characters
+ # Try to determine the width of the user's terminal window in characters
# so the rows can be truncated if they are too long
try:
import subprocess
@@ -26,44 +25,44 @@ def format_grid(grid, divider_positions=[], truncatable_column=None):
print 'The size of your terminal window could not be determined so ' \
'the layout of the grid below may be broken due to text wrapping.'
- # default width for a lot of systems
+ # Default width for a lot of systems
terminal_width = 80
- # if the grid is wider than the terminal window work out the difference between them
- # this is the amount to truncate the grid by
+ # If the grid is wider than the terminal window work out the difference between them -
+ # this is the number of characters by which the table should be truncated
terminal_diff = None
if total > terminal_width:
if truncatable_column is not None:
# 12 is the number of dividers and spaces added
terminal_diff = terminal_width - total - 12
- # reduce the width of the column by the difference
+ # Reduce the width of the column by the difference
widths[2] += terminal_diff
else:
print 'The grid is wider than your terminal but no columns can be truncated so ' \
'some columns may not be visible.'
- # final grid array
+ # Final grid array
a = []
for row in grid:
- # truncate column 3 if the table would be wider than the terminal window
+ # Truncate column 3 if the table would be wider than the terminal window
# id, url and date don't vary much in width, only the local path is worth truncating
if truncatable_column is not None and terminal_diff is not None and \
len(row[truncatable_column]) > widths[truncatable_column]:
row[truncatable_column] = row[truncatable_column][:terminal_diff - 3] + '...'
- # format the cells into a string with dividers between and add the row to the final grid
+ # Format the cells into a string with dividers between and add the row to the final grid
# and pad with spaces so all cells in the column are the same width
s = ((' {:%d} |' * len(widths))[:-1] % tuple(widths)).format(*row)
a.append(s)
- # add a horizontal divider only below the header
+ # Add a horizontal divider below the column titles
width = len(s)
for pos, i in zip(divider_positions, xrange(len(divider_positions))):
a.insert(pos + i, '-' * width)
- # convert to the final string and trim the last line break
+ # Create the final string and trim the last line break
return '\n' + '\n'.join(a)[:-1]
View
@@ -3,37 +3,37 @@
PLATFORM = system()
-# name of the app.
+# Name of the app
APP_NAME = "ClipCloud"
-# root folder in AppData for storing data
+# Root directory for storing application data
if PLATFORM == 'Darwin':
APP_PATH = os.path.join(os.path.expanduser('~'), 'Library/Application Support/' + APP_NAME)
elif PLATFORM == 'Windows':
APP_PATH = os.path.join(os.environ['APPDATA'], APP_NAME)
elif PLATFORM == 'Linux':
APP_PATH = os.path.expanduser(os.path.join("~", "." + APP_NAME))
-# folder for storing screenshots
+# Directory for storing screenshots
SCREENSHOT_PATH = os.path.join(APP_PATH, 'img')
-# folder for temporary files
+# Directory for storing temporary files
TMP_PATH = os.path.join(APP_PATH, 'tmp')
-# file to store history in
+# File to write history data to
HISTORY_PATH = os.path.join(APP_PATH, 'history.json')
-# path to file in which the Oauth access token for connecting to dropbox is stored
+# Path to file in which the OAuth access token for connecting to Dropbox is stored
TOKEN_PATH = os.path.join(APP_PATH, 'token.json')
GITHUB_TOKEN_PATH = os.path.join(APP_PATH, 'github_token.json')
-# services to send the link to the hosted file to
+# Services to send the link to the hosted file to
SHARING_SERVICES = 'clipboard facebook twitter email stdout'.split(' ')
-# default message when shared to a social network
+# Default message when shared to a social network
SHARE_MESSAGE = 'I just uploaded a file to ClipCloud - check it out.'
-# urls of the various services
+# URLs of the various sharing services
URLS = {
'twitter': "https://twitter.com/intent/tweet?text=%s&url=%s",
'facebook': "http://www.facebook.com/sharer.php?u=%s&t=%s",

0 comments on commit 222121f

Please sign in to comment.