python-backpack 1.1.4__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-1.1.4 → python_backpack-2.0.1}/backpack/cache.py

@@ -5,13 +5,16 @@
 # ----------------------------------------------------------------------------------------
 from datetime import datetime, timedelta, timezone
 from functools import lru_cache, wraps
+from typing import Any, Callable, TypeVar, cast
 
 from backpack.logger import get_logger
 
 log = get_logger('Python Backpack - Cache')
 
+F = TypeVar('F', bound=Callable[..., Any])
 
-def timed_lru_cache(seconds: int, maxsize: int = 128):
+
+def timed_lru_cache(seconds: int, maxsize: int = 128) -> Callable[[F], F]:
     """Lru_cache with expiration time.
 
     Args:
@@ -36,10 +39,10 @@ def timed_lru_cache(seconds: int, maxsize: int = 128):
 
     """
 
-    def wrapper_cache(func):
-        func = lru_cache(maxsize=maxsize)(func)
-        func.lifetime = timedelta(seconds=seconds)
-        func.expiration = datetime.now(timezone.utc) + func.lifetime
+    def wrapper_cache(func: F) -> F:
+        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):
@@ -54,15 +57,15 @@ def timed_lru_cache(seconds: int, maxsize: int = 128):
                 function result
             """
 
-            if force_clear or datetime.now(timezone.utc) >= func.expiration:
+            if force_clear or datetime.now(timezone.utc) >= cached_func.expiration:
                 if show_log:
-                    log.debug(f'Cache cleared for {func.__name__}')
+                    log.debug(f'Cache cleared for {cached_func.__name__}')
 
-                func.cache_clear()
-                func.expiration = datetime.now(timezone.utc) + func.lifetime
+                cached_func.cache_clear()
+                cached_func.expiration = datetime.now(timezone.utc) + cached_func.lifetime
 
-            return func(*args, **kwargs)
+            return cached_func(*args, **kwargs)
 
-        return wrapped_func
+        return cast(F, wrapped_func)
 
     return wrapper_cache

{python_backpack-1.1.4 → 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-1.1.4 → python_backpack-2.0.1}/backpack/json_user_settings.py

@@ -9,6 +9,7 @@ us.save(someDict)
 data = us.load()
 
 """
+
 # ----------------------------------------------------------------------------------------
 import os
 
@@ -59,14 +60,16 @@ class JsonUserSettings:
 
         return True
 
-    def save_settings(self, data=False) -> bool:
+    def save_settings(self, data: dict | None = None) -> bool | None:
         """Saves a dictionary into a json file (os user path).
 
         Args:
-            data (dictionary) : info dictionary to save, if set to False,
+            data (dictionary): 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.
         """
-        if not data:
+        if data is None:
             data = self.user_data
 
         r = json_save(data, self.filepath)
@@ -74,7 +77,7 @@ class JsonUserSettings:
             log.info('json settings file saved! [%s]', self.filepath)
         return r
 
-    def load_settings(self) -> dict:
+    def load_settings(self) -> dict | bool:
         """Load json file from path and returns its contents."""
         try:
             return json_load(self.filepath)

{python_backpack-1.1.4 → 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-1.1.4 → python_backpack-2.0.1}/backpack/strings.py

@@ -8,8 +8,11 @@ import contextlib
 import re
 
 
-def reformat_input_string(
-    input_string: str, under_spaces: bool = True, under_hyphen: bool = True
+def normalize_input_string(
+    input_string: str,
+    under_spaces: bool = True,
+    under_hyphen: bool = True,
+    replacer: str = '_',
 ) -> str:
     """Reformat the user input string.
 
@@ -20,6 +23,7 @@ def reformat_input_string(
         input_string (str): input string to reformat
         under_spaces (bool, optional): replaces spaces. Defaults to True.
         under_hyphen (bool, optional): replaces hyphens. Defaults to True.
+        replacer (str, optional): char to replace spaces and hyphens. Defaults to '_'.
 
     Returns:
         str: reformatted string
@@ -30,13 +34,13 @@ def reformat_input_string(
         regex = re.sub('[^A-Za-z0-9 _-]+', '', input_string)
 
     for char in regex:
-        # replacing " " for "_"
+        # replacing " " for replacer
         if under_spaces and char == ' ':
-            regex = regex.replace(' ', '_')
+            regex = regex.replace(' ', replacer)
 
-        # replacing "-" for "_"
+        # replacing "-" for replacer
         if under_hyphen and char == '-':
-            regex = regex.replace('-', '_')
+            regex = regex.replace('-', replacer)
 
     return regex
 
@@ -85,6 +89,7 @@ def camelcase_to_snakecase(input_string: str) -> str:
     Examples:
         OneDayCaseChar > one_day_case_char
         oneCamelCaseChar > one_camel_case_char
+        HTTPServer > http_server
         _TwoCamel_CaseChar > _two_camel_case_char
         _LeadingUnderscore_case_ > _leading_underscore_case_
     """
@@ -97,18 +102,28 @@ def camelcase_to_snakecase(input_string: str) -> str:
             snake_str += char
             continue
 
-        if char.isupper() and index == 0:
-            snake_str += char.lower()
-            continue
-
-        if char.isupper():
-            if input_string[index - 1] != '_':
-                snake_str += '_' + char.lower()
-            else:
-                snake_str += char.lower()
-
+        if not char.isupper():
+            snake_str += char
             continue
 
-        snake_str += char
+        prev_char = input_string[index - 1] if index > 0 else ''
+        next_char = input_string[index + 1] if index + 1 < len(input_string) else ''
+
+        # Add underscore only at real word boundaries.
+        # This keeps acronyms together: HTTPServer -> http_server.
+        should_add_underscore = (
+            index > 0
+            and prev_char != '_'
+            and (
+                prev_char.islower()
+                or prev_char.isdigit()
+                or (prev_char.isupper() and next_char.islower())
+            )
+        )
+
+        if should_add_underscore:
+            snake_str += '_'
+
+        snake_str += char.lower()
 
     return snake_str

{python_backpack-1.1.4 → python_backpack-2.0.1}/backpack/test_utils.py

@@ -12,7 +12,7 @@ from backpack.logger import get_logger
 log = get_logger('Python Backpack - TestUtils')
 
 
-def random_string(length: str = 10) -> str:
+def random_string(length: int = 10) -> str:
     """Generates a random string of fixed length.
 
     Args:

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

@@ -9,11 +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.1 05/2026 - Remove tox workflow and setup.py, standardize uv + coverage tooling
 # ----------------------------------------------------------------------------------------
 
-VERSION_MAJOR = 1
-VERSION_MINOR = 1
-VERSION_PATCH = 4
+VERSION_MAJOR = 2
+VERSION_MINOR = 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