nnlogging 0.1.2__py3-none-any.whl

nnlogging/__init__.py

@@ -0,0 +1,16 @@
+"""
+Package: `nnlogging`
+Version: ``0.1.1``
+"""
+
+from .shell import (
+    Shell,
+    get_global_shell,
+    replace_global_shell,
+)
+
+__all__ = [
+    "Shell",
+    "get_global_shell",
+    "replace_global_shell",
+]

nnlogging/shell.py

@@ -0,0 +1,450 @@
+import sys
+from collections.abc import Collection
+from logging import Formatter as LoggingFormatter, Logger as LoggingLogger
+from typing import Literal, cast
+
+from aim import Repo as AimRepo, Run as AimRun
+from aim.sdk.types import AimObject
+from rich.highlighter import Highlighter as RichHighlighter
+from rich.progress import ProgressColumn as RichProgressColumn
+from rich.theme import Theme as RichTheme
+
+from nnlogging.typings import (
+    Branch,
+    ConsolePrintOptions,
+    FormatTimeCallable,
+    LogOptions,
+    Omitable,
+    Sink,
+)
+from nnlogging.utils import (
+    BranchConfig,
+    LoggerConfig,
+    RunConfig,
+    add_tag as _add_tag,
+    advance as _advance,
+    branch_add as _branch_add,
+    branch_configure as _branch_configure,
+    branch_remove as _branch_remove,
+    critical as _critical,
+    debug as _debug,
+    error as _error,
+    exception as _exception,
+    info as _info,
+    log as _log,
+    logger_configure as _logger_configure,
+    remove_tag as _remove_tag,
+    run_configure as _run_configure,
+    task_add as _task_add,
+    task_remove as _task_remove,
+    track as _track,
+    update_metadata as _update_metadata,
+    warn as _warn,
+)
+
+global_shell = None
+
+
+class Shell:
+    def __init__(
+        self,
+        shell_name: str = "nnlogging",
+        /,
+        *,
+        logger_config: LoggerConfig | None = None,
+        run_config: RunConfig | None = None,
+        branch_config: BranchConfig | None = None,
+    ):
+        self.logger: LoggingLogger | None = None
+        self.run: AimRun | None = None
+        self.branches: dict[str, Branch] = dict()
+
+        self.name: str = shell_name
+        self.logger_config: LoggerConfig = logger_config or LoggerConfig()
+        self.run_config: RunConfig = run_config or RunConfig()
+        self.branch_config: BranchConfig = branch_config or BranchConfig()
+
+    def logger_configure(
+        self,
+        config: LoggerConfig | None = None,
+        /,
+        *,
+        name: Omitable[str] = ...,
+        level: Omitable[int | str] = ...,
+        propagate: Omitable[bool] = ...,
+    ):
+        _logger_configure(
+            self,
+            config,
+            name=name,
+            level=level,
+            propagate=propagate,
+        )
+
+    def run_configure(
+        self,
+        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_configure(
+            self,
+            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 branch_configure(
+        self,
+        config: BranchConfig | None = None,
+        /,
+        *,
+        markup: Omitable[bool] = ...,
+        highlighter: Omitable[RichHighlighter] = ...,
+        width: Omitable[int | None] = ...,
+        height: Omitable[int | None] = ...,
+        emoji: Omitable[bool] = ...,
+        color_system: Omitable[Literal["auto", "standard", "truecolor"] | None] = ...,
+        theme: Omitable[RichTheme] = ...,
+        soft_wrap: Omitable[bool] = ...,
+        force_terminal: Omitable[bool | None] = ...,
+        force_jupyter: Omitable[bool | None] = ...,
+        force_interactive: Omitable[bool | None] = ...,
+        level: Omitable[str | int] = ...,
+        show_level: Omitable[bool] = ...,
+        show_time: Omitable[bool] = ...,
+        show_path: Omitable[bool] = ...,
+        log_time_format: Omitable[str | FormatTimeCallable] = ...,
+        omit_repeated_times: Omitable[bool] = ...,
+        rich_tracebacks: Omitable[bool] = ...,
+        tracebacks_show_locals: Omitable[bool] = ...,
+        log_message_format: Omitable[str | LoggingFormatter] = ...,
+        columns: Omitable[Collection[str | RichProgressColumn]] = ...,
+        transient: Omitable[bool] = ...,
+        refresh_per_second: Omitable[float] = ...,
+        speed_estimate_period: Omitable[float] = ...,
+        default_column_markup: Omitable[bool] = ...,
+    ):
+        _branch_configure(
+            self,
+            config,
+            markup=markup,
+            highlighter=highlighter,
+            width=width,
+            height=height,
+            emoji=emoji,
+            color_system=color_system,
+            theme=theme,
+            soft_wrap=soft_wrap,
+            force_terminal=force_terminal,
+            force_jupyter=force_jupyter,
+            force_interactive=force_interactive,
+            level=level,
+            show_level=show_level,
+            show_time=show_time,
+            show_path=show_path,
+            log_time_format=log_time_format,
+            omit_repeated_times=omit_repeated_times,
+            rich_tracebacks=rich_tracebacks,
+            tracebacks_show_locals=tracebacks_show_locals,
+            log_message_format=log_message_format,
+            columns=columns,
+            transient=transient,
+            refresh_per_second=refresh_per_second,
+            speed_estimate_period=speed_estimate_period,
+            default_column_markup=default_column_markup,
+        )
+
+    def branch_add(
+        self,
+        name: str,
+        /,
+        sink: Sink | None = None,
+        *,
+        markup: Omitable[bool] = ...,
+        highlighter: Omitable[RichHighlighter] = ...,
+        width: Omitable[int | None] = ...,
+        height: Omitable[int | None] = ...,
+        emoji: Omitable[bool] = ...,
+        color_system: Omitable[Literal["auto", "standard", "truecolor"] | None] = ...,
+        theme: Omitable[RichTheme] = ...,
+        soft_wrap: Omitable[bool] = ...,
+        force_terminal: Omitable[bool | None] = ...,
+        force_jupyter: Omitable[bool | None] = ...,
+        force_interactive: Omitable[bool | None] = ...,
+        level: Omitable[str | int] = ...,
+        show_level: Omitable[bool] = ...,
+        show_time: Omitable[bool] = ...,
+        show_path: Omitable[bool] = ...,
+        log_time_format: Omitable[str | FormatTimeCallable] = ...,
+        omit_repeated_times: Omitable[bool] = ...,
+        rich_tracebacks: Omitable[bool] = ...,
+        tracebacks_show_locals: Omitable[bool] = ...,
+        log_message_format: Omitable[str | LoggingFormatter] = ...,
+    ):
+        _branch_add(
+            self,
+            name,
+            sink=sink,
+            markup=markup,
+            highlighter=highlighter,
+            width=width,
+            height=height,
+            emoji=emoji,
+            color_system=color_system,
+            theme=theme,
+            soft_wrap=soft_wrap,
+            force_terminal=force_terminal,
+            force_jupyter=force_jupyter,
+            force_interactive=force_interactive,
+            level=level,
+            show_level=show_level,
+            show_time=show_time,
+            show_path=show_path,
+            log_time_format=log_time_format,
+            omit_repeated_times=omit_repeated_times,
+            rich_tracebacks=rich_tracebacks,
+            tracebacks_show_locals=tracebacks_show_locals,
+            log_message_format=log_message_format,
+        )
+
+    def branch_remove(
+        self,
+        name: str,
+        /,
+    ):
+        _branch_remove(
+            self,
+            name,
+        )
+
+    def task_add(
+        self,
+        name: str,
+        /,
+        *,
+        desc: str,
+        total: float | None,
+        done: float = 0,
+    ):
+        _task_add(
+            self,
+            name,
+            desc=desc,
+            total=total,
+            done=done,
+        )
+
+    def task_remove(
+        self,
+        name: str,
+        /,
+    ):
+        _task_remove(
+            self,
+            name,
+        )
+
+    def log(
+        self,
+        level: int,
+        msg: object,
+        *args: object,
+        log_options: LogOptions | None = None,
+        console_options: ConsolePrintOptions | None = None,
+    ):
+        _log(
+            self,
+            level,
+            msg,
+            *args,
+            log_options=log_options,
+            console_options=console_options,
+        )
+
+    def debug(
+        self,
+        msg: object,
+        *args: object,
+        log_options: LogOptions | None = None,
+        console_options: ConsolePrintOptions | None = None,
+    ):
+        _debug(
+            self,
+            msg,
+            *args,
+            log_options=log_options,
+            console_options=console_options,
+        )
+
+    def info(
+        self,
+        msg: object,
+        *args: object,
+        log_options: LogOptions | None = None,
+        console_options: ConsolePrintOptions | None = None,
+    ):
+        _info(
+            self,
+            msg,
+            *args,
+            log_options=log_options,
+            console_options=console_options,
+        )
+
+    def warn(
+        self,
+        msg: object,
+        *args: object,
+        log_options: LogOptions | None = None,
+        console_options: ConsolePrintOptions | None = None,
+    ):
+        _warn(
+            self,
+            msg,
+            *args,
+            log_options=log_options,
+            console_options=console_options,
+        )
+
+    def error(
+        self,
+        msg: object,
+        *args: object,
+        log_options: LogOptions | None = None,
+        console_options: ConsolePrintOptions | None = None,
+    ):
+        _error(
+            self,
+            msg,
+            *args,
+            log_options=log_options,
+            console_options=console_options,
+        )
+
+    def critical(
+        self,
+        msg: object,
+        *args: object,
+        log_options: LogOptions | None = None,
+        console_options: ConsolePrintOptions | None = None,
+    ):
+        _critical(
+            self,
+            msg,
+            *args,
+            log_options=log_options,
+            console_options=console_options,
+        )
+
+    def exception(
+        self,
+        msg: object,
+        *args: object,
+        log_options: LogOptions | None = None,
+        console_options: ConsolePrintOptions | None = None,
+    ):
+        _exception(
+            self,
+            msg,
+            *args,
+            log_options=log_options,
+            console_options=console_options,
+        )
+
+    def advance(
+        self,
+        name: str,
+        /,
+        value: float,
+    ):
+        _advance(
+            self,
+            name,
+            advance=value,
+        )
+
+    def track(
+        self,
+        value: object,
+        /,
+        name: str | None,
+        *,
+        step: int | None,
+        epoch: int | None,
+        context: AimObject,
+    ):
+        _track(
+            self,
+            value,
+            name=name,
+            step=step,
+            epoch=epoch,
+            context=context,
+        )
+
+    def add_tag(
+        self,
+        name: str,
+        /,
+    ):
+        _add_tag(
+            self,
+            name,
+        )
+
+    def remove_tag(
+        self,
+        name: str,
+        /,
+    ):
+        _remove_tag(
+            self,
+            name,
+        )
+
+    def update_metadata(
+        self,
+        name: str,
+        /,
+        metadata: AimObject,
+    ):
+        _update_metadata(
+            self,
+            name,
+            metadata,
+        )
+
+
+def get_global_shell(sink: Sink | Literal["stderr", "stdout"] = "stderr"):
+    global global_shell
+    if global_shell is None:
+        global_shell = Shell()
+        if isinstance(sink, str) and sink in ("stderr", "stdout"):
+            sink = cast(Sink, getattr(sys, sink))
+        global_shell.branch_add("default", sink)
+        global_shell.debug(f'"global_shell" is now initialized as {repr(global_shell)}')
+    return global_shell
+
+
+def replace_global_shell(shell: Shell):
+    global global_shell
+    msg = f'"global_shell" has been replaced from {repr(global_shell)} to {repr(shell)}'
+    if global_shell is not None:
+        global_shell.info(msg)
+    global_shell = shell
+    global_shell.debug(msg)

nnlogging/shell_protocol.py

@@ -0,0 +1,86 @@
+from logging import Logger as LoggingLogger
+from typing import Protocol, runtime_checkable
+
+from aim import Run as AimRun
+from aim.sdk.types import AimObject
+
+from nnlogging.typings import Branch, LogOptions
+from nnlogging.utils.factory_funcs.shell_ import BranchConfig, LoggerConfig, RunConfig
+
+
+@runtime_checkable
+class ShellProtocol(Protocol):
+    logger_config: LoggerConfig
+    run_config: RunConfig
+    branch_config: BranchConfig
+    logger: LoggingLogger | None
+    run: AimRun | None
+    branches: dict[str, Branch]
+
+    def logger_configure(
+        self,
+        config: LoggerConfig | None,
+        /,
+    ): ...
+    def run_configure(
+        self,
+        conf: RunConfig | None,
+        /,
+    ): ...
+    def branch_configure(
+        self,
+        conf: BranchConfig | None,
+        /,
+    ): ...
+    def branch_add(
+        self,
+        name: str,
+        /,
+    ): ...
+    def branch_remove(
+        self,
+        name: str,
+        /,
+    ): ...
+    def task_add(
+        self,
+        name: str,
+        /,
+        *,
+        desc: str,
+        total: float | None,
+    ): ...
+    def task_remove(
+        self,
+        name: str,
+        /,
+    ): ...
+    def log(
+        self,
+        level: int,
+        msg: object,
+        /,
+    ): ...
+    def exception(
+        self,
+        msg: object,
+        /,
+        *,
+        log_options: LogOptions | None = None,
+    ): ...
+    def advance(
+        self,
+        name: str,
+        /,
+        value: float,
+    ): ...
+    def track(
+        self,
+        value: object,
+        /,
+        name: str | None,
+        *,
+        step: int | None,
+        epoch: int | None,
+        context: AimObject,
+    ): ...

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: ...