Alert: Sadly, I don't have time to maintain this.
A full working flask demo api, exhaustive examples of common web services that we can made with this great micro-framework flask. A kind of one-size-fits-all which can be too complicated for beginners and also too opinionated for advanced uses but first-of-all it's a full working example of common use cases in web api services featuring authentication and backoffice admin, resources CRUD and query pagination, modular structure, REST json responses or Html renders, bootstrap custom themes, some utils like config files for Nginx (as a frontend reverse proxy), Gunicorn (as a WSGI application server), Redis (as a server-side session storage), MySQL or SQLite (as DataBase) and much more features.
This is an advanced demo app forked from AndreiD/Flask-Easy-Template : https://github.com/AndreiD/Flask-Easy-Template
Additional reference sources - mbithenzomo/project-dream-team-three : https://github.com/mbithenzomo/project-dream-team-three
- configuration files, environment variables and sensitive variables (in private folder)
- Production environment config : REDIS (as a server-side session storage), Nginx (as a frontend reverse proxy), Gunicorn (as a multi-threaded WSGI application server) and some supervisor (upstart) config file examples in utils folder
- Utils for server production setups (nginx and supervisor config files for redis, gunicorn)
- Latest bootstrap, bootswatch, modernizer, jquery, moment.js, tinymcs, etc. served from content delivery networks.
- Module Sample PAGES, with home page full-screen layout
- Module Sample database SECTIONS with SQLALchemy, relational models and Pagination
- Module Sample database USERS with SQLALchemy, relational models and Pagination
- Module Sample page MESSAGES with email form, recaptcha and Email service by SendGrid and Flash MESSAGE notifications
- Module Sample database RESOURCES :
- ITEMS with images gallery and wysiwyg visual editor,
- ASSETS files and image processing with Pillow
- EVENTS (start/end datetime and timestamp operations)
- ADDRESSES (google map and geocoding with latitude and longitude)
- Module Sample database ORDERS and orderitem many-to-many relationship and shopping cart operations
- Module Sample database PAYMENTS, credit cards, cryptography and transaction operations via paypal API Restful.
- Module sample ADMIN, backoffice member with authentication and authorization, and hash password powered by Flask-login and Werkzeug.security plugin :
- User Registry, Login & Logout
- Session based authentication or Basic HTTP authentication or Token based authentication (with active SSL recommended in production environement)
- Password hash and password-check with werkzeug.security (bcrypt-like approach) (with active SSL recommended in production environment)
- password base64 encoding for remote ajax-based app client (optional)
- Role management (is_admin, is_owner, is_member), control access and Dashboard sample page.
- SQLite or MySQL database configuration option
- SQL schema files and SQL populate files for SQLite or MySQL
- ORM Schema relationships samples with SQLAlchemy :
- ONE-TO-MANY and MANY-TO-ONE
- HIERARCHIC (Adjacency List Relationships : parent-children)
- MANY-TO-MANY Association object
- CUSTOM THEME layout and templates
- Logger setting service
- INTERNATIONALIZATION with functions like get_locale() and get_timezone() (flask-babel optional) based on :
current_user locale and current_user timezone
or global current_language and global timezone
or browser language and locale timezone
- Helpers (include decorators like SSL required, threaded function, Datetime and timezone utils, datetime format filter, random populate data, Random token generator)
- Maintenance/coming-soon, flash-message page
- Error handlers : 404 (path not found),
500 (server error),
403 (forbidden page or invalid csrf token form),
400 (Bad request, the syntax of the request entity is not correct),
422 (Unprocessable Entity : the request is syntactically correct but his contained instructions is
semantically erroneous so it was unable to process )
You may have some sensitive variables that should not be publicly shared, such as passwords and secret keys.
These can be put in an instance/config.py file, which will not be pushed to version control.
(Flask default dedicated folder for secret data must be named /instance)
Edit example config files in `utils` folder ( `prod-config.py`, `dev-config.py`, `test-config.py` )
and move it to `/instance` folder, they will override some default variables in your `config.py` file.
- `git clone https://github.com/systemaker/flask-web-api-demo.git <project_name>` or download the zip
- `pip install -r requirements.txt` or `python -m pip install -r requirements-pip2.txt`
- `python run.py` -> http://server_ip:5000
- Troubleshoots or advanced python setup required ?
for PYTHON VIRTUAL ENVIRONMENT SETTING, see next section below.
- `export FLASK_CONFIG=production`
or on Windows systems shell script `set FLASK_CONFIG=production`
- `export FLASK_APP=run.py`
or on Windows systems `set FLASK_APP=run.py`
- `flask run`
- check the `config.py`file or your secret config `instance/config.py` file.
Edit also example config files in `utils` folder ( `prod-config.py`, `dev-config.py`, `test-config.py` )
and move it to `/instance` folder, they will override some default variables in your `config.py` file.
> <!DOCTYPE html>
> {% set bootstrap_version = '3.3.4' %}
> {% set jquery_version = '2.1.3' %}
> {% set modernizer_version = '2.8.3' %}
> {% set bootswatch_version = '3.3.2' %}
> {% set bootswatch_theme = 'slate' %}
In case you don't like the "slate" theme, you can chose a nice theme from http://bootswatch.com/ and just replace the theme name
- in template, use current_user : {% if current_user.is_authenticated %} ... {% else %} ... {% endif %}
- in controllers route, use `@login_required` to check if user is already login then `current_user` to check his role
from flask_login import login_required, current_user
@auth_page.route('/dashboard')
@login_required
def dashboard():
# prevent non-admin roles from accessing the page
if not(current_user.is_admin):
abort(403)
return render_template('auth/dashboard.html')
# INSTALL VIRTUAL ENV : In Python 3.3, virtualenv is already included !!! But his name is now pyvenv
`pip install virtualenv`
# optional switcher/wrapper helper `pip install virtualenvwrapper`
# optional addon helper for windows `pip install virtualenvwrapper-win`
- on Windows systems you can add an environment variable WORKON_HOME to specify the path to store environments (By default, this is %USERPROFILE%\Envs) ; pywin python version switcher is not included
# List all of the environments
`lsvirtualenv`
# Create the directory ('/envs' for example if not exist) for the virtual environments for this project
`mkdir /path/to/your_projet/envs`
# Create your first virtual environnement for this project ('/libs1' for example )
`virtualenv /path/to/your_projet/envs/libs1`
or 'mkvirtualenv' ?
# optional for no system libraries : --no-site-packages
# optional for python version choice --python=your_python_path : -p /usr/bin/python2.6
- to get python path : which python3
# Activate this environment for your current shell session
`workon [<name>]`
or `source my_project/bin/activate`
or on Windows go in the Scripts path folder `cd my_project/env/libs1/Scripts` then `activate`
- WARNING ON WINDOWS SYSTEMS : Some paths within the virtualenv are slightly different on Windows: scripts and executables on Windows go in ENV\Scripts\ instead of ENV/bin/ and libraries go in ENV\Lib\ rather than ENV/lib/.
on Windows systems, the equivalent activate script is by opening active shell in the Scripts folder (Based on your active shell (CMD.exe or Powershell.exe), Windows will use either activate.bat or activate.ps1)
# then install your dependencies
`pip install -r requirements.txt` or `python -m pip install -r requirements-pip2.txt`
# Deactivate the current working virtualenv and switch back to the default system Python.
(myenv)$ `deactivate`
# Remove a virtual environment
`rmvirtualenv [<name>]`
`python -m pip install <new_package> && pip list > requirements.txt && pip list --format=freeze > requirements-pip2.txt`
`pip install -r requirements.txt` or `python -m pip install -r requirements-pip2.txt`
`find . -name \*.pyc -delete`
or for windows users `del /S *.pyc`
with nginx config files and supervisor (upstart) configuration files for gunicorn
PRODUCTION CONFIG with GUNICORN : Use it for production with GUNICORN Upstart script and NGINX config from utils directory :
- set environment to production with `export FLASK_CONFIG=production`
or on Windows systems shell script `set FLASK_CONFIG=production`
- active your Python virtual environment
- GUNICORN : on shell command type `gunicorn --bind 0.0.0.0:5000 run:app`
'run' is the name of your main application file 'run.py' which serve as the entry point for your application
'app' is here the name of your defined application in app/__init__.py
- If you visit your server's domain name or IP address with :5000 appended to the end in your web browser, you should see the homepage of your application
- Create an Upstart script which will allow server to automatically start Gunicorn and serve our Flask application whenever the server boots :
- create Gunicorn Upstart script : `sudo nano /etc/init/myproject_gunicorn.conf`
or customize Upstart script file (edit example in file 'myproject_gunicorn.conf' in utils directory and replace 'myproject' paths by your project path) (replace user keyword by your chosen server user name ) and place it in /etc/init/myproject_gunicorn.conf
- then type `sudo start myproject_gunicorn` (replace myproject with your application folder name)
- After editing a code, you can refresh app by typing `sudo service myproject_gunicorn restart`
- NOTE : with our Gunicorn config upstart script file, you can generate Python and Gunicorn error logs file and access logs file in your project folder 'myproject/logs'
- NGINX: then create a new server block configuration file in Nginx's sites-available directory.
`sudo nano /etc/nginx/sites-available/myproject`
- then customize it : see example in file 'utils/myproject_nginx.txt' in utils directory
- Then enable the Nginx server block configuration, link the file to the sites-enabled directory:
`sudo ln -s /etc/nginx/sites-available/myproject /etc/nginx/sites-enabled`
- test for syntax errors by typing: `sudo nginx -t`
- restart the Nginx process to read the our new config: `sudo service nginx restart`
- Install, configure and secure Redis in your server : https://redis.io/
- Add in your config.py file or prod-config.py file :
import redis
...
SESSION_TYPE = 'redis'
SESSION_REDIS = redis.from_url('127.0.0.1:6379')
- edit origins url in "register cors" section in __init__.py file :
CORS(app, resources={r"/*": {"origins": "http://localhost:3000"}})
# Edit sql file in `/data` folder
- Signin in first with `mysql -u root -p`
- Create a database : `CREATE DATABASE my_database;`
- Show all databases : `SHOW DATABASES;`
- Select my database : `USE my_database;`
- Execute script on my database, for example insert data into a mysql table :
`INSERT INTO table_name (field1, field2, ...) VALUES (value1, value2, ...);`
- Import and execute sql script file :
`source /home/myproject_path/data/schema_mysql.sql;`
- View current database : `SELECT database();`
- Delete my database : `DROP DATABASE my_database;`
`mysql -u root -p DB_NAME < /home/myproject_path/data/schema_mysql.sql`
`mysqldump -u root -p --databases DB_NAME > /home/myproject_path/data/schema_mysql.sql`
- READ FIRST : About Python 2 and 3 compatibility
Some scripts and modules versions required here are written in python 2 and not ready yet for python 3 ,
so it is recommended to download and install both interpreters python 2 and also python 3 (for windows users don't forget to add their folder paths also in your environment variables)
Then when calling python scripts in version 2 or 3 anyway (example with the package manager script PIP), you can run default python command like :
"python -m pip install ..." or "pip install ..."
To call only python 3 scripts choose this instead :
"py -m pip install ..." or "pip3 install ..."
-----------------------------------------------------------------------------------------
- Error parsing in requirements.txt ?
Run instead this compatible formatted file :
python -m pip install -r requirements-pip2.txt
or convert first your requirements.txt to a python 2 pip2 compatible format with this command :
python -m pip list --format=freeze > requirements.txt
-----------------------------------------------------------------------------------------
- Error install on Proxytype : SyntaxError like Missing parentheses in call to 'print' ?
the print function requires parentheses in Python 3 but not in Python 2 which means that the extension that you are trying to install is not yet compatible with python 3
This is why it is recommended to install python 3 and python 2 by default.
So run instead this compatible command for python 2 extensions (after installing python 2 if not got it yet) :
python -m pip install -r requirements-pip2.txt
or python -m pip install ...
-----------------------------------------------------------------------------------------
- Error install module Pycrypto : microsoft visual c++ compiler for python 2.7 is required ?
download and install microsoft visual c++ compiler for python 2.7 here : https://www.microsoft.com/en-us/download/details.aspx?id=44266
-----------------------------------------------------------------------------------------
- Error Tornado module not found ?
it is a problem when installing modules like tornado in a multiple python interpreters environment
So run instead this common command python which precize by default the python 2 version
python -m pip install -r requirements-pip2.txt
or python -m pip install ...
or python run.py
- Error Install MySQL-python on Windows systems not working ?
go over to oracle, and download the MySQL Connector C 6.0.2 and do the typical install.
http://dev.mysql.com/downloads/connector/c/6.0.html#downloads
Your Feedback is appreciated :)
Copyright 2017 Systemaker.com
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.