dycw-utilities 0.166.30__py3-none-any.whl → 0.185.8__py3-none-any.whl

utilities/tabulate.py

@@ -0,0 +1,32 @@
+from __future__ import annotations
+
+from textwrap import indent
+from typing import TYPE_CHECKING, Any
+
+from tabulate import tabulate
+
+from utilities.core import get_func_name, normalize_str
+from utilities.text import split_f_str_equals
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+
+def func_param_desc(func: Callable[..., Any], version: str, /, *variables: str) -> str:
+    """Generate a string describing a function & its parameters."""
+    name = get_func_name(func)
+    table = indent(params_table(*variables), "  ")
+    return normalize_str(f"""\
+Running {name!r} (version {version}) with:
+{table}
+""")
+
+
+def params_table(*variables: str) -> str:
+    """Generate a table of parameter names and values."""
+    data = list(map(split_f_str_equals, variables))
+    table = tabulate(data, tablefmt="rounded_outline")
+    return normalize_str(table)
+
+
+__all__ = ["func_param_desc", "params_table"]

utilities/testbook.py

@@ -5,17 +5,17 @@ from typing import TYPE_CHECKING, Any
 
 from testbook import testbook
 
-from utilities.pytest import throttle
-from utilities.text import pascal_case
+from utilities.core import pascal_case
+from utilities.pytest import throttle_test
 
 if TYPE_CHECKING:
     from collections.abc import Callable
 
-    from utilities.types import Delta, PathLike
+    from utilities.types import Duration, PathLike
 
 
 def build_notebook_tester(
-    path: PathLike, /, *, throttle: Delta | None = None, on_try: bool = False
+    path: PathLike, /, *, throttle: Duration | None = None, on_try: bool = False
 ) -> type[Any]:
     """Build the notebook tester class."""
     path = Path(path)
@@ -27,7 +27,7 @@ def build_notebook_tester(
     ]
     namespace = {
         f"test_{p.stem.replace('-', '_')}": _build_test_method(
-            p, delta=throttle, on_try=on_try
+            p, duration=throttle, on_try=on_try
         )
         for p in notebooks
     }
@@ -35,14 +35,14 @@ def build_notebook_tester(
 
 
 def _build_test_method(
-    path: Path, /, *, delta: Delta | None = None, on_try: bool = False
+    path: Path, /, *, duration: Duration | 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)
+    if duration is not None:
+        method = throttle_test(duration=duration, on_try=on_try)(method)
 
     return method
 

utilities/text.py

@@ -5,11 +5,7 @@ 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, VERBOSE, escape, search
-from textwrap import dedent
-from threading import get_ident
-from time import time_ns
+from re import IGNORECASE, escape, search
 from typing import (
     TYPE_CHECKING,
     Any,
@@ -19,11 +15,10 @@ from typing import (
     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
+from utilities.constants import BRACKETS, LIST_SEPARATOR, PAIR_SEPARATOR, Sentinel
+from utilities.core import repr_, transpose
+from utilities.iterables import CheckDuplicatesError, check_duplicates
 
 if TYPE_CHECKING:
     from collections.abc import Iterable, Mapping, Sequence
@@ -31,9 +26,6 @@ if TYPE_CHECKING:
     from utilities.types import MaybeCallableBoolLike, MaybeCallableStr, StrStrMapping
 
 
-DEFAULT_SEPARATOR = ","
-
-
 ##
 
 
@@ -77,21 +69,6 @@ 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))
@@ -100,47 +77,21 @@ def prompt_bool(prompt: object = "", /, *, confirm: bool = False) -> bool:
 ##
 
 
-def repr_encode(obj: Any, /) -> bytes:
-    """Return the representation of the object encoded as bytes."""
-    return repr(obj).encode()
+def split_f_str_equals(text: str, /) -> tuple[str, str]:
+    """Split an `f`-string with `=`."""
+    first, second = text.split(sep="=", maxsplit=1)
+    return first, second
 
 
 ##
 
 
-def snake_case(text: str, /) -> str:
-    """Convert text into 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 "_".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,
-)
-
-##
-
-
-LIST_SEPARATOR = DEFAULT_SEPARATOR
-PAIR_SEPARATOR = "="
-BRACKETS = [("(", ")"), ("[", "]"), ("{", "}")]
-
-
 @overload
 def split_key_value_pairs(
     text: str,
     /,
     *,
-    list_separator: str = DEFAULT_SEPARATOR,
+    list_separator: str = LIST_SEPARATOR,
     pair_separator: str = PAIR_SEPARATOR,
     brackets: Iterable[tuple[str, str]] | None = BRACKETS,
     mapping: Literal[True],
@@ -150,7 +101,7 @@ def split_key_value_pairs(
     text: str,
     /,
     *,
-    list_separator: str = DEFAULT_SEPARATOR,
+    list_separator: str = LIST_SEPARATOR,
     pair_separator: str = PAIR_SEPARATOR,
     brackets: Iterable[tuple[str, str]] | None = BRACKETS,
     mapping: Literal[False] = False,
@@ -160,7 +111,7 @@ def split_key_value_pairs(
     text: str,
     /,
     *,
-    list_separator: str = DEFAULT_SEPARATOR,
+    list_separator: str = LIST_SEPARATOR,
     pair_separator: str = PAIR_SEPARATOR,
     brackets: Iterable[tuple[str, str]] | None = BRACKETS,
     mapping: bool = False,
@@ -169,7 +120,7 @@ def split_key_value_pairs(
     text: str,
     /,
     *,
-    list_separator: str = DEFAULT_SEPARATOR,
+    list_separator: str = LIST_SEPARATOR,
     pair_separator: str = PAIR_SEPARATOR,
     brackets: Iterable[tuple[str, str]] | None = BRACKETS,
     mapping: bool = False,
@@ -217,7 +168,7 @@ class _SplitKeyValuePairsDuplicateKeysError(SplitKeyValuePairsError):
 
     @override
     def __str__(self) -> str:
-        return f"Unable to split {self.text!r} into a mapping since there are duplicate keys; got {get_repr(self.counts)}"
+        return f"Unable to split {self.text!r} into a mapping since there are duplicate keys; got {repr_(self.counts)}"
 
 
 ##
@@ -228,7 +179,7 @@ def split_str(
     text: str,
     /,
     *,
-    separator: str = DEFAULT_SEPARATOR,
+    separator: str = LIST_SEPARATOR,
     brackets: Iterable[tuple[str, str]] | None = None,
     n: Literal[1],
 ) -> tuple[str]: ...
@@ -237,7 +188,7 @@ def split_str(
     text: str,
     /,
     *,
-    separator: str = DEFAULT_SEPARATOR,
+    separator: str = LIST_SEPARATOR,
     brackets: Iterable[tuple[str, str]] | None = None,
     n: Literal[2],
 ) -> tuple[str, str]: ...
@@ -246,7 +197,7 @@ def split_str(
     text: str,
     /,
     *,
-    separator: str = DEFAULT_SEPARATOR,
+    separator: str = LIST_SEPARATOR,
     brackets: Iterable[tuple[str, str]] | None = None,
     n: Literal[3],
 ) -> tuple[str, str, str]: ...
@@ -255,7 +206,7 @@ def split_str(
     text: str,
     /,
     *,
-    separator: str = DEFAULT_SEPARATOR,
+    separator: str = LIST_SEPARATOR,
     brackets: Iterable[tuple[str, str]] | None = None,
     n: Literal[4],
 ) -> tuple[str, str, str, str]: ...
@@ -264,7 +215,7 @@ def split_str(
     text: str,
     /,
     *,
-    separator: str = DEFAULT_SEPARATOR,
+    separator: str = LIST_SEPARATOR,
     brackets: Iterable[tuple[str, str]] | None = None,
     n: Literal[5],
 ) -> tuple[str, str, str, str, str]: ...
@@ -273,7 +224,7 @@ def split_str(
     text: str,
     /,
     *,
-    separator: str = DEFAULT_SEPARATOR,
+    separator: str = LIST_SEPARATOR,
     brackets: Iterable[tuple[str, str]] | None = None,
     n: int | None = None,
 ) -> tuple[str, ...]: ...
@@ -281,7 +232,7 @@ def split_str(
     text: str,
     /,
     *,
-    separator: str = DEFAULT_SEPARATOR,
+    separator: str = LIST_SEPARATOR,
     brackets: Iterable[tuple[str, str]] | None = None,
     n: int | None = None,
 ) -> tuple[str, ...]:
@@ -306,7 +257,7 @@ def _split_str_brackets(
     brackets: Iterable[tuple[str, str]],
     /,
     *,
-    separator: str = DEFAULT_SEPARATOR,
+    separator: str = LIST_SEPARATOR,
 ) -> list[str]:
     brackets = list(brackets)
     opens, closes = transpose(brackets)
@@ -397,7 +348,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 = LIST_SEPARATOR
 ) -> str:
     """Join a collection of strings, with a special provision for the empty list."""
     texts = list(texts)
@@ -410,7 +361,7 @@ def join_strs(
     return separator.join(texts)
 
 
-def _escape_separator(*, separator: str = DEFAULT_SEPARATOR) -> str:
+def _escape_separator(*, separator: str = LIST_SEPARATOR) -> str:
     return f"\\{separator}"
 
 
@@ -451,15 +402,6 @@ def str_encode(obj: Any, /) -> bytes:
 ##
 
 
-def strip_and_dedent(text: str, /, *, trailing: bool = False) -> str:
-    """Strip and dedent a string."""
-    result = dedent(text.strip("\n")).strip("\n")
-    return f"{result}\n" if trailing else result
-
-
-##
-
-
 @overload
 def to_bool(bool_: MaybeCallableBoolLike, /) -> bool: ...
 @overload
@@ -504,20 +446,7 @@ def to_str(text: MaybeCallableStr | None | Sentinel, /) -> str | None | Sentinel
 ##
 
 
-def unique_str() -> str:
-    """Generate at unique string."""
-    now = time_ns()
-    pid = getpid()
-    ident = get_ident()
-    key = str(uuid4()).replace("-", "")
-    return f"{now}_{pid}_{ident}_{key}"
-
-
 __all__ = [
-    "BRACKETS",
-    "DEFAULT_SEPARATOR",
-    "LIST_SEPARATOR",
-    "PAIR_SEPARATOR",
     "ParseBoolError",
     "ParseNoneError",
     "SplitKeyValuePairsError",
@@ -525,16 +454,12 @@ __all__ = [
     "join_strs",
     "parse_bool",
     "parse_none",
-    "pascal_case",
     "prompt_bool",
-    "repr_encode",
     "secret_str",
-    "snake_case",
+    "split_f_str_equals",
     "split_key_value_pairs",
     "split_str",
     "str_encode",
-    "strip_and_dedent",
     "to_bool",
     "to_str",
-    "unique_str",
 ]

utilities/throttle.py

@@ -0,0 +1,159 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass
+from functools import partial, wraps
+from inspect import iscoroutinefunction
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, NoReturn, assert_never, cast, override
+
+from whenever import ZonedDateTime
+
+from utilities.constants import SECOND
+from utilities.core import get_env, get_now_local, write_text
+from utilities.functions import in_timedelta
+from utilities.pathlib import to_path
+from utilities.types import Duration, MaybeCallablePathLike, MaybeCoro
+
+if TYPE_CHECKING:
+    from utilities.types import Coro
+
+
+def throttle[F: Callable[..., MaybeCoro[None]]](
+    *,
+    on_try: bool = False,
+    duration: Duration = SECOND,
+    path: MaybeCallablePathLike = Path.cwd,
+    raiser: Callable[[], NoReturn] | None = None,
+) -> Callable[[F], F]:
+    """Throttle a function. On success by default, on try otherwise."""
+    return cast(
+        "Any",
+        partial(
+            _throttle_inner, on_try=on_try, duration=duration, path=path, raiser=raiser
+        ),
+    )
+
+
+def _throttle_inner[F: Callable[..., MaybeCoro[None]]](
+    func: F,
+    /,
+    *,
+    on_try: bool = False,
+    duration: Duration = SECOND,
+    path: MaybeCallablePathLike = Path.cwd,
+    raiser: Callable[[], NoReturn] | None = None,
+) -> F:
+    match bool(iscoroutinefunction(func)), on_try:
+        case False, False:
+
+            @wraps(func)
+            def throttle_sync_on_pass(*args: Any, **kwargs: Any) -> None:
+                path_use = to_path(path)
+                if _is_throttle(path=path_use, duration=duration):
+                    _try_raise(raiser=raiser)
+                else:
+                    cast("Callable[..., None]", func)(*args, **kwargs)
+                    _write_throttle(path=path_use)
+
+            return cast("Any", throttle_sync_on_pass)
+
+        case False, True:
+
+            @wraps(func)
+            def throttle_sync_on_try(*args: Any, **kwargs: Any) -> None:
+                path_use = to_path(path)
+                if _is_throttle(path=path_use, duration=duration):
+                    _try_raise(raiser=raiser)
+                else:
+                    _write_throttle(path=path_use)
+                    cast("Callable[..., None]", func)(*args, **kwargs)
+
+            return cast("Any", throttle_sync_on_try)
+
+        case True, False:
+
+            @wraps(func)
+            async def throttle_async_on_pass(*args: Any, **kwargs: Any) -> None:
+                path_use = to_path(path)
+                if _is_throttle(path=path_use, duration=duration):
+                    _try_raise(raiser=raiser)
+                else:
+                    await cast("Callable[..., Coro[None]]", func)(*args, **kwargs)
+                    _write_throttle(path=path_use)
+
+            return cast("Any", throttle_async_on_pass)
+
+        case True, True:
+
+            @wraps(func)
+            async def throttle_async_on_try(*args: Any, **kwargs: Any) -> None:
+                path_use = to_path(path)
+                if _is_throttle(path=path_use, duration=duration):
+                    _try_raise(raiser=raiser)
+                else:
+                    _write_throttle(path=path_use)
+                    await cast("Callable[..., Coro[None]]", func)(*args, **kwargs)
+
+            return cast("Any", throttle_async_on_try)
+
+        case never:
+            assert_never(never)
+
+
+def _is_throttle(
+    *, path: MaybeCallablePathLike = Path.cwd, duration: Duration = SECOND
+) -> bool:
+    if get_env("THROTTLE", nullable=True):
+        return False
+    path = to_path(path)
+    if path.is_file():
+        text = path.read_text().rstrip("\n")
+        if text == "":
+            path.unlink(missing_ok=True)
+            return False
+        try:
+            last = ZonedDateTime.parse_iso(text)
+        except ValueError:
+            raise _ThrottleParseZonedDateTimeError(path=path, text=text) from None
+        threshold = get_now_local() - in_timedelta(duration)
+        return threshold <= last
+    if not path.exists():
+        return False
+    raise _ThrottleMarkerFileError(path=path)
+
+
+def _try_raise(*, raiser: Callable[[], NoReturn] | None = None) -> None:
+    if raiser is not None:
+        raiser()
+
+
+def _write_throttle(*, path: MaybeCallablePathLike = Path.cwd) -> None:
+    path_use = to_path(path)
+    write_text(path_use, get_now_local().format_iso(), overwrite=True)
+
+
+@dataclass(kw_only=True, slots=True)
+class ThrottleError(Exception): ...
+
+
+@dataclass(kw_only=True, slots=True)
+class _ThrottleParseZonedDateTimeError(ThrottleError):
+    path: Path
+    text: str
+
+    @override
+    def __str__(self) -> str:
+        return f"Unable to parse the contents {self.text!r} of {str(self.path)!r} to a ZonedDateTime"
+
+
+@dataclass(kw_only=True, slots=True)
+class _ThrottleMarkerFileError(ThrottleError):
+    path: Path
+
+    @override
+    def __str__(self) -> str:
+        return f"Invalid marker file {str(self.path)!r}"
+
+
+__all__ = ["ThrottleError", "throttle"]

utilities/time.py

@@ -0,0 +1,18 @@
+from __future__ import annotations
+
+import time
+from typing import TYPE_CHECKING
+
+from utilities.functions import in_seconds
+
+if TYPE_CHECKING:
+    from utilities.types import Duration
+
+
+def sleep(duration: Duration | None = None, /) -> None:
+    """Sleep which accepts durations."""
+    if duration is not None:
+        time.sleep(in_seconds(duration))
+
+
+__all__ = ["sleep"]

utilities/timer.py

@@ -3,12 +3,15 @@ from __future__ import annotations
 from operator import add, eq, ge, gt, le, lt, mul, ne, sub, truediv
 from typing import TYPE_CHECKING, Any, Self, override
 
-from utilities.whenever import get_now_local
+from whenever import TimeDelta
+
+from utilities.core import get_now_local
+from utilities.functions import in_timedelta
 
 if TYPE_CHECKING:
     from collections.abc import Callable
 
-    from whenever import TimeDelta, ZonedDateTime
+    from whenever import ZonedDateTime
 
 
 class Timer:
@@ -56,33 +59,33 @@ 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
 
     @override
     def __eq__(self, other: object) -> bool:
-        return self._apply_op(eq, other)
+        return self._apply_op(eq, other, cast=True, type_error=False)
 
     def __ge__(self, other: Any) -> bool:
-        return self._apply_op(ge, other)
+        return self._apply_op(ge, other, cast=True)
 
     def __gt__(self, other: Any) -> bool:
-        return self._apply_op(gt, other)
+        return self._apply_op(gt, other, cast=True)
 
     def __le__(self, other: Any) -> bool:
-        return self._apply_op(le, other)
+        return self._apply_op(le, other, cast=True)
 
     def __lt__(self, other: Any) -> bool:
-        return self._apply_op(lt, other)
+        return self._apply_op(lt, other, cast=True)
 
     @override
     def __ne__(self, other: object) -> bool:
-        return self._apply_op(ne, other)
+        return self._apply_op(ne, other, cast=True, type_error=True)
 
     # properties
 
@@ -94,10 +97,24 @@ class Timer:
 
     # private
 
-    def _apply_op(self, op: Callable[[Any, Any], Any], other: Any, /) -> Any:
-        if isinstance(other, Timer):
-            return op(self.timedelta, other.timedelta)
-        return op(self.timedelta, other)
+    def _apply_op(
+        self,
+        op: Callable[[Any, Any], Any],
+        other: Any,
+        /,
+        *,
+        cast: bool = False,
+        type_error: bool | None = None,
+    ) -> Any:
+        other_use = other.timedelta if isinstance(other, Timer) else other
+        if cast:
+            if isinstance(other_use, float | int | TimeDelta):
+                other_use = in_timedelta(other_use)
+            elif type_error is not None:
+                return type_error
+            else:
+                raise TypeError  # pragma: no cover
+        return op(self.timedelta, other_use)
 
 
 __all__ = ["Timer"]