This package uses Poetry >=1.2 (documentation).

For vscode install the python extension. Add the poetry venv path to the folders the python extension searches for venvs if the virtualenvs of poetry are not automatically discovered.

On linux:

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

Run poetry install to install dependencies.

The flask dev server loads environment variables from .flaskenv and .env. To override any variable create a .env file. Environment variables in .env take precedence over .flaskenv. See the content of the .flaskenv file for the default environment variables.

Run the development server with

poetry run flask run

For a list of all dependencies with their license open http://localhost:5000/licenses/.

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)
• invoke (documentation)
  tool for scripting cli tasks in python Tasks: tasks.py

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.
• .flaskenv
  Environment variables loaded by the flask command and the flask dev server.
• .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
  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.
• tasks.py
  Tasks that can be executed with invoke (see invoke tasks)

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)

# install dependencies from lock file in a virtualenv
poetry install

# open a shell in the virtualenv
poetry shell

# update dependencies
poetry update
poetry run invoke update-dependencies # to update other dependencies in the repository

# run a command in the virtualenv (replace cmd with the command to run without quotes)
poetry run cmd

Invoke is a python tool for scripting cli commands. It allows to define complex commands in simple python functions in the tasks.py file.

⚠️ Make sure to update the module name in tasks.py after renaming the flask_template module!

# list available commands
poetry run invoke --list

# update dependencies (requirements.txt in ./docs and licenses template)
poetry run invoke update-dependencies

# Compile the documentation
poetry run invoke doc

# Open the documentation in the default browser
poetry run invoke browse-doc

# 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

# compile documentation
poetry run invoke doc

# Open the documentation in the default browser
poetry run invoke browse-doc

# Find reference targets defined in the documentation
poetry run invoke doc-index --filter=searchtext

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