refactored utils.handle_help to have better docstrings and renamed to be acalled handle_flag_message

modules/django.py

@@ -15,7 +15,7 @@ try:
     from customfabric.modules.utils import loggify, print_run, booleanize
     from customfabric.modules.utils import generate_template_build_path
     from customfabric.modules.utils import generate_template_files_path
-    from customfabric.modules.utils import handle_help
+    from customfabric.modules.utils import handle_flag_message
     from customfabric.modules.utils import prompt_continue
 
 except ImportError:
@@ -25,7 +25,7 @@ except ImportError:
 # from .utils import loggify, print_run, booleanize
 # from .utils import generate_template_build_path
 # from .utils import generate_template_files_path
-# from .utils import handle_help
+# from .utils import handle_flag_message
 # from .utils import prompt_continue
 #
 # import os
@@ -315,7 +315,7 @@ def startapp(appname='help'):
 
     import sys
 
-    if handle_help(appname, msg_help, 'help'):
+    if handle_flag_message(appname, msg_help, 'help'):
         sys.exit()
 
     command = "startapp {appname}".format(

modules/pip.py

@@ -159,9 +159,9 @@ def freeze(param='help'):
     \tFalse (default) - print the freeze output to the console
     """
 
-    from .utils import booleanize, handle_help
+    from .utils import booleanize, handle_flag_message
 
-    if handle_help(param, msg_help, 'help'):
+    if handle_flag_message(param, msg_help, 'help'):
         sys.exit()
     else:
         try:

modules/utils.py

@@ -236,6 +236,46 @@ def ensure_file(filepath):
 
 def upload_template(filename, destination, context, use_jinja,
                     use_sudo, backup, template_dir, debug=False):
+    """
+    helper wrapper method to upload a template
+
+    it wraps around fabric.contrib.files.upload_template method.
+    See https://docs.fabfile.org/en/1.11/api/contrib/files.html
+
+    :parameter filename: the full path to the filename if we are not
+        using jinja, otherwise using template_dir and just the filename
+        this file will be interpolated using the given context and
+        uploaded to the remote host
+    :type filename: string
+
+    :parameter destination: remote file path to place the file
+        (includes filename)
+    :type destination: string
+
+    :parameter context: variable context
+    :type context: dict
+
+    :parameter use_jinja: whether we are using jinja template system or not.
+        Templates will be loaded from the invoking users' current working
+        directory or by template_dir
+    :type use_jinja: boolean
+
+    :parameter use_sudo: whether we are using sudo to place the file.
+        By default the file will be copied as the logged in user
+    :type use_sudo: boolean
+
+    :parameter backup: if the destination file already exists, create a backup
+        of it with the extension .bak
+    :type backup: boolean
+
+    :parameter template_dir: path to the template directory that is used if
+        jinja is true.  directory where the file is located
+    :type template_dir: string
+
+    :parameter debug: if true, just print out the command we are using to
+        invoke the fabric upload_template method. defaults to False
+    :type debug: boolean
+    """
 
     if env.debug:
         logging.basicConfig(
@@ -322,11 +362,15 @@ def generate_template_build_path(section, template_name='conf'):
     """
     helper function to automate creation of build path
 
-    section - the template section we are building off of
+    :parameter section: the template section we are building off of
-    template_name - by default this is "conf", but can be different, for
+    :type section: string
-    example, the 'database' section has 3 different template names
 
-    returns a path to where the template should be placed
+    :parameter template_name: by default this is "conf", but can be
+        different, for example, the 'database' section has 3 different
+        template names
+    :type template_name: string
+
+    :return: a path to where the template should be placed
     """
     import os
 
@@ -394,12 +438,25 @@ def print_run(command, prefix="\"\n\t", suffix="\n\t\""):
         command=command)
 
 
-def handle_help(param, message, values=None):
+def handle_flag_message(param, message, values=['-h', '--help']):
+    """
+    if a given parameter is in the given values
+    then return the given message
 
-    values_default = ['-h', '--help']
+    :parameter param: checks if the given parameter is in
+        the values.
+    :type param: string
 
-    if values is None:
+    :parameter message: the message to print out if true
-        values = values_default
+    :type message: string
+
+    :parameter values: the values we are checking to see.
+        by default this is ['-h', '--help']
+    :type values: list
+
+    :return: whether the given param is in values
+    :rtype: boolean
+    """
 
     if isinstance(param, str):
         if param.lower() in values:
@@ -410,6 +467,15 @@ def handle_help(param, message, values=None):
 
 
 def is_help(key):
+    """
+    helper method to determine if the given key is a help key
+
+    :parameter key: the key we are checking
+    :type key: string
+
+    :return: if key is in -h or --help
+    :rtype: boolean
+    """
     help_keys = ['-h', '--help']
 
     return key in help_keys