简介

本项目提供了针对flask_sqlalchemy和flask_sqlalchemy_lite的兼容性支持。藉此以最小的修改，实现从其中之一向另一包的相互迁移。

适用场景如下：

令使用flask_sqlitealchemy_lite的代码支持到Python 3.7~3.8：

设计此包的主要目的，是因为flask_sqlalchemy_lite不支持python<=3.8。此包在python<=3.8时，透过flask_sqlalchemy实现了类似flask_sqlalchemy_lite的接口、并提供了相似的用法。因此，当用户需要兼容到低版本时，此包免去了维护两套代码的麻烦。
在使用flask_sqlalchemy_lite时，仍需使用flask_sqlalchemy的API：

相比flask_sqlalchemy_lite，历史更久的flask_sqlalchemy支持更多的功能。由于这些功能大多用来撰写老旧风格的代码，在flask_sqlalchemy_lite就不再得到支持。然而，若用户想要从flask_sqlalchemy迁移到flask_sqlalchemy_lite，又不愿修改过多的代码，此包就可以作为一个可用方案。
在Python 3.7的环境下，仍需使用sqlalchemy>=2.0.0提供的sa.orm.DeclarativeBase功能：

SQLAlchemy 2代码风格提供了sa.orm.DeclarativeBase和sa.orm.Mapped。这些用法本身是支持Python 3.7的。然而，flask_sqlalchemy对Python 3.7支持的最高版本仅到3.0.5，并且不支持DeclarativeBase的功能。此项目提供了一个flask_sqlalchemy的兼容版本，允许用户在Python 3.7的前提下，使用DeclarativeBase。

用法

Flask SQLAlchemy Lite
Flask SQLAlchemy

当你主要使用flask_sqlalchemy_lite时，以下代码可以帮助你的代码，在flask_sqlalchemy_lite未安装、而flask_sqlalchemy又安装了的情况下，退到兼容模式。

use_flask_sqlalchemy_lite_style.py
import sqlalchemy as sa
import sqlalchemy.orm as sa_orm
import flask_sqlalchemy_compat as fsc


class _Base(sa_orm.DeclarativeBase): ...


db, Base = fsc.get_flask_sqlalchemy_lite(_Base)


class NewModel(Base):
    __tablename__ = "new_model"

    id: sa_orm.Mapped[int] = sa_orm.mapped_column(primary_key=True)
    name: sa_orm.Mapped[str] = sa_orm.mapped_column()


if __name__ == "__main__":
    import os
    import flask

    app = flask.Flask(__name__, instance_path=os.path.abspath("./instance"))
    app.config.update({"SQLALCHEMY_ENGINES": {"default": "sqlite:///main.db"}})
    db.init_app(app)

    with app.app_context():
        Base.metadata.create_all(db.engine)

        db.session.add(NewModel(name="new"))
        db.session.commit()

        model = db.session.scalar(sa.select(NewModel))
        print(model.id, model.name) if model is not None else print("NOT FOUND.")

这意味着，只要你安装了flask_sqlalchemy，即使你没有安装flask_sqlalchemy_lite，以上代码仍然能正常工作。

类似地，下例则是为flask_sqlalchemy所写。其会在flask-sqlalchemy未安装、但flask-sqlalchemy_lite已安装时，退到兼容模式。

use_flask_sqlalchemy_style.py
import sqlalchemy as sa
import sqlalchemy.orm as sa_orm
import flask_sqlalchemy_compat as fsc


class _Base(sa_orm.DeclarativeBase): ...


db = fsc.get_flask_sqlalchemy(_Base)


class NewModel(db.Model):
    id: sa_orm.Mapped[int] = sa_orm.mapped_column(primary_key=True)
    name: sa_orm.Mapped[str] = sa_orm.mapped_column()


if __name__ == "__main__":
    import os
    import flask

    app = flask.Flask(__name__, instance_path=os.path.abspath("./instance"))
    app.config.update({"SQLALCHEMY_DATABASE_URI": "sqlite:///main.db"})
    db.init_app(app)

    with app.app_context():
        db.create_all()

        # 诚然，flask-sqlalchemy直到`3.1.x`、还存在类型标记错误。
        # 但这并不妨碍运行时的表现。参见
        # https://github.com/pallets-eco/flask-sqlalchemy/issues/1312
        db.session.add(NewModel(name="new"))
        db.session.commit()

        model = db.session.scalar(sa.select(NewModel))
        print(model.id, model.name) if model is not None else print("NOT FOUND.")