nnlogging 0.1.2__py3-none-any.whl → 0.1.4__py3-none-any.whl

nnlogging/shell_funcs/branch_.py

@@ -0,0 +1,79 @@
+import sys
+from dataclasses import asdict, replace
+from typing import Literal, cast
+
+from nnlogging.exceptions import (
+    call_branch_exists_error,
+    call_branch_not_found_error,
+)
+from nnlogging.options import BranchConfigOptionDict
+from nnlogging.typings.exts import Unpack
+from nnlogging.typings.protocols import ShellProtocol, Sink
+from nnlogging.utils.factories import get_branch
+
+__all__ = [
+    "branch_configure",
+    "branch_add",
+    "branch_remove",
+]
+
+
+def branch_configure(
+    inst: ShellProtocol,
+    **kwargs: Unpack[BranchConfigOptionDict],
+):
+    inst.branch_config = replace(
+        inst.branch_config,
+        **kwargs,
+    )
+
+
+def branch_add(
+    inst: ShellProtocol,
+    name: str,
+    sink: Sink | Literal["stderr", "stdout"] = "stderr",
+    **kwargs: Unpack[BranchConfigOptionDict],
+):
+    if name in inst.branches:
+        e = call_branch_exists_error(
+            inst,
+            name,
+            stacklevel=2,
+        )
+        if inst.strict:
+            raise e
+
+    else:
+        if isinstance(sink, str) and sink in ("stderr", "stdout"):
+            sink = cast(Sink, getattr(sys, sink))
+        branch = get_branch(
+            sink,
+            **(asdict(inst.branch_config) | kwargs),  # pyright: ignore[reportArgumentType]
+        )
+        inst.branches[name] = branch
+        if inst.logger is not None:
+            inst.logger.addHandler(branch["handler"])
+
+
+def branch_remove(
+    inst: ShellProtocol,
+    name: str,
+):
+    if name not in inst.branches:
+        e = call_branch_not_found_error(
+            inst,
+            name,
+            stacklevel=2,
+        )
+        if inst.strict:
+            raise e
+
+    else:
+        branch = inst.branches[name]
+        branch["handler"].close()
+        branch["tasks"].clear()
+        if branch["progress"] is not None:
+            branch["progress"].stop()
+        if inst.logger is not None:
+            inst.logger.removeHandler(branch["handler"])
+        del inst.branches[name]

nnlogging/{utils/shell_funcs → shell_funcs}/logger_.py

@@ -1,20 +1,41 @@
 import logging
+from dataclasses import asdict, replace
 
 from rich.console import ConsoleRenderable as RichConsoleRenderable
 
-from nnlogging.shell_protocol import ShellProtocol
-from nnlogging.typings import ConsolePrintOptions, LogOptions, Omitable
-from nnlogging.utils.factory_funcs.shell_ import LoggerConfig, get_logging_logger
-from nnlogging.utils.helpers import evolve_
+from nnlogging.options import (
+    LoggerConfigOptionDict,
+    LoggingLogOptionDict,
+    LogOptionDict,
+    RichPrintOptionDict,
+)
+from nnlogging.typings.exts import Unpack
+from nnlogging.typings.protocols import ShellProtocol
+from nnlogging.utils.factories import get_logging_logger
+from nnlogging.utils.helpers import (
+    filter_by_typeddict,
+    inc_stacklevel,
+    inject_excinfo,
+)
+
+__all__ = [
+    "logger_configure",
+    "log",
+    "debug",
+    "info",
+    "warn",
+    "error",
+    "critical",
+    "exception",
+]
 
 
 def _logger_open(
     inst: ShellProtocol,
-    /,
 ):
     if inst.logger is None:
         logging.captureWarnings(True)
-        inst.logger = get_logging_logger(inst.logger_config)
+        inst.logger = get_logging_logger(**asdict(inst.logger_config))
         for name in inst.branches:
             branch = inst.branches[name]
             inst.logger.addHandler(branch["handler"])
@@ -23,55 +44,46 @@ def _logger_open(
 
 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.filters.clear()
         inst.logger.setLevel(logging.NOTSET)
-        inst.logger.propagate = False
+        inst.logger.propagate = True
         inst.logger = None
 
 
 def logger_configure(
     inst: ShellProtocol,
-    /,
-    config: LoggerConfig | None = None,
-    *,
-    name: Omitable[str] = ...,
-    level: Omitable[int | str] = ...,
-    propagate: Omitable[bool] = ...,
+    **kwargs: Unpack[LoggerConfigOptionDict],
 ):
     _logger_close(inst)
-    inst.logger_config = evolve_(
-        config or inst.logger_config,
-        name=name,
-        level=level,
-        propagate=propagate,
+    inst.logger_config = replace(
+        inst.logger_config,
+        **kwargs,
     )
 
 
 def log(
     inst: ShellProtocol,
-    /,
     level: int,
     msg: object,
     *args: object,
-    log_options: LogOptions | None = None,
-    console_options: ConsolePrintOptions | None = None,
+    **kwargs: Unpack[LogOptionDict],
 ):
     _logger_open(inst)
     assert inst.logger is not None
     match msg:
         case RichConsoleRenderable():
-            debug(
+            inst.logger.log(
+                level,
+                "Sending %s to %s branches ...",
+                msg,
                 inst,
-                f"Sending {repr(msg)} to branches ...",
-                log_options=log_options or LogOptions(),
+                **inc_stacklevel(filter_by_typeddict(kwargs, LoggingLogOptionDict)),
             )
             for name in inst.branches:
                 branch = inst.branches[name]
@@ -79,121 +91,102 @@ def log(
                     branch["console"].print(
                         msg,
                         *args,
-                        **(console_options or ConsolePrintOptions()),
+                        **filter_by_typeddict(kwargs, RichPrintOptionDict),
                     )
         case _:
             inst.logger.log(
                 level,
                 msg,
                 *args,
-                **(log_options or LogOptions()),
+                **inc_stacklevel(filter_by_typeddict(kwargs, LoggingLogOptionDict)),
             )
 
 
 def debug(
     inst: ShellProtocol,
-    /,
     msg: object,
     *args: object,
-    log_options: LogOptions | None = None,
-    console_options: ConsolePrintOptions | None = None,
+    **kwargs: Unpack[LogOptionDict],
 ):
     log(
         inst,
         logging.DEBUG,
         msg,
         *args,
-        log_options=log_options,
-        console_options=console_options,
+        **inc_stacklevel(kwargs),
     )
 
 
 def info(
     inst: ShellProtocol,
-    /,
     msg: object,
     *args: object,
-    log_options: LogOptions | None = None,
-    console_options: ConsolePrintOptions | None = None,
+    **kwargs: Unpack[LogOptionDict],
 ):
     log(
         inst,
         logging.INFO,
         msg,
         *args,
-        log_options=log_options,
-        console_options=console_options,
+        **inc_stacklevel(kwargs),
     )
 
 
 def warn(
     inst: ShellProtocol,
-    /,
     msg: object,
     *args: object,
-    log_options: LogOptions | None = None,
-    console_options: ConsolePrintOptions | None = None,
+    **kwargs: Unpack[LogOptionDict],
 ):
     log(
         inst,
-        logging.WARNING,
+        logging.WARN,
         msg,
         *args,
-        log_options=log_options,
-        console_options=console_options,
+        **inc_stacklevel(kwargs),
     )
 
 
 def error(
     inst: ShellProtocol,
-    /,
     msg: object,
     *args: object,
-    log_options: LogOptions | None = None,
-    console_options: ConsolePrintOptions | None = None,
+    **kwargs: Unpack[LogOptionDict],
 ):
     log(
         inst,
         logging.ERROR,
         msg,
         *args,
-        log_options=log_options,
-        console_options=console_options,
+        **inc_stacklevel(kwargs),
     )
 
 
 def critical(
     inst: ShellProtocol,
-    /,
     msg: object,
     *args: object,
-    log_options: LogOptions | None = None,
-    console_options: ConsolePrintOptions | None = None,
+    **kwargs: Unpack[LogOptionDict],
 ):
     log(
         inst,
         logging.CRITICAL,
         msg,
         *args,
-        log_options=log_options,
-        console_options=console_options,
+        **inc_stacklevel(kwargs),
     )
 
 
 def exception(
     inst: ShellProtocol,
-    /,
     msg: object,
     *args: object,
-    log_options: LogOptions | None = None,
-    console_options: ConsolePrintOptions | None = None,
+    **kwargs: Unpack[LogOptionDict],
 ):
-    default_log_options = LogOptions(exc_info=True)
     log(
         inst,
-        logging.CRITICAL,
+        logging.ERROR,
         msg,
         *args,
-        log_options=default_log_options | (log_options or LogOptions()),
-        console_options=console_options,
+        **inc_stacklevel(inject_excinfo(kwargs)),
     )

nnlogging/shell_funcs/run_.py

@@ -0,0 +1,84 @@
+from dataclasses import asdict, replace
+
+from aim.storage.types import AimObject
+
+from nnlogging.options import RunConfigOptionDict, TrackOptionDict
+from nnlogging.typings.exts import Unpack
+from nnlogging.typings.protocols import ShellProtocol
+from nnlogging.utils.factories import get_aim_run
+
+__all__ = [
+    "run_configure",
+    "track",
+    "add_tag",
+    "remove_tag",
+    "update_metadata",
+]
+
+
+def _run_open(
+    inst: ShellProtocol,
+):
+    if inst.run is None:
+        inst.run = get_aim_run(**asdict(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,
+    **kwargs: Unpack[RunConfigOptionDict],
+):
+    _run_close(inst)
+    inst.run_config = replace(
+        inst.run_config,
+        **kwargs,
+    )
+
+
+def track(
+    inst: ShellProtocol,
+    value: object,
+    **kwargs: Unpack[TrackOptionDict],
+):
+    _run_open(inst)
+    assert inst.run is not None
+    inst.run.track(
+        value,
+        **kwargs,  # pyright: ignore[reportArgumentType]
+    )
+
+
+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 update_metadata(
+    inst: ShellProtocol,
+    key: str,
+    value: AimObject,
+):
+    _run_open(inst)
+    assert inst.run is not None
+    inst.run[key] = value

nnlogging/{utils/shell_funcs → shell_funcs}/task_.py

@@ -1,48 +1,57 @@
-from nnlogging.shell_protocol import ShellProtocol
-from nnlogging.utils.exception import (
-    raise_task_exists_error,
-    raise_task_not_found_error,
-)
-from nnlogging.utils.factory_funcs.rich_ import get_rich_progress
+from dataclasses import asdict
+
+from nnlogging.exceptions import call_task_exists_error, call_task_not_found_error
+from nnlogging.options import RichProgressOptionDict, TaskOptionDict
+from nnlogging.typings.exts import Unpack
+from nnlogging.typings.protocols import ShellProtocol
+from nnlogging.utils.factories import get_rich_progress
+from nnlogging.utils.helpers import filter_by_typeddict
+
+__all__ = [
+    "task_add",
+    "task_remove",
+    "advance",
+]
 
 
 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(
+            e = call_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
+            if inst.strict:
+                raise e
+
+        else:
+            if branch["progress"] is None:
+                progress = get_rich_progress(
+                    branch["console"],
+                    **filter_by_typeddict(
+                        asdict(inst.branch_config),
+                        RichProgressOptionDict,
+                    ),
+                )
+                progress.start()
+                branch["progress"] = progress
 
 
 def _task_close(
     inst: ShellProtocol,
-    /,
     name: str,
 ):
-    task_found = False
+    _task_found = False
     for branch_name in inst.branches:
         branch = inst.branches[branch_name]
         if name in branch["tasks"]:
-            task_found = True
+            _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]
@@ -50,44 +59,37 @@ def _task_close(
             if branch["progress"].finished:
                 branch["progress"].stop()
                 branch["progress"] = None
-    if not task_found:
-        raise_task_not_found_error(
+    if not _task_found:
+        e = call_task_not_found_error(
             inst,
             name,
             stacklevel=2,
         )
+        if inst.strict:
+            raise e
 
 
 def task_add(
     inst: ShellProtocol,
-    /,
     name: str,
-    *,
-    desc: str,
-    total: float | None,
-    done: float = 0,
+    **kwargs: Unpack[TaskOptionDict],
 ):
     _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]
-        )
+        assert branch["progress"] is not None
+        task_id = branch["progress"].add_task(**kwargs)  # 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
+            assert branch["progress"] is not None
             task_id = branch["tasks"][name]
             branch["progress"]._tasks[task_id].finished_time = 0  # pyright: ignore[reportPrivateUsage]
     _task_close(inst, name)
@@ -95,17 +97,15 @@ def task_remove(
 
 def advance(
     inst: ShellProtocol,
-    /,
     name: str,
-    *,
-    advance: float,
+    value: float,
 ):
     for branch_name in inst.branches:
         branch = inst.branches[branch_name]
-        assert branch["progress"] is not None  # definitely
+        assert branch["progress"] is not None
         task_id = branch["tasks"][name]
         branch["progress"].advance(
             task_id=task_id,
-            advance=advance,
+            advance=value,
         )
     _task_close(inst, name)

nnlogging/typings/aliases.py

@@ -1,66 +1,18 @@
-import sys
-from collections.abc import Mapping
 from datetime import datetime
-from types import TracebackType
-from typing import Callable, Literal, TypeAlias, TypedDict
+from os import PathLike
+from typing import Callable, 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]
+StrPath: TypeAlias = str | PathLike[str]
 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]
+class Branch(TypedDict, total=True):
+    console: RichConsole
+    handler: RichHandler
+    tasks: dict[str, RichTaskID]
+    progress: RichProgress | None

nnlogging/typings/exts.py

@@ -0,0 +1,15 @@
+import sys
+
+if sys.version_info >= (3, 11):
+    from typing import Never, NotRequired, Required, Unpack
+else:
+    from typing_extensions import Never, NotRequired, Required, Unpack
+
+
+__all__ = [
+    # py311
+    "NotRequired",
+    "Required",
+    "Unpack",
+    "Never",
+]