adjust docstrings and rename certain internal params to clarify their usage

Author: xulbux

src/xulbux/data.py

@@ -247,8 +247,8 @@ def is_equal(
             ignore_paths = [ignore_paths]
 
         return cls._compare_nested(
-            d1=cls.remove_comments(data1, comment_start, comment_end),
-            d2=cls.remove_comments(data2, comment_start, comment_end),
+            data1=cls.remove_comments(data1, comment_start, comment_end),
+            data2=cls.remove_comments(data2, comment_start, comment_end),
             ignore_paths=[str(path).split(path_sep) for path in ignore_paths if path],
         )
 
@@ -339,14 +339,11 @@ def set_value_by_path_id(cls, data: DataStructure, update_values: dict[str, Any]
         { "1>012": "new value", "1>31": ["new value 1", "new value 2"], ... }
           ```
           The path IDs should have been created using `Data.get_path_id()`."""
-
-        valid_entries = [(path_id, new_val) for path_id, new_val in update_values.items()]
-        if not valid_entries:
+        if not (valid_update_values := [(path_id, new_val) for path_id, new_val in update_values.items()]):
             raise ValueError(f"No valid 'update_values' found in dictionary:\n{update_values!r}")
 
-        for path_id, new_val in valid_entries:
-            path = cls._sep_path_id(path_id)
-            data = cls._set_nested_val(data, path, new_val)
+        for path_id, new_val in valid_update_values:
+            data = cls._set_nested_val(data, id_path=cls._sep_path_id(path_id), value=new_val)
 
         return data
 
@@ -464,33 +461,33 @@ def print(
     @classmethod
     def _compare_nested(
         cls,
-        d1: DataStructure,
-        d2: DataStructure,
+        data1: DataStructure,
+        data2: DataStructure,
         ignore_paths: list[list[str]],
         current_path: list[str] = [],
     ) -> bool:
         if any(current_path == path[:len(current_path)] for path in ignore_paths):
             return True
-        if type(d1) is not type(d2):
+        if type(data1) is not type(data2):
             return False
-        if isinstance(d1, dict) and isinstance(d2, dict):
-            if set(d1.keys()) != set(d2.keys()):
+        if isinstance(data1, dict) and isinstance(data2, dict):
+            if set(data1.keys()) != set(data2.keys()):
                 return False
-            return all(cls._compare_nested(d1[key], d2[key], ignore_paths, current_path + [key]) for key in d1)
-        if isinstance(d1, (list, tuple)):
-            if len(d1) != len(d2):
+            return all(cls._compare_nested(data1[key], data2[key], ignore_paths, current_path + [key]) for key in data1)
+        if isinstance(data1, (list, tuple)):
+            if len(data1) != len(data2):
                 return False
             return all(
                 cls._compare_nested(item1, item2, ignore_paths, current_path + [str(i)])
-                for i, (item1, item2) in enumerate(zip(d1, d2))
+                for i, (item1, item2) in enumerate(zip(data1, data2))
             )
-        if isinstance(d1, (set, frozenset)):
-            return d1 == d2
-        return d1 == d2
+        if isinstance(data1, (set, frozenset)):
+            return data1 == data2
+        return data1 == data2
 
     @staticmethod
     def _sep_path_id(path_id: str) -> list[int]:
-        """Internal method to separate a path ID into its ID parts."""
+        """Internal method to separate a path-ID string into its ID parts as a list of integers."""
         if len(split_id := path_id.split(">")) == 2:
             id_part_len, path_id_parts = split_id
 
@@ -546,23 +543,24 @@ def _get_path_id(path: str, path_sep: str, data_obj: DataStructure, ignore_not_f
         return f"{max_id_length}>{''.join(id.zfill(max_id_length) for id in path_ids)}"
 
     @classmethod
-    def _set_nested_val(cls, data: DataStructure, path: list[int], value: Any) -> DataStructure:
-        if len(path) == 1:
+    def _set_nested_val(cls, data: DataStructure, id_path: list[int], value: Any) -> DataStructure:
+        """Internal method to set a value in a nested data structure based on the provided ID path."""
+        if len(id_path) == 1:
             if isinstance(data, dict):
                 keys, data = list(data.keys()), dict(data)
-                data[keys[path[0]]] = value
+                data[keys[id_path[0]]] = value
             elif isinstance(data, IndexIterableTypes):
                 was_t, data = type(data), list(data)
-                data[path[0]] = value
+                data[id_path[0]] = value
                 data = was_t(data)
 
         else:
             if isinstance(data, dict):
                 keys, data = list(data.keys()), dict(data)
-                data[keys[path[0]]] = cls._set_nested_val(data[keys[path[0]]], path[1:], value)
+                data[keys[id_path[0]]] = cls._set_nested_val(data[keys[id_path[0]]], id_path[1:], value)
             elif isinstance(data, IndexIterableTypes):
                 was_t, data = type(data), list(data)
-                data[path[0]] = cls._set_nested_val(data[path[0]], path[1:], value)
+                data[id_path[0]] = cls._set_nested_val(data[id_path[0]], id_path[1:], value)
                 data = was_t(data)
 
         return data
@@ -588,30 +586,31 @@ def __init__(self, data: DataStructure, comment_start: str, comment_end: str, co
         )) if len(comment_end) > 0 else None
 
     def __call__(self) -> DataStructure:
-        return self._rem_nested_comments(self.data)
+        return self.rem_nested_comments(self.data)
 
-    def _rem_nested_comments(self, item: Any) -> Any:
+    def rem_nested_comments(self, item: Any) -> Any:
         if isinstance(item, dict):
             return {
-                k: v
-                for k, v in ((self._rem_nested_comments(key), self._rem_nested_comments(value)) for key, value in item.items())
-                if k is not None
+                key: val
+                for key, val in ( \
+                    (self.rem_nested_comments(k), self.rem_nested_comments(v)) for k, v in item.items()
+                ) if key is not None
             }
+
         if isinstance(item, IndexIterableTypes):
-            processed = (v for v in map(self._rem_nested_comments, item) if v is not None)
+            processed = (v for v in map(self.rem_nested_comments, item) if v is not None)
             return type(item)(processed)
+
         if isinstance(item, str):
-            return self._remove_str_comment(item)
-        return item
+            if self.pattern:
+                if (match := self.pattern.match(item)):
+                    start, end = match.group(1).strip(), match.group(2).strip()
+                    return f"{start}{self.comment_sep if start and end else ''}{end}" or None
+                return item.strip() or None
+            else:
+                return None if item.lstrip().startswith(self.comment_start) else item.strip() or None
 
-    def _remove_str_comment(self, s: str) -> Optional[str]:
-        if self.pattern:
-            if (match := self.pattern.match(s)):
-                start, end = match.group(1).strip(), match.group(2).strip()
-                return f"{start}{self.comment_sep if start and end else ''}{end}" or None
-            return s.strip() or None
-        else:
-            return None if s.lstrip().startswith(self.comment_start) else s.strip() or None
+        return item
 
 
 class _DataRenderHelper:

src/xulbux/env_path.py

@@ -53,9 +53,9 @@ def remove_path(cls, path: Optional[str] = None, cwd: bool = False, base_dir: bo
 
     @staticmethod
     def _get(path: Optional[str] = None, cwd: bool = False, base_dir: bool = False) -> str:
-        """Get and/or normalize the given path, CWD or base directory.\n
-        ------------------------------------------------------------------------------------
-        Raise an error if no path is provided and neither `cwd` or `base_dir` is `True`."""
+        """Internal method to get the normalized `path`, CWD path or script directory path.\n
+        --------------------------------------------------------------------------------------
+        Raise an error if no path is provided and neither `cwd` or `base_dir` is true."""
         if cwd:
             if base_dir:
                 raise ValueError("Both 'cwd' and 'base_dir' cannot be True at the same time.")
@@ -70,7 +70,8 @@ def _get(path: Optional[str] = None, cwd: bool = False, base_dir: bool = False)
 
     @classmethod
     def _persistent(cls, path: str, remove: bool = False) -> None:
-        """Add or remove a path from PATH persistently across sessions as well as the current session."""
+        """Internal method to add or remove a path from the PATH environment variable,
+        persistently, across sessions, as well as the current session."""
         current_paths = list(cls.paths(as_list=True))
         path = _os.path.normpath(path)
 

src/xulbux/json.py

@@ -157,8 +157,8 @@ def update(
 
     @staticmethod
     def _create_nested_path(data_obj: dict, path_keys: list[str], value: Any) -> dict:
-        """Creates nested dictionaries/lists based on the given path keys
-        and sets the specified value at the end of the path."""
+        """Internal method that creates nested dictionaries/lists based on the
+        given path keys and sets the specified value at the end of the path."""
         last_idx, current = len(path_keys) - 1, data_obj
 
         for i, key in enumerate(path_keys):

src/xulbux/path.py

@@ -179,37 +179,39 @@ def remove(cls, path: str, only_content: bool = False) -> None:
                     raise Exception(f"Failed to delete {file_path}. Reason: {e}")
 
     @staticmethod
-    def _expand_env_path(p: str) -> str:
-        """Expand environment variables in the given path string."""
-        if "%" not in p:
-            return p
+    def _expand_env_path(path_str: str) -> str:
+        """Internal method that expands all environment variables in the given path string."""
+        if "%" not in path_str:
+            return path_str
 
-        for i in range(1, len(parts := p.split("%")), 2):
+        for i in range(1, len(parts := path_str.split("%")), 2):
             if parts[i].upper() in _os.environ:
                 parts[i] = _os.environ[parts[i].upper()]
 
         return "".join(parts)
 
     @classmethod
-    def _find_path(cls, start: str, parts: list[str], use_closest_match: bool) -> Optional[str]:
-        """Find a path by traversing the given parts from the start directory,
-        optionally using closest matches for each part."""
-        current: str = start
-
-        for part in parts:
-            if _os.path.isfile(current):
-                return current
-            if (closest_match := cls._get_closest_match(current, part) if use_closest_match else part) is None:
+    def _find_path(cls, start_dir: str, path_parts: list[str], use_closest_match: bool) -> Optional[str]:
+        """Internal method to find a path by traversing the given parts from
+        the start directory, optionally using closest matches for each part."""
+        current_dir: str = start_dir
+
+        for part in path_parts:
+            if _os.path.isfile(current_dir):
+                return current_dir
+            if (closest_match := cls._get_closest_match(current_dir, part) if use_closest_match else part) is None:
                 return None
-            current = _os.path.join(current, closest_match)
+            current_dir = _os.path.join(current_dir, closest_match)
 
-        return current if _os.path.exists(current) and current != start else None
+        return current_dir if _os.path.exists(current_dir) and current_dir != start_dir else None
 
     @staticmethod
-    def _get_closest_match(dir: str, part: str) -> Optional[str]:
-        """Get the closest matching file or folder name in the given directory for the given part."""
+    def _get_closest_match(dir: str, path_part: str) -> Optional[str]:
+        """Internal method to get the closest matching file or folder name
+        in the given directory for the given path part."""
         try:
-            matches = _difflib.get_close_matches(part, _os.listdir(dir), n=1, cutoff=0.6)
-            return matches[0] if matches else None
+            return matches[0] if (
+                matches := _difflib.get_close_matches(path_part, _os.listdir(dir), n=1, cutoff=0.6)
+            ) else None
         except Exception:
             return None