Metadata-Version: 2.4
Name: python-backpack
Version: 2.0.3
Summary: Lightweight utilities for JSON, filesystem operations, strings, caching, and scripting.
Project-URL: Homepage, https://github.com/MaxRocamora/python-backpack
Project-URL: Repository, https://github.com/MaxRocamora/python-backpack.git
Author-email: Maximiliano Rocamora <maxirocamora@gmail.com>
License-Expression: GPL-3.0-only
License-File: LICENSE
Keywords: cache,filesystem,json,strings,utilities
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Utilities
Requires-Python: >=3.11
Description-Content-Type: text/markdown

[![PyPI Supported Python Versions](https://img.shields.io/pypi/pyversions/python-backpack.svg?style=flat-square&logo=appveyor)](https://pypi.python.org/pypi/python-backpack/)
[![PyPI version](https://badge.fury.io/py/python-backpack.svg?style=flat-square&logo=appveyor)](https://badge.fury.io/py/python-backpack)
[![GitHub version](https://badge.fury.io/gh/MaxRocamora%2Fpython-backpack.svg?style=flat-square&logo=appveyor)](https://badge.fury.io/gh/MaxRocamora%2Fpython-backpack)
[![codecov](https://codecov.io/gh/MaxRocamora/python-backpack/graph/badge.svg?token=6D1xwYdXW2)](https://codecov.io/gh/MaxRocamora/python-backpack)


# 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

```bash
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

```python
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')
```

