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

{python_backpack-2.0.1 → python_backpack-2.0.3}/.github/workflows/codecov_tests.yml

@@ -9,7 +9,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: ['3.11']
+        python-version: ['3.11', '3.12', '3.13', '3.14']
 
     steps:
     - uses: actions/checkout@v6
@@ -19,20 +19,29 @@ jobs:
       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
+    - name: Run Ruff
+      if: ${{ matrix.python-version == '3.11' }}
+      run: uv run ruff check .
+
+    - name: Run Pyright
+      if: ${{ matrix.python-version == '3.11' }}
+      run: uv run pyright backpack tests
+
+    - name: Run tests
+      if: ${{ matrix.python-version != '3.11' }}
+      run: uv run pytest
+
+    - name: Run tests with branch coverage
+      if: ${{ matrix.python-version == '3.11' }}
       run: |
-        uv run coverage run --source=backpack -m pytest
-        uv run coverage report -m --fail-under=70
+        uv run coverage run --branch --source=backpack -m pytest
+        uv run coverage report -m --fail-under=99
         uv run coverage xml
 
     - name: Upload coverage.xml

{python_backpack-2.0.1 → python_backpack-2.0.3}/.gitignore

@@ -129,3 +129,4 @@ dmypy.json
 
 # test generated files
 tests/test_json/MD_test.json
+.vscode/settings.json

python_backpack-2.0.3/PKG-INFO

@@ -0,0 +1,168 @@
+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')
+```
+

{python_backpack-2.0.1 → python_backpack-2.0.3}/README.md

@@ -43,32 +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`)
 
@@ -88,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`)
@@ -119,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
 
@@ -132,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')

{python_backpack-2.0.1 → python_backpack-2.0.3}/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 timed_lru_cache(seconds: int, maxsize: int = 128) -> Callable[[F], F]:
 
     """
 
-    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 timed_lru_cache(seconds: int, maxsize: int = 128) -> Callable[[F], F]:
 
             return cached_func(*args, **kwargs)
 
-        return cast(F, wrapped_func)
+        return cast(TimedCachedCallable[R], wrapped_func)
 
     return wrapper_cache

{python_backpack-2.0.1 → python_backpack-2.0.3}/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,7 +32,7 @@ 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)
@@ -36,13 +40,16 @@ def replace_strings_in_file(ascii_file: str, strings: list, new_string: str) ->
             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:

{python_backpack-2.0.1 → python_backpack-2.0.3}/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:

{python_backpack-2.0.1 → python_backpack-2.0.3}/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 @@ class JsonMetaFile:
         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 @@ class JsonMetaFile:
             '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(),
         }
 

{python_backpack-2.0.1 → python_backpack-2.0.3}/backpack/json_user_settings.py

@@ -27,7 +27,7 @@ class JsonUserSettings:
             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()
@@ -35,7 +35,7 @@ class JsonUserSettings:
     @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 @@ class JsonUserSettings:
 
         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

{python_backpack-2.0.1 → python_backpack-2.0.3}/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
 

{python_backpack-2.0.1 → python_backpack-2.0.3}/backpack/strings.py

@@ -4,7 +4,6 @@
 # https://github.com/MaxRocamora/python-backpack
 # ----------------------------------------------------------------------------------------
 
-import contextlib
 import re
 
 
@@ -29,30 +28,25 @@ def normalize_input_string(
         str: reformatted string
     """
 
-    # re-encode string to valid chars
-    with contextlib.suppress(UnicodeDecodeError):
-        regex = re.sub('[^A-Za-z0-9 _-]+', '', input_string)
-
-    for char in regex:
-        # replacing " " for replacer
-        if under_spaces and char == ' ':
-            regex = regex.replace(' ', replacer)
-
-        # replacing "-" for replacer
-        if under_hyphen and char == '-':
-            regex = regex.replace('-', replacer)
+    regex = re.sub(r'[^A-Za-z0-9 _-]+', '', input_string)
+    if under_spaces:
+        regex = regex.replace(' ', replacer)
+    if under_hyphen:
+        regex = regex.replace('-', replacer)
 
     return regex
 
 
 def begin_or_end_with_numbers(input_string: str) -> bool:
     """Returns true if the input string begins or ends with number."""
-    return _char_is_number(input_string[0]) or _char_is_number(input_string[-1])
+    return bool(input_string) and (
+        _char_is_number(input_string[0]) or _char_is_number(input_string[-1])
+    )
 
 
 def begin_with_number(input_string: str) -> bool:
     """Returns true if the input string begins with numbers."""
-    return _char_is_number(input_string[0])
+    return bool(input_string) and _char_is_number(input_string[0])
 
 
 def has_numbers(input_string: str) -> bool: