From f53569cadcee045555b0b08ff3f39891e6b218cc Mon Sep 17 00:00:00 2001 From: ronny abraham Date: Sat, 8 Jul 2023 21:26:24 +0300 Subject: [PATCH] modified a bunch of docstrings and fixed up the arguments for ensure_dir and ensure_file --- docs | 2 +- modules/utils.py | 168 +++++++++++++++++++++++++++++++++++------------ 2 files changed, 127 insertions(+), 43 deletions(-) diff --git a/docs b/docs index 697af1a..08a9039 160000 --- a/docs +++ b/docs @@ -1 +1 @@ -Subproject commit 697af1a3153808dbffd87c415b9619ea59788696 +Subproject commit 08a9039d75dbf22afa0b8f02cef9d263fedf6e73 diff --git a/modules/utils.py b/modules/utils.py index 9c5c4fd..1d86080 100644 --- a/modules/utils.py +++ b/modules/utils.py @@ -11,18 +11,38 @@ from fabric.operations import run, sudo def printvar(name, value, exit=False): + """ + debug helper method to print a variable from within a process + + :parameter name: name of the variable we are printing out + :type name: string + + :parameter value: the value of the variable we want to print + :type value: string + + :parameter exit: determines whether or not we exit the program at + this point. defaults to false + :type exit: boolean + """ print("%s : %s" % (name, value)) if exit: sys.exit() def printerr(message="", errcode=-2, exit=True): - """ prints error message and error code then exits + """ + debug helper method thats prints error message and error code then exits - Keyword Arguments: - message -- error message - errcode -- the error code - exit -- if we do a sys.exit + :parameter message: the error message we want to print out. + defaults to empty string. + :type message: string + + :parameter errcode: the code of the error + :type errcode: integer + + :parameter exit: determines whether or not we exit the program at + this point. defaults to True + :type exit: boolean """ message = "Error\n\t{message}\n\tExiting with code: {errcode}\n".format( @@ -40,11 +60,17 @@ def loggify(module, func, prefix=""): decided to just dump it here, and return a logger that can be used and thrown away when it's done - module - name of the module being used, ie 'nginx', 'deploy', etc - func - the name of the function this logger is going to be used in - prefix - anything you want to add to the front of the logger, ie '\n' + :parameter module: name of the module being used, ie 'nginx', 'deploy', etc + :type module: string - returns a logging object + :parameter func: the name of the function this logger is going to be used + in + :type func: string + + :parameter prefix: anything you want to add to the front of the logger, + ie \'\\n\'. defaults to an empty string. + :type prefix: string + :rtype: logging object """ loggername = '{module}.{func}'.format( @@ -66,12 +92,21 @@ def print_console(string, prepend="\n\n", append="\n\n", sep="-", numsep=44): helper function to take a string, and format it so it prints to the console in a way that is pleasing to the eye. - string - the string to be printed - prepend - defaults to two line spaces, can be anything - append - defaults to two lines spaces after the string is printed - sep - the character used to print out one line above the string and - one line after - numsep - number of times the separator is printed out on a line + :parameter string: the string to be printed + :type string: string + + :parameter prepend: defaults to two line spaces, can be anything + :type string: string + + :parameter append: defaults to two lines spaces after the string is printed + :type append: string + + :parameter sep: the character used to print out one line above the string + and one line after + :type sep: character + + :parameter numsep: number of times the separator is printed out on a line + :type numsep: integer """ print(prepend) @@ -88,30 +123,48 @@ def print_console(string, prepend="\n\n", append="\n\n", sep="-", numsep=44): def print_debug(debugstr, module, function): + """ + debug helper method to print out a debug string, the name of the module, + and the function it is located in. + + The message will be printed out in the form :: + + :parameter debugstr: the debugging message we want to print + :type debugstr: string + + :parameter module: the name of the module we are in + :type module: string + + :parameter function: the name of the function we are in + :type function: + """ + print("%s:%s:%s" % (module, function, debugstr)) -def executize(config_execute): +def executize(config_execute='local'): """ - A couple of times using fabric I've found that I'll need to switch between - sudo, run or local depending on where I'm executing the function, because - repeating this code in every funcion that needs it can be straingint on the - eyes, I'm putting it here for use. + creates an executor to run commands. returns one of the following methods + fabric.api.local, fabric.operations.run or fabric.operations.sudo - config_execute - a string that can represent the value of 'sudo', - 'run', or 'local' + :parameter config_execute: values can be either 'sudo', 'run', or 'local'. + defaults to 'local'. + :type config_execute: string - return the fabric command corresponding to the string value - in config_execute + :return: the fabric command corresponding to the string value + in config_execute, either a sudo, a run or a local executor """ - _execute = local if config_execute == 'sudo': _execute = sudo elif config_execute == 'run': _execute = run elif config_execute == 'local': _execute = local + else: + errmsg = "did not enter a correct value of 'sudo', 'run' or" \ + " 'local' to executize.\nExiting." + printerr(message=errmsg, errcode=-2) return _execute @@ -120,8 +173,16 @@ def booleanize(value): """ take the argument and return it as either True or False - if the argument is neither, return False by default and warn the user that - there is a problem + if the argument is neither, throw a TypeError explaining that the value + given cannot be booleanized + + :parameter value: takes values of y, n, yes, no, true, false, + 1 or 0 + :type value: string + + :return: converts value to True or False. Note 1 is + considered True and 0 is False + :rtype: boolean """ true_values = ("y", "yes", "true", "1") @@ -139,28 +200,38 @@ def booleanize(value): raise TypeError("Cannot booleanize ambiguous value '%s'" % value) -def ensure_dir(directory): +def ensure_dir(dirpath): """ - Create a directory if it's not exists + Create a directory if it does not exists. + + Raises an OSError if there is a problem + + :parameter dirpath: directory path + :type dirpath: string + """ try: - if not os.path.exists(directory): - print("creating directory: %s" % directory) - os.makedirs(directory) + if not os.path.exists(dirpath): + print("creating directory: %s" % dirpath) + os.makedirs(dirpath) except OSError as e: if e.errno != errno.EEXIST: print("Error occurred while creating directory: %s" - % directory) + % dirpath) raise -def ensure_file(f): +def ensure_file(filepath): """ Simulates linux 'touch' command + + :parameter filepath: name of the file we want to create. Note this + must include the full path and filename + :type filepath: string """ - if not os.path.exists(f): - open(f, 'w').close() + if not os.path.exists(filepath): + open(filepath, 'w').close() def upload_template(filename, destination, context, use_jinja, @@ -277,9 +348,11 @@ def generate_template_files_path(section): """ 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 + :type section: string - returns a path to where the template jinja file is located + :return: a path to where the template jinja file is located + :rtype: string """ import os @@ -296,12 +369,23 @@ def generate_template_files_path(section): def print_run(command, prefix="\"\n\t", suffix="\n\t\""): """ - helper function for when I want a string that has the form + helper function to print out what a command will actually look like when + run - "\n\t run(some_command_string) \t\n" + :parameter command: a typical bash command that I want to run + :type command: string - where "somce_command_string" is a bash script commmand or something like - that + :parameter prefix: prefix that is added to the string, typically done + for clarity of viewing + :type prefix: string + + :parameter suffix: suffix that is added to the string, typically done + for clarity of viewing + :type suffix: string + + :returns: an example of how the command will actually look if run + on the command line + :rtype: string """ return "run ({prefix}{command}{suffix})".format(