dycw-utilities 0.127.0__py3-none-any.whl → 0.129.13__py3-none-any.whl

utilities/traceback.py

@@ -1,10 +1,14 @@
 from __future__ import annotations
 
+import re
+import sys
+from asyncio import run
 from collections.abc import Callable, Iterable
 from dataclasses import dataclass, field, replace
-from functools import wraps
+from functools import partial, wraps
 from getpass import getuser
 from inspect import iscoroutinefunction, signature
+from itertools import repeat
 from logging import Formatter, Handler, LogRecord
 from pathlib import Path
 from socket import gethostname
@@ -26,7 +30,8 @@ from typing import (
     runtime_checkable,
 )
 
-from utilities.errors import ImpossibleCaseError
+from utilities.datetime import get_datetime, get_now, serialize_compact
+from utilities.errors import ImpossibleCaseError, repr_error
 from utilities.functions import (
     ensure_not_none,
     ensure_str,
@@ -34,7 +39,8 @@ from utilities.functions import (
     get_func_name,
     get_func_qualname,
 )
-from utilities.iterables import always_iterable, one
+from utilities.iterables import OneEmptyError, always_iterable, one
+from utilities.pathlib import get_path
 from utilities.reprlib import (
     RICH_EXPAND_ALL,
     RICH_INDENT_SIZE,
@@ -45,11 +51,18 @@ from utilities.reprlib import (
     yield_call_args_repr,
     yield_mapping_repr,
 )
-from utilities.types import TBaseException, TCallable
+from utilities.types import (
+    MaybeCallableDateTime,
+    MaybeCallablePathLike,
+    PathLike,
+    TBaseException,
+    TCallable,
+)
 from utilities.version import get_version
+from utilities.whenever import serialize_duration
 
 if TYPE_CHECKING:
-    from collections.abc import Callable, Iterable, Iterator
+    from collections.abc import Callable, Iterable, Iterator, Sequence
     from logging import _FormatStyle
     from types import FrameType, TracebackType
 
@@ -60,6 +73,132 @@ if TYPE_CHECKING:
 _T = TypeVar("_T")
 _CALL_ARGS = "_CALL_ARGS"
 _INDENT = 4 * " "
+_START = get_now()
+
+
+##
+
+
+def format_exception_stack(
+    error: BaseException,
+    /,
+    *,
+    header: bool = False,
+    start: MaybeCallableDateTime | None = _START,
+    version: MaybeCallableVersionLike | None = None,
+    capture_locals: bool = False,
+    max_width: int = RICH_MAX_WIDTH,
+    indent_size: int = RICH_INDENT_SIZE,
+    max_length: int | None = RICH_MAX_LENGTH,
+    max_string: int | None = RICH_MAX_STRING,
+    max_depth: int | None = RICH_MAX_DEPTH,
+    expand_all: bool = RICH_EXPAND_ALL,
+) -> str:
+    """Format an exception stack."""
+    lines: Sequence[str] = []
+    if header:
+        lines.extend(_yield_header_lines(start=start, version=version))
+    lines.extend(
+        _yield_formatted_frame_summary(
+            error,
+            capture_locals=capture_locals,
+            max_width=max_width,
+            indent_size=indent_size,
+            max_length=max_length,
+            max_string=max_string,
+            max_depth=max_depth,
+            expand_all=expand_all,
+        )
+    )
+    return "\n".join(lines)
+
+
+##
+
+
+def make_except_hook(
+    *,
+    start: MaybeCallableDateTime | None = _START,
+    version: MaybeCallableVersionLike | None = None,
+    path: MaybeCallablePathLike | None = None,
+    max_width: int = RICH_MAX_WIDTH,
+    indent_size: int = RICH_INDENT_SIZE,
+    max_length: int | None = RICH_MAX_LENGTH,
+    max_string: int | None = RICH_MAX_STRING,
+    max_depth: int | None = RICH_MAX_DEPTH,
+    expand_all: bool = RICH_EXPAND_ALL,
+    slack_url: str | None = None,
+) -> Callable[
+    [type[BaseException] | None, BaseException | None, TracebackType | None], None
+]:
+    """Exception hook to log the traceback."""
+    return partial(
+        _make_except_hook_inner,
+        start=start,
+        version=version,
+        path=path,
+        max_width=max_width,
+        indent_size=indent_size,
+        max_length=max_length,
+        max_string=max_string,
+        max_depth=max_depth,
+        expand_all=expand_all,
+        slack_url=slack_url,
+    )
+
+
+def _make_except_hook_inner(
+    exc_type: type[BaseException] | None,
+    exc_val: BaseException | None,
+    traceback: TracebackType | None,
+    /,
+    *,
+    start: MaybeCallableDateTime | None = _START,
+    version: MaybeCallableVersionLike | None = None,
+    path: MaybeCallablePathLike | None = None,
+    max_width: int = RICH_MAX_WIDTH,
+    indent_size: int = RICH_INDENT_SIZE,
+    max_length: int | None = RICH_MAX_LENGTH,
+    max_string: int | None = RICH_MAX_STRING,
+    max_depth: int | None = RICH_MAX_DEPTH,
+    expand_all: bool = RICH_EXPAND_ALL,
+    slack_url: str | None = None,
+) -> None:
+    """Exception hook to log the traceback."""
+    _ = (exc_type, traceback)
+    if exc_val is None:
+        raise MakeExceptHookError
+    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:
+        from utilities.atomicwrites import writer
+        from utilities.tzlocal import get_now_local
+
+        path = (
+            get_path(path=path)
+            .joinpath(serialize_compact(get_now_local()))
+            .with_suffix(".txt")
+        )
+        full = format_exception_stack(
+            exc_val,
+            header=True,
+            start=start,
+            version=version,
+            capture_locals=True,
+            max_width=max_width,
+            indent_size=indent_size,
+            max_length=max_length,
+            max_string=max_string,
+            max_depth=max_depth,
+            expand_all=expand_all,
+        )
+        with writer(path, overwrite=True) as temp:
+            _ = temp.write_text(full)
+    if slack_url is not None:  # pragma: no cover
+        from utilities.slack_sdk import send_to_slack
+
+        send = f"```{slim}```"
+        run(send_to_slack(slack_url, send))
 
 
 ##
@@ -78,6 +217,7 @@ class RichTracebackFormatter(Formatter):
         /,
         *,
         defaults: StrMapping | None = None,
+        start: MaybeCallableDateTime | None = _START,
         version: MaybeCallableVersionLike | None = None,
         max_width: int = RICH_MAX_WIDTH,
         indent_size: int = RICH_INDENT_SIZE,
@@ -89,7 +229,8 @@ class RichTracebackFormatter(Formatter):
         post: Callable[[str], str] | None = None,
     ) -> None:
         super().__init__(fmt, datefmt, style, validate, defaults=defaults)
-        self._version = version
+        self._start = get_datetime(datetime=start)
+        self._version = get_version(version=version)
         self._max_width = max_width
         self._indent_size = indent_size
         self._max_length = max_length
@@ -110,6 +251,7 @@ class RichTracebackFormatter(Formatter):
         exc_value = ensure_not_none(exc_value, desc="exc_value")
         error = get_rich_traceback(
             exc_value,
+            start=self._start,
             version=self._version,
             max_width=self._max_width,
             indent_size=self._indent_size,
@@ -263,6 +405,7 @@ class ExcChainTB(Generic[TBaseException]):
     errors: list[
         ExcGroupTB[TBaseException] | ExcTB[TBaseException] | TBaseException
     ] = field(default_factory=list)
+    start: MaybeCallableDateTime | None = field(default=_START, repr=False)
     version: MaybeCallableVersionLike | None = field(default=None, repr=False)
     max_width: int = RICH_MAX_WIDTH
     indent_size: int = RICH_INDENT_SIZE
@@ -292,7 +435,7 @@ class ExcChainTB(Generic[TBaseException]):
         """Format the traceback."""
         lines: list[str] = []
         if header:  # pragma: no cover
-            lines.extend(_yield_header_lines(version=self.version))
+            lines.extend(_yield_header_lines(start=self.start, version=self.version))
         total = len(self.errors)
         for i, errors in enumerate(self.errors, start=1):
             lines.append(f"Exception chain {i}/{total}:")
@@ -315,6 +458,7 @@ class ExcGroupTB(Generic[TBaseException]):
     errors: list[
         ExcGroupTB[TBaseException] | ExcTB[TBaseException] | TBaseException
     ] = field(default_factory=list)
+    start: MaybeCallableDateTime | None = field(default=_START, repr=False)
     version: MaybeCallableVersionLike | None = field(default=None, repr=False)
     max_width: int = RICH_MAX_WIDTH
     indent_size: int = RICH_INDENT_SIZE
@@ -333,7 +477,7 @@ class ExcGroupTB(Generic[TBaseException]):
         """Format the traceback."""
         lines: list[str] = []  # skipif-ci
         if header:  # pragma: no cover
-            lines.extend(_yield_header_lines(version=self.version))
+            lines.extend(_yield_header_lines(start=self.start, version=self.version))
         lines.append("Exception group:")  # skipif-ci
         match self.exc_group:  # skipif-ci
             case ExcTB() as exc_tb:
@@ -363,6 +507,7 @@ class ExcTB(Generic[TBaseException]):
 
     frames: list[_Frame] = field(default_factory=list)
     error: TBaseException
+    start: MaybeCallableDateTime | None = field(default=_START, repr=False)
     version: MaybeCallableVersionLike | None = field(default=None, repr=False)
     max_width: int = RICH_MAX_WIDTH
     indent_size: int = RICH_INDENT_SIZE
@@ -391,7 +536,7 @@ class ExcTB(Generic[TBaseException]):
         total = len(self)
         lines: list[str] = []
         if header:  # pragma: no cover
-            lines.extend(_yield_header_lines(version=self.version))
+            lines.extend(_yield_header_lines(start=self.start, version=self.version))
         for i, frame in enumerate(self.frames):
             is_head = i < total - 1
             lines.append(
@@ -485,6 +630,7 @@ def get_rich_traceback(
     error: TBaseException,
     /,
     *,
+    start: MaybeCallableDateTime | None = _START,
     version: MaybeCallableVersionLike | None = None,
     max_width: int = RICH_MAX_WIDTH,
     indent_size: int = RICH_INDENT_SIZE,
@@ -506,6 +652,7 @@ def get_rich_traceback(
             err_recast = cast("TBaseException", err)
             return _get_rich_traceback_non_chain(
                 err_recast,
+                start=start,
                 version=version,
                 max_width=max_width,
                 indent_size=indent_size,
@@ -520,6 +667,7 @@ def get_rich_traceback(
                 errors=[
                     _get_rich_traceback_non_chain(
                         e,
+                        start=start,
                         version=version,
                         max_width=max_width,
                         indent_size=indent_size,
@@ -530,6 +678,7 @@ def get_rich_traceback(
                     )
                     for e in errs_recast
                 ],
+                start=start,
                 version=version,
                 max_width=max_width,
                 indent_size=indent_size,
@@ -544,6 +693,7 @@ def _get_rich_traceback_non_chain(
     error: ExceptionGroup[Any] | TBaseException,
     /,
     *,
+    start: MaybeCallableDateTime | None = _START,
     version: MaybeCallableVersionLike | None = None,
     max_width: int = RICH_MAX_WIDTH,
     indent_size: int = RICH_INDENT_SIZE,
@@ -567,6 +717,7 @@ def _get_rich_traceback_non_chain(
             errors = [
                 _get_rich_traceback_non_chain(
                     e,
+                    start=start,
                     version=version,
                     max_width=max_width,
                     indent_size=indent_size,
@@ -580,6 +731,7 @@ def _get_rich_traceback_non_chain(
             return ExcGroupTB(
                 exc_group=exc_group_or_exc_tb,
                 errors=errors,
+                start=start,
                 version=version,
                 max_width=max_width,
                 indent_size=indent_size,
@@ -591,6 +743,7 @@ def _get_rich_traceback_non_chain(
         case BaseException() as base_exc:
             return _get_rich_traceback_base_one(
                 base_exc,
+                start=start,
                 version=version,
                 max_width=max_width,
                 indent_size=indent_size,
@@ -607,6 +760,7 @@ def _get_rich_traceback_base_one(
     error: TBaseException,
     /,
     *,
+    start: MaybeCallableDateTime | None = _START,
     version: MaybeCallableVersionLike | None = None,
     max_width: int = RICH_MAX_WIDTH,
     indent_size: int = RICH_INDENT_SIZE,
@@ -638,6 +792,7 @@ def _get_rich_traceback_base_one(
         return ExcTB(
             frames=frames,
             error=error,
+            start=start,
             version=version,
             max_width=max_width,
             indent_size=indent_size,
@@ -792,14 +947,29 @@ def _merge_frames(
     return values[::-1]
 
 
+##
+
+
 def _yield_header_lines(
-    *, version: MaybeCallableVersionLike | None = None
+    *,
+    start: MaybeCallableDateTime | None = _START,
+    version: MaybeCallableVersionLike | None = None,
 ) -> Iterator[str]:
     """Yield the header lines."""
-    from utilities.tzlocal import get_now_local
+    from utilities.tzlocal import get_local_time_zone, get_now_local
     from utilities.whenever import serialize_zoned_datetime
 
-    yield f"Date/time | {serialize_zoned_datetime(get_now_local())}"
+    now = get_now_local()
+    start_use = get_datetime(datetime=start)
+    start_use = (
+        None if start_use is None else start_use.astimezone(get_local_time_zone())
+    )
+    yield f"Date/time | {serialize_zoned_datetime(now)}"
+    start_str = "" if start_use is None else serialize_zoned_datetime(start_use)
+    yield f"Started   | {start_str}"
+    duration = None if start_use is None else (now - start_use)
+    duration_str = "" if duration is None else serialize_duration(duration)
+    yield f"Duration  | {duration_str}"
     yield f"User      | {getuser()}"
     yield f"Host      | {gethostname()}"
     version_use = "" if version is None else get_version(version=version)
@@ -807,12 +977,108 @@ def _yield_header_lines(
     yield ""
 
 
+##
+
+
+def _yield_formatted_frame_summary(
+    error: BaseException,
+    /,
+    *,
+    capture_locals: bool = False,
+    max_width: int = RICH_MAX_WIDTH,
+    indent_size: int = RICH_INDENT_SIZE,
+    max_length: int | None = RICH_MAX_LENGTH,
+    max_string: int | None = RICH_MAX_STRING,
+    max_depth: int | None = RICH_MAX_DEPTH,
+    expand_all: bool = RICH_EXPAND_ALL,
+) -> Iterator[str]:
+    """Yield the formatted frame summary lines."""
+    stack = TracebackException.from_exception(
+        error, capture_locals=capture_locals
+    ).stack
+    n = len(stack)
+    for i, frame in enumerate(stack, start=1):
+        num = f"{i}/{n}"
+        first, *rest = _yield_frame_summary_lines(
+            frame,
+            max_width=max_width,
+            indent_size=indent_size,
+            max_length=max_length,
+            max_string=max_string,
+            max_depth=max_depth,
+            expand_all=expand_all,
+        )
+        yield f"{num} | {first}"
+        blank = "".join(repeat(" ", len(num)))
+        for rest_i in rest:
+            yield f"{blank} | {rest_i}"
+    yield repr_error(error)
+
+
+def _yield_frame_summary_lines(
+    frame: FrameSummary,
+    /,
+    *,
+    max_width: int = RICH_MAX_WIDTH,
+    indent_size: int = RICH_INDENT_SIZE,
+    max_length: int | None = RICH_MAX_LENGTH,
+    max_string: int | None = RICH_MAX_STRING,
+    max_depth: int | None = RICH_MAX_DEPTH,
+    expand_all: bool = RICH_EXPAND_ALL,
+) -> Iterator[str]:
+    module = _path_to_dots(frame.filename)
+    yield f"{module}:{frame.lineno} | {frame.name} | {frame.line}"
+    if frame.locals is not None:
+        yield from yield_mapping_repr(
+            frame.locals,
+            _max_width=max_width,
+            _indent_size=indent_size,
+            _max_length=max_length,
+            _max_string=max_string,
+            _max_depth=max_depth,
+            _expand_all=expand_all,
+        )
+
+
+def _path_to_dots(path: PathLike, /) -> str:
+    new_path: Path | None = None
+    for pattern in [
+        "site-packages",
+        ".venv",  # after site-packages
+        "src",
+        r"python\d+\.\d+",
+    ]:
+        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)
+
+
+def _trim_path(path: PathLike, pattern: str, /) -> Path | None:
+    parts = Path(path).parts
+    compiled = re.compile(f"^{pattern}$")
+    try:
+        i = one(i for i, p in enumerate(parts) if compiled.search(p))
+    except OneEmptyError:
+        return None
+    return Path(*parts[i + 1 :])
+
+
+@dataclass(kw_only=True, slots=True)
+class MakeExceptHookError(Exception):
+    @override
+    def __str__(self) -> str:
+        return "No exception to log"
+
+
 __all__ = [
     "ExcChainTB",
     "ExcGroupTB",
     "ExcTB",
     "RichTracebackFormatter",
+    "format_exception_stack",
     "get_rich_traceback",
+    "make_except_hook",
     "trace",
     "yield_exceptions",
     "yield_extended_frame_summaries",

utilities/types.py

@@ -241,8 +241,8 @@ type SerializeObjectExtra = Mapping[Any, Callable[[Any], str]]
 
 
 # pathlib
+type MaybeCallablePathLike = MaybeCallable[PathLike]
 type PathLike = MaybeStr[Path]
-type PathLikeOrCallable = PathLike | Callable[[], PathLike]
 
 
 # random
@@ -282,6 +282,7 @@ __all__ = [
     "MaybeCallableDate",
     "MaybeCallableDateTime",
     "MaybeCallableEvent",
+    "MaybeCallablePathLike",
     "MaybeCoroutine1",
     "MaybeIterable",
     "MaybeIterableHashable",
@@ -293,7 +294,6 @@ __all__ = [
     "Parallelism",
     "ParseObjectExtra",
     "PathLike",
-    "PathLikeOrCallable",
     "RoundMode",
     "Seed",
     "SerializeObjectExtra",

utilities/version.py

@@ -137,14 +137,6 @@ def get_version(*, version: MaybeCallableVersionLike) -> Version: ...
 def get_version(*, version: None) -> None: ...
 @overload
 def get_version(*, version: Sentinel) -> Sentinel: ...
-@overload
-def get_version(
-    *, version: MaybeCallableVersionLike | Sentinel
-) -> Version | Sentinel: ...
-@overload
-def get_version(
-    *, version: MaybeCallableVersionLike | None | Sentinel = sentinel
-) -> Version | None | Sentinel: ...
 def get_version(
     *, version: MaybeCallableVersionLike | None | Sentinel = sentinel
 ) -> Version | None | Sentinel:

utilities/whenever.py

@@ -4,7 +4,9 @@ import datetime as dt
 import re
 from contextlib import suppress
 from dataclasses import dataclass
-from typing import TYPE_CHECKING, override
+from functools import cache
+from logging import LogRecord
+from typing import TYPE_CHECKING, Any, override
 
 from whenever import (
     Date,
@@ -33,6 +35,8 @@ from utilities.re import (
 from utilities.zoneinfo import UTC, ensure_time_zone, get_time_zone_name
 
 if TYPE_CHECKING:
+    from zoneinfo import ZoneInfo
+
     from utilities.types import (
         DateLike,
         DateTimeLike,
@@ -561,6 +565,64 @@ class SerializeZonedDateTimeError(Exception):
 ##
 
 
+class WheneverLogRecord(LogRecord):
+    """Log record powered by `whenever`."""
+
+    zoned_datetime: str
+
+    @override
+    def __init__(
+        self,
+        name: str,
+        level: int,
+        pathname: str,
+        lineno: int,
+        msg: object,
+        args: Any,
+        exc_info: Any,
+        func: str | None = None,
+        sinfo: str | None = None,
+    ) -> None:
+        super().__init__(
+            name, level, pathname, lineno, msg, args, exc_info, func, sinfo
+        )
+        length = self._get_length()
+        plain = format(self._get_now().to_plain().format_common_iso(), f"{length}s")
+        time_zone = self._get_time_zone_key()
+        self.zoned_datetime = f"{plain}[{time_zone}]"
+
+    @classmethod
+    @cache
+    def _get_time_zone(cls) -> ZoneInfo:
+        """Get the local timezone."""
+        try:
+            from utilities.tzlocal import get_local_time_zone
+        except ModuleNotFoundError:  # pragma: no cover
+            return UTC
+        return get_local_time_zone()
+
+    @classmethod
+    @cache
+    def _get_time_zone_key(cls) -> str:
+        """Get the local timezone as a string."""
+        return cls._get_time_zone().key
+
+    @classmethod
+    @cache
+    def _get_length(cls) -> int:
+        """Get maximum length of a formatted string."""
+        now = cls._get_now().replace(nanosecond=1000).to_plain()
+        return len(now.format_common_iso())
+
+    @classmethod
+    def _get_now(cls) -> ZonedDateTime:
+        """Get the current zoned datetime."""
+        return ZonedDateTime.now(cls._get_time_zone().key)
+
+
+##
+
+
 def _to_datetime_delta(timedelta: dt.timedelta, /) -> DateTimeDelta:
     """Serialize a timedelta."""
     total_microseconds = datetime_duration_to_microseconds(timedelta)
@@ -610,6 +672,7 @@ __all__ = [
     "SerializePlainDateTimeError",
     "SerializeTimeDeltaError",
     "SerializeZonedDateTimeError",
+    "WheneverLogRecord",
     "check_valid_zoned_datetime",
     "ensure_date",
     "ensure_datetime",