Metadata-Version: 2.4
Name: zy_log
Version: 0.3.0
Summary: An advanced, asynchronous logging system for algorithmic projects.
Author-email: zy <zhoumuci77@gamil.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/yaosterm/zy_log
Project-URL: Bug Tracker, https://github.com/yaosterm/zy_log/issues
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Classifier: Topic :: System :: Logging
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: rich>=13.0.0
Dynamic: license-file

# zy_log

为 Python 项目提供异步文件日志和 Rich 控制台输出。日志路径由你指定，默认追加写入，不会自动插入日期目录或时间戳。

## 安装

```bash
pip install zy_log
```

要求 Python 3.8 或更高版本。

## 快速使用

```python
from zy_log import setup_logging, get_logger

# 每次启动都追加到同一个文件；目录不存在时自动创建。
log_path = setup_logging("log/training.log", level="INFO")
logger = get_logger(__name__)
logger.info("Training started")
logger.info("中文日志同样支持")
```

不传参数时，固定写入当前工作目录下的 `log/default_algorithm.log`。`setup_logging()` 返回实际使用的绝对路径（`pathlib.Path`）。

- `setup_logging("training.log")`：当前工作目录下的 `training.log`。
- `setup_logging("logs/training.log")`：当前工作目录下的 `logs/training.log`。
- 绝对路径：直接使用该路径。
- 所有路径均不会添加日期、时间戳、扩展名或额外的 `log/` 前缀。
- 相对路径以进程的当前工作目录为准，与脚本所在目录无关。需要跨工作目录续写时，请传绝对路径。

在程序主入口初始化一次，各子模块只需要调用 `get_logger(__name__)`。也可以使用标准库 `logging.getLogger()`。

## 常用设置

```python
from zy_log import setup_logging

# 默认追加；程序重启后继续写入同一个文件。
setup_logging("log/training.log", mode="a")

# 显式清空当前文件，再开始写入。已有轮转备份不会被清空。
setup_logging("log/training.log", mode="w")

# 文件记录 DEBUG 及以上，控制台只显示 WARNING 及以上。
setup_logging(
    "log/training.log",
    file_level="DEBUG",
    console_level="WARNING",
)

# 只写文件。
setup_logging("log/training.log", console=False)

# 文件达到约 20 MiB 时轮转，最多保留 10 份备份。
setup_logging("log/training.log", max_bytes=20 * 1024 * 1024, backup_count=10)

# 不轮转，持续追加到同一个文件。
setup_logging("log/training.log", max_bytes=0)
```

轮转后的备份名为 `training.log.1`、`training.log.2` 等，其中 `.1` 最新；超过保留数量的旧备份会删除。单条记录较大时，文件大小可能超过阈值。

## 参数

除第一个 `log_file` 外，所有参数均须通过名称传入。未知参数和无效设置会直接报错。

| 参数 | 默认行为 | 含义 |
| --- | --- | --- |
| `log_file` | `log/default_algorithm.log` | 文件路径，接受字符串或 Path |
| `level` | `INFO`，可由环境变量或 JSON 设置 | 文件和控制台共用的基础级别 |
| `file_level` | 继承基础级别 | 文件级别 |
| `console_level` | 继承基础级别 | 控制台级别 |
| `mode` | `"a"` | `"a"` 追加；`"w"` 在初始化时清空当前文件 |
| `console` | `True` | 是否输出到控制台 |
| `max_bytes` | `10485760`（10 MiB） | 轮转阈值；`0` 关闭轮转 |
| `backup_count` | `5` | 备份数量；启用轮转时必须大于 0 |
| `encoding` | `"utf-8"` | 日志文件编码 |
| `config_path` | 不读取外部配置 | 简单 JSON 配置的路径 |
| `env_key_level` | `"LOG_LEVEL"` | 基础级别环境变量名；`None` 表示忽略环境变量 |
| `capture_exceptions` | `True` | 记录主线程的未捕获异常 |
| `show_startup` | `False` | 是否输出一条英文 INFO 启动记录，仍受日志级别过滤 |
| `log_format` | 时间、PID、名称、级别、消息、来源 | 文件日志的标准库 `%` 格式 |
| `date_format` | `"%Y-%m-%d %H:%M:%S"` | 文件日志中的时间格式 |

级别接受 `"DEBUG"`、`"INFO"` 等字符串，也接受 `logging.DEBUG` 等整数常量。参数的 `None` 表示未覆盖配置，不代表关闭功能。

基础级别优先级：**显式 `level` > 环境变量 > JSON > 内置默认值**。单独设置的 `file_level`、`console_level` 决定对应输出的级别。其他设置的优先级为：**显式参数 > JSON > 内置默认值**。

## JSON 配置

例如创建 `logging.json`：

```json
{
  "log_file": "log/training.log",
  "level": "INFO",
  "file_level": "DEBUG",
  "console_level": "WARNING",
  "mode": "a",
  "max_bytes": 20971520,
  "backup_count": 10
}
```

```python
setup_logging(config_path="logging.json")
# 显式参数仍然可以覆盖 JSON 中的值。
setup_logging(config_path="logging.json", log_file="log/another.log", console=False)
```

配置可包含参数表中除 `config_path`、`env_key_level` 以外的设置。`file_level` 和 `console_level` 可设为 `null` 以继承基础级别。JSON 中的相对日志路径同样基于当前工作目录。配置文件不存在、JSON 无效、设置名称错误或日志文件不可打开时会报错；不会把配置文件误当成日志文件。

## 异常与退出

```python
from zy_log import get_logger, flush_logging, shutdown_logging

logger = get_logger(__name__)
try:
    result = 1 / 0
except ZeroDivisionError:
    logger.exception("Calculation failed")

# 记录 ERROR，并抛出具有相同格式化消息的 RuntimeError。
# logger.error_and_raise("Invalid sample: %s", "sample-01")

flush_logging()     # 等待队列写完；之后仍可继续记录。
shutdown_logging()  # 写完队列并关闭本次会话；重复调用也安全。
```

正常退出时会自动等待队列写完。未捕获的主线程异常会记录完整堆栈；中断退出（KeyboardInterrupt）沿用原异常钩子。强制结束进程或断电不能保证队列中的记录已经落盘。

再次调用 `setup_logging()` 会替换当前会话，排空旧队列并关闭旧文件。无效参数、无效配置或文件打开失败时，已有会话会继续工作。配置管理根 logger；已有命名 logger 的独立级别和 handler 不会被重置。关闭会话时恢复先前的根 logger 设置和由本包接管的异常钩子。

文件和控制台 I/O 在后台线程执行。支持单进程内的多个线程；多个进程不要各自对同一个文件执行轮转。Rich 不可用时，控制台回退为标准库输出。库自身的提示为英文，用户日志保留原文。

## 从 0.1.x 升级到 0.2.0

这是一次明确的接口和默认行为调整：

- 默认不再为每次运行创建时间戳文件，改为追加到固定路径。
- `log_file_override=...` 和 `log_filename=...` 改为 `log_file=...`，也可以作为第一个位置参数传入。
- `default_level=...` 改为 `level=...`。
- 裸文件名直接位于当前工作目录，不再自动放进 `log/`。
- 外部配置改用上面的简单 JSON 格式，旧 `handlers_templates` 配置需要迁移。
- 取消大段启动横幅和续写空行。需要启动提示时设置 `show_startup=True`。
- 旧日志文件不会自动移动或合并。要继续某个旧文件，请将其完整路径传给 `log_file`。

## 开发验证

```bash
python -m unittest discover -s tests -v
python -m build
```

示例：`python -m example.run_log --log-file log/example.log --level DEBUG`。默认追加，显式添加 `--mode w` 才会清空文件。

本项目使用 [MIT License](LICENSE)。
