arin-log

A lightweight, cross-platform logging package for long-running pipelines. A virtual assistant for the user. A clean archive for the developer.

What is arin_log?

arin_log combines two roles in one package:

1. A virtual assistant (Arin) who talks to the user on the console and keeps them informed about what the script is doing.
2. A clean, technical log file that contains only the beacons: start, exception, exit. Meant for the developer who has to reconstruct later what happened.

The user sees a story. The developer sees a trail. That is the core.

Arin is not an AI. She is a voice — a smart logger with a character. This is a deliberate choice not to abuse the AI hype.

Installation

pip install arin-log

On first import, a folder dialog appears asking where you want to store your log files. The choice, together with the default colors, is saved in:

• Windows: %APPDATA%\arin_log\config_log.json
• Linux/macOS: ~/.arin_log/config_log.json

The dialog appears only once. On every next run, arin_log reads this file and skips the dialog.

If you want to change the log folder later:

from arin_log import change_folder
change_folder()

Quick example

from arin_log import log_start, log_notes, log_except, log_exit
from sys import _getframe

log_start("my_pipeline", logloc="pipeline")

try:
    log_notes("startup ; loading data", logloc="pipeline")
    # ... your work ...
    log_notes("success ; data loaded", logloc="pipeline")
except Exception:
    log_except(_getframe(), "data ; loading ; fail", logloc="pipeline")
    log_exit("my_pipeline", imp=False, logloc="pipeline")

log_exit("my_pipeline", imp=True, logloc="pipeline")

What the user sees on the console:

Arin : startup ; loading data
Arin : success ; data loaded
Arin my_pipeline ; 14:32:11 ; completed

What ends up in the log file:

26-10-04.pipeline.log

my_pipeline ; 14:32:11 ; running

startup ; loading data
success ; data loaded

my_pipeline ; 14:32:11 ; completed
------------------------------------------------------------

JSON helpers

arin_log ships with two JSON helpers, available directly from the package:

from arin_log import load_json, save_json

data = load_json("myfile.json")
save_json("myfile.json", data, indent=4)

load_json returns {} if the file is missing or corrupt. save_json returns True on success, False on failure.

These helpers come with arin_log because most modules already import the package — so they are available wherever you need them, without an extra dependency.

What makes arin_log different?

Core USP: logloc + daily grouping per main module + separation of console and archive + Arin.

How it works

The package consists of four modules, each with a clear task:

• logger.py — the heart: log_start, log_notes, log_except, log_exit, and the helpers.
• folder.py — manages the config folder and the log folder.
• console.py — console interaction: clear screen, menus.
• utils.py — JSON helpers (load_json, save_json).

Configuration

• log_cnfg.json ships with the package as a template: the default color words and color codes for the console.
• config_log.json lives in %APPDATA%\arin_log\ (Windows) or ~/.arin_log/ (Linux/macOS). On first run it is created by copying the colors from log_cnfg.json and adding your chosen log folder.

To customize colors, edit config_log.json in the config folder above. Your changes survive pip install --upgrade arin-log, because the file is never touched by pip.

The log folder

arin_log stores its files in a folder of your choice. On first use, a folder dialog appears. The choice is saved in config_log.json (see Configuration), so it survives across sessions and is never overwritten by a pip install --upgrade.

If config_log.json is missing or corrupt, the dialog appears again — the package has no fallback folder. The user is expected to choose.

Requirements

• Python 3.9 or higher

No external dependencies.

License

MIT — see LICENSE.

Status

Alpha (0.2.1). The core works. Tests are still in development.