Merge pull request #15 from pallets-eco/examples

add examples

examples/blog/.flaskenv

@@ -0,0 +1 @@
+FLASK_APP=flaskr

examples/blog/.gitignore

@@ -0,0 +1,5 @@
+.venv/
+__pycache__/
+.coverage
+htmlcov/
+instance/

examples/blog/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Pallets
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

examples/blog/README.md

@@ -0,0 +1,54 @@
+# Flask Tutorial App
+
+The basic blog app built in the Flask [tutorial]. Modified to use
+Flask-SQLAlchemy-Lite and Flask-Alembic.
+
+[tutorial]: https://flask.palletsprojects.com/tutorial/
+
+
+## Install
+
+Clone the repository and move into the project folder:
+
+```
+$ git clone https://github.com/pallets-eco/flask-sqlalchemy-lite
+$ cd flask-sqlalchemy-lite/examples/blog
+```
+
+Create a virtualenv and activate it:
+
+```
+$ python3 -m venv .venv
+$ . .venv/bin/activate
+```
+
+Or on Windows:
+
+```
+$ py -m venv .venv
+$ .venv\Scripts\activate
+```
+
+Install the project and its dev dependencies:
+
+```
+$ pip install -r requirements/dev.txt && pip install -e .
+```
+
+## Run
+
+```
+$ flask db upgrade
+$ flask run --debug
+```
+
+Open <http://127.0.0.1:5000> in a browser.
+
+
+## Test
+
+```
+$ coverage run -m pytest
+$ coverage report
+$ coverage html  # open htmlcov/index.html in a browser
+```

examples/blog/pyproject.toml

@@ -0,0 +1,35 @@
+[project]
+name = "flaskr"
+version = "1.0.0"
+description = "The basic blog app built in the Flask tutorial."
+readme = "README.md"
+license = {file = "LICENSE.txt"}
+maintainers = [{name = "Pallets", email = "[email protected]"}]
+classifiers = ["Private :: Do Not Upload"]
+dependencies = [
+    "flask",
+    "flask-alembic",
+    "flask-sqlalchemy-lite",
+]
+
+[build-system]
+requires = ["flit_core<4"]
+build-backend = "flit_core.buildapi"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+filterwarnings = ["error"]
+
+[tool.coverage.run]
+source = ["flaskr", "tests"]
+branch = true
+
+[tool.mypy]
+files = ["src/flaskr", "tests"]
+show_error_codes = true
+pretty = true
+strict = true
+
+[tool.pyright]
+include = ["src/flaskr", "tests"]
+typeCheckingMode = "basic"

examples/blog/requirements/base.txt

@@ -0,0 +1,43 @@
+# This file was autogenerated by uv via the following command:
+#    uv pip compile ../pyproject.toml -o base.txt
+alembic==1.14.0
+    # via flask-alembic
+asgiref==3.8.1
+    # via flask
+blinker==1.9.0
+    # via flask
+click==8.1.7
+    # via flask
+flask==3.0.3
+    # via
+    #   flaskr (../pyproject.toml)
+    #   flask-alembic
+    #   flask-sqlalchemy-lite
+flask-alembic==3.1.1
+    # via flaskr (../pyproject.toml)
+flask-sqlalchemy-lite==0.1.0
+    # via flaskr (../pyproject.toml)
+greenlet==3.1.1
+    # via sqlalchemy
+itsdangerous==2.2.0
+    # via flask
+jinja2==3.1.4
+    # via flask
+mako==1.3.6
+    # via alembic
+markupsafe==3.0.2
+    # via
+    #   jinja2
+    #   mako
+    #   werkzeug
+sqlalchemy==2.0.36
+    # via
+    #   alembic
+    #   flask-alembic
+    #   flask-sqlalchemy-lite
+typing-extensions==4.12.2
+    # via
+    #   alembic
+    #   sqlalchemy
+werkzeug==3.1.3
+    # via flask

examples/blog/requirements/dev.in

@@ -0,0 +1,7 @@
+-r base.txt
+coverage
+mypy
+pytest
+python-dotenv
+sqlalchemy-utils
+watchdog

examples/blog/requirements/dev.txt

@@ -0,0 +1,83 @@
+# This file was autogenerated by uv via the following command:
+#    uv pip compile dev.in -o dev.txt
+alembic==1.14.0
+    # via
+    #   -r base.txt
+    #   flask-alembic
+asgiref==3.8.1
+    # via
+    #   -r base.txt
+    #   flask
+blinker==1.9.0
+    # via
+    #   -r base.txt
+    #   flask
+click==8.1.7
+    # via
+    #   -r base.txt
+    #   flask
+coverage==7.6.4
+    # via -r dev.in
+flask==3.0.3
+    # via
+    #   -r base.txt
+    #   flask-alembic
+    #   flask-sqlalchemy-lite
+flask-alembic==3.1.1
+    # via -r base.txt
+flask-sqlalchemy-lite==0.1.0
+    # via -r base.txt
+greenlet==3.1.1
+    # via
+    #   -r base.txt
+    #   sqlalchemy
+iniconfig==2.0.0
+    # via pytest
+itsdangerous==2.2.0
+    # via
+    #   -r base.txt
+    #   flask
+jinja2==3.1.4
+    # via
+    #   -r base.txt
+    #   flask
+mako==1.3.6
+    # via
+    #   -r base.txt
+    #   alembic
+markupsafe==3.0.2
+    # via
+    #   -r base.txt
+    #   jinja2
+    #   mako
+    #   werkzeug
+mypy==1.13.0
+    # via -r dev.in
+mypy-extensions==1.0.0
+    # via mypy
+packaging==24.2
+    # via pytest
+pluggy==1.5.0
+    # via pytest
+pytest==8.3.3
+    # via -r dev.in
+python-dotenv==1.0.1
+    # via -r dev.in
+sqlalchemy==2.0.36
+    # via
+    #   -r base.txt
+    #   alembic
+    #   flask-alembic
+    #   flask-sqlalchemy-lite
+typing-extensions==4.12.2
+    # via
+    #   -r base.txt
+    #   alembic
+    #   mypy
+    #   sqlalchemy
+watchdog==6.0.0
+    # via -r dev.in
+werkzeug==3.1.3
+    # via
+    #   -r base.txt
+    #   flask

examples/blog/src/flaskr/__init__.py

@@ -0,0 +1,64 @@
+from __future__ import annotations
+
+import typing as t
+
+import sqlalchemy as sa
+from flask import Flask
+from flask_alembic import Alembic
+from sqlalchemy import orm
+
+from flask_sqlalchemy_lite import SQLAlchemy
+
+
+class Model(orm.DeclarativeBase):
+    metadata: t.ClassVar[sa.MetaData] = sa.MetaData(
+        naming_convention={
+            "ix": "ix_%(column_0_label)s",
+            "uq": "uq_%(table_name)s_%(column_0_name)s",
+            "ck": "ck_%(table_name)s_%(constraint_name)s",
+            "fk": "fk_%(table_name)s_%(column_0_name)s_%(referred_table_name)s",
+            "pk": "pk_%(table_name)s",
+        }
+    )
+
+
+db: SQLAlchemy = SQLAlchemy()
+alembic: Alembic = Alembic(metadatas=Model.metadata)
+
+
+def create_app(test_config: dict[str, t.Any] | None = None) -> Flask:
+    """Create and configure an instance of the Flask application."""
+    app = Flask(__name__)
+    app.config |= {
+        # a default secret that should be overridden by instance config
+        "SECRET_KEY": "dev",
+        # store the database in the instance folder
+        "SQLALCHEMY_ENGINES": {"default": "sqlite:///blog.sqlite"},
+    }
+
+    if test_config is None:  # pragma: no cover
+        # load config from env vars when not testing
+        app.config.from_prefixed_env()
+    else:
+        # load the test config if passed in
+        app.testing = True
+        app.config |= test_config
+
+    # apply the extensions to the app
+    db.init_app(app)
+    alembic.init_app(app)
+
+    # apply the blueprints to the app
+    from flaskr import auth
+    from flaskr import blog
+
+    app.register_blueprint(auth.bp)
+    app.register_blueprint(blog.bp)
+
+    # make url_for('index') == url_for('blog.index')
+    # in another app, you might define a separate main index here with
+    # app.route, while giving the blog blueprint a url_prefix, but for
+    # the tutorial the blog will be the main index
+    app.add_url_rule("/", endpoint="index")
+
+    return app