Metadata-Version: 2.4
Name: nnlogging2
Version: 0.1.0
Summary: `nnlogging2` is a non-invasive extension of the standard Python logging library. `nnlogging2` is designed to track numerical metrics by time and execution context.
Keywords: experiment,logging,machine learning
Author: amas127
Author-email: amas127 <amadeusxu127@gmail.com>
License-Expression: MIT
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: Implementation :: CPython
Requires-Dist: numpy>=2
Requires-Dist: line-profiler>=5.0.2 ; extra == 'dev'
Requires-Dist: py-spy>=0.4.1 ; extra == 'dev'
Requires-Dist: pytest>=9.0.2 ; extra == 'dev'
Requires-Dist: pytest-cov>=7.0.0 ; extra == 'dev'
Requires-Python: >=3.12, <3.15
Project-URL: Issues, https://codeberg.org/amas127/nnlogging2/issues
Project-URL: Repository, https://codeberg.org/amas127/nnlogging2.git
Provides-Extra: dev
Description-Content-Type: text/markdown

# nnlogging2

[![status-badge](https://ci.codeberg.org/api/badges/16633/status.svg)](https://ci.codeberg.org/repos/16633)
[![PyPI - Version](https://img.shields.io/pypi/v/nnlogging2)](https://pypi.org/project/nnlogging2/)
![PyPI - Downloads](https://img.shields.io/pypi/dm/nnlogging2)
![PyPI - Python Version](https://img.shields.io/pypi/pyversions/nnlogging2)

`nnlogging2` is a non-invasive extension of the standard Python logging library.
`nnlogging2` is designed to track numerical metrics by time and execution context.

- **Metric Tracking:** Fast automatic metric statistics tracking.
- **Extensibility:** Fork metric, logger, handler or formatter at any time.
- **Compatibility:** Compatible with standard python logging library and
  third-party modules.

---

## Preview

![assets/preview.png](assets/preview.png)

---

## Installation

```shell
pip install nnlogging2
```

---

## Preview Script

```python
from nnlogging2 import (
    get_metric_logger,
    ContextedMetricFormatter,
    AttyStreamHandler,
    level_to_int,
    modify_logger_fallback_attrs_recorded,
)

# 1. Initialize the promoted logger

modify_logger_fallback_attrs_recorded(("lastval", "mean", "median"))
logger = get_metric_logger("train")
logger.setLevel(level_to_int("INFO"))

# 2. Setup formatting for context and metrics
# Inject "%(context_ext)s" and "%(metrics_ext)s" to formatter
# (8 showing characters, 9 ANSI escaped codes)
formatter = ContextedMetricFormatter(
    fmt="%(levelname)-17s %(context_ext)s %(message)s%(metrics_ext)s"
)
handler = AttyStreamHandler()
handler.setFormatter(formatter)
logger.addHandler(handler)

# 3. Attach context to logger (optional)
ctx_logger = logger.contexted({"epoch": "E1/1"})

# 4. Standard logging
ctx_logger.debug("debug ...")
ctx_logger.info("info ...")
ctx_logger.warning("warning ...")
ctx_logger.error("error ...")
ctx_logger.critical("critical ...")

# 5. Update & Logging
for i in range(3):
    # Update numerical values (automatically tracked in a moving window)
    ctx_logger.update(loss=0.5 / (i + 1), accuracy=0.8 + (i * 0.05))
    ctx_logger.log_metric(
        level_to_int("INFO"),
        metrics=[
            ("loss", "[%(metricname)s: %(lastval).2f (%(mean).2f)]"),
            ("accuracy", "[%(metricname)s: %(median).2f]"),
        ],
    )
```

## License

This project is licensed under the MIT License [LICENSE](LICENSE).
