zero-3rdparty 0.101.0__tar.gz

zero_3rdparty-0.101.0/.gitignore

@@ -0,0 +1,36 @@
+# path-sync copy -n python-template
+
+# === DO_NOT_EDIT: path-sync gitignore ===
+# Python bytecode
+__pycache__/
+*.pyc
+*.pyo
+
+# Virtual environments
+.venv/
+venv/
+
+# Build artifacts
+dist/
+build/
+*.egg-info/
+
+# Coverage
+.coverage
+htmlcov/
+coverage.xml
+
+# Cache directories
+.ruff_cache/
+.pytest_cache/
+.mypy_cache/
+
+# IDE
+.idea/
+*.iml
+.vscode/
+
+# pkg-ext dev mode files
+.groups-dev.yaml
+CHANGELOG-dev.md
+# === OK_EDIT: path-sync gitignore ===

zero_3rdparty-0.101.0/PKG-INFO

@@ -0,0 +1,15 @@
+Metadata-Version: 2.4
+Name: zero-3rdparty
+Version: 0.101.0
+Author-email: EspenAlbert <espen.albert1@gmail.com>
+License-Expression: MIT
+Classifier: Development Status :: 4 - Beta
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+
+# Zero 3rd-party
+[![codecov](https://codecov.io/gh/EspenAlbert/zero-3rdparty/graph/badge.svg?token=47B15SDYMF)](https://codecov.io/gh/EspenAlbert/zero-3rdparty)
+
+- May add some examples here...

zero_3rdparty-0.101.0/pyproject.toml

@@ -0,0 +1,105 @@
+[project]
+name = "zero-3rdparty"
+version = "0.101.0"
+requires-python = ">=3.13"
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+]
+readme = "readme.md"
+license = "MIT"
+keywords = []
+authors = [
+  { name = "EspenAlbert", email = "espen.albert1@gmail.com" },
+]
+
+[build-system]
+requires = [
+  "hatchling",
+]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.sdist]
+include = [
+  "zero_3rdparty/*.py",
+  "zero_3rdparty/_internal/*.py",
+  "zero_3rdparty/py.typed",
+]
+exclude = [
+  "*_examples.py",
+  "*_test.py",
+  "conftest.py",
+  "test_*.json",
+]
+
+[tool.pkg-ext]
+tag_prefix = "v"
+
+[tool.pkg-ext.groups.sections]
+examples_enabled = true
+examples_include = [
+  "CommentConfig",
+  "parse_sections",
+  "replace_sections",
+  "get_comment_config",
+]
+
+[tool.ruff]
+line-length = 120
+target-version = "py313"
+
+[tool.ruff.lint]
+extend-ignore = [
+  "E501",
+  "UP006",
+  "UP007",
+  "UP035",
+  "UP040",
+  "UP046",
+  "UP047",
+]
+extend-select = [
+  "Q",
+  "RUF100",
+  "C90",
+  "UP",
+  "I",
+  "T",
+]
+
+[tool.pytest.ini_options]
+addopts = "-s -vv --log-cli-level=INFO"
+python_files = [
+  "*_test.py",
+  "test_*.py",
+]
+
+[tool.coverage.report]
+omit = [
+  "*_test.py",
+]
+exclude_lines = [
+  "no cov",
+  "if __name__ == .__main__.:",
+]
+
+[tool.pyright]
+include = [
+  "zero_3rdparty",
+]
+exclude = [
+  "zero_3rdparty/humps.py",
+  "zero_3rdparty/timeparse.py",
+]
+
+[dependency-groups]
+dev = [
+  "pytest>=9.0",
+  "pytest-cov>=7.0",
+  "pytest-freezer>=0.4.9",
+  "ruff>=0.14",
+  "xdoctest>=1.3.0",
+  "pyright>=1.1.404",
+  "pydantic",
+]

zero_3rdparty-0.101.0/readme.md

@@ -0,0 +1,4 @@
+# Zero 3rd-party
+[![codecov](https://codecov.io/gh/EspenAlbert/zero-3rdparty/graph/badge.svg?token=47B15SDYMF)](https://codecov.io/gh/EspenAlbert/zero-3rdparty)
+
+- May add some examples here...

zero_3rdparty-0.101.0/zero_3rdparty/__init__.py

@@ -0,0 +1,8 @@
+# Generated by pkg-ext
+# flake8: noqa
+from zero_3rdparty import sections
+
+VERSION = "0.101.0"
+__all__ = [
+    "sections",
+]

zero_3rdparty-0.101.0/zero_3rdparty/_internal/sections.py

@@ -0,0 +1,257 @@
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from pathlib import Path
+
+
+def slug(text: str) -> str:
+    """Convert text to lowercase slug suitable for section marker IDs."""
+    s = re.sub(r"[^\w\s-]", "", text.lower())
+    return re.sub(r"[-\s]+", "_", s).strip("_")
+
+
+@dataclass(frozen=True)
+class CommentConfig:
+    prefix: str
+    suffix: str = ""
+
+
+@dataclass
+class Section:
+    id: str
+    content: str
+    start_line: int
+    end_line: int
+
+
+EXTENSION_COMMENT_MAP: dict[str, CommentConfig] = {
+    # Hash comments
+    ".py": CommentConfig("#"),
+    ".yaml": CommentConfig("#"),
+    ".yml": CommentConfig("#"),
+    ".toml": CommentConfig("#"),
+    ".sh": CommentConfig("#"),
+    ".bash": CommentConfig("#"),
+    ".zsh": CommentConfig("#"),
+    ".r": CommentConfig("#"),
+    ".R": CommentConfig("#"),
+    # HTML-style comments
+    ".md": CommentConfig("<!--", " -->"),
+    ".mdc": CommentConfig("<!--", " -->"),
+    ".html": CommentConfig("<!--", " -->"),
+    ".xml": CommentConfig("<!--", " -->"),
+    ".svg": CommentConfig("<!--", " -->"),
+    # C-style line comments
+    ".js": CommentConfig("//"),
+    ".ts": CommentConfig("//"),
+    ".jsx": CommentConfig("//"),
+    ".tsx": CommentConfig("//"),
+    ".go": CommentConfig("//"),
+    ".c": CommentConfig("//"),
+    ".cpp": CommentConfig("//"),
+    ".h": CommentConfig("//"),
+    ".java": CommentConfig("//"),
+    ".kt": CommentConfig("//"),
+    ".swift": CommentConfig("//"),
+    ".rs": CommentConfig("//"),
+    ".scala": CommentConfig("//"),
+    ".groovy": CommentConfig("//"),
+    # C-style block comments (single line)
+    ".css": CommentConfig("/*", " */"),
+    ".scss": CommentConfig("/*", " */"),
+    ".less": CommentConfig("/*", " */"),
+    # SQL
+    ".sql": CommentConfig("--"),
+    # Lua
+    ".lua": CommentConfig("--"),
+}
+
+FILENAME_COMMENT_MAP: dict[str, CommentConfig] = {
+    "justfile": CommentConfig("#"),
+    "Makefile": CommentConfig("#"),
+    "Dockerfile": CommentConfig("#"),
+    ".gitignore": CommentConfig("#"),
+    ".dockerignore": CommentConfig("#"),
+    ".env": CommentConfig("#"),
+    ".editorconfig": CommentConfig("#"),
+}
+
+
+def get_comment_config(path: Path | str, override: CommentConfig | None = None) -> CommentConfig:
+    if override:
+        return override
+    p = Path(path) if isinstance(path, str) else path
+    if config := EXTENSION_COMMENT_MAP.get(p.suffix):
+        return config
+    if config := FILENAME_COMMENT_MAP.get(p.name):
+        return config
+    raise ValueError(f"No comment config for: {p.name} (extension={p.suffix!r})")
+
+
+def _build_start_pattern(tool_name: str, config: CommentConfig) -> re.Pattern[str]:
+    return re.compile(
+        rf"^{re.escape(config.prefix)}\s*===\s*DO_NOT_EDIT:\s*"
+        rf"{re.escape(tool_name)}\s+(?P<id>\w+)\s*==={re.escape(config.suffix)}$",
+        re.MULTILINE,
+    )
+
+
+def _build_end_pattern(tool_name: str, config: CommentConfig) -> re.Pattern[str]:
+    return re.compile(
+        rf"^{re.escape(config.prefix)}\s*===\s*OK_EDIT:\s*"
+        rf"{re.escape(tool_name)}\s+(?P<end_id>\w+)\s*==={re.escape(config.suffix)}$",
+        re.MULTILINE,
+    )
+
+
+def _start_marker(tool_name: str, section_id: str, config: CommentConfig) -> str:
+    return f"{config.prefix} === DO_NOT_EDIT: {tool_name} {section_id} ==={config.suffix}"
+
+
+def _end_marker(tool_name: str, section_id: str, config: CommentConfig) -> str:
+    return f"{config.prefix} === OK_EDIT: {tool_name} {section_id} ==={config.suffix}"
+
+
+def parse_sections(content: str, tool_name: str, config: CommentConfig) -> list[Section]:
+    start_pattern = _build_start_pattern(tool_name, config)
+    end_pattern = _build_end_pattern(tool_name, config)
+    lines = content.split("\n")
+    sections: list[Section] = []
+    current_id: str | None = None
+    current_start: int = -1
+    content_lines: list[str] = []
+
+    for i, line in enumerate(lines):
+        if start_match := start_pattern.match(line):
+            if current_id is not None:
+                raise ValueError(f"Nested section at line {i}: found '{start_match.group('id')}' inside '{current_id}'")
+            current_id = start_match.group("id")
+            current_start = i
+            content_lines = []
+        elif end_match := end_pattern.match(line):
+            if current_id is None:
+                continue  # standalone OK_EDIT is valid, ignored
+            end_id = end_match.group("end_id")
+            if end_id != current_id:
+                raise ValueError(f"Mismatched section end at line {i}: expected '{current_id}', got '{end_id}'")
+            sections.append(
+                Section(
+                    id=current_id,
+                    content="\n".join(content_lines),
+                    start_line=current_start,
+                    end_line=i,
+                )
+            )
+            current_id = None
+            current_start = -1
+            content_lines = []
+        elif current_id is not None:
+            content_lines.append(line)
+
+    if current_id is not None:
+        raise ValueError(f"Unclosed section '{current_id}' starting at line {current_start}")
+
+    return sections
+
+
+def has_sections(content: str, tool_name: str, config: CommentConfig) -> bool:
+    return bool(_build_start_pattern(tool_name, config).search(content))
+
+
+def extract_sections(content: str, tool_name: str, config: CommentConfig) -> dict[str, str]:
+    return {s.id: s.content for s in parse_sections(content, tool_name, config)}
+
+
+def compare_sections(
+    baseline_content: str,
+    current_content: str,
+    tool_name: str,
+    config: CommentConfig,
+    skip: set[str] | None = None,
+) -> list[str]:
+    """Return section IDs with changes (modified or removed), excluding skipped sections."""
+    skip_ids = skip or set()
+    baseline_secs = extract_sections(baseline_content, tool_name, config)
+    current_secs = extract_sections(current_content, tool_name, config)
+    return [
+        sec_id
+        for sec_id, baseline_text in baseline_secs.items()
+        if sec_id not in skip_ids and baseline_text != current_secs.get(sec_id, "")
+    ]
+
+
+def wrap_section(content: str, section_id: str, tool_name: str, config: CommentConfig) -> str:
+    start = _start_marker(tool_name, section_id, config)
+    end = _end_marker(tool_name, section_id, config)
+    return f"{start}\n{content}\n{end}"
+
+
+def wrap_in_default_section(content: str, tool_name: str, config: CommentConfig) -> str:
+    return wrap_section(content, "default", tool_name, config)
+
+
+def replace_sections(
+    dest_content: str,
+    src_sections: dict[str, str],
+    tool_name: str,
+    config: CommentConfig,
+    skip_sections: list[str] | None = None,
+) -> str:
+    """Replace sections in dest_content with src_sections, excluding skipped sections. New sections are added at the end"""
+    skip = set(skip_sections or [])
+    dest_parsed = parse_sections(dest_content, tool_name, config)
+    dest_ids = {s.id for s in dest_parsed}
+    dest_sections = {s.id: s.content for s in dest_parsed}
+
+    start_pattern = _build_start_pattern(tool_name, config)
+    end_pattern = _build_end_pattern(tool_name, config)
+    lines = dest_content.split("\n")
+    result: list[str] = []
+
+    current_section_id: str | None = None
+    for line in lines:
+        if start_match := start_pattern.match(line):
+            current_section_id = start_match.group("id")
+            result.append(line)
+        elif end_pattern.match(line):
+            if current_section_id:
+                should_replace = current_section_id in src_sections and current_section_id not in skip
+                section_content = (
+                    src_sections[current_section_id] if should_replace else dest_sections.get(current_section_id, "")
+                )
+                if section_content:
+                    result.append(section_content)
+            result.append(line)
+            current_section_id = None
+        elif current_section_id is None:
+            result.append(line)
+
+    # Append new sections from source not in dest
+    for sid in src_sections:
+        if sid not in dest_ids and sid not in skip:
+            result.extend(
+                (
+                    _start_marker(tool_name, sid, config),
+                    src_sections[sid],
+                    _end_marker(tool_name, sid, config),
+                )
+            )
+
+    return "\n".join(result)
+
+
+# Path-based convenience functions
+def parse_sections_from_path(path: Path, tool_name: str) -> list[Section]:
+    config = get_comment_config(path)
+    return parse_sections(path.read_text(), tool_name, config)
+
+
+def has_sections_in_path(path: Path, tool_name: str) -> bool:
+    config = get_comment_config(path)
+    return has_sections(path.read_text(), tool_name, config)
+
+
+def extract_sections_from_path(path: Path, tool_name: str) -> dict[str, str]:
+    config = get_comment_config(path)
+    return extract_sections(path.read_text(), tool_name, config)

zero_3rdparty-0.101.0/zero_3rdparty/cache_ttl.py

@@ -0,0 +1,78 @@
+from __future__ import annotations
+
+from collections import defaultdict
+from collections.abc import Hashable
+from functools import wraps
+from inspect import signature
+from time import monotonic
+from typing import Any, Callable, ParamSpec, TypeVar
+
+T = TypeVar("T")
+P = ParamSpec("P")
+_sentinel = object()
+
+
+def _wrap_func(func, seconds):
+    expire_result = (0, _sentinel)
+
+    @wraps(func)
+    def inner(*args, **kwargs):
+        nonlocal expire_result
+        now_seconds = monotonic()
+        expire, call_result = expire_result
+        if now_seconds < expire and call_result is not _sentinel:
+            return call_result
+        call_result = func(*args, **kwargs)
+        expire_result = (now_seconds + seconds, call_result)
+        return call_result
+
+    def clear():
+        nonlocal expire_result
+        expire_result = (0, _sentinel)
+
+    inner.clear = clear  # type: ignore
+    return inner
+
+
+def _wrap_method(seconds: float, instance_key: Callable[[T], Hashable], meth: Callable[P, Any]):
+    expire_times: dict[Hashable, tuple[float, Any]] = defaultdict(lambda: (0, _sentinel))
+
+    @wraps(meth)
+    def inner(self, *args, **kwargs):
+        now_seconds = monotonic()
+        key = instance_key(self)
+        expire, call_result = expire_times[key]
+        if now_seconds < expire and call_result is not _sentinel:
+            return call_result
+        call_result = meth(self, *args, **kwargs)  # type: ignore
+        expire_times[key] = now_seconds + seconds, call_result
+        return call_result
+
+    def clear():
+        nonlocal expire_times
+        keys = list(expire_times.keys())
+        for key in keys:
+            expire_times[key] = (0, _sentinel)
+
+    inner.clear = clear  # type: ignore
+    return inner
+
+
+def cache_ttl(seconds: float | int) -> Callable[[Callable[P, T]], Callable[P, T]]:
+    """simple decorator if you want to cache the results of a call ignoring arguments
+    Warning:
+        1. Only caches a 'single value'
+        2. Expects it to be a method if 'self' is in parameters
+    '"""
+    assert isinstance(seconds, float | int), "ttl seconds must be int/float"
+
+    def decorator(func: Callable[P, T]) -> Callable[P, T]:
+        if "self" in signature(func).parameters:
+            return _wrap_method(seconds, id, func)
+        return _wrap_func(func, seconds)  # type: ignore
+
+    return decorator
+
+
+def clear_cache(func):
+    func.clear()

zero_3rdparty-0.101.0/zero_3rdparty/closable_queue.py

@@ -0,0 +1,97 @@
+from __future__ import annotations
+
+import logging
+import threading
+from collections.abc import Iterable
+from contextlib import suppress
+from functools import partial
+from queue import Empty, Queue
+from threading import RLock
+from typing import Generator, Generic, TypeVar
+
+logger = logging.getLogger(__name__)
+
+QueueT = TypeVar("QueueT")
+
+_empty = object()
+
+
+class QueueIsClosed(Exception):
+    pass
+
+
+def _raise_queue_is_closed(item: object, *, queue: ClosableQueue, **kwargs):
+    if item is not ClosableQueue.SENTINEL:
+        raise QueueIsClosed
+    Queue.put(queue, item, **kwargs)
+
+
+class ClosableQueue(Queue[QueueT], Generic[QueueT]):
+    SENTINEL = object()
+    __QUEUES: list[ClosableQueue] = []
+
+    def __init__(self, maxsize: int = 0):  # 0 == infinite
+        super().__init__(maxsize=maxsize)
+        self.__QUEUES.append(self)
+        # ensure close doesn't block and can set raise error
+        self.mutex = RLock()  # type: ignore
+
+        self.not_empty = threading.Condition(self.mutex)
+        self.not_full = threading.Condition(self.mutex)
+        self.all_tasks_done = threading.Condition(self.mutex)
+
+    def close(self):
+        with self.mutex:
+            self.put(self.SENTINEL)  # type: ignore
+            self.put = partial(_raise_queue_is_closed, queue=self)  # type: ignore
+        with suppress(Exception):
+            self.__QUEUES.remove(self)
+
+    def close_safely(self):
+        with suppress(QueueIsClosed):
+            self.close()
+
+    def __iter__(self) -> Generator[QueueT]:
+        try:
+            while True:
+                item = super().get(block=True)
+                if item is self.SENTINEL:
+                    with self.mutex:
+                        # ensure next iterator will finish immediately
+                        self.queue.append(item)
+                        self.not_empty.notify()
+                    return  # Cause the thread to exit
+                yield item
+        except BaseException as e:
+            logger.exception(e)
+        finally:
+            with suppress(ValueError):
+                self.task_done()
+
+    def pop(self, default=_empty):
+        try:
+            out = self.get_nowait()
+        except Empty:
+            return default
+        else:
+            if out is self.SENTINEL:
+                self.put(self.SENTINEL)  # type: ignore # ensure next iterator will finish immediately
+            return out
+
+    def iter_non_blocking(self) -> Iterable[QueueT]:
+        next_or_sentinel = partial(self.pop, self.SENTINEL)
+        return iter(next_or_sentinel, self.SENTINEL)  # type: ignore
+
+    @classmethod
+    def close_all(cls):
+        if cls.__QUEUES:
+            logger.info("closing all queues")
+            for q in list(cls.__QUEUES):  # avoid modification during iteration
+                q.close()
+
+    def get(self, block: bool = True, timeout: float | None = None) -> QueueT:
+        item = super().get(block, timeout)
+        if item is self.SENTINEL:
+            self.queue.append(self.SENTINEL)
+            raise QueueIsClosed
+        return item

zero_3rdparty-0.101.0/zero_3rdparty/dataclass_utils.py

@@ -0,0 +1,37 @@
+from __future__ import annotations
+
+from collections.abc import Container
+from dataclasses import fields
+from typing import Any, Callable, TypeVar
+
+T = TypeVar("T")
+
+
+def field_names(cls: type[T] | T) -> list[str]:
+    return [f.name for f in fields(cls)]  # type: ignore
+
+
+def values(instance: object) -> list:
+    return [getattr(instance, name) for name in field_names(instance)]
+
+
+def copy_dataclass(instance: T, exclude: Container[str] | None = None, update: dict | None = None) -> T:
+    if exclude:
+
+        def include(field_name: str):
+            return field_name not in exclude  # type: ignore
+
+        kwargs = as_dict(instance, filter=include)
+    else:
+        kwargs = as_dict(instance)
+    if update:
+        kwargs.update(update)
+    return type(instance)(**kwargs)
+
+
+def as_dict(instance: object, filter: Callable[[str], bool] | None = None) -> dict[str, Any]:
+    return {
+        field_name: getattr(instance, field_name)
+        for field_name in field_names(instance)
+        if filter is None or filter(field_name)
+    }