Add a few docstrings, remove getpermission.py.

voussoirkit/betterhelp.py

@@ -11,6 +11,11 @@ HELPSTRINGS = {'', 'help', '-h', '--help'}
 # INTERNALS
 ################################################################################
 def can_use_bare(parser):
+    '''
+    Return true if the given parser has no required arguments, ie can run bare.
+    This is used to decide whether running `> myprogram.py` should show the
+    helptext or just run normally.
+    '''
     def is_required(action):
         # I found that positional arguments marked with nargs=* were still being
         # considered 'required', which is not what I want as far as can_use_bare
@@ -25,6 +30,9 @@ def can_use_bare(parser):
     return has_func and not has_required_args
 
 def can_use_bare_subparsers(subparser_action):
+    '''
+    Return a set of subparser names which can be used bare.
+    '''
     can_bares = set(
         sp_name for (sp_name, sp) in subparser_action.choices.items()
         if can_use_bare(sp)

voussoirkit/bytestring.py

@@ -1,3 +1,7 @@
+'''
+This module provides integer constants for power-of-two byte size units, and
+functions for converting between ints and human-readable strings e.g. "1.2 GiB".
+'''
 import re
 import sys
 

voussoirkit/fusker.py

@@ -1,3 +1,25 @@
+'''
+Fusking is the act of generating many strings by using a template with a range
+of integers or a spinner of alternate strings.
+
+Ranges:
+    x[1-10]y -> x1y, x2y, x3y, x4y, x5y, x6y, x7y, x8y, x9y, x10y
+    x[01-10]y -> x01y, x02y, x03y, x04y, x05y, x06y, x07y, x08y, x09y, x10y
+
+Spinners:
+    x{alpha|beta|charlie}y -> xalphay, xbetay, xcharliey
+
+fusker.fusker('https://subdomain-{a|b|c}.website.com/image[01-99].jpg') ->
+(
+    'https://subdomain-a.website.com/image01.jpg',
+    'https://subdomain-a.website.com/image02.jpg',
+    'https://subdomain-a.website.com/image03.jpg',
+    ...
+    'https://subdomain-a.website.com/image99.jpg',
+    'https://subdomain-b.website.com/image01.jpg',
+    'https://subdomain-b.website.com/image02.jpg',
+)
+'''
 import collections
 import itertools
 import string

voussoirkit/getpermission.py

@@ -1,5 +0,0 @@
-import warnings
-warnings.warn('Please switch to voussoirkit.interactive.getpermission')
-
-from voussoirkit import interactive
-getpermission = interactive.getpermission

voussoirkit/interactive.py

@@ -1,3 +1,6 @@
+'''
+This module provides functions for interactive command line UIs.
+'''
 ####################################################################################################
 ## ABC_CHOOSER #####################################################################################
 ####################################################################################################