refactor: improve utility typing and edge-case handling

Author: MaxRocamora

README.md

@@ -43,34 +43,34 @@ pip install python-backpack
 
 ### File Utils (`backpack.file_utils`)
 
-- `replace_strings_in_file(ascii_file: str, strings: list, new_string: str) -> None`
+- `replace_strings_in_file(ascii_file: str, strings: Sequence[str], new_string: str) -> None`
     - Replaces multiple string occurrences in a text file.
-- `remove_line_from_file(ascii_file: str, strings: list, verbose: bool = False) -> None`
-    - Removes exact matching lines from a text file.
+- `remove_line_from_file(ascii_file: str, strings: Sequence[str], verbose: bool = False) -> None`
+    - Removes every exact matching line while preserving retained line endings.
 - `file_is_writeable(filepath: str) -> bool`
     - Checks whether a file can be opened for read/write.
 - `get_version_from_filename(filename: str) -> str`
     - Extracts a numeric version token from a filename.
 
 ### Folder Utils (`backpack.folder_utils`)
 
-- `browse_folder(folder: str) -> bool`
-    - Opens a folder in Windows Explorer.
-- `create_folders(folders: list, force_empty: bool = False, verbose: bool = False)`
+- `browse_folder(folder: str | None) -> bool`
+    - Opens a valid folder in Windows Explorer and returns `False` if it cannot be opened.
+- `create_folders(folders: Sequence[str], force_empty: bool = False, verbose: bool = False) -> None`
     - Creates multiple folders.
-- `create_folder(path: str, force_empty: bool = False, verbose: bool = True)`
+- `create_folder(path: str, force_empty: bool = False, verbose: bool = True) -> bool`
     - Creates a folder and optionally clears it if it already exists.
-- `remove_files_in_dir(path: str)`
+- `remove_files_in_dir(path: str) -> None`
     - Removes all files and subdirectories inside a directory.
-- `recursive_dir_copy(source_path: str, target_path: str)`
+- `recursive_dir_copy(source_path: str, target_path: str) -> None`
     - Recursively copies files and subfolders from source to target.
 
 ### JSON Utils (`backpack.json_utils`)
 
 - `json_load(json_file: str) -> dict`
     - Loads JSON data from file with validation and error handling.
-- `json_save(data: dict, json_file: str) -> bool`
-    - Saves a dictionary to JSON file.
+- `json_save(data: object, json_file: str) -> bool`
+    - Saves a JSON-serializable value as UTF-8 and returns whether it succeeded.
 
 ### JSON Metadata (`backpack.json_metadata`)
 
@@ -90,7 +90,7 @@ pip install python-backpack
 - `JsonUserSettings(folder: str, name: str)`
     - Saves and loads JSON settings in the current user's home directory.
     - Main public methods:
-        - `save_settings(data: dict | None = None) -> bool | None`
+        - `save_settings(data: dict | None = None) -> bool`
         - `load_settings() -> dict | bool`
 
 ### Logger (`backpack.logger`)
@@ -121,8 +121,8 @@ pip install python-backpack
 
 - `random_string(length: int = 10) -> str`
     - Generates a random lowercase string.
-- `time_function_decorator(method: type)`
-    - Decorator that logs execution time.
+- `time_function_decorator(method: Callable[P, R]) -> Callable[P, R]`
+    - Decorator that logs execution time while preserving function metadata and return values.
 
 ## Quick Example
 
@@ -134,7 +134,7 @@ from backpack.json_utils import json_save, json_load
 
 @timed_lru_cache(seconds=60)
 def expensive_call():
-        return {'ok': True}
+    return {'ok': True}
 
 
 value = camelcase_to_snakecase('HTTPServer')

backpack/cache.py

@@ -5,16 +5,33 @@
 # ----------------------------------------------------------------------------------------
 from datetime import datetime, timedelta, timezone
 from functools import lru_cache, wraps
-from typing import Any, Callable, TypeVar, cast
+from typing import Any, Callable, Protocol, TypeVar, cast
 
 from backpack.logger import get_logger
 
 log = get_logger('Python Backpack - Cache')
 
-F = TypeVar('F', bound=Callable[..., Any])
+R = TypeVar('R', covariant=True)
 
 
-def timed_lru_cache(seconds: int, maxsize: int = 128) -> Callable[[F], F]:
+class TimedCachedCallable(Protocol[R]):
+    """Callable returned by timed_lru_cache with cache control kwargs."""
+
+    def __call__(
+        self,
+        *args: Any,
+        force_clear: bool = False,
+        show_log: bool = False,
+        **kwargs: Any,
+    ) -> R:
+        """Call the cached function, optionally forcing a cache clear first."""
+        ...
+
+
+def timed_lru_cache(
+    seconds: int,
+    maxsize: int = 128,
+) -> Callable[[Callable[..., R]], TimedCachedCallable[R]]:
     """Lru_cache with expiration time.
 
     Args:
@@ -39,13 +56,18 @@ def my_function():
 
     """
 
-    def wrapper_cache(func: F) -> F:
+    def wrapper_cache(func: Callable[..., R]) -> TimedCachedCallable[R]:
         cached_func = cast(Any, lru_cache(maxsize=maxsize)(func))
         cached_func.lifetime = timedelta(seconds=seconds)
         cached_func.expiration = datetime.now(timezone.utc) + cached_func.lifetime
 
         @wraps(func)
-        def wrapped_func(*args, force_clear: bool = False, show_log: bool = False, **kwargs):
+        def wrapped_func(
+            *args: Any,
+            force_clear: bool = False,
+            show_log: bool = False,
+            **kwargs: Any,
+        ) -> R:
             """Wrapper function for lru_cache with expiration time.
 
             Args:
@@ -66,6 +88,6 @@ def wrapped_func(*args, force_clear: bool = False, show_log: bool = False, **kwa
 
             return cached_func(*args, **kwargs)
 
-        return cast(F, wrapped_func)
+        return cast(TimedCachedCallable[R], wrapped_func)
 
     return wrapper_cache

backpack/file_utils.py

@@ -4,14 +4,18 @@
 # https://github.com/MaxRocamora/python-backpack
 # ----------------------------------------------------------------------------------------
 
-import contextlib
+from collections.abc import Sequence
 
 from backpack.logger import get_logger
 
 log = get_logger('Python Backpack - FileUtils')
 
 
-def replace_strings_in_file(ascii_file: str, strings: list, new_string: str) -> None:
+def replace_strings_in_file(
+    ascii_file: str,
+    strings: Sequence[str],
+    new_string: str,
+) -> None:
     """Opens ascii file and replaces all occurrences from strings into new_string.
 
     In this class we use a full path to avoid use of os.dirname, which
@@ -28,21 +32,24 @@ def replace_strings_in_file(ascii_file: str, strings: list, new_string: str) ->
 
     log.info(f'Replacing Strings, Opening File: {ascii_file}')
 
-    with open(ascii_file) as f:
+    with open(ascii_file, newline='') as f:
         file_data = f.read()
         for i in strings:
             log.info('Finding: %s', i)
             log.info('Replacing for: %s', new_string)
             log.info('-' * 50)
             file_data = file_data.replace(i, new_string)
 
-    with open(ascii_file, 'w') as f:
+    with open(ascii_file, 'w', newline='') as f:
         f.write(file_data)
-        f.close()
         log.info(f'Closing File: {ascii_file}')
 
 
-def remove_line_from_file(ascii_file: str, strings: list, verbose: bool = False) -> None:
+def remove_line_from_file(
+    ascii_file: str,
+    strings: Sequence[str],
+    verbose: bool = False,
+) -> None:
     """Removes given lines from ascii file.
 
     Args:
@@ -51,21 +58,22 @@ def remove_line_from_file(ascii_file: str, strings: list, verbose: bool = False)
         verbose: (bool) if true, prints removed lines
     """
 
-    with open(ascii_file) as f:
-        file_content = f.read().splitlines()
+    retained_lines = []
+    with open(ascii_file, newline='') as f:
+        file_content = f.readlines()
 
     for line in file_content:
+        value = line.rstrip('\r\n')
         if verbose:
-            log.info(f'Checking line: {line}')
-        with contextlib.suppress(ValueError):
-            if line in strings:
-                if verbose:
-                    log.info(f'Removing line: {line}')
-                file_content.pop(file_content.index(line))
-
-    with open(ascii_file, 'w') as f:
-        contents = '\n'.join(file_content)
-        f.write(contents)
+            log.info(f'Checking line: {value}')
+        if value in strings:
+            if verbose:
+                log.info(f'Removing line: {value}')
+        else:
+            retained_lines.append(line)
+
+    with open(ascii_file, 'w', newline='') as f:
+        f.writelines(retained_lines)
 
 
 def file_is_writeable(filepath: str) -> bool:

backpack/folder_utils.py

@@ -7,27 +7,37 @@
 import os
 import shutil
 import subprocess
+from collections.abc import Sequence
 
 from backpack.logger import get_logger
 
 log = get_logger('Python Backpack - FolderUtils')
 
 
-def browse_folder(folder: str) -> bool:
+def browse_folder(folder: str | None) -> bool:
     """Open windows explorer on folder.
 
     Args:
         folder: (string path) folder to open
     """
     if folder and os.path.isdir(folder):
-        subprocess.Popen(f'explorer {os.path.abspath(folder)}')
-        return True
+        try:
+            subprocess.Popen(['explorer', os.path.abspath(folder)])
+            return True
+        except OSError as error:
+            log.warning(f'Unable to open folder {folder}')
+            log.error(str(error))
+            return False
 
     log.warning(f'Unable to open folder {folder}')
     return False
 
 
-def create_folders(folders: list, force_empty: bool = False, verbose: bool = False):
+def create_folders(
+    folders: Sequence[str],
+    force_empty: bool = False,
+    verbose: bool = False,
+) -> None:
     """Creates multiple folders on disc.
 
     Args:
@@ -39,7 +49,7 @@ def create_folders(folders: list, force_empty: bool = False, verbose: bool = Fal
         create_folder(folder, force_empty=force_empty, verbose=verbose)
 
 
-def create_folder(path: str, force_empty: bool = False, verbose: bool = True):
+def create_folder(path: str, force_empty: bool = False, verbose: bool = True) -> bool:
     """Creates a folder.
 
     Args:
@@ -63,7 +73,7 @@ def create_folder(path: str, force_empty: bool = False, verbose: bool = True):
     return True
 
 
-def remove_files_in_dir(path: str):
+def remove_files_in_dir(path: str) -> None:
     """Clears all content in given directory."""
     for root, dirs, files in os.walk(path):
         for f in files:
@@ -72,7 +82,7 @@ def remove_files_in_dir(path: str):
             shutil.rmtree(os.path.join(root, d))
 
 
-def recursive_dir_copy(source_path: str, target_path: str):
+def recursive_dir_copy(source_path: str, target_path: str) -> None:
     """Copy all files src dir to dest dir, including sub-directories.
 
     Args:

backpack/json_metadata.py

@@ -3,6 +3,7 @@
 # Maximiliano Rocamora / maxirocamora@gmail.com
 # https://github.com/MaxRocamora/python-backpack
 # ----------------------------------------------------------------------------------------
+import getpass
 import inspect
 import os
 import platform
@@ -97,7 +98,9 @@ def insert_class(self, _class: type) -> None:
         attributes = {}
         for name in dir(_class):
             value = getattr(_class, name)
-            if not name.startswith('__') and not inspect.ismethod(value):
+            if not name.startswith('__') and not (
+                inspect.isroutine(value) or inspect.isdatadescriptor(value)
+            ):
                 attributes[name] = value
 
         self._data = attributes
@@ -113,7 +116,7 @@ def _system_data(self) -> dict:
             'app': os.path.basename(sys.executable),
             'PC': str(platform.node()),
             'python_version': sys.version,
-            'User': str(os.getenv('username')),
+            'User': getpass.getuser(),
             'time': self._current_time_metadata(),
         }
 

backpack/json_user_settings.py

@@ -27,15 +27,15 @@ def __init__(self, folder: str, name: str) -> None:
             folder (str): name of sub folder inside user path. Defaults to 'json_settings'.
             name (str): name used for the json file. Defaults to 'user_data'.
         """
-        self.name = name
+        self.filename = name
         self.folder = folder
         self._user_data = {}
         self._verify_path()
 
     @property
     def filepath(self) -> str:
         """Returns user filepath."""
-        path = os.path.join(self.os_user_folder, self.folder, f'{self.name}.json')
+        path = os.path.join(self.os_user_folder, self.folder, f'{self.filename}.json')
         return os.path.abspath(path)
 
     @property
@@ -60,14 +60,14 @@ def _verify_path(self) -> bool:
 
         return True
 
-    def save_settings(self, data: dict | None = None) -> bool | None:
+    def save_settings(self, data: dict | None = None) -> bool:
         """Saves a dictionary into a json file (os user path).
 
         Args:
-            data (dictionary): info dictionary to save, if not provided,
+            data (dict): info dictionary to save, if not provided,
                 saves instead local self.user_data property
         Returns:
-            bool | None: True if file was saved, False if error, None if no data to save.
+            bool: True if the file was saved, otherwise False.
         """
         if data is None:
             data = self.user_data

backpack/json_utils.py

@@ -18,32 +18,32 @@ def json_load(json_file: str) -> dict:
     if not os.path.exists(json_file):
         raise OSError(f'json_load: File not found: {json_file}.')
 
-    with open(json_file) as json_file_opened:
+    with open(json_file, encoding='utf-8') as json_file_opened:
         try:
             value = json.load(json_file_opened)
         except ValueError as e:
-            json_file_opened.close()
             raise OSError(f'{json_file} \n JSON File issue: {str(e)}') from e
 
     return value
 
 
-def json_save(data: dict, json_file: str) -> bool:
+def json_save(data: object, json_file: str) -> bool:
     """Saves a dictionary into a json file.
 
     Args:
-        data: (dict) dictionary to save
+        data: value to serialize as JSON
         json_file: (string filepath) json file to save data.
 
     Returns:
         bool (True if success)
     """
 
-    if not os.path.exists(os.path.dirname(json_file)):
-        os.makedirs(os.path.dirname(json_file), exist_ok=True)
+    parent_dir = os.path.dirname(json_file)
+    if parent_dir and not os.path.exists(parent_dir):
+        os.makedirs(parent_dir, exist_ok=True)
 
     try:
-        with open(json_file, 'w') as f:
+        with open(json_file, 'w', encoding='utf-8') as f:
             json.dump(data, f, sort_keys=True, indent=4)
             return True