Metadata-Version: 2.3
Name: ezlog-py
Version: 1.0.5
Summary: Simple, performant logging with ANSI colors for Python.
Author: eaannist
Author-email: eaannist <eaannist@gmail.com>
Requires-Dist: pytest>=9.0.2
Requires-Dist: pytest>=8.0.0 ; extra == 'dev'
Requires-Python: >=3.12
Provides-Extra: dev
Description-Content-Type: text/markdown

# ezlog

Simple, performant logging with ANSI colors for Python.  
Published on PyPI as **ezlog-py**.

- **6 levels**: `debug`, `info`, `success`, `warn`, `error`, `critical`
- **Short aliases**: `d`, `i`, `s`, `w`, `e`, `c`
- **ANSI colors**: full palette
- **Stdlib integration**: creating an EzLog wires it to stdlib logging automatically
- **Zero dependencies**

## Install

```bash
pip install ezlog-py
```

## Usage

Create a logger; it wires itself to stdlib logging. Use `log.i()`, `log.success()`, and anywhere `logging.info()` / `logger.error()` also go through ezlog:

```python
from ezlog import EzLog

log = EzLog()  # or EzLog({"useColors": True, "timestamp": False})

# Direct ezlog (includes .success() level)
log.success("Application started")
log.i("Hello")
log.w("Oops")
log.e("OMG")
log.d("hmmm..")

# Stdlib logging (wired internally; same formatting)
import logging
logging.info("From stdlib")
logging.error("Failed", exc_info=True)
```

## Configuration

```python
# Example: custom config (partial overrides)
log = EzLog({
    "useColors": True,
    "useLevels": True,
    "useSymbols": False,
    "timestamp": {
        "color": "white",
        "format": "%Y-%m-%d %H:%M:%S",
    },
    "levels": {
        "info": {"text": "Information"},
        "debug": False,      # disable debug in production
        "critical": False,   # or disable a level entirely
    },
})
```

Each option has a default and is optional.

- **useColors** : boolean – Enable ANSI colors. Default `True`.
- **useLevels** : boolean – Show level label/symbol in output. Default `True`.
- **useSymbols** : boolean – Use symbol for level (if `False`, use text label). Default `True`.
- **timestamp** : `TimestampConfig` or `False` – Configure timestamp, or set to `False` to disable.
- **levels** : `LevelsConfig` – Keys: `debug`, `info`, `success`, `warn`, `error`, `critical`. Each value is a `LevelConfig` (partial override) or `False` to disable that level.

#### `LevelConfig`

- **color** : `LogColors` – Level color (e.g. `"light-red"`, `"cyan"`).
- **text** : str – Level label (e.g. `"INFO"`, `"Error"`).
- **symbol** : str – Level symbol; validated with a safe fallback when the system doesn’t support the character.

#### `TimestampConfig`

- **format** : str – strftime format (e.g. `"%Y-%m-%d %H:%M:%S"`). Default from `ezlog.defaults.DEFAULT_TIMESTAMP_FORMAT`.
- **color** : `LogColors` or `"as_levels"` – Timestamp color. `"as_levels"` uses the same color as the log level. Default `"as_levels"`.

## Levels

- **Order (severity)**: `debug` → `info` → `success` → `warn` → `error` → `critical`.
- **Short aliases**: `d`, `i`, `s`, `w`, `e`, `c`.
- **Stdlib mapping**: `logging.DEBUG` → debug, `logging.INFO` → info, `logging.WARNING` → warn, `logging.ERROR` → error, `logging.CRITICAL` → critical. `NOTSET` is skipped.
- Default symbols and colors are in `ezlog.defaults` (`DEFAULT_TEXTS`, `DEFAULT_COLORS`, `DEFAULT_SYMBOLS_FALLBACK`).

## Color properties

When **useColors** is enabled, the logger exposes: `log.red`, `log.yellow`, `log.cyan`, `log.green`, `log.magenta`, `log.white`, `log.gray`, `log.reset`. Use them for custom formatted output; end colored segments with `log.reset`.

## Exports

- **EzLog**(config?) – Create logger (wires to stdlib on construction). Config optional: `EzLog()` or `EzLog({"useColors": True, "timestamp": False})`.
- **Types** – `LogLevel`, `LogColors`, `TimestampColor`, `TimestampConfig`, `EzlogConfig`, `LevelsConfig`, `LevelConfig`, `LogArgs`, `ConsoleMethod`.
- **Constants** (from `ezlog.defaults`) – `COLOR_CODES`, `RESET`, `DEFAULT_SYMBOLS_FALLBACK`, `DEFAULT_TEXTS`, `DEFAULT_COLORS`, `DEFAULT_TIMESTAMP_FORMAT`, `DEFAULT_TIMESTAMP_COLOR`, `DEFAULT_TIMESTAMP`.
