Metadata-Version: 2.4
Name: logry
Version: 0.1.0
Summary: A fast, flexible Python logging library with sync and async support.
Project-URL: Homepage, https://github.com/riokzyofficial-debug/logry
Project-URL: Repository, https://github.com/riokzyofficial-debug/logry
Author: riokzy
License: MIT
License-File: LICENSE
Keywords: async,cli,logger,logging,logry
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
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: Topic :: System :: Logging
Classifier: Typing :: Typed
Requires-Python: >=3.8
Description-Content-Type: text/markdown

# logry

Python logging library with native async support, multiple independent loggers, and zero external dependencies.

## Installation

```
pip install logry
```

Requires Python 3.8 or higher.

---

## Quick Start

```python
from logry import log

log.info("Server started")
log.success("Connected to database")
log.warning("Memory usage at 80%")
log.error("Connection dropped")
log.debug("user_id=123")
```

Output:

```
[2026-03-09 10:23:45] INFO    | Server started
[2026-03-09 10:23:46] SUCCESS | Connected to database
[2026-03-09 10:23:47] WARNING | Memory usage at 80%
[2026-03-09 10:23:48] ERROR   | Connection dropped
[2026-03-09 10:23:49] DEBUG   | user_id=123
```

---

## Log Levels

| Level   | Method          | Color  |
|---------|-----------------|--------|
| DEBUG   | `log.debug()`   | Grey   |
| INFO    | `log.info()`    | Blue   |
| SUCCESS | `log.success()` | Green  |
| WARNING | `log.warning()` | Yellow |
| ERROR   | `log.error()`   | Red    |

---

## Usage

### Global logger

The simplest way to use logry is via the built-in global `log` instance, which is ready to use immediately after import.

```python
from logry import log

log.info("Application initialized")
log.error("Unexpected error")
```

### Named loggers

Each `Logger` instance is fully independent and can be configured separately.

```python
from logry import Logger

db  = Logger("database")
api = Logger("api")
bot = Logger("bot")

db.info("Connected to PostgreSQL")
api.error("Request timeout")
bot.success("Polling started")
```

### Output formats

Three formats are available: `pretty` (default), `minimal`, and `json`.

`pretty` outputs colored lines with a timestamp, suited for development. `minimal` outputs level and message only. `json` outputs structured single-line JSON, suited for production log collection.

```python
log = Logger("app", format="json")
log.info("Structured output")
```

```json
{"time": "2026-03-09 10:23:45", "level": "INFO", "name": "app", "message": "Structured output"}
```

### File output

```python
log = Logger("app")
log.set_file("app.log")
```

With automatic rotation:

```python
log.set_file("app.log", max_size="10MB", backup=3)
```

`max_size` accepts values in `KB` or `MB`. When the file reaches the specified size, it is rotated and up to `backup` copies are retained.

### Custom colors

```python
log.set_colors({
    "debug":   "cyan",
    "info":    "blue",
    "success": "green",
    "warning": "yellow",
    "error":   "red",
})
```

Available colors: `black`, `red`, `green`, `yellow`, `blue`, `magenta`, `cyan`, `white`, `grey`.

### Full configuration

All options can be set at construction time or updated at runtime.

```python
log = Logger(
    name="app",
    level="DEBUG",
    save="app.log",
    format="pretty",
    colors=True,
    async_mode=False,
)

log.set_level("WARNING")
log.set_format("json")
log.set_file("app.log", max_size="5MB", backup=5)
```

### Async support

When `async_mode=True`, log calls become coroutines and must be awaited. Output is written through an `asyncio.Queue` worker, keeping the event loop unblocked.

```python
import asyncio
from logry import Logger

log = Logger("app", async_mode=True)

async def main():
    await log.ainfo("Async log entry")
    await log.aerror("Async error")

asyncio.run(main())
```

---

## Benchmarks

Tested on Python 3.12 with 100,000 filtered log entries. Filtered means the log level of the call is below the logger's active level, so no output is produced — the most common scenario in production.

| Library        | Time   | Messages/sec |
|----------------|--------|--------------|
| stdlib logging | 0.085s | 1,176,000    |
| logry         | 0.031s | 3,225,000    |

logry avoids formatting the message string entirely when the log level is inactive (lazy formatting), which accounts for the difference.

---

## License

MIT © riokzy
