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.
- 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 useGevent
andWebsockets
by default. (Note optional)- Convenient command line application running options.
GPL v2
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 -
make run
python -m <your_app_name> -s
Voila you are ready to roll.
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-
- Make a
create_blueprint
factory function in__init__.py
or expose it somehow from your blueprint package which will return atupple
like(blueprint_instance, url_prefix)
. Your blueprints will be auto registered when the application starts up. - Make two variables named
__blueprint__
and__prefix__
in__init__.py
or expose them somehow from your blueprint package and you are good to go.
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 -
__tablename__
- this will be autogenerated using your model's class name. For example if your model class isSomeModel
, the table name will besome_model
. So if a model class is named asANEWModel
, the table name will bea_n_e_w_model
.id
- Default is asqlalchemy.Integer
type primary key. Override it if neccessary._created
-sqlalchemy.DateTime
type._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-
MODEL_DIRS
- A list of directory names (only the directory name not absolute path) to look for models.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.
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.
A convenient Makefile
is prepared for you with the following commands -
make
\make all
: Initialize alembic configs, migrate and upgrade and finally run the application in development mode.make run_tests
: Run testsmake initdb
: Initialize alembic configs and directories. You need to run this only once. (in development mode)make migrate
: Create migration in development modemake upgrade
: Upgrade database to latest migration in development modemake downgrade
: Downgrade one revision in development modemake run
: Run the application in development modemake shell
: Runflask shell
in development modemake uwsgi
: RunuWSGI
server in development modemake gunicorn
: RunGunicorn
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 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.
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.
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.
Write your tests subclassing unittest.TestCase
and you are good to go. you can run tests in a number of
ways -
python setup.py test
make run_tests
from application directory- or specify particular module to run
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.
Any contribution or suggestion is welcome. Make an issue in github, or fork it to change if you want.