pyazrico 0.1.0__tar.gz

pyazrico-0.1.0/.gitignore

@@ -0,0 +1,14 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.venv/
+venv/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+.idea/
+.vscode/

pyazrico-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Azrideus
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pyazrico-0.1.0/PKG-INFO

@@ -0,0 +1,76 @@
+Metadata-Version: 2.5
+Name: pyazrico
+Version: 0.1.0
+Summary: Shared utilities used across Azrico Python packages.
+Author-email: Azrideus <gebraengineer@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: helpers,utilities
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-cov>=5; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Requires-Dist: twine>=5; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# pyazrico
+
+Shared utilities used across my Python packages.
+
+Installed as `pyazrico`, imported as `azrico`.
+
+## Installation
+
+```bash
+pip install pyazrico
+```
+
+## Usage
+
+```python
+from azrico import str_utils
+```
+
+## Modules
+
+| Module            | Description       |
+| ----------------- | ----------------- |
+| `azrico.str_utils` | String utilities |
+
+## Development
+
+```bash
+python -m venv .venv
+.venv\Scripts\activate          # Windows
+# source .venv/bin/activate     # macOS / Linux
+pip install -e ".[dev]"
+
+pytest          # run tests
+ruff check .    # lint
+mypy            # type-check
+```
+
+## Releasing to PyPI
+
+1. Bump `__version__` in `src/azrico/__init__.py`.
+2. Build and upload:
+
+   ```bash
+   rm -rf dist
+   python -m build
+   twine check dist/*
+   twine upload dist/*          # or --repository testpypi first
+   ```
+
+## License
+
+MIT

pyazrico-0.1.0/README.md

@@ -0,0 +1,52 @@
+# pyazrico
+
+Shared utilities used across my Python packages.
+
+Installed as `pyazrico`, imported as `azrico`.
+
+## Installation
+
+```bash
+pip install pyazrico
+```
+
+## Usage
+
+```python
+from azrico import str_utils
+```
+
+## Modules
+
+| Module            | Description       |
+| ----------------- | ----------------- |
+| `azrico.str_utils` | String utilities |
+
+## Development
+
+```bash
+python -m venv .venv
+.venv\Scripts\activate          # Windows
+# source .venv/bin/activate     # macOS / Linux
+pip install -e ".[dev]"
+
+pytest          # run tests
+ruff check .    # lint
+mypy            # type-check
+```
+
+## Releasing to PyPI
+
+1. Bump `__version__` in `src/azrico/__init__.py`.
+2. Build and upload:
+
+   ```bash
+   rm -rf dist
+   python -m build
+   twine check dist/*
+   twine upload dist/*          # or --repository testpypi first
+   ```
+
+## License
+
+MIT

pyazrico-0.1.0/pyproject.toml

@@ -0,0 +1,62 @@
+[build-system]
+requires = ["hatchling>=1.26"]
+build-backend = "hatchling.build"
+
+[project]
+name = "pyazrico"
+dynamic = ["version"]
+description = "Shared utilities used across Azrico Python packages."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Azrideus", email = "gebraengineer@gmail.com" }]
+keywords = ["utilities", "helpers"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Typing :: Typed",
+]
+dependencies = []
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8",
+    "pytest-cov>=5",
+    "ruff>=0.6",
+    "mypy>=1.10",
+    "build>=1.2",
+    "twine>=5",
+]
+
+# [project.urls]
+# Homepage = "https://github.com/<user>/pyazrico"
+# Issues = "https://github.com/<user>/pyazrico/issues"
+
+[tool.hatch.version]
+path = "src/azrico/__init__.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/azrico"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/azrico", "tests", "README.md", "LICENSE"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-ra"
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "B", "UP"]
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+files = ["src"]

pyazrico-0.1.0/src/azrico/NameMatcher.py

@@ -0,0 +1,41 @@
+import re
+from collections.abc import Iterable
+
+
+class NameMatcher:
+    """Exact match, then a unique prefix ("mon"), then a unique per-part prefix ("g-1", "g1" -> "guard-1").
+
+    Parts are runs of letters or digits; a letter part matches by prefix, a number part only in full.
+    """
+
+    @staticmethod
+    def match(query: str, names: Iterable[str]) -> list[str]:
+        """The single resolved name, or every candidate when ambiguous, or [] when nothing matches."""
+        query = query.casefold()
+        words = NameMatcher._parts(query)
+        exact: list[str] = []
+        prefix: list[str] = []
+        parts: list[str] = []
+        for name in names:
+            key = name.casefold()
+            key_words = NameMatcher._parts(key)
+            if key == query:
+                exact.append(name)
+            if key.startswith(query):
+                prefix.append(name)
+            if len(words) == len(key_words) and all(
+                map(NameMatcher._part_matches, key_words, words)
+            ):
+                parts.append(name)
+        for found in (exact, prefix, parts):
+            if len(found) == 1:
+                return found
+        return sorted(set(prefix + parts))
+
+    @staticmethod
+    def _parts(name: str) -> list[str]:
+        return re.findall(r"[^\W\d_]+|\d+", name)
+
+    @staticmethod
+    def _part_matches(key_word: str, word: str) -> bool:
+        return key_word == word if word.isdigit() else key_word.startswith(word)

pyazrico-0.1.0/src/azrico/__init__.py

@@ -0,0 +1,8 @@
+"""Azrico: shared utilities used across Azrico Python packages."""
+
+from .classes import CapacityDict
+from .NameMatcher import NameMatcher
+
+__version__ = "0.1.0"
+
+__all__ = ["CapacityDict", "NameMatcher", "__version__"]

pyazrico-0.1.0/src/azrico/classes/CapacityDict.py

@@ -0,0 +1,17 @@
+from collections import OrderedDict
+
+
+class CapacityDict(OrderedDict):
+    """
+    Dict with a maximum capacity. When the capacity is exceeded, the oldest item is removed.
+    """
+
+    def __init__(self, capacity: int, *args, **kwargs):
+        self.capacity = capacity
+        super().__init__(*args, **kwargs)
+
+    def __setitem__(self, key, value):
+        # If the key is new and we are at capacity, evict the oldest item
+        if key not in self and len(self) >= self.capacity:
+            self.popitem(last=False)  # last=False pops the FIFO (oldest) item
+        super().__setitem__(key, value)

pyazrico-0.1.0/src/azrico/classes/__init__.py

@@ -0,0 +1,3 @@
+from .CapacityDict import CapacityDict
+
+__all__ = ["CapacityDict"]

pyazrico-0.1.0/src/azrico/file_utils.py

@@ -0,0 +1,35 @@
+"""File utilities."""
+
+import glob
+import hashlib
+import os
+
+# Defaults for `file_list_hashed`.
+SKIP_EXTS = frozenset({".pyc", ".pyo", ".tmp", ".log"})
+SKIP_DIR_NAMES = frozenset({".git", "__pycache__", "node_modules", ".venv", "venv"})
+
+
+def hash_file(path) -> str:
+    """SHA-256 of a file's contents, streamed in 1 MiB blocks."""
+    digest = hashlib.sha256()
+    with open(path, "rb") as f:
+        for block in iter(lambda: f.read(1024 * 1024), b""):
+            digest.update(block)
+    return digest.hexdigest()
+
+
+def file_list_hashed(
+    requested_dir, *, skip_exts=SKIP_EXTS, skip_dir_names=SKIP_DIR_NAMES
+) -> dict[str, str]:
+    """Map every file under `requested_dir` (recursive) to its content hash, skipping
+    `skip_dir_names` directories and `skip_exts` file types."""
+    files = {}
+    for path in glob.glob(f"{requested_dir}/**/*", recursive=True):
+        if os.path.isdir(path):
+            continue
+        if any(part in skip_dir_names for part in path.split(os.sep)):
+            continue
+        if os.path.splitext(path)[1].lower() in skip_exts:
+            continue
+        files[path] = hash_file(path)
+    return files

pyazrico-0.1.0/src/azrico/parse_utils.py

@@ -0,0 +1,23 @@
+def parse_bool(value) -> bool:
+    """Parse common string boolean values, falling back to normal truthiness."""
+    if isinstance(value, str):
+        return value.strip().lower() in (
+            "1",
+            "true",
+            "on",
+            "ok",
+            "yes",
+            "y",
+            "ye",
+            "yep",
+            "yeah",
+            "continue",
+            "go",
+            "good",
+            "sure",
+            "okay",
+            "proceed",
+            "confirm",
+            "confirmed",
+        )
+    return bool(value)

pyazrico-0.1.0/src/azrico/str_utils.py

@@ -0,0 +1,91 @@
+"""String utilities."""
+
+import json
+import re
+
+
+def str_loose_match(a: str, b: str) -> bool:
+    """Case-insensitive equality after stripping all whitespace and dash and underscores."""
+    bad_chars = re.compile(r"[\s\-_]+")
+    a = bad_chars.sub("", a or "").casefold()
+    b = bad_chars.sub("", b or "").casefold()
+    return a == b
+
+
+def str_loose_in(value: str, items) -> bool:
+    """`value in items`, compared with `str_loose_match`."""
+    return any(str_loose_match(value, item) for item in items or ())
+
+
+def slugify(text: str, maxlen: int = 48) -> str:
+    """Lowercase [a-z0-9-] slug, truncated at a word boundary (no mid-word cut).
+    Empty / all-punctuation input yields "default"."""
+    return m_sanitize_text(text, replacement="-", maxlen=maxlen, default="default")
+
+
+def m_sanitize_text(
+    value: str,
+    *,
+    keep: str = "",
+    replacement: str = "",
+    lowercase: bool = True,
+    maxlen: int = 0,
+    default: str = "",
+) -> str:
+    """Keep only [A-Za-z0-9] plus the punctuation listed in `keep`.
+
+    Every run of other characters becomes `replacement`, which is then trimmed
+    off both ends. `keep` is "_-" for slugs, "._-" for filenames, "" (the
+    default) for alphanumeric-only. `maxlen` truncates at the last
+    `replacement` boundary so a word is never cut in half, and `default` is
+    returned when nothing survives.
+    """
+    s = re.sub(f"[^A-Za-z0-9{re.escape(keep)}]+", replacement, (value or "").strip())
+    if lowercase:
+        s = s.lower()
+    if replacement:
+        s = s.strip(replacement)
+        if maxlen and len(s) > maxlen:
+            cut = s[:maxlen]
+            if replacement in cut[maxlen // 2 :]:
+                cut = cut[: cut.rfind(replacement)]
+            s = cut.strip(replacement)
+    elif maxlen:
+        s = s[:maxlen]
+    return s or default
+
+
+def basic_str_array(v, whitespace_seperated: bool = False, unique: bool = False) -> list[str]:
+    """
+    converts input to a list
+    split by , \n | or \\, and strips whitespace from each element.
+    unique=True drops duplicates, keeping first-seen order.
+    A bracketed string is read as an array: "[1, 2]" and '["1", "2"]' -> ["1", "2"]
+    """
+    if isinstance(v, str) and v.strip().startswith("[") and v.strip().endswith("]"):
+        try:
+            v = json.loads(v)
+        except ValueError:
+            v = [x.strip().strip("\"'") for x in v.strip()[1:-1].split(",")]
+    if isinstance(v, str):
+        has_comma = "," in v
+        v = v.replace("\\", ",").replace("\n", ",").replace("|", ",")
+        # a comma seperated string should not be considred whitespace seperated.
+        if not has_comma and whitespace_seperated:
+            v = re.sub(r"\s+", ",", v)
+        v = v.split(",")
+    if not isinstance(v, list):
+        return []
+    items = [str(x).strip() for x in v if str(x).strip()]
+    return list(dict.fromkeys(items)) if unique else items
+
+
+def normalize_extensions(extensions) -> list[str]:
+    """normalize file extensions to a lowercase dotted form
+    `pdf`, `.PDF`, `*.pdf` -> `.pdf`. Duplicates are dropped, order is kept.
+    """
+    return list(
+        dict.fromkeys(
+            "." + ext.lower().lstrip("*.").strip() for ext in (extensions or []) if ext.strip(" *.")
+        )
+    )

pyazrico-0.1.0/tests/test_str_utils.py

@@ -0,0 +1,5 @@
+from azrico import str_utils
+
+
+def test_module_imports() -> None:
+    assert str_utils is not None