Metadata-Version: 2.4
Name: fry-qt6-logger
Version: 0.1.0
Summary: PyQt6 多输出日志类与日志Widget：同时输出到 GUI 文本框与文件，并支持自动轮转。
Author: fanrenyi
License-Expression: MIT
Project-URL: Homepage, https://gitlab.com/fanrenyi33/fry_python_lib_d120_fry_qt6_logger
Project-URL: Source, https://gitlab.com/fanrenyi33/fry_python_lib_d120_fry_qt6_logger
Project-URL: Issues, https://gitlab.com/fanrenyi33/fry_python_lib_d120_fry_qt6_logger/-/issues
Keywords: pyqt6,qt6,logger,logging,widget,gui
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
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 :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Logging
Classifier: Environment :: X11 Applications :: Qt
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: PyQt6>=6.4.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-qt>=4.2; extra == "dev"
Requires-Dist: build>=1.0; extra == "dev"
Requires-Dist: twine>=4.0; extra == "dev"
Dynamic: license-file

# fry-qt6-logger

> PyQt6 多输出日志类与日志 Widget：**同时**输出到 GUI 文本框与日志文件，并支持日志文件按条数自动轮转。

[![Python](https://img.shields.io/badge/python-3.9%2B-blue.svg)](https://www.python.org/)
[![PyQt6](https://img.shields.io/badge/PyQt6-%E2%89%A56.4-green.svg)](https://pypi.org/project/PyQt6/)
[![License](https://img.shields.io/badge/license-MIT-yellow.svg)](LICENSE)

---

## 安装

```bash
pip install fry-qt6-logger
```

依赖会自动安装 `PyQt6`。Python ≥ 3.9。

---

## 两个核心类，按需取用

| 类                  | 用途                                                                |
| ------------------- | ------------------------------------------------------------------- |
| `FryLogger`         | **纯日志类**。可独立使用（仅写文件），也可附加任意支持 `append()` 的控件 |
| `FryLoggerWidget`   | **日志显示控件**。继承自 `QTextEdit`，自带颜色样式、右键菜单与导出功能   |

> 简单原则：**只要日志类，就用 `FryLogger`；要 GUI 显示，就用 `FryLoggerWidget`。**

---

## 快速上手

### 1. 只要日志类（无 GUI 也能跑）

```python
from fry_qt6_logger import FryLogger

logger = FryLogger(log_dir="logs", max_entries_per_file=1000)
logger.log_info("应用启动")
logger.log_success("数据加载完毕")
logger.log_warning("配置文件缺字段，已使用默认值")
logger.log_error("网络连接失败")
```

日志文件会写入 `logs/log_<时间戳>_0000.txt`，达到 `max_entries_per_file` 条后自动滚到下一个文件。

### 2. 要 GUI 日志控件

```python
import sys
from PyQt6.QtWidgets import QApplication, QMainWindow
from fry_qt6_logger import FryLoggerWidget

app = QApplication(sys.argv)
win = QMainWindow()
win.setWindowTitle("FryLoggerWidget Demo")

log_widget = FryLoggerWidget(log_dir="logs")
win.setCentralWidget(log_widget)

log_widget.log_info("我是普通信息（灰色）")
log_widget.log_success("我是成功（绿色）")
log_widget.log_warning("我是警告（橙色）")
log_widget.log_error("我是错误（红色）")
log_widget.log_important("我是重要（紫色）")
log_widget.log_group_begin("批处理开始")
log_widget.log_info("处理 1 / 3")
log_widget.log_info("处理 2 / 3")
log_widget.log_info("处理 3 / 3")
log_widget.log_group_end("批处理结束")

win.resize(900, 500)
win.show()
sys.exit(app.exec())
```

控件右键支持：清除日志、复制、全选、导出 TXT。

### 3. 把 `print` / 异常输出重定向到日志

```python
import sys
from fry_qt6_logger import FryLoggerWidget, StdoutRedirector, StderrRedirector

log_widget = FryLoggerWidget()
sys.stdout = StdoutRedirector(log_widget)
sys.stderr = StderrRedirector(log_widget)

print("现在 print 会出现在 GUI 日志里")
```

### 4. 用字符串选择级别

```python
log_widget.log_by_level("ERROR", "网络错误")      # 英文
log_widget.log_by_level("警告", "配置缺失")        # 中文
log_widget.log_by_level("success", "保存成功")    # 大小写不敏感
```

支持的级别别名见 [`docs/CORE_CONCEPTS.md`](docs/CORE_CONCEPTS.md)。

---

## 项目结构

```
fry-qt6-logger/
├── pyproject.toml          # 打包配置
├── README.md               # 你正在看的文件
├── LICENSE                 # MIT
├── docs/
│   └── CORE_CONCEPTS.md    # 核心关键点（推荐阅读）
├── examples/               # 可直接运行的示例
│   ├── 01_logger_only.py
│   ├── 02_widget_basic.py
│   ├── 03_widget_full_demo.py
│   ├── 04_redirect_stdio.py
│   └── 05_log_by_level.py
├── src/
│   └── fry_qt6_logger/     # 包源代码
│       ├── __init__.py
│       ├── logger.py       # FryLogger
│       ├── widget.py       # FryLoggerWidget
│       └── redirector.py   # Stdout/StderrRedirector
└── tests/                  # pytest 测试
    ├── test_logger.py
    └── test_widget.py
```

---

## 运行示例

```bash
# 1) 纯日志，不需要 Qt 显示
python examples/01_logger_only.py

# 2) 最简 GUI 例子
python examples/02_widget_basic.py

# 3) 完整 demo（含分组、级别切换、stdout 重定向）
python examples/03_widget_full_demo.py
```

---

## 跑测试

```bash
pip install -e ".[dev]"
pytest
```

- `tests/test_logger.py` 不需要 GUI，CI 环境也能跑。
- `tests/test_widget.py` 依赖 `pytest-qt`，需要可创建 `QApplication` 的环境。

---

## 核心关键点速读

完整版见 [`docs/CORE_CONCEPTS.md`](docs/CORE_CONCEPTS.md)。

- **GUI 与文件双输出**：`_log()` 是唯一的入口，分别写 widget HTML 与 `logging.FileHandler`。
- **自动轮转**：每个文件最多 `max_entries_per_file` 条，超过自动开新文件，文件名带递增序号。
- **解耦**：`FryLogger` 通过 duck-typing 的 `log_widget.append(html)` 与控件耦合，所以连 `None` 也可以传，无 GUI 场景照样工作。
- **级别名兼容**：中文（信息 / 警告 / 错误 / 成功 / 重要 / 组开始 / 组结束）与英文别名（INFO / WARNING / ERROR / SUCCESS / IMPORTANT / GROUP\_BEGIN / GROUP\_END / OK / FAIL …）。
- **彩色 HTML 渲染**：通过 `QTextEdit.append` 写 HTML，时间戳灰色、消息按级别上色。
- **Widget 自带菜单**：清除 / 复制 / 全选 / 导出 TXT，无需额外接线。
- **logger 实例唯一名**：内部用 `id(self)` 当 logger 名，多个 `FryLogger` 互不串扰。

---

## License

[MIT](LICENSE)
