Python-Backpack

Python-Backpack is a lightweight utility collection for common scripting tasks:

• JSON load/save helpers with validation
• user settings persistence under the OS user directory
• metadata export/import to JSON files
• file and folder operations
• string normalization and case conversion
• cache decorator with expiration support
• custom exceptions, logging helper, singleton pattern, and testing helpers

Compatibility

• Python 3.11+

Installation

pip install python-backpack

Package API Reference

Cache (backpack.cache)

• timed_lru_cache(seconds: int, maxsize: int = 128)
  • functools.lru_cache decorator with expiration time.
  • Wrapped calls support force_clear=True and show_log=True.

Custom Errors (backpack.custom_errors)

• EnvironmentVariableNotFoundError(var_name: str)
  • Raised when a required environment variable is missing.
• ApplicationNotFoundError(app_name: str)
  • Raised when a required application is not found.

File Utils (backpack.file_utils)

• 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: 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 | 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) -> bool
  • Creates a folder and optionally clears it if it already exists.
• remove_files_in_dir(path: str) -> None
  • Removes all files and subdirectories inside a directory.
• 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: object, json_file: str) -> bool
  • Saves a JSON-serializable value as UTF-8 and returns whether it succeeded.

JSON Metadata (backpack.json_metadata)

• JsonMetaFile(name: str, path: str)
  • Manages a metadata JSON file with package/system/time information.
  • Main public methods:
    • has_file() -> bool
    • load() -> None
    • insert(key: str, value: Any) -> None
    • remove(key: str) -> None
    • save() -> None
    • load_as_class() -> type
    • insert_class(_class: type) -> None

JSON User Settings (backpack.json_user_settings)

• 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
    • load_settings() -> dict | bool

Logger (backpack.logger)

• get_logger(name: str) -> logging.Logger
  • Returns a configured logger with stream handler.

Patterns (backpack.patterns)

• Singleton
  • Base class implementing singleton behavior via __new__.

Strings (backpack.strings)

• normalize_input_string(input_string: str, under_spaces: bool = True, under_hyphen: bool = True, replacer: str = '_') -> str
  • Keeps alphanumeric/space/hyphen characters and normalizes separators.
• begin_or_end_with_numbers(input_string: str) -> bool
  • Checks whether first or last character is numeric.
• begin_with_number(input_string: str) -> bool
  • Checks whether the first character is numeric.
• has_numbers(input_string: str) -> bool
  • Checks whether any character is numeric.
• camelcase_to_snakecase(input_string: str) -> str
  • Converts CamelCase to snake_case.
  • Handles acronym prefixes, for example HTTPServer -> http_server.

Test Utils (backpack.test_utils)

• random_string(length: int = 10) -> str
  • Generates a random lowercase string.
• time_function_decorator(method: Callable[P, R]) -> Callable[P, R]
  • Decorator that logs execution time while preserving function metadata and return values.

Quick Example

from backpack.cache import timed_lru_cache
from backpack.strings import camelcase_to_snakecase, normalize_input_string
from backpack.json_utils import json_save, json_load


@timed_lru_cache(seconds=60)
def expensive_call():
    return {'ok': True}


value = camelcase_to_snakecase('HTTPServer')
clean = normalize_input_string('Blade Runner-2049')

json_save({'value': value, 'clean': clean}, 'data.json')
data = json_load('data.json')