Metadata-Version: 2.4
Name: mlog-util
Version: 2026.5.10
Summary: 多进程安全的日志轮转工具，基于 Python logging 扩展
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: rich>=14.2.0
Requires-Dist: portalocker

# mlog-util

多进程安全的 Python 日志轮转工具，基于标准 `logging` 模块扩展。

## 特性

- **多进程安全** — 基于 `portalocker` 文件锁 + 临时文件机制，多进程同时写入不丢日志
- **大小轮转** — 文件达到阈值自动轮转，支持 `"1 M"`、`"5K"`、`"2G"` 等可读格式
- **时间轮转** — 按 S / M / H / D / MIDNIGHT 轮转，多进程共享轮转时间点
- **分级别输出** — 通过 `HandlerConfig` 为每个 handler 独立配置级别、格式、Filter
- **开箱即用** — `setup_logging("project")` 一行生成 task / detail / error 三文件日志体系
- **Rich 控制台** — 默认彩色终端输出

## 安装

```bash
pip install mlog-util
```

## 快速开始

### Tier 1：一行搞定（推荐）

```python
from mlog_util import setup_logging

logger = setup_logging("my_project")
logger.info("任务开始")
```

自动生成 `logs/my_project/` 目录：

```
logs/my_project/
├── task.log      # 任务流程日志
├── detail.log    # 全量日志（INFO+）
└── error.log     # 仅 ERROR
```

项目中的 `logging.getLogger(__name__)` 自动接入 detail.log 和 error.log，无需额外配置。

### Tier 2：分级别 / Filter / 自定义格式

```python
from mlog_util import get_logger, HandlerConfig, MultiProcessSafeSizeRotatingHandler
import logging

err_h = MultiProcessSafeSizeRotatingHandler("logs/error.log")
info_h = MultiProcessSafeSizeRotatingHandler("logs/info.log")

logger = get_logger("my_app", add_console=True, custom_handlers=[
    HandlerConfig(err_h, level=logging.ERROR),
    HandlerConfig(info_h, level=logging.INFO),
])

logger.info("进入 info.log")
logger.error("进入 error.log")
```

### Tier 3：完全自由的日志拓扑

```python
from mlog_util import get_logger, MultiProcessSafeTimeRotatingHandler, make_formatter, FORMAT_JSON
import logging

task_log = get_logger("task", log_file="logs/task.log", add_console=True)

root = logging.getLogger()
root.setLevel(logging.DEBUG)

detail_h = MultiProcessSafeSizeRotatingHandler("logs/detail.log", maxBytes=10*1024*1024)
detail_h.setFormatter(make_formatter())
root.addHandler(detail_h)

error_h = MultiProcessSafeTimeRotatingHandler("logs/error.log", when="D")
error_h.setFormatter(make_formatter(FORMAT_JSON))
error_h.setLevel(logging.ERROR)
root.addHandler(error_h)
```

## Handler 类型

| Handler | 触发方式 | 默认参数 | 场景 |
|---|---|---|---|
| `MultiProcessSafeSizeRotatingHandler` | 文件大小 | `maxBytes=5MB` | 通用 |
| `MultiProcessSafeTimeRotatingHandler` | 时间间隔 | `when="D"` | 周期性任务 |

## Formatter 预设

| 常量 | 输出示例 |
|---|---|
| `FORMAT_DETAIL` | `2026-05-10 21:00:00 \| module \| INFO \| 消息` |
| `FORMAT_SIMPLE` | `2026-05-10 21:00:00 \| 消息` |
| `FORMAT_PLAIN` | `module - INFO - 消息` |
| `FORMAT_JSON` | `{"time":"...","name":"module","level":"INFO","msg":"消息"}` |

## 开发

```bash
# 安装依赖
uv sync

# 运行测试
uv run python -m pytest tests/ -v
```

## 文档

- [使用指南](docs/usage.md) — 三层用法详解
- [测试计划](docs/test_plan.md)

## 变更记录

### v2026.05.10

- 新增 `setup_logging` 一站式三文件日志配置
- 新增 `__init__.py` 模块级文档和使用示例
- 新增 `docs/usage.md` 三层用法指南

### v2026.04.28

- `log_manager` 优化
  - 新增预设 Formatter 常量：`FORMAT_DETAIL`、`FORMAT_SIMPLE`、`FORMAT_PLAIN`、`FORMAT_JSON` 和 `make_formatter()` 工厂函数
  - `custom_handlers` 支持列表和 `HandlerConfig`，可为每个 handler 单独配置级别、格式、过滤条件
  - `HandlerConfig(handler, level=ERROR, formatter=fmt, filters=[...])`
- `handlers` 修复
  - `maxBytes` 支持 G 单位（`"2G"`）
  - `maxBytes` 解析前自动去除空格
  - 修复极端并发下临时文件竞态导致的日志丢失
- 添加 pytest 测试套件（85 个测试），添加 `dev/` 演示脚本

### v0.1.7 - 2025-10-28

- 时间轮询基准时间从 UTC 改为本地时间
- 新增轮询时间和文件大小（默认 1 天 + 5MB）

### v2025.12.03

- 删除时间轮询方式
- 修改文件大小轮询方式

### v2025.12.11

- 重新添加时间轮询方式，添加测试

### v2025.12.16

- 修改 format 为 `%(asctime)s | %(name)-8s | %(levelname)-4s | %(message)s`

### v2025.12.23

- 调整时间轮询默认值为天

### v0.1.6 - 2025-10-17

- 调整整体结构，修复 v0.1.4 不可用问题

### v0.1.5 - 2025-10-17

### v0.1.4 - 2025-10-17

- 调整 `log_manager` 模块结构
