nnlogging 0.1.0__py3-none-any.whl → 0.1.1__py3-none-any.whl

nnlogging/utils/rich_factories.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/shell_factories.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.helpers import evolve_, or_
+from nnlogging.utils.rich_factories import (
+    get_rich_console,
+    get_rich_handler,
+    get_rich_progress_default_columns,
+)
+
+
+@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-0.1.1.dist-info/METADATA

@@ -0,0 +1,181 @@
+Metadata-Version: 2.4
+Name: nnlogging
+Version: 0.1.1
+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
+
+A powerful logging library for neural network and machine learning experiments
+that combines [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 progress
+  bars
+- 📊 **Experiment Tracking** - Built-in Aim integration for metrics and
+  hyperparameters
+- 🔧 **Flexible Logging** - Multiple console handlers with customizable
+  formatting
+- 📈 **Progress Tracking** - Advanced progress bars for long-running training
+  loops
+- 🎯 **ML-Focused Design** - Purpose-built for machine learning workflows
+- 🐍 **Modern Python** - Python 3.10+ with full type hints
+
+## 🚀 Installation
+
+```bash
+pip install nnlogging
+```
+
+**Requirements:** Python 3.10-3.12
+
+## ⚡ Quick Start
+
+### Basic Logging
+
+```python
+from nnlogging import Shell
+from nnlogging.utils import get_rich_console
+import sys
+
+# Initialize logger
+shell = Shell(name="my_experiment")
+shell.add_console({"main": get_rich_console(sys.stderr)})
+shell.build_handler_from_console()
+
+# Log messages
+shell.info("Starting training...")
+shell.warn("Learning rate is high")
+shell.error("CUDA out of memory")
+```
+
+### Experiment Tracking
+
+```python
+# Initialize Aim tracking
+shell.add_aimrun(experiment="resnet_training")
+
+# Track metrics during training
+for epoch in range(100):
+    train_loss, train_acc = train_epoch()
+    shell.track(train_loss, name="train_loss", epoch=epoch)
+    shell.track(train_acc, name="train_accuracy", epoch=epoch)
+
+    shell.info(f"Epoch {epoch}: Loss={train_loss:.4f}, Acc={train_acc:.3f}")
+
+# Track hyperparameters
+shell.update_aimrun_metadata("config", {
+    "learning_rate": 0.001,
+    "batch_size": 32,
+    "model": "ResNet50"
+})
+```
+
+### Progress Tracking
+
+```python
+# Setup progress bars
+shell.build_progress_from_console("main")
+shell.add_task("training", description="Training", total=1000)
+shell.start_progress()
+
+# Update during training loop
+for step in range(1000):
+    loss = train_step()
+    shell.update_task("training", advance=1)
+
+    if step % 100 == 0:
+        shell.info(f"Step {step}: Loss={loss:.4f}")
+
+shell.stop_progress()
+```
+
+### Complete Training Example
+
+```python
+from nnlogging import Shell
+from nnlogging.utils import get_rich_console
+import sys
+
+# Setup logging with both console and experiment tracking
+shell = Shell(name="training")
+shell.add_console({"console": get_rich_console(sys.stdout)})
+shell.build_handler_from_console()
+shell.build_progress_from_console()
+
+# Initialize experiment tracking
+shell.add_aimrun(
+    experiment="mnist_cnn",
+    log_system_params=True,
+    capture_terminal_logs=True
+)
+
+# Log hyperparameters
+config = {"lr": 0.001, "batch_size": 64, "epochs": 10}
+shell.update_aimrun_metadata("hparams", config)
+shell.info(f"Starting training with config: {config}")
+
+# Training loop with progress tracking
+shell.add_task("epochs", description="Epochs", total=config["epochs"])
+shell.start_progress()
+
+for epoch in range(config["epochs"]):
+    # Training phase
+    train_loss, train_acc = train_model()
+    shell.track(train_loss, name="train_loss", epoch=epoch)
+    shell.track(train_acc, name="train_acc", epoch=epoch)
+
+    # Validation phase
+    val_loss, val_acc = validate_model()
+    shell.track(val_loss, name="val_loss", epoch=epoch)
+    shell.track(val_acc, name="val_acc", epoch=epoch)
+
+    shell.update_task("epochs", advance=1)
+    shell.info(f"Epoch {epoch}: Train Loss={train_loss:.3f}, Val Acc={val_acc:.3f}")
+
+shell.stop_progress()
+shell.info("Training completed! 🎉")
+```
+
+## 🔄 Workflow
+
+![Workflow Overview](assets/workflow-overview.png)
+
+1. **Initialize** - Create Shell instance for your experiment
+2. **Configure** - Add consoles and progress tracking
+3. **Track** - Connect to Aim for experiment tracking
+4. **Train & Log** - Use throughout your ML pipeline
+5. **Visualize** - View results in Aim's web interface with `aim up`
+
+## 🌍 Environments
+
+nnlogging works seamlessly across different environments:
+
+- **Local Development** - Full Rich terminal output with colors and formatting
+- **Jupyter Notebooks** - Integrated display with notebook-friendly rendering
+- **Remote Servers** - Automatic fallback for limited terminal capabilities
+- **CI/CD Pipelines** - Clean text output when Rich features aren't supported
+- **Docker Containers** - Optimized for containerized ML workloads
+
+## 🤝 Contributing
+
+Contributions welcome! Please open an issue for major changes.
+
+## 📄 License
+
+MIT License

nnlogging-0.1.1.dist-info/RECORD

@@ -0,0 +1,26 @@
+nnlogging/__init__.py,sha256=sVUcI-0A0ID9W-l0FS9vNzoCngPnxQsDdMkXsFTsPOE,235
+nnlogging/shell/__init__.py,sha256=tdcZDJuqlihYreih_jvgub0la_X8c3JWxnaNLR77u5c,128
+nnlogging/shell/protocol.py,sha256=wVbdqBycfZqbj066HugmaCtQc9OdVxy47rvdLu5o5bc,1663
+nnlogging/shell/shell.py,sha256=lN2aSzySnORGVI5DaljilfzDh7h-s9i4KqZs1mcH2rQ,11592
+nnlogging/shell/exception/__init__.py,sha256=aFAbufsmio0Yndq6H7zEEoWGNA2kfO7F3ZL1p6iGYzQ,365
+nnlogging/shell/exception/branch_exists.py,sha256=OpsZduL-vlOHn8RKmktw9J1Y-dlQI064zqJOb32wm_Y,1114
+nnlogging/shell/exception/branch_not_found.py,sha256=r5RHg7DnP9VnraOJtioGi8BK7alhFLo7yKfaF13CD0g,1126
+nnlogging/shell/exception/task_exists.py,sha256=m1ezYtxzdSR0MqFT2Qb1DkQUTIVMqt-AHN91punsP4g,1232
+nnlogging/shell/exception/task_not_found.py,sha256=cydrhiRbnqP_ZvVMziF_iW7nY8lXUb7MnQgcIKfpxzo,1106
+nnlogging/shell/utils/__init__.py,sha256=z70fg9IUfJOjXhJj3gi7U3RIJQGLWBfIV8vm5MkV_3w,675
+nnlogging/shell/utils/branch_funcs.py,sha256=5UbPFDaHkfq9YRdMaGXW0bwwiufVQAUlkk-DnGe9abM,5559
+nnlogging/shell/utils/logger_funcs.py,sha256=VdP7VpFQM_lwlFgdrkCJ9_tM90W9kX385LFNe-YCTGA,4611
+nnlogging/shell/utils/run_funcs.py,sha256=9Q4SjftQIE4BCI_VzR2B1o5az27E37ey5yI0vBtVOpQ,2281
+nnlogging/shell/utils/task_funcs.py,sha256=p76NvB-M5cNyTIqACDk7i_2qKNF1YOC6L_WDkt0qSeI,3222
+nnlogging/typings/__init__.py,sha256=7ar5136odVB9vOj5MTQ6_AYuodoWOGduMSveEpVtF1Y,774
+nnlogging/typings/aliases.py,sha256=EpLqeOss5u5-zpu-tbv6g-LZ21mFyKO0PpyXmDLrCUs,2080
+nnlogging/typings/exceptions.py,sha256=rCmrwA599Uy7iOVnX12_Q8B0FMydyJX7zgOLBWxWDUM,174
+nnlogging/typings/generics.py,sha256=olwknb77voWiIydEM62aMuU5kQPyS74zoyX7Ncr9cig,680
+nnlogging/typings/protocols.py,sha256=osKmzyQ9Qzz_woxbd2eM9wDvPZ6hJZvupQ2cdkOM0H8,341
+nnlogging/utils/__init__.py,sha256=cVr1eB99PAw_nSDlpMAopMGeQVI6Pouge5Bgkawo6fU,733
+nnlogging/utils/helpers.py,sha256=8KTHeyQJR36Wnm8CRG7fZsx-IX6kXU4CsSkrTEgyZ0E,785
+nnlogging/utils/rich_factories.py,sha256=RVI46Ncxk5aoMTbbQmf_mIB664IkYACXOiVOqwHLLt0,4473
+nnlogging/utils/shell_factories.py,sha256=nGkQxhGZT19K4V_E94yqNTPlvnTGS245SrNYyc72B9o,6367
+nnlogging-0.1.1.dist-info/METADATA,sha256=zUI3SPhYM9Q6pkEqx5vns07QuUmGrPBh_ryT6sA5k6w,5475
+nnlogging-0.1.1.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+nnlogging-0.1.1.dist-info/RECORD,,