This tutorial is not meant for beginners. It is assumed that the reader is familiar with the flask framework.
In this tutorial we will be writing a flask application using
Flask Blueprints and
Application Factory Pattern.
If you're working on a small project, keeping all of your code in one module isn't a bad idea. However, for large projects, it is usual practise to divide your project into numerous packages using Flask Blueprints.
A blueprint is a file that contains a single piece of functionality in your application. Consider a flask application built with blueprints as a collection of critical bits of functionality that work together to produce a complete web application.
It's a good idea to think about what blueprints you can break your application into before you start writing. I usually use three blueprints,
admin, in my personal approach. The
api blueprint is added to handle programmatic access to the web application resources. The user-related functionality is handled by the
user blueprint, including registration, logout, login, password reset etc. The admin blueprint is in charge of the admin panel functionality and features.
|-app.py |-.gitignore |-README.md |-requirements.txt |-logs/ |-app_name/ |-__init__.py |-.env |-models/ |-utils/ |-forms/ |-config/ |-config.py |-database.py |-static/ |-templates/ |-layout.html |-400.html |-403.html |-404.html |-405.html |-500.html |-routes/ |-__init__.py |-api.py |-user.py |-admin.py |-templates |-user/ |-register.html |-admin/ |-panel.html
The following table gives an overview of what each file and folder does
|File or Folder||Description|
|app.py||The file that contains the flask application instance for starting the application|
|requirements.py||The file that contains all the dependencies of the application|
|logs/||The folder that contains application logs|
|app_name/.env||"The file that contains environment variables like SECRET_KEY|
|app_name/routes||The folder that contains the blueprints and templates related to them|
|app_name/__init__.py||The file where we assemble the different components of the flask application|
|app_name/models/||The folder that contains the database models|
|app_name/utils/||The folder that contains the essential services like database access object (daos)|
|app_name/forms/||The folder that contains flask forms|
|app_name/config/config.py||The file that contains configurations of the flask application|
|app_name/config/database.py||The file that contains configurations of the database|
|app_name/static||"The folder that contains all the css|
|app_name/templates||The folder that contains the base template and error pages of the application|
Because we've organised our application into blueprints, instead of sending requests to the flask application instance to be handled, the server now sends them to the appropriate blueprint. The blueprints must "register" with the flask application instance in order for the flask application instance to know about the project's blueprints and routes.
There are several ways to configure a flask application, but in this tutorial we will be using an
.env file and python objects.
In practise, you wouldn't want to hardcode the value of important parameters like the
mail server username and
password, and many more in the
config.py file for security reasons.
The production-grade or the !noob way of setting important
parameters is to write them in an
.env file. The python package
python-dotenv is a handy little tool. After you've installed the package, you'll need to create a
.env file in your project's root directory to define all of your environment variables. The
load_dotenv() function in your config.py file is then used to load the environment configuration settings from the
.env file. You must remember to include the
.env file to your
.gitignore file if you use this technique.
CONFIG_ENV = Development ENV = development SECRET_KEY = 'DamnSIMpLeSecREtKEy' DATABASE_URI = 'mysql+pymysql://user:password@hostname:port/database_name' MAIL_USERNAME = mail_user MAIL_PASSWORD = mail_password MAIL_DEFAULT_SENDER = mail_sender
from os import path, environ from dotenv import load_dotenv # Absolute path of app_name directory BASE_DIR = path.abspath(path.dirname(path.dirname(__file__))) # Loading configuration variable into the environment from .env file load_dotenv(path.join(BASE_DIR, '.env')) class Config: """ Base class configuration, common to all other config classes """ SECRET_KEY = environ.get('SECRET_KEY', 'samplesecret_key') WTF_CSRF_ENABLED = True SQLALCHEMY_TRACK_MODIFICATIONS = False MAIL_SERVER = 'smtp.googlemail.com' MAIL_USE_SSL = True MAIL_PORT = 465 MAIL_USE_TLS = False MAIL_SUPPRESS_SEND = False MAIL_USERNAME = environ.get('MAIL_USERNAME', '') MAIL_PASSWORD = environ.get('MAIL_PASSWORD', '') MAIL_DEFAULT_SENDER = environ.get('MAIL_USERNAME', '') class Development(Config): """Configuration settings for development environment""" DEBUG = True TESTING = False ENV = 'development' DATABASE_URI = environ.get("DATABASE_URI") class Production(Config): """Configuration settings for production environment""" DEBUG = False TESTING = False ENV = 'production' DATABASE_URI = environ.get("PROD_DATABASE_URI") class Testing(Config): """Configuration settings for testing environment""" TESTING = True WTF_CSRF_ENABLED = False MAIL_SUPPRESS_SEND = True DATABASE_URI = environ.get("TEST_DATABASE_URI")
from flask import Flask from os import environ from .config.config import Development, Production def create_app(): app = Flask(__name__) if environ.get('CONFIG_ENV') == 'Development': app.config.from_object(Development()) else: app.config.from_object(Production()) @app.route("/",methods=['GET']) def index(): return '<h2>App is Running</h2>' return app
from os import environ from app_name import create_app app = create_app() if __name__ == "__main__": app.run()
Blueprints are defined by instantiating an instance of the Blueprint class. The arguments passed to the class constructor are the name of the blueprint and the name of the folder containing the templates belonging to the blueprint and a url prefix to differentiate between the similar routes of different blueprints. You then need to write the routes of that blueprint.
from flask import Blueprint def create_blueprint(): """Instantiating api blueprint and returning it""" api = Blueprint('api', __name__, template_folder='templates', url_prefix='/api') @api.route('/info',methods=['GET']) def info(): return '<h2>Sample Route</h2>' return api
from flask import Blueprint, render_template def create_blueprint(): """Instantiating user blueprint and returning it""" user = Blueprint('user', __name__, template_folder='templates/user', url_prefix='/user') @user.route('/register',methods=['GET']) def register(): return render_template('register.html') return user
from flask import Blueprint, render_template def create_blueprint(): """Instantiating admin blueprint and returning it""" admin = Blueprint('admin', __name__, template_folder='templates/admin', url_prefix='/admin') @admin.route('/panel',methods=['GET']) def panel(): return render_template('panel.html') return admin
Any references to the
appobject must be replaced with references to the
current_appobject. This is because you no longer have direct access to the flask application instance when dealing with blueprints. It is only accessible through its proxy,
Make sure the
url_for()method refers to the view function's blueprint. This is done to reflect the reality that certain blueprints have distinct view functionalities.
Make that the blueprint object is used by the decorator used to define any route.
We want to create flask applications with different configurations(
Development, Production, Testing) without changing much in the actual code. Here, the function of
factory method is to spin up different flask applications according to our need. The Application Factory Pattern is nothing but the well-known design pattern
Factory Method Pattern.
- Instantiation of Flask Application
- Loading Configurations of Flask Application
- Registration of BLueprints
- Registration of Error Handlers
- Configuration of Logging Module
We covered the first two steps in the previous sections, so we will be continuing from the third step.
Blueprints are registered by passing the blueprint object to the
register_blueprint() method the flask application instance exposes.
from app_name.routes import user, admin, api def register_blueprints(app): """Registering all the blueprint objects""" app.register_blueprint(user.create_blueprint()) app.register_blueprint(admin.create_blueprint()) app.register_blueprint(api.create_blueprint())
from flask import Flask from os import environ from .config.config import Development, Production from .utils.register_blueprints import register_blueprints def create_app(): app = Flask(__name__) if environ.get('CONFIG_ENV') == 'Development': app.config.from_object(Development()) else: app.config.from_object(Production()) # Registering Blueprints register_blueprints(app) @app.route("/",methods=['GET']) def index(): return '<h2>App is Running</h2>' return app
It is the process of keeping official record of your application. It is used for recording events as they occur and is a great tool for debugging any issues and gaining information about your application's working.
You should log application specific errors as well as database specific errors. You may also opt to log important functionalities of your application. Any kind of sensitive information should not be logged as logs are stored in plaintext format.
Generally standard python logging module is used. The standard looging module has 4 submodules, which are
Loggers are the objects that create log messages. When you produce a log message, you have to specify its criticality by using the function associated with the criticality level.The following are the criticalility levels (also known as logging levels), their numeric representations, and the functions that go with them:
- Debug → 10 → debug()
- Info → 20 → info()
- Warning → 30 → warning()
- Error → 40 → error()
- Critical → 50 → critical()
logger object can be accessed and utilised without the requirement for any configuration. The
app.logger object is exposed by every flask instance. If you're using blueprints, you'll need to use the
current_app object, which is a proxy for the flask application instance.
from flask import Blueprint, render_template, current_app def create_blueprint(): """Instantiating admin blueprint and returning it""" admin = Blueprint('admin', __name__, template_folder='templates/admin', url_prefix='/admin') @admin.route('/panel',methods=['GET']) def panel(): current_app.logger.info("Admin Panel Accessed") return render_template('panel.html') return admin
The default logger, unfortunately, simply prints to the console. As a result, if you want to log to a file, you must create a new logger instance. The default logger will continue to log, but you can turn it off if you want:
from flask.logging import default_handler app.logger.removeHandler(default_handler)
You can set the minimum criticality level of the messages that should be logged when configuring a new logger instance. All log messages with a criticality of this value or greater will be logged, while those with a criticality of less than this value will be ignored. This is handy in instances where you don't want
to delete log calls from your source code but still want to limit the number of log messages. You can increase the minimum log level of messages that are written to the log, such as ERROR messages and higher.
Handlers are the objects that route log messages to the appropriate location. A stream handler is the default handler, and it transmits log messages to the terminal. To route log messages to different destinations, you can build different handler objects.
FileHandleris used to log to a file. A
SMTPHandleris used to deliver log messages as email.
FileHandlerfunction accepts the
nameof the log file you wish to write to and creates a
FileHandlerobject that sends log messages to that file.
In most cases, the
logsfolder is used to store files that execute during runtime (logs and database files). This folder must be added to your
.gitignorefile in order for version control to ignore it.
file_handler = logging.FileHandler('logs/application.log') app.logger.addHandler(file_handler)
The log messages are written to a single log file via the
FileHandler object. As a result, the log file might quickly grow in size. Using the
RotatingFileHandler object is a better option. It likewise saves log messages to a file, but if the existing log file surpasses a certain size, it produces a new one (
maxBytes). Before overwriting the current files, it will generate a new file up to a given number of files (
from logging.handlers import RotatingFileHandler file_handler = RotatingFileHandler('logs/application.log', maxBytes=16384, backupCount=15)
Filters are used to add contextual information to log messages. When logging requests, for example, you can add a filter that includes the request's external IP address.
Formatters are used to specify the format of the log messages. A
LogRecord object represents each log message. Log formatters are used to specify which
LogRecord characteristics should be displayed and in what order they should be displayed.
- %(asctime)s - datetime when the LogRecord was created
- %(filename)s - filename portion of pathname
- %(funcName)s - name of function containing the logging call
- %(levelname)s - logging level for the message
- %(lineno)d - line number of source code where the logging call was issued (if available)
- %(message)s - the logged message
- %(module)s - module from which the logging call was issued
You should configure
logging before creating the flask application instance, otherwise it will use the default handler which writes log messages to the console. This is why the application factory function is used to configure logging.
import logging from flask.logging import default_handler from logging.handlers import RotatingFileHandler def log_config(app): # Deactivate default flask logger app.logger.removeHandler(default_handler) # File handler object file_handler = RotatingFileHandler('logs/application.log', maxBytes=16384, backupCount=15) # Set logging level of the file handler object so that it logs INFO and up file_handler.setLevel(logging.INFO) # file formatter object file_formatter = logging.Formatter('%(asctime)s %(levelname)s: %(message)s [in %(filename)s: %(lineno)d]') # Apply file formatter object to the file handler object file_handler.setFormatter(file_formatter) # Add file handler object to the logger app.logger.addHandler(file_handler)
An HTTP status code is included in the response message when a client sends a request to a web server. It's a three-digit number that represents the outcome of the request processing. Based on the initial digit, status codes are divided into five categories, each representing a different type of response:
- 1xx — Informational response
- 2xx — Successful responses
200(OK), for successful processing of the request
- 3xx — Redirects
302(Found), for successfuly redirecting the client to a new URL
- 4xx — Client errors
400(Bad Request): when the client makes a request that the server can’t understand or doesn’t allow.
403(Forbidden): when the client tries to access a restricted resource and doesn’t have authorization to do so.
404(Not Found): when a client requests a URL that the server does not recognise. The error message given should be something along the lines of “Sorry, what you are looking for just isn’t there!”.
405(Method Not Allowed): when a request method is not accepted by the view function that handles requests for a given route. The error message given should be along the lines of “Sorry, the method requested is not supported by this resource!”.
- 5xx — Server errors
500(Internal Server Error): Usually occurs due to programming errors or the server getting overloaded.
Create your custom error pages eg:
404.html and then render these error pages using error_handlers.
def error_handlers(app): # 403 - Forbidden @app.errorhandler(403) def forbidden(e): return render_template('403.html'), 403 # 400 - Bad Request @app.errorhandler(400) def bad_request(e): return render_template('400.html'), 400 # 404 - Page Not Found @app.errorhandler(404) def page_not_found(e): return render_template('404.html'), 404 # 405 - Method Not Allowed @app.errorhandler(405) def method_not_allowed(e): return render_template('405.html'), 405 # 500 - Internal Server Error @app.errorhandler(500) def server_error(e): return render_template('500.html'), 500
from flask import Flask from os import environ from .config.config import Development, Production from .utils.register_blueprints import register_blueprints from .utils.error_handlers import error_handlers from .utils.log_config import log_config def create_app(): app = Flask(__name__) if environ.get('CONFIG_ENV') == 'Development': app.config.from_object(Development()) else: app.config.from_object(Production()) # Registering Blueprints register_blueprints(app) # Configure Logging log_config(app) # Registering Error Handlers error_handlers(app) @app.route("/",methods=['GET']) def index(): return '<h2>App is Running</h2>' return app
You may now brag to your buddies about not being a noob flask developer.
I hope you all enjoyed the article.