From e218dc827c104ea4006a4afb9274c15043302eb4 Mon Sep 17 00:00:00 2001 From: ronny abraham Date: Sun, 9 Jul 2023 21:11:13 +0300 Subject: [PATCH] changed the types in docstrings --- docs | 2 +- modules/django.py | 44 ++++++++++++++++---- modules/utils.py | 100 +++++++++++++++++++++++----------------------- 3 files changed, 89 insertions(+), 57 deletions(-) diff --git a/docs b/docs index 08a9039..e48bd91 160000 --- a/docs +++ b/docs @@ -1 +1 @@ -Subproject commit 08a9039d75dbf22afa0b8f02cef9d263fedf6e73 +Subproject commit e48bd91c6b0e763b919ec49b73f1c3bf82bf815d diff --git a/modules/django.py b/modules/django.py index 66c4195..bfe3de7 100644 --- a/modules/django.py +++ b/modules/django.py @@ -62,6 +62,15 @@ def test(args=None): def commandline(args="", workingdir=None): """ prints out what you need to run on the command line to invoke manage.py + + :parameter args: the arguments you would normally say the django.manage. + defaults to empty string + :type args: str + + :parameter workingdir: the working directory of the manage.py script. + defaults to None, which means it uses the working directory that are + given in the project settings + :type workingdir: str """ configuration = env.config @@ -84,6 +93,27 @@ def commandline(args="", workingdir=None): @task def manage(args="help", workingdir=None, prefix="", suffix=""): + """ + wrapper method for the django manage.py command, takes values given + and runs it using the project settings. It automatically applies + the correct virtualenvwrapper for this project, sets the correct python + path, and locates the correct settings file + + :parameter args: usually the argument that manage.py will take. + defaults to 'help' + :type args: str + + :parameter workingdir: the working directory of the manage.py script. + defaults to None, which means it uses the working directory that are + given in the project settings + :type workingdir: str + + :param prefix: any bash commands we'd want to place before manage.py + :type prefix: str + + :param suffix: any bash commands we'd want to place after manage.py + :type suffix: str + """ configuration = env.config # changes the working directory to the djangoroot @@ -178,34 +208,34 @@ def coverage(application, args="test", workingdir=None, outputdir=None, :parameter application: the name of the installed application being tested. NOTE: this is required because currently I do not know how to run manage.py test on all installed applications. - :type application: string + :type application: str :parameter args: the manage command that coverage is going to run. defaults to test - :type args: string + :type args: str :parameter workingdir: the working directory that manage will run it's command under. defaults to None - :type workingdir: string + :type workingdir: str :parameter outputdir: the directory to which file results will be output to. defaults to None - :type outputdir: string + :type outputdir: str :parameter coveragerc: flags whether or not there is a coverage settings file which determines what coverage will or wont do. coveragerc file is located in share/coverage/setup.cfg you can modify this in the virtualenv settings for this branch. defaults to True - :type coveragerc: boolean + :type coveragerc: bool :parameter report: flags whether or not coverage will be asked to generate a report. defaults to true. - :type report: boolean + :type report: bool :parameter html: flags whether or not coverage will generate an html version of its report. defaults to true - :type html: boolean + :type html: bool TODO: test if coverage is installed and if it isn't give an error explaining diff --git a/modules/utils.py b/modules/utils.py index 7164d58..265e43e 100644 --- a/modules/utils.py +++ b/modules/utils.py @@ -15,14 +15,14 @@ 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 + :type name: str :parameter value: the value of the variable we want to print - :type value: string + :type value: str :parameter exit: determines whether or not we exit the program at this point. defaults to false - :type exit: boolean + :type exit: bool """ print("%s : %s" % (name, value)) if exit: @@ -35,14 +35,14 @@ def printerr(message="", errcode=-2, exit=True): :parameter message: the error message we want to print out. defaults to empty string. - :type message: string + :type message: str :parameter errcode: the code of the error - :type errcode: integer + :type errcode: int :parameter exit: determines whether or not we exit the program at this point. defaults to True - :type exit: boolean + :type exit: bool """ message = "Error\n\t{message}\n\tExiting with code: {errcode}\n".format( @@ -61,16 +61,18 @@ def loggify(module, func, prefix=""): thrown away when it's done :parameter module: name of the module being used, ie 'nginx', 'deploy', etc - :type module: string + :type module: str :parameter func: the name of the function this logger is going to be used in - :type func: string + :type func: str :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 + :type prefix: str + + :return: a logging object + :rtype: object """ loggername = '{module}.{func}'.format( @@ -93,20 +95,20 @@ def print_console(string, prepend="\n\n", append="\n\n", sep="-", numsep=44): in a way that is pleasing to the eye. :parameter string: the string to be printed - :type string: string + :type string: str :parameter prepend: defaults to two line spaces, can be anything - :type string: string + :type string: str :parameter append: defaults to two lines spaces after the string is printed - :type append: string + :type append: str :parameter sep: the character used to print out one line above the string and one line after - :type sep: character + :type sep: str :parameter numsep: number of times the separator is printed out on a line - :type numsep: integer + :type numsep: int """ print(prepend) @@ -130,10 +132,10 @@ def print_debug(debugstr, module, function): The message will be printed out in the form :: :parameter debugstr: the debugging message we want to print - :type debugstr: string + :type debugstr: str :parameter module: the name of the module we are in - :type module: string + :type module: str :parameter function: the name of the function we are in :type function: @@ -149,7 +151,7 @@ def executize(config_execute='local'): :parameter config_execute: values can be either 'sudo', 'run', or 'local'. defaults to 'local'. - :type config_execute: string + :type config_execute: str :return: the fabric command corresponding to the string value in config_execute, either a sudo, a run or a local executor @@ -178,11 +180,11 @@ def booleanize(value): :parameter value: takes values of y, n, yes, no, true, false, 1 or 0 - :type value: string + :type value: str :return: converts value to True or False. Note 1 is considered True and 0 is False - :rtype: boolean + :rtype: bool """ true_values = ("y", "yes", "true", "1") @@ -207,7 +209,7 @@ def ensure_dir(dirpath): Raises an OSError if there is a problem :parameter dirpath: directory path - :type dirpath: string + :type dirpath: str """ try: @@ -228,7 +230,7 @@ def ensure_file(filepath): :parameter filepath: name of the file we want to create. Note this must include the full path and filename - :type filepath: string + :type filepath: str """ if not os.path.exists(filepath): open(filepath, 'w').close() @@ -246,11 +248,11 @@ def upload_template(filename, destination, context, use_jinja, 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 + :type filename: str :parameter destination: remote file path to place the file (includes filename) - :type destination: string + :type destination: str :parameter context: variable context :type context: dict @@ -258,23 +260,23 @@ def upload_template(filename, destination, context, use_jinja, :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 + :type use_jinja: bool :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 + :type use_sudo: bool :parameter backup: if the destination file already exists, create a backup of it with the extension .bak - :type backup: boolean + :type backup: bool :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 + :type template_dir: str :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 + :type debug: bool """ if env.debug: @@ -373,12 +375,12 @@ def generate_template_build_path(section, template_name='conf'): helper function to automate creation of build path :parameter section: the template section we are building off of - :type section: string + :type section: str :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 + :type template_name: str :return: a path to where the template should be placed """ @@ -403,10 +405,10 @@ def generate_template_files_path(section): helper function to automate creation of build path :parameter section: the template section we are building off of - :type section: string + :type section: str :return: a path to where the template jinja file is located - :rtype: string + :rtype: str """ import os @@ -427,19 +429,19 @@ def print_run(command, prefix="\"\n\t", suffix="\n\t\""): run :parameter command: a typical bash command that I want to run - :type command: string + :type command: str :parameter prefix: prefix that is added to the string, typically done for clarity of viewing - :type prefix: string + :type prefix: str :parameter suffix: suffix that is added to the string, typically done for clarity of viewing - :type suffix: string + :type suffix: str :returns: an example of how the command will actually look if run on the command line - :rtype: string + :rtype: str """ return "run ({prefix}{command}{suffix})".format( @@ -455,17 +457,17 @@ def handle_flag_message(param, message, values=['-h', '--help']): :parameter param: checks if the given parameter is in the values. - :type param: string + :type param: str :parameter message: the message to print out if true - :type message: string + :type message: str :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 + :rtype: bool """ if isinstance(param, str): @@ -481,10 +483,10 @@ 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 + :type key: str :return: if key is in -h or --help - :rtype: boolean + :rtype: bool """ help_keys = ['-h', '--help'] @@ -500,13 +502,13 @@ def link_create(path_src, path_dst, debug=False): Otherwise sys.exit with an error message. :parameter path_src: source path - :type path_src: string + :type path_src: str :paramter path_dst: destination path - :type path_dst: string + :type path_dst: str :parameter debug: whether we do nothing and just return a message - :type debug: boolean + :type debug: bool :return: if debug=True then it returns a msg """ @@ -553,14 +555,14 @@ def prompt_continue(message="Do you want to continue? Y/n", default="Y", prompts user if he wants to continue :parameter message: ask if user wants to continue - :type message: string + :type message: str :parameter default: the default entry that we expect for the user if he hits enter without giving a value - :type default: string + :type default: str :parameter exit: whether we do a sys.exit if it fails. default True - :type exit: boolean + :type exit: bool """ from fabric.operations import prompt @@ -592,7 +594,7 @@ def check_debug(env): :type env: dict :return: True if debug was set - :rtype: boolean + :rtype: bool """ if hasattr(env, 'debug'):