LMDS Flask APP example

This repository contains a brief totorial on making a Flask app. It contains an example of taking a user input (in this case a string), doing a function on it (in this case sorting the string alphabetically), and returning the result to the user.

This example should give the reader enough information to understand other open source LMDS apps (as described in the associated paper) such as the MOF porosity app, the ElMTree app, and the heat capacity modelling app.

What this tutorial covers

• How to lay out a flask app
• How to add web pages
• Making a form to take user input
• Processing and returning user input
• A brief description of networking fundamentals
• Making an API of a the same form using flask-RESTful

What this tutorial does not cover

• How to code Python (an assumed prerequisit)
• How to code HTML (simple HTML is easy to learn, feel free to the LMDS layout as a basis, or you may find outsourcing this surprisingly affordable)
• How to use Gunicorn to run manage Flask apps (see alternate git repository)
• How to set up virtual machines or why you might want to use them (this is discussed in the associated paper)
• Many other completely unrelated things, such as how to bake a cake, how to express love, and how to calculate the airspeed velocity of an unladen swallow

The layout of a Flask app

A Flask apps used in the LMDS usually have the following file layout:

├── Top Level Folder
│   ├── wsgi.py
│   ├── app
│   │   ├── __init__.py
│   │   ├── routes.py
│   │   ├── any_further_source_code
│   │   ├── ....
│   │   ├── templates
|   │   │   ├── HTML_to_render.html
├── README (and other documentation)
└── .gitignore

You may also choose to include a static folder to host any static files (such as css or javascript). As many of these files are common across LMDS apps, we choose to host them seperately so they can be shared across web apps.

wsgi.py

Flask apps organised as a Python module within the "app" folder. The wsgi.py file imports that module and calls app.run(). This wsgi.py file is also called when the command "flask run" is called at the top level folder.

It can thus be used to import information about site packages and the working directory, and do any configuration. These wsgi files are simple and standard across many flask apps, so feel free to copy the example given here.

app folder

This folder contains the app module, as such it has an __init__py, which imports and deffines the application, again this is fairly standard and doesn't vary much between applications

routes.py

This file defines routes which are avaialable in the application. A route could be a web page or an API call. Web pages are usually functions which are called when somebody asks for a page with decorators defining which pages refer to which functions, whereas API calls are classes.

This file contains the bulk of the web app, take a look at it to see how it works.

forms.py

The most LMDS apps use what the forms (wtforms) for interaction between the user and the app. This works well as it is simple, and one of the design intentions of the LMDS is to be simple to implement.

Look at this file to see how we define the form.

app/templates folder

This folder contains html templates which can be rendered for the user. This is a very simple example which shows a basic webpage, a webpage with the form, and a footer which is shared between them. Templates allow you to share parts of the website between different pages, for example a footer, reducing repeated code.

API calls

The API is defined using flask-restful, this integrates well with flask and so in the routes.py you will notice that both the website call and the API call end up using the same underlying function.

Restful APIs define functions which can be called by other programs. These functions are http functions:

• GET
• POST
• PUT
• DELETE

the API deffined this app is a simple POST call which does the same function as the wbesite, this can be found in routes.py