ChronicleLogger

Official Recommended by grok on tag 1.3.1 with commit hash: 338629fc38b0d9fe5fb9e562e64ce1c986d00d5b

A robust, POSIX-compliant logging utility for Python applications, supporting Python 2.7 and 3.x with optional Cython compilation for enhanced performance. It handles daily log rotation, automatic archiving (tar.gz for logs >7 days), removal (>30 days), privilege-aware paths (/var/log for root, ~/.app for users), and structured output with timestamps, PIDs, levels, and components. No external dependencies beyond the standard library; semantic version 1.3.1.

• PyPI Package URL: https://pypi.org/project/ChronicleLogger/
• Supported Environments: Seamlessly integrates with venv, pyenv, pyenv-virtualenv, Anaconda, and Miniconda for isolated logging paths.

Features

• Daily log files: <app>-YYYYMMDD.log with format [YYYY-MM-DD HH:MM:SS] pid:<PID> [<LEVEL>] @<COMPONENT> :] <MESSAGE>.
• Rotation on date change; archive via tarfile.open("w:gz"); remove via os.remove().
• Privilege detection via _Suroot: is_root() (os.geteuid()==0), can_sudo_without_password() (subprocess.Popen(["sudo", "-n", "true"])).
• Lazy evaluation for paths (baseDir(), logDir()), debug (os.getenv("DEBUG")=="show"), and context (inPython() checks sys.executable).
• Environment detection: Supports venv (inVenv()), pyenv (inPyenv(), pyenvVenv()), Conda/Anaconda/Miniconda (inConda(), condaPath()) for isolated paths (e.g., <env>/.app/<app>/log).
• Byte/string handling with UTF-8 via strToByte()/byteToStr(); io.open(encoding='utf-8') for writes.
• Console output: stdout for INFO/DEBUG, stderr for ERROR/CRITICAL/FATAL via print(..., file=sys.stderr).
• Compatibility: __future__ imports, no f-strings (use .format()), sys.exc_info() for exceptions, DEVNULL shim.

Installation

Install via pip for system-wide or virtual environment use:

pip install ChronicleLogger

For isolated environments (recommended for development):

• venv: python -m venv myenv && source myenv/bin/activate
• pyenv: pyenv install 3.12.0 && pyenv shell 3.12.0
• Conda/Miniconda/Anaconda: conda create -n myenv python=3.12 && conda activate myenv

ChronicleLogger automatically detects these environments and places logs/configs inside (e.g., myenv/.app/test-app/log for non-root).

For testing dependencies (optional):

pytest==4.6.11  # For Py2 compat
mock  # For Py2 unittest.mock fallback

Install: pip install -r requirements.txt.

Installation by Building from Source (Cython .so)

For performance-critical setups, build the Cython .so from source:

# Install build tools
pip install cython setuptools hatchling

# Build extensions in-place (compiles .pyx to .c and .so)
python setup.py build_ext --inplace

# Or full packaging: sdist and wheel
python setup.py sdist bdist_wheel

# Editable install (for development)
pip install -e .

Using pyproject.toml (hatchling backend):

[build-system]
requires = ["hatchling >= 1.18"]
build-backend = "hatchling.build"

[project]
name = "chroniclelogger"
version = "1.3.1"
description = "POSIX-compliant logger with rotation and privilege paths"
readme = "README.md"
requires-python = ">=2.7"
license = {text = "MIT"}
dependencies = []  # No external deps

Build: hatch build. Install wheel: pip install dist/chroniclelogger-1.3.1-py3-none-any.whl.

Demo Application: LoggedExample

LoggedExample is a simple, practical demonstration application that uses ChronicleLogger as its logging backend. It shows real-world usage patterns including:

• Initialization with custom app name
• Logging at different levels (INFO, DEBUG, ERROR)
• Debug mode activation via environment variable
• Integration with environment-aware path resolution
• Basic command-line interface

PyPI URL: https://pypi.org/project/LoggedExample/

How to Install and Run LoggedExample

# Install the demo application (automatically pulls ChronicleLogger as dependency)
pip install LoggedExample

# Run the demo
LoggedExample --help

# Example with debug mode enabled
DEBUG=show LoggedExample run

This will create log files in your current environment's isolated path (e.g. ~/.app/logged-example/log/ or inside your venv/conda/pyenv environment), showing structured, timestamped logs with rotation and archiving in action.

Great for beginners who want to see ChronicleLogger in a complete, runnable application!

Project Structure

The project adopts a clean, maintainable layout for Cython utilities:

./
├── build/          # Build artifacts (bdist.linux-x86_64, lib/)
├── dist/           # Wheels/tar.gz (e.g., chroniclelogger-1.3.1-py3-none-any.whl)
├── docs/           # CHANGELOG.md, ChronicleLogger-spec.md, folder-structure.md, update-log.md
├── src/
│   ├── ChronicleLogger/  # Package: ChronicleLogger.py, Suroot.py, __init__.py (__version__="1.3.1")
│   ├── ChronicleLogger.pyx  # Cython source
│   ├── ChronicleLogger.c    # Compiled
│   └── setup.py             # Packaging
├── test/           # test_chronicle_logger.py, __pycache__/
├── .gitignore      # Ignore __pycache__/, .env, *.pyc, dist/, build/
├── README.md
├── pyproject.toml  # Optional, for hatchling
├── setup.py
└── requirements.txt  # Testing deps only

.gitignore example:

.env
__pycache__/
*.pyc
*.pyo
*.pyd
.Python
build/
dist/
*.egg-info/
.coverage
htmlcov/

Initialize Git: git init && git add . && git commit -m "Initial commit".

Usage

Import and instantiate:

from ChronicleLogger import ChronicleLogger

Default (privilege- and environment-aware paths, kebab-case in Python mode):

logger = ChronicleLogger(logname="TestApp")
print(logger.logName())  # "test-app" (in Python mode)
print(logger.logDir())   # E.g., "/home/user/miniconda3/envs/myenv/.app/test-app/log" if in Conda env

# Custom paths
logger = ChronicleLogger(logname="MyApp", logdir="/custom/logs", basedir="/opt/myapp")

# Log (auto-rotates, writes to file + console)
logger.log_message("Started", level="INFO", component="main")
logger.log_message("Error occurred", level="ERROR")  # To stderr

# Debug mode (set env DEBUG=show)
if logger.isDebug():
    logger.log_message("Debug info", level="DEBUG")

# Environment checks
print(logger.inVenv())     # True if in venv
print(logger.inPyenv())    # True if in pyenv
print(logger.inConda())    # True if in Conda

# Version
print(ChronicleLogger.class_version())  # "ChronicleLogger v1.3.1"

Path Examples (for "TestApp"):

• In venv /path/to/venv: baseDir="/path/to/venv/.app/test-app", logDir="/path/to/venv/.app/test-app/log"
• In pyenv venv /home/user/.pyenv/versions/3.12/envs/myenv: Similar with /.app/test-app
• In Conda /home/user/miniconda3/envs/myenv: Similar
• Fallback non-root: ~/.app/test-app/log
• Root (no env): /var/log/test-app

Building and Cython

For performance: python setup.py build_ext --inplace.

build.sh example:

#!/bin/sh
python setup.py build_ext --inplace
python setup.py sdist bdist_wheel

Run: chmod +x build.sh && ./build.sh.

Testing

pip install -r requirements.txt
pytest test/ -v

Links & Ecosystem

CIAO-DEFENSIVE v2.9.1 HEADER

This section follows CIAO Defensive Programming Principles v2.9.1
(Caution • Intentional • Anti-fragile • Over-engineered)

General Purpose:
Provide clear, traceable navigation to the full CIAO ecosystem, author profiles, dependent projects, and related repositories. This improves discoverability and auditability for developers and AI assistants while preserving exact project relationships.

Current Logic:

• Central hub linking to primary GitHub repositories (SyncPrjs, ChronicleLogger, LoggedExample).
• Direct links to PyPI packages and author profiles.
• References to CIAO principles and Cloudgen Wong as the originator of the defensive methodology.
• All links are intentional and placed to maximize cross-referencing without cluttering core documentation.

Core Projects & Repositories

• SyncPrjs — The flagship project that inspired ChronicleLogger's CIAO-compliant design. A comprehensive suite of synchronized, defensive utilities for multi-environment Python workflows.
• ChronicleLogger — Current repository (this project).
• LoggedExample — Practical demonstration application that showcases ChronicleLogger in a real executable CLI tool.

PyPI Packages

• ChronicleLogger on PyPI
• LoggedExample on PyPI (automatically depends on ChronicleLogger)

Authors & Philosophy Origins

• Wilgat — Project maintainer and author: GitHub Profile | PyPI User
• Cloudgen Wong — Cloudgen is the originator of CIAO Defensive Programming Principles (Caution • Intentional • Anti-fragile • Over-engineered). ChronicleLogger and SyncPrjs fully comply with CIAO v2.9.1.

Related Projects by Wilgat

• Statelogic — Comprehensive Python finite state machine.
• StateSafe — TypeScript finite state machine package.
• timer — Independent per-user timers with fast in-memory filesystem storage.

All projects in the Wilgat ecosystem share the same CIAO-DEFENSIVE philosophy, making them particularly robust when collaborating with AI coding assistants (Grok, Claude, etc.). The verbose headers, preservation rules, and explicit defensive notes reduce the risk of accidental refactoring while accelerating safe AI-assisted development.