nm-tool-forge 0.2.3

Analyze MigMan log files and generate aggregated CSV, Markdown, HTML, and optional PDF reports.

nm-tool-forge

nm-tool-forge analyzes MigMan text log files with severity tokens such as INFO, ERROR, and WARNING and generates aggregated CSV, Markdown, HTML, and optional PDF reports.

The project uses a package-ready src layout. The legacy log_analysis.py file remains available as a thin compatibility entry point for older local setups.

Features

• Parse logical log entries from multi-line text logs
• Normalize recurring error patterns for better aggregation
• Generate aggregated CSV reports
• Generate Markdown summary reports
• Optionally convert reports to HTML and PDF
• Keep a backup copy of analyzed log files
• Run built-in self-tests from the CLI

Installation

Basic installation from a local checkout:

python -m pip install .

Installation with optional PDF support and developer tools:

python -m pip install .[pdf,dev]

Command-line usage

After installation, both entry points are available:

python -m loganalysis --help
loganalysis --help
nm-tool-forge --help

Typical analysis run:

nm-tool-forge --logs-dir logs --out-dir log_analyse_out

Analysis with HTML/PDF conversion:

nm-tool-forge --logs-dir logs --out-dir log_analyse_out --convert

Self-test mode:

python -m loganalysis --self-test

Legacy compatibility call:

Release process

To publish a new release, always test on TestPyPI first, then upload to PyPI only after successful Conda/Smoke-Tests:

export TWINE_USERNAME="__token__"
export TWINE_PASSWORD="pypi-..."

bash scripts/release_testpypi.sh --bump patch
bash scripts/release_pypi.sh --yes

Hinweise:

• Erst TestPyPI ausführen und testen, dann final nach PyPI hochladen.
• Versionen auf PyPI können nicht überschrieben oder erneut verwendet werden.

python .\log_analysis.py --convert

Supported CLI options

• --logs-dir
• --out-dir
• --backup-dir
• --top-examples
• --convert
• --self-test

Library usage

from pathlib import Path

from loganalysis import (
    analyze_file,
    convert_report_md_to_html_pdf,
    iter_logical_entries,
    normalize_message,
)

result = analyze_file(Path("logs/app.txt"))
print(result["norm_counts"])

print(normalize_message(
    'Conversion: X =3100110. 138 The record was not found in table "Teile".'
))

for entry in iter_logical_entries(Path("logs/app.txt")):
    print(entry)

convert_report_md_to_html_pdf(
    Path("log_analyse_out/report.md"),
    Path("log_analyse_out/report.html"),
    Path("log_analyse_out/report.pdf"),
)

Project structure

.
├─ pyproject.toml
├─ src/loganalysis/
├─ tests/
├─ docs/
└─ log_analysis.py

Important modules:

• analysis.py - file-level and overall aggregation
• parsing.py - logical entry detection and parsing
• normalization.py - message normalization
• report_markdown.py - Markdown report model and rendering
• report_html.py - HTML/CSS rendering
• report_pdf.py - PDF engine selection and fallback handling
• converters.py - Markdown-to-HTML/PDF conversion
• cli.py - command-line entry point

HTML/PDF conversion

Report conversion is intentionally optional:

• report.md remains the primary human-readable output
• report.html is generated from the internal report model
• report.pdf is created when supported PDF tooling is available

PDF engine preference order:

1. weasyprint
2. wkhtmltopdf
3. pandoc + xelatex or pdflatex

If no supported PDF engine is available, the analysis still succeeds and generates Markdown and HTML output.

Windows-specific setup notes:

• docs/install_gtk_weasyprint_windows.md
• docs/install_xelatex_windows.md

Tests

pytest

Local build

python -m build

Expected artifacts:

• dist/*.tar.gz
• dist/*.whl

Notes

The package name on PyPI/TestPyPI is nm-tool-forge, while the current Python import package remains loganalysis.

This keeps the first public release small and low-risk. A later follow-up release can still rename the import package if desired.