arin-log 0.2.0__tar.gz

arin_log-0.2.0/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/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,160 @@
+# 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/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-0.2.0/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-0.2.0/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()