Jenkins-py/logging_conf.py

"""
logging_conf.py - 统一日志配置
对应原 Shell 中 echo + tee 的组合效果。
"""
import logging
import sys
from pathlib import Path
from typing import Optional


def setup_logging(
    level: int = logging.INFO,
    log_file: Optional[str] = None,
    console: bool = True,
) -> None:
    """
    配置根日志记录器。

    Args:
        level: 日志级别，例如 logging.DEBUG / logging.INFO
        log_file: 文件路径，如果提供则同时写入该文件（相当于 tee 效果）
        console: 是否输出到控制台（sys.stdout）
    """
    root = logging.getLogger()
    root.setLevel(level)

    # 清除已有 handlers，避免重复
    root.handlers.clear()

    formatter = logging.Formatter(
        "%(asctime)s [%(levelname)-8s] %(name)s: %(message)s",
        datefmt="%Y-%m-%d %H:%M:%S",
    )

    if console:
        console_handler = logging.StreamHandler(sys.stdout)
        console_handler.setLevel(level)
        console_handler.setFormatter(formatter)
        root.addHandler(console_handler)

    if log_file:
        log_path = Path(log_file)
        log_path.parent.mkdir(parents=True, exist_ok=True)
        file_handler = logging.FileHandler(str(log_path), encoding="utf-8")
        file_handler.setLevel(level)
        file_handler.setFormatter(formatter)
        root.addHandler(file_handler)

    # 减少第三方库的日志噪音
    logging.getLogger("paramiko").setLevel(logging.WARNING)
    logging.getLogger("ftplib").setLevel(logging.WARNING)


def get_logger(name: str) -> logging.Logger:
    """获取命名日志记录器，推荐使用 __name__ 作为参数"""
    return logging.getLogger(name)