diff --git a/docs/developer/management_script_helpers.md b/docs/developer/management_script_helpers.md index 609015ad6..104e4dc13 100644 --- a/docs/developer/management_script_helpers.md +++ b/docs/developer/management_script_helpers.md @@ -5,94 +5,47 @@ This file documents what they do and provides guidance on their usage. ## TerminalColors `TerminalColors` provides ANSI color codes as variables to style terminal output. -Usage: -```print(f"{TerminalColors.OKGREEN}Success!{TerminalColors.ENDC}")``` - ## ScriptDataHelper ### bulk_update_fields `bulk_update_fields` performs a memory-efficient bulk update on a Django model in batches using a Paginator. -Usage: -```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 `PopulateScriptTemplate` is an abstract base class that provides a template for creating generic populate scripts. It handles logging and bulk updating for repetitive scripts that update a few fields. -**Disclaimer:** This template is intended as a shorthand for simple scripts. It is not recommended for complex operations. See `transfer_federal_agency.py` for a straightforward example of how to use this template. +### **Disclaimer** +This template is intended as a shorthand for simple scripts. It is not recommended for complex operations. See `transfer_federal_agency.py` for a straightforward example of how to use this template. -To use `PopulateScriptTemplate`, create a new class that inherits from it and implement the `update_record` method. This method defines how each record should be updated. +### Step-by-step usage guide +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 -The class provides the following optional configuration variables: -- `prompt_title`: The header displayed by `prompt_for_execution` when the script starts (default: "Do you wish to proceed?") -- `display_run_summary_items_as_str`: If True, runs `str(item)` on each item when printing the run summary for prettier output (default: False) -- `run_summary_header`: The header for the script run summary printed after the script finishes (default: None) +#### Template explanation The main method provided by `PopulateScriptTemplate` is `mass_update_records`. This method loops through each valid object (specified by `filter_conditions`) and updates the fields defined in `fields_to_update` using the `update_record` method. @@ -100,13 +53,13 @@ Before updating, `mass_update_records` prompts the user to confirm the proposed After processing the records, `mass_update_records` performs a bulk update on the specified fields using `ScriptDataHelper.bulk_update_fields` and logs a summary of the script run using `TerminalHelper.log_script_run_summary`. +#### Config options +The class provides the following optional configuration variables: +- `prompt_title`: The header displayed by `prompt_for_execution` when the script starts (default: "Do you wish to proceed?") +- `display_run_summary_items_as_str`: If True, runs `str(item)` on each item when printing the run summary for prettier output (default: False) +- `run_summary_header`: The header for the script run summary printed after the script finishes (default: None) + The class also provides helper methods: - `get_class_name`: Returns a display-friendly class name for the terminal prompt - `get_failure_message`: Returns the message to display if a record fails to update -- `should_skip_record`: Defines the condition for skipping a record (by default, no records are skipped) - -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 \ No newline at end of file +- `should_skip_record`: Defines the condition for skipping a record (by default, no records are skipped) \ No newline at end of file