dycw-utilities 0.135.0__py3-none-any.whl → 0.178.1__py3-none-any.whl

utilities/throttle.py

@@ -0,0 +1,158 @@
+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.atomicwrites import writer
+from utilities.os import get_env_var
+from utilities.pathlib import to_path
+from utilities.types import MaybeCallablePathLike, MaybeCoro
+from utilities.whenever import SECOND, get_now_local
+
+if TYPE_CHECKING:
+    from utilities.types import Coro, Delta
+
+
+def throttle[F: Callable[..., MaybeCoro[None]]](
+    *,
+    on_try: bool = False,
+    delta: Delta = 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, delta=delta, path=path, raiser=raiser),
+    )
+
+
+def _throttle_inner[F: Callable[..., MaybeCoro[None]]](
+    func: F,
+    /,
+    *,
+    on_try: bool = False,
+    delta: Delta = 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, delta=delta):
+                    _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, delta=delta):
+                    _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, delta=delta):
+                    _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, delta=delta):
+                    _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, delta: Delta = SECOND
+) -> bool:
+    if get_env_var("THROTTLE", nullable=True):
+        return False
+    path = to_path(path)
+    if path.is_file():
+        text = path.read_text()
+        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() - delta
+        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 = to_path(path)
+    with writer(path, overwrite=True) as temp:
+        _ = temp.write_text(get_now_local().format_iso())
+
+
+@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/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
 

utilities/traceback.py

@@ -2,21 +2,21 @@ from __future__ import annotations
 
 import re
 import sys
-from asyncio import run
-from collections.abc import Callable
 from dataclasses import dataclass
 from functools import partial
 from getpass import getuser
 from itertools import repeat
+from os import getpid
 from pathlib import Path
 from socket import gethostname
+from sys import stderr
 from traceback import TracebackException
 from typing import TYPE_CHECKING, override
 
 from utilities.atomicwrites import writer
 from utilities.errors import repr_error
 from utilities.iterables import OneEmptyError, one
-from utilities.pathlib import get_path
+from utilities.pathlib import module_path, to_path
 from utilities.reprlib import (
     RICH_EXPAND_ALL,
     RICH_INDENT_SIZE,
@@ -26,17 +26,26 @@ from utilities.reprlib import (
     RICH_MAX_WIDTH,
     yield_mapping_repr,
 )
-from utilities.version import get_version
-from utilities.whenever import format_compact, get_now, to_zoned_date_time
+from utilities.text import to_bool
+from utilities.tzlocal import LOCAL_TIME_ZONE_NAME
+from utilities.version import to_version
+from utilities.whenever import (
+    format_compact,
+    get_now,
+    get_now_local,
+    to_zoned_date_time,
+)
 
 if TYPE_CHECKING:
-    from collections.abc import Callable, Iterator, Sequence
+    from collections.abc import Callable, Iterator
     from traceback import FrameSummary
     from types import TracebackType
 
     from utilities.types import (
+        Delta,
+        MaybeCallableBoolLike,
         MaybeCallablePathLike,
-        MaybeCallableZonedDateTime,
+        MaybeCallableZonedDateTimeLike,
         PathLike,
     )
     from utilities.version import MaybeCallableVersionLike
@@ -45,15 +54,12 @@ if TYPE_CHECKING:
 ##
 
 
-_START = get_now()
-
-
 def format_exception_stack(
     error: BaseException,
     /,
     *,
     header: bool = False,
-    start: MaybeCallableZonedDateTime | None = _START,
+    start: MaybeCallableZonedDateTimeLike = get_now,
     version: MaybeCallableVersionLike | None = None,
     capture_locals: bool = False,
     max_width: int = RICH_MAX_WIDTH,
@@ -64,7 +70,7 @@ def format_exception_stack(
     expand_all: bool = RICH_EXPAND_ALL,
 ) -> str:
     """Format an exception stack."""
-    lines: Sequence[str] = []
+    lines: list[str] = []
     if header:
         lines.extend(_yield_header_lines(start=start, version=version))
     lines.extend(
@@ -84,22 +90,20 @@ def format_exception_stack(
 
 def _yield_header_lines(
     *,
-    start: MaybeCallableZonedDateTime | None = _START,
+    start: MaybeCallableZonedDateTimeLike = get_now,
     version: MaybeCallableVersionLike | None = None,
 ) -> Iterator[str]:
     """Yield the header lines."""
-    now = get_now()
-    start_use = to_zoned_date_time(date_time=start)
-    yield f"Date/time | {format_compact(now)}"
-    start_str = "" if start_use is None else format_compact(start_use)
-    yield f"Started   | {start_str}"
-    delta = None if start_use is None else (now - start_use)
-    delta_str = "" if delta is None else delta.format_common_iso()
-    yield f"Duration  | {delta_str}"
-    yield f"User      | {getuser()}"
-    yield f"Host      | {gethostname()}"
-    version_use = "" if version is None else get_version(version=version)
-    yield f"Version   | {version_use}"
+    now = get_now_local()
+    yield f"Date/time  | {format_compact(now)}"
+    start_use = to_zoned_date_time(start).to_tz(LOCAL_TIME_ZONE_NAME)
+    yield f"Started    | {format_compact(start_use)}"
+    yield f"Duration   | {(now - start_use).format_iso()}"
+    yield f"User       | {getuser()}"
+    yield f"Host       | {gethostname()}"
+    yield f"Process ID | {getpid()}"
+    version_use = "" if version is None else to_version(version)
+    yield f"Version    | {version_use}"
     yield ""
 
 
@@ -174,7 +178,7 @@ def _path_to_dots(path: PathLike, /) -> str:
         if (new_path := _trim_path(path, pattern)) is not None:
             break
     path_use = Path(path) if new_path is None else new_path
-    return ".".join(path_use.with_suffix("").parts)
+    return module_path(path_use)
 
 
 def _trim_path(path: PathLike, pattern: str, /) -> Path | None:
@@ -192,9 +196,10 @@ def _trim_path(path: PathLike, pattern: str, /) -> Path | None:
 
 def make_except_hook(
     *,
-    start: MaybeCallableZonedDateTime | None = _START,
+    start: MaybeCallableZonedDateTimeLike = get_now,
     version: MaybeCallableVersionLike | None = None,
     path: MaybeCallablePathLike | None = None,
+    path_max_age: Delta | None = None,
     max_width: int = RICH_MAX_WIDTH,
     indent_size: int = RICH_INDENT_SIZE,
     max_length: int | None = RICH_MAX_LENGTH,
@@ -202,6 +207,7 @@ def make_except_hook(
     max_depth: int | None = RICH_MAX_DEPTH,
     expand_all: bool = RICH_EXPAND_ALL,
     slack_url: str | None = None,
+    pudb: MaybeCallableBoolLike = False,
 ) -> Callable[
     [type[BaseException] | None, BaseException | None, TracebackType | None], None
 ]:
@@ -211,6 +217,7 @@ def make_except_hook(
         start=start,
         version=version,
         path=path,
+        path_max_age=path_max_age,
         max_width=max_width,
         indent_size=indent_size,
         max_length=max_length,
@@ -218,6 +225,7 @@ def make_except_hook(
         max_depth=max_depth,
         expand_all=expand_all,
         slack_url=slack_url,
+        pudb=pudb,
     )
 
 
@@ -227,9 +235,10 @@ def _make_except_hook_inner(
     traceback: TracebackType | None,
     /,
     *,
-    start: MaybeCallableZonedDateTime | None = _START,
+    start: MaybeCallableZonedDateTimeLike = get_now,
     version: MaybeCallableVersionLike | None = None,
     path: MaybeCallablePathLike | None = None,
+    path_max_age: Delta | None = None,
     max_width: int = RICH_MAX_WIDTH,
     indent_size: int = RICH_INDENT_SIZE,
     max_length: int | None = RICH_MAX_LENGTH,
@@ -237,6 +246,7 @@ def _make_except_hook_inner(
     max_depth: int | None = RICH_MAX_DEPTH,
     expand_all: bool = RICH_EXPAND_ALL,
     slack_url: str | None = None,
+    pudb: MaybeCallableBoolLike = False,
 ) -> None:
     """Exception hook to log the traceback."""
     _ = (exc_type, traceback)
@@ -245,9 +255,10 @@ def _make_except_hook_inner(
     slim = format_exception_stack(exc_val, header=True, start=start, version=version)
     _ = sys.stderr.write(f"{slim}\n")  # don't 'from sys import stderr'
     if path is not None:
-        path = (
-            get_path(path=path).joinpath(format_compact(get_now())).with_suffix(".txt")
-        )
+        path = to_path(path)
+        path_log = path.joinpath(
+            format_compact(get_now_local(), path=True)
+        ).with_suffix(".txt")
         full = format_exception_stack(
             exc_val,
             header=True,
@@ -261,13 +272,37 @@ def _make_except_hook_inner(
             max_depth=max_depth,
             expand_all=expand_all,
         )
-        with writer(path, overwrite=True) as temp:
+        with writer(path_log, overwrite=True) as temp:
             _ = temp.write_text(full)
+        if path_max_age is not None:
+            _make_except_hook_purge(path, path_max_age)
     if slack_url is not None:  # pragma: no cover
-        from utilities.slack_sdk import send_to_slack
+        from utilities.slack_sdk import SendToSlackError, send_to_slack
+
+        try:
+            send_to_slack(slack_url, f"```{slim}```")
+        except SendToSlackError as error:
+            _ = stderr.write(f"{error}\n")
+    if to_bool(pudb):  # pragma: no cover
+        from pudb import post_mortem  # pyright: ignore[reportMissingImports]
+
+        post_mortem(tb=traceback, e_type=exc_type, e_value=exc_val)
+
 
-        send = f"```{slim}```"
-        run(send_to_slack(slack_url, send))
+def _make_except_hook_purge(path: PathLike, max_age: Delta, /) -> None:
+    threshold = get_now_local() - max_age
+    paths: set[Path] = set()
+    for p in Path(path).iterdir():
+        if p.is_file():
+            try:
+                date_time = to_zoned_date_time(p.stem)
+            except ValueError:
+                pass
+            else:
+                if date_time <= threshold:
+                    paths.add(p)
+    for p in paths:
+        p.unlink(missing_ok=True)
 
 
 @dataclass(kw_only=True, slots=True)