如何创建不被SQLAlchemy注册的表子类以实现Flask向后兼容？

问题背景 #

在Flask+SQLAlchemy项目中调整了模型类的存放位置和导入路径后，为兼容旧代码需保留原路径导入能力，同时在有人使用旧路径时抛出警告。但直接子类化新模型的方式会触发SQLAlchemy重复注册错误：

sqlalchemy.exc.InvalidRequestError: One or more mappers failed to initialize - can't proceed with initialization of other mappers. Triggering mapper: 'mapped class Admin->admin'. Original exception was: Multiple classes found for path "TableModel" in the registry of this declarative base. Please use a fully module-qualified path.

解决方案 #

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

这种方式无需创建新模型子类，通过旧模块的__getattr__钩子拦截导入请求，抛出警告后直接返回新模型类，从根源避免SQLAlchemy注册冲突。

在旧模块（比如app/old_data.py）中写入以下代码：

import warnings
from app.data import TableModel as NewTableModel

def __getattr__(name):
    if name == "TableModel":
        warnings.warn(
            'TableModel 从 app.old_data 导入已废弃，请使用 app.data.TableModel 替代',
            DeprecationWarning,
            stacklevel=2
        )
        return NewTableModel
    raise AttributeError(f"模块 {__name__} 不存在属性 {name}")

当用户执行from app.old_data import TableModel时，Python会自动调用__getattr__，触发警告并返回新的TableModel类，完全复用新模型定义，不会产生任何SQLAlchemy注册冲突。

方法二：手动取消子类的SQLAlchemy注册 #

如果必须通过子类化实现，可在定义子类后手动从SQLAlchemy注册表中移除它，避免被当成新模型注册。

代码示例：

import warnings
from sqlalchemy import inspect
from app.data import TableModel as NewTableModel
from app.data import Base  # 替换为你项目中的DeclarativeBase类

class TableModel(NewTableModel):
    def __init__(self, *args, **kwargs):
        warnings.warn(
            '旧的TableModel已废弃，请使用NewTableModel替代',
            DeprecationWarning,
            stacklevel=2
        )
        super().__init__(*args, **kwargs)

# 从注册表中移除这个子类
inspect(TableModel).registry.unregister(TableModel)

注意：必须在模型初始化完成后立即执行unregister操作，确保SQLAlchemy不会将该子类纳入映射管理。但此方式会创建额外类对象，不如第一种方法简洁高效。

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