farlog 1.1.7__py3-none-any.whl

farlog/__init__.py

@@ -0,0 +1,3 @@
+from .core import configure, get_logger, getLogger
+
+__all__ = ["configure", "getLogger", "get_logger"]

farlog/core.py

@@ -0,0 +1,109 @@
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+from threading import Lock
+
+from loguru import logger
+
+_DEFAULT_FORMAT = (
+    "{time:YYYY-MM-DD HH:mm:ss.SSS} |{level:8}| "
+    "{name} : {module}:{line:4} | {extra[module_name]} | - {message}"
+)
+_DEFAULT_FORMAT_COLOR = (
+    "{time:YYYY-MM-DD HH:mm:ss.SSS} |<lvl>{level:8}</>| "
+    "{name} : {module}:{line:4} | <cyan>{extra[module_name]}</> | - <lvl>{message}</>"
+)
+_log_dir = Path("logs")
+_loggers = {}
+_lock = Lock()
+
+
+def _ensure_log_dir(log_dir: str | Path) -> Path:
+    path = Path(log_dir)
+    path.mkdir(parents=True, exist_ok=True)
+    return path
+
+
+def _add_file_handler(name: str, level: str, formatter: str) -> int:
+    return logger.add(
+        sink=_log_dir / f"{name}.log",
+        format=formatter,
+        filter=lambda record, _name=name: record["extra"].get("module_name") == _name,
+        level=level,
+        rotation="00:00",
+        compression="gz",
+        retention=7,
+        colorize=False,
+    )
+
+
+def configure(log_dir: str | Path = "logs") -> None:
+    """Explicitly configure console and aggregate file logging."""
+    global _log_dir
+
+    with _lock:
+        path = _ensure_log_dir(log_dir)
+        logger.configure(
+            handlers=[
+                {
+                    "sink": sys.stderr,
+                    "format": _DEFAULT_FORMAT_COLOR,
+                    "colorize": True,
+                    "level": "INFO",
+                },
+                {
+                    "sink": path / "all.log",
+                    "format": _DEFAULT_FORMAT,
+                    "colorize": False,
+                    "rotation": "00:00",
+                    "compression": "gz",
+                    "retention": 30,
+                    "level": "INFO",
+                },
+            ],
+            extra={"module_name": "-"},
+        )
+        _log_dir = path
+
+        for name, (level, formatter, _, bound_logger) in list(_loggers.items()):
+            handler_id = _add_file_handler(name, level, formatter)
+            _loggers[name] = (level, formatter, handler_id, bound_logger)
+
+
+def _validate_name(name: str) -> None:
+    if (
+        not isinstance(name, str)
+        or not name
+        or name in {".", ".."}
+        or Path(name).name != name
+        or "\0" in name
+    ):
+        raise ValueError("logger name must be a non-empty file name")
+
+
+def get_logger(
+    name: str = "default",
+    level: str = "INFO",
+    formatter: str | None = None,
+):
+    """Get a named logger with one rotating file handler."""
+    _validate_name(name)
+    selected_formatter = formatter or _DEFAULT_FORMAT
+
+    with _lock:
+        current = _loggers.get(name)
+        if current and current[:2] == (level, selected_formatter):
+            return current[3]
+
+        _ensure_log_dir(_log_dir)
+        handler_id = _add_file_handler(name, level, selected_formatter)
+        bound_logger = current[3] if current else logger.bind(module_name=name)
+        if current:
+            logger.remove(current[2])
+        _loggers[name] = (level, selected_formatter, handler_id, bound_logger)
+        return bound_logger
+
+
+# Backward-compatible alias
+getLogger = get_logger

farlog-1.1.7.dist-info/METADATA

@@ -0,0 +1,135 @@
+Metadata-Version: 2.4
+Name: farlog
+Version: 1.1.7
+Summary: Small Loguru helper for named rotating log files
+Author-email: 牛哥 <niuliangtao@qq.com>, farfarfun <farfarfun@qq.com>
+Maintainer-email: 牛哥 <niuliangtao@qq.com>, farfarfun <farfarfun@qq.com>
+License-Expression: MIT
+Project-URL: Organization, https://github.com/farfarfun
+Project-URL: Repository, https://github.com/farfarfun/nltlog
+Project-URL: Releases, https://github.com/farfarfun/nltlog/releases
+Keywords: logging,loguru,rotation
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: System :: Logging
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: loguru>=0.7.3
+Dynamic: license-file
+
+# farlog
+
+`farlog` 是一个轻量的 [Loguru](https://github.com/Delgan/loguru) 辅助库，用于按名称拆分日志文件，并提供开箱即用的按日轮转、压缩和保留策略。
+
+## 特性
+
+- 导入包时不创建目录、不写文件，也不修改 Loguru 的全局 handler
+- 每个 logger 名称对应一个独立日志文件
+- 日志按日轮转，历史文件自动使用 gzip 压缩
+- 可选生成聚合日志 `all.log`，同时统一控制台输出格式
+- 重复获取同名 logger 不会重复添加 handler
+- 兼容旧接口 `getLogger`
+
+## 环境要求
+
+- Python 3.9 或更高版本
+
+## 安装
+
+```bash
+pip install farlog
+```
+
+## 快速开始
+
+### 仅使用命名日志
+
+直接调用 `get_logger()` 会保留应用已有的 Loguru handler，并在默认的 `logs/` 目录中创建命名日志文件。
+
+```python
+from farlog import get_logger
+
+log = get_logger("worker")
+log.info("任务开始")
+```
+
+生成的文件：
+
+```text
+logs/
+└── worker.log
+```
+
+### 配置控制台和聚合日志
+
+需要统一控制台格式或生成 `all.log` 时，在应用启动阶段显式调用 `configure()`：
+
+```python
+from farlog import configure, get_logger
+
+configure("logs")
+
+log = get_logger("worker", level="DEBUG")
+log.debug("调试信息")
+log.info("任务开始")
+```
+
+生成的文件：
+
+```text
+logs/
+├── all.log
+└── worker.log
+```
+
+`configure()` 会替换 Loguru 的全局 handler。未绑定 `module_name` 的普通 Loguru 日志仍可正常输出，并在格式中显示为 `-`。
+
+## API
+
+### `configure(log_dir="logs")`
+
+配置彩色控制台输出和聚合日志，并设置后续命名日志使用的目录。
+
+- `log_dir`：日志目录，支持字符串或 `pathlib.Path`
+- `all.log`：记录 `INFO` 及以上级别，按日轮转，保留最近 30 个文件
+- 如果已经创建过命名 logger，其文件 handler 会切换到新目录
+
+### `get_logger(name="default", level="INFO", formatter=None)`
+
+获取带有独立文件 handler 的 Loguru logger。
+
+- `name`：logger 名称，同时作为日志文件名；只允许普通文件名，不允许传入路径
+- `level`：该命名日志文件的最低记录级别
+- `formatter`：可选的 Loguru 格式字符串
+- 命名日志按日轮转并压缩，保留最近 7 个文件
+- 重复调用会复用同名 logger；修改 `level` 或 `formatter` 时会替换旧文件 handler
+
+非法名称会抛出 `ValueError`：
+
+```python
+get_logger("../outside")  # ValueError
+```
+
+旧接口仍然可用：
+
+```python
+from farlog import getLogger
+
+log = getLogger("worker")
+```
+
+## 开发
+
+运行回归测试和静态检查：
+
+```bash
+python -m unittest discover -s tests -v
+ruff check .
+```
+
+## 许可证
+
+本项目使用 [MIT License](LICENSE)。

farlog-1.1.7.dist-info/RECORD

@@ -0,0 +1,7 @@
+farlog/__init__.py,sha256=eUmH2zadWHXX4pbjxBpYgPSSzInxp4ToQgC17Psr9aI,103
+farlog/core.py,sha256=oJf-mFNdBRRbRRvUh-1eZp1cGjV35weOqNVI6Wsry3M,3166
+farlog-1.1.7.dist-info/licenses/LICENSE,sha256=BvvS-yeQjeaYgHQW2Vh7Msedpzoc-r7mnjNCpqUUbgM,1066
+farlog-1.1.7.dist-info/METADATA,sha256=TNdNkC7t_v8My-wYGWg-wcvpg1m2yZtm9lFtseyqNko,3613
+farlog-1.1.7.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+farlog-1.1.7.dist-info/top_level.txt,sha256=gF4NFCRgZnlro-8kPMBsdk83hVzC-G5Fsn2h3AWubVA,7
+farlog-1.1.7.dist-info/RECORD,,

farlog-1.1.7.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

farlog-1.1.7.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 farfarfun
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

farlog-1.1.7.dist-info/top_level.txt

@@ -0,0 +1 @@
+farlog