From 9a1a66aa64bc2359724ebd842ccf767187c044de Mon Sep 17 00:00:00 2001 From: dw-0 Date: Mon, 4 Dec 2023 21:33:35 +0100 Subject: [PATCH] docs(utils): add docstrings Signed-off-by: Dominik Willner --- kiauh/__init__.py | 2 + kiauh/core/backup_manager/backup_manager.py | 2 +- kiauh/utils/common.py | 2 +- kiauh/utils/constants.py | 3 -- kiauh/utils/input_utils.py | 44 +++++++++++++++++++++ kiauh/utils/system_utils.py | 9 ++++- 6 files changed, 55 insertions(+), 7 deletions(-) diff --git a/kiauh/__init__.py b/kiauh/__init__.py index 662cd28..8fc1d9a 100644 --- a/kiauh/__init__.py +++ b/kiauh/__init__.py @@ -10,6 +10,8 @@ # ======================================================================= # from os.path import join, dirname, abspath +from pathlib import Path APPLICATION_ROOT = dirname(dirname(abspath(__file__))) KIAUH_CFG = join(APPLICATION_ROOT, "kiauh.cfg") +KIAUH_BACKUP_DIR = f"{Path.home()}/kiauh-backups" diff --git a/kiauh/core/backup_manager/backup_manager.py b/kiauh/core/backup_manager/backup_manager.py index ee6b782..db82162 100644 --- a/kiauh/core/backup_manager/backup_manager.py +++ b/kiauh/core/backup_manager/backup_manager.py @@ -12,8 +12,8 @@ import shutil from pathlib import Path +from kiauh import KIAUH_BACKUP_DIR from kiauh.utils.common import get_current_date -from kiauh.utils.constants import KIAUH_BACKUP_DIR from kiauh.utils.logger import Logger diff --git a/kiauh/utils/common.py b/kiauh/utils/common.py index 4b6a48a..b6a8e87 100644 --- a/kiauh/utils/common.py +++ b/kiauh/utils/common.py @@ -16,7 +16,7 @@ from typing import Dict, Literal def get_current_date() -> Dict[Literal["date", "time"], str]: """ Get the current date | - :return: a Dict holding a date and time key:value pair + :return: Dict holding a date and time key:value pair """ now: datetime = datetime.today() date: str = now.strftime("%Y-%m-%d") diff --git a/kiauh/utils/constants.py b/kiauh/utils/constants.py index 37d4a33..66b00ff 100644 --- a/kiauh/utils/constants.py +++ b/kiauh/utils/constants.py @@ -11,7 +11,6 @@ import os import pwd -from pathlib import Path # text colors and formats COLOR_WHITE = "\033[37m" # white @@ -21,8 +20,6 @@ COLOR_YELLOW = "\033[93m" # bright yellow COLOR_RED = "\033[91m" # bright red COLOR_CYAN = "\033[96m" # bright cyan RESET_FORMAT = "\033[0m" # reset format -# kiauh -KIAUH_BACKUP_DIR = f"{Path.home()}/kiauh-backups" # current user CURRENT_USER = pwd.getpwuid(os.getuid())[0] SYSTEMD = "/etc/systemd/system" diff --git a/kiauh/utils/input_utils.py b/kiauh/utils/input_utils.py index dcddda0..7f9f1f5 100644 --- a/kiauh/utils/input_utils.py +++ b/kiauh/utils/input_utils.py @@ -19,6 +19,13 @@ from kiauh.utils.logger import Logger def get_confirm( question: str, default_choice=True, allow_go_back=False ) -> Union[bool, None]: + """ + Helper method for validating confirmation (yes/no) user input. | + :param question: The question to display + :param default_choice: A default if input was submitted without input + :param allow_go_back: Navigate back to a previous dialog + :return: Either True or False, or None on go_back + """ options_confirm = ["y", "yes"] options_decline = ["n", "no"] options_go_back = ["b", "B"] @@ -48,6 +55,15 @@ def get_confirm( def get_number_input( question: str, min_count: int, max_count=None, default=None, allow_go_back=False ) -> Union[int, None]: + """ + Helper method to get a number input from the user + :param question: The question to display + :param min_count: The lowest allowed value + :param max_count: The highest allowed value (or None) + :param default: Optional default value + :param allow_go_back: Navigate back to a previous dialog + :return: Either the validated number input, or None on go_back + """ options_go_back = ["b", "B"] _question = format_question(question, default) while True: @@ -65,6 +81,13 @@ def get_number_input( def get_string_input(question: str, exclude=Optional[List], default=None) -> str: + """ + Helper method to get a string input from the user + :param question: The question to display + :param exclude: List of strings which are not allowed + :param default: Optional default value + :return: The validated string value + """ while True: _input = input(format_question(question, default)).strip() @@ -77,6 +100,13 @@ def get_string_input(question: str, exclude=Optional[List], default=None) -> str def get_selection_input(question: str, option_list: List, default=None) -> str: + """ + Helper method to get a selection from a list of options from the user + :param question: The question to display + :param option_list: The list of options the user can select from + :param default: Optional default value + :return: The option that was selected by the user + """ while True: _input = input(format_question(question, default)).strip() @@ -87,6 +117,12 @@ def get_selection_input(question: str, option_list: List, default=None) -> str: def format_question(question: str, default=None) -> str: + """ + Helper method to have a standardized formatting of questions | + :param question: The question to display + :param default: If defined, the default option will be displayed to the user + :return: The formatted question string + """ formatted_q = question if default is not None: formatted_q += f" (default={default})" @@ -95,6 +131,14 @@ def format_question(question: str, default=None) -> str: def validate_number_input(value: str, min_count: int, max_count: int) -> int: + """ + Helper method for a simple number input validation. | + :param value: The value to validate + :param min_count: The lowest allowed value + :param max_count: The highest allowed value (or None) + :return: The validated value as Integer + :raises: ValueError if value is invalid + """ if max_count is not None: if min_count <= int(value) <= max_count: return int(value) diff --git a/kiauh/utils/system_utils.py b/kiauh/utils/system_utils.py index ec1026e..34a2985 100644 --- a/kiauh/utils/system_utils.py +++ b/kiauh/utils/system_utils.py @@ -40,7 +40,7 @@ def parse_packages_from_file(source_file: Path) -> List[str]: Read the package names from bash scripts, when defined like: PKGLIST="package1 package2 package3" | :param source_file: path of the sourcefile to read from - :return: a list of package names + :return: A list of package names """ packages = [] @@ -169,7 +169,7 @@ def update_system_package_lists(silent: bool, rls_info_change=False) -> None: kill(f"Error updating system package list:\n{e.stderr.decode()}") -def install_system_packages(packages: List) -> None: +def install_system_packages(packages: List[str]) -> None: """ Installs a list of system packages | :param packages: List of system package names @@ -234,6 +234,11 @@ def check_file_exists(file_path: Path) -> bool: # this feels hacky and not quite right, but for now it works # see: https://stackoverflow.com/questions/166506/finding-local-ip-addresses-using-pythons-stdlib def get_ipv4_addr() -> str: + """ + Helper function that returns the IPv4 of the current machine + by opening a socket and sending a package to an arbitrary IP. | + :return: Local IPv4 of the current machine + """ s = socket.socket(socket.AF_INET, socket.SOCK_DGRAM) s.settimeout(0) try: