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

nnlogging/typings/protocols.py

@@ -1,4 +1,16 @@
-from typing import Protocol, runtime_checkable
+from logging import Logger as LoggingLogger
+from typing import Protocol, TypeAlias, runtime_checkable
+
+from aim import Run as AimRun
+
+from nnlogging.options import (
+    BranchConfigOption,
+    LoggerConfigOption,
+    LogOptionDict,
+    RunConfigOption,
+)
+from nnlogging.typings.aliases import Branch
+from nnlogging.typings.exts import Unpack
 
 
 @runtime_checkable
@@ -12,3 +24,33 @@ class TerminalWritable(Protocol):
     def write(self, text: str, /) -> int: ...
     def flush(self) -> None: ...
     def isatty(self) -> bool: ...
+
+
+Sink: TypeAlias = Writable | TerminalWritable
+
+
+class ExceptionProtocol(Protocol):
+    branches: dict[str, Branch]
+
+    def exception(
+        self, msg: str, /, *args: object, **kwargs: Unpack[LogOptionDict]
+    ): ...
+
+
+class ShellProtocol(ExceptionProtocol, Protocol):
+    name: str
+    logger: LoggingLogger | None
+    run: AimRun | None
+    branches: dict[str, Branch]
+    logger_config: LoggerConfigOption
+    run_config: RunConfigOption
+    branch_config: BranchConfigOption
+    strict: bool
+
+    def log(
+        self,
+        level: int,
+        msg: object,
+        *args: object,
+        **kwargs: Unpack[LogOptionDict],
+    ): ...

nnlogging/utils/factories.py

@@ -0,0 +1,112 @@
+import logging
+from collections.abc import Collection
+from dataclasses import asdict
+from logging import Formatter as LoggingFormatter
+from sys import stderr
+from typing import cast
+
+from aim import Run as AimRun
+from rich.console import Console as RichConsole
+from rich.logging import RichHandler
+from rich.progress import Progress as RichProgress, ProgressColumn as RichProgressColumn
+
+from nnlogging.options import (
+    BranchConfigOptionDict,
+    LoggerConfigOption,
+    LoggerConfigOptionDict,
+    RichConsoleOption,
+    RichConsoleOptionDict,
+    RichHandlerOption,
+    RichHandlerOptionDict,
+    RichProgressOption,
+    RichProgressOptionDict,
+    RunConfigOption,
+    RunConfigOptionDict,
+)
+from nnlogging.typings.aliases import Branch
+from nnlogging.typings.exts import Unpack
+from nnlogging.typings.protocols import Sink
+from nnlogging.utils.helpers import filter_by_typeddict
+
+
+def get_rich_console(
+    sink: Sink = stderr,
+    /,
+    **kwargs: Unpack[RichConsoleOptionDict],
+):
+    options = asdict(RichConsoleOption(**kwargs))
+    console = RichConsole(
+        file=sink,  # pyright: ignore[reportArgumentType],
+        **options,
+    )
+    return console
+
+
+def get_rich_handler(
+    console: RichConsole | None = None,
+    /,
+    **kwargs: Unpack[RichHandlerOptionDict],
+):
+    options = asdict(RichHandlerOption(**kwargs))
+    log_message_format = cast(LoggingFormatter, options.pop("log_message_format"))
+    handler = RichHandler(
+        console=console or get_rich_console(),
+        **options,
+    )
+    handler.setFormatter(log_message_format)
+    return handler
+
+
+def get_rich_progress(
+    console: RichConsole | None = None,
+    /,
+    **kwargs: Unpack[RichProgressOptionDict],
+):
+    options = asdict(RichProgressOption(**kwargs))
+    columns = cast(Collection[str | RichProgressColumn], options.pop("columns"))
+    progress = RichProgress(
+        *columns,
+        console=console,
+        **options,
+    )
+    return progress
+
+
+def get_logging_logger(
+    **kwargs: Unpack[LoggerConfigOptionDict],
+):
+    options = asdict(LoggerConfigOption(**kwargs))
+    logger = logging.getLogger(options["name"])
+    logger.setLevel(options["level"])
+    logger.propagate = options["propagate"]
+    return logger
+
+
+def get_aim_run(
+    **kwargs: Unpack[RunConfigOptionDict],
+):
+    options = asdict(RunConfigOption(**kwargs))
+    run = AimRun(**options)
+    return run
+
+
+def get_branch(
+    sink: Sink = stderr,
+    /,
+    **kwargs: Unpack[BranchConfigOptionDict],
+):
+    console = get_rich_console(
+        sink,
+        **filter_by_typeddict(kwargs, RichConsoleOptionDict),
+    )
+    handler = get_rich_handler(
+        console,
+        **filter_by_typeddict(kwargs, RichHandlerOptionDict),
+    )
+    branch = Branch(
+        console=console,
+        handler=handler,
+        progress=None,
+        tasks=dict(),
+    )
+    return branch

nnlogging/utils/helpers.py

@@ -1,39 +1,74 @@
-from dataclasses import replace
-from types import EllipsisType
+import threading
+from collections.abc import Mapping
+from typing import Any, TypeVar, cast
 
-from nnlogging.typings import DataclassT, Omitable, T
+from nnlogging.options import (
+    LoggingLogOptionDict,
+    LogOptionDict,
+    RichConsoleOptionDict,
+    RichHandlerOptionDict,
+    RichPrintOptionDict,
+    RichProgressOptionDict,
+)
 
 
-def or_(
-    value: Omitable[T],
-    default: T,
+def get_name(
+    inst: object,
     /,
-) -> T:
-    return default if isinstance(value, EllipsisType) else value
+) -> object:
+    return getattr(inst, "name", inst)
+
+
+LogOptionT = TypeVar(
+    "LogOptionT",
+    bound=LogOptionDict | LoggingLogOptionDict | dict[str, Any],
+)
 
 
-def evolve_(
-    inst: DataclassT,
+def inc_stacklevel(
+    dct: LogOptionT,
     /,
-    **kwargs: object,
-) -> DataclassT:
-    evolutions = {k: v for k, v in kwargs.items() if not isinstance(v, EllipsisType)}
-    return replace(inst, **evolutions)
+) -> LogOptionT:
+    if "stacklevel" in dct:
+        dct["stacklevel"] = dct["stacklevel"] + 1
+    return dct
 
 
-def get_name(
-    inst: object,
+def inject_excinfo(
+    dct: LogOptionT,
+    e: BaseException | bool = True,
     /,
-):
-    inst_name = getattr(inst, "name", str(inst))
-    assert isinstance(inst_name, str)
-    return inst_name
+) -> LogOptionT:
+    if "exc_info" not in dct:
+        dct["exc_info"] = e
+    return dct
 
 
-def get__debugging(
-    inst: object,
+TypedDictT = TypeVar(
+    "TypedDictT",
+    bound=RichConsoleOptionDict
+    | RichHandlerOptionDict
+    | RichProgressOptionDict
+    | LoggingLogOptionDict
+    | RichPrintOptionDict,
+)
+
+
+def filter_by_typeddict(
+    dct: Mapping[str, object],
     /,
-):
-    inst_debugging = getattr(inst, "_debugging", False)
-    assert isinstance(inst_debugging, bool)
-    return inst_debugging
+    typpeddict: type[TypedDictT],
+) -> TypedDictT:
+    keys = typpeddict.__annotations__.keys()
+    return cast(TypedDictT, {k: v for k, v in dct.items() if k in keys})  # pyright: ignore[reportInvalidCast]
+
+
+def with_lock(lock: threading.Lock):
+    def decorator(f):
+        def wrapper(*args, **kwargs):
+            with lock:
+                return f(*args, **kwargs)
+
+        return wrapper
+
+    return decorator

{nnlogging-0.1.2.dist-info → nnlogging-0.1.4.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nnlogging
-Version: 0.1.2
+Version: 0.1.4
 Summary: A powerful and elegant logging library designed specifically for neural network and machine learning experiments. nnlogging seamlessly integrates [Rich](https://github.com/Textualize/rich) for beautiful terminal output and [Aim](https://github.com/aimhubio/aim) for comprehensive experiment tracking.
 Requires-Python: <3.13,>=3.10
 Requires-Dist: aim>=3.29.0
@@ -29,8 +29,8 @@ library for neural network and machine learning experiments, combining
   integrated progress bars.
 - 📊 **Effortless Experiment Tracking** - Seamless Aim integration for metrics,
   parameters, and system monitoring.
-- 🔧 **Simplified API** - Get started in two lines of code with the global
-  shell.
+- 🔧 **Simplified API** - Get started in one line of code with the global
+  functions.
 - 📈 **Advanced Progress Tracking** - Manage multiple progress bars for
   training, validation, and other tasks.
 - 🎯 **ML-Focused Design** - Purpose-built for the machine learning workflow.
@@ -55,16 +55,13 @@ Get the global shell or customize your shell from scratch to use logging methods
 and trackings.
 
 ```python
-from nnlogging import get_global_shell
+import nnlogging
 
-# 1. Get the global shell logger
-shell = get_global_shell()
-
-# 2. Log messages!
-shell.info("Starting training...")
-shell.warn("Learning rate seems high.")
-shell.debug("This is a detailed debug message.")
-shell.error("CUDA out of memory.", extra={"show_locals": True})
+# Log messages!
+nnlogging.info("Starting training...")
+nnlogging.warn("Learning rate seems high.")
+nnlogging.debug("This is a detailed debug message.")
+nnlogging.error("CUDA out of memory.", extra={"show_locals": True})
 ```
 
 ### Experiment Tracking with Aim
@@ -73,12 +70,10 @@ Configure the Aim run to track metrics, hyperparameters, and more.
 
 ```python
 import random
-from nnlogging import get_global_shell
-
-shell = get_global_shell()
+import nnlogging
 
 # 1. Configure the experiment tracker
-shell.run_configure(
+nnlogging.run_configure(
     experiment="resnet_training",
     log_system_params=True,      # Track CPU/GPU usage
     capture_terminal_logs=True   # Save console output in Aim
@@ -86,16 +81,16 @@ shell.run_configure(
 
 # 2. Log hyperparameters
 config = {"lr": 0.001, "batch_size": 32, "model": "ResNet50"}
-shell.update_metadata("hparams", config)
-shell.info(f"Using config: {config}")
+nnlogging.update_metadata("hparams", config)
+nnlogging.info(f"Using config: {config}")
 
 # 3. Track metrics in your training loop
 for epoch in range(10):
     train_loss = 1.0 / (epoch + 1) + random.random() * 0.1
-    shell.track(train_loss, name="train_loss", epoch=epoch)
-    shell.info(f"Epoch {epoch}: Loss={train_loss:.4f}")
+    nnlogging.track(train_loss, name="train_loss", epoch=epoch)
+    nnlogging.info(f"Epoch {epoch}: Loss={train_loss:.4f}")
 
-shell.info("Experiment finished!")
+nnlogging.info("Experiment finished!")
 ```
 
 To view the results, run `aim up` in your terminal.
@@ -106,34 +101,32 @@ Add tasks to the logger to display and update rich progress bars.
 
 ```python
 import time
-from nnlogging import get_global_shell
-
-shell = get_global_shell()
+import nnlogging
 
 # 1. Add a task to the progress display
-shell.task_add("training", desc="Training", total=500)
+nnlogging.task_add("training", desc="Training", total=500)
 
 # 2. Update the task during your training loop
 for step in range(500):
     # training_step()
     time.sleep(0.01)
-    shell.advance("training", 1)
+    nnlogging.advance("training", 1)
 
     if step % 100 == 0:
-        shell.info(f"Completed step {step}")
+        nnlogging.info(f"Completed step {step}")
 
 # 3. Remove the task when finished
-shell.task_remove("training")
-shell.info("Training complete!")
+nnlogging.task_remove("training")
+nnlogging.info("Training complete!")
 ```
 
 ## 🔄 Workflow
 
-1. **`get_global_shell()`** - Get the logger instance at the start of your
+1. **Import `nnlogging`** - Import the `nnlogging` library at the start of your
    script.
 2. **`run_configure()`** - (Optional) Configure Aim for experiment tracking.
-3. **Log & Track** - Use `shell.info()`, `shell.track()`, and `shell.advance()`
-   throughout your code.
+3. **Log & Track** - Use `nnlogging.info()`, `nnlogging.track()`, and
+   `nnlogging.advance()` throughout your code.
 4. **Visualize** - Run `aim up` to launch the Aim UI and analyze your results.
 
 ## 🤝 Contributing

nnlogging-0.1.4.dist-info/RECORD

@@ -0,0 +1,31 @@
+nnlogging/__init__.py,sha256=LxZc3hpo_z0rH7yWRU3GAVMhVUc_-EQKeFG-msPzJxY,69
+nnlogging/global_.py,sha256=L6tOsKIWxglceEyYf9b0yTWWaaVgwbrdvxUK_ZZkraw,5704
+nnlogging/shell.py,sha256=RIbHbm28_f_3mqtUO4AU-901eeMeEKkxUqDFqvuD_Ms,5481
+nnlogging/exceptions/__init__.py,sha256=Wz5SOYX7zZObWV3KRvFA2JsxixIjgO8eW-zfwlMnt0o,533
+nnlogging/exceptions/branch_exists.py,sha256=NnwHDBMBG2b8BtQvda-cSGwXFffnnEolCYmFbd90sl8,709
+nnlogging/exceptions/branch_not_found.py,sha256=ragJ0Z8m4_HUvCz-092-owNFK9aYXOwixhLPFAHHxGM,706
+nnlogging/exceptions/task_exists.py,sha256=VBmBFJtFVnzQStZDP1ApISM6YUa1RTeYYPSaVZJdb24,781
+nnlogging/exceptions/task_not_found.py,sha256=GJKC9fOnulVV1SghMnI68n2dlgBp5ypjLuQunrxUulE,696
+nnlogging/options/__init__.py,sha256=ItPUHN7dJvVEfaTbRTIafPYyvWpK5nE6VfcZWei78H4,1092
+nnlogging/options/branch_config.py,sha256=KnvtUuGda1qoAtgntS1JCdRu8sske5wLx-jZZXFSmkE,592
+nnlogging/options/log_option.py,sha256=gvmOhIXgic_DRwdnNz10YzfGF3HLZNhBX_OsUOvk-t8,814
+nnlogging/options/logger_config.py,sha256=5y2WxYnNt1jxWnkKOVaUHl8a4z9lEzG-p9vw3D15F8c,386
+nnlogging/options/rich_console.py,sha256=HbgbZgoQIL15sKunQCPc012MS_QC2EOwu5gQotL3LiE,1420
+nnlogging/options/rich_handler.py,sha256=JR65KUtRJa02FpESraIHysX30GG89GLD6vIs_nnp7xk,1643
+nnlogging/options/rich_progress.py,sha256=ztM7zNY6y6tPmFz6BVWqympk6lQ5sQmnMJvWFWeZUqs,1675
+nnlogging/options/run_config.py,sha256=YEtGS5oQP5wDcYKv6egL1dKfpVjlV0d3H4qAYVlbhPY,842
+nnlogging/options/task_option.py,sha256=pPppAfbdz3OjsHGywKLIgTWHP9vzfvE6vCxh_J7oWeI,412
+nnlogging/options/track_option.py,sha256=TNsno3dX5fyW4S-CkgtS5UXKwIgm4mCMSlKCUTZqtxE,454
+nnlogging/shell_funcs/__init__.py,sha256=dtahWAUZLdGnFr2XmWGJ9kAr6XYVaOo7b_ckktvN1Fg,87
+nnlogging/shell_funcs/branch_.py,sha256=XV66VbAeEOisX2JbyiT0wbK7oQ-binLetDhgxVNB7zo,1978
+nnlogging/shell_funcs/logger_.py,sha256=t3WGU7Lcrg9dZM4MOH6K0h5PiwIcZhCEtiP3RIUPm8k,4064
+nnlogging/shell_funcs/run_.py,sha256=SN52ub-TXwJFg4CUPcwjD0PhITDXxVQHsUCF58NYxSo,1556
+nnlogging/shell_funcs/task_.py,sha256=IpcuWVWArq2ZnygbIOatNOFjkTyUapz4q_QSQsMhhpc,3209
+nnlogging/typings/aliases.py,sha256=hnT-Zd9JBDR3-RbqI0RmH8ZtoIqhPsp_k_0qYscMhDM,563
+nnlogging/typings/exts.py,sha256=lcLkliPdtkaFl0NrzacDkpaeXV4b99lKWAZvZzpuSxw,271
+nnlogging/typings/protocols.py,sha256=fzgZoBa2uvEPZvJjP0t4hkSLCST69KczbOqFVTf4M1c,1282
+nnlogging/utils/factories.py,sha256=PLtNL_RRiW4TiYTtyuWYXQe4rOXleyfiabUc63wNc8Q,2857
+nnlogging/utils/helpers.py,sha256=ct40BUt0jb7pgMQxzw_cFuE0BFs5LIbNZjG25G_k8yY,1485
+nnlogging-0.1.4.dist-info/METADATA,sha256=wj6NSy9OAxiN5rMRRhzBZpmWmifwl7pDCmqnQfL7L0c,4427
+nnlogging-0.1.4.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+nnlogging-0.1.4.dist-info/RECORD,,

nnlogging/shell_protocol.py

@@ -1,86 +0,0 @@
-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

@@ -1,41 +0,0 @@
-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/exceptions.py

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

nnlogging/typings/generics.py

@@ -1,23 +0,0 @@
-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/utils/__init__.py

@@ -1,83 +0,0 @@
-"""
-``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

@@ -1,11 +0,0 @@
-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",
-]