如何将Python类的实例标记为已弃用并触发警告？

方法一：模块级__getattr__（推荐） #

Python 3.7及以上版本支持模块级的__getattr__函数，当外部访问模块中未定义的test属性时，自动触发警告并返回simulator实例：

import warnings

class Environment(object):
    def __init__(self, name, params):
        self.name = name
        self.params = params

# 定义新环境实例
sandbox = Environment('sandbox', {"url": "https://sandbox.example.com"})
simulator = Environment('simulator', {"url": "https://simulator.example.com"})  # 对应旧test环境
production = Environment('production', {"url": "https://prod.example.com"})

def __getattr__(name):
    if name == 'test':
        # stacklevel=2 让警告指向调用test的代码行，而非当前函数
        warnings.warn("'test' 环境已弃用，请使用 'simulator' 替代", DeprecationWarning, stacklevel=2)
        return simulator
    raise AttributeError(f"模块不存在属性 '{name}'")

优势 #

• 无需修改Environment类的核心逻辑，解耦兼容逻辑与业务代码
• 每次访问test都会触发警告，持续提醒开发者替换旧代码
• 对调用方完全透明，旧代码无需修改即可正常运行

方法二：代理对象（属性访问触发警告） #

如果需要仅在实际使用test的属性（如test.name、test.params）时触发警告，可以创建代理类包装simulator实例：

import warnings

class Environment(object):
    def __init__(self, name, params):
        self.name = name
        self.params = params

# 定义新环境实例
sandbox = Environment('sandbox', {"url": "https://sandbox.example.com"})
simulator = Environment('simulator', {"url": "https://simulator.example.com"})
production = Environment('production', {"url": "https://prod.example.com"})

class DeprecatedProxy:
    def __init__(self, target, warning_msg):
        self._target = target
        self._warning_msg = warning_msg

    def __getattr__(self, attr):
        warnings.warn(self._warning_msg, DeprecationWarning, stacklevel=2)
        return getattr(self._target, attr)

# 用代理对象替代直接赋值
test = DeprecatedProxy(simulator, "'test' 环境已弃用，请使用 'simulator' 替代")

适用场景 #

• 希望仅在实际使用test的属性时触发警告，而非单纯引用变量时
• 保持test的实例行为一致性，所有属性访问均转发至simulator

关键注意事项 #

• 使用DeprecationWarning：这是Python官方推荐的弃用警告类型
• 设置stacklevel=2：确保警告信息指向调用test的代码行，而非警告触发的内部逻辑，方便开发者定位
• 强制显示警告：可通过warnings.simplefilter('always', DeprecationWarning)确保警告始终被输出（默认情况下Python可能忽略部分警告）

内容的提问来源于stack exchange，提问作者Colin 't Hart