Flask-Philo

Utilities to build Flask-based microservices.

What is this project?

Flask is an awesome web microframework that works great out of the box. Nevertheless, additional configuration and integration with complimentary libraries is required in order to build complex applications. Here at Riffstation we have several HTTP REST-based microservices and whenever we want to create a new microservice we need to bootstrap very similar common code.

This library concentrates all logic related with HTTP, REST and databases in one common place. Feel free to use it and extend it. We are willing to hear about your suggestions and improvements.

Basic Features

  • REST out of the box.
  • Simple SQLAlchemy ORM, customized for PostgreSQL with multiple dabatases.
  • Unit testing tools
  • Simple Redis integration.
  • Simple Elastic Search integration.
  • Basic AWS integration.

Quick start

Installation

$ pip install Flask-Philo

Alternatively, you can create a virtual environment first:

$ mkvirtualenv -p /usr/bin/python3 philo
$ pip install Flask-Philo

Creating a new project

Flask-Philo includes the flask-philo-admin command line tool.

To quickly generate a new Flask-Philo project, navigate to the directory in which you want to create the project and run:

$ flask-philo-admin startproject <project_name>

This will create a folder called <project_name> which will contain the basic structure of a Flask-Philo application, basic unit tests and configuration.

Folder structure

The following folder structure is created for the new project:

  • README.md
  • documentation
  • src
    • app
      • __init__.py
      • models
      • serializers
      • urls.py
      • views
    • config
      • development.py
      • test.py
    • console_commands
      • __init__.py
    • manage.py
    • tests
      • __init__.py
      • test_views.py
  • tools
    • requirements
      • base.txt
      • dev.txt

Running the server for your new project

To run the listening server for your new Flask-Philo project, navigate to the project’s src/ directory and issue the runserver command :

$ cd <your-project-dir>/src
$ python3 manage.py runserver

The response from this command will be something like this:

* Running on http://0.0.0.0:8080/ (Press CTRL+C to quit)
* Restarting with stat
* Debugger is active!
* Debugger PIN: 147-416-135

Access to the server’s URL routes is controlled in two places: URL and View files.

URL Routes

The URLs file urls.py defines all available routes for your Flask-Philo application. You can refer to the example created automatically by Flask-Philo by accessing the file urls.py located in the src/app directory. It will look like this:

from app.views.example_views import ExampleView

URLS = (
    ('/example', ExampleView, 'example_route'),
)

The defined route /example is mapped to the View class ExampleView, which is defined in src/app/views/example_views.py. All View classes should be defined in the src/app/views/ directory. Below you can find the content of the example View file:

from flask_philo.views import BaseResourceView


class ExampleView(BaseResourceView):
    def get(self):
        return self.json_response(
            status=200, data={'some_data': 'yes'})

Accessing the new Flask-Philo app

If you haven’t already done so, run the following terminal command to create your Flask-Philo application:

$ python3 manage.py runserver

Now, with the application running and with a route defined, the following URL address will be accessible in the browser of your choice, and will return a JSON response:

http://localhost:8080/example

Note that the port number (in this case 8080) should match the port number displayed when you start the application:

# Port 8080 in this case
* Running on http://0.0.0.0:8080/ (Press CTRL+C to quit)
...

Your browser will display a JSON response, as defined in the ExampleView class :

{"some_data": "yes"}

Alternatively, you can test this example URL route with a direct HTTP request using the CURL command-line tool:

$ curl http://localhost:8080/example
{"some_data": "yes"}

All incoming request to your Flask-Philo application and their corresponding HTTP status codes may be viewed in the same console session you used to start the application:

* Running on http://0.0.0.0:8080/ (Press CTRL+C to quit)
* Restarting with stat
* Debugger is active!
* Debugger PIN: 147-416-135
127.0.0.1 - - [05/Dec/2017 00:06:01] "GET /example HTTP/1.1" 200 -

Running Unit Tests

Flask-Philo simplifies Unit Test coverage by providing a single console command for running and managing all test. All test code should be written in the dedicated directory location : src/app/tests. Within this directory, all Python source files begining with test_ will be executed as part of a suite of Unit Tests.

To run all Unit Tests for your new Flask-Philo app, use the following console command:

$ python3 manage.py test

The return of the tests will be something like the print below:

===================================== test session starts ======================================
platform darwin -- Python 3.5.1, pytest-3.3.0, py-1.5.2, pluggy-0.6.0
rootdir: <where_your_project_is>/flask-philo-example/src, inifile:
collected 1 item

tests/test_views.py .                                                                    [100%]

=================================== 1 passed in 0.02 seconds ===================================

In this example, the automatically-generated example Unit Test class TestExampleEndpoints is executed, as defined in src/tests/test_views.py

Extending Flask-Philo projects

Flask-Philo projects are fully customizable and fully extensible. There are a lot of possible integrations. Below, you can see some examples and their documentation link:

In order to deploy a Flask-Philo application, we can use any deployment tool on the market. For example :

For further information related to Flask-Philo, here follows the link for the documentation of the project:

[http://flask-philo.readthedocs.io/en/latest/index.html]

You can refer to the examples above, by checking our real Flask-Philo example in the following github project:

[https://github.com/Riffstation/flask-philo-example]