https://github.com/cainmagi/flask-sqlalchemy-compat
Support the compatibility between flask_sqlalchemy and flask_sqlalchemy_lite.
https://github.com/cainmagi/flask-sqlalchemy-compat
compatibility compatibility-layer flask flask-sqlalchemy flask-sqlalchemy-lite python python-library python3 sqlalchemy
Last synced: 6 months ago
JSON representation
Support the compatibility between flask_sqlalchemy and flask_sqlalchemy_lite.
- Host: GitHub
- URL: https://github.com/cainmagi/flask-sqlalchemy-compat
- Owner: cainmagi
- License: mit
- Created: 2024-12-09T19:34:23.000Z (7 months ago)
- Default Branch: main
- Last Pushed: 2024-12-17T18:56:02.000Z (6 months ago)
- Last Synced: 2024-12-28T10:15:10.994Z (6 months ago)
- Topics: compatibility, compatibility-layer, flask, flask-sqlalchemy, flask-sqlalchemy-lite, python, python-library, python3, sqlalchemy
- Language: Python
- Homepage: https://cainmagi.github.io/flask-sqlalchemy-compat/
- Size: 503 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: Changelog.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Security: SECURITY.md
Awesome Lists containing this project
README
# Flask SQLAlchemy Compat
Support the compatibility between `flask_sqlalchemy` and `flask_sqlalchemy_lite`. It allows users to make minimal changes when they need to migrate from either one of these two packages to each other.
The main motivation of this package is because `flask_sqlalchemy_lite` does not support `python<=3.8`. This package is designed for providing the similar usages when users have to make the `flask_sqlalchemy_lite` working with `python<=3.8` by using `flask_sqlalchemy`. In this case, users can get rid of the difficulty of maintaining two sets of codes.
> [!WARNING]
> This package is designed for `sqlalchemy>=2.0.0` only. If you are using an older version. You cannot use this package.
> [!WARNING]
> To make this package work with `python=3.7`, users should install an unofficial `flask-sqlalchemy` version.
## 1. Install
Intall the **latest released version** of this package by using the PyPI source:
``` sh
python -m pip install flask-sqlalchemy-compat
```
or use the following commands to install **the developing version** from the GitHub Source when you have already installed [Git :hammer:][tool-git]:
```sh
python -m pip install "flask-sqlalchemy-compat[dev] @ git+https://github.com/cainmagi/flask-sqlalchemy-compat.git"
```
> [!WARNING]
> To make this package work with `python=3.7`, users should install an unofficial `flask-sqlalchemy` version. See
>
> https://github.com/pallets-eco/flask-sqlalchemy/issues/1140#issuecomment-1577921154
>
> This unofficial version can be installed by:
> ```sh
> python -m pip install flask-sqlalchemy-compat[backends]
> ```
## 2. Usage
When you are using `flask-sqlalchemy-lite`, using the following codes will let your codes fall back to the compatible mode if `flask-sqlalchemy-lite` is not installed but `flask-sqlalchemy` is installed.
```python
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.")
```
The above codes will works no matter `flask_sqlalchemy_lite` or `flask_sqlalchemy` is installed.
Similarly, the following example is designed for the codes written with `flask_sqlalchemy`. The codes fall back to the compatible mode if `flask-sqlalchemy` is not installed but `flask-sqlalchemy-lite` is installed.
```python
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()
# Indeed, flask_sqlalchemy has a type hint issue until `3.1.x`.
# But it does not cause issues in run time. See
# 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.")
```
The magic happens if you run the first example with only `flask-sqlalchemy` installed and the second example with only `flask-sqlalchemy-lite` installed.
Compared to the above minimal examples, we also provided a `usage.py` file and example applications in the `examples/` folder. Check them to view more details.
> [!TIP]
> To run the demos in `examples`, you need to install the optional dependencies by
> ```sh
> python -m pip install flask-sqlalchemy-compat[example,backends]
> ```
## 3. Documentation
Check the documentation to find more details about the examples and APIs.
https://cainmagi.github.io/flask-sqlalchemy-compat/
## 4. Contributing
See [CONTRIBUTING.md :book:][link-contributing]
## 5. Changelog
See [Changelog.md :book:][link-changelog]
[tool-git]:https://git-scm.com/downloads
[link-contributing]:https://github.com/cainmagi/flask-sqlalchemy-compat/blob/main/CONTRIBUTING.md
[link-changelog]:https://github.com/cainmagi/flask-sqlalchemy-compat/blob/main/Changelog.md