Metadata-Version: 2.4
Name: ChronicleLogger
Version: 1.3.1
Summary: Privilege-aware, auto-rotating daily logger for Linux daemons & CLI tools
Home-page: https://github.com/Wilgat/ChronicleLogger
Author: Wilgat Wong
Author-email: wilgat.wong@gmail.com
License: MIT
Project-URL: Bug Tracker, https://github.com/Wilgat/ChronicleLogger/issues
Project-URL: Source, https://github.com/Wilgat/ChronicleLogger
Keywords: logging linux daemon sudo privilege log rotation daily
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
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: License :: OSI Approved :: MIT License
Classifier: Operating System :: POSIX :: Linux
Classifier: Topic :: System :: Logging
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Requires-Python: >=2.7, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*, !=3.4.*
Description-Content-Type: text/markdown
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: license
Dynamic: project-url
Dynamic: requires-python
Dynamic: summary

# ChronicleLogger

[![Version](https://img.shields.io/badge/Version-1.3.1-blue?style=flat-square)](https://github.com/Wilgat/ChronicleLogger)
[![License](https://img.shields.io/badge/License-MIT-green?style=flat-square)](LICENSE)
[![CIAO](https://img.shields.io/badge/Philosophy-CIAO%20(Caution%20%E2%80%A2%20Intentional%20%E2%80%A2%20Anti--fragile%20%E2%80%A2%20Over--engineered)-purple.svg)](https://github.com/cloudgen/ciao)

Official Recommended by [grok](https://grok.com/c/9b027c66-e076-4c3c-9e1d-46f496013ed1?rid=152b4130-8500-45c1-b531-0130f191d7a1) 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:

```bash
# 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):

```toml
[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
```bash
# 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:

```python
from ChronicleLogger import ChronicleLogger
```

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

```python
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:

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

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

## Testing
```bash
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](https://github.com/cloudgen/ciao) and [Cloudgen Wong](https://github.com/cloudgen) 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](https://github.com/Wilgat/SyncPrjs)** — The flagship project that inspired ChronicleLogger's CIAO-compliant design. A comprehensive suite of synchronized, defensive utilities for multi-environment Python workflows.  
- **[ChronicleLogger](https://github.com/Wilgat/ChronicleLogger)** — Current repository (this project).  
- **[LoggedExample](https://github.com/Wilgat/LoggedExample)** — Practical demonstration application that showcases ChronicleLogger in a real executable CLI tool.  

### PyPI Packages

- **[ChronicleLogger on PyPI](https://pypi.org/project/ChronicleLogger/)**  
- **[LoggedExample on PyPI](https://pypi.org/project/LoggedExample/)** (automatically depends on ChronicleLogger)

### Authors & Philosophy Origins

- **Wilgat** — Project maintainer and author: [GitHub Profile](https://github.com/Wilgat) | [PyPI User](https://pypi.org/user/wilgat/)  
- **Cloudgen Wong** — [Cloudgen](https://github.com/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](https://github.com/Wilgat/Statelogic)** — Comprehensive Python finite state machine.  
- **[StateSafe](https://github.com/Wilgat/StateSafe)** — TypeScript finite state machine package.  
- **[timer](https://github.com/Wilgat/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.

---
