flask-ligand-example

A simple example project on how to use the flask-ligand library. This example project is based on the example from the flask-smorest project. (Which is a core library that flask-ligand is built upon)

Quick Start Guide

Follow the instructions below to start exploring this example project!

Prerequisites

• Python 3.10+
• virtualenvwrapper
• Docker (with Compose V2)

Clone Repo

$ git clone git@github.com:cowofevil/flask-ligand-example.git

Make Targets

Execute the following command to get a full list of make targets:

$ make help

Setup Python Environment

1. Create a Python virtual environment:

   $ mkvirtualenv -p py310 flask-ligand-example
   

2. Setup develop environment:

   $ make develop-venv
   

3. Setup git pre-commit hooks:

   $ make setup-pre-commit
   

4. Verify that environment is ready for development:

   $ make test-tox
   

Setup Docker Environment

The included docker environment used for integration testing can also be used for exploring the example project as well!

1. Setup the Docker environment:

   $ make setup-integration
   

2. Verify that the Docker environment is ready:

   $ make check-integration
   

3. (Optionally) Execute the integration tests:

   $ make test-integration
   

Explore with SwaggerUI Docs

This example project has all the bells and whistles enabled for the flask-ligand library which can be explored by using the included SwaggerUI documentation. Follow the instructions below to start start running a local Flask server to serve the SwaggerUI documentation.

1. Generate a '.env' file to configure Flask server to use the included Docker environment:

   $ make gen-local-env-file
   

2. Initialize the database:

   $ make setup-db
   

3. Generate a JWT access token with admin rights for accessing the included example project endpoints:

   $ make gen-admin-access-token
   

4. Start the local Flask server:

   $ make run
   

5. Open a browser and navigate to 'http://localhost:5000/apidocs'.

6. Click the 'Authorize' button and paste in the JWT access token you created previously.

Now go ahead and start playing around with the API!

Access Keycloak Admin Console

If you would like to make changes to the Keycloak IAM clients to explore authentication then you can access the admin console by navigating to 'http://localhost:8080/admin/master/console/'. The admin credentials can be found in the 'docker/env_files/integration.env/' file.

Flask-Migrate Auto-generation

For Flask-Migrate to work well when auto-generating migration scripts it is critical that the script.py.mako template in the migrations folder include an import for sqlalchemy_utils. This project already has the template updated, but if you are using the flask-ligand library without copying this example project, then it is necessary you make the appropriate update to the script.py.mako template before using Flask-Migrate.

Resources

• Changelog
• Contributing
• License