Metadata-Version: 2.4
Name: sysentropy
Version: 0.1.1
Summary: Opinionated Python logging
Author: leogabac
License: MIT License
        
        Copyright (c) 2026 leogabac
        
        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.
        
Project-URL: Homepage, https://github.com/leogabac/sysentropy
Project-URL: Repository, https://github.com/leogabac/sysentropy
Keywords: logging,logger,color,stdout,python
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: System :: Logging
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# sysentropy

Opinionated Python logging for the recurring problem of:
"I just need a decent logger, why am I formatting timestamps by hand again?"

`sysentropy` is a small Python library that writes plain logs to disk, colored logs to stdout, and gives you reusable timestamp, timing, and exception helpers so you can stop rebuilding the same logging glue in every project.

## How This Repo Happened

This repo exists because writing the same logging setup in every project gets old fast.

One day it is:
- "I'll just do a tiny logger wrapper."
- then "I want colors."
- then "I want a logfile too."
- then "why is this handler duplicated?"
- then "what was that timestamp format again?"

At that point the only rational response was obviously to make a library about it.

So this is the result: a lightweight package extracted from that exact cycle of mild annoyance, repeated enough times to become a design requirement. Very noble. Very serious. Entirely unnecessary until it suddenly isn't.

## What It Does

- plain logs on disk
- colored logs on stdout
- a small API built on top of the standard `logging` module
- a reusable timestamp helper for logfile names and other boring-but-common cases
- a timing decorator for quick execution-time logging
- lightweight helpers for timed blocks and exception logging

## Features

- Linux-kernel-inspired level colors for console output
- separate stdout and file formatters
- simple `get_logger()` entrypoint
- optional directory creation for file logging
- handler reuse to avoid duplicate output
- a configuration object that leaves room for future expansion
- a `timestamp()` helper that returns `YYYYMMDD_HHMMSS`
- a `timing()` decorator that logs function runtime
- a `time_block()` context manager for inline timing
- a `log_exceptions()` helper that logs tracebacks before re-raising
- automatic color detection for TTY vs redirected output

## Install

```bash
pip install sysentropy
```

## Quick start

```python
from sysentropy import get_logger, log_exceptions, time_block, timestamp, timing

logger = get_logger("demo", log_file=f"logs/demo-{timestamp()}.log")


@timing(logger=logger)
@log_exceptions(logger=logger)
def do_work() -> None:
    with time_block("startup", logger=logger):
        logger.info("service started")

logger.debug("debug message")
do_work()
logger.warning("disk usage high")
logger.error("request failed")
logger.critical("system halted")
```

Default output style:

```text
2026-04-01 22:00:00 INFO     : service started
2026-04-01 22:00:00 WARNING  : disk usage high
2026-04-01 22:00:00 ERROR    : request failed
```

## Timestamp Helper

If you only need the timestamp format, import it directly:

```python
from sysentropy import timestamp

filename = f"run-{timestamp()}.log"
```

It returns values like:

```text
20260401_223735
```

## Timing Helper

Use `timing()` as a decorator when you want a quick runtime measurement in your logs:

```python
from sysentropy import get_logger, timing

logger = get_logger("demo")


@timing(logger=logger, label="expensive task")
def expensive_task() -> None:
    ...
```

It logs lines like:

```text
2026-04-02 09:15:00 INFO     : expensive task completed in 0.012384s
```

## Timed Blocks

Use `time_block()` when you only want to time one section of a function:

```python
from sysentropy import get_logger, time_block

logger = get_logger("demo")

with time_block("database warmup", logger=logger):
    ...
```

## Exception Logging

Use `log_exceptions()` to log tracebacks before the exception keeps propagating:

```python
from sysentropy import get_logger, log_exceptions

logger = get_logger("demo")


@log_exceptions(logger=logger)
def run_job() -> None:
    raise RuntimeError("boom")
```
