Flask project template
Flask project template contains working example of Flask project with features:
- Ready to ship Flask project template
- Database migrations out-of-the-box (uses Alembic)
- Simple setup
make setup && make runwhich make local virtualenv isolated environment and doesn't trash your system python.
Dockerfilethat allow to setup full linux environment on any host OS supported by Docker
- Static files managed by
bower. By default templates uses
Bootstrapbut doesn't force you to use this UI framework.
- Have working example of GitHub OAuth authorization, you only need to provide your own security and secret key (will work with example keys only on
127.0.0.1:5000). Allow user login/logout
- i18n and l10n via integrated Babel support and
- User settings page with ability to switch site language
Flask-FlatPagessupport to simplify static pages management
- Built In
- Fixtures dump/restore support
- Inegrated Celery background tasks management
- Cache using Flask-Cache
- Logging with example how to make email notifications when something goes wrong on server
How to start
Second way is manually clone this repository and change it later by own. Project is ready to run (with some requrements). You need to clone and run:
$ mkdir Project $ cd Project $ git clone firstname.lastname@example.org:xen/flask-project-template.git . $ make $ make run
Open http://127.0.0.1:5000/, customize project files and have fun.
If you have any ideas how to improve it Fork project and send me pull request.
If you never worked with python projects then simpliest way is run project inside Docker. Follow instruction how to install Docker in your OS.
If you familiar with web development then you need Python and Node.js:
- Recent Python supported version with sqlite library (usually it is included)
virtualenvcommand, name can vary, so you can change it inside
bower, if you already have
npmthen run this command:
npm install -g bower
How to make full Python setup on macOS is not topic that can be cowered quickly (because you will need XCode and few more steps). One of the prefered ways to install required packages is to use
brew. Memcached and Redis are not nesessary for all sites, but I have included them into project since my projects usually depends on them. If you need them also then install
brew and then run this command:
brew install python # or python3 or pypy brew install memcached libmemcached redis
You also can use
brew to install your prefered RDBMS, nginx or whatever you need for your development.
Can I use Python 3?
This Flask project template is Python 3 ready, but unfortunately some of Flask extensions or python modules can be incompatible with Python 3.x. If you are sure that you don't need one of them then try to use Python 3.x or PyPy.
Included modules support
Werkzeug— base for everything.
Flask-Babel— i18n support.
Markdown— to maintain auxiliary pages (About, Contacts, etc).
Flask-Script— simplify management tasks.
Flask-WTF— form validation.
flask-restless— restfull API generator.
Flask-SQLAlchemy— database ORM layer build on top of SQLAlchemy, best python ORM with depth and flexibility.
flask-migrate— database schema migration support.
Flask-Login— social networks login.
Celery— background and defered tasks broker.
Flask-Cache— tiny cache extension. Since I found myself using cache in most projects added this package to the list.
make commands overview
There is several useful targets in
run— local run server in DEBUG mode
init— synchronize database scheme and apply migrations. This target should be idempotent (if you run in several times you will get the same results in the end), but if you work with several database at once sometimes in need manual tuning.
project/translations/messages.potfile with different strategy.
addlang— add new language translation with code taken from shell variable
LANG. Simple usage example
$ LANG=en make addlang
updlang— update language files in language folders made by
celery— run celery broker
dcelery— run celery broker in debug state with code reload and verbose output. Sometimes require manual reloads, but more handy during development
Translation workflow in nutshell:
- Edit templates and py files
lazybabelif new translations strings were added or modified
updlangto apply master
.potfiles changes to
addlangif you need to support another language
LANGUAGESdict to allow users see new translations in Settings page
- Use Poedit to translate strings
manage.py command overview
Flask-Script added flawor of Django
manage.py to Flask development. Put your common management tasks inside this file. Migration commands already available with
db prefix. For example how to make new migration and upgrade your database:
$ python manage.py db migrate -m "new models" $ python manage.py db upgrade # don't forget to add new file under git control $ git add migrations/versions/*.py
manage.py already have this commands:
init— recreate all tables in database. Usually you don't need to use this command since it will erase all your data, but on empty environment can be usefull on local enviroment.
dump— make fixture and save all data contained in models defined in
restore— restore fixtures from file created by
After you checkout this code you may need to rename folder
project to something more relevant your needs. I prefer to have own name for each individual project. Next step to change all mentions of word
project in your code. I don't added any code generators for this project since anyway make code reviews every time starting new Flask project by adding or removing extensions or some parts of the source code.
. ├── Dockerfile
If you need run project inside
├── Makefile ├── README.md ├── babel.cfg
Flask-Babel, generally you don't need to edit this file unless you use different template system.
To run Celery brocker use this file.
To run Flask server use this file, it is already prepared for
mod_wsgi or other wsgi webserver modules.
Rename this file to
local.cfg and use on different versions on product, test and development environment.
Use this file to register management commands. Alembic commands set already included with
├── migrations │ ├── README │ ├── alembic.ini │ ├── env.py │ ├── script.py.mako │ └── versions │ └── ee69294e63e_init_state.py
Migrations folder contains all your database migrations.
This file used by Docker and contains all Ubuntu packages that need to be installed on fresh Ubuntu server.
Your project code is here
│ ├── __init__.py │ ├── api │ │ ├── __init__.py │ │ └── views.py
Put here your your admin or API views created by
│ ├── app.py
This cornerstone part of the project structure. But export only two functions
create_celery. More info inside file.
│ ├── auth │ │ ├── __init__.py │ │ ├── forms.py │ │ ├── models.py │ │ ├── templates │ │ │ └── auth │ │ │ ├── index.html │ │ │ ├── macros.html │ │ │ ├── profile.html │ │ │ └── settings.html │ │ └── views.py
project.auth is working example of blueprint which show how to organize user authentication using different OAuth providers, such as Facebook, GitHub, Twitter, etc. Full list of supported social backends available in
python-social-auth documentation page.
│ ├── config.py
File contains default configuration for the project. My personal approach to have code that can run with defaults. When you don't need special Postgres or other database features on deployment environment for testing purpose enough to use SQLite, but set of projects that are database agnostic is very limited in real life. More about configuration is separate chapter.
│ ├── docs │ │ └── index.md
Have section with simple text files is common for sites. Sometimes you need to have "Contacts" or "Features" page without dynamic elements. Just simple HTML. Here are these files. By default available by
frontend.page route, if you need to change it see inside
│ ├── extensions.py
All Flask extensions registered here. You can access them by import from this file. More information is available in configuration chapter.
│ ├── frontend │ │ ├── __init__.py │ │ ├── templates │ │ │ └── frontend │ │ │ ├── index.html │ │ │ └── user_profile.html │ │ └── views.py
Front page of the site and some useful common pages combined in one blueprint. Generally each site section have its own blueprint, but if you are not sure where to put something small put it here.
│ ├── models.py
Helper to access
SQLAlchemy models. I found very comfortably to have all models collected together in one place. Since your models always mapped into database you never should have conflict errors using the same name because database don't allow to have several tables with the same name.
│ ├── tasks.py
Celery tasks placed here. If you have worked with Celery you will found yourself familiar with this concept. If you need to spit tasks in different files then follow idea of
│ ├── templates │ │ ├── base.html │ │ ├── counter.html │ │ ├── macros.html │ │ ├── misc │ │ │ ├── 403.html │ │ │ ├── 404.html │ │ │ ├── 405.html │ │ │ ├── 500.html │ │ │ └── base.html │ │ ├── nav.html │ │ └── page.html
There are basic site templates. Each blueprint have its own
template/<blueprint_name> folder because of recommendation of Jinja documentation. If you don't want to read how Jinja environment lookup working then just follow this pattern. For your convenience
misc folder contains templates for common error pages.
│ ├── translations │ │ ├── en │ │ │ └── LC_MESSAGES │ │ │ └── messages.po │ │ ├── messages.pot │ │ └── ru │ │ └── LC_MESSAGES │ │ ├── messages.mo │ │ └── messages.po
If you don't need internationalization you can ignore this folder. If you don't then your translation strings located here.
Po files are standard for translation and internationalization of different projects. Always cover text inside
_ (underscore) function, project code contains all needed examples.
│ └── utils.py
Trash-can for all common usefulness that can't find place in other parts of the code.
All project dependencies installed by
This file makes your folder python project that can be wrapped into egg and distributed by DevOps. This part is not covered in documentation and usually needed on past stages of project.
└── static ├── bower.json ├── code.js ├── favicon.png ├── libs ├── robots.txt └── style.css
All static dependencies are installed by
bower packages manager. Of course you can get rid of
browserify or CoffeScript? By default site already use Bootstrap.
Already mention my approach: project should be able to start with minimum external dependencies. Of course if project grow up probability of using individual features increase. For example Postgres have different capabilities then SQLite, but this Flask project template trying to be as much agnostic as it can. That is why
config.py is not empty, I attempt to make you able to start your simple Flask application after git checkout.
Of course you will make changes to your configuration, but more important how your project will work after development phase and how it flexible will be if you have team of developers.
My recommendation store everything common and insensitive inside
config.py. But if you need to have personal settings then store in
local.cfg and put this file in the root folder of the project.
But still it is not flexible enough. What if you need to connect staging or test database? Then you can use option
-c to define different config file:
$ python manage.py runserver -c test.cfg # if you need to apply migration to test database $ python manage.py -c test.cfg db upgrade
This time Flask will read configuration this order:
config.pyinside project folder
- Try to find
local.cfgin parent folder
- Configuration file provided by command line
cfg files don't executed it is simple text files. In the end configuration variable will have last value it was mentioned. For example if
MAIL_SERVER defined in
config.py and redefined in
local.cfg then last value will be used by Flask application.
This approach cover most cases I have in my practice. Show your DevOp how to use
cfg and put inside variables he/she need to change.
local.cfg is ignored in
.gitignore so you will not accidentally put your database passwords to public repository.