flask_runner

Flask Runner

This is a Flask project template for large application developers who intend to modularise their application by utilizing flask.Blueprint in the simplest manner.

This is a Cookiecutter template, so to generate a project using this template one must use python cookiecutter.

Note : This template is a copy-and-edit version of Eve Runner Version-5.0.2.

Features

• Minimal setup
• Factory based application structure
• Blueprints are auto registered (yes automatically registered! see below)
• Separate configuration for development and production application
• Can use Gunicorn for both development and production server (Note optional)
• Uses Eventlet worker if using Gunicorn to allow implementing asynchronous apps(i.e SocketIO by Flask-SocketIO) (Note optional)
• Only assumption made during making the template is that the developer may want to use SQLAlchemy, so Flask-SQLAlchemy and Flask-Migrate are preconfigured. The developer only has to change SQLAlchemy related configurations.
• Easy Makefile syntax for running, testing, migrating application and it’s databases including both development and production variants.
• Auto loads SQLAlchemy models at the application startup. So no need to import all model modules by hand.
• A declarative Base class is prepared to be used
• Can use uWSGI out of the box using different config files for development and production release.(Note optional)
• uWSGI is configured to use Gevent and Websockets by default. (Note optional)
• Convenient command line application running options.

License

GPL v2

Creating new project

You only need to install cookiecutter python package either globally or in a virtual environment. After that run -

cookiecutter https://github.com/asif-mahmud/flask_runner.git

to create a project.

At this point you have 3 options for running the application -

• Using Flask Command: To run the application you’ve just created by flask run command, you need to install the app using the following command (use virtual env if you prefer) -

pip install -e . --upgrade

• Using Gunicorn: If you are on unix based platform or deploying the application you may want to use Gunicorn server to serve your app. On development run, Gunicorn is configured to watch file changes and reload your application. To do that you need to install it using the following command (use virtual env if you prefer) -

pip install -e .[gunicorn] --upgrade

• Using uWSGI: If you are on unix based platform or deploying the application you may want to use uWSGI server to serve your app. On development run, uWSGI is configured to watch file changes and reload your application. To do that you need to install it using the following command (use virtual env if you prefer) -

pip install -e .[uwsgi] --upgrade

Now you can run the application by one of the following commands depending on your choice and platform -

1. make run
2. python -m <your_app_name> -s

Voila you are ready to roll.

Blueprints

Creating blueprints is made super easy here. You only need to create you blueprint in a package under blueprints package and do any one of the following-

1. Make a create_blueprint factory function in __init__.py or expose it somehow from your blueprint package which will return a tupple like (blueprint_instance, url_prefix). Your blueprints will be auto registered when the application starts up.
2. Make two variables named __blueprint__ and __prefix__ in __init__.py or expose them somehow from your blueprint package and you are good to go.

Database models

A declarative base class is ready and exposed to be used in instance.db as Base with proper naming conventions. This base class has the following attributes predefined -

1. __tablename__ - this will be autogenerated using your model’s class name. For example if your model class is SomeModel, the table name will be some_model. So if a model class is named as ANEWModel, the table name will be a_n_e_w_model.
2. id - Default is a sqlalchemy.Integer type primary key. Override it if neccessary.
3. _created - sqlalchemy.DateTime type.
4. _updated - sqlalchemy.DateTime type.

Additionally a default __repr__ method is implemented which will return ModelClassName<Model_id> string.

You can override any of these to better suite your need.

All database models will be auto imported at application startup. You can control the scanning procedure by modifying the following configurations-

1. MODEL_DIRS - A list of directory names (only the directory name not absolute path) to look for models.
2. MODEL_EXCLUDE_FILES - A list of file names (python files like __init__.py) to exclude from importing.

All the modules available inside the MODEL_DIRS excluding the modules in MODEL_EXCLUDE_FILES will be imported. So define your models in those modules.

Application configuration

Two separate modules are dedicated to define development and production release configuration for the application. For development configuration use instance.configs.development.APP_CONFIG dictionary and for production release use instance.configs.production.APP_CONFIG dictionary.

Makefile

A convenient Makefile is prepared for you with the following commands -

1. make \ make all: Initialize alembic configs, migrate and upgrade and finally run the application in development mode.
2. make run_tests: Run tests
3. make initdb: Initialize alembic configs and directories. You need to run this only once. (in development mode)
4. make migrate: Create migration in development mode
5. make upgrade: Upgrade database to latest migration in development mode
6. make downgrade: Downgrade one revision in development mode
7. make run: Run the application in development mode
8. make shell: Run flask shell in development mode
9. make uwsgi: Run uWSGI server in development mode
10. make gunicorn: Run Gunicorn server in development mode

Commands from 3 to last have their _prod variants which will run the specified operation in production mode. (i.e make run_prod). The makefile is not under python application directory and hereby will not be included in the application package.

Switching run mode

Switching between development and production mode is done using an environmental variable named PROD, just set PROD=1 prior to running the application to run in production mode. Otherwise it will run in development mode. Database migration command will also be affected by this variable.

Running Flask Shell

Flask shell is a convenient tool to test your app quickly. To run flask shell set environmental variable FLASK_APP to your_app_name.application prior to run flask shell command. PROD variable is effective here as well. Use it to switch configuration. Additionally it can be launched by make shell or make shell_prod command.

Command line options

There is a __main__ module in the application package. So you can run various commands using python -m <your_app_name>. Run python -m <your_app_name> -h to see a list of options/commands you can run through it. You can also look at the makefile for example usage of the command line options.

Running tests

Write your tests subclassing unittest.TestCase and you are good to go. you can run tests in a number of ways -

1. python setup.py test
2. make run_tests from application directory
3. or specify particular module to run

Notes

There is no default view or api or model created for you, I believe thats your field of expertise. Using systemwide python installation or a virtualenv is also left upto your choice of development.

Contribute

Any contribution or suggestion is welcome. Make an issue in github, or fork it to change if you want.

This site is open source. Improve this page.