nnlogging 0.1.2__py3-none-any.whl

nnlogging/utils/__init__.py

@@ -0,0 +1,83 @@
+"""
+``nnlogging.utils``
+"""
+
+from .exception import (
+    raise_branch_exists_error,
+    raise_branch_not_found_error,
+    raise_task_exists_error,
+    raise_task_not_found_error,
+)
+from .factory_funcs.rich_ import (
+    get_rich_console,
+    get_rich_handler,
+    get_rich_progress,
+    get_rich_progress_default_columns,
+)
+from .factory_funcs.shell_ import (
+    BranchConfig,
+    LoggerConfig,
+    RunConfig,
+    get_aim_run,
+    get_branch,
+    get_logging_logger,
+)
+from .helpers import evolve_, get__debugging, get_name, or_
+from .shell_funcs.branch_ import branch_add, branch_configure, branch_remove
+from .shell_funcs.logger_ import (
+    critical,
+    debug,
+    error,
+    exception,
+    info,
+    log,
+    logger_configure,
+    warn,
+)
+from .shell_funcs.run_ import add_tag, remove_tag, run_configure, track, update_metadata
+from .shell_funcs.task_ import advance, task_add, task_remove
+
+__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",
+    # shell func
+    "branch_add",
+    "branch_configure",
+    "branch_remove",
+    "critical",
+    "debug",
+    "error",
+    "exception",
+    "info",
+    "log",
+    "logger_configure",
+    "warn",
+    "add_tag",
+    "remove_tag",
+    "run_configure",
+    "track",
+    "update_metadata",
+    "advance",
+    "task_add",
+    "task_remove",
+    # exception
+    "raise_branch_exists_error",
+    "raise_branch_not_found_error",
+    "raise_task_exists_error",
+    "raise_task_not_found_error",
+]

nnlogging/utils/exception/__init__.py

@@ -0,0 +1,11 @@
+from .branch_exists import raise_branch_exists_error
+from .branch_not_found import raise_branch_not_found_error
+from .task_exists import raise_task_exists_error
+from .task_not_found import raise_task_not_found_error
+
+__all__ = [
+    "raise_branch_exists_error",
+    "raise_branch_not_found_error",
+    "raise_task_exists_error",
+    "raise_task_not_found_error",
+]

nnlogging/utils/exception/branch_exists.py

@@ -0,0 +1,49 @@
+import sys
+
+from nnlogging.shell_protocol import ShellProtocol
+from nnlogging.typings import BranchExistsError, LogOptions
+from nnlogging.utils.helpers import get__debugging, get_name
+
+if sys.version_info >= (3, 11):
+    from typing import Never
+else:
+    from typing_extensions import Never
+
+
+def _branch_exists_msg(
+    inst: ShellProtocol,
+    name: str,
+    /,
+):
+    return f'branch "{name}" already exists in {get_name(inst)}.branches'
+
+
+def _branch_exists_error(
+    inst: ShellProtocol,
+    name: str,
+    /,
+):
+    return BranchExistsError(
+        f'branch "{name}" already exists in {get_name(inst)}.branches: {inst.branches}'
+    )
+
+
+def raise_branch_exists_error(
+    inst: ShellProtocol,
+    name: str,
+    /,
+    *,
+    stacklevel: int = 1,
+) -> Never:
+    try:
+        raise _branch_exists_error(inst, name)
+    except BranchExistsError as e:
+        inst.exception(
+            _branch_exists_msg(inst, name),
+            log_options=LogOptions(
+                exc_info=e,
+                stack_info=get__debugging(inst),
+                stacklevel=stacklevel + 1,
+            ),
+        )
+        raise

nnlogging/utils/exception/branch_not_found.py

@@ -0,0 +1,49 @@
+import sys
+
+from nnlogging.shell_protocol import ShellProtocol
+from nnlogging.typings import BranchNotFoundError, LogOptions
+from nnlogging.utils.helpers import get__debugging, get_name
+
+if sys.version_info >= (3, 11):
+    from typing import Never
+else:
+    from typing_extensions import Never
+
+
+def _branch_not_found_msg(
+    inst: ShellProtocol,
+    name: str,
+    /,
+):
+    return f'branch "{name}" not found in {get_name(inst)}.branches'
+
+
+def _branch_not_found_error(
+    inst: ShellProtocol,
+    name: str,
+    /,
+):
+    return BranchNotFoundError(
+        f'branch "{name}" not found in {get_name(inst)}.branches: {inst.branches}'
+    )
+
+
+def raise_branch_not_found_error(
+    inst: ShellProtocol,
+    name: str,
+    /,
+    *,
+    stacklevel: int = 1,
+) -> Never:
+    try:
+        raise _branch_not_found_error(inst, name)
+    except BranchNotFoundError as e:
+        inst.exception(
+            _branch_not_found_msg(inst, name),
+            log_options=LogOptions(
+                exc_info=e,
+                stack_info=get__debugging(inst),
+                stacklevel=stacklevel + 1,
+            ),
+        )
+        raise

nnlogging/utils/exception/task_exists.py

@@ -0,0 +1,54 @@
+import sys
+
+from nnlogging.shell_protocol import ShellProtocol
+from nnlogging.typings import LogOptions, TaskExistsError
+from nnlogging.utils.helpers import get__debugging, get_name
+
+if sys.version_info >= (3, 11):
+    from typing import Never
+else:
+    from typing_extensions import Never
+
+
+def _task_exists_msg(
+    inst: ShellProtocol,
+    branch: str,
+    name: str,
+    /,
+):
+    return (
+        f'task "{name}" already exists in {get_name(inst)}.branches."{branch}"."tasks"'
+    )
+
+
+def _task_exists_error(
+    inst: ShellProtocol,
+    branch: str,
+    name: str,
+    /,
+):
+    return TaskExistsError(
+        f'task "{name}" already exists in {get_name(inst)}.branches."{branch}"."tasks": {inst.branches[branch]["tasks"]}'
+    )
+
+
+def raise_task_exists_error(
+    inst: ShellProtocol,
+    branch: str,
+    name: str,
+    /,
+    *,
+    stacklevel: int = 1,
+) -> Never:
+    try:
+        raise _task_exists_error(inst, branch, name)
+    except TaskExistsError as e:
+        inst.exception(
+            _task_exists_msg(inst, branch, name),
+            log_options=LogOptions(
+                exc_info=e,
+                stack_info=get__debugging(inst),
+                stacklevel=stacklevel + 1,
+            ),
+        )
+        raise

nnlogging/utils/exception/task_not_found.py

@@ -0,0 +1,49 @@
+import sys
+
+from nnlogging.shell_protocol import ShellProtocol
+from nnlogging.typings import LogOptions, TaskNotFoundError
+from nnlogging.utils.helpers import get__debugging, get_name
+
+if sys.version_info >= (3, 11):
+    from typing import Never
+else:
+    from typing_extensions import Never
+
+
+def _task_not_found_msg(
+    inst: ShellProtocol,
+    name: str,
+    /,
+):
+    return f'task "{name}" not found in {get_name(inst)}.branches'
+
+
+def _task_not_found_error(
+    inst: ShellProtocol,
+    name: str,
+    /,
+):
+    return TaskNotFoundError(
+        f'task "{name}" not found in {get_name(inst)}.branches: {inst.branches}'
+    )
+
+
+def raise_task_not_found_error(
+    inst: ShellProtocol,
+    name: str,
+    /,
+    *,
+    stacklevel: int = 1,
+) -> Never:
+    try:
+        raise _task_not_found_error(inst, name)
+    except TaskNotFoundError as e:
+        inst.exception(
+            _task_not_found_msg(inst, name),
+            log_options=LogOptions(
+                exc_info=e,
+                stack_info=get__debugging(inst),
+                stacklevel=stacklevel + 1,
+            ),
+        )
+        raise

nnlogging/utils/factory_funcs/rich_.py

@@ -0,0 +1,154 @@
+import logging
+from collections.abc import Collection
+from logging import Formatter as LoggingFormatter
+from sys import stderr
+from typing import Literal
+
+from rich.console import Console as RichConsole
+from rich.highlighter import (
+    Highlighter as RichHighlighter,
+    NullHighlighter as RichNullHighlighter,
+)
+from rich.logging import RichHandler
+from rich.progress import Progress as RichProgress, ProgressColumn as RichProgressColumn
+from rich.theme import Theme as RichTheme
+
+from nnlogging.typings import FormatTimeCallable, Sink
+
+
+def get_rich_console(
+    sink: Sink | None = None,
+    /,
+    *,
+    width: int | None = None,
+    height: int | None = None,
+    markup: bool = True,
+    emoji: bool = True,
+    color_system: Literal["auto", "standard", "truecolor"] | None = "auto",
+    theme: RichTheme | None = None,
+    highlighter: RichHighlighter | None = None,
+    soft_wrap: bool = True,
+    force_terminal: bool | None = None,
+    force_jupyter: bool | None = None,
+    force_interactive: bool | None = None,
+):
+    console = RichConsole(
+        file=sink or stderr,  # pyright: ignore[reportArgumentType]
+        width=width,
+        height=height,
+        markup=markup,
+        emoji=emoji,
+        color_system=color_system,
+        theme=theme,
+        highlight=highlighter is not None
+        and not isinstance(highlighter, RichNullHighlighter),
+        highlighter=highlighter or RichNullHighlighter(),
+        soft_wrap=soft_wrap,
+        force_terminal=force_terminal,
+        force_jupyter=force_jupyter,
+        force_interactive=force_interactive,
+    )
+    return console
+
+
+def get_rich_handler(
+    console: RichConsole | None = None,
+    /,
+    *,
+    level: str | int = logging.NOTSET,
+    show_level: bool = True,
+    show_time: bool = True,
+    show_path: bool = True,
+    log_time_format: str | FormatTimeCallable = "[%x %X]",
+    omit_repeated_times: bool = True,
+    markup: bool = True,
+    highlighter: RichHighlighter | None = None,
+    rich_tracebacks: bool = True,
+    tracebacks_show_locals: bool = False,
+    log_message_format: str | LoggingFormatter = "%(message)s",
+):
+    handler = RichHandler(
+        console=console or get_rich_console(),
+        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,
+        markup=markup,
+        highlighter=highlighter or RichNullHighlighter(),
+        rich_tracebacks=rich_tracebacks,
+        tracebacks_show_locals=tracebacks_show_locals,
+    )
+    match log_message_format:
+        case str():
+            handler.setFormatter(LoggingFormatter(log_message_format))
+        case LoggingFormatter():
+            handler.setFormatter(log_message_format)
+    return handler
+
+
+def get_rich_progress_default_columns(
+    *,
+    markup: bool = True,
+):
+    from rich.progress import (
+        BarColumn,
+        SpinnerColumn,
+        TaskProgressColumn,
+        TextColumn,
+        TimeRemainingColumn,
+    )
+
+    spinner_column = SpinnerColumn(
+        spinner_name="dots",
+        style="progress.spinner",
+        finished_text=" ",
+    )
+    text_column = TextColumn(
+        text_format="{task.description}",
+        style="progress.description",
+        justify="left",
+        markup=markup,
+    )
+    bar_column = BarColumn(bar_width=40)
+    task_progress_column = TaskProgressColumn(
+        text_format="{task.percentage:>3.0f}%",
+        text_format_no_percentage="",
+        style="progress.percentage",
+        justify="right",
+        markup=markup,
+        show_speed=True,
+    )
+    time_remaining_column = TimeRemainingColumn(
+        compact=False,
+        elapsed_when_finished=True,
+    )
+
+    return (
+        spinner_column,
+        text_column,
+        bar_column,
+        task_progress_column,
+        time_remaining_column,
+    )
+
+
+def get_rich_progress(
+    console: RichConsole | None = None,
+    /,
+    *,
+    columns: Collection[str | RichProgressColumn] | None = None,
+    transient: bool = False,
+    refresh_per_second: float = 10,
+    speed_estimate_period: float = 3600,
+    default_column_markup: bool = True,
+):
+    progress = RichProgress(
+        *(columns or get_rich_progress_default_columns(markup=default_column_markup)),
+        console=console,
+        transient=transient,
+        refresh_per_second=refresh_per_second,
+        speed_estimate_period=speed_estimate_period,
+    )
+    return progress

nnlogging/utils/factory_funcs/shell_.py

@@ -0,0 +1,192 @@
+import logging
+from collections.abc import Collection
+from dataclasses import asdict, dataclass, field
+from logging import Formatter as LoggingFormatter
+from typing import Literal
+
+from aim import Repo as AimRepo, Run as AimRun
+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, FormatTimeCallable, Omitable, Sink
+from nnlogging.utils.factory_funcs.rich_ import (
+    get_rich_console,
+    get_rich_handler,
+    get_rich_progress_default_columns,
+)
+from nnlogging.utils.helpers import evolve_, or_
+
+
+@dataclass(slots=True, kw_only=True)
+class LoggerConfig:
+    name: str = "nnlogging"
+    level: int | str = logging.DEBUG
+    propagate: bool = False
+
+
+def get_logging_logger(
+    config: LoggerConfig | None = None,
+    /,
+    *,
+    name: Omitable[str] = ...,
+    level: Omitable[int | str] = ...,
+    propagate: Omitable[bool] = ...,
+):
+    config_base = config or LoggerConfig()
+    config_evolved = evolve_(
+        config_base,
+        name=name,
+        level=level,
+        propagate=propagate,
+    )
+    logger = logging.getLogger(config_evolved.name)
+    logger.setLevel(config_evolved.level)
+    logger.propagate = config_evolved.propagate
+    return logger
+
+
+@dataclass(slots=True, kw_only=True)
+class RunConfig:
+    experiment: str | None = None
+    repo: str | AimRepo | None = None
+    system_tracking_interval: float | None = 10
+    capture_terminal_logs: bool = False
+    log_system_params: bool = False
+    run_hash: str | None = None
+    read_only: bool = False
+    force_resume: bool = False
+
+
+def get_aim_run(
+    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] = ...,
+):
+    config_base = config or RunConfig()
+    config_evolved = evolve_(
+        config_base,
+        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,
+    )
+    run = AimRun(**asdict(config_evolved))  # pyright: ignore[reportAny]
+    return run
+
+
+@dataclass(slots=True, kw_only=True)
+class BranchConfig:
+    # shared
+    markup: bool = True
+    highlighter: RichHighlighter | None = None
+
+    # console
+    width: int | None = None
+    height: int | None = None
+    emoji: bool = True
+    color_system: Literal["auto", "standard", "truecolor"] | None = "auto"
+    theme: RichTheme | None = None
+    soft_wrap: bool = True
+    force_terminal: bool | None = None
+    force_jupyter: bool | None = None
+    force_interactive: bool | None = None
+
+    # handler
+    level: str | int = logging.NOTSET
+    show_level: bool = True
+    show_time: bool = True
+    show_path: bool = True
+    log_time_format: str | FormatTimeCallable = "[%x %X]"
+    omit_repeated_times: bool = True
+    rich_tracebacks: bool = True
+    tracebacks_show_locals: bool = False
+    log_message_format: str | LoggingFormatter = "%(message)s"
+
+    # progress
+    columns: Collection[str | RichProgressColumn] = field(
+        default_factory=get_rich_progress_default_columns,
+        compare=False,
+    )
+    transient: bool = False
+    refresh_per_second: float = 10
+    speed_estimate_period: float = 3600
+    default_column_markup: bool = True
+
+
+def get_branch(
+    config: BranchConfig | None = None,
+    /,
+    sink: Sink | None = None,
+    *,
+    markup: Omitable[bool] = ...,
+    highlighter: Omitable[RichHighlighter | None] = ...,
+    width: Omitable[int | None] = ...,
+    height: Omitable[int | None] = ...,
+    emoji: Omitable[bool] = ...,
+    color_system: Omitable[Literal["auto", "standard", "truecolor"] | None] = ...,
+    theme: Omitable[RichTheme | None] = ...,
+    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] = ...,
+):
+    if config is None:
+        config = BranchConfig()
+    console = get_rich_console(
+        sink,
+        width=or_(width, config.width),
+        height=or_(height, config.height),
+        markup=or_(markup, config.markup),
+        emoji=or_(emoji, config.emoji),
+        color_system=or_(color_system, config.color_system),
+        theme=or_(theme, config.theme),
+        highlighter=or_(highlighter, config.highlighter),
+        soft_wrap=or_(soft_wrap, config.soft_wrap),
+        force_terminal=or_(force_terminal, config.force_terminal),
+        force_jupyter=or_(force_jupyter, config.force_jupyter),
+        force_interactive=or_(force_interactive, config.force_interactive),
+    )
+    handler = get_rich_handler(
+        console,
+        level=or_(level, config.level),
+        show_level=or_(show_level, config.show_level),
+        show_time=or_(show_time, config.show_time),
+        show_path=or_(show_path, config.show_path),
+        log_time_format=or_(log_time_format, config.log_time_format),
+        omit_repeated_times=or_(omit_repeated_times, config.omit_repeated_times),
+        markup=or_(markup, config.markup),
+        highlighter=or_(highlighter, config.highlighter),
+        rich_tracebacks=or_(rich_tracebacks, config.rich_tracebacks),
+        tracebacks_show_locals=or_(
+            tracebacks_show_locals, config.tracebacks_show_locals
+        ),
+        log_message_format=or_(log_message_format, config.log_message_format),
+    )
+    return Branch(
+        console=console,
+        handler=handler,
+        tasks=dict(),
+        progress=None,
+    )

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