This package uses Poetry (documentation).

For vscode install the python extension and add the poetry venv path to the folders the python extension searches for venvs.

On linux:

{
    "python.venvFolders": [
        "~/.cache/pypoetry/virtualenvs"
    ]
}

Run poetry install to install dependencies.

Add .env file with the following content into the repository root.

FLASK_APP=flask_template # rename this if you rename the package!
FLASK_ENV=development # set to production if in production!

Run the development server with

poetry run flask run

http://localhost:5000/api/

Configured in flask_template/util/config/smorest_config.py.

• Redoc (view only): http://localhost:5000/api/redoc
• Rapidoc: http://localhost:5000/api/rapidoc
• Swagger-UI: http://localhost:5000/api/swagger-ui
• OpenAPI Spec (JSON): http://localhost:5000/api/api-spec.json

• Index: http://localhost:5000/debug/
• Registered Routes: http://localhost:5000/debug/routes
  Useful for looking up which endpoint is served under a route or what routes are available.

This template uses the following libraries to build a rest app with a database on top of flask.

• Flask (documentation)
• Flask-Cors (documentation)
  Used to provide cors headers.
  Can be configured or removed in flask_template/__init__.py.
• flask-babel (documentation, babel documentation)
  Used to provide translations.
  Can be configured in flask_template/babel.py and babel.cfg.
  Translation files and Folders: translations (and messages.pot currently in .gitignore)
• Flask-SQLAlchemy (documentation, SQLAlchemy documentation)
  ORM Mapper for many SQL databases.
  Models: flask_template/db/models
  Config: flask_template/util/config/sqlalchemy_config.py and flask_template/db/db.py
• Flask-Migrate (documentation, Alembic documentation)
  Provides automatic migration support based on alembic.
  Migrations: migrations
• flask-smorest (documentation, marshmallow documentation, apispec documentation, OpenAPI spec)
  Provides the API code and generates documentation in form of a OpenAPI specification.
  API: flask_template/api
  API Models: flask_template/api/v1_api/models
  Config: flask_template/util/config/smorest_config.py and flask_template/api/__init__.py
• Flask-JWT-Extended (documentation)
  Provides authentication with JWT tokens.
  Config: flask_template/util/config/smorest_config.py and flask_template/api/jwt.py
• Sphinx (documentation)
  The documentation generator.
  Config: pyproject.toml and docs/conf.py (toml config input is manually configured in conf.py)
• sphinxcontrib-redoc (documantation) Renders the OpenAPI spec with redoc in sphinx html output. Config: docs/conf.py (API title is read from spec)

Additional files and folders:

• default.nix and shell.nix
  For use with the nix ecosystem.
• pyproject.toml
  Poetry package config and config for the black formatter.
• .flake8
  Config for the flake8 linter
• .editorconfig
• tests
  Reserved for unit tests, this template has no unit tests.
• instance (in .gitignore)
• flask_template/templates and flask_template/static (currently empty)
  Templates and static files of the flask app
• docs
  Folder containing a sphinx documentation
• typings
  Python typing stubs for libraries that have no type information. Mostly generated with the pylance extension of vscode.

Library alternatives or recommendations:

• Rest API: flask-restx (documentation)
• For including single page applications: flask-static-digest (documentation)
• For scripting tasks: invoke (documentation)
• For hashing passwords: flask-bcrypt (documentation)
• For Background Task Scheduling: Celery (See also Integrating Celery with Flask)

# initial
poetry run pybabel extract -F babel.cfg -o messages.pot .
# create language
poetry run pybabel init -i messages.pot -d translations -l en
# compile translations to be used
poetry run pybabel compile -d translations
# extract updated strings
poetry run pybabel update -i messages.pot -d translations

# create dev db (this will NOT run migrations!)
poetry run flask create-db
# drop dev db
poetry run flask drop-db

# create a new migration after changes in the db (Always manually review the created migration!)
poetry run flask db migrate -m "Initial migration."
# upgrade db to the newest migration
poetry run flask db upgrade
# help
poetry run flask db --help

poetry shell
cd docs
make html

# export/update requirements.txt from poetry dependencies (for readthedocs build)
poetry export --format requirements.txt --output requirements.txt