From 5d376acf49322c66776cc745402cc65afde75eb1 Mon Sep 17 00:00:00 2001 From: Sven Sager Date: Mon, 21 Apr 2025 14:38:32 +0200 Subject: [PATCH] doc(revpiconfig): Add detailed docstrings to ConfigTxt methods Enhance the `ConfigTxt` class with comprehensive docstrings for all methods, providing clear explanations of their functionality, parameters, and return values. This improves code readability and facilitates easier maintenance and understanding for future developers. --- .../system_config/revpi_config.py | 132 ++++++++++++++++++ 1 file changed, 132 insertions(+) diff --git a/src/revpi_middleware/dbus_middleware1/system_config/revpi_config.py b/src/revpi_middleware/dbus_middleware1/system_config/revpi_config.py index 23d6378..a615c9f 100644 --- a/src/revpi_middleware/dbus_middleware1/system_config/revpi_config.py +++ b/src/revpi_middleware/dbus_middleware1/system_config/revpi_config.py @@ -119,6 +119,20 @@ class RevPiConfig: class ConfigTxt: + """ + Configuration file handler for managing 'config.txt'. + + This class provides an interface to read, modify, save, and reload + Raspbian's configuration file `config.txt`. It includes functionalities + to manipulate specific parameters within the configuration and supports + managing dtoverlay and dtparam entries. The primary aim of this class + is to abstract file operations and make modifications user-friendly. + + Attributes: + _config_txt_path (str): The path to the configuration file `config.txt`. + _config_txt_lines (list[str]): Contains all lines of the configuration + file as a list of strings, where each string represents a line. + """ re_name_value = re.compile(r"^\s*(?!#)(?P[^=\s].+?)\s*=\s*(?P\S+)\s*$") def __init__(self): @@ -134,6 +148,24 @@ class ConfigTxt: self._config_txt_lines = [] def _clear_name_values(self, name: str, values: str or list) -> int: + """ + Removes all occurrences of specified name-value pairs from the configuration. + + This method searches for all name-value pairs in the configuration and + removes those that match the given name and value(s). It returns the + number of occurrences removed. + + Arguments: + name: str + The name of the configuration variable to search for. + values: str or list + The value or list of values to match the configuration variable + against. + + Returns: + int: The number of name-value pairs removed from the configuration. + + """ counter = 0 if type(values) is str: values = [values] @@ -146,6 +178,21 @@ class ConfigTxt: return counter def _get_all_name_values(self) -> List[ConfigVariable]: + """ + Retrieves all name-value pairs from the configuration text lines. + + This method parses the configuration text lines to extract all name-value + pairs. If the configuration text lines are not loaded, it reloads the + configuration before processing. Each extracted name-value pair is added to a + list as a ConfigVariable object, which also holds the index of the match in + the text lines. The method returns the compiled list of these ConfigVariable + objects. + + Returns: + List[ConfigVariable]: A list of ConfigVariable objects representing the + name-value pairs found in the configuration text lines, along with their + corresponding indexes. + """ if not self._config_txt_lines: self.reload_config() @@ -159,10 +206,28 @@ class ConfigTxt: return lst_return def reload_config(self): + """ + Reloads the configuration file and updates the list of configuration lines. + + This method reads the content of the configuration file specified by the + attribute `_config_txt_path` and updates `_config_txt_lines` with the file + contents as a list of strings, where each string represents a line. + + Returns: + None + """ with open(self._config_txt_path, "r") as f: self._config_txt_lines = f.readlines() def save_config(self): + """ + Saves the current configuration to a file. The method ensures atomicity by first writing + to a temporary file and then moving it to the desired path. After the configuration is + saved, the internal list of configuration lines is cleared. + + Raises: + OSError: If there is an issue writing to or moving the file. + """ if not self._config_txt_lines: return @@ -174,6 +239,20 @@ class ConfigTxt: self._config_txt_lines.clear() def add_name_value(self, name: str, value: str): + """ + Adds a name-value pair to the configuration if it does not already exist. + + This method checks if the given name-value pair is already present in + the configuration. If it is not present, the pair is appended to the + configuration text lines. + + Parameters: + name (str): The name to be added to the configuration. + value (str): The value corresponding to the name to be added. + + Returns: + None + """ # Check weather name and value already exists for config_var in self._get_all_name_values(): if config_var.name == name and config_var.value == value: @@ -182,12 +261,55 @@ class ConfigTxt: self._config_txt_lines.append(f"{name}={value}\n") def clear_dtoverlays(self, dtoverlays: str or list) -> int: + """ + Clears the specified device tree overlays. This method removes one or more + device tree overlays by clearing their corresponding name-value pairs. + + Args: + dtoverlays (str or list): A device tree overlay name as a string, or a + list of such overlay names to be cleared. + + Returns: + int: The number of device tree overlay name-value pairs successfully + cleared. + """ return self._clear_name_values("dtoverlay", dtoverlays) def clear_dtparams(self, dtparams: str or list) -> int: + """ + Clears the specified device tree parameters. + + This method removes the given device tree parameters by utilizing + the underlying `_clear_name_values` function with a predefined + parameter type. + + Parameters: + dtparams: str or list + A string or list of strings specifying the device tree + parameters to remove. + + Returns: + int + The number of parameters cleared. + """ return self._clear_name_values("dtparam", dtparams) def get_values(self, var_name: str) -> list: + """ + Get all values associated with a given variable name. + + This method retrieves a list of values corresponding to the specified + variable name by iterating through a collection of configuration + variables. Each configuration variable is checked for a matching name, + and its value is appended to the resulting list if a match is found. + + Parameters: + var_name (str): The name of the variable for which values are to + be retrieved. + + Returns: + list: A list of values associated with the specified variable name. + """ var_values = [] for config_var in self._get_all_name_values(): @@ -198,6 +320,16 @@ class ConfigTxt: @property def config_txt_path(self) -> str: + """ + Get the file path for the configuration text file. + + This property provides access to the private attribute `_config_txt_path` which + stores the file path to the configuration text file. + + Returns: + str + The file path to the configuration text file. + """ return self._config_txt_path