Flask Series: Application Configuration

Each application needs a configuration. Flask allows developers to implement their application configuration using several different approaches:

  • file-based;
  • object-based;
  • environment-variable-based;
  • instance-folders-based;

Regardless of what approach developer chooses for her/ his Flask application configuration, all configuration values are loaded on the config attribute(configuration dictionary) of the Flask application object:

There is a list of configuration values, used internally by Flask.

Note that Flask expects configuration to be available when the application starts up.

File-based configuration

Flask allows developers to store their configuration in separate files and load it from them.

The configuration file uses INI file syntax – name/value pairs in a plain text file, separated by an equal sign (“=”).

Object-based configuration

Good pattern to follow is to use classes for your Flask application configuration:

and to use this configuration, the from_object method should be used:


EnvVars-based configuration

The application can be configured based on configuration file, which is specified by a environment variable:

here the FLASK_CONFIG_FILE environment variable points to the configuration file.

Instance-based configuration

Since version 0.8 Flask provides one more configuration option – instance folders. The instance folder is designed not to be under source control and could store sensitive information. This instance folder should be directly deployed on the production server. To be able to use it, the instance_path of the Flask object should be specified:

or use it as relative path, where we have instance folder under our application folder.


Now you are ready to configure your application based on the instance folders mechanism, where the flask.cfg is stored either under the instance_path  (1) or under the instance folder (2)

Best Practice

Good practice is to have a default configuration, which is under source control and to override it with sensitive and specific information kept in instance folders. For the default configuration you could use object-based configuration hierarchy(described in Object-based configuration section) and to manage which configuration object to load via environment variables:

The complete demo application, described in this blog post, can be found here.

In the next blog post I will describe how to use templates in your Flask project.

Flask Series: Structure the Application

In the previous blog post of Flask Series I have described how to prepare your Flask environment, now it’s time to structure it.

Create your project structure using the following directory hierarchy:

│   run.py
│   │   __init__.py
│   ├───admin
│   │       controllers.py
│   │       __init__.py
│   └───main
│           controllers.py
│           __init__.py

Brief Description of the Application Structure

  • bin – in this folder you could place your scripts, that will be executed on the command line;
  • docs – in this folder you could place project related documentation files;
  • tests – this folder contains your unit tests, I will prepare a blog post on this topic in the Flask Series;
  • [app_name] – contains the application itself, in this demo application I will name it a bookshelf;
  • run.py – this file is used to run the Flask application, where the contents of the file is:

The Application Folder 

The application is configured to be a modular, based on the blueprint concept in Flask. The Flask blueprints allows developers to simplify applications, better structure them and provide a central means for Flask extensions to register operations on applications. The blueprint is similar to the Flask application object, rather it is a mean to construct or extend an application.

main and admin are the Bookshelf application modules, make sure you have __init__.py files under the admin and main folders. This file (__init__.py) initializes them as python packages. Application module controllers are using the blueprint concept and are initialized as follows:



Now that you have the admin and main application modules, you need to create the application object and register them.


Test the Application

Activate your flask virtual environment created and configured in the the previous blog post and run the application:

workon flask
python run.py

Open a browser and nagivate to:

http://localhost:5000/ – to test the main application module


http://localhost:5000/admin – for the admin one

The complete demo application, described in this blog post, can be found here.

In the next blog post I will describe how to configure your Flask project.

Flask Series: Prepare the Environment

What is a Flask?

Flask is a Python micro web framework based on Werkzeug and Jinja2. It is BSD licensed.

Once you have Python installed, you can install and configure pip, setuptools and virtualenv.

pip is a recommended tool for installing Python packages.

How to install pip?
The most secure way to install pip on your machine is by downloading get-pip.py and run the following command, which may require administrator / root rights:

python get-pip.py

How to upgrade pip?
Once installed, it is very easy to upgrade pip to a newer version:

pip install -U pip

pip issues

Follow the solutions explained in the following blog post.

setuptools is a library used for packaging Python projects that allows easily to download, build, install, uninstall and upgrade these Python packages.

How to install setuptools?

pip install setuptools

virtualenv is a very helpful tool, used to keep the Python project dependencies in different places, allowing to build isolated environments. It solves dependency, versioning and permissions issues, where common packages are shared between multiple projects.

How to install virtualenv?

pip install virtualenv

virtualenvwrapper is set of extensions for the virtualenv tool, which allows easily to create, used and delete virtual environments.

How to install and configure virtualenvwrapper on UNIX systems?

pip install virtualenvwrapper

… and configuration is done like this …

export WORKON_HOME=~/Envs
mkdir -p $WORKON_HOME
source /usr/local/bin/virtualenvwrapper.sh

How to install and configure virtualenvwrapper on Windows systems?

pip install virtualenvwrapper-win

Create a new virtual environment

mkvirtualenv flask_env

Now you could install some Python packages:

(flask_env)$ pip install flask

Activate a virtual environment

workon flask_env

Deactivate the current virtual environment and switch back to the default one


More virtualenvwrapper commands can be found here.

My First Flask Application

Now that you have pip, setuptools and virtualenv installed and configured, you could implement your first Flask application.

First you should activate the already created virtual environment:

workon flask_env

Create a new python module named app.py and paste the following code within it:

Run the following command to start the flask application:

python app.py

Open your browser and type http://localhost:5000 By default the flask web application will run on port 5000. You could change that option by specifying the port parameter of the run method:

In the next blog post I will write how to structure your Flask project.

How to fix an AssertionError when trying to list Python packages with the ‘pip list’ command

The Problem

Getting the following assertion error when trying to list the Python packages:

pip list

Traceback (most recent call last):
  File "/usr/lib/python2.7/dist-packages/pip/basecommand.py", line 134, in main
    status = self.run(options, args)
  File "/usr/lib/python2.7/dist-packages/pip/commands/list.py", line 80, in run
  File "/usr/lib/python2.7/dist-packages/pip/commands/list.py", line 127, in run_listing
  File "/usr/lib/python2.7/dist-packages/pip/commands/list.py", line 136, in output_package_listing
    if dist_is_editable(dist):
  File "/usr/lib/python2.7/dist-packages/pip/util.py", line 347, in dist_is_editable
    req = FrozenRequirement.from_dist(dist, [])
  File "/usr/lib/python2.7/dist-packages/pip/__init__.py", line 194, in from_dist
    assert len(specs) == 1 and specs[0][0] == '=='

means that either pip is outdated on the host machine or the distribute package.

The Solution

Upgrading pip

pip can be upgraded using the following set of commands:

# download get-pip.py via curl
curl -O https://bootstrap.pypa.io/get-pip.py
# download get-pip.py via wget
wget https://bootstrap.pypa.io/get-pip.py

# installing pip
sudo python get-pip.py


pip install -U pip

More information about pip installation and upgrade can be found here.

Upgrading the distribute package

pip install --upgrade distribute