# Flask SQLAlchemy Compat
<p><img alt="Banner" src="https://repository-images.githubusercontent.com/900959960/5fa49b35-0f23-4e6d-9c00-b57ff6e513fd"></p>
<p align="center">
<a href="https://github.com/cainmagi/flask-sqlalchemy-compat/releases/latest"><img alt="GitHub release (latest SemVer)" src="https://img.shields.io/github/v/release/cainmagi/flask-sqlalchemy-compat?logo=github&sort=semver&style=flat-square"></a>
<a href="https://github.com/cainmagi/flask-sqlalchemy-compat/releases"><img alt="GitHub all releases" src="https://img.shields.io/github/downloads/cainmagi/flask-sqlalchemy-compat/total?logo=github&style=flat-square"></a>
<a href="https://github.com/cainmagi/flask-sqlalchemy-compat/blob/main/LICENSE"><img alt="GitHub" src="https://img.shields.io/github/license/cainmagi/flask-sqlalchemy-compat?style=flat-square&logo=opensourceinitiative&logoColor=white"></a>
<a href="https://pypi.org/project/flask-sqlalchemy-compat"><img alt="PyPI - Downloads" src="https://img.shields.io/pypi/dm/flask-sqlalchemy-compat?style=flat-square&logo=pypi&logoColor=white&label=pypi"/></a>
</p>
<p align="center">
<a href="https://github.com/cainmagi/flask-sqlalchemy-compat/actions/workflows/python-package.yml"><img alt="GitHub Actions (Build)" src="https://img.shields.io/github/actions/workflow/status/cainmagi/flask-sqlalchemy-compat/python-package.yml?style=flat-square&logo=githubactions&logoColor=white&label=build"></a>
<a href="https://github.com/cainmagi/flask-sqlalchemy-compat/actions/workflows/python-publish.yml"><img alt="GitHub Actions (Release)" src="https://img.shields.io/github/actions/workflow/status/cainmagi/flask-sqlalchemy-compat/python-publish.yml?style=flat-square&logo=githubactions&logoColor=white&label=release"></a>
</p>
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
Raw data
{
"_id": null,
"home_page": null,
"name": "Flask-SQLAlchemy-compat",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "Yuchen Jin <cainmagi@gmail.com>",
"keywords": "python, python3, python-library, flask, sqlalchemy, flask-sqlalchemy, flask-sqlalchemy-lite, compatibility, compatibility-layer",
"author": null,
"author_email": "Yuchen Jin <cainmagi@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/4c/f3/caaef4fc198e3b2ac5c00ef07dd3a67addf8c8ee301873fef4298501c6ae/flask_sqlalchemy_compat-0.2.1.tar.gz",
"platform": null,
"description": "# Flask SQLAlchemy Compat\n\n<p><img alt=\"Banner\" src=\"https://repository-images.githubusercontent.com/900959960/5fa49b35-0f23-4e6d-9c00-b57ff6e513fd\"></p>\n\n<p align=\"center\">\n <a href=\"https://github.com/cainmagi/flask-sqlalchemy-compat/releases/latest\"><img alt=\"GitHub release (latest SemVer)\" src=\"https://img.shields.io/github/v/release/cainmagi/flask-sqlalchemy-compat?logo=github&sort=semver&style=flat-square\"></a>\n <a href=\"https://github.com/cainmagi/flask-sqlalchemy-compat/releases\"><img alt=\"GitHub all releases\" src=\"https://img.shields.io/github/downloads/cainmagi/flask-sqlalchemy-compat/total?logo=github&style=flat-square\"></a>\n <a href=\"https://github.com/cainmagi/flask-sqlalchemy-compat/blob/main/LICENSE\"><img alt=\"GitHub\" src=\"https://img.shields.io/github/license/cainmagi/flask-sqlalchemy-compat?style=flat-square&logo=opensourceinitiative&logoColor=white\"></a>\n <a href=\"https://pypi.org/project/flask-sqlalchemy-compat\"><img alt=\"PyPI - Downloads\" src=\"https://img.shields.io/pypi/dm/flask-sqlalchemy-compat?style=flat-square&logo=pypi&logoColor=white&label=pypi\"/></a>\n</p>\n<p align=\"center\">\n <a href=\"https://github.com/cainmagi/flask-sqlalchemy-compat/actions/workflows/python-package.yml\"><img alt=\"GitHub Actions (Build)\" src=\"https://img.shields.io/github/actions/workflow/status/cainmagi/flask-sqlalchemy-compat/python-package.yml?style=flat-square&logo=githubactions&logoColor=white&label=build\"></a>\n <a href=\"https://github.com/cainmagi/flask-sqlalchemy-compat/actions/workflows/python-publish.yml\"><img alt=\"GitHub Actions (Release)\" src=\"https://img.shields.io/github/actions/workflow/status/cainmagi/flask-sqlalchemy-compat/python-publish.yml?style=flat-square&logo=githubactions&logoColor=white&label=release\"></a>\n</p>\n\nSupport 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.\n\nThe 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.\n\n> [!WARNING]\n> This package is designed for `sqlalchemy>=2.0.0` only. If you are using an older version. You cannot use this package.\n\n> [!WARNING]\n> To make this package work with `python=3.7`, users should install an unofficial `flask-sqlalchemy` version.\n\n## 1. Install\n\nIntall the **latest released version** of this package by using the PyPI source:\n\n``` sh\npython -m pip install flask-sqlalchemy-compat\n```\n\nor use the following commands to install **the developing version** from the GitHub Source when you have already installed [Git :hammer:][tool-git]:\n\n```sh\npython -m pip install \"flask-sqlalchemy-compat[dev] @ git+https://github.com/cainmagi/flask-sqlalchemy-compat.git\"\n```\n\n> [!WARNING]\n> To make this package work with `python=3.7`, users should install an unofficial `flask-sqlalchemy` version. See\n>\n> https://github.com/pallets-eco/flask-sqlalchemy/issues/1140#issuecomment-1577921154\n>\n> This unofficial version can be installed by:\n> ```sh\n> python -m pip install flask-sqlalchemy-compat[backends]\n> ```\n\n## 2. Usage\n\nWhen 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.\n\n```python\nimport sqlalchemy as sa\nimport sqlalchemy.orm as sa_orm\nimport flask_sqlalchemy_compat as fsc\n\n\nclass _Base(sa_orm.DeclarativeBase): ...\n\n\ndb, Base = fsc.get_flask_sqlalchemy_lite(_Base)\n\n\nclass NewModel(Base):\n __tablename__ = \"new_model\"\n\n id: sa_orm.Mapped[int] = sa_orm.mapped_column(primary_key=True)\n name: sa_orm.Mapped[str] = sa_orm.mapped_column()\n\n\nif __name__ == \"__main__\":\n import os\n import flask\n\n app = flask.Flask(__name__, instance_path=os.path.abspath(\"./instance\"))\n app.config.update({\"SQLALCHEMY_ENGINES\": {\"default\": \"sqlite:///main.db\"}})\n db.init_app(app)\n\n with app.app_context():\n Base.metadata.create_all(db.engine)\n\n db.session.add(NewModel(name=\"new\"))\n db.session.commit()\n\n model = db.session.scalar(sa.select(NewModel))\n print(model.id, model.name) if model is not None else print(\"NOT FOUND.\")\n```\n\nThe above codes will works no matter `flask_sqlalchemy_lite` or `flask_sqlalchemy` is installed.\n\nSimilarly, 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.\n\n```python\nimport sqlalchemy as sa\nimport sqlalchemy.orm as sa_orm\nimport flask_sqlalchemy_compat as fsc\n\n\nclass _Base(sa_orm.DeclarativeBase): ...\n\n\ndb = fsc.get_flask_sqlalchemy(_Base)\n\n\nclass NewModel(db.Model):\n id: sa_orm.Mapped[int] = sa_orm.mapped_column(primary_key=True)\n name: sa_orm.Mapped[str] = sa_orm.mapped_column()\n\n\nif __name__ == \"__main__\":\n import os\n import flask\n\n app = flask.Flask(__name__, instance_path=os.path.abspath(\"./instance\"))\n app.config.update({\"SQLALCHEMY_DATABASE_URI\": \"sqlite:///main.db\"})\n db.init_app(app)\n\n with app.app_context():\n db.create_all()\n\n # Indeed, flask_sqlalchemy has a type hint issue until `3.1.x`.\n # But it does not cause issues in run time. See\n # https://github.com/pallets-eco/flask-sqlalchemy/issues/1312\n db.session.add(NewModel(name=\"new\"))\n db.session.commit()\n\n model = db.session.scalar(sa.select(NewModel))\n print(model.id, model.name) if model is not None else print(\"NOT FOUND.\")\n```\n\nThe magic happens if you run the first example with only `flask-sqlalchemy` installed and the second example with only `flask-sqlalchemy-lite` installed.\n\nCompared 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.\n\n> [!TIP]\n> To run the demos in `examples`, you need to install the optional dependencies by\n> ```sh\n> python -m pip install flask-sqlalchemy-compat[example,backends]\n> ```\n\n## 3. Documentation\n\nCheck the documentation to find more details about the examples and APIs.\n\nhttps://cainmagi.github.io/flask-sqlalchemy-compat/\n\n## 4. Contributing\n\nSee [CONTRIBUTING.md :book:][link-contributing]\n\n## 5. Changelog\n\nSee [Changelog.md :book:][link-changelog]\n\n[tool-git]:https://git-scm.com/downloads\n\n[link-contributing]:https://github.com/cainmagi/flask-sqlalchemy-compat/blob/main/CONTRIBUTING.md\n[link-changelog]:https://github.com/cainmagi/flask-sqlalchemy-compat/blob/main/Changelog.md\n",
"bugtrack_url": null,
"license": "MIT License",
"summary": "Support the compatibility between Flask-SQLAlchemy and Flask-SQLAlchemy-Lite.",
"version": "0.2.1",
"project_urls": {
"Changelog": "https://github.com/cainmagi/flask-sqlalchemy-compat/blob/main/Changelog.md",
"Documentation": "https://cainmagi.github.io/flask-sqlalchemy-compat/",
"Homepage": "https://github.com/cainmagi/flask-sqlalchemy-compat",
"Issues": "https://github.com/cainmagi/flask-sqlalchemy-compat/issues",
"Repository": "https://github.com/cainmagi/flask-sqlalchemy-compat.git"
},
"split_keywords": [
"python",
" python3",
" python-library",
" flask",
" sqlalchemy",
" flask-sqlalchemy",
" flask-sqlalchemy-lite",
" compatibility",
" compatibility-layer"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "79db14522c6a0316f7cbdaf2a57a99027d7fd9b481d29e8f5b4bb04a48a624fe",
"md5": "d907d4c68fe753473dd06347f86d9f08",
"sha256": "504284039aa026c7ee4f050fd746635c9610ee99461fc17d31c7c93837ad9b9c"
},
"downloads": -1,
"filename": "Flask_SQLAlchemy_compat-0.2.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "d907d4c68fe753473dd06347f86d9f08",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 29215,
"upload_time": "2024-12-17T18:56:40",
"upload_time_iso_8601": "2024-12-17T18:56:40.753608Z",
"url": "https://files.pythonhosted.org/packages/79/db/14522c6a0316f7cbdaf2a57a99027d7fd9b481d29e8f5b4bb04a48a624fe/Flask_SQLAlchemy_compat-0.2.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "4cf3caaef4fc198e3b2ac5c00ef07dd3a67addf8c8ee301873fef4298501c6ae",
"md5": "14cbfd60d8ed83334e1c148d88e2ce1d",
"sha256": "a38c1366bc0d01f2b18807886d22be153278ad680805e6d5b21b1c514f16ec09"
},
"downloads": -1,
"filename": "flask_sqlalchemy_compat-0.2.1.tar.gz",
"has_sig": false,
"md5_digest": "14cbfd60d8ed83334e1c148d88e2ce1d",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 149209,
"upload_time": "2024-12-17T18:56:49",
"upload_time_iso_8601": "2024-12-17T18:56:49.451818Z",
"url": "https://files.pythonhosted.org/packages/4c/f3/caaef4fc198e3b2ac5c00ef07dd3a67addf8c8ee301873fef4298501c6ae/flask_sqlalchemy_compat-0.2.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-12-17 18:56:49",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "cainmagi",
"github_project": "flask-sqlalchemy-compat",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "flask",
"specs": []
},
{
"name": "sqlalchemy",
"specs": [
[
">=",
"2.0.31"
]
]
},
{
"name": "sqlalchemy",
"specs": [
[
">=",
"2.0.16"
]
]
},
{
"name": "sqlalchemy",
"specs": [
[
">=",
"2.0.0"
]
]
},
{
"name": "werkzeug",
"specs": []
},
{
"name": "typing-extensions",
"specs": [
[
">=",
"4.1.0"
]
]
}
],
"lcname": "flask-sqlalchemy-compat"
}
JSON
