Metadata-Version: 2.4
Name: elegant-log
Version: 0.1.2
Summary: 现代化的Python日志库
Author-email: ElegantLog Team <elegantlog@example.com>
License: MIT
License-File: LICENSE
Keywords: elegant,logging,modern,performance
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.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Logging
Requires-Python: >=3.12
Description-Content-Type: text/markdown

# ElegantLog

现代化的 Python 日志库，重点解决这几类问题：

- 多进程场景下的文件日志
- 按大小 / 按服务器本地时间跨午夜轮转
- 父子 logger 重复输出
- JSON 结构化日志
- `print()` 增强与全局异常捕获
- Web 框架中的日志恢复与稳定性

## 安装

```bash
pip install elegant-log
```

要求：

- Python `>= 3.12`

## 文档

- [文档入口](docs/README.md)
- [进阶指南](docs/ADVANCED_GUIDE.md)
- [JSON 日志指南](docs/JSON_LOGGING.md)
- [开发者指南](docs/DEVELOPER_GUIDE.md)
- [示例代码](examples/)

## 快速开始

### 最小示例

```python
import elegantlog

logger = elegantlog.get_logger("myapp")
logger.info("应用已启动")
logger.warning("这是一条警告")
logger.error("这是一条错误")
```

### 输出到文件

```python
logger = elegantlog.get_logger(
    name="myapp",
    file=True,
    log_dir="./logs",
    console=True,
)

logger.info("日志将写入 ./logs/myapp_{pid}.log")
```

说明：

- 活动文件命名：`myapp_{pid}.log`
- 每个进程独立文件，避免多进程锁竞争

### 启用日志轮转

`rotation_by_date=False`：只按大小轮转

```python
logger = elegantlog.get_logger(
    name="myapp_size_only",
    file=True,
    log_dir="./logs",
    rotation_by_size=True,
    max_file_size=50 * 1024 * 1024,
    rotation_by_date=False,
    backup_count=7,
)
```

适用场景：

- 只关心控制单个日志文件大小
- 不需要按天切分日志

`rotation_by_date=True`：按服务器本地时间跨午夜轮转

```python
logger = elegantlog.get_logger(
    name="myapp_daily",
    file=True,
    log_dir="./logs",
    rotation_by_size=True,
    max_file_size=50 * 1024 * 1024,
    rotation_by_date=True,
    backup_count=7,
)
```

归档文件命名示例：

- `myapp_{pid}_20240115_143025_0001.log`

日期轮转说明：

- `rotation_by_date=True` 时，按服务器本地时间在跨午夜时轮转
- 迟到日志不会回写历史日期文件
- 如果需要按事件发生日期归档，应交给外部日志收集或归档系统处理

### 性能相关配置

```python
logger = elegantlog.get_logger(
    name="high_performance",
    file=True,
    batch_size=500,
    flush_interval=2.0,
    async_mode=True,
)
```

### Print 增强

```python
from elegantlog import enable_print_enhancement

enable_print_enhancement()
print("带时间戳和调用位置的输出")
```

### 异常捕获

```python
from elegantlog import enable_exception_capture

logger = elegantlog.get_logger("myapp", file=True)
enable_exception_capture(logger)
```

### JSON 日志

```python
import elegantlog
from elegantlog import JsonFormatter

logger = elegantlog.get_logger("myapp", file=True)
formatter = JsonFormatter(
    static_fields={"service": "myapp", "environment": "production"}
)

for handler in logger.handlers:
    handler.setFormatter(formatter)

logger.info("用户登录", extra={"user_id": "user123", "ip": "192.168.1.1"})
```

更多内容：

- JSON 输出结构、配置项和接入方式见 [docs/JSON_LOGGING.md](docs/JSON_LOGGING.md)
- JSON 内部设计与维护说明见 [docs/JSON_INTERNALS.md](docs/JSON_INTERNALS.md)

## 常用 API

```python
elegantlog.get_logger(name, **kwargs)
elegantlog.configure(config)
elegantlog.set_exclusive_handler(name, handler_type, **kwargs)
elegantlog.clear_handlers(name)
elegantlog.replace_handler(name, old_handler_type, new_handler_type, **kwargs)
```

## 下一步看什么

如果你已经完成基础接入，建议按这个顺序继续阅读：

1. [docs/ADVANCED_GUIDE.md](docs/ADVANCED_GUIDE.md)
2. 如果使用 JSON 输出，再看 [docs/JSON_LOGGING.md](docs/JSON_LOGGING.md)
3. 如果你要参与仓库开发，再看 [docs/DEVELOPER_GUIDE.md](docs/DEVELOPER_GUIDE.md)
