arin-log 0.2.0__py3-none-any.whl

arin_log/__init__.py

@@ -0,0 +1,68 @@
+"""
+arin_log
+--------
+Een lichtgewicht, platformonafhankelijke logging-package voor
+langlopende pipelines.
+
+Twee rollen in één package:
+
+1. Een virtuele assistent (Arin) die op de console tegen de gebruiker
+   praat en hem op de hoogte houdt van wat het script doet.
+2. Een schoon, technisch logbestand dat alleen de bakens bevat:
+   start, exception, exit. Bedoeld voor de ontwikkelaar die later
+   moet reconstrueren wat er is gebeurd.
+
+De gebruiker ziet een verhaal. De ontwikkelaar ziet een spoor.
+
+Publieke API
+------------
+Vanuit de logger:
+    log_start, log_notes, log_except, log_exit,
+    config_logs, file_exist, tijd
+
+Vanuit de folder:
+    change_folder, get_folder
+
+Vanuit de console:
+    cons_menu
+
+Interne functies blijven bereikbaar via hun eigen module, bijvoorbeeld:
+    from arin_log.logger import not_set
+    from arin_log.folder import get_config
+    from arin_log.utils import load_json, save_json
+    from arin_log.console import cls, menu_dict
+"""
+
+__version__ = "0.2.0"
+
+from arin_log.logger import (
+    log_start,
+    log_notes,
+    log_except,
+    log_exit,
+    config_logs,
+    file_exist,
+    tijd,
+)
+
+from arin_log.folder import (
+    change_folder,
+    get_folder,
+)
+
+from arin_log.console import (
+    cons_menu,
+)
+
+__all__ = [
+    "log_start",
+    "log_notes",
+    "log_except",
+    "log_exit",
+    "config_logs",
+    "file_exist",
+    "tijd",
+    "change_folder",
+    "get_folder",
+    "cons_menu",
+]

arin_log/console.py

@@ -0,0 +1,91 @@
+"""
+console.py
+----------
+Console-interactie voor arin_log.
+
+Bevat:
+    cls()                    - wist het scherm (Windows: cls, anders clear)
+    menu_dict(optlst)        - bouwt een dict van genummerde menu-opties
+    cons_menu(optlst, ...)   - toont een console-menu en retourneert
+                               de gekozen functie als commando-string.
+
+Dit is een aparte module omdat console-interactie (menu, scherm wissen)
+niets met loggen te maken heeft. De logger logt; de console toont.
+"""
+
+from os import system, name, path
+from arin_log.logger import log_notes
+
+br = chr(10)
+prgnm = path.basename(__file__).split('.')[0]
+
+
+def cls():
+    """Wist het scherm. Op Windows met 'cls', anders met 'clear'."""
+    system('cls' if name == 'nt' else 'clear')
+    return
+
+
+def menu_dict(optlst):
+    """Bouwt een dict van genummerde menu-opties.
+
+    De opties krijgen de sleutels '1', '2', '3', ... in volgorde.
+    Daarnaast worden de aliassen 'e', 'exit', 'q' en 'quit' toegevoegd,
+    die allemaal naar 'exit' wijzen."""
+    opties = {}
+    idx = 1
+    for opt in optlst:
+        ids = str(idx)
+        opties[ids] = opt
+        idx += 1
+    opties['e'] = 'exit'
+    opties['exit'] = 'exit'
+    opties['q'] = 'exit'
+    opties['quit'] = 'exit'
+    return opties
+
+
+def cons_menu(optlst, logloc=None):
+    """Toont een console-menu en retourneert de gekozen functie
+    als een commando-string (bijvoorbeeld 'mijn_functie()').
+
+    optlst   - lijst met functienamen (strings, zonder haakjes).
+               'exit' wordt automatisch toegevoegd als het ontbreekt.
+    logloc   - context voor de logger; standaard None.
+
+    De functie blijft het menu tonen tot de gebruiker een geldige
+    keuze maakt. 'exit', 'e', 'q' en 'quit' geven 'exit(0)' terug."""
+
+    exts = ['e', 'exit', 'q', 'quit']
+    tlst = optlst
+    if 'exit' not in tlst:
+        tlst.append('exit')
+
+    opties = menu_dict(tlst)
+    keys = list(opties.keys())
+    lng = len(keys)
+    choice = '#'
+    com = ''
+    while choice not in keys:
+        cls()
+        log_notes([f'{logloc} ; console ; menu', br])
+        for key in keys:
+            tmp = opties[key].replace('_', ' ')
+            if key not in exts:
+                print(f'{key}. {tmp}')
+        print()
+        choice = input(f'Enter your choice ({keys[0]}-{keys[-5]}): ')
+        if choice.lower() in exts:
+            choice = choice.lower()
+        cls()
+        if choice in keys:
+            com = opties[choice]
+            tmp = opties[choice].replace('_', ' ')
+            x = keys.index(choice)
+            if x < lng - 5:
+                log_notes([br, f'Your ; choice ; {tmp}'], logloc=logloc)
+            if com.lower() == 'exit':
+                com = 'exit(0)'
+            else:
+                com = f'{com}()'
+    return com

arin_log/demo_log.py

@@ -0,0 +1,37 @@
+"""
+demo_log.py
+-----------
+Eerste kennismaking met arin_log.
+
+Laat zien:
+    - hoe je een hoofdmodule markeert met log_start / log_exit
+    - hoe je een exception logt met log_except
+    - hoe je console-output en logbestand-uitvoer combineert
+      via de logloc-parameter
+
+Draai met:
+    python -m arin_log.demo_log
+"""
+
+from arin_log.logger import log_start, log_notes, log_except, log_exit
+from sys import _getframe
+from os import path
+
+prgnm = path.basename(__file__).split('.')[0]
+
+def demo():
+    log_start(prgnm, logloc=prgnm)
+
+    log_notes("demo ; test ; logger")
+
+    try:
+        1 / 0
+    except Exception:
+        log_except(_getframe(), "zero ; division ; exception", logloc=prgnm)
+
+    log_notes("continuing ; logging ; success")
+    log_notes("demo ; test ; success", logloc=prgnm)
+    log_exit(prgnm, logloc=prgnm)
+
+if __name__ == "__main__":
+    demo()

arin_log/folder.py

@@ -0,0 +1,306 @@
+"""
+folder.py
+---------
+Beheert de config folder van arin_log.
+
+Alle user-specifieke configuratie staat in één bestand:
+
+    %APPDATA%\\arin_log\\config_log.json
+
+Dit bestand bevat:
+    - de kleuren (gekopieerd uit log_cnfg.json bij de eerste run)
+    - de gekozen log_folder
+
+Bij de eerste run wordt het bestand aangemaakt:
+    1. De gebruiker kiest een log folder via de dialoog.
+    2. De kleuren worden uit log_cnfg.json (package folder) gelezen.
+    3. Alles wordt opgeslagen in config_log.json.
+
+Bij volgende runs wordt alleen config_log.json gelezen.
+Als het bestand corrupt is, wordt het opnieuw aangemaakt.
+
+Publieke functies:
+    get_folder()               - geeft de huidige log_folder terug
+    change_folder(parent=None) - folder-dialoog, update config + log_folder
+    get_config()               - geeft de volledige config dict terug
+
+Interne functie:
+    _get_folder()              - resolver, eenmalig bij import
+"""
+
+from os import path, makedirs, environ
+from arin_log.utils import load_json, save_json
+br = chr(10)
+
+CNFG_FOLDER = "arin_log"
+CNFG_FILE = "config_log.json"
+TEMPLATE_FILE = "log_cnfg.json"
+
+
+# =====================================================================
+# 1. INTERNE HELPERS — paden
+# =====================================================================
+def _config_folder():
+    """Bepaalt de config folder.
+
+    Windows: %APPDATA%\\arin_log
+    Anders:  ~/.arin_log
+    Maakt de folder aan als die nog niet bestaat.
+    Retourneert het pad, of False bij falen."""
+    base = environ.get("APPDATA")
+    if base:
+        folder = path.join(base, CNFG_FOLDER)
+    else:
+        folder = path.join(path.expanduser("~"), ".arin_log")
+    try:
+        makedirs(folder, exist_ok=True)
+    except Exception:
+        return False
+    return folder
+
+
+def _config_file():
+    """Pad naar config_log.json, of False."""
+    folder = _config_folder()
+    if not folder:
+        return False
+    return path.join(folder, CNFG_FILE)
+
+
+def _template_file():
+    """Pad naar log_cnfg.json (in de package folder)."""
+    return path.join(path.dirname(__file__), TEMPLATE_FILE)
+
+
+# =====================================================================
+# 2. INTERNE HELPERS — config lezen en schrijven
+# =====================================================================
+def _read_config():
+    """Leest config_log.json en retourneert de dict.
+    Retourneert {} als het bestand ontbreekt."""
+    pf = _config_file()
+    if pf and path.isfile(pf):
+        d = load_json(pf)
+        if isinstance(d, dict):
+            return d
+    return {}
+
+
+def _write_config(data):
+    """Schrijft data naar config_log.json.
+    Retourneert True bij succes, anders False."""
+    pf = _config_file()
+    if not pf:
+        return False
+    return save_json(pf, data, indent=4)
+
+
+def _read_template():
+    """Leest log_cnfg.json uit de package folder.
+    Retourneert de dict, of {} als het bestand ontbreekt."""
+    pf = _template_file()
+    if path.isfile(pf):
+        d = load_json(pf)
+        if isinstance(d, dict):
+            return d
+    return {}
+
+
+def _create_config(log_folder):
+    """Maakt config_log.json aan.
+
+    Kopieert alle sleutels uit log_cnfg.json (de template) en
+    voegt 'log_folder' toe. Retourneert True bij succes."""
+    d = _read_template()
+    d["log_folder"] = log_folder
+    return _write_config(d)
+
+
+def _save_folder(folder):
+    """Update alleen de 'log_folder'-key in config_log.json.
+    Andere keys blijven staan. Retourneert True bij succes."""
+    d = _read_config()
+    if not d:
+        return _create_config(folder)
+    d["log_folder"] = folder
+    return _write_config(d)
+
+
+def _save_failed():
+    """Meldt dat het opslaan is mislukt en stopt met exitcode 1."""
+    from sys import stderr, exit
+    stderr.write(f"folder ; selection ; not saved{br}administrator ; adjustments ; required")
+    exit(1)
+
+
+# =====================================================================
+# 3. INTERNE HELPERS — folder keuze
+# =====================================================================
+def _norm(p):
+    """Normaliseert een pad naar forward slashes.
+    Retourneert het pad als string, of de oorspronkelijke waarde
+    als die leeg is."""
+    return str(p).replace("\\", "/") if p else p
+
+
+def manual_input():
+    """Vraagt de gebruiker om een folder via de console.
+
+    Blijft vragen tot de gebruiker een niet-lege invoer geeft en
+    de folder bestaat (of aangemaakt kan worden). Normaliseert het
+    pad naar forward slashes.
+
+    De hele lus zit in een buitenste try/except. Als er iets
+    onverwachts misgaat, geeft de functie False terug in plaats
+    van te crashen."""
+    try:
+        while True:
+            gekozen = input("Enter a folder path for your log files: ")
+            if not gekozen:
+                continue
+
+            gekozen = _norm(gekozen)
+
+            if not path.isdir(gekozen):
+                try:
+                    makedirs(gekozen, exist_ok=True)
+                except Exception:
+                    print(f"Could not create folder: {gekozen}")
+                    continue
+
+            return gekozen
+    except Exception:
+        return False
+
+
+def _folder_dialog(parent=None):
+    """Opent een folder-dialoog. tkinter wordt lokaal geïmporteerd.
+
+    parent=None -> tijdelijke verborgen root (batch-context).
+    parent=<Tk> -> gebruikt de bestaande root (GUI-context).
+    Retourneert het gekozen pad, of '' bij annuleren.
+
+    Als tkinter of de GUI niet beschikbaar is, valt de functie
+    terug op manual_input() (console-invoer). Als dat ook faalt,
+    stopt het programma met de melding 'platform ; graphic GUI ;
+    inexistent' en exitcode 1."""
+
+    try:
+        from tkinter import Tk, filedialog
+
+        root = None
+        folder = ""
+        eigen_root = False
+        if parent is None:
+            root = Tk()
+            root.withdraw()
+            eigen_root = True
+            parent = root
+        try:
+            folder = filedialog.askdirectory(
+                parent=parent,
+                title="Choose a folder for your log files"
+            )
+        finally:
+            if eigen_root:
+                try:
+                    root.destroy()
+                except Exception:
+                    pass
+
+        return folder if folder else ""
+
+    except Exception:
+        gekozen = manual_input()
+        if gekozen:
+            return gekozen
+        from sys import stderr, exit
+        stderr.write(f"platform ; graphic GUI ; inexistent{br}administrator ; adjustments ; required")
+        exit(1)
+
+
+# =====================================================================
+# 4. RESOLVER — eenmalig bij import
+# =====================================================================
+def _get_folder():
+    """Resolver: lees config_log.json, of maak het aan.
+
+    Retourneert altijd een geldig pad (string).
+    - Als config_log.json bestaat: log_folder daaruit.
+    - Anders: dialoog, dan config_log.json aanmaken.
+    - Bij corruptie: opnieuw aanmaken.
+
+    Wordt eenmalig aangeroepen bij het laden van de module.
+    Daarna is log_folder gezet en gebruikt de rest van de code
+    die waarde via get_folder() of folder.log_folder."""
+    d = _read_config()
+    folder = d.get("log_folder", False)
+
+    if folder:
+        return _norm(folder)
+
+    while True:
+        gekozen = _folder_dialog()
+        if gekozen:
+            gekozen = _norm(gekozen)
+            if not _create_config(gekozen):
+                _save_failed()
+            return gekozen
+
+
+# =====================================================================
+# 5. PUBLIEKE FUNCTIES
+# =====================================================================
+def get_folder():
+    """Geeft de huidige log_folder terug.
+
+    Altijd de actuele waarde. Aanroepen na change_folder() geeft
+    de nieuwe folder, niet de oude. Dit is de enige juiste manier
+    om de log folder op te vragen vanuit een andere module."""
+    return log_folder
+
+
+def change_folder(parent=None):
+    """Opent de folder-dialoog, update config_log.json en de
+    globale log_folder en retourneert de nieuwe waarde.
+
+    parent=None -> tijdelijke verborgen root (batch-context).
+    parent=<Tk> -> gebruikt de bestaande root (GUI-context).
+
+    Bij annulering: retourneert False, log_folder blijft ongewijzigd.
+    Retourneert het nieuwe pad (string) bij succes.
+
+    Als de keuze niet opgeslagen kan worden, stopt het programma
+    met de melding 'folder ; selection ; not saved' en exitcode 1."""
+    global log_folder
+
+    gekozen = _folder_dialog(parent=parent)
+    if not gekozen:
+        return False
+
+    gekozen = _norm(gekozen)
+    if not _save_folder(gekozen):
+        _save_failed()
+    log_folder = gekozen
+    return log_folder
+
+
+def get_config():
+    """Geeft de volledige config dict terug uit config_log.json.
+
+    Wordt gebruikt door logger.config_logs() om de kleuren te laden."""
+    return _read_config()
+
+
+# =====================================================================
+# 6. TOP-LEVEL UITVOERING — log_folder is klaar na import
+# =====================================================================
+log_folder = _get_folder()
+
+# =====================================================================
+# 7. TESTBLOK
+# =====================================================================
+if __name__ == "__main__":
+    print(f"log_folder: {log_folder}")
+    print(f"config: {get_config()}")
+    exit(0)

arin_log/log_cnfg.json

@@ -0,0 +1,63 @@
+   {
+	   "color_codes": {
+		  "black": "30m",
+		  "blue": "34m",
+		  "cyan": "36m",
+		  "darkgrey": "90m",
+		  "green": "32m",
+		  "lightblue": "94m",
+		  "lightcyan": "96m",
+		  "lightgreen": "92m",
+		  "lightgrey": "37m",
+		  "lightred": "91m",
+		  "orange": "33m",
+		  "pink": "95m",
+		  "purple": "35m",
+		  "red": "31m",
+		  "yellow": "93m"
+	   },
+	   "color_words": {
+		  "Arin": "cyan",
+		  "completed": "cyan",
+		  "modification": "cyan",
+		  "pending": "cyan",
+		  "terminated": "cyan",
+		  "satisfied": "cyan",
+		  "shutdown": "cyan",
+		  "startup": "cyan",
+          "rebooted": "cyan",
+		  "recovery": "cyan",
+		  "running": "cyan",
+		  "updated": "cyan",
+		  "added": "green",
+		  "succes": "green",
+          "success": "green",
+		  "present": "green",
+		  "restored": "green",
+		  "saved": "green",
+		  "corrupt": "lightred",
+		  "error": "lightred",
+		  "empty": "lightred",
+		  "fail": "lightred",
+		  "false": "lightred",
+		  "inexistent": "lightred",
+		  "invalid": "lightred",
+		  "not exist": "lightred",
+		  "not valid": "lightred",
+		  "rude": "lightred",
+		  "broken": "lightred",
+		  "unrecoverable": "lightred",
+		  "exception": "pink",
+		  "changed": "orange",
+		  "deleted": "orange",
+		  "interrupted": "orange",
+		  "interruption": "orange",
+		  "fault": "orange",
+          "fault(s)": "orange",
+		  "none": "orange",
+          "removed": "orange",
+		  "timeout": "orange",
+		  "unaltered": "orange",
+		  "unfit": "orange"
+	   }
+   }

arin_log/logger.py

@@ -0,0 +1,265 @@
+"""
+logger.py
+---------
+Centrale logging-module van arin_log.
+
+Ondersteunende modules:
+    folder.py   - beheert de config en de log folder.
+    utils.py    - algemene helpers (load_json, save_json).
+    console.py  - console-interactie (menu, scherm wissen).
+
+Publieke functies:
+    log_start, log_notes, log_except, log_exit, config_logs,
+    file_exist, tijd, not_set, last_record.
+"""
+
+from os import path, makedirs
+from sys import _getframe, stderr, exit
+from gc import collect
+from re import sub
+import time
+
+from arin_log import folder
+
+color_words = {}
+color_codes = {}
+prgnm = ''
+tas = ''
+tas2 = ''
+br = chr(10)
+recs_dic = {}
+
+
+def not_set():
+    global prgnm
+    isns = True if prgnm == '' else False
+    return isns
+
+
+def tijd():
+    return time.strftime("%H:%M:%S")
+
+
+def last_record(logloc):
+    global recs_dic, br
+    result = recs_dic.get(logloc, br)
+    return result
+
+
+def to_cons(note):
+    """Print note naar de console, met kleuren volgens color_words
+    en color_codes. Woorden worden alleen gekleurd als ze exact
+    overeenkomen (inclusief spaties)."""
+    global color_words, color_codes
+    clrlst = list(color_words.keys())
+    if any([x in note for x in clrlst]):
+        for w in clrlst:
+            if w in note:
+                tmp = sub(r'[^\w\s]', '', note)
+                tmp = sub(' +', ' ', tmp)
+                nwlst = tmp.split(' ')
+                twl = w.split(' ')
+                if all([x in nwlst for x in twl]):
+                    clr = color_words.get(w, None)
+                    clrc = color_codes.get(clr, None)
+                    if clrc is not None:
+                        note = note.replace(w, f"\033[{clrc}{w}\033[00m")
+    print(note)
+    return
+
+
+def to_file(data, logloc=None):
+    global br, recs_dic
+    frm = _getframe()
+    logloc = 'error' if logloc is None else logloc
+    fnm = '.'.join([tas2, logloc, 'log'])
+    pf = path.join(folder.log_folder, fnm)
+    act = 'a' if path.isfile(pf) else 'w'
+    if isinstance(data, list):
+        records = data
+    else:
+        records = [str(data)]
+    ln = len(records)
+    if ln > 0:
+        try:
+            with open(pf, act, encoding="utf-8") as txtFile:
+                for rec in records:
+
+                    if (last_record(logloc) == br) and (rec == br):
+                        continue
+                    else:
+                        if rec == br:
+                            recs_dic[logloc] = br
+                            rec = ''
+                        else:
+                            recs_dic[logloc] = 'ne'
+                        rec = rec + br
+                        txtFile.write(rec)
+
+                        if any([x in rec for x in ['completed', 'terminated']]):
+                            lng = len(rec)
+                            if 'completed' in rec:
+                                lijn = '-' * (lng - 1) + br
+                            elif 'terminated' in rec:
+                                lijn = '_' * (lng - 1) + br
+                            txtFile.write(lijn)
+                            recs_dic[logloc] = 'ne'
+                txtFile.close()
+        except Exception:
+            st = ' ; '.join(['logging', fnm, 'fail'])
+            log_except(frm, st, mod=prgnm, logloc=logloc)
+    else:
+        st = ' ; '.join(['log', fnm, 'empty'])
+        log_except(frm, st, mod=prgnm, logloc=logloc)
+    return
+
+
+def log_notes(notes, cons=None, logloc=None, end=False, ar_on=True):
+    """Schrijft notes naar de console (indien cons=True) en naar het
+    logbestand (indien logloc is meegegeven).
+
+    end=True  -> gebruik 'Arin' als prefix (voor afsluitende berichten).
+    end=False -> gebruik 'Arin :' als prefix (of geen prefix als ar_on=False).
+    """
+    global br, prgnm
+    cons = True if cons is None else cons
+    st = False if logloc is None else True
+    if isinstance(notes, str):
+        notes = [notes]
+    for el in notes:
+        if cons:
+            if end:
+                if el == br:
+                    print()
+                else:
+                    to_cons(' '.join(['Arin', el]))
+            else:
+                if el == br:
+                    print()
+                elif ar_on:
+                    to_cons(' '.join(['Arin :', el]))
+                else:
+                    to_cons(el)
+        if st:
+            to_file(el, logloc=logloc)
+    return
+
+
+def log_start(pnm, imp=None, cons=None, logloc=None):
+    """Markeert het begin van een module-run en ververst de datum
+    waarop het logbestand is gebaseerd (tas2). Zo komt een run die
+    na middernacht start in het logbestand van de nieuwe dag."""
+    global br, tas2
+    imp = False if imp is None else imp
+    typ = 'pending' if imp else 'running'
+    cons = True if cons is None else cons
+    tas2 = time.strftime('%y-%m-%d')
+    lijn = ' ; '.join([pnm, tijd(), typ])
+    if last_record(logloc) != br:
+        lijn = [br, lijn]
+    if not imp:
+        lijn = [lijn, br]
+    log_notes(lijn, cons=cons, logloc=logloc)
+    return
+
+
+def log_except(frm, note, mod=None, cons=None, logloc=None):
+    global br
+    logloc = 'error' if logloc is None else logloc
+    cons = True if cons is None else cons
+    if last_record(logloc) == br:
+        notes = []
+    else:
+        notes = [br]
+    flpf = frm.f_code.co_filename
+    mod = path.basename(flpf).split('.')[0] if mod is None else mod
+    fncpos = '.'.join([mod, frm.f_code.co_name, str(frm.f_lineno)])
+    lijn = ' ; '.join([fncpos, tijd(), 'exception'])
+    notes.append(lijn)
+    if isinstance(note, str):
+        notes.append(note)
+    elif isinstance(note, list):
+        notes = notes + note
+    log_notes(notes, logloc=logloc, cons=cons)
+    return
+
+
+def log_exit(prginf, imp=None, cons=None, logloc=None):
+    global br
+    imp = False if imp is None else imp
+    cons = True if cons is None else cons
+    notes = [prginf] if isinstance(prginf, str) else prginf
+    if imp:
+        notes[-1] = ' ; '.join([notes[-1], tijd(), 'completed'])
+    else:
+        if last_record(logloc) != br:
+            notes = [br] + notes
+        notes[-1] = ' ; '.join([notes[-1], tijd(), 'terminated'])
+    notes.append(br)
+    log_notes(notes, logloc=logloc, cons=cons)
+    collect()
+    if imp:
+        return
+    else:
+        import sys
+        sys.tracebacklimit = 0
+        sys.exit(0)
+
+
+def config_logs():
+    """Leest de kleuren uit config_log.json (via folder.get_config)
+    en zet ze als globals.
+
+    De sleutel 'log_folder' wordt overgeslagen; die hoort bij folder.py."""
+    jsnd = folder.get_config()
+    if len(jsnd) > 0:
+        for k in jsnd.keys():
+            if k == "log_folder":
+                continue
+            globals()[k] = jsnd.get(k, False)
+    return
+
+
+def file_exist(pf, timeout=None):
+    from time import sleep
+    timeout = 0.24 if timeout is None else timeout
+    if pf is None:
+        return False
+    else:
+        st = True
+        slt = 0.08
+        tt = 0
+        while not path.isfile(pf):
+            tt = tt + slt
+            if tt >= timeout:
+                st = False
+                break
+            sleep(slt)
+    return st
+
+
+def _ensure_log_folder():
+    """Controleert of folder.log_folder bestaat en maakt hem zo nodig
+    aan. Lukt dat niet, dan stopt het programma met een duidelijke
+    melding op stderr en exitcode 1."""
+    try:
+        makedirs(folder.log_folder, exist_ok=True)
+    except Exception:
+        stderr.write(f"log ; folder ; inexistent{br}administrator ; adjustments ; required")
+        exit(1)
+    return
+
+
+if not_set():
+    prgnm = path.basename(__file__).split('.')[0]
+    tas2 = time.strftime('%y-%m-%d')
+    tas = time.strftime('%Y-%m-%d')
+    _ensure_log_folder()
+    config_logs()
+
+
+if __name__ == "__main__":
+    from arin_log.demo_log import demo
+    demo()
+    exit(0)
+

arin_log/utils.py

@@ -0,0 +1,61 @@
+from os import path
+from json import dump, load
+
+# Vaste ANSI-kleuren voor _warn.
+# Los van de user-config (log_cnfg.json), omdat utils.py een blad is
+# en geen toegang heeft tot de logger.
+# Kleurcodes uit log_cnfg.json: cyan=36m, pink=95m, lightred=91m.
+_CYAN = "\033[36m"
+_RESET = "\033[00m"
+
+
+def _warn(note, word, color):
+    """Print een waarschuwing op de console.
+
+    'Arin' wordt altijd cyaan. Het opgegeven woord krijgt de
+    opgegeven kleurcode. Wordt alleen gebruikt bij interne fouten
+    in utils.py (corrupt of ontbrekend bestand).
+
+    Deze functie staat los van de logger: utils.py is een blad en
+    mag niet van logger afhangen (zou een circulaire import geven)."""
+    note = note.replace(word, f"\033[{color}{word}{_RESET}")
+    print(f"{_CYAN}Arin{_RESET} : {note}")
+    return
+
+
+def load_json(pf):
+    """Leest een JSON-bestand en retourneert de inhoud als dict.
+    Retourneert {} als het bestand ontbreekt of corrupt is.
+
+    Bij ontbreken of corruptie wordt een melding op de console
+    geprint, met Arin-prefix en vaste kleuren."""
+    jsnd = {}
+    fnm = path.basename(pf)
+    if path.isfile(pf):
+        try:
+            with open(pf, encoding='utf-8') as fil:
+                jsnd = load(fil)
+        except Exception:
+            _warn(f"data ; {fnm} ; corrupt", "corrupt", "95m")
+    else:
+        _warn(f"file ; {fnm} ; inexistent", "inexistent", "91m")
+    return jsnd
+
+
+def save_json(pf, data, indent=None):
+    """Schrijft data als JSON naar pf.
+
+    indent=None of een negatief getal -> geen indentering.
+    indent=<int> >= 0                 -> indentering met die breedte.
+
+    Retourneert True bij succes, anders False.
+    Bij een fout wordt een melding op de console geprint."""
+    indent = indent if isinstance(indent, int) and indent >= 0 else None
+    fnm = path.basename(pf)
+    try:
+        with open(pf, 'w', encoding='utf-8') as fil:
+            dump(data, fil, ensure_ascii=False, indent=indent)
+        return True
+    except Exception:
+        _warn(f"save ; {fnm} ; fail", "fail", "91m")
+        return False

arin_log-0.2.0.dist-info/METADATA

@@ -0,0 +1,185 @@
+Metadata-Version: 2.4
+Name: arin-log
+Version: 0.2.0
+Summary: A lightweight logging package for long-running pipelines: a virtual assistant for the user, a clean archive for the developer.
+Author-email: Marcus Aurelius <marcus.aurelius.hu@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/marcus-aurelius-hu/arin_log
+Project-URL: Source, https://github.com/marcus-aurelius-hu/arin_log
+Project-URL: Issues, https://github.com/marcus-aurelius-hu/arin_log/issues
+Keywords: logging,pipeline,console,logger,arin
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: System :: Logging
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# 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
+
+```bash
+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:
+
+```python
+from arin_log import change_folder
+change_folder()
+```
+
+---
+
+## Quick example
+
+```python
+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
+------------------------------------------------------------
+```
+
+---
+
+## What makes `arin_log` different?
+
+| Aspect | `arin_log` | Loguru / stdlib / structlog |
+|---|---|---|
+| **Context propagation** | One parameter `logloc` travels through the whole call chain; every submodule becomes part of the same log file | `LoggerAdapter`, `contextvars`, or manual config |
+| **Console vs. log file** | Deliberately separated: console = everything (with Arin as a voice), log file = only the beacons | Everything goes to the same handlers |
+| **Archive** | One log file per main module per day, with automatic section separation per subtask | Scattered files or one big file |
+| **Arin as virtual assistant** | A character who guides the user, not a log-level prefix | No equivalent |
+| **Exception notation** | `module.function.linenumber ; time ; exception` — compact and directly usable | Full traceback or `exc_info=True` |
+
+**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](LICENSE).
+
+---
+
+## Status
+
+**Alpha (0.2.0).** The core works. Tests are still in development.

arin_log-0.2.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+arin_log/__init__.py,sha256=hP5IEKp9lGNVjzh02xRoFbr4aIv_RP0to764h8FMWDg,1437
+arin_log/console.py,sha256=UlInyJkt0468K0X8r-GfPHu5CZM0TlVtDB1YrZfiKQ4,2868
+arin_log/demo_log.py,sha256=WVwDj_G-c32OEZstqurxtbx0_f_zBU0ECvEfaHKBf3c,873
+arin_log/folder.py,sha256=bttm6LWH7j04dYTA_2JBW6bS_6BIezLWRasW90mvMCw,9709
+arin_log/log_cnfg.json,sha256=-N7A_663Xbc4NQGofNXc99DCpBwUz5wYVWoIzI3SgpQ,1526
+arin_log/logger.py,sha256=3Thbt_iZ54UBsI59lucqOJ2pT3hcfMz6HMEyRsQ40-w,8008
+arin_log/utils.py,sha256=04oJk2328-wxnsDwXWPojcfzu946EpSbRBeoeI2QUx0,2125
+arin_log-0.2.0.dist-info/licenses/LICENSE,sha256=HXmJEUrdgvHJ6S_VAXL9ZWRgKS0KyqzEu0Q_TWxx0nQ,1071
+arin_log-0.2.0.dist-info/METADATA,sha256=RqH2QHQwlzeAUSdz6BBXcWYAHmJYuRnn1zuUU2MWyZU,5936
+arin_log-0.2.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+arin_log-0.2.0.dist-info/top_level.txt,sha256=Z70CumXkXyWyXM6YZk86a1GVb8q6hdsLC7lNpbEJQpY,9
+arin_log-0.2.0.dist-info/RECORD,,

arin_log-0.2.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

arin_log-0.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Marcus Aurelius
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

arin_log-0.2.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+arin_log