python-backpack 2.0.0__tar.gz → 2.0.1__tar.gz

python_backpack-2.0.1/.github/workflows/codecov_tests.yml

@@ -0,0 +1,51 @@
+name: Python Tests & Coverage
+
+on:
+  - push
+  - pull_request
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ['3.11']
+
+    steps:
+    - uses: actions/checkout@v6
+
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v6
+      with:
+        python-version: ${{ matrix.python-version }}
+
+    - name: Add path to PYTHONPATH
+      run: |
+        echo "PYTHONPATH=$GITHUB_WORKSPACE" >> $GITHUB_ENV
+
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install uv
+        uv sync --dev
+
+    - name: Run tests with coverage
+      run: |
+        uv run coverage run --source=backpack -m pytest
+        uv run coverage report -m --fail-under=70
+        uv run coverage xml
+
+    - name: Upload coverage.xml
+      if: ${{ matrix.python-version == '3.11' }}
+      uses: actions/upload-artifact@v7
+      with:
+        name: upload coverage
+        path: ${{ github.workspace }}/coverage.xml
+        if-no-files-found: warn
+
+    # upload coverage.xml to codecov
+    - name: Upload coverage.xml to codecov
+      if: ${{ matrix.python-version == '3.11' }}
+      uses: codecov/codecov-action@v6
+      with:
+        token: ${{ secrets.CODECOV_TOKEN }}

python_backpack-2.0.1/.gitignore

@@ -0,0 +1,131 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+pip-wheel-metadata/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+.python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# test generated files
+tests/test_json/MD_test.json

python_backpack-2.0.1/PKG-INFO

@@ -0,0 +1,7 @@
+Metadata-Version: 2.4
+Name: python-backpack
+Version: 2.0.1
+Summary: A collection of personal scripts for json, File/Folder Operations, String Validation, Custom Errors, Cache and stuff.
+Author: Maximiliano Rocamora
+License-File: LICENSE
+Requires-Python: >=3.11

python_backpack-2.0.1/README.md

@@ -0,0 +1,144 @@
+[![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: list, 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.
+- `file_is_writeable(filepath: str) -> bool`
+    - Checks whether a file can be opened for read/write.
+
+### 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)`
+    - Creates multiple folders.
+- `create_folder(path: str, force_empty: bool = False, verbose: bool = True)`
+    - Creates a folder and optionally clears it if it already exists.
+- `remove_files_in_dir(path: str)`
+    - Removes all files and subdirectories inside a directory.
+- `recursive_dir_copy(source_path: str, target_path: str)`
+    - 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 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 | None`
+        - `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: type)`
+    - Decorator that logs execution time.
+
+## 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')
+```
+

{python_backpack-2.0.0 → python_backpack-2.0.1}/backpack/file_utils.py

@@ -84,3 +84,44 @@ def file_is_writeable(filepath: str) -> bool:
         log.info(x.strerror)
 
     return False
+
+
+def get_version_from_filename(filename: str) -> str:
+    """Extracts version from filename.
+
+    Args:
+        filename: (str) file name to extract version from
+    Returns:
+        str : version extracted from filename
+
+    Examples:
+        get_version_from_filename('myfile_23.txt') -> '23'
+        get_version_from_filename('myfile-9.txt') -> '9'
+        get_version_from_filename('myfile.130.txt') -> '130'
+        get_version_from_filename('myfile_v1002.txt') -> '1002'
+
+    """
+
+    filename_no_ext = filename.rsplit('.', 1)[0]
+
+    # guess is the separator is an underscore, dash, dot or v, and the version is the last part before the extension
+    separators = ['_', '-', '.', 'v']
+    if not any(sep in filename_no_ext for sep in separators):
+        log.info(f'No separator found in filename: {filename_no_ext}. Using fallback extraction.')
+    else:
+        for sep in separators:
+            if sep in filename_no_ext:
+                parts = filename_no_ext.split(sep)
+                version_part = parts[-1].split('.')[0]  # Get the last part before the extension
+                if version_part.replace('.', '').isdigit():  # Check if it's a valid version number
+                    log.info(
+                        f'Extracted version: {version_part} from filename: {filename} using separator: {sep}'
+                    )
+                    return version_part
+
+    # Fallback: extract from the entire filename
+    version = filename_no_ext.lstrip('v')
+    version = version.replace('_', '.').replace('-', '.')
+    version = version if version.replace('.', '').isdigit() else '0'
+    log.info(f'Extracted version: {version} from filename: {filename}')
+    return version

{python_backpack-2.0.0 → python_backpack-2.0.1}/backpack/json_utils.py

@@ -40,7 +40,7 @@ def json_save(data: dict, json_file: str) -> bool:
     """
 
     if not os.path.exists(os.path.dirname(json_file)):
-        os.makedirs(os.path.dirname(json_file))
+        os.makedirs(os.path.dirname(json_file), exist_ok=True)
 
     try:
         with open(json_file, 'w') as f:

{python_backpack-2.0.0 → python_backpack-2.0.1}/backpack/version.py

@@ -9,12 +9,12 @@
 # 1.1.2 07/2025 - Update actions versions, remove unused badge from README
 # 1.1.3 07/2025 - Improve test class names and docstrings for clarity, ruff formatting
 # 1.1.4 07/2025 - Moved from pipenv to poetry for dependency management.toml
-# 2.0.0 03/2026 - Remove tox workflow and setup.py, standardize Poetry + coverage tooling
+# 2.0.1 05/2026 - Remove tox workflow and setup.py, standardize uv + coverage tooling
 # ----------------------------------------------------------------------------------------
 
 VERSION_MAJOR = 2
 VERSION_MINOR = 0
-VERSION_PATCH = 0
+VERSION_PATCH = 1
 
 version = f'{VERSION_MAJOR}.{VERSION_MINOR}.{VERSION_PATCH}'
 

python_backpack-2.0.1/backpack.code-workspace

@@ -0,0 +1,63 @@
+{
+	"folders": [
+		{
+			"path": "."
+		}
+	],
+	"settings": {
+		"python.analysis.completeFunctionParens": false,
+		"python.analysis.autoImportCompletions": false,
+		"editor.formatOnSave": true,
+		"editor.formatOnPaste": false,
+		"editor.codeActionsOnSave": {
+			"source.organizeImports": "never"
+		},
+		"editor.rulers": [
+			90
+		],
+		"editor.defaultFormatter": "charliermarsh.ruff",
+		"editor.wordWrap": "wordWrapColumn",
+		"editor.wordWrapColumn": 120,
+		"workbench.colorTheme": "Monokai Pro (Filter Spectrum)",
+		"workbench.colorCustomizations": {
+			"titleBar.activeBackground": "#f36edf",
+			"titleBar.activeForeground": "#0c0b0b"
+		},
+		"python.analysis.extraPaths": [],
+		"python.testing.unittestArgs": [
+			"-v",
+			"-s",
+			".",
+			"-p",
+			"*test*.py"
+		],
+		"python.testing.pytestEnabled": false,
+		"python.testing.unittestEnabled": true,
+		"terminal.integrated.fontSize": 12,
+		"cSpell.words": [
+			"autopep",
+			"camelcase",
+			"charliermarsh",
+			"codecov",
+			"docstrings",
+			"ftime",
+			"jsonfile",
+			"levelname",
+			"Maximiliano",
+			"Monokai",
+			"numpy",
+			"Parens",
+			"pipenv",
+			"pycodestyle",
+			"pydocstyle",
+			"pylint",
+			"pypi",
+			"pytest",
+			"PYTHONPATH",
+			"Rocamora",
+			"runn",
+			"snakecase",
+			"strerror"
+		],
+	}
+}

python_backpack-2.0.1/codecov.yml

@@ -0,0 +1,2 @@
+ignore:
+  - "*/tests/*"

python_backpack-2.0.1/coverage.bat

@@ -0,0 +1,9 @@
+@echo off
+REM Run tests with coverage and generate reports.
+uv run coverage run --source=backpack -m pytest
+if errorlevel 1 exit /b %errorlevel%
+uv run coverage report -m --fail-under=70
+if errorlevel 1 exit /b %errorlevel%
+uv run coverage html
+if errorlevel 1 exit /b %errorlevel%
+uv run coverage xml

python_backpack-2.0.1/pyproject.toml

@@ -0,0 +1,29 @@
+[project]
+name = "python-backpack"
+version = "2.0.1"
+description = "A collection of personal scripts for json, File/Folder Operations, String Validation, Custom Errors, Cache and stuff."
+authors = [
+    { name = "Maximiliano Rocamora" }
+]
+requires-python = ">=3.11"
+dependencies = []
+
+[dependency-groups]
+dev = [
+    "coverage>=7.14.0",
+    "ruff>=0.15.12",
+    "mock>=5.2.0",
+    "pytest>=9.0.3",
+    "pytest-cov>=7.1.0",
+]
+
+[build-system]
+requires = ["hatchling>=1.27.0"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["backpack"]
+
+[tool.pytest.ini_options]
+addopts = "-p no:cacheprovider"
+testpaths = ["tests"]

python_backpack-2.0.1/ruff.toml

@@ -0,0 +1,26 @@
+line-length = 99
+
+# Assume Python 3.11
+target-version = "py311"
+
+[lint]
+select = ["D", "F", "N", "I", "W"]
+# ignore E402: module level import not at top of file
+# ignore D100: missing docstring in public module
+# ignore D101: missing docstring in public class
+# ignore D104: missing docstring in public package
+# ignore D202: no blank lines allowed after function docstring
+ignore = ["E402", "D100", "D202", "D101", "D104"]
+
+[lint.per-file-ignores]
+# Ignore `E402` (import violations) in all `__init__.py` files.
+"__init__.py" = ["E402"]
+
+[lint.pydocstyle]
+convention = "google"  # Accepts: "google", "numpy", or "pep257".
+
+[format]
+# Enable reformatting of code snippets in docstrings.
+docstring-code-format = true
+docstring-code-line-length = 109
+quote-style = "single"

python_backpack-2.0.1/tests/test_cache.py

@@ -0,0 +1,20 @@
+# ----------------------------------------------------------------------------------------
+# Python-Backpack - Custom Exceptions UnitTest
+# Maximiliano Rocamora / maxirocamora@gmail.com
+# https://github.com/MaxRocamora/python-backpack
+# ----------------------------------------------------------------------------------------
+
+from backpack.cache import timed_lru_cache
+
+
+@timed_lru_cache(seconds=1)
+def cached_test_function():
+    """Some heavy process here to be cached."""
+    return True
+
+
+def test_cache():
+    """Testing module."""
+    assert cached_test_function()
+    assert cached_test_function(force_clear=True) is True
+    assert cached_test_function(force_clear=True, show_log=True) is True

python_backpack-2.0.1/tests/test_errors.py

@@ -0,0 +1,47 @@
+# ----------------------------------------------------------------------------------------
+# Python-Backpack - Custom Exceptions UnitTest
+# Maximiliano Rocamora / maxirocamora@gmail.com
+# https://github.com/MaxRocamora/python-backpack
+# ----------------------------------------------------------------------------------------
+
+import os
+import sys
+
+import pytest
+
+from backpack.custom_errors import ApplicationNotFoundError, EnvironmentVariableNotFoundError
+
+mod_path = os.path.dirname(__file__)
+if mod_path not in sys.path:
+    sys.path.append(mod_path)
+
+
+def get_env_var(name: str):
+    """Call for an env var or raise EnvironmentVariableNotFoundError."""
+    try:
+        value = os.environ[name]
+    except KeyError as e:
+        raise EnvironmentVariableNotFoundError(name) from e
+    return value
+
+
+def get_app(name: str):
+    """Raisers error."""
+    raise ApplicationNotFoundError(f'Background executable not found {name}')
+
+
+def test_env_var_error():
+    """Testing module."""
+    with pytest.raises(EnvironmentVariableNotFoundError):
+        get_env_var('my_env_var')
+    error = EnvironmentVariableNotFoundError('my_env_var')
+    assert str(error) == error.message
+
+
+def test_env_app_error():
+    """Testing module."""
+    with pytest.raises(ApplicationNotFoundError):
+        get_app('my_app.exe')
+
+    error = ApplicationNotFoundError('my_app.exe')
+    assert str(error) == error.message

python_backpack-2.0.1/tests/test_file_utils.py

@@ -0,0 +1,71 @@
+# ----------------------------------------------------------------------------------------
+# Python-Backpack - FolderUtils Tests
+# Maximiliano Rocamora / maxirocamora@gmail.com
+# https://github.com/MaxRocamora/python-backpack
+# ----------------------------------------------------------------------------------------
+
+import os
+import shutil
+import sys
+
+import pytest
+
+from backpack.file_utils import (
+    file_is_writeable,
+    get_version_from_filename,
+    remove_line_from_file,
+    replace_strings_in_file,
+)
+
+mod_path = os.path.dirname(__file__)
+if mod_path not in sys.path:
+    sys.path.append(mod_path)
+
+# test folders
+BASE_FILE = os.path.join(mod_path, 'test_files', 'origin.txt')
+EDITED_FILE = os.path.join(mod_path, 'test_files', 'edited.txt')
+STRINGS = ['to be replaced!', 'also replaced']
+NEW_STRING = 'REPLACED'
+LOCKED_FILE = os.path.join(mod_path, 'test_files', 'locked_file.txt')
+UNLOCKED_FILE = os.path.join(mod_path, 'test_files', 'unlocked_file.txt')
+NO_FILE = os.path.join(mod_path, 'test_files', 'no_file.txt')
+
+
+def test_replace_strings_in_file():
+    """Testing module."""
+    shutil.copy(BASE_FILE, EDITED_FILE)
+    replace_strings_in_file(EDITED_FILE, STRINGS, NEW_STRING)
+
+
+def test_remove_line_from_file():
+    """Testing module."""
+    source_file = os.path.join(mod_path, 'test_files', 'origin_remove.txt')
+    test_file = os.path.join(mod_path, 'test_files', 'edited_remove.txt')
+    shutil.copy(source_file, test_file)
+    remove_line_from_file(test_file, ['REMOVE_ME', 'to be replaced!'], verbose=True)
+
+
+def test_locked_file():
+    """Testing module."""
+    assert file_is_writeable(UNLOCKED_FILE)
+    assert not file_is_writeable(NO_FILE)
+
+
+@pytest.mark.parametrize(
+    ('filename', 'expected_version'),
+    [
+        ('myfile_23.txt', '23'),
+        ('myfile-9.txt', '9'),
+        ('myfile.130.txt', '130'),
+        ('myfile_v1002.txt', '1002'),
+        ('name_without_separator.txt', '0'),
+        ('v42.txt', '42'),
+        ('myfile-alpha.txt', '0'),
+        ('myfile.txt', '0'),
+        ('mod_asset.1004.ma', '1004'),
+        ('script_nuke_s100_v1005.ma', '1005'),
+    ],
+)
+def test_get_version_from_filename(filename: str, expected_version: str):
+    """Version extraction should handle supported separators and invalid values."""
+    assert get_version_from_filename(filename) == expected_version