如何在使用Python旧命名空间时触发弃用警告？

当然有办法！Python标准库的warnings模块完美适配这个需求，结合简单的导入技巧，既能维持向后兼容性，又能清晰提示用户迁移到新的命名空间。下面是几种实用的方案：

方案1：直接在旧路径导入时触发警告 #

如果你的旧路径（比如package/__init__.py）是直接从新命名空间导入并重命名对象，可以在导入逻辑前先抛出弃用警告。

举个例子，假设旧导入是from package import OldClass，新导入是from package.new_submodule import NewClass，那在旧的package/__init__.py里可以这么写：

import warnings

# 抛出弃用警告，stacklevel=2能让警告指向用户的导入代码，而非当前包内部的__init__.py
warnings.warn(
    "`from package import OldClass` 已弃用，请使用 `from package.new_submodule import NewClass`",
    DeprecationWarning,
    stacklevel=2
)

# 保持兼容的导入逻辑
from package.new_submodule import NewClass as OldClass

这里的stacklevel=2是关键——它会让Python在警告信息里显示用户代码中触发导入的那一行，而不是我们包内部的代码，用户能立刻定位到需要修改的地方。

方案2：用__getattr__实现懒加载式警告 #

如果你的包采用懒加载模式，或者不想在用户导入包时就触发警告（只在实际访问旧对象时提示），可以使用模块级别的__getattr__函数。这个函数会在用户访问模块中不存在的属性时被调用，我们可以在这里拦截旧名称，抛出警告后返回新对象。

比如在旧的package/__init__.py中：

import warnings
from package.new_namespace import (
    NewModule as _new_module,
    NewUtility as _new_utility
)

def __getattr__(name):
    if name == "old_module":
        warnings.warn(
            "`package.old_module` 已弃用，请使用 `package.new_namespace.NewModule`",
            DeprecationWarning,
            stacklevel=2
        )
        return _new_module
    elif name == "old_utility":
        warnings.warn(
            "`package.old_utility` 已弃用，请使用 `package.new_namespace.NewUtility`",
            DeprecationWarning,
            stacklevel=2
        )
        return _new_utility
    # 处理其他未知属性
    raise AttributeError(f"module 'package' has no attribute '{name}'")

这种方式的优势是：只有当用户实际使用旧名称时才会触发警告，不会在用户仅导入包时就弹出一堆提示，体验更友好。

方案3：针对整个旧模块的迁移 #

如果你有单独的旧模块文件（比如package/old_module.py），可以直接在这个旧模块的顶部添加警告，然后从新模块导入所有内容：

import warnings

warnings.warn(
    "`package.old_module` 已弃用，请使用 `package.new_module`",
    DeprecationWarning,
    stacklevel=2
)

# 导入新模块的所有内容，维持旧模块的API兼容
from package.new_module import *

让警告能被用户看到 #

默认情况下，Python会过滤掉DeprecationWarning（避免过多噪音），你可以在文档里告知用户，他们可以通过以下方式启用警告：

• 运行Python时加上-Wd参数：python -Wd your_script.py
• 在代码开头手动设置警告过滤器：

  import warnings
  warnings.simplefilter('always', DeprecationWarning)
  

这样用户就能及时收到弃用提示，逐步迁移到新的命名空间啦。

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