pyfect-dev 0.1.0__py3-none-any.whl

pyfect/logger/_console.py

@@ -0,0 +1,116 @@
+"""The console loggers: ``default_logger`` and ``console_pretty``."""
+
+from __future__ import annotations
+
+import sys
+from collections.abc import Callable
+from datetime import datetime
+
+from pyfect.console import CurrentConsole
+from pyfect.logger._level import LogLevel
+from pyfect.logger._model import Logger, Options
+from pyfect.logger._refs import CurrentLogAnnotations, CurrentLogSpans, LogToStderr
+from pyfect.logger._text import format_log_span, structured_message
+
+
+def default_date_format(when: datetime) -> str:
+    """Local wall-clock time, ``HH:MM:SS.mmm``."""
+    local = when.astimezone()
+    return local.strftime("%H:%M:%S.") + f"{local.microsecond // 1000:03d}"
+
+
+def _spans(options: Options) -> str:
+    now = options.millis
+    return "".join(
+        " " + format_log_span(span, now) for span in options.fiber.get_ref(CurrentLogSpans)
+    )
+
+
+def _default(options: Options) -> None:
+    fiber = options.fiber
+    items = list(options.message)
+    if options.cause.reasons:
+        items.append(options.cause.pretty())
+    annotations = fiber.get_ref(CurrentLogAnnotations)
+    if annotations:
+        items.append(dict(annotations))
+    console = fiber.get_ref(CurrentConsole)
+    write = console.error if fiber.get_ref(LogToStderr) else console.log
+    header = f"[{default_date_format(options.date)}] {str(options.log_level).upper()} (#{fiber.id})"
+    write(f"{header}{_spans(options)}:", *items)
+
+
+default_logger: Logger[None] = Logger(_default)
+"""Effect's default logger: ``[HH:MM:SS.mmm] LEVEL (#fiber) spans:`` and
+then the logged items, the cause and the annotations, on the console."""
+
+
+_COLORS = {
+    "bold": "1",
+    "red": "31",
+    "green": "32",
+    "yellow": "33",
+    "blue": "34",
+    "cyan": "36",
+    "white": "37",
+    "gray": "90",
+    "black": "30",
+    "bg_bright_red": "101",
+}
+_LEVEL_COLORS: dict[LogLevel, tuple[str, ...]] = {
+    LogLevel.ALL: (),
+    LogLevel.NONE: (),
+    LogLevel.TRACE: ("gray",),
+    LogLevel.DEBUG: ("blue",),
+    LogLevel.INFO: ("green",),
+    LogLevel.WARN: ("yellow",),
+    LogLevel.ERROR: ("red",),
+    LogLevel.FATAL: ("bg_bright_red", "black"),
+}
+
+
+def _paint(text: str, *colors: str) -> str:
+    return "".join(f"\x1b[{_COLORS[c]}m" for c in colors) + text + "\x1b[0m"
+
+
+def _plain(text: str, *_colors: str) -> str:
+    return text
+
+
+def console_pretty(
+    *, colors: bool | None = None, format_date: Callable[[datetime], str] = default_date_format
+) -> Logger[None]:
+    """A readable multi-line logger for terminals: a colored header with
+    the first message, then the cause, the other items and the
+    annotations, indented in a console group. ``colors`` defaults to
+    whether stdout is a terminal."""
+    show = sys.stdout.isatty() if colors is None else colors
+    color = _paint if show else _plain
+
+    def log(options: Options) -> None:
+        fiber = options.fiber
+        console = fiber.get_ref(CurrentConsole)
+        write = console.error if fiber.get_ref(LogToStderr) else console.log
+        level = options.log_level
+        items = list(options.message)
+        first_line = (
+            color(f"[{format_date(options.date)}]", "white")
+            + f" {color(str(level).upper(), *_LEVEL_COLORS[level])}"
+            + f" (#{fiber.id}){_spans(options)}:"
+        )
+        if items and isinstance(first := structured_message(items[0]), str):
+            first_line += " " + color(first, "bold", "cyan")
+            items.pop(0)
+        write(first_line)
+        console.group()
+        try:
+            if options.cause.reasons:
+                write(options.cause.pretty())
+            for item in items:
+                write(item)
+            for key, value in fiber.get_ref(CurrentLogAnnotations).items():
+                write(color(f"{key}:", "bold", "white"), value)
+        finally:
+            console.group_end()
+
+    return Logger(log)

pyfect/logger/_file.py

@@ -0,0 +1,31 @@
+"""``Logger.to_file``: a logger appending lines to a file through the
+``FileSystem`` service."""
+
+from __future__ import annotations
+
+from collections.abc import Generator, Sequence
+from typing import Any
+
+from pyfect._core import Effect
+from pyfect._js import text_encode
+from pyfect.duration import Duration
+from pyfect.effect import gen
+from pyfect.file_system import FileSystem, OpenFlag
+from pyfect.logger._model import Logger
+from pyfect.platform_error import PlatformError
+from pyfect.scope import Scope
+
+
+def to_file(
+    logger: Logger[str], path: str, *, flag: OpenFlag, mode: int, batch_window: Duration
+) -> Effect[Logger[None], PlatformError, Scope | FileSystem]:
+    def build() -> Generator[Effect[Any, PlatformError, Scope | FileSystem], Any, Logger[None]]:
+        fs = yield from FileSystem()
+        file = yield from fs.open(path, flag=flag, mode=mode)
+
+        def flush(lines: Sequence[str]) -> Effect[object]:
+            return file.write_all(text_encode("\n".join(lines) + "\n")).ignore()
+
+        return (yield from logger.batched(window=batch_window, flush=flush))
+
+    return gen(build)

pyfect/logger/_formats.py

@@ -0,0 +1,104 @@
+"""Loggers that render an entry: ``format_simple`` and ``format_logfmt``
+(``key=value`` lines), ``format_structured`` (a dict) and ``format_json``,
+plus ``console_*`` loggers writing them to the console."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import NotRequired, TypedDict
+
+from pyfect.logger._model import Logger, Options
+from pyfect.logger._refs import CurrentLogAnnotations, CurrentLogSpans
+from pyfect.logger._text import (
+    escape_double_quotes,
+    format_label,
+    format_log_span,
+    format_unknown,
+    is_text_only,
+    iso_millis,
+    json_quote_line,
+    json_text,
+    structured_message,
+)
+
+
+def _key_values(quote: Callable[[str], str]) -> Callable[[Options], str]:
+    def text(value: object) -> str:
+        return value if isinstance(value, str) else format_unknown(value)
+
+    def pair(label: str, value: str) -> str:
+        return f"{format_label(label)}={value if is_text_only(value) else quote(value)}"
+
+    def render(options: Options) -> str:
+        fiber = options.fiber
+        parts = [
+            pair("timestamp", iso_millis(options.date)),
+            pair("level", str(options.log_level).upper()),
+            pair("fiber", f"#{fiber.id}"),
+        ]
+        parts.extend(pair("message", text(m)) for m in options.message)
+        if options.cause.reasons:
+            parts.append(pair("cause", options.cause.pretty()))
+        now = options.millis
+        parts.extend(format_log_span(span, now) for span in fiber.get_ref(CurrentLogSpans))
+        parts.extend(
+            pair(label, text(value))
+            for label, value in fiber.get_ref(CurrentLogAnnotations).items()
+        )
+        return " ".join(parts)
+
+    return render
+
+
+format_simple: Logger[str] = Logger(_key_values(escape_double_quotes))
+"""``key=value`` pairs; values with spaces, ``=`` or ``"`` are quoted."""
+
+format_logfmt: Logger[str] = Logger(_key_values(json_quote_line))
+"""The logfmt format: ``key=value`` pairs, values that need it quoted as
+JSON strings."""
+
+
+class StructuredLog(TypedDict):
+    """An entry as ``format_structured`` gives it; the keys are Effect's.
+    ``message`` is the item when one was logged, else the list of them;
+    ``cause`` is there only when a cause was logged."""
+
+    message: object
+    level: str
+    timestamp: str
+    cause: NotRequired[str]
+    annotations: dict[str, object]
+    spans: dict[str, int]
+    fiberId: str
+
+
+def _structured(options: Options) -> StructuredLog:
+    fiber = options.fiber
+    now = options.millis
+    items = options.message
+    log: StructuredLog = {
+        "message": (
+            structured_message(items[0])
+            if len(items) == 1
+            else [structured_message(m) for m in items]
+        ),
+        "level": str(options.log_level).upper(),
+        "timestamp": iso_millis(options.date),
+        "annotations": {
+            k: structured_message(v) for k, v in fiber.get_ref(CurrentLogAnnotations).items()
+        },
+        "spans": {span.label: now - span.start for span in fiber.get_ref(CurrentLogSpans)},
+        "fiberId": f"#{fiber.id}",
+    }
+    if options.cause.reasons:
+        log["cause"] = options.cause.pretty()
+    return log
+
+
+format_structured: Logger[StructuredLog] = Logger(_structured)
+format_json: Logger[str] = format_structured.map(json_text)
+"""``format_structured`` as one line of JSON."""
+
+console_logfmt: Logger[None] = format_logfmt.with_console_log()
+console_structured: Logger[None] = format_structured.with_console_log()
+console_json: Logger[None] = format_json.with_console_log()

pyfect/logger/_layer.py

@@ -0,0 +1,50 @@
+"""``logger.layer``: install loggers for the effects a layer is provided
+to."""
+# pyright: reportPrivateUsage=false
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import Any, Never, overload
+
+from pyfect._core import Effect, _Gen
+from pyfect.layer import Layer, effect
+from pyfect.logger._model import Logger
+from pyfect.logger._refs import CurrentLoggers
+from pyfect.scope import Scope
+
+type _Loggers[E, R] = Sequence[Logger[object] | Effect[Logger[object], E, R]]
+
+
+@overload
+def layer[E = Never](
+    loggers: Sequence[Logger[object] | Effect[Logger[object], E, Scope]],
+    *,
+    merge_with_existing: bool = False,
+) -> Layer[Never, E]: ...
+@overload
+def layer[E = Never, R = Never](
+    loggers: Sequence[Logger[object] | Effect[Logger[object], E, Scope | R]],
+    *,
+    merge_with_existing: bool = False,
+) -> Layer[Never, E, R]: ...
+def layer(
+    loggers: _Loggers[Any, Any], *, merge_with_existing: bool = False
+) -> Layer[Any, Any, Any]:
+    """A layer that replaces the current loggers with ``loggers`` (or adds
+    them, with ``merge_with_existing``). An item may be an effect making a
+    logger, such as ``Logger.batched``; it runs when the layer builds, and
+    its resources are released with the layer."""
+    given = list(loggers)
+
+    def build():
+        current: list[Logger[Any]] = (
+            list((yield from CurrentLoggers())) if merge_with_existing else []
+        )
+        for item in given:
+            made = (yield from item) if isinstance(item, Effect) else item
+            if all(made is not existing for existing in current):
+                current.append(made)
+        return tuple(current)
+
+    return effect(CurrentLoggers, _Gen(build))

pyfect/logger/_level.py

@@ -0,0 +1,53 @@
+"""``LogLevel``: Effect's eight levels as an ``IntEnum``.
+
+The severities use the standard library's numbers (``logging.DEBUG`` is
+``LogLevel.DEBUG``), with ``TRACE`` at 5 below them. ``ALL`` and ``NONE``
+are thresholds only: nothing is logged at them, which ``Severity`` says.
+Levels order as Effect's do, so compare them with ``<`` and ``>``. A level
+prints as Effect's ``LogLevel`` string: ``str(LogLevel.INFO)`` is ``"Info"``.
+"""
+# pyright: reportPrivateUsage=false
+
+from __future__ import annotations
+
+from enum import IntEnum
+from typing import TYPE_CHECKING, Literal
+
+if TYPE_CHECKING:
+    from pyfect._core import Effect
+
+_MAX_SAFE_INTEGER = 2**53 - 1
+
+
+class LogLevel(IntEnum):
+    """Effect's log levels, in Effect's order (``values``)."""
+
+    ALL = -_MAX_SAFE_INTEGER
+    FATAL = 50
+    ERROR = 40
+    WARN = 30
+    INFO = 20
+    DEBUG = 10
+    TRACE = 5
+    NONE = _MAX_SAFE_INTEGER
+
+    def __str__(self) -> str:
+        """Effect's name for the level: ``"Info"``, ``"Warn"``, ``"All"``."""
+        return self.name.capitalize()
+
+    def __format__(self, format_spec: str) -> str:
+        return format(str(self), format_spec)
+
+    def is_enabled(self) -> Effect[bool]:
+        """Whether a log at this level passes the current
+        ``MinimumLogLevel``."""
+        from pyfect._core import _Succeed, _WithFiber
+        from pyfect.logger._refs import MinimumLogLevel
+
+        return _WithFiber(lambda fiber: _Succeed(fiber.get_ref(MinimumLogLevel) <= self))
+
+
+type Severity = Literal[
+    LogLevel.FATAL, LogLevel.ERROR, LogLevel.WARN, LogLevel.INFO, LogLevel.DEBUG, LogLevel.TRACE
+]
+"""A level a log can be written at: every level but ``ALL`` and ``NONE``."""

pyfect/logger/_log.py

@@ -0,0 +1,142 @@
+"""The logging effects: ``log`` and its levels, and
+``annotate_logs_scoped``."""
+# pyright: reportPrivateUsage=false
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from datetime import UTC, datetime, timedelta
+from typing import Any, Never, overload
+
+from pyfect._context_effects import update_service_scoped
+from pyfect._core import Effect, _Succeed, _WithFiber
+from pyfect._fiber import Fiber
+from pyfect.cause import Cause, Reason
+from pyfect.clock import Clock
+from pyfect.logger._level import LogLevel, Severity
+from pyfect.logger._model import Options
+from pyfect.logger._refs import (
+    CurrentLogAnnotations,
+    CurrentLoggers,
+    CurrentLogLevel,
+    MinimumLogLevel,
+    UnhandledLogLevel,
+)
+from pyfect.scope import Scope
+
+_VOID: Effect[None] = _Succeed(None)
+_EPOCH = datetime(1970, 1, 1, tzinfo=UTC)
+
+
+def log_with_level(level: Severity | None, *message: object) -> Effect[None]:
+    """Log ``message`` at ``level`` (``None``: the ``CurrentLogLevel``) to
+    every logger in ``CurrentLoggers``, unless ``MinimumLogLevel`` is above
+    it. ``Cause`` items are taken out of the message and logged as its
+    cause."""
+    reasons: list[Reason[object]] = []
+    items: list[object] = []
+    for item in message:
+        if isinstance(item, Cause):
+            reasons.extend(item.reasons)  # pyright: ignore[reportUnknownMemberType, reportUnknownArgumentType]
+        else:
+            items.append(item)
+    cause: Cause[object] = Cause(tuple(reasons))
+    logged = tuple(items)
+
+    def body(fiber: Fiber[Any, Any]) -> Effect[None]:
+        at = fiber.get_ref(CurrentLogLevel) if level is None else level
+        if fiber.get_ref(MinimumLogLevel) > at:
+            return _VOID
+        loggers = fiber.get_ref(CurrentLoggers)
+        if loggers:
+            nanos = fiber.get_ref(Clock).now_nanos_unsafe()
+            date = _EPOCH + timedelta(microseconds=nanos // 1000)
+            options = Options(logged, at, cause, fiber, date)
+            for logger in loggers:
+                logger.log(options)
+        return _VOID
+
+    return _WithFiber(body)
+
+
+def log(*message: object) -> Effect[None]:
+    """Log at the ``CurrentLogLevel`` (``INFO`` unless provided)."""
+    return log_with_level(None, *message)
+
+
+def log_fatal(*message: object) -> Effect[None]:
+    return log_with_level(LogLevel.FATAL, *message)
+
+
+def log_error(*message: object) -> Effect[None]:
+    return log_with_level(LogLevel.ERROR, *message)
+
+
+def log_warning(*message: object) -> Effect[None]:
+    return log_with_level(LogLevel.WARN, *message)
+
+
+def log_info(*message: object) -> Effect[None]:
+    return log_with_level(LogLevel.INFO, *message)
+
+
+def log_debug(*message: object) -> Effect[None]:
+    return log_with_level(LogLevel.DEBUG, *message)
+
+
+def log_trace(*message: object) -> Effect[None]:
+    return log_with_level(LogLevel.TRACE, *message)
+
+
+def log_unhandled(message: str, cause: Cause[object]) -> Effect[None]:
+    """Log a failure nobody can handle at the ``UnhandledLogLevel``."""
+
+    def body(fiber: Fiber[Any, Any]) -> Effect[None]:
+        level = fiber.get_ref(UnhandledLogLevel)
+        return _VOID if level is None else log_with_level(level, message, cause)
+
+    return _WithFiber(body)
+
+
+_MISSING = object()
+
+
+def _same(a: object, b: object) -> bool:
+    """JavaScript's ``===`` or ``Object.is``: the same object, or equal
+    strings, numbers or bytes (NaN equals NaN)."""
+    if a is b:
+        return True
+    if type(a) is not type(b) or not isinstance(a, str | int | float | bytes):
+        return False
+    return a == b or (isinstance(a, float) and a != a and b != b)  # noqa: PLR0124
+
+
+@overload
+def annotate_logs_scoped(key: str, value: object, /) -> Effect[None, Never, Scope]: ...
+@overload
+def annotate_logs_scoped(values: Mapping[str, object], /) -> Effect[None, Never, Scope]: ...
+def annotate_logs_scoped(
+    key_or_values: str | Mapping[str, object], value: object = _MISSING, /
+) -> Effect[None, Never, Scope]:
+    """Add log annotations for the rest of the current fiber's region,
+    until the current scope closes. Closing it restores each key's earlier
+    value (or removes the key), unless the key was set again since."""
+    added = {key_or_values: value} if isinstance(key_or_values, str) else dict(key_or_values)
+
+    def add(annotations: Mapping[str, object]) -> Mapping[str, object]:
+        return {**annotations, **added}
+
+    def restore(
+        before: Mapping[str, object], _updated: Mapping[str, object], now: Mapping[str, object]
+    ) -> Mapping[str, object]:
+        restored = dict(now)
+        for k, v in added.items():
+            if not _same(now.get(k, _MISSING), v):
+                continue
+            if k in before:
+                restored[k] = before[k]
+            else:
+                del restored[k]
+        return restored
+
+    return update_service_scoped(CurrentLogAnnotations, add, reset=restore)

pyfect/logger/_model.py

@@ -0,0 +1,163 @@
+"""``Logger[O]``: a function from one log entry (``Options``) to an output.
+
+Effect's ``Logger<Message, Output>`` also abstracts the message; every
+logger the runtime calls receives the logged items, so here the message is
+always that tuple and only the output varies.
+"""
+# pyright: reportPrivateUsage=false
+
+from __future__ import annotations
+
+from collections.abc import Callable, Sequence
+from dataclasses import dataclass
+from datetime import UTC, datetime, timedelta
+from typing import TYPE_CHECKING, Any, Generic, NamedTuple, Never, Self, TypeVar, overload
+
+from pyfect._unsubscripted import Unsubscripted
+from pyfect.cause import Cause
+from pyfect.logger._level import LogLevel
+
+if TYPE_CHECKING:
+    from pyfect._core import Effect
+    from pyfect._fiber import Fiber
+    from pyfect.console import Console
+    from pyfect.duration import Duration
+    from pyfect.file_system import FileSystem, OpenFlag
+    from pyfect.platform_error import PlatformError
+    from pyfect.scope import Scope
+
+O_co = TypeVar("O_co", covariant=True, default=Unsubscripted)
+
+_EPOCH = datetime(1970, 1, 1, tzinfo=UTC)
+_MILLISECOND = timedelta(milliseconds=1)
+
+
+class LogSpan(NamedTuple):
+    """A span opened by ``with_log_span``: its label and when it started,
+    in whole milliseconds since the epoch."""
+
+    label: str
+    start: int
+
+
+@dataclass(frozen=True, slots=True)
+class Options:
+    """One log entry, as each logger receives it."""
+
+    message: tuple[object, ...]
+    """The logged items, causes taken out."""
+    log_level: LogLevel
+    cause: Cause[object]
+    """The causes logged with the items, merged; empty when there were none."""
+    fiber: Fiber[Any, Any]
+    """The logging fiber. Read the annotations and spans with
+    ``fiber.get_ref(CurrentLogAnnotations)`` and ``CurrentLogSpans``."""
+    date: datetime
+    """When it was logged, by the fiber's ``Clock`` (aware, UTC)."""
+
+    @property
+    def millis(self) -> int:
+        """``date`` in whole milliseconds since the epoch."""
+        return (self.date - _EPOCH) // _MILLISECOND
+
+
+class Logger(Generic[O_co]):
+    """A logger producing ``O`` from each entry. Make one with
+    ``Logger.make``; install it with ``logger.layer([...])`` or
+    ``eff.with_logger(...)``."""
+
+    __slots__ = ("_log",)
+
+    def __init__(self, log: Callable[[Options], O_co]) -> None:
+        self._log = log
+
+    @overload
+    @classmethod
+    def make[O](cls: type[Logger[Unsubscripted]], log: Callable[[Options], O]) -> Logger[O]: ...
+    @overload
+    @classmethod
+    def make(cls, log: Callable[[Options], O_co]) -> Logger[O_co]: ...
+    @classmethod
+    def make[O](cls, log: Callable[[Options], O]) -> Logger[O]:
+        return Logger(log)
+
+    def log(self, options: Options) -> O_co:
+        return self._log(options)
+
+    def map[O2](self, f: Callable[[O_co], O2]) -> Logger[O2]:
+        """A logger whose output is ``f`` of this one's."""
+        log = self._log
+        return Logger(lambda options: f(log(options)))
+
+    def with_console_log(self) -> Logger[None]:
+        """Write the output to the current console with ``log``."""
+        return self._to_console(lambda console, _level: console.log)
+
+    def with_console_error(self) -> Logger[None]:
+        """Write the output to the current console with ``error``."""
+        return self._to_console(lambda console, _level: console.error)
+
+    def with_leveled_console(self) -> Logger[None]:
+        """Write the output with the console method matching the level:
+        ``debug``, ``info``, ``trace``, ``warn``, ``error`` (for ``ERROR``
+        and ``FATAL``)."""
+
+        def method(console: Console, level: LogLevel) -> Callable[..., None]:
+            match level:
+                case LogLevel.DEBUG:
+                    return console.debug
+                case LogLevel.INFO:
+                    return console.info
+                case LogLevel.TRACE:
+                    return console.trace
+                case LogLevel.WARN:
+                    return console.warn
+                case LogLevel.ERROR | LogLevel.FATAL:
+                    return console.error
+                case _:
+                    return console.log
+
+        return self._to_console(method)
+
+    def _to_console(self, pick: Callable[[Console, LogLevel], Callable[..., None]]) -> Logger[None]:
+        from pyfect.console import CurrentConsole
+
+        log = self._log
+
+        def write(options: Options) -> None:
+            console = options.fiber.get_ref(CurrentConsole)
+            pick(console, options.log_level)(log(options))
+
+        return Logger(write)
+
+    def batched(
+        self, *, window: Duration, flush: Callable[[Sequence[O_co]], Effect[object]]
+    ) -> Effect[Logger[None], Never, Scope]:
+        """A logger that buffers this one's outputs and hands them to
+        ``flush`` every ``window``, and once more when the scope closes
+        (after any flush in progress)."""
+        from pyfect.logger._batched import batched
+
+        return batched(self, window, flush)
+
+    def to_file(
+        self: Logger[str],
+        path: str,
+        *,
+        flag: OpenFlag = "a+",
+        mode: int = 0o666,
+        batch_window: Duration = 1.0,
+    ) -> Effect[Logger[None], PlatformError, Scope | FileSystem]:
+        """A logger appending this one's lines to the file at ``path``
+        (opened with ``flag`` until the scope closes), written in batches
+        every ``batch_window``; a failed write is dropped (Effect's
+        ``Logger.toFile``)."""
+        from pyfect.logger._file import to_file
+
+        return to_file(self, path, flag=flag, mode=mode, batch_window=batch_window)
+
+    def __repr__(self) -> str:
+        return f"Logger({self._log!r})"
+
+    def pipe[B](self, f: Callable[[Self], B], /) -> B:
+        return f(self)