如何以Pythonic方式标记整个Python文件为已废弃？

直接触发模块级警告（最简单） #

在文件最顶部、所有代码之前添加以下代码，只要模块被导入就会触发废弃警告，一次性覆盖所有函数：

import warnings
warnings.warn(
    "此模块已废弃，请使用[你的新模块名称]替代",
    DeprecationWarning,
    stacklevel=2
)

• stacklevel=2 是关键：它会让警告信息指向导入该模块的代码行，而非模块内部的警告触发行，用户能直接看到自己哪里用了废弃模块。

按需触发警告（Python 3.7+） #

如果希望仅当用户实际调用旧模块的函数时才弹出警告，同时自动复用新模块的实现，可以用模块级__getattr__方法：

import warnings
from importlib import import_module

# 替换为你的新模块完整路径
_NEW_MODULE = "myapp.new_module"

def __getattr__(name):
    # 从新模块获取对应函数/对象
    new_module = import_module(_NEW_MODULE)
    target_obj = getattr(new_module, name)
    
    warnings.warn(
        f"模块{__name__}已废弃，{name}请从{_NEW_MODULE}导入",
        DeprecationWarning,
        stacklevel=2
    )
    return target_obj

# 可选：隐藏原模块的函数列表，避免用户通过dir()看到旧函数
__all__ = []

这种方式既保留了原模块的调用方式（用户不用改代码就能临时运行），又能精准提示废弃信息，还能无缝切换到新实现。

不推荐的方案说明 #

• 封装成类再标记：会强制用户修改调用方式（原本直接func()，现在要MyClass.func()或实例调用），破坏向后兼容性。
• 移到deprecated包：只是物理归类，没有主动警告机制，用户可能毫无察觉地继续使用废弃模块。

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