nnlogging 0.1.0__py3-none-any.whl → 0.1.1__py3-none-any.whl

nnlogging/shell/utils/logger_funcs.py

@@ -0,0 +1,198 @@
+import logging
+
+from rich.console import ConsoleRenderable as RichConsoleRenderable
+
+from nnlogging.shell.protocol import ShellProtocol
+from nnlogging.typings import ConsolePrintOptions, LogOptions, Omitable
+from nnlogging.utils import LoggerConfig, evolve_, get_logging_logger
+
+
+def _logger_open(
+    inst: ShellProtocol,
+    /,
+):
+    if inst.logger is None:
+        logging.captureWarnings(True)
+        inst.logger = get_logging_logger(inst.logger_config)
+        for name in inst.branches:
+            branch = inst.branches[name]
+            inst.logger.addHandler(branch["handler"])
+            # TODO: add `filter` support in v0.2.0
+
+
+def _logger_close(
+    inst: ShellProtocol,
+    /,
+):
+    if inst.logger is not None:
+        logging.captureWarnings(False)
+        for handler in inst.logger.handlers[:]:
+            inst.logger.removeHandler(handler)
+            handler.close()
+        # TODO: add `filter` support in v0.2.0
+        # inst.logger.filters.clear()
+        inst.logger.setLevel(logging.NOTSET)
+        inst.logger.propagate = False
+        inst.logger = None
+
+
+def logger_configure(
+    inst: ShellProtocol,
+    /,
+    config: LoggerConfig | None = None,
+    *,
+    name: Omitable[str] = ...,
+    level: Omitable[int | str] = ...,
+    propagate: Omitable[bool] = ...,
+):
+    _logger_close(inst)
+    inst.logger_config = evolve_(
+        config or inst.logger_config,
+        name=name,
+        level=level,
+        propagate=propagate,
+    )
+
+
+def log(
+    inst: ShellProtocol,
+    /,
+    level: int,
+    msg: object,
+    *args: object,
+    log_options: LogOptions | None = None,
+    console_options: ConsolePrintOptions | None = None,
+):
+    _logger_open(inst)
+    assert inst.logger is not None
+    match msg:
+        case RichConsoleRenderable():
+            debug(
+                inst,
+                f"Sending {repr(msg)} to branches ...",
+                log_options=log_options or LogOptions(),
+            )
+            for name in inst.branches:
+                branch = inst.branches[name]
+                if level >= inst.logger.level and level >= branch["handler"].level:
+                    branch["console"].print(
+                        msg,
+                        *args,
+                        **(console_options or ConsolePrintOptions()),
+                    )
+        case _:
+            inst.logger.log(
+                level,
+                msg,
+                *args,
+                **(log_options or LogOptions()),
+            )
+
+
+def debug(
+    inst: ShellProtocol,
+    /,
+    msg: object,
+    *args: object,
+    log_options: LogOptions | None = None,
+    console_options: ConsolePrintOptions | None = None,
+):
+    log(
+        inst,
+        logging.DEBUG,
+        msg,
+        *args,
+        log_options=log_options,
+        console_options=console_options,
+    )
+
+
+def info(
+    inst: ShellProtocol,
+    /,
+    msg: object,
+    *args: object,
+    log_options: LogOptions | None = None,
+    console_options: ConsolePrintOptions | None = None,
+):
+    log(
+        inst,
+        logging.INFO,
+        msg,
+        *args,
+        log_options=log_options,
+        console_options=console_options,
+    )
+
+
+def warn(
+    inst: ShellProtocol,
+    /,
+    msg: object,
+    *args: object,
+    log_options: LogOptions | None = None,
+    console_options: ConsolePrintOptions | None = None,
+):
+    log(
+        inst,
+        logging.WARNING,
+        msg,
+        *args,
+        log_options=log_options,
+        console_options=console_options,
+    )
+
+
+def error(
+    inst: ShellProtocol,
+    /,
+    msg: object,
+    *args: object,
+    log_options: LogOptions | None = None,
+    console_options: ConsolePrintOptions | None = None,
+):
+    log(
+        inst,
+        logging.ERROR,
+        msg,
+        *args,
+        log_options=log_options,
+        console_options=console_options,
+    )
+
+
+def critical(
+    inst: ShellProtocol,
+    /,
+    msg: object,
+    *args: object,
+    log_options: LogOptions | None = None,
+    console_options: ConsolePrintOptions | None = None,
+):
+    log(
+        inst,
+        logging.CRITICAL,
+        msg,
+        *args,
+        log_options=log_options,
+        console_options=console_options,
+    )
+
+
+def exception(
+    inst: ShellProtocol,
+    /,
+    msg: object,
+    *args: object,
+    log_options: LogOptions | None = None,
+    console_options: ConsolePrintOptions | None = None,
+):
+    default_log_options = LogOptions(exc_info=True)
+    log(
+        inst,
+        logging.CRITICAL,
+        msg,
+        *args,
+        log_options=default_log_options | (log_options or LogOptions()),
+        console_options=console_options,
+    )

nnlogging/shell/utils/run_funcs.py

@@ -0,0 +1,96 @@
+from aim import Repo as AimRepo
+from aim.sdk.types import AimObject
+
+from nnlogging.shell.protocol import ShellProtocol
+from nnlogging.typings import Omitable
+from nnlogging.utils import RunConfig, evolve_, get_aim_run
+
+
+def _run_open(
+    inst: ShellProtocol,
+    /,
+):
+    if inst.run is None:
+        inst.run = get_aim_run(inst.run_config)
+
+
+def _run_close(
+    inst: ShellProtocol,
+    /,
+):
+    if inst.run is not None:
+        inst.run.close()
+        del inst.run
+        inst.run = None
+
+
+def run_configure(
+    inst: ShellProtocol,
+    /,
+    config: RunConfig | None = None,
+    *,
+    experiment: Omitable[str | None] = ...,
+    repo: Omitable[str | AimRepo | None] = ...,
+    system_tracking_interval: Omitable[float | None] = ...,
+    capture_terminal_logs: Omitable[bool] = ...,
+    log_system_params: Omitable[bool] = ...,
+    run_hash: Omitable[str | None] = ...,
+    read_only: Omitable[bool] = ...,
+    force_resume: Omitable[bool] = ...,
+):
+    _run_close(inst)
+    inst.run_config = evolve_(
+        config or inst.run_config,
+        experiment=experiment,
+        repo=repo,
+        system_tracking_interval=system_tracking_interval,
+        capture_terminal_logs=capture_terminal_logs,
+        log_system_params=log_system_params,
+        run_hash=run_hash,
+        read_only=read_only,
+        force_resume=force_resume,
+    )
+
+
+def update_metadata(
+    inst: ShellProtocol,
+    /,
+    label: str,
+    metadata: AimObject,
+):
+    _run_open(inst)
+    assert inst.run is not None
+    inst.run[label] = metadata
+
+
+def add_tag(inst: ShellProtocol, /, tag: str):
+    _run_open(inst)
+    assert inst.run is not None
+    inst.run.add_tag(tag)
+
+
+def remove_tag(inst: ShellProtocol, /, tag: str):
+    _run_open(inst)
+    assert inst.run is not None
+    inst.run.remove_tag(tag)
+
+
+def track(
+    inst: ShellProtocol,
+    /,
+    value: object,
+    *,
+    name: str | None = None,
+    step: int | None = None,
+    epoch: int | None = None,
+    context: AimObject = None,
+):
+    _run_open(inst)
+    assert inst.run is not None
+    inst.run.track(
+        value,
+        name=name,  # pyright: ignore[reportArgumentType]
+        step=step,  # pyright: ignore[reportArgumentType]
+        epoch=epoch,  # pyright: ignore[reportArgumentType]
+        context=context,
+    )

nnlogging/shell/utils/task_funcs.py

@@ -0,0 +1,115 @@
+import sys
+
+from nnlogging.shell.exception import (
+    raise_task_exists_error,
+    raise_task_not_found_error,
+)
+from nnlogging.shell.protocol import ShellProtocol
+from nnlogging.utils import get_rich_progress
+
+sys.version_info.major
+
+
+def _task_open(
+    inst: ShellProtocol,
+    /,
+    name: str,
+):
+    for branch_name in inst.branches:
+        branch = inst.branches[branch_name]
+        if name in branch["tasks"]:
+            raise_task_exists_error(
+                inst,
+                branch_name,
+                name,
+                stacklevel=2,
+            )
+        if branch["progress"] is None:
+            progress = get_rich_progress(
+                branch["console"],
+                columns=inst.branch_config.columns,
+                transient=inst.branch_config.transient,
+                refresh_per_second=inst.branch_config.refresh_per_second,
+                speed_estimate_period=inst.branch_config.speed_estimate_period,
+                default_column_markup=inst.branch_config.default_column_markup,
+            )
+            progress.start()
+            branch["progress"] = progress
+
+
+def _task_close(
+    inst: ShellProtocol,
+    /,
+    name: str,
+):
+    task_found = False
+    for branch_name in inst.branches:
+        branch = inst.branches[branch_name]
+        if name in branch["tasks"]:
+            task_found = True
+            assert branch["progress"] is not None  # definitely
+            task_id = branch["tasks"][name]
+            if branch["progress"]._tasks[task_id].finished:  # pyright: ignore[reportPrivateUsage]
+                del branch["tasks"][name]
+            if branch["progress"].finished:
+                branch["progress"].stop()
+                branch["progress"] = None
+    if not task_found:
+        raise_task_not_found_error(
+            inst,
+            name,
+            stacklevel=2,
+        )
+
+
+def task_add(
+    inst: ShellProtocol,
+    /,
+    name: str,
+    *,
+    desc: str,
+    total: float | None,
+    done: float = 0,
+):
+    _task_open(inst, name)
+    for branch_name in inst.branches:
+        branch = inst.branches[branch_name]
+        assert branch["progress"] is not None  # definitely
+        task_id = branch["progress"].add_task(
+            description=desc,
+            total=total,
+            completed=done,  # pyright: ignore[reportArgumentType]
+        )
+        branch["tasks"][name] = task_id
+
+
+def task_remove(
+    inst: ShellProtocol,
+    /,
+    name: str,
+):
+    for branch_name in inst.branches:
+        branch = inst.branches[branch_name]
+        if name in branch["tasks"]:
+            assert branch["progress"] is not None  # definitely
+            task_id = branch["tasks"][name]
+            branch["progress"]._tasks[task_id].finished_time = 0  # pyright: ignore[reportPrivateUsage]
+    _task_close(inst, name)
+
+
+def advance(
+    inst: ShellProtocol,
+    /,
+    name: str,
+    *,
+    advance: float,
+):
+    for branch_name in inst.branches:
+        branch = inst.branches[branch_name]
+        assert branch["progress"] is not None  # definitely
+        task_id = branch["tasks"][name]
+        branch["progress"].advance(
+            task_id=task_id,
+            advance=advance,
+        )
+    _task_close(inst, name)

nnlogging/typings/__init__.py

@@ -0,0 +1,41 @@
+from .aliases import (
+    Branch,
+    ConsolePrintOptions,
+    ExcInfo,
+    FormatTimeCallable,
+    GenericPath,
+    LogOptions,
+    Sink,
+)
+from .exceptions import (
+    BranchExistsError,
+    BranchNotFoundError,
+    TaskExistsError,
+    TaskNotFoundError,
+)
+from .generics import DataclassT, Omitable, Pathlike, T
+from .protocols import TerminalWritable, Writable
+
+__all__ = [
+    # aliases
+    "Branch",
+    "Sink",
+    "GenericPath",
+    "FormatTimeCallable",
+    "ExcInfo",
+    "ConsolePrintOptions",
+    "LogOptions",
+    # generics
+    "T",
+    "DataclassT",
+    "Omitable",
+    "Pathlike",
+    # protocols
+    "Writable",
+    "TerminalWritable",
+    # exception
+    "BranchNotFoundError",
+    "BranchExistsError",
+    "TaskExistsError",
+    "TaskNotFoundError",
+]

nnlogging/typings/aliases.py

@@ -0,0 +1,66 @@
+import sys
+from collections.abc import Mapping
+from datetime import datetime
+from types import TracebackType
+from typing import Callable, Literal, TypeAlias, TypedDict
+
+from rich.console import Console as RichConsole
+from rich.logging import RichHandler
+from rich.progress import Progress as RichProgress, TaskID as RichTaskID
+from rich.style import Style as RichStyle
+from rich.text import Text as RichText
+
+from nnlogging.typings.generics import Pathlike
+from nnlogging.typings.protocols import TerminalWritable, Writable
+
+if sys.version_info >= (3, 11):
+    from typing import NotRequired, Required
+else:
+    from typing_extensions import NotRequired, Required
+
+
+Sink: TypeAlias = Writable | TerminalWritable
+GenericPath = Pathlike[str] | Pathlike[bytes]
+FormatTimeCallable: TypeAlias = Callable[[datetime], RichText]
+
+
+class Branch(TypedDict):
+    console: Required[RichConsole]
+    handler: Required[RichHandler]
+    tasks: Required[dict[str, RichTaskID]]
+    progress: Required[RichProgress | None]
+
+
+JustifyMethod = Literal["default", "left", "center", "right", "full"]
+OverflowMethod = Literal["fold", "crop", "ellipsis", "ignore"]
+
+
+class ConsolePrintOptions(TypedDict):
+    sep: NotRequired[str]
+    end: NotRequired[str]
+    style: NotRequired[str | RichStyle | None]
+    justify: NotRequired[JustifyMethod | None]
+    overflow: NotRequired[OverflowMethod | None]
+    no_wrap: NotRequired[bool | None]
+    emoji: NotRequired[bool | None]
+    markup: NotRequired[bool | None]
+    highlight: NotRequired[bool | None]
+    width: NotRequired[int | None]
+    height: NotRequired[int | None]
+    crop: NotRequired[bool]
+    soft_wrap: NotRequired[bool | None]
+    new_line_start: NotRequired[bool]
+
+
+_SysExcInfo: TypeAlias = (
+    tuple[type[BaseException], BaseException, TracebackType | None]
+    | tuple[None, None, None]
+)
+ExcInfo: TypeAlias = None | bool | _SysExcInfo | BaseException
+
+
+class LogOptions(TypedDict):
+    exc_info: NotRequired[ExcInfo]
+    stack_info: NotRequired[bool]
+    stacklevel: NotRequired[int]
+    extra: NotRequired[Mapping[str, object] | None]

nnlogging/typings/exceptions.py

@@ -0,0 +1,10 @@
+class BranchExistsError(LookupError): ...
+
+
+class BranchNotFoundError(LookupError): ...
+
+
+class TaskExistsError(LookupError): ...
+
+
+class TaskNotFoundError(LookupError): ...

nnlogging/typings/generics.py

@@ -0,0 +1,23 @@
+import sys
+from dataclasses import Field
+from os import PathLike
+from types import EllipsisType
+from typing import Any, ClassVar, Protocol, TypeVar
+
+if sys.version_info >= (3, 12):
+    from typing import TypeAliasType
+else:
+    from typing_extensions import TypeAliasType
+
+
+class DataclassInstance(Protocol):
+    __dataclass_fields__: ClassVar[dict[str, Field[Any]]]  # pyright: ignore[reportExplicitAny]
+
+
+T = TypeVar("T")
+PathT = TypeVar("PathT", str, bytes)
+
+
+Omitable = TypeAliasType("Omitable", T | EllipsisType, type_params=(T,))
+DataclassT = TypeVar("DataclassT", bound=DataclassInstance)
+Pathlike = TypeAliasType("Pathlike", PathT | PathLike[PathT], type_params=(PathT,))

nnlogging/typings/protocols.py

@@ -0,0 +1,14 @@
+from typing import Protocol, runtime_checkable
+
+
+@runtime_checkable
+class Writable(Protocol):
+    def write(self, text: str, /) -> int: ...
+    def flush(self) -> None: ...
+
+
+@runtime_checkable
+class TerminalWritable(Protocol):
+    def write(self, text: str, /) -> int: ...
+    def flush(self) -> None: ...
+    def isatty(self) -> bool: ...

nnlogging/utils/__init__.py

@@ -0,0 +1,39 @@
+"""
+``nnlogging.utils``
+"""
+
+from .helpers import evolve_, get__debugging, get_name, or_
+from .rich_factories import (
+    get_rich_console,
+    get_rich_handler,
+    get_rich_progress,
+    get_rich_progress_default_columns,
+)
+from .shell_factories import (
+    BranchConfig,
+    LoggerConfig,
+    RunConfig,
+    get_aim_run,
+    get_branch,
+    get_logging_logger,
+)
+
+__all__ = [
+    # helper
+    "evolve_",
+    "or_",
+    "get__debugging",
+    "get_name",
+    # rich factory
+    "get_rich_console",
+    "get_rich_handler",
+    "get_rich_progress",
+    "get_rich_progress_default_columns",
+    # shell factory
+    "LoggerConfig",
+    "get_logging_logger",
+    "RunConfig",
+    "get_aim_run",
+    "BranchConfig",
+    "get_branch",
+]

nnlogging/utils/helpers.py

@@ -0,0 +1,39 @@
+from dataclasses import replace
+from types import EllipsisType
+
+from nnlogging.typings import DataclassT, Omitable, T
+
+
+def or_(
+    value: Omitable[T],
+    default: T,
+    /,
+) -> T:
+    return default if isinstance(value, EllipsisType) else value
+
+
+def evolve_(
+    inst: DataclassT,
+    /,
+    **kwargs: object,
+) -> DataclassT:
+    evolutions = {k: v for k, v in kwargs.items() if not isinstance(v, EllipsisType)}
+    return replace(inst, **evolutions)
+
+
+def get_name(
+    inst: object,
+    /,
+):
+    inst_name = getattr(inst, "name", str(inst))
+    assert isinstance(inst_name, str)
+    return inst_name
+
+
+def get__debugging(
+    inst: object,
+    /,
+):
+    inst_debugging = getattr(inst, "_debugging", False)
+    assert isinstance(inst_debugging, bool)
+    return inst_debugging