Python包中如何实现logging默认回退print且不干扰用户配置？

这确实是Python包开发中非常常见的痛点——既要让没配置logging的新手用户能看到关键的INFO级日志输出，又不能干扰已经显式配置了自定义日志规则的资深用户。我自己开发开源包时也踩过这个坑，分享几个经过实践验证的靠谱方案：

方案1：自动兜底配置（推荐首选） #

核心思路是仅在根日志未被用户配置时，才添加默认的日志处理器，这样既不会破坏用户的自定义设置，又能给新手提供开箱即用的日志输出。

在你的包的__init__.py中添加以下代码：

import logging
import sys

def _setup_default_logging():
    root_logger = logging.getLogger()
    # 检查根日志是否已有处理器，避免重复添加
    if not root_logger.handlers:
        # 创建默认的控制台处理器
        handler = logging.StreamHandler(sys.stdout)
        # 配置简洁的日志格式，也可以根据需求调整
        formatter = logging.Formatter(
            "%(asctime)s - %(name)s - %(levelname)s - %(message)s",
            datefmt="%Y-%m-%d %H:%M:%S"
        )
        handler.setFormatter(formatter)
        root_logger.addHandler(handler)
        # 默认开启INFO级别输出
        root_logger.setLevel(logging.INFO)

# 包被导入时自动执行兜底配置
_setup_default_logging()

之后在包的各个模块中，正常使用标准的logging写法即可：

# 模块内的代码
import logging
logger = logging.getLogger(__name__)

def func():
    logger.info("Calling func")

为什么这个方案靠谱？ #

• 如果用户已经自己配置了logging（比如添加了文件处理器、修改了日志级别、自定义了格式），根日志会存在已有的handlers，我们的兜底配置会直接跳过，完全不干扰用户的设置。
• 未配置logging的用户，导入包后会自动获得一个可用的控制台日志输出，能看到INFO及以上级别的日志。

方案2：给包日志器设置默认级别（配合方案1使用） #

为了更灵活地控制包内日志的输出级别，可以在模块内给当前日志器设置默认级别，但仅在日志器未被显式配置时生效：

logger = logging.getLogger(__name__)
# 仅当日志器未被用户设置过级别时，才启用默认INFO级别
if logger.level == logging.NOTSET:
    logger.setLevel(logging.INFO)

这样做的好处是：

• 如果用户给你的包单独设置了日志级别（比如logging.getLogger("your_package").setLevel(logging.WARNING)），这个设置会优先生效。
• 如果用户只配置了根日志的级别，包内日志器会继承根日志的级别，同时 fallback 到我们设置的INFO默认值。

方案3：提供显式的日志初始化函数（可选） #

如果希望给用户更多控制权，可以提供一个公开的setup_logging函数，让用户主动选择是否使用默认配置：

def setup_logging(level: int = logging.INFO, format_str: str = None):
    root_logger = logging.getLogger()
    if not root_logger.handlers:
        handler = logging.StreamHandler(sys.stdout)
        # 用户可以自定义日志格式
        formatter = logging.Formatter(
            format_str or "%(asctime)s - %(name)s - %(levelname)s - %(message)s"
        )
        handler.setFormatter(formatter)
        root_logger.addHandler(handler)
    root_logger.setLevel(level)

新手用户可以直接调用your_package.setup_logging()快速开启日志，而资深用户可以跳过这个函数，完全自定义自己的logging配置。

避坑提醒 #

• 不要直接调用logging.basicConfig()：这个函数只会在根日志没有handlers时生效，但如果用户之后想自己配置日志，会因为根日志已有handlers而无法通过basicConfig修改，灵活性很差。
• 优先使用环境变量控制级别：可以把默认级别改成从环境变量读取，比如：

  import os
  default_level = getattr(logging, os.getenv("YOUR_PACKAGE_LOG_LEVEL", "INFO").upper())
  

  这样用户不用修改代码，只需设置环境变量就能调整日志级别，非常方便。

内容的提问来源于stack exchange，提问作者Gere