diff --git a/docs/developer/management_script_helpers.md b/docs/developer/management_script_helpers.md index fd1a82839..609015ad6 100644 --- a/docs/developer/management_script_helpers.md +++ b/docs/developer/management_script_helpers.md @@ -1,10 +1,12 @@ # Terminal Helper Functions -`terminal_helper.py` contains utility functions to assist with common terminal and script operations. +`terminal_helper.py` contains utility functions to assist with common terminal and script operations. +This file documents what they do and provides guidance on their usage. ## TerminalColors -`TerminalColors` provides ANSI color codes as variables to style terminal output. Example usage: +`TerminalColors` provides ANSI color codes as variables to style terminal output. -print(f"{TerminalColors.OKGREEN}Success!{TerminalColors.ENDC}") +Usage: +```print(f"{TerminalColors.OKGREEN}Success!{TerminalColors.ENDC}")``` ## ScriptDataHelper ### bulk_update_fields @@ -12,7 +14,72 @@ print(f"{TerminalColors.OKGREEN}Success!{TerminalColors.ENDC}") `bulk_update_fields` performs a memory-efficient bulk update on a Django model in batches using a Paginator. Usage: -bulk_update_fields(Domain, page.object_list, ["first_ready"]) +```bulk_update_fields(Domain, object_list, ["first_ready"])``` + +## TerminalHelper +### log_script_run_summary + +`log_script_run_summary` logs a summary of a script run, including counts of updated, skipped, and failed records. + +Usage: +```TerminalHelper.log_script_run_summary(self.to_update, self.failed_to_update, self.skipped, debug)``` + +### print_conditional + +`print_conditional` conditionally logs a statement at a specified severity if a condition is met. + +Usage: +```python +TerminalHelper.print_conditional( + debug_on, + f"""{TerminalColors.YELLOW}Missing Domain Information + {TerminalColors.ENDC}""", +) +``` + +### prompt_for_execution + +`prompt_for_execution` prompts the user to inspect a string and confirm if they wish to proceed. Returns True if proceeding, False if skipping, or exits the script. + +```python +TerminalHelper.prompt_for_execution( + system_exit_on_terminate=True, + info_to_inspect=f""" + ==Master data file== + domain_additional_filename: {org_args.domain_additional_filename} + + ==Organization data== + organization_adhoc_filename: {org_args.organization_adhoc_filename} + + ==Containing directory== + directory: {org_args.directory} + """, + prompt_title="Do you wish to load organization data for TransitionDomains?", +) +``` + +### query_yes_no + +`query_yes_no` prompts the user with a yes/no question and returns True for "yes" or False for "no". + +Usage: +```python +if query_yes_no("Do you want to proceed?"): + print("Proceeding...") +else: + print("Aborting.") +``` + +### query_yes_no_exit + +`query_yes_no_exit` is similar to `query_yes_no` but includes an "exit" option to terminate the script. + +Usage: +if query_yes_no_exit("Continue, abort, or exit?"): + print("Continuing...") +else: + print("Aborting.") + # Script will exit if user selected "e" for exit ## PopulateScriptTemplate @@ -42,67 +109,4 @@ To create a script using `PopulateScriptTemplate`: 1. Create a new class that inherits from `PopulateScriptTemplate` 2. Implement the `update_record` method to define how each record should be updated 3. Optionally, override the configuration variables and helper methods as needed -4. Call `mass_update_records` within `handle` and run the script - -## TerminalHelper -### log_script_run_summary - -`log_script_run_summary` logs a summary of a script run, including counts of updated, skipped, and failed records. - -### print_conditional - -`print_conditional` conditionally logs a statement at a specified severity if a condition is met. - -### prompt_for_execution - -`prompt_for_execution` prompts the user to inspect a string and confirm if they wish to proceed. Returns True if proceeding, False if skipping, or exits the script. - -### get_file_line_count - -`get_file_line_count` returns the number of lines in a file. - -### print_to_file_conditional - -`print_to_file_conditional` conditionally writes content to a file if a condition is met. - -Refer to the source code for full function signatures and additional details. - -### query_yes_no - -`query_yes_no` prompts the user with a yes/no question and returns True for "yes" or False for "no". - -Usage: -```python -if query_yes_no("Do you want to proceed?"): - print("Proceeding...") -else: - print("Aborting.") -``` - -### query_yes_no_exit - -`query_yes_no_exit` is similar to `query_yes_no` but includes an "exit" option to terminate the script. - -Usage: -if query_yes_no_exit("Continue, abort, or exit?"): - print("Continuing...") -else: - print("Aborting.") - # Script will exit if user selected "e" for exit - -### array_as_string - -`array_as_string` converts a list of strings into a single string with each element on a new line. - -Usage: -```python -my_list = ["apple", "banana", "cherry"] -print(array_as_string(my_list)) -``` - -Output: -``` -apple -banana -cherry -``` +4. Call `mass_update_records` within `handle` and run the script \ No newline at end of file