dycw-utilities 0.148.4__py3-none-any.whl → 0.174.12__py3-none-any.whl

utilities/tempfile.py

@@ -1,11 +1,17 @@
 from __future__ import annotations
 
+import tempfile
+from contextlib import contextmanager
 from pathlib import Path
-from tempfile import TemporaryDirectory as _TemporaryDirectory
+from shutil import move
+from tempfile import NamedTemporaryFile as _NamedTemporaryFile
 from tempfile import gettempdir as _gettempdir
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, override
+
+from utilities.warnings import suppress_warnings
 
 if TYPE_CHECKING:
+    from collections.abc import Iterator
     from types import TracebackType
 
     from utilities.types import PathLike
@@ -21,13 +27,15 @@ class TemporaryDirectory:
         prefix: str | None = None,
         dir: PathLike | None = None,  # noqa: A002
         ignore_cleanup_errors: bool = False,
+        delete: bool = True,
     ) -> None:
         super().__init__()
-        self._temp_dir = _TemporaryDirectory(
+        self._temp_dir = _TemporaryDirectoryNoResourceWarning(
             suffix=suffix,
             prefix=prefix,
             dir=dir,
             ignore_cleanup_errors=ignore_cleanup_errors,
+            delete=delete,
         )
         self.path = Path(self._temp_dir.name)
 
@@ -43,6 +51,56 @@ class TemporaryDirectory:
         self._temp_dir.__exit__(exc, val, tb)
 
 
+class _TemporaryDirectoryNoResourceWarning(tempfile.TemporaryDirectory):
+    @classmethod
+    @override
+    def _cleanup(  # pyright: ignore[reportGeneralTypeIssues]
+        cls,
+        name: str,
+        warn_message: str,
+        ignore_errors: bool = False,
+        delete: bool = True,
+    ) -> None:
+        with suppress_warnings(category=ResourceWarning):
+            return super()._cleanup(  # pyright: ignore[reportAttributeAccessIssue]
+                name, warn_message, ignore_errors=ignore_errors, delete=delete
+            )
+
+
+##
+
+
+@contextmanager
+def TemporaryFile(  # noqa: N802
+    *,
+    suffix: str | None = None,
+    prefix: str | None = None,
+    dir: PathLike | None = None,  # noqa: A002
+    ignore_cleanup_errors: bool = False,
+    delete: bool = True,
+    name: str | None = None,
+) -> Iterator[Path]:
+    """Yield a temporary file."""
+    with TemporaryDirectory(
+        suffix=suffix,
+        prefix=prefix,
+        dir=dir,
+        ignore_cleanup_errors=ignore_cleanup_errors,
+        delete=delete,
+    ) as temp_dir:
+        temp_file = _NamedTemporaryFile(  # noqa: SIM115
+            dir=temp_dir, delete=delete, delete_on_close=False
+        )
+        if name is None:
+            yield temp_dir / temp_file.name
+        else:
+            _ = move(temp_dir / temp_file.name, temp_dir / name)
+            yield temp_dir / name
+
+
+##
+
+
 def gettempdir() -> Path:
     """Get the name of the directory used for temporary files."""
     return Path(_gettempdir())
@@ -51,4 +109,4 @@ def gettempdir() -> Path:
 TEMP_DIR = gettempdir()
 
 
-__all__ = ["TEMP_DIR", "TemporaryDirectory", "gettempdir"]
+__all__ = ["TEMP_DIR", "TemporaryDirectory", "TemporaryFile", "gettempdir"]

utilities/testbook.py

@@ -0,0 +1,50 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+from testbook import testbook
+
+from utilities.pytest import throttle
+from utilities.text import pascal_case
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+    from utilities.types import Delta, PathLike
+
+
+def build_notebook_tester(
+    path: PathLike, /, *, throttle: Delta | None = None, on_try: bool = False
+) -> type[Any]:
+    """Build the notebook tester class."""
+    path = Path(path)
+    name = f"Test{pascal_case(path.stem)}"
+    notebooks = [
+        path_i
+        for path_i in path.rglob("**/*.ipynb")
+        if all(p != ".ipynb_checkpoints" for p in path_i.parts)
+    ]
+    namespace = {
+        f"test_{p.stem.replace('-', '_')}": _build_test_method(
+            p, delta=throttle, on_try=on_try
+        )
+        for p in notebooks
+    }
+    return type(name, (), namespace)
+
+
+def _build_test_method(
+    path: Path, /, *, delta: Delta | None = None, on_try: bool = False
+) -> Callable[..., Any]:
+    @testbook(path, execute=True)
+    def method(self: Any, tb: Any) -> None:
+        _ = (self, tb)  # pragma: no cover
+
+    if delta is not None:
+        method = throttle(delta=delta, on_try=on_try)(method)
+
+    return method
+
+
+__all__ = ["build_notebook_tester"]

utilities/text.py

@@ -2,26 +2,44 @@ from __future__ import annotations
 
 import re
 from collections import deque
+from collections.abc import Callable
 from dataclasses import dataclass
 from itertools import chain
 from os import getpid
-from re import IGNORECASE, Match, escape, search
+from re import IGNORECASE, VERBOSE, escape, search
 from textwrap import dedent
 from threading import get_ident
 from time import time_ns
-from typing import TYPE_CHECKING, Any, Literal, overload, override
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    ClassVar,
+    Literal,
+    assert_never,
+    overload,
+    override,
+)
 from uuid import uuid4
 
 from utilities.iterables import CheckDuplicatesError, check_duplicates, transpose
 from utilities.reprlib import get_repr
+from utilities.sentinel import Sentinel
 
 if TYPE_CHECKING:
     from collections.abc import Iterable, Mapping, Sequence
 
-    from utilities.types import StrStrMapping
+    from utilities.types import MaybeCallableBoolLike, MaybeCallableStr, StrStrMapping
 
 
-DEFAULT_SEPARATOR = ","
+_DEFAULT_SEPARATOR = ","
+
+
+##
+
+
+def kebab_case(text: str, /) -> str:
+    """Convert text into kebab case."""
+    return _kebab_snake_case(text, "-")
 
 
 ##
@@ -67,6 +85,29 @@ class ParseNoneError(Exception):
 ##
 
 
+def pascal_case(text: str, /) -> str:
+    """Convert text to pascal case."""
+    parts = _SPLIT_TEXT.findall(text)
+    parts = [p for p in parts if len(p) >= 1]
+    parts = list(map(_pascal_case_one, parts))
+    return "".join(parts)
+
+
+def _pascal_case_one(text: str, /) -> str:
+    return text if text.isupper() else text.title()
+
+
+##
+
+
+def prompt_bool(prompt: object = "", /, *, confirm: bool = False) -> bool:
+    """Prompt for a boolean."""
+    return True if confirm else parse_bool(input(prompt))
+
+
+##
+
+
 def repr_encode(obj: Any, /) -> bytes:
     """Return the representation of the object encoded as bytes."""
     return repr(obj).encode()
@@ -75,30 +116,15 @@ def repr_encode(obj: Any, /) -> bytes:
 ##
 
 
-_ACRONYM_PATTERN = re.compile(r"([A-Z\d]+)(?=[A-Z\d]|$)")
-_SPACES_PATTERN = re.compile(r"\s+")
-_SPLIT_PATTERN = re.compile(r"([\-_]*[A-Z][^A-Z]*[\-_]*)")
-
-
 def snake_case(text: str, /) -> str:
     """Convert text into snake case."""
-    text = _SPACES_PATTERN.sub("", text)
-    if not text.isupper():
-        text = _ACRONYM_PATTERN.sub(_snake_case_title, text)
-        text = "_".join(s for s in _SPLIT_PATTERN.split(text) if s)
-    while search("__", text):
-        text = text.replace("__", "_")
-    return text.lower()
-
-
-def _snake_case_title(match: Match[str], /) -> str:
-    return match.group(0).title()
+    return _kebab_snake_case(text, "_")
 
 
 ##
 
 
-LIST_SEPARATOR = DEFAULT_SEPARATOR
+LIST_SEPARATOR = _DEFAULT_SEPARATOR
 PAIR_SEPARATOR = "="
 BRACKETS = [("(", ")"), ("[", "]"), ("{", "}")]
 
@@ -108,7 +134,7 @@ def split_key_value_pairs(
     text: str,
     /,
     *,
-    list_separator: str = DEFAULT_SEPARATOR,
+    list_separator: str = _DEFAULT_SEPARATOR,
     pair_separator: str = PAIR_SEPARATOR,
     brackets: Iterable[tuple[str, str]] | None = BRACKETS,
     mapping: Literal[True],
@@ -118,7 +144,7 @@ def split_key_value_pairs(
     text: str,
     /,
     *,
-    list_separator: str = DEFAULT_SEPARATOR,
+    list_separator: str = _DEFAULT_SEPARATOR,
     pair_separator: str = PAIR_SEPARATOR,
     brackets: Iterable[tuple[str, str]] | None = BRACKETS,
     mapping: Literal[False] = False,
@@ -128,7 +154,7 @@ def split_key_value_pairs(
     text: str,
     /,
     *,
-    list_separator: str = DEFAULT_SEPARATOR,
+    list_separator: str = _DEFAULT_SEPARATOR,
     pair_separator: str = PAIR_SEPARATOR,
     brackets: Iterable[tuple[str, str]] | None = BRACKETS,
     mapping: bool = False,
@@ -137,7 +163,7 @@ def split_key_value_pairs(
     text: str,
     /,
     *,
-    list_separator: str = DEFAULT_SEPARATOR,
+    list_separator: str = _DEFAULT_SEPARATOR,
     pair_separator: str = PAIR_SEPARATOR,
     brackets: Iterable[tuple[str, str]] | None = BRACKETS,
     mapping: bool = False,
@@ -196,7 +222,7 @@ def split_str(
     text: str,
     /,
     *,
-    separator: str = DEFAULT_SEPARATOR,
+    separator: str = _DEFAULT_SEPARATOR,
     brackets: Iterable[tuple[str, str]] | None = None,
     n: Literal[1],
 ) -> tuple[str]: ...
@@ -205,7 +231,7 @@ def split_str(
     text: str,
     /,
     *,
-    separator: str = DEFAULT_SEPARATOR,
+    separator: str = _DEFAULT_SEPARATOR,
     brackets: Iterable[tuple[str, str]] | None = None,
     n: Literal[2],
 ) -> tuple[str, str]: ...
@@ -214,7 +240,7 @@ def split_str(
     text: str,
     /,
     *,
-    separator: str = DEFAULT_SEPARATOR,
+    separator: str = _DEFAULT_SEPARATOR,
     brackets: Iterable[tuple[str, str]] | None = None,
     n: Literal[3],
 ) -> tuple[str, str, str]: ...
@@ -223,7 +249,7 @@ def split_str(
     text: str,
     /,
     *,
-    separator: str = DEFAULT_SEPARATOR,
+    separator: str = _DEFAULT_SEPARATOR,
     brackets: Iterable[tuple[str, str]] | None = None,
     n: Literal[4],
 ) -> tuple[str, str, str, str]: ...
@@ -232,7 +258,7 @@ def split_str(
     text: str,
     /,
     *,
-    separator: str = DEFAULT_SEPARATOR,
+    separator: str = _DEFAULT_SEPARATOR,
     brackets: Iterable[tuple[str, str]] | None = None,
     n: Literal[5],
 ) -> tuple[str, str, str, str, str]: ...
@@ -241,18 +267,18 @@ def split_str(
     text: str,
     /,
     *,
-    separator: str = DEFAULT_SEPARATOR,
+    separator: str = _DEFAULT_SEPARATOR,
     brackets: Iterable[tuple[str, str]] | None = None,
     n: int | None = None,
-) -> Sequence[str]: ...
+) -> tuple[str, ...]: ...
 def split_str(
     text: str,
     /,
     *,
-    separator: str = DEFAULT_SEPARATOR,
+    separator: str = _DEFAULT_SEPARATOR,
     brackets: Iterable[tuple[str, str]] | None = None,
     n: int | None = None,
-) -> Sequence[str]:
+) -> tuple[str, ...]:
     """Split a string, with a special provision for the empty string."""
     if text == "":
         texts = []
@@ -263,7 +289,7 @@ def split_str(
     else:
         texts = _split_str_brackets(text, brackets, separator=separator)
     if n is None:
-        return texts
+        return tuple(texts)
     if len(texts) != n:
         raise _SplitStrCountError(text=text, n=n, texts=texts)
     return tuple(texts)
@@ -274,8 +300,8 @@ def _split_str_brackets(
     brackets: Iterable[tuple[str, str]],
     /,
     *,
-    separator: str = DEFAULT_SEPARATOR,
-) -> Sequence[str]:
+    separator: str = _DEFAULT_SEPARATOR,
+) -> list[str]:
     brackets = list(brackets)
     opens, closes = transpose(brackets)
     close_to_open = {close: open_ for open_, close in brackets}
@@ -283,7 +309,7 @@ def _split_str_brackets(
     escapes = map(escape, chain(chain.from_iterable(brackets), [separator]))
     pattern = re.compile("|".join(escapes))
 
-    results: Sequence[str] = []
+    results: list[str] = []
     stack: deque[tuple[str, int]] = deque()
     last = 0
 
@@ -325,7 +351,7 @@ class SplitStrError(Exception):
 @dataclass(kw_only=True, slots=True)
 class _SplitStrCountError(SplitStrError):
     n: int
-    texts: Sequence[str]
+    texts: list[str]
 
     @override
     def __str__(self) -> str:
@@ -365,7 +391,7 @@ class _SplitStrOpeningBracketUnmatchedError(SplitStrError):
 
 
 def join_strs(
-    texts: Iterable[str], /, *, sort: bool = False, separator: str = DEFAULT_SEPARATOR
+    texts: Iterable[str], /, *, sort: bool = False, separator: str = _DEFAULT_SEPARATOR
 ) -> str:
     """Join a collection of strings, with a special provision for the empty list."""
     texts = list(texts)
@@ -378,13 +404,39 @@ def join_strs(
     return separator.join(texts)
 
 
-def _escape_separator(*, separator: str = DEFAULT_SEPARATOR) -> str:
+def _escape_separator(*, separator: str = _DEFAULT_SEPARATOR) -> str:
     return f"\\{separator}"
 
 
 ##
 
 
+class secret_str(str):  # noqa: N801
+    """A string with an obfuscated representation."""
+
+    __slots__ = ("_text",)
+    _REPR: ClassVar[str] = "***"
+
+    def __init__(self, text: str, /) -> None:
+        super().__init__()
+        self._text = text
+
+    @override
+    def __repr__(self) -> str:
+        return self._REPR
+
+    @override
+    def __str__(self) -> str:
+        return self._REPR
+
+    @property
+    def str(self) -> str:
+        return self._text
+
+
+##
+
+
 def str_encode(obj: Any, /) -> bytes:
     """Return the string representation of the object encoded as bytes."""
     return str(obj).encode()
@@ -402,6 +454,50 @@ def strip_and_dedent(text: str, /, *, trailing: bool = False) -> str:
 ##
 
 
+@overload
+def to_bool(bool_: MaybeCallableBoolLike, /) -> bool: ...
+@overload
+def to_bool(bool_: None, /) -> None: ...
+@overload
+def to_bool(bool_: Sentinel, /) -> Sentinel: ...
+def to_bool(
+    bool_: MaybeCallableBoolLike | None | Sentinel, /
+) -> bool | None | Sentinel:
+    """Convert to a bool."""
+    match bool_:
+        case bool() | None | Sentinel():
+            return bool_
+        case str():
+            return parse_bool(bool_)
+        case Callable() as func:
+            return to_bool(func())
+        case never:
+            assert_never(never)
+
+
+##
+
+
+@overload
+def to_str(text: MaybeCallableStr, /) -> str: ...
+@overload
+def to_str(text: None, /) -> None: ...
+@overload
+def to_str(text: Sentinel, /) -> Sentinel: ...
+def to_str(text: MaybeCallableStr | None | Sentinel, /) -> str | None | Sentinel:
+    """Convert to a string."""
+    match text:
+        case str() | None | Sentinel():
+            return text
+        case Callable() as func:
+            return to_str(func())
+        case never:
+            assert_never(never)
+
+
+##
+
+
 def unique_str() -> str:
     """Generate at unique string."""
     now = time_ns()
@@ -411,9 +507,30 @@ def unique_str() -> str:
     return f"{now}_{pid}_{ident}_{key}"
 
 
+##
+
+
+def _kebab_snake_case(text: str, separator: str, /) -> str:
+    """Convert text into kebab/snake case."""
+    leading = bool(search(r"^_", text))
+    trailing = bool(search(r"_$", text))
+    parts = _SPLIT_TEXT.findall(text)
+    parts = (p for p in parts if len(p) >= 1)
+    parts = chain([""] if leading else [], parts, [""] if trailing else [])
+    return separator.join(parts).lower()
+
+
+_SPLIT_TEXT = re.compile(
+    r"""
+    [A-Z]+(?=[A-Z][a-z0-9]) | # all caps followed by Upper+lower or digit (API in APIResponse2)
+    [A-Z]?[a-z]+[0-9]*      | # normal words with optional trailing digits (Text123)
+    [A-Z]+[0-9]*            | # consecutive caps with optional trailing digits (ID2)
+    """,
+    flags=VERBOSE,
+)
+
 __all__ = [
     "BRACKETS",
-    "DEFAULT_SEPARATOR",
     "LIST_SEPARATOR",
     "PAIR_SEPARATOR",
     "ParseBoolError",
@@ -421,13 +538,19 @@ __all__ = [
     "SplitKeyValuePairsError",
     "SplitStrError",
     "join_strs",
+    "kebab_case",
     "parse_bool",
     "parse_none",
+    "pascal_case",
+    "prompt_bool",
     "repr_encode",
+    "secret_str",
     "snake_case",
     "split_key_value_pairs",
     "split_str",
     "str_encode",
     "strip_and_dedent",
+    "to_bool",
+    "to_str",
     "unique_str",
 ]

utilities/timer.py

@@ -56,11 +56,11 @@ class Timer:
 
     @override
     def __repr__(self) -> str:
-        return self.timedelta.format_common_iso()
+        return self.timedelta.format_iso()
 
     @override
     def __str__(self) -> str:
-        return self.timedelta.format_common_iso()
+        return self.timedelta.format_iso()
 
     # comparison