zy-log 0.1.0__tar.gz

zy_log-0.1.0/LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) [2025] [yaoZhou]
+
+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.

zy_log-0.1.0/PKG-INFO

@@ -0,0 +1,113 @@
+Metadata-Version: 2.4
+Name: zy_log
+Version: 0.1.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: 一个为算法项目定制的、专业的、异步的日志系统
+
+[![PyPI Version](https://badge.fury.io/py/zy_log.svg)](https://badge.fury.io/py/zy_log) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+一个功能强大的 Python 日志包，专为计算密集型和算法项目设计。它通过异步 I/O 确保日志记录不会阻塞您的主计算线程，并使用 `rich` 提供美观的控制台输出和异常堆栈。
+
+## 核心功能
+
+* **异步非阻塞**: 所有日志 I/O (文件/控制台) 都在一个单独的后台线程中处理。
+* **Rich 集成**: 自动的控制台颜色、美观的格式化和清晰的异常堆栈追踪。
+* **动态配置**: 可通过参数或环境变量 (`LOG_LEVEL`) 轻松覆盖配置。
+* **致命错误处理**: 提供 `logger.error_and_raise()` 方法，在记录致命错误后立即抛出异常，实现“快速失败”(Fail-Fast)。
+
+## 安装
+
+```bash
+pip install zy_log
+```
+
+## 快速使用
+
+您只需要在您算法的**主入口文件** (`main.py`) 中初始化一次，然后在任何子模块中调用 `get_logger` 即可。
+
+### 1. 初始化 (在 `main.py` 中)
+
+这是最关键的一步。
+
+```python
+# main.py
+import zy_log
+import os
+import time
+from your_project import run_my_core_algo
+
+# --- 日志系统初始化 (仅一次) ---
+# 推荐：动态指定日志文件名，并设置环境变量
+log_filename = f"run_{time.strftime('%Y%m%d_%H%M%S')}.log"
+os.environ['LOG_LEVEL'] = 'INFO' # 生产环境
+# os.environ['LOG_LEVEL'] = 'DEBUG' # 调试时
+
+zy_log.setup_logging(log_file_override=log_filename)
+# --- 初始化完成 ---
+
+# 获取主模块的 logger
+logger = zy_log.get_logger(__name__)
+
+logger.info(f"算法启动，日志将记录到: {log_filename}")
+
+# 运行您的核心算法
+try:
+    run_my_core_algo()
+    logger.info("算法运行成功结束。")
+except Exception as e:
+    logger.critical(f"算法主流程意外崩溃: {e}", exc_info=True)
+
+```
+
+### 2. 在任意子模块中使用
+
+在您的任何算法子模块中：
+
+```python
+# your_project/core_algo.py
+import zy_log
+import time
+
+# [关键] 直接获取 logger，它已经被 main.py 配置好了
+logger = zy_log.get_logger(__name__)
+
+def run_my_core_algo():
+    
+    # 1. 记录正常流程 (Normal)
+    logger.info("开始加载数据模型...")
+    
+    # 2. 记录警告 (Warning)
+    logger.warning("检测到 5% 的缺失值，将使用均值填充。")
+    
+    # 3. 记录致命错误 (Error)
+    try:
+        if "关键数据" is None:
+            # 这会记录一个红色的 Error 日志，然后抛出 RuntimeError
+            logger.error_and_raise("关键数据为 None，算法无法继续！")
+            
+    except RuntimeError as e:
+        logger.error(f"算法因致命错误中断: {e}")
+        raise # 必须重新抛出，让上层知道
+
+```
+
+## 贡献
+
+欢迎提交 PR 或 Issue。
+
+## 许可证
+
+本项目使用 [MIT License](LICENSE) 授权。

zy_log-0.1.0/README.md

@@ -0,0 +1,96 @@
+# zy_log: 一个为算法项目定制的、专业的、异步的日志系统
+
+[![PyPI Version](https://badge.fury.io/py/zy_log.svg)](https://badge.fury.io/py/zy_log) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+一个功能强大的 Python 日志包，专为计算密集型和算法项目设计。它通过异步 I/O 确保日志记录不会阻塞您的主计算线程，并使用 `rich` 提供美观的控制台输出和异常堆栈。
+
+## 核心功能
+
+* **异步非阻塞**: 所有日志 I/O (文件/控制台) 都在一个单独的后台线程中处理。
+* **Rich 集成**: 自动的控制台颜色、美观的格式化和清晰的异常堆栈追踪。
+* **动态配置**: 可通过参数或环境变量 (`LOG_LEVEL`) 轻松覆盖配置。
+* **致命错误处理**: 提供 `logger.error_and_raise()` 方法，在记录致命错误后立即抛出异常，实现“快速失败”(Fail-Fast)。
+
+## 安装
+
+```bash
+pip install zy_log
+```
+
+## 快速使用
+
+您只需要在您算法的**主入口文件** (`main.py`) 中初始化一次，然后在任何子模块中调用 `get_logger` 即可。
+
+### 1. 初始化 (在 `main.py` 中)
+
+这是最关键的一步。
+
+```python
+# main.py
+import zy_log
+import os
+import time
+from your_project import run_my_core_algo
+
+# --- 日志系统初始化 (仅一次) ---
+# 推荐：动态指定日志文件名，并设置环境变量
+log_filename = f"run_{time.strftime('%Y%m%d_%H%M%S')}.log"
+os.environ['LOG_LEVEL'] = 'INFO' # 生产环境
+# os.environ['LOG_LEVEL'] = 'DEBUG' # 调试时
+
+zy_log.setup_logging(log_file_override=log_filename)
+# --- 初始化完成 ---
+
+# 获取主模块的 logger
+logger = zy_log.get_logger(__name__)
+
+logger.info(f"算法启动，日志将记录到: {log_filename}")
+
+# 运行您的核心算法
+try:
+    run_my_core_algo()
+    logger.info("算法运行成功结束。")
+except Exception as e:
+    logger.critical(f"算法主流程意外崩溃: {e}", exc_info=True)
+
+```
+
+### 2. 在任意子模块中使用
+
+在您的任何算法子模块中：
+
+```python
+# your_project/core_algo.py
+import zy_log
+import time
+
+# [关键] 直接获取 logger，它已经被 main.py 配置好了
+logger = zy_log.get_logger(__name__)
+
+def run_my_core_algo():
+    
+    # 1. 记录正常流程 (Normal)
+    logger.info("开始加载数据模型...")
+    
+    # 2. 记录警告 (Warning)
+    logger.warning("检测到 5% 的缺失值，将使用均值填充。")
+    
+    # 3. 记录致命错误 (Error)
+    try:
+        if "关键数据" is None:
+            # 这会记录一个红色的 Error 日志，然后抛出 RuntimeError
+            logger.error_and_raise("关键数据为 None，算法无法继续！")
+            
+    except RuntimeError as e:
+        logger.error(f"算法因致命错误中断: {e}")
+        raise # 必须重新抛出，让上层知道
+
+```
+
+## 贡献
+
+欢迎提交 PR 或 Issue。
+
+## 许可证
+
+本项目使用 [MIT License](LICENSE) 授权。

zy_log-0.1.0/pyproject.toml

@@ -0,0 +1,28 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "zy_log"
+version = "0.1.0" # 版本升级
+authors = [
+  { name="zy", email="zhoumuci77@gamil.com" },
+]
+description = "An advanced, asynchronous logging system for algorithmic projects."
+readme = "README.md"
+requires-python = ">=3.8"
+
+license = "MIT"
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Operating System :: OS Independent",
+    "Topic :: System :: Logging",
+]
+# 依赖项变更：
+dependencies = [
+    "rich>=13.0.0", # 替换 colorama
+]
+
+[project.urls]
+"Homepage" = "https://github.com/yaosterm/zy_log"
+"Bug Tracker" = "https://github.com/yaosterm/zy_log/issues"

zy_log-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

zy_log-0.1.0/zy_log/__init__.py

@@ -0,0 +1,42 @@
+"""
+zy_log: A professional, asynchronous logging system customized for algorithm projects.
+
+This package provides an advanced logging configuration interface (setup_logging) and one
+
+Customized Logger (get_logger), this Logger contains a special
+
+The 'error_and_raise' method is used to immediately interrupt the algorithm execution after recording an error.
+
+Core functions
+
+-setup_logging: Initialize the logging system.
+
+-get_logger: Obtain a configured Logger instance.
+
+For complete usage, please refer to the documentation strings of 'setup_logging' and 'get_logger'.
+
+:Author: yao zhou
+:Version: 0.1.0
+"""
+
+import logging
+from .core import setup_logging
+from .loggers import AlgorithmicLogger
+
+logging.setLoggerClass(AlgorithmicLogger)
+
+def get_logger(name: str) -> logging.Logger:
+    """
+    获取一个 Logger 实例。
+
+    因为我们已经调用了 logging.setLoggerClass()，
+    这个函数将自动返回一个 AlgorithmicLogger 实例。
+    """
+    return logging.getLogger(name)
+
+# 控制 'from zy_log import *' 的行为
+__all__ = [
+    "setup_logging",
+    "get_logger",
+    "AlgorithmicLogger"
+]

zy_log-0.1.0/zy_log/core.py

@@ -0,0 +1,158 @@
+import logging
+import logging.config
+import json
+import os
+import pkgutil
+import atexit
+from queue import Queue
+from logging.handlers import QueueHandler, QueueListener
+
+# 确保我们的自定义类被注册
+from . import loggers
+
+# rich 是一个必需的依赖，如果它不存在，我们应该在 setup.py/pyproject.toml 中处理
+try:
+    from rich.logging import RichHandler
+except ImportError:
+    print("错误: 'rich' 库未安装。请运行 'pip install rich'", flush=True)
+    # 使用一个基础的 StreamHandler 作为后备
+    from logging import StreamHandler as RichHandler
+
+# 用于存储 Listener，以便程序退出时安全停止
+_listener = None
+
+
+def setup_logging(
+        config_path=None,
+        default_level=logging.INFO,
+        env_key_level='LOG_LEVEL',
+        log_file_override=None
+):
+    """
+        配置异步、动态的日志系统。
+
+        这是一个功能完备的日志初始化函数，它会配置异步的 QueueListener，
+        使用 rich 进行控制台美化，并允许通过环境变量和参数进行动态覆盖。
+
+        :param config_path: (可选) 自定义 JSON/YAML 配置文件的路径。
+        :type config_path: str or None
+
+        :param default_level: (可选) 如果未找到配置，使用的默认日志级别。
+        :type default_level: int
+
+        :param env_key_level: (可选) 用于覆盖日志级别的环境变量名称。
+        :type env_key_level: str
+
+        :param log_file_override: (可选) 强制指定日志文件名，覆盖所有配置。
+        :type log_file_override: str or None
+
+        :return: 无
+        :rtype: None
+
+        :raises IOError: 如果配置文件路径存在但无法读取。
+
+        **用法示例 (Usage Example):**
+
+        .. code-block:: python
+
+            import zy_log
+            import os
+
+            # 1. 简单启动 (使用默认配置)
+            zy_log.setup_logging()
+
+            # 2. 动态文件名
+            log_file = f"run_{time.strftime('%Y%m%d')}.log"
+            zy_log.setup_logging(log_file_override=log_file)
+
+            # 3. 通过环境变量设置级别
+            os.environ['LOG_LEVEL'] = 'DEBUG'
+            zy_log.setup_logging()
+
+        """
+    global _listener
+
+    # 确保我们的 Logger 类被使用
+    logging.setLoggerClass(loggers.AlgorithmicLogger)
+
+    # 1. 加载基础配置 (从文件或默认)
+    config = None
+    if config_path and os.path.exists(config_path):
+        with open(config_path, 'r') as f:
+            config = json.load(f)
+    else:
+        try:
+            config_bytes = pkgutil.get_data(__name__, "config/default_config.json")
+            if config_bytes:
+                config = json.loads(config_bytes.decode('utf-8'))
+            else:
+                raise IOError("无法加载默认日志配置。")
+        except Exception as e:
+            logging.basicConfig(level=default_level)
+            logging.warning(f"加载日志配置失败: {e}。使用 basicConfig。")
+            return
+
+    # 2. 动态/环境变量覆盖
+
+    # 2.1. 覆盖日志级别
+    env_level = os.getenv(env_key_level)
+    final_console_level = env_level or config['handlers_templates']['console_rich']['level']
+
+    # 2.2. 覆盖文件路径
+    if log_file_override:
+        config['handlers_templates']['file']['filename'] = log_file_override
+
+    # 3. 实例化 Handlers
+    try:
+        # 3.1. 控制台 Handler (Rich)
+        console_handler = RichHandler(
+            level=final_console_level,
+            rich_tracebacks=config['handlers_templates']['console_rich'].get('rich_tracebacks', True),
+            tracebacks_show_locals=config['handlers_templates']['console_rich'].get('tracebacks_show_locals', True)
+        )
+
+        # 3.2. 文件 Handler (Rotating)
+        file_config = config['handlers_templates']['file']
+        file_formatter = logging.Formatter(
+            fmt=config['formatters']['standard_file']['format'],
+            datefmt=config['formatters']['standard_file']['datefmt']
+        )
+        file_handler = logging.handlers.RotatingFileHandler(
+            filename=file_config['filename'],
+            maxBytes=file_config['maxBytes'],
+            backupCount=file_config['backupCount'],
+            encoding=file_config['encoding']
+        )
+        file_handler.setLevel(file_config['level'])
+        file_handler.setFormatter(file_formatter)
+
+    except Exception as e:
+        logging.basicConfig(level=default_level)
+        logging.error(f"实例化 Handlers 失败: {e}。使用 basicConfig。")
+        return
+
+    # 4. [核心] 设置异步非阻塞 I/O
+    # 创建一个无限大小的队列
+    log_queue = Queue(-1)
+
+    # 创建 QueueHandler，这是 *唯一* 附加到根 Logger 的 Handler
+    # 它会立即将日志消息放入队列，主线程不会阻塞
+    queue_handler = QueueHandler(log_queue)
+
+    # 创建 QueueListener，它在 *单独的线程* 中运行
+    # 它监听 log_queue，并将消息分发给 *真正* 的 Handlers (console 和 file)
+    _listener = QueueListener(log_queue, console_handler, file_handler, respect_handler_level=True)
+
+    # 配置根 Logger
+    root_logger = logging.getLogger()
+    root_logger.setLevel(logging.DEBUG)  # 根 Logger 级别必须足够低
+    root_logger.handlers.clear()  # 清除任何现有的 handlers
+    root_logger.addHandler(queue_handler)  # 只添加队列 Handler
+
+    # 5. 启动
+    _listener.start()
+
+    # 注册一个退出处理程序，以确保在程序关闭时停止 Listener 线程
+    atexit.register(_listener.stop)
+
+    # print("异步日志系统已初始化。") # 调试

zy_log-0.1.0/zy_log/loggers.py

@@ -0,0 +1,26 @@
+import logging
+
+
+class AlgorithmicLogger(logging.Logger):
+    """
+    自定义 Logger 类，增加了用于算法的特定方法。
+    """
+    def __init__(self, name, level=logging.NOTSET):
+        super().__init__(name, level)
+
+    def error_and_raise(self, msg, *args, **kwargs):
+        """
+        记录一个 ERROR 级别的日志，然后立即抛出一个 RuntimeError。
+        这用于算法中不可恢复的致命错误。
+        """
+        # 1. 记录日志 (现在将由 rich 美观地打印 Traceback)
+        # 注意：为了让 rich 正确捕获异常上下文，我们最好在这里传递 exc_info
+        kwargs.setdefault('exc_info', True)
+        self.error(msg, *args, **kwargs)
+
+        # 2. 抛出异常
+        raise RuntimeError(msg)
+
+
+# 告诉 logging 模块，当调用 getLogger 时，使用我们的自定义类
+logging.setLoggerClass(AlgorithmicLogger)

zy_log-0.1.0/zy_log.egg-info/PKG-INFO

@@ -0,0 +1,113 @@
+Metadata-Version: 2.4
+Name: zy_log
+Version: 0.1.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: 一个为算法项目定制的、专业的、异步的日志系统
+
+[![PyPI Version](https://badge.fury.io/py/zy_log.svg)](https://badge.fury.io/py/zy_log) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+一个功能强大的 Python 日志包，专为计算密集型和算法项目设计。它通过异步 I/O 确保日志记录不会阻塞您的主计算线程，并使用 `rich` 提供美观的控制台输出和异常堆栈。
+
+## 核心功能
+
+* **异步非阻塞**: 所有日志 I/O (文件/控制台) 都在一个单独的后台线程中处理。
+* **Rich 集成**: 自动的控制台颜色、美观的格式化和清晰的异常堆栈追踪。
+* **动态配置**: 可通过参数或环境变量 (`LOG_LEVEL`) 轻松覆盖配置。
+* **致命错误处理**: 提供 `logger.error_and_raise()` 方法，在记录致命错误后立即抛出异常，实现“快速失败”(Fail-Fast)。
+
+## 安装
+
+```bash
+pip install zy_log
+```
+
+## 快速使用
+
+您只需要在您算法的**主入口文件** (`main.py`) 中初始化一次，然后在任何子模块中调用 `get_logger` 即可。
+
+### 1. 初始化 (在 `main.py` 中)
+
+这是最关键的一步。
+
+```python
+# main.py
+import zy_log
+import os
+import time
+from your_project import run_my_core_algo
+
+# --- 日志系统初始化 (仅一次) ---
+# 推荐：动态指定日志文件名，并设置环境变量
+log_filename = f"run_{time.strftime('%Y%m%d_%H%M%S')}.log"
+os.environ['LOG_LEVEL'] = 'INFO' # 生产环境
+# os.environ['LOG_LEVEL'] = 'DEBUG' # 调试时
+
+zy_log.setup_logging(log_file_override=log_filename)
+# --- 初始化完成 ---
+
+# 获取主模块的 logger
+logger = zy_log.get_logger(__name__)
+
+logger.info(f"算法启动，日志将记录到: {log_filename}")
+
+# 运行您的核心算法
+try:
+    run_my_core_algo()
+    logger.info("算法运行成功结束。")
+except Exception as e:
+    logger.critical(f"算法主流程意外崩溃: {e}", exc_info=True)
+
+```
+
+### 2. 在任意子模块中使用
+
+在您的任何算法子模块中：
+
+```python
+# your_project/core_algo.py
+import zy_log
+import time
+
+# [关键] 直接获取 logger，它已经被 main.py 配置好了
+logger = zy_log.get_logger(__name__)
+
+def run_my_core_algo():
+    
+    # 1. 记录正常流程 (Normal)
+    logger.info("开始加载数据模型...")
+    
+    # 2. 记录警告 (Warning)
+    logger.warning("检测到 5% 的缺失值，将使用均值填充。")
+    
+    # 3. 记录致命错误 (Error)
+    try:
+        if "关键数据" is None:
+            # 这会记录一个红色的 Error 日志，然后抛出 RuntimeError
+            logger.error_and_raise("关键数据为 None，算法无法继续！")
+            
+    except RuntimeError as e:
+        logger.error(f"算法因致命错误中断: {e}")
+        raise # 必须重新抛出，让上层知道
+
+```
+
+## 贡献
+
+欢迎提交 PR 或 Issue。
+
+## 许可证
+
+本项目使用 [MIT License](LICENSE) 授权。

zy_log-0.1.0/zy_log.egg-info/SOURCES.txt

@@ -0,0 +1,11 @@
+LICENSE
+README.md
+pyproject.toml
+zy_log/__init__.py
+zy_log/core.py
+zy_log/loggers.py
+zy_log.egg-info/PKG-INFO
+zy_log.egg-info/SOURCES.txt
+zy_log.egg-info/dependency_links.txt
+zy_log.egg-info/requires.txt
+zy_log.egg-info/top_level.txt

zy_log-0.1.0/zy_log.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

zy_log-0.1.0/zy_log.egg-info/requires.txt

@@ -0,0 +1 @@
+rich>=13.0.0

zy_log-0.1.0/zy_log.egg-info/top_level.txt

@@ -0,0 +1 @@
+zy_log