docs(utils): add docstrings

Signed-off-by: Dominik Willner <th33xitus@gmail.com>

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"

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
 
 

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")

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"

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)

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: