nnlogging 0.1.2__py3-none-any.whl

nnlogging/utils/shell_funcs/branch_.py

@@ -0,0 +1,164 @@
+from collections.abc import Collection
+from logging import Formatter as LoggingFormatter
+from typing import Literal
+
+from rich.highlighter import Highlighter as RichHighlighter
+from rich.progress import ProgressColumn as RichProgressColumn
+from rich.theme import Theme as RichTheme
+
+from nnlogging.shell_protocol import ShellProtocol
+from nnlogging.typings import FormatTimeCallable, Omitable, Sink
+from nnlogging.utils.exception import (
+    raise_branch_exists_error,
+    raise_branch_not_found_error,
+)
+from nnlogging.utils.factory_funcs.shell_ import BranchConfig, get_branch
+from nnlogging.utils.helpers import evolve_
+
+
+def branch_configure(
+    inst: ShellProtocol,
+    /,
+    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] = ...,
+):
+    inst.branch_config = evolve_(
+        config or inst.branch_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(
+    inst: ShellProtocol,
+    /,
+    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] = ...,
+):
+    if name in inst.branches:
+        raise_branch_exists_error(
+            inst,
+            name,
+            stacklevel=6,
+        )
+    else:
+        branch = get_branch(
+            inst.branch_config,
+            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,
+        )
+        inst.branches[name] = branch
+        if inst.logger is not None:
+            # TODO: add branch-add-hint
+            inst.logger.addHandler(branch["handler"])
+
+
+def branch_remove(
+    inst: ShellProtocol,
+    /,
+    name: str,
+):
+    if name not in inst.branches:
+        raise_branch_not_found_error(
+            inst,
+            name,
+            stacklevel=6,
+        )
+    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:
+            # TODO: add branch-remove-hint
+            inst.logger.removeHandler(branch["handler"])
+        del inst.branches[name]

nnlogging/utils/shell_funcs/logger_.py

@@ -0,0 +1,199 @@
+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.factory_funcs.shell_ import LoggerConfig, get_logging_logger
+from nnlogging.utils.helpers import evolve_
+
+
+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/utils/shell_funcs/run_.py

@@ -0,0 +1,97 @@
+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.factory_funcs.shell_ import RunConfig, get_aim_run
+from nnlogging.utils.helpers import evolve_
+
+
+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/utils/shell_funcs/task_.py

@@ -0,0 +1,111 @@
+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
+
+
+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-0.1.2.dist-info/METADATA

@@ -0,0 +1,146 @@
+Metadata-Version: 2.4
+Name: nnlogging
+Version: 0.1.2
+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
+Requires-Dist: rich>=14.0.0
+Provides-Extra: dev
+Requires-Dist: faker>=37.11.0; extra == 'dev'
+Requires-Dist: pytest-cov>=7.0.0; extra == 'dev'
+Requires-Dist: pytest-html>=4.1.1; extra == 'dev'
+Requires-Dist: pytest-repeat>=0.9.4; extra == 'dev'
+Requires-Dist: pytest-sugar>=1.1.1; extra == 'dev'
+Requires-Dist: pytest-xdist>=3.8.0; extra == 'dev'
+Requires-Dist: pytest>=8.4.2; extra == 'dev'
+Requires-Dist: twine>=6.2.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# nnlogging
+
+[nnlogging](https://codeberg.org/nnaf/nnlogging) is a powerful, modern logging
+library for neural network and machine learning experiments, combining
+[Rich](https://github.com/Textualize/rich) for beautiful terminal output with
+[Aim](https://github.com/aimhubio/aim) for comprehensive experiment tracking.
+
+## ✨ Features
+
+- 🎨 **Beautiful Console Output** - Rich-powered colorful logging with
+  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.
+- 📈 **Advanced Progress Tracking** - Manage multiple progress bars for
+  training, validation, and other tasks.
+- 🎯 **ML-Focused Design** - Purpose-built for the machine learning workflow.
+- 🐍 **Modern Python** - Fully typed, Python 3.10+ codebase.
+
+## 🚀 Installation
+
+```bash
+pip install nnlogging
+```
+
+**Requirements:** Python 3.10-3.12
+
+## ⚡ Quick Start
+
+The new `nnlogging` API is designed for simplicity. You can get a
+pre-configured, global logger instance and start logging right away.
+
+### Basic Logging
+
+Get the global shell or customize your shell from scratch to use logging methods
+and trackings.
+
+```python
+from nnlogging import get_global_shell
+
+# 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})
+```
+
+### Experiment Tracking with Aim
+
+Configure the Aim run to track metrics, hyperparameters, and more.
+
+```python
+import random
+from nnlogging import get_global_shell
+
+shell = get_global_shell()
+
+# 1. Configure the experiment tracker
+shell.run_configure(
+    experiment="resnet_training",
+    log_system_params=True,      # Track CPU/GPU usage
+    capture_terminal_logs=True   # Save console output in Aim
+)
+
+# 2. Log hyperparameters
+config = {"lr": 0.001, "batch_size": 32, "model": "ResNet50"}
+shell.update_metadata("hparams", config)
+shell.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}")
+
+shell.info("Experiment finished!")
+```
+
+To view the results, run `aim up` in your terminal.
+
+### Progress Tracking
+
+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()
+
+# 1. Add a task to the progress display
+shell.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)
+
+    if step % 100 == 0:
+        shell.info(f"Completed step {step}")
+
+# 3. Remove the task when finished
+shell.task_remove("training")
+shell.info("Training complete!")
+```
+
+## 🔄 Workflow
+
+1. **`get_global_shell()`** - Get the logger instance 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.
+4. **Visualize** - Run `aim up` to launch the Aim UI and analyze your results.
+
+## 🤝 Contributing
+
+Contributions are welcome! Please feel free to open an issue or submit a pull
+request.
+
+## 📄 License
+
+This project is licensed under the MIT License.