')\n",
"def user(name):\n",
" return render_template('user.html', name=name)\n",
"26 \n",
"| \n",
"Chapter 3: Templates\n",
"\n",
"The function render_template() provided by Flask integrates the Jinja2 template\n",
"engine with the application. This function takes the filename of the template as its\n",
"first argument. Any additional arguments are key-value pairs that represent actual\n",
"values for variables referenced in the template. In this example, the second template is\n",
"receiving a name variable.\n",
"Keyword arguments like name=name in the previous example are fairly common, but\n",
"they may seem confusing and hard to understand if you are not used to them. The\n",
"“name” on the left side represents the argument name, which is used in the place‐\n",
"holder written in the template. The “name” on the right side is a variable in the cur‐\n",
"rent scope that provides the value for the argument of the same name. While this is a\n",
"common pattern, using the same variable name on both sides is not required.\n",
"If you have cloned the application’s Git repository on GitHub, you\n",
"can run git checkout 3a to check out this version of the applica‐\n",
"tion.\n",
"Variables\n",
"The {{ name }} construct used in the template shown in Example 3-2 references a\n",
"variable, a special placeholder that tells the template engine that the value that goes in\n",
"that place should be obtained from data provided at the time the template is ren‐\n",
"dered.\n",
"Jinja2 recognizes variables of any type, even complex types such as lists, dictionaries,\n",
"and objects. The following are some more examples of variables used in templates:\n",
"A value from a dictionary: {{ mydict['key'] }}.
\n",
"A value from a list: {{ mylist[3] }}.
\n",
"A value from a list, with a variable index: {{ mylist[myintvar] }}.
\n",
"A value from an object's method: {{ myobj.somemethod() }}.
\n",
"Variables can be modified with filters, which are added after the variable name with a\n",
"pipe character as separator. For example, the following template shows the name vari‐\n",
"able capitalized:\n",
"Hello, {{ name|capitalize }}\n",
"Table 3-1 lists some of the commonly used filters that come with Jinja2.\n",
"The Jinja2 Template Engine \n",
"| \n",
"27\n",
"\n",
"Table 3-1. Jinja2 variable filters\n",
"Filter name\n",
"Description\n",
"safe\n",
"Renders the value without applying escaping\n",
"capitalize\n",
"Converts the first character of the value to uppercase and the rest to lowercase\n",
"lower\n",
"Converts the value to lowercase characters\n",
"upper\n",
"Converts the value to uppercase characters\n",
"title\n",
"Capitalizes each word in the value\n",
"trim\n",
"Removes leading and trailing whitespace from the value\n",
"striptags\n",
"Removes any HTML tags from the value before rendering\n",
"The safe filter is interesting to highlight. By default Jinja2 escapes all variables for\n",
"security purposes. For example, if a variable is set to the value 'Hello
',\n",
"Jinja2 will render the string as '<h1>Hello</h1>', which will cause the\n",
"h1 element to be displayed and not interpreted by the browser. Many times it is neces‐\n",
"sary to display HTML code stored in variables, and for those cases the safe filter is\n",
"used.\n",
"Never use the safe filter on values that aren’t trusted, such as text\n",
"entered by users on web forms.\n",
"The complete list of filters can be obtained from the official Jinja2 documentation.\n",
"Control Structures\n",
"Jinja2 offers several control structures that can be used to alter the flow of the tem‐\n",
"plate. This section introduces some of the most useful ones with simple examples.\n",
"The following example shows how conditional statements can be entered in a\n",
"template:\n",
"{% if user %}\n",
" Hello, {{ user }}!\n",
"{% else %}\n",
" Hello, Stranger!\n",
"{% endif %}\n",
"Another common need in templates is to render a list of elements. This example\n",
"shows how this can be done with a for loop:\n",
"\n",
" {% for comment in comments %}\n",
"28 \n",
"| \n",
"Chapter 3: Templates\n",
"\n",
" - {{ comment }}
\n",
" {% endfor %}\n",
"
\n",
"Jinja2 also supports macros, which are similar to functions in Python code. For\n",
"example:\n",
"{% macro render_comment(comment) %}\n",
" {{ comment }}\n",
"{% endmacro %}\n",
"\n",
" {% for comment in comments %}\n",
" {{ render_comment(comment) }}\n",
" {% endfor %}\n",
"
\n",
"To make macros more reusable, they can be stored in standalone files that are then\n",
"imported from all the templates that need them:\n",
"{% import 'macros.html' as macros %}\n",
"\n",
" {% for comment in comments %}\n",
" {{ macros.render_comment(comment) }}\n",
" {% endfor %}\n",
"
\n",
"Portions of template code that need to be repeated in several places can be stored in a \n",
"separate file and included from all the templates to avoid repetition:\n",
"{% include 'common.html' %}\n",
"Yet another powerful way to reuse is through template inheritance, which is similar to\n",
"class inheritance in Python code. First, a base template is created with the name\n",
"base.html:\n",
"\n",
"\n",
" {% block head %}\n",
" {% block title %}{% endblock %} - My Application\n",
" {% endblock %}\n",
"\n",
"\n",
" {% block body %}\n",
" {% endblock %}\n",
"\n",
"\n",
"Base templates define blocks that can be overridden by derived templates. The Jinja2\n",
"block and endblock directives define blocks of content that are added to the base\n",
"template. In this example, there are blocks called head, title, and body; note that\n",
"title is contained by head. The following example is a derived template of the base\n",
"template:\n",
"The Jinja2 Template Engine \n",
"| \n",
"29\n",
"\n",
"{% extends \"base.html\" %}\n",
"{% block title %}Index{% endblock %}\n",
"{% block head %}\n",
" {{ super() }}\n",
" \n",
"{% endblock %}\n",
"{% block body %}\n",
"Hello, World!
\n",
"{% endblock %}\n",
"The extends directive declares that this template derives from base.html. This direc‐\n",
"tive is followed by new definitions for the three blocks defined in the base template,\n",
"which are inserted in the proper places. When a block has some content in both the\n",
"base and derived templates, the content from the derived template is used. Within\n",
"this block, the derived template can call super() to reference the contents of the\n",
"block in the base template. In the preceding example, this is done in the head block.\n",
"Real-world usage of all the control structures presented in this section will be shown\n",
"later, so you will have the opportunity to see how they work.\n",
"Bootstrap Integration with Flask-Bootstrap\n",
"Bootstrap is an open-source web browser framework from Twitter that provides user\n",
"interface components that help create clean and attractive web pages that are compat‐\n",
"ible with all modern web browsers used on desktop and mobile platforms.\n",
"Bootstrap is a client-side framework, so the server is not directly involved with it. All\n",
"the server needs to do is provide HTML responses that reference Bootstrap’s Cascad‐\n",
"ing Style Sheets (CSS) and JavaScript files, and instantiate the desired user interface\n",
"elements through HTML, CSS, and JavaScript code. The ideal place to do all this is in\n",
"templates.\n",
"The naive approach to integrating Bootstrap with the application is to make all the\n",
"necessary changes to the HTML templates, following the recommendations given by\n",
"the Bootstrap documentation. But this is an area where the use of a Flask extension\n",
"makes an integration task much simpler, while helping keep these changes nicely\n",
"organized.\n",
"The extension is called Flask-Bootstrap, and it can be installed with pip:\n",
"(venv) $ pip install flask-bootstrap\n",
"Flask extensions are initialized at the same time the application instance is created.\n",
"Example 3-4 shows the initialization of Flask-Bootstrap.\n",
"30 \n",
"| \n",
"Chapter 3: Templates\n",
"\n",
"Example 3-4. hello.py: Flask-Bootstrap initialization\n",
"from flask_bootstrap import Bootstrap\n",
"# ...\n",
"bootstrap = Bootstrap(app)\n",
"The extension is usually imported from a flask_ package, where is the\n",
"extension name. Most Flask extensions follow one of two consistent patterns for initi‐\n",
"alization. In Example 3-4, the extension is initialized by passing the application\n",
"instance as an argument in the constructor. You will learn about a more advanced\n",
"method to initialize extensions appropriate for larger applications in Chapter 7.\n",
"Once Flask-Bootstrap is initialized, a base template that includes all the Bootstrap\n",
"files and general structure is available to the application. The application then takes\n",
"advantage of Jinja2’s template inheritance to extend this base template. Example 3-5\n",
"shows a new version of user.html as a derived template.\n",
"Example 3-5. templates/user.html: template that uses Flask-Bootstrap\n",
"{% extends \"bootstrap/base.html\" %}\n",
"{% block title %}Flasky{% endblock %}\n",
"{% block navbar %}\n",
"\n",
"{% endblock %}\n",
"{% block content %}\n",
"\n",
" \n",
"Bootstrap Integration with Flask-Bootstrap \n",
"| \n",
"31\n",
"\n",
"
\n",
"{% endblock %}\n",
"The Jinja2 extends directive implements the template inheritance by referencing\n",
"bootstrap/base.html from Flask-Bootstrap. The base template from Flask-Bootstrap\n",
"provides a skeleton web page that includes all the Bootstrap CSS and JavaScript files.\n",
"The user.html template defines three blocks called title, navbar, and content. These\n",
"are all blocks that the base template exports for derived templates to define. The\n",
"title block is straightforward; its contents will appear between tags in the\n",
"header of the rendered HTML document. The navbar and content blocks are\n",
"reserved for the page navigation bar and main content.\n",
"In this template, the navbar block defines a simple navigation bar using Bootstrap\n",
"components. The content block has a container <div> with a page header inside. The\n",
"greeting line that was in the previous version of the template is now inside the page\n",
"header. Figure 3-1 shows how the application looks with these changes.\n",
"Figure 3-1. Bootstrap templates\n",
"If you have cloned the application’s Git repository on GitHub, you\n",
"can run git checkout 3b to check out this version of the applica‐\n",
"tion. The Flask-Bootstrap package also needs to be installed in your\n",
"virtual environment. The Bootstrap official documentation is a\n",
"great learning resource full of copy/paste-ready examples.\n",
"Flask-Bootstrap’s base.html template defines several other blocks that can be used in\n",
"derived templates. Table 3-2 shows the complete list of available blocks.\n",
"32 \n",
"| \n",
"Chapter 3: Templates\n",
"\n",
"Table 3-2. Flask-Bootstrap’s base template blocks\n",
"Block name\n",
"Description\n",
"doc\n",
"The entire HTML document\n",
"html_attribs\n",
"Attributes inside the <html> tag\n",
"html\n",
"The contents of the <html> tag\n",
"head\n",
"The contents of the <head> tag\n",
"title\n",
"The contents of the <title> tag\n",
"metas\n",
"The list of <meta> tags\n",
"styles\n",
"CSS definitions\n",
"body_attribs Attributes inside the <body> tag\n",
"body\n",
"The contents of the <body> tag\n",
"navbar\n",
"User-defined navigation bar\n",
"content\n",
"User-defined page content\n",
"scripts\n",
"JavaScript declarations at the bottom of the document\n",
"Many of the blocks in Table 3-2 are used by Flask-Bootstrap itself, so overriding them\n",
"directly would cause problems. For example, the styles and scripts blocks are\n",
"where the Bootstrap CSS and JavaScript files are declared. If the application needs to\n",
"add its own content to a block that already has some content, then Jinja2’s super()\n",
"function must be used. For example, this is how the scripts block would need to be\n",
"written in the derived template to add a new JavaScript file to the document:\n",
"{% block scripts %}\n",
"{{ super() }}\n",
"<script type=\"text/javascript\" src=\"my-script.js\"></script>\n",
"{% endblock %}\n",
"Custom Error Pages\n",
"When you enter an invalid route in your browser’s address bar, you get a code 404\n",
"error page. Compared to the Bootstrap-powered pages, the default error page is now\n",
"too plain and unattractive, and it has no consistency with the actual pages generated\n",
"by the application.\n",
"Flask allows an application to define custom error pages that can be based on tem‐\n",
"plates, like regular routes. The two most common error codes are 404, triggered when\n",
"the client requests a page or route that is not known, and 500, triggered when there is\n",
"an unhandled exception in the application. Example 3-6 shows how to provide cus‐\n",
"tom handlers for these two errors using the app.errorhandler decorator.\n",
"Custom Error Pages \n",
"| \n",
"33\n",
"\n",
"Example 3-6. hello.py: custom error pages\n",
"@app.errorhandler(404)\n",
"def page_not_found(e):\n",
" return render_template('404.html'), 404\n",
"@app.errorhandler(500)\n",
"def internal_server_error(e):\n",
" return render_template('500.html'), 500\n",
"Error handlers return a response, like view functions, but they also need to return the\n",
"numeric status code that corresponds to the error, which Flask conveniently accepts\n",
"as a second return value.\n",
"The templates referenced in the error handlers need to be written. These templates\n",
"should follow the same layout as the regular pages, so in this case they will have a\n",
"navigation bar and a page header that shows the error message.\n",
"The straightforward way to write these templates is to copy templates/user.html to\n",
"templates/404.html and templates/500.html and then change the page header elements\n",
"in these two new files to the appropriate error messages, but this will generate a lot of\n",
"duplication.\n",
"Jinja2’s template inheritance can help with this. In the same way Flask-Bootstrap pro‐\n",
"vides a base template with the basic layout of the page, the application can define its\n",
"own base template with a uniform page layout that includes the navigation bar and\n",
"leaves the page content to be defined in derived templates. Example 3-7 shows tem‐\n",
"plates/base.html, a new template that inherits from bootstrap/base.html and defines\n",
"the navigation bar but is itself a second-level base template to other templates such as\n",
"templates/user.html, templates/404.html, and templates/500.html.\n",
"Example 3-7. templates/base.html: base application template with navigation bar\n",
"{% extends \"bootstrap/base.html\" %}\n",
"{% block title %}Flasky{% endblock %}\n",
"{% block navbar %}\n",
"<div class=\"navbar navbar-inverse\" role=\"navigation\">\n",
" <div class=\"container\">\n",
" <div class=\"navbar-header\">\n",
" <button type=\"button\" class=\"navbar-toggle\"\n",
" data-toggle=\"collapse\" data-target=\".navbar-collapse\">\n",
" <span class=\"sr-only\">Toggle navigation</span>\n",
" <span class=\"icon-bar\"></span>\n",
" <span class=\"icon-bar\"></span>\n",
" <span class=\"icon-bar\"></span>\n",
" </button>\n",
" <a class=\"navbar-brand\" href=\"/\">Flasky</a>\n",
"34 \n",
"| \n",
"Chapter 3: Templates\n",
"\n",
" </div>\n",
" <div class=\"navbar-collapse collapse\">\n",
" <ul class=\"nav navbar-nav\">\n",
" <li><a href=\"/\">Home</a></li>\n",
" </ul>\n",
" </div>\n",
" </div>\n",
"</div>\n",
"{% endblock %}\n",
"{% block content %}\n",
"<div class=\"container\">\n",
" {% block page_content %}{% endblock %}\n",
"</div>\n",
"{% endblock %}\n",
"The content block of this template is just a container <div> element that wraps a new\n",
"empty block called page_content, which derived templates can define.\n",
"The templates of the application will now inherit from this template instead of\n",
"directly from Flask-Bootstrap. Example 3-8 shows how simple it is to construct a cus‐\n",
"tom code 404 error page that inherits from templates/base.html. The page for the 500\n",
"error is similar, and you can find it in the GitHub repository for the application.\n",
"Example 3-8. templates/404.html: custom code 404 error page using template\n",
"inheritance\n",
"{% extends \"base.html\" %}\n",
"{% block title %}Flasky - Page Not Found{% endblock %}\n",
"{% block page_content %}\n",
"<div class=\"page-header\">\n",
" <h1>Not Found</h1>\n",
"</div>\n",
"{% endblock %}\n",
"Figure 3-2 shows how the error page looks in the browser.\n",
"Custom Error Pages \n",
"| \n",
"35\n",
"\n",
"Figure 3-2. Custom code 404 error page\n",
"The templates/user.html template can now be simplified by making it inherit from the\n",
"base template, as shown in Example 3-9.\n",
"Example 3-9. templates/user.html: simplified page template using template inheritance\n",
"{% extends \"base.html\" %}\n",
"{% block title %}Flasky{% endblock %}\n",
"{% block page_content %}\n",
"<div class=\"page-header\">\n",
" <h1>Hello, {{ name }}!</h1>\n",
"</div>\n",
"{% endblock %}\n",
"If you have cloned the application’s Git repository on GitHub, you\n",
"can run git checkout 3c to check out this version of the applica‐\n",
"tion.\n",
"Links\n",
"Any application that has more than one route will invariably need to include links\n",
"that connect the different pages, such as in a navigation bar.\n",
"Writing the URLs as links directly in the template is trivial for simple routes, but for\n",
"dynamic routes with variable portions it can get more complicated to build the URLs\n",
"36 \n",
"| \n",
"Chapter 3: Templates\n",
"\n",
"right in the template. Also, URLs written explicitly create an unwanted dependency\n",
"on the routes defined in the code. If the routes are reorganized, links in templates\n",
"may break.\n",
"To avoid these problems, Flask provides the url_for() helper function, which gener‐\n",
"ates URLs from the information stored in the application’s URL map.\n",
"In its simplest usage, this function takes the view function name (or endpoint name\n",
"for routes defined with app.add_url_route()) as its single argument and returns its\n",
"URL. For example, in the current version of hello.py the call url_for('index')\n",
"would return /, the root URL of the application. Calling url_for('index',\n",
"_external=True) would instead return an absolute URL, which in this example is\n",
"http://localhost:5000/.\n",
"Relative URLs are sufficient when generating links that connect the\n",
"different routes of the application. Absolute URLs are necessary\n",
"only for links that will be used outside of the web browser, such as\n",
"when sending links by email.\n",
"Dynamic URLs can be generated with url_for() by passing the dynamic parts as\n",
"keyword \n",
"arguments. \n",
"For \n",
"example, \n",
"url_for('user', \n",
"name='john',\n",
"_external=True) would return http://localhost:5000/user/john.\n",
"Keyword arguments sent to url_for() are not limited to arguments used by dynamic\n",
"routes. The function will add any arguments that are not dynamic to the query string.\n",
"For example, url_for('user', name='john', page=2, version=1) would\n",
"return /user/john?page=2&version=1.\n",
"Static Files\n",
"Web applications are not made of Python code and templates alone. Most applica‐\n",
"tions also use static files such as images, JavaScript source files, and CSS files that are\n",
"all referenced from the HTML code in templates.\n",
"You may recall that when the hello.py application’s URL map was inspected in Chap‐\n",
"ter 2, a static entry appeared in it. Flask automatically supports static files by adding\n",
"a special route to the application defined as /static/<filename>. For example, a call\n",
"to url_for('static', filename='css/styles.css', _external=True) would\n",
"return http://localhost:5000/static/css/styles.css.\n",
"In its default configuration, Flask looks for static files in a subdirectory called static\n",
"located in the application’s root folder. Files can be organized in subdirectories inside\n",
"this folder if desired. When the server receives a URL that maps to a static route, it\n",
"Static Files \n",
"| \n",
"37\n",
"\n",
"generates a response that includes the contents of the corresponding file in the file\n",
"system.\n",
"Example 3-10 shows how the application can include a favicon.ico icon in the base\n",
"template for browsers to show in the address bar.\n",
"Example 3-10. templates/base.html: favicon definition\n",
"{% block head %}\n",
"{{ super() }}\n",
"<link rel=\"shortcut icon\" href=\"{{ url_for('static', filename='favicon.ico') }}\"\n",
" type=\"image/x-icon\">\n",
"<link rel=\"icon\" href=\"{{ url_for('static', filename='favicon.ico') }}\"\n",
" type=\"image/x-icon\">\n",
"{% endblock %}\n",
"The icon declaration is inserted at the end of the head block. Note how super() is\n",
"used to preserve the original contents of the block defined in the base templates.\n",
"If you have cloned the application’s Git repository on GitHub, you\n",
"can run git checkout 3d to check out this version of the applica‐\n",
"tion.\n",
"Localization of Dates and Times with Flask-Moment\n",
"Handling of dates and times in a web application is not a trivial problem when users\n",
"work in different parts of the world.\n",
"The server needs uniform time units that are independent of the location of each\n",
"user, so typically Coordinated Universal Time (UTC) is used. For users, however, see‐\n",
"ing times expressed in UTC can be confusing, as users always expect to see dates and\n",
"times presented in their local time and formatted according to the customs of their\n",
"region.\n",
"An elegant solution that allows the server to work exclusively in UTC is to send these\n",
"time units to the web browser, where they are converted to local time and rendered\n",
"using JavaScript. Web browsers can do a much better job at this task because they\n",
"have access to time zone and locale settings on the user’s computer.\n",
"There is an excellent open source library written in JavaScript that renders dates and\n",
"times in the browser called Moment.js. Flask-Moment is an extension for Flask appli‐\n",
"cations that makes the integration of Moment.js into Jinja2 templates very easy. Flask-\n",
"Moment is installed with pip:\n",
"(venv) $ pip install flask-moment\n",
"38 \n",
"| \n",
"Chapter 3: Templates\n",
"\n",
"The extension is initialized in a similar way to Flask-Bootstrap. The required code is\n",
"shown in Example 3-11.\n",
"Example 3-11. hello.py: initializing Flask-Moment\n",
"from flask_moment import Moment\n",
"moment = Moment(app)\n",
"Flask-Moment depends on jQuery.js in addition to Moment.js. These two libraries\n",
"need to be included somewhere in the HTML document—either directly, in which\n",
"case you can choose what versions to use, or through the helper functions provided\n",
"by the extension, which reference tested versions of these libraries from a content\n",
"delivery network (CDN). Because Bootstrap already includes jQuery.js, only\n",
"Moment.js needs to be added in this case. Example 3-12 shows how this library is\n",
"loaded in the scripts block of the template, while also preserving the original con‐\n",
"tents of the block provided by the base template. Note that since this is a predefined\n",
"block in the Flask-Bootstrap base template, the location in templates/base.html where\n",
"this block is inserted does not matter.\n",
"Example 3-12. templates/base.html: importing the Moment.js library\n",
"{% block scripts %}\n",
"{{ super() }}\n",
"{{ moment.include_moment() }}\n",
"{% endblock %}\n",
"To work with timestamps, Flask-Moment makes a moment object available to tem‐\n",
"plates. Example 3-13 demonstrates passing a variable called current_time to the tem‐\n",
"plate for rendering.\n",
"Example 3-13. hello.py: adding a datetime variable\n",
"from datetime import datetime\n",
"@app.route('/')\n",
"def index():\n",
" return render_template('index.html',\n",
" current_time=datetime.utcnow())\n",
"Example 3-14 shows how this current_time template variable is rendered.\n",
"Example 3-14. templates/index.html: timestamp rendering with Flask-Moment\n",
"<p>The local date and time is {{ moment(current_time).format('LLL') }}.</p>\n",
"<p>That was {{ moment(current_time).fromNow(refresh=True) }}</p>\n",
"Localization of Dates and Times with Flask-Moment \n",
"| \n",
"39\n",
"\n",
"The format('LLL') function renders the date and time according to the time zone\n",
"and locale settings in the client computer. The argument determines the rendering\n",
"style, from 'L' to 'LLLL' for four different levels of verbosity. The format() function\n",
"can also accept a long list of custom format specifiers.\n",
"The fromNow() render style shown in the second line renders a relative timestamp\n",
"and automatically refreshes it as time passes. Initially this timestamp will be shown as\n",
"“a few seconds ago,” but the refresh=True option will keep it updated as time passes,\n",
"so if you leave the page open for a few minutes you will see the text changing to “a\n",
"minute ago,” then “2 minutes ago,” and so on.\n",
"Figure 3-3 shows how the http://localhost:5000/ route looks after the two timestamps\n",
"are added to the index.html template.\n",
"Figure 3-3. Page with two Flask-Moment timestamps\n",
"If you have cloned the application’s Git repository on GitHub, you\n",
"can run git checkout 3e to check out this version of the applica‐\n",
"tion.\n",
"Flask-Moment implements the format(), fromNow(), fromTime(), calendar(),\n",
"valueOf(), and unix() methods from Moment.js. Consult the Moment.js documen‐\n",
"tation to learn about all the formatting options offered by this library.\n",
"40 \n",
"| \n",
"Chapter 3: Templates\n",
"\n",
"Flask-Moment assumes that timestamps handled by the server-side\n",
"application are “naive” datetime objects expressed in UTC. See the\n",
"documentation for the datetime package in the standard library\n",
"for information on naive and aware date and time objects.\n",
"The timestamps rendered by Flask-Moment can be localized to many languages. A\n",
"language can be selected in the template by passing the two-letter language code to\n",
"function locale(), right after the Moment.js library is included. For example, here is\n",
"how to configure Moment.js to use Spanish:\n",
"{% block scripts %}\n",
"{{ super() }}\n",
"{{ moment.include_moment() }}\n",
"{{ moment.locale('es') }}\n",
"{% endblock %}\n",
"With all the techniques discussed in this chapter, you should be able to build modern\n",
"and user-friendly web pages for your application. The next chapter touches on an\n",
"aspect of templates not yet discussed: how to interact with the user through web\n",
"forms.\n",
"Localization of Dates and Times with Flask-Moment \n",
"| \n",
"41\n",
"\n",
"\n",
"CHAPTER 4\n",
"Web Forms\n",
"The templates that you worked with in Chapter 3 are unidirectional, in the sense that\n",
"they allow information to flow from the server to the user. For most applications,\n",
"however, there is also a need to have information that flows in the other direction,\n",
"with the user providing data that the server accepts and processes.\n",
"With HTML, it is possible to create web forms, in which users can enter information.\n",
"The form data is then submitted by the web browser to the server, typically in the\n",
"form of a POST request. The Flask request object, introduced in Chapter 2, exposes all\n",
"the information sent by the client in a request and, in particular for POST requests\n",
"containing form data, provides access to the user information through request.form.\n",
"Although the support provided in Flask’s request object is sufficient for the handling\n",
"of web forms, there are a number of tasks that can become tedious and repetitive.\n",
"Two good examples are the generation of HTML code for the forms and the valida‐\n",
"tion of the submitted form data.\n",
"The Flask-WTF extension makes working with web forms a much more pleasant\n",
"experience. This extension is a Flask integration wrapper around the framework-\n",
"agnostic WTForms package.\n",
"Flask-WTF and its dependencies can be installed with pip:\n",
"(venv) $ pip install flask-wtf\n",
"43\n",
"\n",
"Configuration\n",
"Unlike most other extensions, Flask-WTF does not need to be initialized at the appli‐\n",
"cation level, but it expects the application to have a secret key configured. A secret key\n",
"is a string with any random and unique content that is used as an encryption or sign‐\n",
"ing key to improve the security of the application in several ways. Flask uses this key\n",
"to protect the contents of the user session against tampering. You should pick a dif‐\n",
"ferent secret key in each application that you build and make sure that this string is\n",
"not known by anyone. Example 4-1 shows how to configure a secret key in a Flask\n",
"application.\n",
"Example 4-1. hello.py: Flask-WTF configuration\n",
"app = Flask(__name__)\n",
"app.config['SECRET_KEY'] = 'hard to guess string'\n",
"The app.config dictionary is a general-purpose place to store configuration variables\n",
"used by Flask, extensions, or the application itself. Configuration values can be added\n",
"to the app.config object using standard dictionary syntax. The configuration object\n",
"also has methods to import configuration values from files or the environment. A\n",
"more practical way to manage configuration values for a larger application will be\n",
"discussed in Chapter 7.\n",
"Flask-WTF requires a secret key to be configured in the application because this key\n",
"is part of the mechanism the extension uses to protect all forms against cross-site\n",
"request forgery (CSRF) attacks. A CSRF attack occurs when a malicious website sends\n",
"requests to the application server on which the user is currently logged in. Flask-WTF\n",
"generates security tokens for all forms and stores them in the user session, which is\n",
"protected with a cryptographic signature generated from the secret key.\n",
"For added security, the secret key should be stored in an environ‐\n",
"ment variable instead of being embedded in the source code. This\n",
"technique is described in Chapter 7.\n",
"Form Classes\n",
"When using Flask-WTF, each web form is represented in the server by a class that\n",
"inherits from the class FlaskForm. The class defines the list of fields in the form, each\n",
"represented by an object. Each field object can have one or more validators attached.\n",
"A validator is a function that checks whether the data submitted by the user is valid.\n",
"44 \n",
"| \n",
"Chapter 4: Web Forms\n",
"\n",
"Example 4-2 shows a simple web form that has a text field and a submit button.\n",
"Example 4-2. hello.py: form class definition\n",
"from flask_wtf import FlaskForm\n",
"from wtforms import StringField, SubmitField\n",
"from wtforms.validators import DataRequired\n",
"class NameForm(FlaskForm):\n",
" name = StringField('What is your name?', validators=[DataRequired()])\n",
" submit = SubmitField('Submit')\n",
"The fields in the form are defined as class variables, and each class variable is assigned\n",
"an object associated with the field type. In this example, the NameForm form has a text\n",
"field called name and a submit button called submit. The StringField class repre‐\n",
"sents an HTML <input> element with a type=\"text\" attribute. The SubmitField\n",
"class represents an HTML <input> element with a type=\"submit\" attribute. The first\n",
"argument to the field constructors is the label that will be used when rendering the\n",
"form to HTML.\n",
"The optional validators argument included in the StringField constructor defines\n",
"a list of checkers that will be applied to the data submitted by the user before it is\n",
"accepted. The DataRequired() validator ensures that the field is not submitted\n",
"empty.\n",
"The FlaskForm base class is defined by the Flask-WTF extension,\n",
"so it is imported from flask_wtf. The fields and validators, how‐\n",
"ever, are imported directly from the WTForms package.\n",
"The list of standard HTML fields supported by WTForms is shown in Table 4-1.\n",
"Table 4-1. WTForms standard HTML fields\n",
"Field type\n",
"Description\n",
"BooleanField\n",
"Checkbox with True and False values\n",
"DateField\n",
"Text field that accepts a datetime.date value in a given format\n",
"DateTimeField\n",
"Text field that accepts a datetime.datetime value in a given format\n",
"DecimalField\n",
"Text field that accepts a decimal.Decimal value\n",
"FileField\n",
"File upload field\n",
"HiddenField\n",
"Hidden text field\n",
"MultipleFileField\n",
"Multiple file upload field\n",
"FieldList\n",
"List of fields of a given type\n",
"Form Classes \n",
"| \n",
"45\n",
"\n",
"Field type\n",
"Description\n",
"FloatField\n",
"Text field that accepts a floating-point value\n",
"FormField\n",
"Form embedded as a field in a container form\n",
"IntegerField\n",
"Text field that accepts an integer value\n",
"PasswordField\n",
"Password text field\n",
"RadioField\n",
"List of radio buttons\n",
"SelectField\n",
"Drop-down list of choices\n",
"SelectMultipleField\n",
"Drop-down list of choices with multiple selection\n",
"SubmitField\n",
"Form submission button\n",
"StringField\n",
"Text field\n",
"TextAreaField\n",
"Multiple-line text field\n",
"The list of WTForms built-in validators is shown in Table 4-2.\n",
"Table 4-2. WTForms validators\n",
"Validator\n",
"Description\n",
"DataRequired\n",
"Validates that the field contains data after type conversion\n",
"Email\n",
"Validates an email address\n",
"EqualTo\n",
"Compares the values of two fields; useful when requesting a password to be entered twice for\n",
"confirmation\n",
"InputRequired Validates that the field contains data before type conversion\n",
"IPAddress\n",
"Validates an IPv4 network address\n",
"Length\n",
"Validates the length of the string entered\n",
"MacAddress\n",
"Validates a MAC address\n",
"NumberRange\n",
"Validates that the value entered is within a numeric range\n",
"Optional\n",
"Allows empty input in the field, skipping additional validators\n",
"Regexp\n",
"Validates the input against a regular expression\n",
"URL\n",
"Validates a URL\n",
"UUID\n",
"Validates a UUID\n",
"AnyOf\n",
"Validates that the input is one of a list of possible values\n",
"NoneOf\n",
"Validates that the input is none of a list of possible values\n",
"46 \n",
"| \n",
"Chapter 4: Web Forms\n",
"\n",
"HTML Rendering of Forms\n",
"Form fields are callables that, when invoked from a template, render themselves to\n",
"HTML. Assuming that the view function passes a NameForm instance to the template\n",
"as an argument named form, the template can generate a simple HTML form as\n",
"follows:\n",
"<form method=\"POST\">\n",
" {{ form.hidden_tag() }}\n",
" {{ form.name.label }} {{ form.name() }}\n",
" {{ form.submit() }}\n",
"</form>\n",
"Note that in addition to the name and submit fields, the form has a\n",
"form.hidden_tag() element. This element defines an extra form field that is hidden,\n",
"used by Flask-WTF to implement CSRF protection.\n",
"Of course, the result of rendering a web form in this way is extremely bare. Any key‐\n",
"word arguments added to the calls that render the fields are converted into HTML\n",
"attributes for the field—so, for example, you can give the field id or class attributes\n",
"and then define CSS styles for them:\n",
"<form method=\"POST\">\n",
" {{ form.hidden_tag() }}\n",
" {{ form.name.label }} {{ form.name(id='my-text-field') }}\n",
" {{ form.submit() }}\n",
"</form>\n",
"But even with HTML attributes, the effort required to render a form in this way and\n",
"make it look good is significant, so it is best to leverage Bootstrap’s own set of form\n",
"styles whenever possible. The Flask-Bootstrap extension provides a high-level helper\n",
"function that renders an entire Flask-WTF form using Bootstrap’s predefined form\n",
"styles, all with a single call. Using Flask-Bootstrap, the previous form can be rendered\n",
"as follows:\n",
"{% import \"bootstrap/wtf.html\" as wtf %}\n",
"{{ wtf.quick_form(form) }}\n",
"The import directive works in the same way as regular Python scripts do and allows\n",
"template elements to be imported and used in many templates. The imported boot‐\n",
"strap/wtf.html file defines helper functions that render Flask-WTF forms using Boot‐\n",
"strap. The wtf.quick_form() function takes a Flask-WTF form object and renders it\n",
"using default Bootstrap styles. The complete template for hello.py is shown in\n",
"Example 4-3.\n",
"HTML Rendering of Forms \n",
"| \n",
"47\n",
"\n",
"Example 4-3. templates/index.html: using Flask-WTF and Flask-Bootstrap to render a\n",
"form\n",
"{% extends \"base.html\" %}\n",
"{% import \"bootstrap/wtf.html\" as wtf %}\n",
"{% block title %}Flasky{% endblock %}\n",
"{% block page_content %}\n",
"<div class=\"page-header\">\n",
" <h1>Hello, {% if name %}{{ name }}{% else %}Stranger{% endif %}!</h1>\n",
"</div>\n",
"{{ wtf.quick_form(form) }}\n",
"{% endblock %}\n",
"The content area of the template now has two sections. The first section is a page\n",
"header that shows a greeting. Here a template conditional is used. Conditionals in\n",
"Jinja2 have the format {% if condition %}...{% else %}...{% endif %}. If the\n",
"condition evaluates to True, then what appears between the if and else directives is\n",
"added to the rendered template. If the condition evaluates to False, then what’s\n",
"between the else and endif is rendered instead. The purpose of this is to render\n",
"Hello, {{ name }}! when the name template variable is defined, or the string Hello,\n",
"Stranger! when it is not. The second section of the content renders the NameForm\n",
"form using the wtf.quick_form() function.\n",
"Form Handling in View Functions\n",
"In the new version of hello.py, the index() view function will have two tasks. First it\n",
"will render the form, and then it will receive the form data entered by the user.\n",
"Example 4-4 shows the updated index() view function.\n",
"Example 4-4. hello.py: handle a web form with GET and POST request methods\n",
"@app.route('/', methods=['GET', 'POST'])\n",
"def index():\n",
" name = None\n",
" form = NameForm()\n",
" if form.validate_on_submit():\n",
" name = form.name.data\n",
" form.name.data = ''\n",
" return render_template('index.html', form=form, name=name)\n",
"The methods argument added to the app.route decorator tells Flask to register the\n",
"view function as a handler for GET and POST requests in the URL map. When methods\n",
"is not given, the view function is registered to handle GET requests only.\n",
"48 \n",
"| \n",
"Chapter 4: Web Forms\n",
"\n",
"Adding POST to the method list is necessary because form submissions are much\n",
"more conveniently handled as POST requests. It is possible to submit a form as a GET\n",
"request, but as GET requests have no body, the data is appended to the URL as a query\n",
"string and becomes visible in the browser’s address bar. For this and several other rea‐\n",
"sons, form submissions are almost universally done as POST requests.\n",
"The local name variable is used to hold the name received from the form when avail‐\n",
"able; when the name is not known, the variable is initialized to None. The view func‐\n",
"tion creates an instance of the NameForm class shown previously to represent the form. \n",
"The validate_on_submit() method of the form returns True when the form was\n",
"submitted and the data was accepted by all the field validators. In all other cases,\n",
"validate_on_submit() returns False. The return value of this method effectively\n",
"serves to determine whether the form needs to be rendered or processed.\n",
"When a user navigates to the application for the first time, the server will receive a\n",
"GET request with no form data, so validate_on_submit() will return False. The\n",
"body of the if statement will be skipped and the request will be handled by rendering\n",
"the template, which gets the form object and the name variable set to None as argu‐\n",
"ments. Users will now see the form displayed in the browser.\n",
"When the form is submitted by the user, the server receives a POST request with the\n",
"data. The call to validate_on_submit() invokes the DataRequired() validator\n",
"attached to the name field. If the name is not empty, then the validator accepts it and\n",
"validate_on_submit() returns True. Now the name entered by the user is accessible\n",
"as the data attribute of the field. Inside the body of the if statement, this name is\n",
"assigned to the local name variable and the form field is cleared by setting that data\n",
"attribute to an empty string, so that the field is blanked when the form is rendered to\n",
"the page again. The render_template() call in the last line renders the template, but\n",
"this time the name argument contains the name from the form, so the greeting will be\n",
"personalized.\n",
"If you have cloned the application’s Git repository on GitHub, you\n",
"can run git checkout 4a to check out this version of the applica‐\n",
"tion.\n",
"Figure 4-1 shows how the form looks in the browser window when a user initially\n",
"enters the site. When the user submits a name, the application responds with a per‐\n",
"sonalized greeting. The form still appears below it, so a user can submit it multiple\n",
"times with different names if desired. Figure 4-2 shows the application in this state.\n",
"Form Handling in View Functions \n",
"| \n",
"49\n",
"\n",
"Figure 4-1. Flask-WTF web form\n",
"Figure 4-2. Web form after submission\n",
"50 \n",
"| \n",
"Chapter 4: Web Forms\n",
"\n",
"If the user submits the form with an empty name, the DataRequired() validator\n",
"catches the error, as seen in Figure 4-3. Note how much functionality is being pro‐\n",
"vided automatically. This is a great example of the power that well-designed exten‐\n",
"sions like Flask-WTF and Flask-Bootstrap can give to your application.\n",
"Figure 4-3. Web form after failed validator\n",
"Redirects and User Sessions\n",
"The last version of hello.py has a usability problem. If you enter your name and sub‐\n",
"mit it, and then click the refresh button in your browser, you will likely get an\n",
"obscure warning that asks for confirmation before submitting the form again. This\n",
"happens because browsers repeat the last request they sent when they are asked to\n",
"refresh a page. When the last request sent is a POST request with form data, a refresh\n",
"would cause a duplicate form submission, which in almost all cases is not the desired\n",
"action. For that reason, the browser asks for confirmation from the user.\n",
"Many users do not understand this warning from the browser. Consequently, it is\n",
"considered good practice for web applications to never leave a POST request as the last\n",
"request sent by the browser.\n",
"This is achieved by responding to POST requests with a redirect instead of a normal\n",
"response. A redirect is a special type of response that contains a URL instead of a\n",
"string with HTML code. When the browser receives a redirect response, it issues a\n",
"Redirects and User Sessions \n",
"| \n",
"51\n",
"\n",
"GET request for the redirect URL, and that is the page that it displays. The page may\n",
"take a few more milliseconds to load because of the second request that has to be sent\n",
"to the server, but other than that, the user will not see any difference. Now the last\n",
"request is a GET, so the refresh command works as expected. This trick is known as\n",
"the Post/Redirect/Get pattern.\n",
"But this approach brings a second problem. When the application handles the POST\n",
"request, it has access to the name entered by the user in form.name.data, but as soon\n",
"as that request ends the form data is lost. Because the POST request is handled with a\n",
"redirect, the application needs to store the name so that the redirected request can\n",
"have it and use it to build the actual response.\n",
"Applications can “remember” things from one request to the next by storing them in\n",
"the user session, a private storage that is available to each connected client. The user\n",
"session was introduced in Chapter 2 as one of the variables associated with the\n",
"request context. It’s called session and is accessed like a standard Python dictionary.\n",
"By default, user sessions are stored in client-side cookies that are\n",
"cryptographically signed using the configured secret key. Any tam‐\n",
"pering with the cookie content would render the signature invalid,\n",
"thus invalidating the session.\n",
"Example 4-5 shows a new version of the index() view function that implements redi‐\n",
"rects and user sessions.\n",
"Example 4-5. hello.py: redirects and user sessions\n",
"from flask import Flask, render_template, session, redirect, url_for\n",
"@app.route('/', methods=['GET', 'POST'])\n",
"def index():\n",
" form = NameForm()\n",
" if form.validate_on_submit():\n",
" session['name'] = form.name.data\n",
" return redirect(url_for('index'))\n",
" return render_template('index.html', form=form, name=session.get('name'))\n",
"In the previous version of the application, a local name variable was used to store the\n",
"name entered by the user in the form. That variable is now placed in the user session\n",
"as session['name'] so that it is remembered beyond the request.\n",
"52 \n",
"| \n",
"Chapter 4: Web Forms\n",
"\n",
"Requests that come with valid form data will now end with a call to redirect(), a\n",
"Flask helper function that generates the HTTP redirect response. The redirect()\n",
"function takes the URL to redirect to as an argument. The redirect URL used in this\n",
"case is the root URL, so the response could have been written more concisely as\n",
"redirect('/'), but instead Flask’s URL generator function url_for(), introduced in\n",
"Chapter 3, is used.\n",
"The first and only required argument to url_for() is the endpoint name, the internal\n",
"name each route has. By default, the endpoint of a route is the name of the view func‐\n",
"tion attached to it. In this example, the view function that handles the root URL is\n",
"index(), so the name given to url_for() is index.\n",
"The last change is in the render_template() function, which now obtains the name\n",
"argument directly from the session using session.get('name'). As with regular dic‐\n",
"tionaries, using get() to request a dictionary key avoids an exception for keys that\n",
"aren’t found. The get() method returns a default value of None for a missing key.\n",
"If you have cloned the application’s Git repository on GitHub, you\n",
"can run git checkout 4b to check out this version of the applica‐\n",
"tion.\n",
"With this version of the application, you can see that refreshing the page in your\n",
"browser always results in the expected behavior.\n",
"Message Flashing\n",
"Sometimes it is useful to give the user a status update after a request is completed.\n",
"This could be a confirmation message, a warning, or an error. A typical example is\n",
"when you submit a login form to a website with a mistake and the server responds by\n",
"rendering the login form again with a message above it that informs you that your\n",
"username or password is invalid.\n",
"Flask includes this functionality as a core feature. Example 4-6 shows how the\n",
"flash() function can be used for this purpose.\n",
"Message Flashing \n",
"| \n",
"53\n",
"\n",
"Example 4-6. hello.py: flashed messages\n",
"from flask import Flask, render_template, session, redirect, url_for, flash\n",
"@app.route('/', methods=['GET', 'POST'])\n",
"def index():\n",
" form = NameForm()\n",
" if form.validate_on_submit():\n",
" old_name = session.get('name')\n",
" if old_name is not None and old_name != form.name.data:\n",
" flash('Looks like you have changed your name!')\n",
" session['name'] = form.name.data\n",
" return redirect(url_for('index'))\n",
" return render_template('index.html',\n",
" form = form, name = session.get('name'))\n",
"In this example, each time a name is submitted it is compared against the name\n",
"stored in the user session, which will have been put there during a previous submis‐\n",
"sion of the same form. If the two names are different, the flash() function is invoked\n",
"with a message to be displayed on the next response sent back to the client.\n",
"Calling flash() is not enough to get messages displayed; the templates used by the\n",
"application need to render these messages. The best place to render flashed messages\n",
"is the base template, because that will enable these messages in all pages. Flask makes\n",
"a get_flashed_messages() function available to templates to retrieve the messages\n",
"and render them, as shown in Example 4-7.\n",
"Example 4-7. templates/base.html: rendering of flashed messages\n",
"{% block content %}\n",
"<div class=\"container\">\n",
" {% for message in get_flashed_messages() %}\n",
" <div class=\"alert alert-warning\">\n",
" <button type=\"button\" class=\"close\" data-dismiss=\"alert\">×</button>\n",
" {{ message }}\n",
" </div>\n",
" {% endfor %}\n",
" {% block page_content %}{% endblock %}\n",
"</div>\n",
"{% endblock %}\n",
"In this example, messages are rendered using Bootstrap’s alert CSS styles for warning\n",
"messages (one is shown in Figure 4-4).\n",
"54 \n",
"| \n",
"Chapter 4: Web Forms\n",
"\n",
"Figure 4-4. Flashed message\n",
"A loop is used because there could be multiple messages queued for display, one for\n",
"each time flash() was called in the previous request cycle. Messages that are\n",
"retrieved from get_flashed_messages() will not be returned the next time this func‐\n",
"tion is called, so flashed messages appear only once and are then discarded.\n",
"If you have cloned the application’s Git repository on GitHub, you\n",
"can run git checkout 4c to check out this version of the applica‐\n",
"tion.\n",
"Being able to accept data from the user through web forms is a feature required by\n",
"most applications, and so is the ability to store that data in permanent storage. Using\n",
"databases with Flask is the topic of the next chapter.\n",
"Message Flashing \n",
"| \n",
"55\n",
"\n",
"\n",
"CHAPTER 5\n",
"Databases\n",
"A database stores application data in an organized way. The application then issues\n",
"queries to retrieve specific portions of the data as they are needed. The most com‐\n",
"monly used databases for web applications are those based on the relational model,\n",
"also called SQL databases in reference to the Structured Query Language they use.\n",
"But in recent years document-oriented and key-value databases, informally known\n",
"together as NoSQL databases, have become popular alternatives.\n",
"SQL Databases\n",
"Relational databases store data in tables, which model the different entities in the\n",
"application’s domain. For example, a database for an order management application\n",
"will likely have customers, products, and orders tables.\n",
"A table has a fixed number of columns and a variable number of rows. The columns\n",
"define the data attributes of the entity represented by the table. For example, a\n",
"customers table will have columns such as name, address, phone, and so on. Each\n",
"row in a table defines an actual data element that assigns values to some or all the\n",
"columns.\n",
"Tables have a special column called the primary key, which holds a unique identifier\n",
"for each row stored in the table. Tables can also have columns called foreign keys,\n",
"which reference the primary key of a row in the same or another table. These links\n",
"between rows are called relationships and are the foundation of the relational database\n",
"model.\n",
"Figure 5-1 shows a diagram of a simple database with two tables that store users and\n",
"user roles. The line that connects the two tables represents a relationship between the\n",
"tables.\n",
"57\n",
"\n",
"Figure 5-1. Relational database example\n",
"This graphical style of representing the structure of a database is called an entity-\n",
"relationship diagram. In this representation, boxes represent database tables, showing\n",
"lists of the table’s attributes or columns. The roles table stores the list of all possible\n",
"user roles, each identified by a unique id value—the table’s primary key. The users\n",
"table contains the list of users, each with its own unique id as well. Besides the id\n",
"primary keys, the roles table has a name column and the users table has username\n",
"and password columns.\n",
"The role_id column in the users table is a foreign key. The line that connects the\n",
"roles.id and users.role_id columns represents a relationship between the two\n",
"tables. The symbols attached to the line at each end indicate the cardinality of the\n",
"relationship. On the roles.id side, the line is shown to have a “one,” while on the\n",
"users.role_id side a “many” is represented. This depicts a one-to-many relationship,\n",
"indicating that each row from the roles table can be associated with many rows from\n",
"the users table.\n",
"As seen in the example, relational databases store data efficiently and avoid duplica‐\n",
"tion. Renaming a user role in this database is simple because role names exist in a\n",
"single place. Immediately after a role name is changed in the roles table, all users\n",
"that have a role_id that references the changed role will see the update.\n",
"On the other hand, having the data split into multiple tables can be a complication.\n",
"Producing a listing of users with their roles presents a small problem, because users\n",
"and user roles need to be read from two tables and joined before they can be presen‐\n",
"ted together. Relational database engines provide the support to perform join opera‐\n",
"tions between tables when necessary.\n",
"NoSQL Databases\n",
"Databases that do not follow the relational model described in the previous section\n",
"are collectively referred to as NoSQL databases. One common organization for\n",
"NoSQL databases uses collections instead of tables and documents instead of records.\n",
"NoSQL databases are designed in a way that makes joins difficult, so most of them do\n",
"not support this operation at all. For a NoSQL database structured as in Figure 5-1,\n",
"58 \n",
"| \n",
"Chapter 5: Databases\n",
"\n",
"listing the users with their roles requires the application itself to perform the join\n",
"operation by reading the role_id field of each user and then searching the roles\n",
"table for it.\n",
"A more appropriate design for a NoSQL database is shown in Figure 5-2. This is the\n",
"result of applying an operation called denormalization, which reduces the number of\n",
"tables at the expense of data duplication.\n",
"Figure 5-2. NoSQL database example\n",
"A database with this structure has the role name explicitly stored with each user.\n",
"Renaming a role can then turn out to be an expensive operation that may require\n",
"updating a large number of documents.\n",
"But it isn’t all bad news with NoSQL databases. Having the data duplicated allows for\n",
"faster querying. Listing users and their roles is straightforward because no joins are\n",
"needed.\n",
"SQL or NoSQL?\n",
"SQL databases excel at storing structured data in an efficient and compact form.\n",
"These databases go to great lengths to preserve consistency, even in the face of power\n",
"failures or hardware malfunctions. The paradigm that allows relational databases to\n",
"reach this high level of reliability is called ACID, which stands for Atomicity, Consis‐\n",
"tency, Isolation, and Durability. NoSQL databases relax some of the ACID require‐\n",
"ments and as a result can sometimes get a performance edge.\n",
"A full analysis and comparison of database types is outside the scope of this book. For\n",
"small to medium-sized applications, both SQL and NoSQL databases are perfectly\n",
"capable and have practically equivalent performance.\n",
"Python Database Frameworks\n",
"Python has packages for most database engines, both open source and commercial.\n",
"Flask puts no restrictions on what database packages can be used, so you can work\n",
"with MySQL, Postgres, SQLite, Redis, MongoDB, CouchDB, or DynamoDB if any of\n",
"these is your favorite.\n",
"SQL or NoSQL? \n",
"| \n",
"59\n",
"\n",
"As if those weren’t enough choices, there are also a number of database abstraction\n",
"layer packages, such as SQLAlchemy or MongoEngine, that allow you to work at a\n",
"higher level with regular Python objects instead of database entities such as tables,\n",
"documents, or query languages.\n",
"There are a number of factors to evaluate when choosing a database framework:\n",
"Ease of use\n",
"When comparing straight database engines to database abstraction layers, the\n",
"second group clearly wins. Abstraction layers, also called object-relational map‐\n",
"pers (ORMs) or object-document mappers (ODMs), provide transparent conver‐\n",
"sion of high-level object-oriented operations into low-level database instructions.\n",
"Performance\n",
"The conversions that ORMs and ODMs have to do to translate from the object\n",
"domain into the database domain have an overhead. In most cases, the perfor‐\n",
"mance penalty is negligible, but it may not always be. In general, the productivity\n",
"gain obtained with ORMs and ODMs far outweighs a minimal performance deg‐\n",
"radation, so this isn’t a valid argument to drop ORMs and ODMs completely.\n",
"What makes sense is to choose a database abstraction layer that provides optional\n",
"access to the underlying database in case specific operations need to be optimized\n",
"by implementing them directly as native database instructions.\n",
"Portability\n",
"The database choices available on your development and production platforms\n",
"must be considered. For example, if you plan to host your application on a cloud\n",
"platform, then you should find out what database choices this service offers.\n",
"Another portability aspect applies to ORMs and ODMs. Although some of these\n",
"frameworks provide an abstraction layer for a single database engine, others\n",
"abstract even higher and provide a choice of database engines—all accessible\n",
"with the same object-oriented interface. The best example of this is the SQL‐\n",
"Alchemy ORM, which supports a list of relational database engines including the\n",
"popular MySQL, Postgres, and SQLite.\n",
"Flask integration\n",
"Choosing a framework that has integration with Flask is not absolutely required,\n",
"but it will save you from having to write the integration code yourself. Flask inte‐\n",
"gration could simplify configuration and operation, so using a package specifi‐\n",
"cally designed as a Flask extension should be preferred.\n",
"Based on these goals, the chosen database framework for the examples in this book\n",
"will be Flask-SQLAlchemy, the Flask extension wrapper for SQLAlchemy.\n",
"60 \n",
"| \n",
"Chapter 5: Databases\n",
"\n",
"Database Management with Flask-SQLAlchemy\n",
"Flask-SQLAlchemy is a Flask extension that simplifies the use of SQLAlchemy inside\n",
"Flask applications. SQLAlchemy is a powerful relational database framework that\n",
"supports several database backends. It offers a high-level ORM and low-level access\n",
"to the database’s native SQL functionality.\n",
"Like most other extensions, Flask-SQLAlchemy is installed with pip:\n",
"(venv) $ pip install flask-sqlalchemy\n",
"In Flask-SQLAlchemy, a database is specified as a URL. Table 5-1 lists the format of\n",
"the URLs for the three most popular database engines.\n",
"Table 5-1. Flask-SQLAlchemy database URLs\n",
"Database engine\n",
"URL\n",
"MySQL\n",
"mysql://username:password@hostname/database\n",
"Postgres\n",
"postgresql://username:password@hostname/database\n",
"SQLite (Linux, macOS) sqlite:////absolute/path/to/database\n",
"SQLite (Windows)\n",
"sqlite:///c:/absolute/path/to/database\n",
"In these URLs, hostname refers to the server that hosts the database service, which\n",
"could be localhost or a remote server. Database servers can host several databases, so\n",
"database indicates the name of the database to use. For databases that need authenti‐\n",
"cation, username and password are the database user credentials.\n",
"SQLite databases do not have a server, so hostname, username, and\n",
"password are omitted and database is the filename on disk for the\n",
"database.\n",
"The URL of the application database must be configured as the key\n",
"SQLALCHEMY_DATABASE_URI in the Flask configuration object. The Flask-SQLAlchemy\n",
"documentation also suggests setting key SQLALCHEMY_TRACK_MODIFICATIONS to False\n",
"to use less memory unless signals for object changes are needed. Consult the Flask-\n",
"SQLAlchemy documentation for information on other configuration options.\n",
"Example 5-1 shows how to initialize and configure a simple SQLite database.\n",
"Example 5-1. hello.py: database configuration\n",
"import os\n",
"from flask_sqlalchemy import SQLAlchemy\n",
"basedir = os.path.abspath(os.path.dirname(__file__))\n",
"Database Management with Flask-SQLAlchemy \n",
"| \n",
"61\n",
"\n",
"app = Flask(__name__)\n",
"app.config['SQLALCHEMY_DATABASE_URI'] =\\\n",
" 'sqlite:///' + os.path.join(basedir, 'data.sqlite')\n",
"app.config['SQLALCHEMY_TRACK_MODIFICATIONS'] = False\n",
"db = SQLAlchemy(app)\n",
"The db object instantiated from the class SQLAlchemy represents the database and\n",
"provides access to all the functionality of Flask-SQLAlchemy.\n",
"Model Definition\n",
"The term model is used when referring to the persistent entities used by the applica‐\n",
"tion. In the context of an ORM, a model is typically a Python class with attributes that\n",
"match the columns of a corresponding database table.\n",
"The database instance from Flask-SQLAlchemy provides a base class for models as\n",
"well as a set of helper classes and functions that are used to define their structure. The\n",
"roles and users tables from Figure 5-1 can be defined as the models Role and User\n",
"as shown in Example 5-2.\n",
"Example 5-2. hello.py: Role and User model definition\n",
"class Role(db.Model):\n",
" __tablename__ = 'roles'\n",
" id = db.Column(db.Integer, primary_key=True)\n",
" name = db.Column(db.String(64), unique=True)\n",
" def __repr__(self):\n",
" return '<Role %r>' % self.name\n",
"class User(db.Model):\n",
" __tablename__ = 'users'\n",
" id = db.Column(db.Integer, primary_key=True)\n",
" username = db.Column(db.String(64), unique=True, index=True)\n",
" def __repr__(self):\n",
" return '<User %r>' % self.username\n",
"The __tablename__ class variable defines the name of the table in the database. Flask-\n",
"SQLAlchemy assigns a default table name if __tablename__ is omitted, but those\n",
"default names do not follow the popular convention of using plurals for table names,\n",
"so it is best to name tables explicitly. The remaining class variables are the attributes\n",
"of the model, defined as instances of the db.Column class.\n",
"62 \n",
"| \n",
"Chapter 5: Databases\n",
"\n",
"The first argument given to the db.Column constructor is the type of the database col‐\n",
"umn and model attribute. Table 5-2 lists some of the column types that are available,\n",
"along with the Python types used in the model.\n",
"Table 5-2. Most common SQLAlchemy column types\n",
"Type name\n",
"Python type\n",
"Description\n",
"Integer\n",
"int\n",
"Regular integer, typically 32 bits\n",
"SmallInteger\n",
"int\n",
"Short-range integer, typically 16 bits\n",
"BigInteger\n",
"int or long\n",
"Unlimited precision integer\n",
"Float\n",
"float\n",
"Floating-point number\n",
"Numeric\n",
"decimal.Decimal\n",
"Fixed-point number\n",
"String\n",
"str\n",
"Variable-length string\n",
"Text\n",
"str\n",
"Variable-length string, optimized for large or unbounded length\n",
"Unicode\n",
"unicode\n",
"Variable-length Unicode string\n",
"UnicodeText\n",
"unicode\n",
"Variable-length Unicode string, optimized for large or unbounded length\n",
"Boolean\n",
"bool\n",
"Boolean value\n",
"Date\n",
"datetime.date\n",
"Date value\n",
"Time\n",
"datetime.time\n",
"Time value\n",
"DateTime\n",
"datetime.datetime\n",
"Date and time value\n",
"Interval\n",
"datetime.timedelta Time interval\n",
"Enum\n",
"str\n",
"List of string values\n",
"PickleType\n",
"Any Python object\n",
"Automatic Pickle serialization\n",
"LargeBinary\n",
"str\n",
"Binary blob\n",
"The remaining arguments to db.Column specify configuration options for each\n",
"attribute. Table 5-3 lists some of the options available.\n",
"Table 5-3. Most common SQLAlchemy column options\n",
"Option name\n",
"Description\n",
"primary_key\n",
"If set to True, the column is the table’s primary key.\n",
"unique\n",
"If set to True, do not allow duplicate values for this column.\n",
"index\n",
"If set to True, create an index for this column, so that queries are more efficient.\n",
"nullable\n",
"If set to True, allow empty values for this column. If set to False, the column will not allow null values.\n",
"default\n",
"Define a default value for the column.\n",
"Model Definition \n",
"| \n",
"63\n",
"\n",
"Flask-SQLAlchemy requires all models to define a primary key col‐\n",
"umn, which is commonly named id.\n",
"Although it’s not strictly necessary, the two models include a __repr__() method to\n",
"give them a readable string representation that can be used for debugging and testing\n",
"purposes.\n",
"Relationships\n",
"Relational databases establish connections between rows in different tables through\n",
"the use of relationships. The relational diagram in Figure 5-1 expresses a simple rela‐\n",
"tionship between users and their roles. This is a one-to-many relationship from roles\n",
"to users, because one role can belong to many users, but each user can have only one\n",
"role.\n",
"Example 5-3 shows how the one-to-many relationship in Figure 5-1 is represented in\n",
"the model classes.\n",
"Example 5-3. hello.py: relationships in the database models\n",
"class Role(db.Model):\n",
" # ...\n",
" users = db.relationship('User', backref='role')\n",
"class User(db.Model):\n",
" # ...\n",
" role_id = db.Column(db.Integer, db.ForeignKey('roles.id'))\n",
"As seen in Figure 5-1, a relationship connects two rows through the use of a foreign\n",
"key. The role_id column added to the User model is defined as a foreign key, and\n",
"that establishes the relationship. The 'roles.id' argument to db.ForeignKey()\n",
"specifies that the column should be interpreted as having id values from rows in the\n",
"roles table.\n",
"The users attribute added to the model Role represents the object-oriented view of\n",
"the relationship, as seen from the “one” side. Given an instance of class Role, the\n",
"users attribute will return the list of users associated with that role (i.e., the “many”\n",
"side). The first argument to db.relationship() indicates what model is on the other\n",
"side of the relationship. The model class can be provided as a string if the class is\n",
"defined later in the module.\n",
"The backref argument to db.relationship() defines the reverse direction of the\n",
"relationship, by adding a role attribute to the User model. This attribute can be used\n",
"64 \n",
"| \n",
"Chapter 5: Databases\n",
"\n",
"on any instance of User instead of the role_id foreign key to access the Role model\n",
"as an object.\n",
"In most cases db.relationship() can locate the relationship’s foreign key on its own,\n",
"but sometimes it cannot determine what column to use as a foreign key. For example,\n",
"if the User model had two or more columns defined as Role foreign keys, then\n",
"SQLAlchemy would not know which one of the two to use. Whenever the foreign key\n",
"configuration is ambiguous, additional arguments to db.relationship() need to be\n",
"given. Table 5-4 lists some of the common configuration options that can be used to\n",
"define a relationship.\n",
"Table 5-4. Common SQLAlchemy relationship options\n",
"Option name\n",
"Description\n",
"backref\n",
"Add a back reference in the other model in the relationship.\n",
"primaryjoin\n",
"Specify the join condition between the two models explicitly. This is necessary only for ambiguous\n",
"relationships.\n",
"lazy\n",
"Specify how the related items are to be loaded. Possible values are select (items are loaded on\n",
"demand the first time they are accessed), immediate (items are loaded when the source object is\n",
"loaded), joined (items are loaded immediately, but as a join), subquery (items are loaded\n",
"immediately, but as a subquery), noload (items are never loaded), and dynamic (instead of loading\n",
"the items, the query that can load them is given).\n",
"uselist\n",
"If set to False, use a scalar instead of a list.\n",
"order_by\n",
"Specify the ordering used for the items in the relationship.\n",
"secondary\n",
"Specify the name of the association table to use in many-to-many relationships.\n",
"secondaryjoin Specify the secondary join condition for many-to-many relationships when SQLAlchemy cannot\n",
"determine it on its own.\n",
"If you have cloned the application’s Git repository on GitHub, you\n",
"can run git checkout 5a to check out this version of the applica‐\n",
"tion.\n",
"There are other relationship types besides one-to-many. The one-to-one relationship\n",
"can be expressed the same way as one-to-many, as described earlier, but with the\n",
"uselist option set to False within the db.relationship() definition so that the\n",
"“many” side becomes a “one” side. The many-to-one relationship can also be\n",
"expressed as a one-to-many if the tables are reversed, or it can be expressed with the\n",
"foreign key and the db.relationship() definition both on the “many” side. The\n",
"most complex relationship type, many-to-many, requires an additional table called an\n",
"association or junction table. You will learn about many-to-many relationships in\n",
"Chapter 12.\n",
"Relationships \n",
"| \n",
"65\n",
"\n",
"Database Operations\n",
"The models are now fully configured according to the database diagram in Figure 5-1\n",
"and are ready to be used. The best way to learn how to work with these models is in a\n",
"Python shell. The following sections will walk you through the most common data‐\n",
"base operations in a shell started with the flask shell command. Before you use\n",
"this command, make sure the FLASK_APP environment variable is set to hello.py, as\n",
"shown in Chapter 2.\n",
"Creating the Tables\n",
"The very first thing to do is to instruct Flask-SQLAlchemy to create a database based\n",
"on the model classes. The db.create_all() function locates all the subclasses of\n",
"db.Model and creates corresponding tables in the database for them:\n",
"(venv) $ flask shell\n",
">>> from hello import db\n",
">>> db.create_all()\n",
"If you check the application directory, you will now see a new file there called\n",
"data.sqlite, the name that was given to the SQLite database in the configuration. The\n",
"db.create_all() function will not re-create or update a database table if it already\n",
"exists in the database. This can be inconvenient when the models are modified and\n",
"the changes need to be applied to an existing database. The brute-force solution to\n",
"update existing database tables to a different schema is to remove the old tables first:\n",
">>> db.drop_all()\n",
">>> db.create_all()\n",
"Unfortunately, this method has the undesired side effect of destroying all the data in\n",
"the old database. A better solution to the problem of updating databases is presented\n",
"near the end of the chapter.\n",
"Inserting Rows\n",
"The following example creates a few roles and users:\n",
">>> from hello import Role, User\n",
">>> admin_role = Role(name='Admin')\n",
">>> mod_role = Role(name='Moderator')\n",
">>> user_role = Role(name='User')\n",
">>> user_john = User(username='john', role=admin_role)\n",
">>> user_susan = User(username='susan', role=user_role)\n",
">>> user_david = User(username='david', role=user_role)\n",
"The constructors for models accept initial values for the model attributes as keyword\n",
"arguments. Note that the role attribute can be used, even though it is not a real data‐\n",
"base column but a high-level representation of the one-to-many relationship. The id\n",
"66 \n",
"| \n",
"Chapter 5: Databases\n",
"\n",
"attribute of these new objects is not set explicitly: the primary keys in many databases\n",
"are managed by the database itself. The objects exist only on the Python side so far;\n",
"they have not been written to the database yet. Because of that, their id values have\n",
"not yet been assigned:\n",
">>> print(admin_role.id)\n",
"None\n",
">>> print(mod_role.id)\n",
"None\n",
">>> print(user_role.id)\n",
"None\n",
"Changes to the database are managed through a database session, which Flask-\n",
"SQLAlchemy provides as db.session. To prepare objects to be written to the data‐\n",
"base, they must be added to the session:\n",
">>> db.session.add(admin_role)\n",
">>> db.session.add(mod_role)\n",
">>> db.session.add(user_role)\n",
">>> db.session.add(user_john)\n",
">>> db.session.add(user_susan)\n",
">>> db.session.add(user_david)\n",
"Or, more concisely:\n",
">>> db.session.add_all([admin_role, mod_role, user_role,\n",
"... user_john, user_susan, user_david])\n",
"To write the objects to the database, the session needs to be committed by calling its\n",
"commit() method:\n",
">>> db.session.commit()\n",
"Check the id attributes again after having the data committed to see that they are\n",
"now set:\n",
">>> print(admin_role.id)\n",
"1\n",
">>> print(mod_role.id)\n",
"2\n",
">>> print(user_role.id)\n",
"3\n",
"The db.session database session is not related to the Flask\n",
"session object discussed in Chapter 4. Database sessions are also\n",
"called transactions.\n",
"Database sessions are extremely useful in keeping the database consistent. The com‐\n",
"mit operation writes all the objects that were added to the session atomically. If an\n",
"Database Operations \n",
"| \n",
"67\n",
"\n",
"error occurs while the session is being written, the whole session is discarded. If you\n",
"always commit related changes together in a session, you are guaranteed to avoid\n",
"database inconsistencies due to partial updates.\n",
"A \n",
"database \n",
"session \n",
"can \n",
"also \n",
"be \n",
"rolled \n",
"back. \n",
"If\n",
"db.session.rollback() is called, any objects that were added to\n",
"the database session are restored to the state they have in the data‐\n",
"base.\n",
"Modifying Rows\n",
"The add() method of the database session can also be used to update models. Con‐\n",
"tinuing in the same shell session, the following example renames the \"Admin\" role to\n",
"\"Administrator\":\n",
">>> admin_role.name = 'Administrator'\n",
">>> db.session.add(admin_role)\n",
">>> db.session.commit()\n",
"Deleting Rows\n",
"The database session also has a delete() method. The following example deletes the\n",
"\"Moderator\" role from the database:\n",
">>> db.session.delete(mod_role)\n",
">>> db.session.commit()\n",
"Note that deletions, like insertions and updates, are executed only when the database\n",
"session is committed.\n",
"Querying Rows\n",
"Flask-SQLAlchemy makes a query object available in each model class. The most\n",
"basic query for a model is triggered with the all() method, which returns the entire\n",
"contents of the corresponding table:\n",
">>> Role.query.all()\n",
"[<Role 'Administrator'>, <Role 'User'>]\n",
">>> User.query.all()\n",
"[<User 'john'>, <User 'susan'>, <User 'david'>]\n",
"A query object can be configured to issue more specific database searches through\n",
"the use of filters. The following example finds all the users that were assigned the\n",
"\"User\" role:\n",
">>> User.query.filter_by(role=user_role).all()\n",
"[<User 'susan'>, <User 'david'>]\n",
"68 \n",
"| \n",
"Chapter 5: Databases\n",
"\n",
"It is also possible to inspect the native SQL query that SQLAlchemy generates for a\n",
"given query by converting the query object to a string:\n",
">>> str(User.query.filter_by(role=user_role))\n",
"'SELECT users.id AS users_id, users.username AS users_username,\n",
"users.role_id AS users_role_id \\nFROM users \\nWHERE :param_1 = users.role_id'\n",
"If you exit the shell session, the objects created in the previous example will cease to\n",
"exist as Python objects but will continue to exist as rows in their respective database\n",
"tables. If you then start a brand-new shell session, you have to re-create the Python\n",
"objects from their database rows. The following example issues a query that loads the\n",
"user role with name \"User\":\n",
">>> user_role = Role.query.filter_by(name='User').first()\n",
"Note how in this case, the query was issued with the first() method instead of\n",
"all(). While all() returns all the results of the query as a list, first() returns only\n",
"the first result or None if there are no results, so it is a convenient method to use for\n",
"queries that are known to return one result at the most.\n",
"Filters such as filter_by() are invoked on a query object and return a new refined\n",
"query. Multiple filters can be called in sequence until the query is configured as\n",
"needed.\n",
"Table 5-5 shows some of the most common filters available to queries. The complete\n",
"list is in the SQLAlchemy documentation.\n",
"Table 5-5. Common SQLAlchemy query filters\n",
"Option\n",
"Description\n",
"filter()\n",
"Returns a new query that adds an additional filter to the original query\n",
"filter_by()\n",
"Returns a new query that adds an additional equality filter to the original query\n",
"limit()\n",
"Returns a new query that limits the number of results of the original query to the given number\n",
"offset()\n",
"Returns a new query that applies an offset into the list of results of the original query\n",
"order_by()\n",
"Returns a new query that sorts the results of the original query according to the given criteria\n",
"group_by()\n",
"Returns a new query that groups the results of the original query according to the given criteria\n",
"After the desired filters have been applied to the query, a call to all() will cause the\n",
"query to execute and return the results as a list—but there are other ways to trigger\n",
"the execution of a query besides all(). Table 5-6 shows other query execution meth‐\n",
"ods.\n",
"Database Operations \n",
"| \n",
"69\n",
"\n",
"Table 5-6. Most common SQLAlchemy query executors\n",
"Option\n",
"Description\n",
"all()\n",
"Returns all the results of a query as a list\n",
"first()\n",
"Returns the first result of a query, or None if there are no results\n",
"first_or_404() Returns the first result of a query, or aborts the request and sends a 404 error as the response if there\n",
"are no results\n",
"get()\n",
"Returns the row that matches the given primary key, or None if no matching row is found\n",
"get_or_404()\n",
"Returns the row that matches the given primary key or, if the key is not found, aborts the request and\n",
"sends a 404 error as the response\n",
"count()\n",
"Returns the result count of the query\n",
"paginate()\n",
"Returns a Pagination object that contains the specified range of results\n",
"Relationships work similarly to queries. The following example queries the one-to-\n",
"many relationship between roles and users from both ends:\n",
">>> users = user_role.users\n",
">>> users\n",
"[<User 'susan'>, <User 'david'>]\n",
">>> users[0].role\n",
"<Role 'User'>\n",
"The user_role.users query here has a small problem. The implicit query that runs\n",
"when the user_role.users expression is issued internally calls all() to return the\n",
"list of users. Because the query object is hidden, it is not possible to refine it with\n",
"additional query filters. In this particular example, it may have been useful to request\n",
"that the user list be returned in alphabetical order. In Example 5-4, the configuration\n",
"of the relationship is modified with a lazy='dynamic' argument to request that the\n",
"query is not automatically executed.\n",
"Example 5-4. hello.py: dynamic database relationships\n",
"class Role(db.Model):\n",
" # ...\n",
" users = db.relationship('User', backref='role', lazy='dynamic')\n",
" # ...\n",
"With the relationship configured in this way, user_role.users returns a query that\n",
"hasn’t executed yet, so filters can be added to it:\n",
">>> user_role.users.order_by(User.username).all()\n",
"[<User 'david'>, <User 'susan'>]\n",
">>> user_role.users.count()\n",
"2\n",
"70 \n",
"| \n",
"Chapter 5: Databases\n",
"\n",
"Database Use in View Functions\n",
"The database operations described in the previous sections can be used directly inside\n",
"view functions. Example 5-5 shows a new version of the home page route that records\n",
"names entered by users in the database.\n",
"Example 5-5. hello.py: database use in view functions\n",
"@app.route('/', methods=['GET', 'POST'])\n",
"def index():\n",
" form = NameForm()\n",
" if form.validate_on_submit():\n",
" user = User.query.filter_by(username=form.name.data).first()\n",
" if user is None:\n",
" user = User(username=form.name.data)\n",
" db.session.add(user)\n",
" db.session.commit()\n",
" session['known'] = False\n",
" else:\n",
" session['known'] = True\n",
" session['name'] = form.name.data\n",
" form.name.data = ''\n",
" return redirect(url_for('index'))\n",
" return render_template('index.html',\n",
" form=form, name=session.get('name'),\n",
" known=session.get('known', False))\n",
"In this modified version of the application, each time a name is submitted the appli‐\n",
"cation checks for it in the database using the filter_by() query filter. A known vari‐\n",
"able is written to the user session so that after the redirect the information can be sent\n",
"to the template, where it is used to customize the greeting. Note that for the applica‐\n",
"tion to work, the database tables must be created in a Python shell as shown earlier.\n",
"The new version of the associated template is shown in Example 5-6. This template\n",
"uses the known argument to add a second line to the greeting that is different for\n",
"known and new users.\n",
"Example 5-6. templates/index.html: customized greeting in template\n",
"{% extends \"base.html\" %}\n",
"{% import \"bootstrap/wtf.html\" as wtf %}\n",
"{% block title %}Flasky{% endblock %}\n",
"{% block page_content %}\n",
"<div class=\"page-header\">\n",
" <h1>Hello, {% if name %}{{ name }}{% else %}Stranger{% endif %}!</h1>\n",
" {% if not known %}\n",
"Database Use in View Functions \n",
"| \n",
"71\n",
"\n",
" <p>Pleased to meet you!</p>\n",
" {% else %}\n",
" <p>Happy to see you again!</p>\n",
" {% endif %}\n",
"</div>\n",
"{{ wtf.quick_form(form) }}\n",
"{% endblock %}\n",
"If you have cloned the application’s Git repository on GitHub, you\n",
"can run git checkout 5b to check out this version of the applica‐\n",
"tion.\n",
"Integration with the Python Shell\n",
"Having to import the database instance and the models each time a shell session is\n",
"started is tedious work. To avoid having to constantly repeat these steps, the flask\n",
"shell command can be configured to automatically import these objects.\n",
"To add objects to the import list, a shell context processor must be created and regis‐\n",
"tered with the app.shell_context_processor decorator. This is shown in\n",
"Example 5-7.\n",
"Example 5-7. hello.py: adding a shell context\n",
"@app.shell_context_processor\n",
"def make_shell_context():\n",
" return dict(db=db, User=User, Role=Role)\n",
"The shell context processor function returns a dictionary that includes the database\n",
"instance and the models. The flask shell command will import these items auto‐\n",
"matically into the shell, in addition to app, which is imported by default:\n",
"$ flask shell\n",
">>> app\n",
"<Flask 'hello'>\n",
">>> db\n",
"<SQLAlchemy engine='sqlite:////home/flask/flasky/data.sqlite'>\n",
">>> User\n",
"<class 'hello.User'>\n",
"If you have cloned the application’s Git repository on GitHub, you\n",
"can run git checkout 5c to check out this version of the applica‐\n",
"tion.\n",
"72 \n",
"| \n",
"Chapter 5: Databases\n",
"\n",
"Database Migrations with Flask-Migrate\n",
"As you make progress developing an application, you will find that your database\n",
"models need to change, and when that happens the database needs to be updated as\n",
"well. Flask-SQLAlchemy creates database tables from models only when they do not\n",
"exist already, so the only way to make it update tables is by destroying the old tables\n",
"first—but of course, this causes all the data in the database to be lost.\n",
"A better solution is to use a database migration framework. In the same way source\n",
"code version control tools keep track of changes to source code files, a database\n",
"migration framework keeps track of changes to a database schema, allowing incre‐\n",
"mental changes to be applied.\n",
"The developer of SQLAlchemy has written a migration framework called Alembic,\n",
"but instead of using Alembic directly, Flask applications can use the Flask-Migrate\n",
"extension, a lightweight Alembic wrapper that integrates it with the flask command.\n",
"Creating a Migration Repository\n",
"To begin, Flask-Migrate must be installed in the virtual environment:\n",
"(venv) $ pip install flask-migrate\n",
"Example 5-8 shows how the extension is initialized.\n",
"Example 5-8. hello.py: Flask-Migrate initialization\n",
"from flask_migrate import Migrate\n",
"# ...\n",
"migrate = Migrate(app, db)\n",
"To expose the database migration commands, Flask-Migrate adds a flask db com‐\n",
"mand with several subcommands. When you work on a new project, you can add\n",
"support for database migrations with the init subcommand:\n",
"(venv) $ flask db init\n",
" Creating directory /home/flask/flasky/migrations...done\n",
" Creating directory /home/flask/flasky/migrations/versions...done\n",
" Generating /home/flask/flasky/migrations/alembic.ini...done\n",
" Generating /home/flask/flasky/migrations/env.py...done\n",
" Generating /home/flask/flasky/migrations/env.pyc...done\n",
" Generating /home/flask/flasky/migrations/README...done\n",
" Generating /home/flask/flasky/migrations/script.py.mako...done\n",
" Please edit configuration/connection/logging settings in\n",
" '/home/flask/flasky/migrations/alembic.ini' before proceeding.\n",
"Database Migrations with Flask-Migrate \n",
"| \n",
"73\n",
"\n",
"This command creates a migrations directory, where all the migration scripts will be\n",
"stored. If you are following the example project using git checkout, you do not need\n",
"to do this step, as the migration repository is already included in the GitHub reposi‐\n",
"tory.\n",
"The files in a database migration repository must always be added\n",
"to version control along with the rest of the application.\n",
"Creating a Migration Script\n",
"In Alembic, a database migration is represented by a migration script. This script has\n",
"two functions called upgrade() and downgrade(). The upgrade() function applies\n",
"the database changes that are part of the migration, and the downgrade() function\n",
"removes them. This ability to add and remove changes means, Alembic can reconfig‐\n",
"ure a database to any point in the change history.\n",
"Alembic migrations can be created manually or automatically using the revision and\n",
"migrate commands, respectively. A manual migration creates a migration skeleton\n",
"script with empty upgrade() and downgrade() functions that need to be imple‐\n",
"mented by the developer using directives exposed by Alembic’s Operations object.\n",
"An automatic migration attempts to generate the code for the upgrade() and\n",
"downgrade() functions by looking for differences between the model definitions and\n",
"the current state of the database.\n",
"Automatic migrations are not always accurate and can miss some\n",
"details that are ambiguous. For example, if a column is renamed, an\n",
"automatically generated migration may show that the column in\n",
"question was deleted and a new column was added with the new\n",
"name. Leaving the migration as is will cause the data in this column\n",
"to be lost! For this reason, migration scripts generated automati‐\n",
"cally should always be reviewed and manually corrected if they\n",
"have any inaccuracies.\n",
"To make changes to your database schema with Flask-Migrate, the following proce‐\n",
"dure needs to be followed:\n",
"1. Make the necessary changes to the model classes.\n",
"2. Create an automatic migration script with the flask db migrate command.\n",
"3. Review the generated script and adjust it so that it accurately represents the\n",
"changes that were made to the models.\n",
"74 \n",
"| \n",
"Chapter 5: Databases\n",
"\n",
"4. Add the migration script to source control.\n",
"5. Apply the migration to the database with the flask db upgrade command.\n",
"The flask db migrate subcommand creates an automatic migration script:\n",
"(venv) $ flask db migrate -m \"initial migration\"\n",
"INFO [alembic.migration] Context impl SQLiteImpl.\n",
"INFO [alembic.migration] Will assume non-transactional DDL.\n",
"INFO [alembic.autogenerate] Detected added table 'roles'\n",
"INFO [alembic.autogenerate] Detected added table 'users'\n",
"INFO [alembic.autogenerate.compare] Detected added index\n",
"'ix_users_username' on '['username']'\n",
" Generating /home/flask/flasky/migrations/versions/1bc\n",
" 594146bb5_initial_migration.py...done\n",
"If you are following the git checkout instructions to incrementally update the exam‐\n",
"ple application, you do not need to issue the migrate commands, as the migration\n",
"scripts are already incorporated into the Git repository tags.\n",
"If you have cloned the application’s Git repository on GitHub, you\n",
"can run git checkout 5d to check out this version of the applica‐\n",
"tion. Note that you do not need to generate the migration reposi‐\n",
"tory and the migration scripts for this application as these are\n",
"included in the GitHub repository.\n",
"Upgrading the Database\n",
"Once a migration script has been reviewed and accepted, it can be applied to the data‐\n",
"base using the flask db upgrade command:\n",
"(venv) $ flask db upgrade\n",
"INFO [alembic.migration] Context impl SQLiteImpl.\n",
"INFO [alembic.migration] Will assume non-transactional DDL.\n",
"INFO [alembic.migration] Running upgrade None -> 1bc594146bb5, initial migration\n",
"For a first migration, this is effectively equivalent to calling db.create_all(), but in\n",
"successive migrations the flask db upgrade command applies updates to the tables\n",
"without affecting their contents.\n",
"Database Migrations with Flask-Migrate \n",
"| \n",
"75\n",
"\n",
"If you have been working with the application in its previous\n",
"stages, you already have a database file that was created with the\n",
"db.create_all() function earlier. In this state, the flask db\n",
"upgrade will fail because it will try to create database tables that\n",
"already exist. A simple way to address this problem is to delete\n",
"your data.sqlite database file and then run flask db upgrade to\n",
"generate a new database through the migration framework.\n",
"Another option is to skip the flask db upgrade and instead mark\n",
"the existing database as upgraded using the flask db stamp com‐\n",
"mand.\n",
"Adding More Migrations\n",
"As you work on your own projects, you are going to find that you need to make\n",
"changes to your database models very often. When you manage the database through\n",
"a migration framework, all changes must be defined in migration scripts, because\n",
"anything that is not tracked in a migration will not be repeatable. The procedure to\n",
"introduce a change in the database is similar to what was done to introduce the first\n",
"migration:\n",
"1. Make the necessary changes in the database models.\n",
"2. Generate a migration with the flask db migrate command.\n",
"3. Review the generated migration script and correct it if it has any inaccuracies.\n",
"4. Apply the changes to the database with the flask db upgrade command.\n",
"While working on a specific feature, you may find that you need to make several\n",
"changes to your database models before you get them the way you want them. If your\n",
"last migration has not been committed to source control yet, you can opt to expand it\n",
"to incorporate new changes as you make them, and this will save you from having\n",
"lots of very small migration scripts that are meaningless on their own. The procedure\n",
"to expand the last migration script is as follows:\n",
"1. Remove the last migration from the database with the flask db downgrade com‐\n",
"mand (note that this may cause some data to be lost).\n",
"2. Delete the last migration script, which is now orphaned.\n",
"3. Generate a new database migration with the flask db migrate command,\n",
"which will now include the changes in the migration script you just removed,\n",
"plus any other changes you’ve made to the models.\n",
"4. Review and apply the migration script as described previously.\n",
"76 \n",
"| \n",
"Chapter 5: Databases\n",
"\n",
"Consult the Flask-Migrate documentation to learn about other\n",
"subcommands related to database migrations.\n",
"The topic of database design and usage is very important; entire books have been\n",
"written on the subject. You should consider this chapter as an overview; more\n",
"advanced topics will be discussed in later chapters. The next chapter is dedicated to\n",
"sending email.\n",
"Database Migrations with Flask-Migrate \n",
"| \n",
"77\n",
"\n",
"\n",
"CHAPTER 6\n",
"Email\n",
"Many types of applications need to notify users when certain events occur, and the\n",
"usual method of communication is email. In this chapter you are going to learn how\n",
"to send emails from a Flask application.\n",
"Email Support with Flask-Mail\n",
"Although the smtplib package from the Python standard library can be used to send\n",
"email inside a Flask application, the Flask-Mail extension wraps smtplib and integra‐\n",
"tes it nicely with Flask. Flask-Mail is installed with pip:\n",
"(venv) $ pip install flask-mail\n",
"The extension connects to a Simple Mail Transfer Protocol (SMTP) server and passes\n",
"emails to it for delivery. If no configuration is given, Flask-Mail connects to localhost\n",
"at port 25 and sends email without authentication. Table 6-1 shows the list of configu‐\n",
"ration keys that can be used to configure the SMTP server.\n",
"Table 6-1. Flask-Mail SMTP server configuration keys\n",
"Key\n",
"Default\n",
"Description\n",
"MAIL_SERVER\n",
"localhost\n",
"Hostname or IP address of the email server\n",
"MAIL_PORT\n",
"25\n",
"Port of the email server\n",
"MAIL_USE_TLS\n",
"False\n",
"Enable Transport Layer Security (TLS) security\n",
"MAIL_USE_SSL\n",
"False\n",
"Enable Secure Sockets Layer (SSL) security\n",
"MAIL_USERNAME\n",
"None\n",
"Mail account username\n",
"MAIL_PASSWORD\n",
"None\n",
"Mail account password\n",
"79\n",
"\n",
"During development it may be more convenient to connect to an external SMTP\n",
"server. As an example, Example 6-1 shows how to configure the application to send\n",
"email through a Google Gmail account.\n",
"Example 6-1. hello.py: Flask-Mail configuration for Gmail\n",
"import os\n",
"# ...\n",
"app.config['MAIL_SERVER'] = 'smtp.googlemail.com'\n",
"app.config['MAIL_PORT'] = 587\n",
"app.config['MAIL_USE_TLS'] = True\n",
"app.config['MAIL_USERNAME'] = os.environ.get('MAIL_USERNAME')\n",
"app.config['MAIL_PASSWORD'] = os.environ.get('MAIL_PASSWORD')\n",
"Never write account credentials directly in your scripts, particularly\n",
"if you plan to release your work as open source. To protect your\n",
"account information, have your script import sensitive information\n",
"from environment variables.\n",
"For security reasons, Gmail accounts are configured to require\n",
"external applications to use OAuth2 authentication to connect to\n",
"the email server. Unfortunately, Python’s smtplib library does not\n",
"support this method of authentication. To make your Gmail\n",
"account accept standard SMTP authentication, go to your Google\n",
"account settings page and select “Signing in to Google” from the\n",
"left menu bar. On that page, locate the “Allow less secure apps” set‐\n",
"ting and make sure it is enabled. If enabling this setting on your\n",
"personal Gmail account concerns you, create a secondary account\n",
"only to test sending emails.\n",
"Flask-Mail is initialized as shown in Example 6-2.\n",
"Example 6-2. hello.py: Flask-Mail initialization\n",
"from flask_mail import Mail\n",
"mail = Mail(app)\n",
"The two environment variables that hold the email server username and password\n",
"need to be defined in the environment. If you are on Linux or macOS, you can set\n",
"these variables as follows:\n",
"(venv) $ export MAIL_USERNAME=<Gmail username>\n",
"(venv) $ export MAIL_PASSWORD=<Gmail password>\n",
"80 \n",
"| \n",
"Chapter 6: Email\n",
"\n",
"For Microsoft Windows users, the environment variables are set as follows:\n",
"(venv) $ set MAIL_USERNAME=<Gmail username>\n",
"(venv) $ set MAIL_PASSWORD=<Gmail password>\n",
"Sending Email from the Python Shell\n",
"To test the configuration, you can start a shell session and send a test email (replace\n",
"you@example.com with your own email address):\n",
"(venv) $ flask shell\n",
">>> from flask_mail import Message\n",
">>> from hello import mail\n",
">>> msg = Message('test email', sender='you@example.com',\n",
"... recipients=['you@example.com'])\n",
">>> msg.body = 'This is the plain text body'\n",
">>> msg.html = 'This is the <b>HTML</b> body'\n",
">>> with app.app_context():\n",
"... mail.send(msg)\n",
"...\n",
"Note that Flask-Mail’s send() function uses current_app, so it needs to be executed\n",
"with an activated application context.\n",
"Integrating Emails with the Application\n",
"To avoid having to create email messages manually every time, it is a good idea to\n",
"abstract the common parts of the application’s email sending functionality into a\n",
"function. As an added benefit, this function can render email bodies from Jinja2 tem‐\n",
"plates to have the most flexibility. The implementation is shown in Example 6-3.\n",
"Example 6-3. hello.py: email support\n",
"from flask_mail import Message\n",
"app.config['FLASKY_MAIL_SUBJECT_PREFIX'] = '[Flasky]'\n",
"app.config['FLASKY_MAIL_SENDER'] = 'Flasky Admin <flasky@example.com>'\n",
"def send_email(to, subject, template, **kwargs):\n",
" msg = Message(app.config['FLASKY_MAIL_SUBJECT_PREFIX'] + subject,\n",
" sender=app.config['FLASKY_MAIL_SENDER'], recipients=[to])\n",
" msg.body = render_template(template + '.txt', **kwargs)\n",
" msg.html = render_template(template + '.html', **kwargs)\n",
" mail.send(msg)\n",
"The function relies on two application-specific configuration keys that define a prefix\n",
"string for the subject and the address that will be used as the sender. The\n",
"send_email() function takes the destination address, a subject line, a template for the\n",
"email body, and a list of keyword arguments. The template name must be given\n",
"Email Support with Flask-Mail \n",
"| \n",
"81\n",
"\n",
"without the extension, so that two versions of the template can be used for the plain\n",
"text and HTML bodies. The keyword arguments passed by the caller are given to\n",
"render_template() so that they can be used by the templates that generate the email\n",
"body as template variables.\n",
"The index() view function can easily be expanded to send an email to the adminis‐\n",
"trator whenever a new name is received with the form. Example 6-4 shows this\n",
"change.\n",
"Example 6-4. hello.py: email example\n",
"# ...\n",
"app.config['FLASKY_ADMIN'] = os.environ.get('FLASKY_ADMIN')\n",
"# ...\n",
"@app.route('/', methods=['GET', 'POST'])\n",
"def index():\n",
" form = NameForm()\n",
" if form.validate_on_submit():\n",
" user = User.query.filter_by(username=form.name.data).first()\n",
" if user is None:\n",
" user = User(username=form.name.data)\n",
" db.session.add(user)\n",
" session['known'] = False\n",
" if app.config['FLASKY_ADMIN']:\n",
" send_email(app.config['FLASKY_ADMIN'], 'New User',\n",
" 'mail/new_user', user=user)\n",
" else:\n",
" session['known'] = True\n",
" session['name'] = form.name.data\n",
" form.name.data = ''\n",
" return redirect(url_for('index'))\n",
" return render_template('index.html', form=form, name=session.get('name'),\n",
" known=session.get('known', False))\n",
"The recipient of the email is given in the FLASKY_ADMIN environment variable that’s\n",
"loaded into a configuration variable of the same name during startup. Two template\n",
"files need to be created for the text and HTML versions of the email. These files are\n",
"stored in a mail subdirectory inside templates to keep them separate from regular\n",
"templates. The email templates expect the user to be given as a template argument, so\n",
"the call to send_email() includes it as a keyword argument.\n",
"If you have cloned the application’s Git repository on GitHub, you\n",
"can run git checkout 6a to check out this version of the applica‐\n",
"tion.\n",
"82 \n",
"| \n",
"Chapter 6: Email\n",
"\n",
"In addition to the MAIL_USERNAME and MAIL_PASSWORD environment variables\n",
"described earlier, this version of the application needs the FLASKY_ADMIN environment\n",
"variable. For Linux and macOS users, the command to set this variable is:\n",
"(venv) $ export FLASKY_ADMIN=<your-email-address>\n",
"For Microsoft Windows users, this is the equivalent command:\n",
"(venv) $ set FLASKY_ADMIN=<your-email-address>\n",
"With these environment variables set, you can test the application and receive an\n",
"email every time you enter a new name in the form.\n",
"Sending Asynchronous Email\n",
"If you sent a few test emails, you likely noticed that the mail.send() function blocks\n",
"for a few seconds while the email is sent, making the browser look unresponsive dur‐\n",
"ing that time. To avoid unnecessary delays during request handling, the email send\n",
"function can be moved to a background thread. Example 6-5 shows this change.\n",
"Example 6-5. hello.py: asynchronous email support\n",
"from threading import Thread\n",
"def send_async_email(app, msg):\n",
" with app.app_context():\n",
" mail.send(msg)\n",
"def send_email(to, subject, template, **kwargs):\n",
" msg = Message(app.config['FLASKY_MAIL_SUBJECT_PREFIX'] + subject,\n",
" sender=app.config['FLASKY_MAIL_SENDER'], recipients=[to])\n",
" msg.body = render_template(template + '.txt', **kwargs)\n",
" msg.html = render_template(template + '.html', **kwargs)\n",
" thr = Thread(target=send_async_email, args=[app, msg])\n",
" thr.start()\n",
" return thr\n",
"This implementation highlights an interesting problem. Many Flask extensions oper‐\n",
"ate under the assumption that there are active application and/or request contexts. As\n",
"mentioned previously, Flask-Mail’s send() function uses current_app, so it requires\n",
"the application context to be active. But since contexts are associated with a thread,\n",
"when the mail.send() function executes in a different thread it needs the application\n",
"context to be created artificially using app.app_context(). The app instance is passed\n",
"to the thread as an argument so that a context can be created.\n",
"Email Support with Flask-Mail \n",
"| \n",
"83\n",
"\n",
"If you have cloned the application’s Git repository on GitHub, you\n",
"can run git checkout 6b to check out this version of the applica‐\n",
"tion.\n",
"If you run the application now, you will notice that it is much more responsive, but\n",
"keep in mind that for applications that send a large volume of email, having a job\n",
"dedicated to sending email is more appropriate than starting a new thread for each\n",
"email send operation. For example, the execution of the send_async_email() func‐\n",
"tion can be sent to a Celery task queue.\n",
"This chapter completes the overview of the features that are a must-have for most\n",
"web applications. The problem now is that the hello.py script is starting to get large,\n",
"and that makes it harder to work with. In the next chapter, you will learn how to\n",
"structure a larger application.\n",
"84 \n",
"| \n",
"Chapter 6: Email\n",
"\n",
"CHAPTER 7\n",
"Large Application Structure\n",
"Although having small web applications stored in a single script file can be very con‐\n",
"venient, this approach does not scale well. As the application grows in complexity,\n",
"working with a single large source file becomes problematic.\n",
"Unlike most other web frameworks, Flask does not impose a specific organization for\n",
"large projects; the way to structure the application is left entirely to the developer. In\n",
"this chapter, a possible way to organize a large application in packages and modules is\n",
"presented. This structure will be used in the remaining examples of the book.\n",
"Project Structure\n",
"Example 7-1 shows the basic layout for a Flask application.\n",
"Example 7-1. Basic multiple-file Flask application structure\n",
"|-flasky\n",
" |-app/\n",
" |-templates/\n",
" |-static/\n",
" |-main/\n",
" |-__init__.py\n",
" |-errors.py\n",
" |-forms.py\n",
" |-views.py\n",
" |-__init__.py\n",
" |-email.py\n",
" |-models.py\n",
" |-migrations/\n",
" |-tests/\n",
" |-__init__.py\n",
" |-test*.py\n",
" |-venv/\n",
" |-requirements.txt\n",
" |-config.py\n",
" |-flasky.py\n",
"85\n",
"\n",
"This structure has four top-level folders:\n",
"• The Flask application lives inside a package generically named app.\n",
"• The migrations folder contains the database migration scripts, as before.\n",
"• Unit tests are written in a tests package.\n",
"• The venv folder contains the Python virtual environment, as before.\n",
"There are also a few new files:\n",
"• requirements.txt lists the package dependencies so that it is easy to regenerate an\n",
"identical virtual environment on a different computer.\n",
"• config.py stores the configuration settings.\n",
"• flasky.py defines the Flask application instance, and also includes a few tasks that\n",
"help manage the application.\n",
"To help you fully understand this structure, the following sections describe the pro‐\n",
"cess to convert the hello.py application to it.\n",
"Configuration Options\n",
"Applications often need several configuration sets. The best example of this is the\n",
"need to use different databases during development, testing, and production so that\n",
"they don’t interfere with each other.\n",
"Instead of the simple app.config dictionary-like configuration used by hello.py, a\n",
"hierarchy of configuration classes can be used. Example 7-2 shows the config.py file,\n",
"with all the settings imported from hello.py.\n",
"Example 7-2. config.py: application configuration\n",
"import os\n",
"basedir = os.path.abspath(os.path.dirname(__file__))\n",
"class Config:\n",
" SECRET_KEY = os.environ.get('SECRET_KEY') or 'hard to guess string'\n",
" MAIL_SERVER = os.environ.get('MAIL_SERVER', 'smtp.googlemail.com')\n",
" MAIL_PORT = int(os.environ.get('MAIL_PORT', '587'))\n",
" MAIL_USE_TLS = os.environ.get('MAIL_USE_TLS', 'true').lower() in \\\n",
" ['true', 'on', '1']\n",
" MAIL_USERNAME = os.environ.get('MAIL_USERNAME')\n",
" MAIL_PASSWORD = os.environ.get('MAIL_PASSWORD')\n",
" FLASKY_MAIL_SUBJECT_PREFIX = '[Flasky]'\n",
" FLASKY_MAIL_SENDER = 'Flasky Admin <flasky@example.com>'\n",
" FLASKY_ADMIN = os.environ.get('FLASKY_ADMIN')\n",
" SQLALCHEMY_TRACK_MODIFICATIONS = False\n",
"86 \n",
"| \n",
"Chapter 7: Large Application Structure\n",
"\n",
" @staticmethod\n",
" def init_app(app):\n",
" pass\n",
"class DevelopmentConfig(Config):\n",
" DEBUG = True\n",
" SQLALCHEMY_DATABASE_URI = os.environ.get('DEV_DATABASE_URL') or \\\n",
" 'sqlite:///' + os.path.join(basedir, 'data-dev.sqlite')\n",
"class TestingConfig(Config):\n",
" TESTING = True\n",
" SQLALCHEMY_DATABASE_URI = os.environ.get('TEST_DATABASE_URL') or \\\n",
" 'sqlite://'\n",
"class ProductionConfig(Config):\n",
" SQLALCHEMY_DATABASE_URI = os.environ.get('DATABASE_URL') or \\\n",
" 'sqlite:///' + os.path.join(basedir, 'data.sqlite')\n",
"config = {\n",
" 'development': DevelopmentConfig,\n",
" 'testing': TestingConfig,\n",
" 'production': ProductionConfig,\n",
" 'default': DevelopmentConfig\n",
"}\n",
"The Config base class contains settings that are common to all configurations; the\n",
"different subclasses define settings that are specific to a configuration. Additional\n",
"configurations can be added as needed.\n",
"To make configuration more flexible and safe, most settings can be optionally impor‐\n",
"ted from environment variables. For example, the value of the SECRET_KEY, due to its\n",
"sensitive nature, can be set in the environment, but a default value is provided in case\n",
"the environment does not define it. Typically, these settings can be used with their\n",
"defaults during development but should each have an appropriate value set in the\n",
"corresponding environment variable on the production server. The configuration\n",
"options for the email server are all imported from environment variables as well, with\n",
"defaults pointing to the Gmail server for convenience during development.\n",
"Never write passwords or other secrets in a configuration file that is\n",
"committed to source control.\n",
"The SQLALCHEMY_DATABASE_URI variable is assigned different values under each of the\n",
"three configurations. This enables the application to use a different database in each\n",
"Configuration Options \n",
"| \n",
"87\n",
"\n",
"configuration. This is very important, as you don’t want a run of the unit tests to\n",
"change the database that you use for day-to-day development. Each configuration\n",
"tries to import the database URL from an environment variable, and when that is not\n",
"available it sets a default one based on SQLite. For the testing configuration, the\n",
"default is an in-memory database, since there is no need to store any data outside of\n",
"the test run.\n",
"The development and production configurations each have a set of mail server con‐\n",
"figuration options. As an additional way to allow the application to customize its con‐\n",
"figuration, the Config class and its subclasses can define an init_app() class method\n",
"that takes the application instance as an argument. For now the base Config class\n",
"implements an empty init_app() method.\n",
"At the bottom of the configuration script, the different configurations are registered\n",
"in a config dictionary. One of the configurations (the one for development, in this\n",
"case) is also registered as the default.\n",
"Application Package\n",
"The application package is where all the application code, templates, and static files\n",
"live. It is called simply app here, though it can be given an application-specific name if\n",
"desired. The templates and static directories are now part of the application package,\n",
"so they are moved inside app. The database models and the email support functions\n",
"are also moved inside this package, each in its own module, as app/models.py and\n",
"app/email.py.\n",
"Using an Application Factory\n",
"The way the application is created in the single-file version is very convenient, but it\n",
"has one big drawback. Because the application is created in the global scope, there is\n",
"no way to apply configuration changes dynamically: by the time the script is running,\n",
"the application instance has already been created, so it is already too late to make\n",
"configuration changes. This is particularly important for unit tests because sometimes\n",
"it is necessary to run the application under different configuration settings for better\n",
"test coverage.\n",
"The solution to this problem is to delay the creation of the application by moving it\n",
"into a factory function that can be explicitly invoked from the script. This not only\n",
"gives the script time to set the configuration, but also the ability to create multiple\n",
"application instances—another thing that can be very useful during testing. The\n",
"application factory function, shown in Example 7-3, is defined in the app package\n",
"constructor.\n",
"88 \n",
"| \n",
"Chapter 7: Large Application Structure\n",
"\n",
"Example 7-3. app/__init__.py: application package constructor\n",
"from flask import Flask, render_template\n",
"from flask_bootstrap import Bootstrap\n",
"from flask_mail import Mail\n",
"from flask_moment import Moment\n",
"from flask_sqlalchemy import SQLAlchemy\n",
"from config import config\n",
"bootstrap = Bootstrap()\n",
"mail = Mail()\n",
"moment = Moment()\n",
"db = SQLAlchemy()\n",
"def create_app(config_name):\n",
" app = Flask(__name__)\n",
" app.config.from_object(config[config_name])\n",
" config[config_name].init_app(app)\n",
" bootstrap.init_app(app)\n",
" mail.init_app(app)\n",
" moment.init_app(app)\n",
" db.init_app(app)\n",
" # attach routes and custom error pages here\n",
" return app\n",
"This constructor imports most of the Flask extensions currently in use, but because\n",
"there is no application instance to initialize them with, it creates them uninitialized\n",
"by passing no arguments into their constructors. The create_app() function is the\n",
"application factory, which takes as an argument the name of a configuration to use\n",
"for the application. The configuration settings stored in one of the classes defined in\n",
"config.py can be imported directly into the application using the from_object()\n",
"method available in Flask’s app.config configuration object. The configuration\n",
"object is selected by name from the config dictionary. Once an application is created\n",
"and configured, the extensions can be initialized. Calling init_app() on the exten‐\n",
"sions that were created earlier completes their initialization.\n",
"The application initialization is now done in this factory function, using the\n",
"from_object() method from the Flask configuration object, which takes as an argu‐\n",
"ment one of the configuration classes defined in config.py. The init_app() method of\n",
"the selected configuration is also invoked, to allow more complex initialization proce‐\n",
"dures to take place.\n",
"The factory function returns the created application instance, but note that applica‐\n",
"tions created with the factory function in its current state are incomplete, as they are\n",
"missing routes and custom error page handlers. This is the topic of the next section.\n",
"Application Package \n",
"| \n",
"89\n",
"\n",
"Implementing Application Functionality in a Blueprint\n",
"The conversion to an application factory introduces a complication for routes. In\n",
"single-script applications, the application instance exists in the global scope, so routes\n",
"can be easily defined using the app.route decorator. But now that the application is\n",
"created at runtime, the app.route decorator begins to exist only after create_app()\n",
"is invoked, which is too late. Custom error page handlers present the same problem,\n",
"as these are defined with the app.errorhandler decorator.\n",
"Luckily, Flask offers a better solution using blueprints. A blueprint is similar to an\n",
"application in that it can also define routes and error handlers. The difference is that\n",
"when these are defined in a blueprint they are in a dormant state until the blueprint is\n",
"registered with an application, at which point they become part of it. Using a blue‐\n",
"print defined in the global scope, the routes and error handlers of the application can\n",
"be defined in almost the same way as in the single-script application.\n",
"Like applications, blueprints can be defined all in a single file or can be created in a\n",
"more structured way with multiple modules inside a package. To allow for the great‐\n",
"est flexibility, a subpackage inside the application package will be created to host the\n",
"first blueprint of the application. Example 7-4 shows the package constructor, which\n",
"creates the blueprint.\n",
"Example 7-4. app/main/__init__.py: main blueprint creation\n",
"from flask import Blueprint\n",
"main = Blueprint('main', __name__)\n",
"from . import views, errors\n",
"Blueprints are created by instantiating an object of class Blueprint. The constructor\n",
"for this class takes two required arguments: the blueprint name and the module or\n",
"package where the blueprint is located. As with applications, Python’s __name__ vari‐\n",
"able is in most cases the correct value for the second argument.\n",
"The routes of the application are stored in an app/main/views.py module inside the\n",
"package, and the error handlers are in app/main/errors.py. Importing these modules\n",
"causes the routes and error handlers to be associated with the blueprint. It is impor‐\n",
"tant to note that the modules are imported at the bottom of the app/main/__init__.py\n",
"script to avoid errors due to circular dependencies. In this particular example the\n",
"problem is that app/main/views.py and app/main/errors.py in turn are going to import\n",
"the main blueprint object, so the imports are going to fail unless the circular reference\n",
"occurs after main is defined.\n",
"90 \n",
"| \n",
"Chapter 7: Large Application Structure\n",
"\n",
"The from . import <some-module> syntax is used in Python to\n",
"represent relative imports. The . in this statement represents the\n",
"current package. You are going to see another very useful relative\n",
"import soon that uses the form from .. import <some-module>,\n",
"where .. represents the parent of the current package.\n",
"The blueprint is registered with the application inside the create_app() factory func‐\n",
"tion, as shown in Example 7-5.\n",
"Example 7-5. app/__init__.py: main blueprint registration\n",
"def create_app(config_name):\n",
" # ...\n",
" from .main import main as main_blueprint\n",
" app.register_blueprint(main_blueprint)\n",
" return app\n",
"Example 7-6 shows the error handlers.\n",
"Example 7-6. app/main/errors.py: error handlers in main blueprint\n",
"from flask import render_template\n",
"from . import main\n",
"@main.app_errorhandler(404)\n",
"def page_not_found(e):\n",
" return render_template('404.html'), 404\n",
"@main.app_errorhandler(500)\n",
"def internal_server_error(e):\n",
" return render_template('500.html'), 500\n",
"A difference when writing error handlers inside a blueprint is that if the\n",
"errorhandler decorator is used, the handler will be invoked only for errors that orig‐\n",
"inate in the routes defined by the blueprint. To install application-wide error han‐\n",
"dlers, the app_errorhandler decorator must be used instead.\n",
"Example 7-7 shows the route of the application updated to be in the blueprint.\n",
"Application Package \n",
"| \n",
"91\n",
"\n",
"Example 7-7. app/main/views.py: application routes in main blueprint\n",
"from datetime import datetime\n",
"from flask import render_template, session, redirect, url_for\n",
"from . import main\n",
"from .forms import NameForm\n",
"from .. import db\n",
"from ..models import User\n",
"@main.route('/', methods=['GET', 'POST'])\n",
"def index():\n",
" form = NameForm()\n",
" if form.validate_on_submit():\n",
" # ...\n",
" return redirect(url_for('.index'))\n",
" return render_template('index.html',\n",
" form=form, name=session.get('name'),\n",
" known=session.get('known', False),\n",
" current_time=datetime.utcnow())\n",
"There are two main differences when writing a view function inside a blueprint. First,\n",
"as was done for error handlers earlier, the route decorator comes from the blueprint,\n",
"so main.route is used instead of app.route. The second difference is in the usage of\n",
"the url_for() function. As you may recall, the first argument to this function is the\n",
"endpoint name of the route, which for application-based routes defaults to the name\n",
"of the view function. For example, in a single-script application the URL for an\n",
"index() view function can be obtained with url_for('index').\n",
"The difference with blueprints is that Flask applies a namespace to all the endpoints\n",
"defined in a blueprint, so that multiple blueprints can define view functions with the\n",
"same endpoint names without collisions. The namespace is the name of the blueprint\n",
"(the first argument to the Blueprint constructor) and is separated from the endpoint\n",
"name with a dot. The index() view function is then registered with endpoint name\n",
"main.index and its URL can be obtained with url_for('main.index').\n",
"The url_for() function also supports a shorter format for endpoints in blueprints in\n",
"which the blueprint name is omitted, such as url_for('.index'). With this nota‐\n",
"tion, the blueprint name for the current request is used to complete the endpoint\n",
"name. This effectively means that redirects within the same blueprint can use the\n",
"shorter form, while redirects across blueprints must use the fully qualified endpoint\n",
"name that includes the blueprint name.\n",
"To complete the changes to the application package, the form objects are also stored\n",
"inside the blueprint in the app/main/forms.py module.\n",
"92 \n",
"| \n",
"Chapter 7: Large Application Structure\n",
"\n",
"Application Script\n",
"The flasky.py module in the top-level directory is where the application instance is\n",
"defined. This script is shown in Example 7-8.\n",
"Example 7-8. flasky.py: main script\n",
"import os\n",
"from app import create_app, db\n",
"from app.models import User, Role\n",
"from flask_migrate import Migrate\n",
"app = create_app(os.getenv('FLASK_CONFIG') or 'default')\n",
"migrate = Migrate(app, db)\n",
"@app.shell_context_processor\n",
"def make_shell_context():\n",
" return dict(db=db, User=User, Role=Role)\n",
"The script begins by creating an application. The configuration is taken from the\n",
"environment variable FLASK_CONFIG if it’s defined, or else the default configuration is\n",
"used. Flask-Migrate and the custom context for the Python shell are then initialized.\n",
"Because the main script of the application changed from hello.py to flasky.py, the\n",
"FLASK_APP environment variable needs to be updated accordingly so that the flask\n",
"command can locate the application instance. It is also useful to enable Flask’s debug\n",
"mode by setting FLASK_DEBUG=1. For Linux and macOS, this is all done as follows:\n",
"(venv) $ export FLASK_APP=flasky.py\n",
"(venv) $ export FLASK_DEBUG=1\n",
"And for Microsoft Windows:\n",
"(venv) $ set FLASK_APP=flasky.py\n",
"(venv) $ set FLASK_DEBUG=1\n",
"Requirements File\n",
"It is a good practice for applications to include a requirements.txt file that records all\n",
"the package dependencies, with the exact version numbers. This is important in case\n",
"the virtual environment needs to be regenerated on a different machine, such as the\n",
"machine on which the application will be deployed for production use. This file can\n",
"be generated automatically by pip with the following command:\n",
"(venv) $ pip freeze >requirements.txt\n",
"It is a good idea to refresh this file whenever a package is installed or upgraded. An\n",
"example requirements file is shown here:\n",
"Application Script \n",
"| \n",
"93\n",
"\n",
"alembic==0.9.3\n",
"blinker==1.4\n",
"click==6.7\n",
"dominate==2.3.1\n",
"Flask==0.12.2\n",
"Flask-Bootstrap==3.3.7.1\n",
"Flask-Mail==0.9.1\n",
"Flask-Migrate==2.0.4\n",
"Flask-Moment==0.5.1\n",
"Flask-SQLAlchemy==2.2\n",
"Flask-WTF==0.14.2\n",
"itsdangerous==0.24\n",
"Jinja2==2.9.6\n",
"Mako==1.0.7\n",
"MarkupSafe==1.0\n",
"python-dateutil==2.6.1\n",
"python-editor==1.0.3\n",
"six==1.10.0\n",
"SQLAlchemy==1.1.11\n",
"visitor==0.1.3\n",
"Werkzeug==0.12.2\n",
"WTForms==2.1\n",
"When you need to build a perfect replica of the virtual environment, you can create a\n",
"new virtual environment and run the following command on it:\n",
"(venv) $ pip install -r requirements.txt\n",
"The version numbers in the example requirements.txt file are likely going to be outda‐\n",
"ted by the time you read this. You can try using more recent releases of the packages,\n",
"if you like. If you experience any problems, you can always go back to the versions\n",
"specified here, as those are known to be compatible with the application.\n",
"Unit Tests\n",
"This application is very small, so there isn’t a lot to test yet. But as an example, two\n",
"simple tests can be defined, as shown in Example 7-9.\n",
"Example 7-9. tests/test_basics.py: unit tests\n",
"import unittest\n",
"from flask import current_app\n",
"from app import create_app, db\n",
"class BasicsTestCase(unittest.TestCase):\n",
" def setUp(self):\n",
" self.app = create_app('testing')\n",
" self.app_context = self.app.app_context()\n",
" self.app_context.push()\n",
" db.create_all()\n",
"94 \n",
"| \n",
"Chapter 7: Large Application Structure\n",
"\n",
" def tearDown(self):\n",
" db.session.remove()\n",
" db.drop_all()\n",
" self.app_context.pop()\n",
" def test_app_exists(self):\n",
" self.assertFalse(current_app is None)\n",
" def test_app_is_testing(self):\n",
" self.assertTrue(current_app.config['TESTING'])\n",
"The tests are written using the standard unittest package from the Python standard\n",
"library. The setUp() and tearDown() methods of the test case class run before and\n",
"after each test, and any methods that have a name that begins with test_ are executed\n",
"as tests.\n",
"If you want to learn more about writing unit tests with Python’s\n",
"unittest package, read the official documentation.\n",
"The setUp() method tries to create an environment for the test that is close to that of\n",
"a running application. It first creates an application configured for testing and acti‐\n",
"vates its context. This step ensures that tests have access to current_app, like regular\n",
"requests do. Then it creates a brand-new database for the tests using Flask-\n",
"SQLAlchemy’s create_all() method. The database and the application context are\n",
"removed in the tearDown() method.\n",
"The first test ensures that the application instance exists. The second test ensures that\n",
"the application is running under the testing configuration. To make the tests directory\n",
"a proper package, a tests/init.py module needs to be added, but this can be an empty\n",
"file, as the unittest package scans all the modules to discover the tests.\n",
"If you have cloned the application’s Git repository on GitHub, you\n",
"can run git checkout 7a to check out the converted version of the\n",
"application. To ensure that you have all the dependencies installed,\n",
"also run pip install -r requirements.txt.\n",
"To run the unit tests, a custom command can be added to the flasky.py script.\n",
"Example 7-10 shows how to add a test command.\n",
"Unit Tests \n",
"| \n",
"95\n",
"\n",
"Example 7-10. flasky.py: unit test launcher command\n",
"@app.cli.command()\n",
"def test():\n",
" \"\"\"Run the unit tests.\"\"\"\n",
" import unittest\n",
" tests = unittest.TestLoader().discover('tests')\n",
" unittest.TextTestRunner(verbosity=2).run(tests)\n",
"The app.cli.command decorator makes it simple to implement custom commands.\n",
"The name of the decorated function is used as the command name, and the function’s\n",
"docstring is displayed in the help messages. The implementation of the test() func‐\n",
"tion invokes the test runner from the unittest package.\n",
"The unit tests can be executed as follows:\n",
"(venv) $ flask test\n",
"test_app_exists (test_basics.BasicsTestCase) ... ok\n",
"test_app_is_testing (test_basics.BasicsTestCase) ... ok\n",
".----------------------------------------------------------------------\n",
"Ran 2 tests in 0.001s\n",
"OK\n",
"----\n",
"Database Setup\n",
"The restructured application uses a different database than the single-script version.\n",
"The database URL is taken from an environment variable as a first choice, with a\n",
"default SQLite database as an alternative. The environment variables and SQLite\n",
"database filenames are different for each of the three configurations. For example, in\n",
"the development configuration the URL is obtained from the environment variable\n",
"DEV_DATABASE_URL, and if that is not defined then an SQLite database with the name\n",
"data-dev.sqlite is used.\n",
"Regardless of the source of the database URL, the database tables must be created for\n",
"the new database. When working with Flask-Migrate to keep track of migrations,\n",
"database tables can be created or upgraded to the latest revision with a single com‐\n",
"mand:\n",
"(venv) $ flask db upgrade\n",
"96 \n",
"| \n",
"Chapter 7: Large Application Structure\n",
"\n",
"Running the Application\n",
"The refactoring is now complete, and the application can be started. Make sure you\n",
"have updated the FLASK_APP environment variable as indicated in “Application Script”\n",
"on page 93, and then run the application as usual:\n",
"(venv) $ flask run\n",
"Having to set the FLASK_APP and FLASK_DEBUG environment variables every time a\n",
"new command-prompt session is started can get tedious, so you should configure\n",
"your system so that these variables are set by default. If you are using bash, you can\n",
"add them to your ~/.bashrc file.\n",
"Believe it or not, you have reached the end of Part I. You have now learned about the\n",
"basic elements necessary to build a web application with Flask, but you probably feel\n",
"unsure about how all these pieces fit together to form a real application. The goal of\n",
"Part II is to help with that by walking you through the development of a complete\n",
"application.\n",
"Running the Application \n",
"| \n",
"97\n",
"\n",
"\n",
"PART II\n",
"Example: A Social\n",
"Blogging Application\n",
"\n",
"\n",
"CHAPTER 8\n",
"User Authentication\n",
"Most applications need to keep track of who their users are. When users connect with\n",
"an application, they authenticate with it, a process by which they make their identity\n",
"known. Once the application knows who the user is, it can offer a customized experi‐\n",
"ence.\n",
"The most commonly used method of authentication requires users to provide a piece\n",
"of identification, which is either their email address or username, and a secret only\n",
"known to them, which is called the password. In this chapter, the complete authenti‐\n",
"cation system for Flasky is created.\n",
"Authentication Extensions for Flask\n",
"There are many excellent Python authentication packages, but none of them do\n",
"everything. The user authentication solution presented in this chapter uses several\n",
"packages and provides the glue that makes them work well together. This is the list of\n",
"packages that will be used, and what they’re used for:\n",
"• Flask-Login: Management of user sessions for logged-in users\n",
"• Werkzeug: Password hashing and verification\n",
"• itsdangerous: Cryptographically secure token generation and verification\n",
"In addition to authentication-specific packages, the following general-purpose exten‐\n",
"sions will be used:\n",
"• Flask-Mail: Sending of authentication-related emails\n",
"• Flask-Bootstrap: HTML templates\n",
"• Flask-WTF: Web forms\n",
"101\n",
"\n",
"Password Security\n",
"The safety of user information stored in databases is often overlooked during the\n",
"design of web applications. If an attacker is able to break into your server and access\n",
"your user database, then you risk the security of your users—and the risk is bigger\n",
"than you think. It is a known fact that most users use the same password on multiple\n",
"sites, so even if you don’t store any sensitive information, access to the passwords\n",
"stored in your database can give the attacker access to accounts your users have on\n",
"other sites.\n",
"The key to storing user passwords securely in a database relies on not storing the\n",
"password itself but a hash of it. A password hashing function takes a password as\n",
"input, adds a random component to it (the salt), and then applies several one-way\n",
"cryptographic transformations to it. The result is a new sequence of characters that\n",
"has no resemblance to the original password, and has no known way to be trans‐\n",
"formed back into the original password. Password hashes can be verified in place of\n",
"the real passwords because hashing functions are repeatable: given the same inputs\n",
"(the password and the salt), the result is always the same.\n",
"Password hashing is a complex task that is hard to get right. It is\n",
"recommended that you don’t implement your own solution but\n",
"instead rely on well-known libraries that have been reviewed by the\n",
"community. In the next section, Werkzeug’s password hashing\n",
"functions will be demonstrated. Other good choices for password\n",
"hashing are bcrypt and Passlib. If you are interested in learning\n",
"what’s involved in generating secure password hashes, the article\n",
"“Salted Password Hashing - Doing It Right” by Defuse Security is a\n",
"worthwhile read.\n",
"Hashing Passwords with Werkzeug\n",
"Werkzeug’s security module conveniently implements secure password hashing. This\n",
"functionality is exposed with just two functions, used in the registration and verifica‐\n",
"tion phases, respectively:\n",
"generate_password_hash(password, method='pbkdf2:sha256', salt_length=8)\n",
"This function takes a plain-text password and returns the password hash as a\n",
"string that can be stored in the user database. The default values for method and\n",
"salt_length are sufficient for most use cases.\n",
"check_password_hash(hash, password)\n",
"This function takes a password hash previously stored in the database and the\n",
"password entered by the user. A return value of True indicates that the user pass‐\n",
"word is correct.\n",
"102 \n",
"| \n",
"Chapter 8: User Authentication\n",
"\n",
"Example 8-1 shows the changes to the User model created in Chapter 5 to accommo‐\n",
"date password hashing.\n",
"Example 8-1. app/models.py: password hashing in the User model\n",
"from werkzeug.security import generate_password_hash, check_password_hash\n",
"class User(db.Model):\n",
" # ...\n",
" password_hash = db.Column(db.String(128))\n",
" @property\n",
" def password(self):\n",
" raise AttributeError('password is not a readable attribute')\n",
" @password.setter\n",
" def password(self, password):\n",
" self.password_hash = generate_password_hash(password)\n",
" def verify_password(self, password):\n",
" return check_password_hash(self.password_hash, password)\n",
"The password hashing function is implemented through a write-only property called\n",
"password. When this property is set, the setter method will call Werkzeug’s\n",
"generate_password_hash() function and write the result to the password_hash field.\n",
"Attempting to read the password property will return an error, as clearly the original\n",
"password cannot be recovered once hashed.\n",
"The verify_password() method takes a password and passes it to Werkzeug’s\n",
"check_password_hash() function for verification against the hashed version stored\n",
"in the User model. If this method returns True, then the password is correct.\n",
"If you have cloned the application’s Git repository on GitHub, you\n",
"can run git checkout 8a to check out this version of the applica‐\n",
"tion.\n",
"Password Security \n",
"| \n",
"103\n",
"\n",
"The password hashing functionality is now complete and can be tested in the shell:\n",
"(venv) $ flask shell\n",
">>> u = User()\n",
">>> u.password = 'cat'\n",
">>> u.password\n",
"Traceback (most recent call last):\n",
" File \"<console>\", line 1, in <module>\n",
" File \"/home/flask/flasky/app/models.py\", line 24, in password\n",
" raise AttributeError('password is not a readable attribute')\n",
"AttributeError: password is not a readable attribute\n",
">>> u.password_hash\n",
"'pbkdf2:sha256:50000$moHwFH1B$ef1574909f9c549285e8547cad181c5e0213cfa44a4aba4349\n",
"fa830aa1fd227f'\n",
">>> u.verify_password('cat')\n",
"True\n",
">>> u.verify_password('dog')\n",
"False\n",
">>> u2 = User()\n",
">>> u2.password = 'cat'\n",
">>> u2.password_hash\n",
"'pbkdf2:sha256:50000$Pfz0m0KU$27be930b7f0e0119d38e8d8a62f7f5e75c0a7db61ae16709bc\n",
"aa6cfd60c44b74'\n",
"Note how trying to access the password property of a user returns an\n",
"AttributeError. Also, users u and u2 have completely different password hashes,\n",
"even though they both use the same password. To ensure that this functionality con‐\n",
"tinues to work in the future, the preceding tests done manually can be written as unit\n",
"tests that can be repeated easily. In Example 8-2 a new module inside the tests package\n",
"is shown with three new tests that exercise the recent changes to the User model.\n",
"Example 8-2. tests/test_user_model.py: password hashing tests\n",
"import unittest\n",
"from app.models import User\n",
"class UserModelTestCase(unittest.TestCase):\n",
" def test_password_setter(self):\n",
" u = User(password = 'cat')\n",
" self.assertTrue(u.password_hash is not None)\n",
" def test_no_password_getter(self):\n",
" u = User(password = 'cat')\n",
" with self.assertRaises(AttributeError):\n",
" u.password\n",
" def test_password_verification(self):\n",
" u = User(password = 'cat')\n",
" self.assertTrue(u.verify_password('cat'))\n",
" self.assertFalse(u.verify_password('dog'))\n",
"104 \n",
"| \n",
"Chapter 8: User Authentication\n",
"\n",
" def test_password_salts_are_random(self):\n",
" u = User(password='cat')\n",
" u2 = User(password='cat')\n",
" self.assertTrue(u.password_hash != u2.password_hash)\n",
"To run these new unit tests, use the following command:\n",
"(venv) $ flask test\n",
"test_app_exists (test_basics.BasicsTestCase) ... ok\n",
"test_app_is_testing (test_basics.BasicsTestCase) ... ok\n",
"test_no_password_getter (test_user_model.UserModelTestCase) ... ok\n",
"test_password_salts_are_random (test_user_model.UserModelTestCase) ... ok\n",
"test_password_setter (test_user_model.UserModelTestCase) ... ok\n",
"test_password_verification (test_user_model.UserModelTestCase) ... ok\n",
".----------------------------------------------------------------------\n",
"Ran 6 tests in 0.379s\n",
"OK\n",
"You can run the unit test suite like this every time you want to confirm everything is\n",
"working as expected. Having the automation in place makes verifying this feature\n",
"very low cost, so testing should be repeated often, to ensure that this functionality\n",
"does not break in the future.\n",
"Creating an Authentication Blueprint\n",
"Blueprints were introduced in Chapter 7 as a way to define routes in the global scope\n",
"after the creation of the application was moved into a factory function. In this sec‐\n",
"tion, the routes related to the user authentication subsystem will be added to a second\n",
"blueprint, called auth. Using different blueprints for different subsystems of the\n",
"application is a great way to keep the code neatly organized.\n",
"The auth blueprint will be hosted in a Python package with the same name. The blue‐\n",
"print’s package constructor creates the blueprint object and imports routes from a\n",
"views.py module. This is shown in Example 8-3.\n",
"Example 8-3. app/auth/__init__.py: authentication blueprint creation\n",
"from flask import Blueprint\n",
"auth = Blueprint('auth', __name__)\n",
"from . import views\n",
"The app/auth/views.py module, shown in Example 8-4, imports the blueprint and\n",
"defines the routes associated with authentication using its route decorator. For now,\n",
"a /login route is added, which renders a placeholder template of the same name.\n",
"Creating an Authentication Blueprint \n",
"| \n",
"105\n",
"\n",
"Example 8-4. app/auth/views.py: authentication blueprint routes and view functions\n",
"from flask import render_template\n",
"from . import auth\n",
"@auth.route('/login')\n",
"def login():\n",
" return render_template('auth/login.html')\n",
"Note that the template file given to render_template() is stored inside the auth\n",
"directory. This directory must be created inside app/templates, as Flask expects the\n",
"templates’ paths to be relative to the application’s templates directory. By storing the\n",
"blueprint templates in their own subdirectory, there is no risk of naming collisions\n",
"with the main blueprint or any other blueprints that will be added in the future.\n",
"Blueprints can also be configured to have their own independent\n",
"directories for templates. When multiple template directories have\n",
"been configured, the render_template() function searches the\n",
"templates directory configured for the application first, and then\n",
"searches the template directories defined by blueprints.\n",
"The auth blueprint needs to be attached to the application in the create_app() fac‐\n",
"tory function, as shown in Example 8-5.\n",
"Example 8-5. app/__init__.py: authentication blueprint registration\n",
"def create_app(config_name):\n",
" # ...\n",
" from .auth import auth as auth_blueprint\n",
" app.register_blueprint(auth_blueprint, url_prefix='/auth')\n",
" return app\n",
"The url_prefix argument in the blueprint registration is optional. When used, all\n",
"the routes defined in the blueprint will be registered with the given prefix, in this\n",
"case /auth. For example, the /login route will be registered as /auth/login, and the fully\n",
"qualified URL under the development web server then becomes http://localhost:5000/\n",
"auth/login.\n",
"If you have cloned the application’s Git repository on GitHub, you\n",
"can run git checkout 8b to check out this version of the applica‐\n",
"tion.\n",
"106 \n",
"| \n",
"Chapter 8: User Authentication\n",
"\n",
"User Authentication with Flask-Login\n",
"When users log in to the application, their authenticated state has to be recorded in\n",
"the user session, so that it is remembered as they navigate through different pages.\n",
"Flask-Login is a small but extremely useful extension that specializes in managing\n",
"this particular aspect of a user authentication system, without being tied to a specific\n",
"authentication mechanism.\n",
"To begin, the extension needs to be installed in the virtual environment:\n",
"(venv) $ pip install flask-login\n",
"Preparing the User Model for Logins\n",
"Flask-Login works closely with the application’s own User objects. To be able to work\n",
"with the application’s User model, the Flask-Login extension requires it to implement\n",
"a few common properties and methods. The required items are shown in Table 8-1.\n",
"Table 8-1. Flask-Login required items\n",
"Property/method\n",
"Description\n",
"is_authenticated Must be True if the user has valid login credentials or False otherwise.\n",
"is_active\n",
"Must be True if the user is allowed to log in or False otherwise. A False value can be used for\n",
"disabled accounts.\n",
"is_anonymous\n",
"Must always be False for regular users and True for a special user object that represents\n",
"anonymous users.\n",
"get_id()\n",
"Must return a unique identifier for the user, encoded as a Unicode string.\n",
"These properties and methods can be implemented directly in the model class, but as\n",
"an easier alternative Flask-Login provides a UserMixin class that has default imple‐\n",
"mentations that are appropriate for most cases. The updated User model is shown in\n",
"Example 8-6.\n",
"Example 8-6. app/models.py: updates to the User model to support user logins\n",
"from flask_login import UserMixin\n",
"class User(UserMixin, db.Model):\n",
" __tablename__ = 'users'\n",
" id = db.Column(db.Integer, primary_key = True)\n",
" email = db.Column(db.String(64), unique=True, index=True)\n",
" username = db.Column(db.String(64), unique=True, index=True)\n",
" password_hash = db.Column(db.String(128))\n",
" role_id = db.Column(db.Integer, db.ForeignKey('roles.id'))\n",
"User Authentication with Flask-Login \n",
"| \n",
"107\n",
"\n",
"Note that an email field was also added. In this application, users will log in with\n",
"their email addresses, as they are less likely to forget those than their usernames.\n",
"Flask-Login is initialized in the application factory function, as shown in\n",
"Example 8-7.\n",
"Example 8-7. app/__init__.py: Flask-Login initialization\n",
"from flask_login import LoginManager\n",
"login_manager = LoginManager()\n",
"login_manager.login_view = 'auth.login'\n",
"def create_app(config_name):\n",
" # ...\n",
" login_manager.init_app(app)\n",
" # ...\n",
"The login_view attribute of the LoginManager object sets the endpoint for the login\n",
"page. Flask-Login will redirect to the login page when an anonymous user tries to\n",
"access a protected page. Because the login route is inside a blueprint, it needs to be\n",
"prefixed with the blueprint name.\n",
"Finally, Flask-Login requires the application to designate a function to be invoked\n",
"when the extension needs to load a user from the database given its identifier. This\n",
"function is shown in Example 8-8.\n",
"Example 8-8. app/models.py: user loader function\n",
"from . import login_manager\n",
"@login_manager.user_loader\n",
"def load_user(user_id):\n",
" return User.query.get(int(user_id))\n",
"The login_manager.user_loader decorator is used to register the function with\n",
"Flask-Login, which will call it when it needs to retrieve information about the logged-\n",
"in user. The user identifier will be passed as a string, so the function converts it to an\n",
"integer before it passes it to the Flask-SQLAlchemy query that loads the user. The\n",
"return value of the function must be the user object, or None if the user identifier is\n",
"invalid or any other error occurred.\n",
"Protecting Routes\n",
"To protect a route so that it can only be accessed by authenticated users, Flask-Login\n",
"provides a login_required decorator. An example of its usage follows:\n",
"108 \n",
"| \n",
"Chapter 8: User Authentication\n",
"\n",
"from flask_login import login_required\n",
"@app.route('/secret')\n",
"@login_required\n",
"def secret():\n",
" return 'Only authenticated users are allowed!'\n",
"You can see from this example that it is possible to “chain” multiple function decora‐\n",
"tors. When two or more decorators are added to a function, each decorator only\n",
"affects those that are below it, in addition to the target function. In this example, the\n",
"secret() \n",
"function \n",
"will \n",
"be \n",
"protected \n",
"against \n",
"unauthorized \n",
"users \n",
"with\n",
"login_required, and then the resulting function will be registered with Flask as a\n",
"route. Reversing the order will produce the wrong result, as the original function will\n",
"be registered as a route before it receives the additional properties from the\n",
"login_required decorator.\n",
"Thanks to the login_required decorator, if this route is accessed by a user who is not\n",
"authenticated, Flask-Login will intercept the request and send the user to the login\n",
"page instead.\n",
"Adding a Login Form\n",
"The login form that will be presented to users has a text field for the email address, a\n",
"password field, a “remember me” checkbox, and a submit button. The Flask-WTF\n",
"form class that defines this form is shown in Example 8-9.\n",
"Example 8-9. app/auth/forms.py: login form\n",
"from flask_wtf import FlaskForm\n",
"from wtforms import StringField, PasswordField, BooleanField, SubmitField\n",
"from wtforms.validators import DataRequired, Length, Email\n",
"class LoginForm(FlaskForm):\n",
" email = StringField('Email', validators=[DataRequired(), Length(1, 64),\n",
" Email()])\n",
" password = PasswordField('Password', validators=[DataRequired()])\n",
" remember_me = BooleanField('Keep me logged in')\n",
" submit = SubmitField('Log In')\n",
"The PasswordField class represents an <input> element with type=\"password\". The\n",
"BooleanField class represents a checkbox.\n",
"The email field uses the Length() and Email() validators from WTForms in addition\n",
"to DataRequired(), to ensure that the user not only provides a value for this field, but\n",
"that it is valid. When providing a list of validators, WTForms will evaluate them in\n",
"the order provided, and in case of a validation failure the error message shown will be\n",
"the one of the first validator that failed.\n",
"User Authentication with Flask-Login \n",
"| \n",
"109\n",
"\n",
"The template associated with the login page is stored in auth/login.html. This tem‐\n",
"plate just needs to render the form using Flask-Bootstrap’s wtf.quick_form() macro.\n",
"Figure 8-1 shows the login form rendered by the web browser.\n",
"Figure 8-1. Login form\n",
"The navigation bar in the base.html template uses a Jinja2 conditional to display “Log\n",
"In” or “Log Out” links depending on the logged-in state of the current user. The con‐\n",
"ditional is shown in Example 8-10.\n",
"Example 8-10. app/templates/base.html: Log In and Log Out navigation bar links\n",
"<ul class=\"nav navbar-nav navbar-right\">\n",
" {% if current_user.is_authenticated %}\n",
" <li><a href=\"{{ url_for('auth.logout') }}\">Log Out</a></li>\n",
" {% else %}\n",
" <li><a href=\"{{ url_for('auth.login') }}\">Log In</a></li>\n",
" {% endif %}\n",
"</ul>\n",
"The current_user variable used in the conditional is defined by Flask-Login and is\n",
"automatically available to view functions and templates. This variable contains the\n",
"currently logged-in user, or a proxy anonymous user object if the user is not logged\n",
"in. Anonymous user objects have the is_authenticated property set to False, so the\n",
"110 \n",
"| \n",
"Chapter 8: User Authentication\n",
"\n",
"expression current_user.is_authenticated is a convenient way to know whether\n",
"the current user is logged in.\n",
"Signing Users In\n",
"The implementation of the login() view function is shown in Example 8-11.\n",
"Example 8-11. app/auth/views.py: login route\n",
"from flask import render_template, redirect, request, url_for, flash\n",
"from flask_login import login_user\n",
"from . import auth\n",
"from ..models import User\n",
"from .forms import LoginForm\n",
"@auth.route('/login', methods=['GET', 'POST'])\n",
"def login():\n",
" form = LoginForm()\n",
" if form.validate_on_submit():\n",
" user = User.query.filter_by(email=form.email.data).first()\n",
" if user is not None and user.verify_password(form.password.data):\n",
" login_user(user, form.remember_me.data)\n",
" next = request.args.get('next')\n",
" if next is None or not next.startswith('/'):\n",
" next = url_for('main.index')\n",
" return redirect(next)\n",
" flash('Invalid username or password.')\n",
" return render_template('auth/login.html', form=form)\n",
"The view function creates a LoginForm object and uses it like the simple form in\n",
"Chapter 4. When the request is of type GET, the view function just renders the tem‐\n",
"plate, which in turn displays the form. When the form is submitted in a POST request,\n",
"Flask-WTF’s validate_on_submit() function validates the form variables, and then\n",
"attempts to log the user in.\n",
"To log a user in, the function begins by loading the user from the database using the\n",
"email provided with the form. If a user with the given email address exists, then its\n",
"verify_password() method is called with the password that also came with the form.\n",
"If the password is valid, Flask-Login’s login_user() function is invoked to record the\n",
"user as logged in for the user session. The login_user() function takes the user to\n",
"log in and an optional “remember me” Boolean, which was also submitted with the\n",
"form. A value of False for this argument causes the user session to expire when the\n",
"browser window is closed, so the user will have to log in again next time. A value of\n",
"True causes a long-term cookie to be set in the user’s browser, which Flask-Login uses\n",
"to restore the user session. The optional REMEMBER_COOKIE_DURATION configuration\n",
"option can be used to change the default one-year duration for the remember cookie.\n",
"User Authentication with Flask-Login \n",
"| \n",
"111\n",
"\n",
"In accordance with the Post/Redirect/Get pattern discussed in Chapter 4, the POST\n",
"request that submitted the login credentials ends with a redirect, but there are two\n",
"possible URL destinations. If the login form was presented to the user to prevent\n",
"unauthorized access to a protected URL the user wanted to visit, then Flask-Login\n",
"will have saved that original URL in the next query string argument, which can be\n",
"accessed from the request.args dictionary. If the next query string argument is not\n",
"available, a redirect to the home page is issued instead. The URL in next is validated\n",
"to make sure it is a relative URL, to prevent a malicious user from using this argu‐\n",
"ment to redirect unsuspecting users to another site.\n",
"For the case where the email address or password provided by the user is invalid, a\n",
"flash message is set and the form is rendered again for the user to retry.\n",
"On a production server, the application must be made available\n",
"over secure HTTP, so that login credentials and user sessions are\n",
"always transmitted encrypted. Without secure HTTP, sensitive data\n",
"can be intercepted during transit by an attacker.\n",
"The login template needs to be updated to render the form. These changes are shown\n",
"in Example 8-12.\n",
"Example 8-12. app/templates/auth/login.html: login form template\n",
"{% extends \"base.html\" %}\n",
"{% import \"bootstrap/wtf.html\" as wtf %}\n",
"{% block title %}Flasky - Login{% endblock %}\n",
"{% block page_content %}\n",
"<div class=\"page-header\">\n",
" <h1>Login</h1>\n",
"</div>\n",
"<div class=\"col-md-4\">\n",
" {{ wtf.quick_form(form) }}\n",
"</div>\n",
"{% endblock %}\n",
"Signing Users Out\n",
"The implementation of the logout route is shown in Example 8-13.\n",
"Example 8-13. app/auth/views.py: logout route\n",
"from flask_login import logout_user, login_required\n",
"@auth.route('/logout')\n",
"112 \n",
"| \n",
"Chapter 8: User Authentication\n",
"\n",
"@login_required\n",
"def logout():\n",
" logout_user()\n",
" flash('You have been logged out.')\n",
" return redirect(url_for('main.index'))\n",
"To log a user out, Flask-Login’s logout_user() function is called to remove and reset\n",
"the user session. The logout is completed with a flash message that confirms the\n",
"action and a redirect to the home page.\n",
"If you have cloned the application’s Git repository on GitHub, you\n",
"can run git checkout 8c to check out this version of the applica‐\n",
"tion. This update contains a database migration, so remember to\n",
"run flask db upgrade after you check out the code. To ensure that\n",
"you have all the dependencies installed, also run pip install -r\n",
"requirements.txt.\n",
"Understanding How Flask-Login Works\n",
"Flask-Login is a fairly small extension, but due to the many moving pieces involved in\n",
"the authentication flow, Flask users often have trouble understanding how the exten‐\n",
"sion works. The following is the sequence of operations that occur when a user logs in\n",
"to the system:\n",
"1. The user navigates to http://localhost:5000/auth/login by clicking on the “Log In”\n",
"link. The handler for this URL returns the login form template.\n",
"2. The user enters their username and password, and presses the Submit button.\n",
"The same handler is invoked again, but now as a POST request instead of GET.\n",
"a. The handler validates the credentials submitted with the form, and then\n",
"invokes Flask-Login’s login_user() function to log the user in.\n",
"b. The login_user() function writes the ID of the user to the user session as a\n",
"string.\n",
"c. The view function returns with a redirect to the home page.\n",
"3. The browser receives the redirect and requests the home page.\n",
"a. The view function for the home page is invoked, and it triggers the rendering\n",
"of the main Jinja2 template.\n",
"b. During the rendering of the Jinja2 template, a reference to Flask-Login’s\n",
"current_user appears for the first time.\n",
"c. The current_user context variable does not have a value assigned for this\n",
"request yet, so it invokes Flask-Login’s internal function _get_user() to find\n",
"out who the user is.\n",
"User Authentication with Flask-Login \n",
"| \n",
"113\n",
"\n",
"d. The _get_user() function checks if there is a user ID stored in the user ses‐\n",
"sion. If there isn’t one, it returns an instance of Flask-Login’s AnonymousUser.\n",
"If there is an ID, it invokes the function that the application registered with\n",
"the user_loader decorator, with the ID as its argument.\n",
"e. The application’s user_loader handler reads the user from the database and\n",
"returns it. Flask-Login assigns it to the current_user context variable for the\n",
"current request.\n",
"f. The template receives the newly assigned value of current_user.\n",
"The login_required decorator builds on top of the current_user context variable\n",
"by only allowing the decorated view function to run when the expression\n",
"current_user.is_authenticated is True. The logout_user() function simply dele‐\n",
"tes the user ID from the user session.\n",
"Testing Logins\n",
"To verify that the login functionality is working, the home page can be updated to\n",
"greet the logged-in user by name. The template section that generates the greeting is\n",
"shown in Example 8-14.\n",
"Example 8-14. app/templates/index.html: greeting the logged-in user\n",
"Hello,\n",
"{% if current_user.is_authenticated %}\n",
" {{ current_user.username }}\n",
"{% else %}\n",
" Stranger\n",
"{% endif %}!\n",
"In this template once again current_user.is_authenticated is used to determine\n",
"whether the user is logged in.\n",
"Because no user registration functionality has been built, a new user can only be reg‐\n",
"istered from the shell at this time:\n",
"(venv) $ $ flask shell\n",
">>> u = User(email='john@example.com', username='john', password='cat')\n",
">>> db.session.add(u)\n",
">>> db.session.commit()\n",
"The user created previously can now log in. Figure 8-2 shows the application home\n",
"page with the user logged in.\n",
"114 \n",
"| \n",
"Chapter 8: User Authentication\n",
"\n",
"Figure 8-2. Home page after successful login\n",
"New User Registration\n",
"When new users want to become members of the application, they must register with\n",
"it so that they are known and can log in. A link in the login page will send them to a\n",
"registration page, where they can enter their email address, username, and password.\n",
"Adding a User Registration Form\n",
"The form that will be used in the registration page asks the user to enter an email\n",
"address, username, and password. This form is shown in Example 8-15.\n",
"Example 8-15. app/auth/forms.py: user registration form\n",
"from flask_wtf import FlaskForm\n",
"from wtforms import StringField, PasswordField, BooleanField, SubmitField\n",
"from wtforms.validators import DataRequired, Length, Email, Regexp, EqualTo\n",
"from wtforms import ValidationError\n",
"from ..models import User\n",
"class RegistrationForm(FlaskForm):\n",
" email = StringField('Email', validators=[DataRequired(), Length(1, 64),\n",
" Email()])\n",
"New User Registration \n",
"| \n",
"115\n",
"\n",
" username = StringField('Username', validators=[\n",
" DataRequired(), Length(1, 64),\n",
" Regexp('^[A-Za-z][A-Za-z0-9_.]*$', 0,\n",
" 'Usernames must have only letters, numbers, dots or '\n",
" 'underscores')])\n",
" password = PasswordField('Password', validators=[\n",
" DataRequired(), EqualTo('password2', message='Passwords must match.')])\n",
" password2 = PasswordField('Confirm password', validators=[DataRequired()])\n",
" submit = SubmitField('Register')\n",
" def validate_email(self, field):\n",
" if User.query.filter_by(email=field.data).first():\n",
" raise ValidationError('Email already registered.')\n",
" def validate_username(self, field):\n",
" if User.query.filter_by(username=field.data).first():\n",
" raise ValidationError('Username already in use.')\n",
"This form uses the Regexp validator from WTForms to ensure that the username field\n",
"starts with a letter and only contains letters, numbers, underscores, and dots. The two\n",
"arguments to the validator that follow the regular expression are the regular expres‐\n",
"sion flags and the error message to display on failure.\n",
"The password is entered twice as a safety measure, but this step makes it necessary to\n",
"validate that the two password fields have the same content, which is done with\n",
"another validator from WTForms called EqualTo. This validator is attached to one of\n",
"the password fields with the name of the other field given as an argument.\n",
"This form also has two custom validators implemented as methods. When a form\n",
"defines a method with the prefix validate_ followed by the name of a field, the\n",
"method is invoked in addition to any regularly defined validators. In this case, the\n",
"custom validators for email and username ensure that the values given are not dupli‐\n",
"cates. The custom validators indicate a validation error by raising a ValidationError\n",
"exception with the text of the error message as an argument.\n",
"The template that presents this form is called /templates/auth/register.html. Like the\n",
"login template, this one also renders the form with wtf.quick_form(). The registra‐\n",
"tion page is shown in Figure 8-3.\n",
"116 \n",
"| \n",
"Chapter 8: User Authentication\n",
"\n",
"Figure 8-3. New user registration form\n",
"The registration page needs to be linked from the login page so that users who don’t\n",
"have an account can easily find it. This change is shown in Example 8-16.\n",
"Example 8-16. app/templates/auth/login.html: link to the registration page\n",
"<p>\n",
" New user?\n",
" <a href=\"{{ url_for('auth.register') }}\">\n",
" Click here to register\n",
" </a>\n",
"</p>\n",
"Registering New Users\n",
"Handling user registrations does not present any big surprises. When the registration\n",
"form is submitted and validated, a new user is added to the database using the infor‐\n",
"mation provided by the user. The view function that performs this task is shown in\n",
"Example 8-17.\n",
"New User Registration \n",
"| \n",
"117\n",
"\n",
"Example 8-17. app/auth/views.py: user registration route\n",
"@auth.route('/register', methods=['GET', 'POST'])\n",
"def register():\n",
" form = RegistrationForm()\n",
" if form.validate_on_submit():\n",
" user = User(email=form.email.data,\n",
" username=form.username.data,\n",
" password=form.password.data)\n",
" db.session.add(user)\n",
" db.session.commit()\n",
" flash('You can now login.')\n",
" return redirect(url_for('auth.login'))\n",
" return render_template('auth/register.html', form=form)\n",
"If you have cloned the application’s Git repository on GitHub, you\n",
"can run git checkout 8d to check out this version of the applica‐\n",
"tion.\n",
"Account Confirmation\n",
"For certain types of applications, it is important to ensure that the user information\n",
"provided during registration is valid. A common requirement is to ensure that the\n",
"user can be reached through the provided email address.\n",
"To validate the email address, applications send a confirmation email to users imme‐\n",
"diately after they register. The new account is initially marked as unconfirmed until\n",
"the instructions in the email are followed, which proves that the user has received the\n",
"email. The account confirmation procedure usually involves clicking a specially craf‐\n",
"ted URL link that includes a confirmation token.\n",
"Generating Confirmation Tokens with itsdangerous\n",
"The simplest account confirmation link would be a URL with the format http://\n",
"www.example.com/auth/confirm/<id> included in the confirmation email, where\n",
"<id> is the numeric id assigned to the user in the database. When the user clicks the\n",
"link, the view function that handles this route receives the user id to confirm as an\n",
"argument and can easily update the confirmed status of the user.\n",
"But this is obviously not a secure implementation, as any user who figures out the\n",
"format of the confirmation links will be able to confirm arbitrary accounts just by\n",
"sending random numbers in the URL. The idea is to replace the <id> in the URL\n",
"with a token that contains the same information, but in such a way that only the\n",
"server can generate valid confirmation URLs.\n",
"118 \n",
"| \n",
"Chapter 8: User Authentication\n",
"\n",
"If you recall the discussion on user sessions in Chapter 4, Flask uses cryptographically\n",
"signed cookies to protect the content of user sessions against tampering. The user ses‐\n",
"sion cookies contain a cryptographic signature generated by a package called\n",
"itsdangerous. If the contents of the user session is altered, the signature will not\n",
"match the content anymore, so Flask discards the session and starts a new one. The\n",
"same concept can be applied to confirmation tokens.\n",
"The following is a short shell session that shows how itsdangerous can generate a\n",
"signed token that contains a user id inside:\n",
"(venv) $ flask shell\n",
">>> from itsdangerous import TimedJSONWebSignatureSerializer as Serializer\n",
">>> s = Serializer(app.config['SECRET_KEY'], expires_in=3600)\n",
">>> token = s.dumps({ 'confirm': 23 })\n",
">>> token\n",
"'eyJhbGciOiJIUzI1NiIsImV4cCI6MTM4MTcxODU1OCwiaWF0IjoxMzgxNzE0OTU4fQ.ey ...'\n",
">>> data = s.loads(token)\n",
">>> data\n",
"{'confirm': 23}\n",
"The itsdangerous package provides several types of token generators. Among them,\n",
"the class TimedJSONWebSignatureSerializer generates JSON Web Signatures (JWSs)\n",
"with a time expiration. The constructor of this class takes an encryption key as an\n",
"argument, which in a Flask application can be the configured SECRET_KEY.\n",
"The dumps() method generates a cryptographic signature for the data given as an\n",
"argument and then serializes the data plus the signature as a convenient token string.\n",
"The expires_in argument sets an expiration time for the token, expressed in sec‐\n",
"onds.\n",
"To decode the token, the serializer object provides a loads() method that takes the\n",
"token as its only argument. The function verifies the signature and the expiration\n",
"time and, if both are valid, it returns the original data. When the loads() method is\n",
"given an invalid token or a valid token that is expired, an exception is raised.\n",
"Token generation and verification using this functionality can be added to the User\n",
"model. The changes are shown in Example 8-18.\n",
"Example 8-18. app/models.py: user account confirmation\n",
"from itsdangerous import TimedJSONWebSignatureSerializer as Serializer\n",
"from flask import current_app\n",
"from . import db\n",
"class User(UserMixin, db.Model):\n",
" # ...\n",
" confirmed = db.Column(db.Boolean, default=False)\n",
"Account Confirmation \n",
"| \n",
"119\n",
"\n",
" def generate_confirmation_token(self, expiration=3600):\n",
" s = Serializer(current_app.config['SECRET_KEY'], expiration)\n",
" return s.dumps({'confirm': self.id}).decode('utf-8')\n",
" def confirm(self, token):\n",
" s = Serializer(current_app.config['SECRET_KEY'])\n",
" try:\n",
" data = s.loads(token.encode('utf-8'))\n",
" except:\n",
" return False\n",
" if data.get('confirm') != self.id:\n",
" return False\n",
" self.confirmed = True\n",
" db.session.add(self)\n",
" return True\n",
"The generate_confirmation_token() method generates a token with a default val‐\n",
"idity time of one hour. The confirm() method verifies the token and, if valid, sets the\n",
"new confirmed attribute in the user model to True.\n",
"In addition to verifying the token, the confirm() function checks that the id from\n",
"the token matches the logged-in user, which is stored in current_user. This ensures\n",
"that a confirmation token for a given user cannot be used to confirm a different user.\n",
"Because a new column was added to the model to track the con‐\n",
"firmed state of each account, a new database migration needs to be\n",
"generated and applied.\n",
"The two new methods added to the User model are easily tested in unit tests. You can\n",
"find the unit tests in the GitHub repository for the application.\n",
"Sending Confirmation Emails\n",
"The current /register route redirects to /index after adding the new user to the data‐\n",
"base. Before redirecting, this route now needs to send the confirmation email. This\n",
"change is shown in Example 8-19.\n",
"Example 8-19. app/auth/views.py: registration route with confirmation email\n",
"from ..email import send_email\n",
"@auth.route('/register', methods=['GET', 'POST'])\n",
"def register():\n",
" form = RegistrationForm()\n",
" if form.validate_on_submit():\n",
" # ...\n",
"120 \n",
"| \n",
"Chapter 8: User Authentication\n",
"\n",
" db.session.add(user)\n",
" db.session.commit()\n",
" token = user.generate_confirmation_token()\n",
" send_email(user.email, 'Confirm Your Account',\n",
" 'auth/email/confirm', user=user, token=token)\n",
" flash('A confirmation email has been sent to you by email.')\n",
" return redirect(url_for('main.index'))\n",
" return render_template('auth/register.html', form=form)\n",
"Note that a db.session.commit() call had to be added before the confirmation email\n",
"is sent out. The problem is that new users get assigned an id when they are commit‐\n",
"ted to the database, and this id is needed to generate the confirmation token.\n",
"The email templates used by the authentication blueprint will be added in the tem‐\n",
"plates/auth/email directory to keep them separate from the HTML templates. As dis‐\n",
"cussed in Chapter 6, for each email two templates are needed for the plain-text and\n",
"HTML versions of the body. As an example, Example 8-20 shows the plain-text ver‐\n",
"sion of the confirmation email template, and you can find the equivalent HTML ver‐\n",
"sion in the GitHub repository.\n",
"Example 8-20. app/templates/auth/email/confirm.txt: text body of confirmation email\n",
"Dear {{ user.username }},\n",
"Welcome to Flasky!\n",
"To confirm your account please click on the following link:\n",
"{{ url_for('auth.confirm', token=token, _external=True) }}\n",
"Sincerely,\n",
"The Flasky Team\n",
"Note: replies to this email address are not monitored.\n",
"By \n",
"default, \n",
"url_for() \n",
"generates \n",
"relative \n",
"URLs; \n",
"so, \n",
"for \n",
"example,\n",
"url_for('auth.confirm', token='abc') returns the string '/auth/confirm/abc'.\n",
"This, of course, is not a valid URL that can be sent in an email, since it is only the\n",
"path portion of the URL. Relative URLs work fine when they are used within the con‐\n",
"text of a web page because the browser converts them to absolute URLs by adding the\n",
"hostname and port number from the current page, but when sending a URL over\n",
"email there is no such context. The _external=True argument is added to the\n",
"url_for() call to request a fully qualified URL that includes the scheme (http:// or\n",
"https://), hostname, and port.\n",
"The view function that confirms accounts is shown in Example 8-21.\n",
"Account Confirmation \n",
"| \n",
"121\n",
"\n",
"Example 8-21. app/auth/views.py: confirming a user account\n",
"from flask_login import current_user\n",
"@auth.route('/confirm/<token>')\n",
"@login_required\n",
"def confirm(token):\n",
" if current_user.confirmed:\n",
" return redirect(url_for('main.index'))\n",
" if current_user.confirm(token):\n",
" db.session.commit()\n",
" flash('You have confirmed your account. Thanks!')\n",
" else:\n",
" flash('The confirmation link is invalid or has expired.')\n",
" return redirect(url_for('main.index'))\n",
"This route is protected with the login_required decorator from Flask-Login, so that\n",
"when the users click on the link from the confirmation email they are asked to log in\n",
"before they reach this view function.\n",
"The function first checks if the logged-in user is already confirmed, and in that case it\n",
"redirects to the home page, as obviously there is nothing to do. This can prevent\n",
"unnecessary work if a user clicks the confirmation token multiple times by mistake.\n",
"Because the actual token confirmation is done entirely in the User model, all the view\n",
"function needs to do is call the confirm() method and then flash a message accord‐\n",
"ing to the result. When the confirmation succeeds, the User model’s confirmed\n",
"attribute is changed and added to the session and then the database session is com‐\n",
"mitted.\n",
"Each application can decide what unconfirmed users are allowed to do before they\n",
"confirm their accounts. One possibility is to allow unconfirmed users to log in, but\n",
"only show them a page that asks them to confirm their accounts before they can gain\n",
"further access.\n",
"This step can be done using Flask’s before_request hook, which was briefly\n",
"described in Chapter 2. From a blueprint, the before_request hook applies only to\n",
"requests that belong to the blueprint. To install a blueprint hook for all application\n",
"requests, the before_app_request decorator must be used instead. Example 8-22\n",
"shows how this handler is implemented.\n",
"122 \n",
"| \n",
"Chapter 8: User Authentication\n",
"\n",
"Example 8-22. app/auth/views.py: filtering unconfirmed accounts with the\n",
"before_app_request handler\n",
"@auth.before_app_request\n",
"def before_request():\n",
" if current_user.is_authenticated \\\n",
" and not current_user.confirmed \\\n",
" and request.blueprint != 'auth' \\\n",
" and request.endpoint != 'static':\n",
" return redirect(url_for('auth.unconfirmed'))\n",
"@auth.route('/unconfirmed')\n",
"def unconfirmed():\n",
" if current_user.is_anonymous or current_user.confirmed:\n",
" return redirect(url_for('main.index'))\n",
" return render_template('auth/unconfirmed.html')\n",
"The before_app_request handler will intercept a request when three conditions are\n",
"true:\n",
"1. A user is logged in (current_user.is_authenticated is True).\n",
"2. The account for the user is not confirmed.\n",
"3. The requested URL is outside of the authentication blueprint and is not for a\n",
"static file. Access to the authentication routes needs to be granted, as those are the\n",
"routes that will enable the user to confirm the account or perform other account\n",
"management functions.\n",
"If these three conditions are met, then a redirect is issued to a new /auth/unconfirmed\n",
"route that shows a page with information about account confirmation.\n",
"When a before_request or before_app_request callback returns\n",
"a response or a redirect, Flask sends that to the client without\n",
"invoking the view function associated with the request. This effec‐\n",
"tively allows these callbacks to intercept a request when necessary.\n",
"The page that is presented to unconfirmed users (shown in Figure 8-4) just renders a\n",
"template that gives users instructions for how to confirm their accounts and offers a\n",
"link to request a new confirmation email, in case the original email was lost. The\n",
"route that resends the confirmation email is shown in Example 8-23.\n",
"Account Confirmation \n",
"| \n",
"123\n",
"\n",
"Figure 8-4. Unconfirmed account page\n",
"Example 8-23. app/auth/views.py: resending the account confirmation email\n",
"@auth.route('/confirm')\n",
"@login_required\n",
"def resend_confirmation():\n",
" token = current_user.generate_confirmation_token()\n",
" send_email(current_user.email, 'Confirm Your Account',\n",
" 'auth/email/confirm', user=current_user, token=token)\n",
" flash('A new confirmation email has been sent to you by email.')\n",
" return redirect(url_for('main.index'))\n",
"This route repeats what was done in the registration route using current_user, the\n",
"user who is logged in, as the target user. This route is also protected with\n",
"login_required to ensure that when it is accessed, the user that is making the\n",
"request is authenticated.\n",
"If you have cloned the application’s Git repository on GitHub, you\n",
"can run git checkout 8e to check out this version of the applica‐\n",
"tion. This update contains a database migration, so remember to\n",
"run flask db upgrade after you check out the code.\n",
"124 \n",
"| \n",
"Chapter 8: User Authentication\n",
"\n",
"Account Management\n",
"Users who have accounts with the application may need to make changes to their\n",
"accounts from time to time. The following tasks can be added to the authentication\n",
"blueprint using the techniques presented in this chapter:\n",
"Password updates\n",
"Security-conscious users may want to change their passwords periodically. This is\n",
"an easy feature to implement, because as long as the user is logged in, it is safe to\n",
"present a form that asks for the old password and a new password to replace it.\n",
"This feature is implemented as commit 8f in the GitHub repository. As part of\n",
"this change, the “Log Out” link in the navigation bar was refactored into a drop‐\n",
"down that contains the “Change Password” and “Log Out” links.\n",
"Password resets\n",
"To avoid locking users out of the application when they forget their passwords, a\n",
"password reset option can be offered. To implement password resets in a secure\n",
"way, it is necessary to use tokens similar to those used to confirm accounts.\n",
"When a user requests a password reset, an email with a reset token is sent to the\n",
"registered email address. The user then clicks the link in the email and, after the\n",
"token is verified, a form is presented where a new password can be entered. This\n",
"feature is implemented as commit 8g in the GitHub repository.\n",
"Email address changes\n",
"Users can be given the option to change their registered email address, but before\n",
"the new address is accepted it must be verified with a confirmation email. To use\n",
"this feature, the user enters the new email address in a form. To confirm the\n",
"email address, a token is emailed to that address. When the server receives the\n",
"token back, it can update the user object. While the server waits to receive the\n",
"token, it can store the new email address in a new database field reserved for\n",
"pending email addresses, or it can store the address in the token along with the\n",
"id. This feature is implemented as commit 8h in the GitHub repository.\n",
"In the next chapter, the user subsystem of Flasky will be extended through the use of\n",
"user roles.\n",
"Account Management \n",
"| \n",
"125\n",
"\n",
"\n",
"CHAPTER 9\n",
"User Roles\n",
"Not all users of web applications are created equal. In most applications, a small per‐\n",
"centage of users are trusted with extra powers to help keep the application running\n",
"smoothly. Administrators are the best example, but in many cases middle-level power\n",
"users such as content moderators exist as well. To implement this, all users are\n",
"assigned a role.\n",
"There are several ways to implement roles in an application. The appropriate method\n",
"largely depends on how many roles need to be supported and how elaborate they are.\n",
"For example, a simple application may need just two roles, one for regular users and\n",
"one for administrators. In this case, having an is_administrator Boolean field in the\n",
"User model may be all that is necessary. A more complex application may need addi‐\n",
"tional roles with varying levels of power in between regular users and administrators.\n",
"In some applications it may not even make sense to talk about discrete roles, and\n",
"instead giving users a set of individual permissions may be the right approach.\n",
"The user role implementation presented in this chapter is a hybrid between discrete\n",
"roles and permissions. Users are assigned a discrete role, but each role defines what\n",
"actions it allows its users to perform through a list of permissions.\n",
"Database Representation of Roles\n",
"A simple roles table was created in Chapter 5 as a vehicle to demonstrate one-to-\n",
"many relationships. Example 9-1 shows an improved Role model with some addi‐\n",
"tions.\n",
"127\n",
"\n",
"Example 9-1. app/models.py: role database model\n",
"class Role(db.Model):\n",
" __tablename__ = 'roles'\n",
" id = db.Column(db.Integer, primary_key=True)\n",
" name = db.Column(db.String(64), unique=True)\n",
" default = db.Column(db.Boolean, default=False, index=True)\n",
" permissions = db.Column(db.Integer)\n",
" users = db.relationship('User', backref='role', lazy='dynamic')\n",
" def __init__(self, **kwargs):\n",
" super(Role, self).__init__(**kwargs)\n",
" if self.permissions is None:\n",
" self.permissions = 0\n",
"The default field is one of the additions to this model. This field should be set to\n",
"True for only one role and False for all the others. The role marked as default will be\n",
"the one assigned to new users upon registration. Since the application is going to\n",
"search the roles table to find the default one, this column is configured to have an\n",
"index, as that will make searches much faster.\n",
"Another addition to the model is the permissions field, which is an integer value that\n",
"defines the list of permissions for the role in a compact way. Since SQLAlchemy will\n",
"set this field to None by default, a class constructor is added that sets it to 0 if an initial\n",
"value isn’t provided in the constructor arguments.\n",
"The list of tasks for which permissions are needed is obviously application specific.\n",
"For Flasky, the list is shown in Table 9-1.\n",
"Table 9-1. Application permissions\n",
"Task name\n",
"Permission name Permission value\n",
"Follow users\n",
"FOLLOW\n",
"1\n",
"Comment on posts made by others\n",
"COMMENT\n",
"2\n",
"Write articles\n",
"WRITE\n",
"4\n",
"Moderate comments made by others\n",
"MODERATE\n",
"8\n",
"Administration access\n",
"ADMIN\n",
"16\n",
"The benefit of using powers of two for permission values is that it allows permissions\n",
"to be combined, giving each possible combination of permissions a unique value to\n",
"store in the role’s permissions field. For example, for a user role that gives users per‐\n",
"mission to follow other users and comment on posts, the permission value is FOLLOW\n",
"+ COMMENT = 3. This is a very efficient way to store the list of permissions assigned to\n",
"each role.\n",
"128 \n",
"| \n",
"Chapter 9: User Roles\n",
"\n",
"The code representation of Table 9-1 is shown in Example 9-2.\n",
"Example 9-2. app/models.py: permission constants\n",
"class Permission:\n",
" FOLLOW = 1\n",
" COMMENT = 2\n",
" WRITE = 4\n",
" MODERATE = 8\n",
" ADMIN = 16\n",
"With the permission constants in place, a few new methods can be added to the Role\n",
"model to manage permissions. These are shown in Example 9-3.\n",
"Example 9-3. app/models.py: permission management in the Role model\n",
"class Role(db.Model):\n",
" # ...\n",
" def add_permission(self, perm):\n",
" if not self.has_permission(perm):\n",
" self.permissions += perm\n",
" def remove_permission(self, perm):\n",
" if self.has_permission(perm):\n",
" self.permissions -= perm\n",
" def reset_permissions(self):\n",
" self.permissions = 0\n",
" def has_permission(self, perm):\n",
" return self.permissions & perm == perm\n",
"The add_permission(), remove_permission(), and reset_permission() methods\n",
"all use basic arithmetic operations to update the permission list. The\n",
"has_permission() method is the most complex of the set, as it relies on the bitwise\n",
"and operator & to check if a combined permission value includes the given basic per‐\n",
"mission. You can play with these methods in a Python shell:\n",
"(venv) $ flask shell\n",
">>> r = Role(name='User')\n",
">>> r.add_permission(Permission.FOLLOW)\n",
">>> r.add_permission(Permission.WRITE)\n",
">>> r.has_permission(Permission.FOLLOW)\n",
"True\n",
">>> r.has_permission(Permission.ADMIN)\n",
"False\n",
">>> r.reset_permissions()\n",
"Database Representation of Roles \n",
"| \n",
"129\n",
"\n",
">>> r.has_permission(Permission.FOLLOW)\n",
"False\n",
"Table 9-2 shows the list of user roles that will be supported in this application, along\n",
"with the permission combinations that define each of them.\n",
"Table 9-2. User roles\n",
"User role\n",
"Permissions\n",
"Description\n",
"None\n",
"None\n",
"Read-only access to the application. This applies to unknown users who are not\n",
"logged in.\n",
"User\n",
"FOLLOW, COMMENT,\n",
"WRITE\n",
"Basic permissions to write articles and comments and to follow other users.\n",
"This is the default for new users.\n",
"Moderator\n",
"FOLLOW, COMMENT,\n",
"WRITE, MODERATE\n",
"Adds permission to moderate comments made by other users.\n",
"Administrator\n",
"FOLLOW, COMMENT,\n",
"WRITE, MODERATE,\n",
"ADMIN\n",
"Full access, which includes permission to change the roles of other users.\n",
"Adding the roles to the database manually is time consuming and error prone, so\n",
"instead a class method can be added to the Role class for this purpose, as shown in\n",
"Example 9-4. This will make it easy to re-create the correct roles and permissions\n",
"during unit testing and, more importantly, on the production server once the applica‐\n",
"tion is deployed.\n",
"Example 9-4. app/models.py: creating roles in the database\n",
"class Role(db.Model):\n",
" # ...\n",
" @staticmethod\n",
" def insert_roles():\n",
" roles = {\n",
" 'User': [Permission.FOLLOW, Permission.COMMENT, Permission.WRITE],\n",
" 'Moderator': [Permission.FOLLOW, Permission.COMMENT,\n",
" Permission.WRITE, Permission.MODERATE],\n",
" 'Administrator': [Permission.FOLLOW, Permission.COMMENT,\n",
" Permission.WRITE, Permission.MODERATE,\n",
" Permission.ADMIN],\n",
" }\n",
" default_role = 'User'\n",
" for r in roles:\n",
" role = Role.query.filter_by(name=r).first()\n",
" if role is None:\n",
" role = Role(name=r)\n",
" role.reset_permissions()\n",
" for perm in roles[r]:\n",
" role.add_permission(perm)\n",
" role.default = (role.name == default_role)\n",
"130 \n",
"| \n",
"Chapter 9: User Roles\n",
"\n",
" db.session.add(role)\n",
" db.session.commit()\n",
"The insert_roles() function does not directly create new role objects. Instead, it\n",
"tries to find existing roles by name and update those. A new role object is created\n",
"only for roles that aren’t in the database already. This is done so that the role list can\n",
"be updated in the future when changes need to be made. To add a new role or change\n",
"the permission assignments for a role, change the roles dictionary at the top of the\n",
"function and then run the function again. Note that the \"Anonymous\" role does not\n",
"need to be represented in the database, as it is the role that represents users who are\n",
"not known and therefore are not in the database.\n",
"Note also that insert_roles() is a static method, a special type of method that does\n",
"not require an object to be created as it can be invoked directly on the class, for exam‐\n",
"ple, as Role.insert_roles(). Static methods do not take a self argument like\n",
"instance methods.\n",
"Role Assignment\n",
"When users register an account with the application, the correct role should be\n",
"assigned to them. For most users, the role assigned at registration time will be the\n",
"\"User\" role, as that is the role that is marked as a default. The only exception is made\n",
"for the administrator, who needs to be assigned the \"Administrator\" role from the\n",
"start. This user is identified by an email address stored in the FLASKY_ADMIN configu‐\n",
"ration variable, so as soon as that email address appears in a registration request it\n",
"can be given the correct role. Example 9-5 shows how this is done in the User model\n",
"constructor.\n",
"Example 9-5. app/models.py: defining a default role for users\n",
"class User(UserMixin, db.Model):\n",
" # ...\n",
" def __init__(self, **kwargs):\n",
" super(User, self).__init__(**kwargs)\n",
" if self.role is None:\n",
" if self.email == current_app.config['FLASKY_ADMIN']:\n",
" self.role = Role.query.filter_by(name='Administrator').first()\n",
" if self.role is None:\n",
" self.role = Role.query.filter_by(default=True).first()\n",
" # ...\n",
"The User constructor first invokes the constructors of the base classes, and if after\n",
"that the object does not have a role defined, it sets the administrator or default role\n",
"depending on the email address.\n",
"Role Assignment \n",
"| \n",
"131\n",
"\n",
"Role Verification\n",
"To simplify the implementation of roles and permissions, a helper method can be\n",
"added to the User model that checks whether users have a given permission in the\n",
"role they have been assigned. The implementation simply defers to the role methods\n",
"added previously. This is shown in Example 9-6.\n",
"Example 9-6. app/models.py: evaluating whether a user has a given permission\n",
"from flask_login import UserMixin, AnonymousUserMixin\n",
"class User(UserMixin, db.Model):\n",
" # ...\n",
" def can(self, perm):\n",
" return self.role is not None and self.role.has_permission(perm)\n",
" def is_administrator(self):\n",
" return self.can(Permission.ADMIN)\n",
"class AnonymousUser(AnonymousUserMixin):\n",
" def can(self, permissions):\n",
" return False\n",
" def is_administrator(self):\n",
" return False\n",
"login_manager.anonymous_user = AnonymousUser\n",
"The can() method added to the User model returns True if the requested permission\n",
"is present in the role, which means that the user should be allowed to perform the\n",
"requested task. The check for administration permissions is so common that it is also\n",
"implemented as a standalone is_administrator() method.\n",
"For added convenience, a custom AnonymousUser class that implements the can()\n",
"and is_administrator() methods is created as well. This will enable the application\n",
"to freely call current_user.can() and current_user.is_administrator() without\n",
"having to check whether the user is logged in first. Flask-Login is told to use the\n",
"application’s \n",
"custom \n",
"anonymous \n",
"user \n",
"by \n",
"setting \n",
"its \n",
"class \n",
"in \n",
"the\n",
"login_manager.anonymous_user attribute.\n",
"For cases in which an entire view function needs to be made available only to users\n",
"with certain permissions, a custom decorator can be used. Example 9-7 shows the\n",
"implementation of two decorators, one for generic permission checks and one that\n",
"checks specifically for the administrator permission.\n",
"132 \n",
"| \n",
"Chapter 9: User Roles\n",
"\n",
"Example 9-7. app/decorators.py: custom decorators that check user permissions\n",
"from functools import wraps\n",
"from flask import abort\n",
"from flask_login import current_user\n",
"from .models import Permission\n",
"def permission_required(permission):\n",
" def decorator(f):\n",
" @wraps(f)\n",
" def decorated_function(*args, **kwargs):\n",
" if not current_user.can(permission):\n",
" abort(403)\n",
" return f(*args, **kwargs)\n",
" return decorated_function\n",
" return decorator\n",
"def admin_required(f):\n",
" return permission_required(Permission.ADMIN)(f)\n",
"These decorators are built with the help of the functools package from the Python\n",
"standard library and return a 403 response, the “Forbidden” HTTP status code, when\n",
"the current user does not have the requested permission. In Chapter 3, custom error\n",
"pages were created for errors 404 and 500, so now a page for the 403 error is added in\n",
"a similar way.\n",
"The following are two examples that demonstrate the usage of these decorators:\n",
"from .decorators import admin_required, permission_required\n",
"@main.route('/admin')\n",
"@login_required\n",
"@admin_required\n",
"def for_admins_only():\n",
" return \"For administrators!\"\n",
"@main.route('/moderate')\n",
"@login_required\n",
"@permission_required(Permission.MODERATE)\n",
"def for_moderators_only():\n",
" return \"For comment moderators!\"\n",
"As a rule of thumb, the route decorator from Flask should be given first when using\n",
"multiple decorators in a view function. The remaining decorators should be given in\n",
"the order in which they need to evaluate when the view function is invoked. In these\n",
"two cases, the user authenticated state needs to be checked first, since the user needs\n",
"to be redirected to the login prompt if found to not be authenticated.\n",
"Permissions may also need to be checked from templates, so the Permission class\n",
"with all its constants needs to be accessible to them. To avoid having to add a tem‐\n",
"Role Verification \n",
"| \n",
"133\n",
"\n",
"plate argument in every render_template() call, a context processor can be used.\n",
"Context processors make variables available to all templates during rendering. This\n",
"change is shown in Example 9-8.\n",
"Example 9-8. app/main/__init__.py: adding the Permission class to the template context\n",
"@main.app_context_processor\n",
"def inject_permissions():\n",
" return dict(Permission=Permission)\n",
"The new roles and permissions can be exercised in unit tests. Example 9-9 shows two\n",
"of the tests. The source code on GitHub includes one for each role.\n",
"Example 9-9. tests/test_user_model.py: unit tests for roles and permissions\n",
"class UserModelTestCase(unittest.TestCase):\n",
" # ...\n",
" def test_user_role(self):\n",
" u = User(email='john@example.com', password='cat')\n",
" self.assertTrue(u.can(Permission.FOLLOW))\n",
" self.assertTrue(u.can(Permission.COMMENT))\n",
" self.assertTrue(u.can(Permission.WRITE))\n",
" self.assertFalse(u.can(Permission.MODERATE))\n",
" self.assertFalse(u.can(Permission.ADMIN))\n",
" def test_anonymous_user(self):\n",
" u = AnonymousUser()\n",
" self.assertFalse(u.can(Permission.FOLLOW))\n",
" self.assertFalse(u.can(Permission.COMMENT))\n",
" self.assertFalse(u.can(Permission.WRITE))\n",
" self.assertFalse(u.can(Permission.MODERATE))\n",
" self.assertFalse(u.can(Permission.ADMIN))\n",
"If you have cloned the application’s Git repository on GitHub, you\n",
"can run git checkout 9a to check out this version of the applica‐\n",
"tion. This update contains a database migration, so remember to\n",
"run flask db upgrade after you check out the code.\n",
"Before you move on to the next chapter, add the new roles to your development data‐\n",
"base in a shell session:\n",
"(venv) $ flask shell\n",
">>> Role.insert_roles()\n",
">>> Role.query.all()\n",
"[<Role 'Administrator'>, <Role 'User'>, <Role 'Moderator'>]\n",
"134 \n",
"| \n",
"Chapter 9: User Roles\n",
"\n",
"It is also a good idea to update the user list so that all the user accounts that were\n",
"created before roles and permissions existed have a role assigned. You can run the fol‐\n",
"lowing code in a Python shell to perform this update:\n",
"(venv) $ flask shell\n",
">>> admin_role = Role.query.filter_by(name='Administrator').first()\n",
">>> default_role = Role.query.filter_by(default=True).first()\n",
">>> for u in User.query.all():\n",
"... if u.role is None:\n",
"... if u.email == app.config['FLASKY_ADMIN']:\n",
"... u.role = admin_role\n",
"... else:\n",
"... u.role = default_role\n",
"...\n",
">>> db.session.commit()\n",
"The user system is now fairly complete. The next chapter will make use of it to create\n",
"user profile pages.\n",
"Role Verification \n",
"| \n",
"135\n",
"\n",
"\n",
"CHAPTER 10\n",
"User Profiles\n",
"In this chapter, user profiles for Flasky are implemented. All socially aware sites give\n",
"their users a profile page, where a summary of the user’s participation in the website\n",
"is presented. Users can advertise their presence on the website by sharing the URL to\n",
"their profile page, so it is important that the URLs be short and easy to remember.\n",
"Profile Information\n",
"To make user profile pages more interesting, some additional information about\n",
"users can be stored in the database. In Example 10-1 the User model is extended with\n",
"several new fields.\n",
"Example 10-1. app/models.py: user information fields\n",
"class User(UserMixin, db.Model):\n",
" # ...\n",
" name = db.Column(db.String(64))\n",
" location = db.Column(db.String(64))\n",
" about_me = db.Column(db.Text())\n",
" member_since = db.Column(db.DateTime(), default=datetime.utcnow)\n",
" last_seen = db.Column(db.DateTime(), default=datetime.utcnow)\n",
"The new fields store the user’s real name, location, self-written bio, date of registra‐\n",
"tion, and date of last visit. The about_me field is assigned the type db.Text(). The\n",
"difference between db.String and db.Text is that db.Text is a variable-length field\n",
"and as such does not need a maximum length.\n",
"The two timestamps are given a default value of the current time. Note that the\n",
"datetime.utcnow is missing the () at the end. This is because the default argument\n",
"in db.Column() can take a function as a value. Each time a default value needs to be\n",
"137\n",
"\n",
"generated, SQLAlchemy invokes the function to produce it. This default value is all\n",
"that is needed to manage the member_since field.\n",
"The last_seen field is also initialized to the current time upon creation, but it needs\n",
"to be refreshed each time the user accesses the site. A method in the User class can be\n",
"added to perform this update. This is shown in Example 10-2.\n",
"Example 10-2. app/models.py: refreshing a user’s last visit time\n",
"class User(UserMixin, db.Model):\n",
" # ...\n",
" def ping(self):\n",
" self.last_seen = datetime.utcnow()\n",
" db.session.add(self)\n",
" db.session.commit()\n",
"To keep the last visit date for all users updated, the ping() method must be called\n",
"each time a request from a user is received. Because the before_app_request handler \n",
"in the auth blueprint runs before every request, it can do this easily, as shown in\n",
"Example 10-3.\n",
"Example 10-3. app/auth/views.py: pinging the logged-in user\n",
"@auth.before_app_request\n",
"def before_request():\n",
" if current_user.is_authenticated:\n",
" current_user.ping()\n",
" if not current_user.confirmed \\\n",
" and request.endpoint \\\n",
" and request.blueprint != 'auth' \\\n",
" and request.endpoint != 'static':\n",
" return redirect(url_for('auth.unconfirmed'))\n",
"User Profile Page\n",
"Creating a profile page for each user does not present any new challenges.\n",
"Example 10-4 shows the route definition.\n",
"Example 10-4. app/main/views.py: profile page route\n",
"@main.route('/user/<username>')\n",
"def user(username):\n",
" user = User.query.filter_by(username=username).first_or_404()\n",
" return render_template('user.html', user=user)\n",
"138 \n",
"| \n",
"Chapter 10: User Profiles\n",
"\n",
"This route is added in the main blueprint. For a user named john, the profile page will\n",
"be at http://localhost:5000/user/john. The username given in the URL is searched in\n",
"the database and, if found, the user.html template is rendered with it as the argument.\n",
"An invalid username sent into this route will cause a 404 error to be returned. With\n",
"Flask-SQLAlchemy, the search and error cases can be nicely combined in a single\n",
"statement using the first_or_404() method of the query object. The user.html tem‐\n",
"plate is going to need to present user information, so it receives the user object as an\n",
"argument. An initial version of this template is shown in Example 10-5.\n",
"Example 10-5. app/templates/user.html: user profile template\n",
"{% extends \"base.html\" %}\n",
"{% block title %}Flasky - {{ user.username }}{% endblock %}\n",
"{% block page_content %}\n",
"<div class=\"page-header\">\n",
" <h1>{{ user.username }}</h1>\n",
" {% if user.name or user.location %}\n",
" <p>\n",
" {% if user.name %}{{ user.name }}{% endif %}\n",
" {% if user.location %}\n",
" From <a href=\"http://maps.google.com/?q={{ user.location }}\">\n",
" {{ user.location }}\n",
" </a>\n",
" {% endif %}\n",
" </p>\n",
" {% endif %}\n",
" {% if current_user.is_administrator() %}\n",
" <p><a href=\"mailto:{{ user.email }}\">{{ user.email }}</a></p>\n",
" {% endif %}\n",
" {% if user.about_me %}<p>{{ user.about_me }}</p>{% endif %}\n",
" <p>\n",
" Member since {{ moment(user.member_since).format('L') }}.\n",
" Last seen {{ moment(user.last_seen).fromNow() }}.\n",
" </p>\n",
"</div>\n",
"{% endblock %}\n",
"This template has a few interesting implementation details:\n",
"• The name and location fields are rendered inside a single <p> element. A Jinja2\n",
"conditional ensures that the <p> element is created only when at least one of the\n",
"fields is defined.\n",
"• The user location field is rendered as a link to a Google Maps query, so that\n",
"clicking on it opens a map centered on the location.\n",
"User Profile Page \n",
"| \n",
"139\n",
"\n",
"• If the logged-in user is an administrator, then the email address of the user is\n",
"shown, rendered as a mailto link. This is useful when an administrator is viewing\n",
"the profile page of another user and needs to contact the user.\n",
"• The two timestamps for the user are rendered to the page using Flask-Moment,\n",
"as shown in Chapter 3.\n",
"As most users will want easy access to their own profile page, a link to it can be added\n",
"to the navigation bar. The relevant changes to the base.html template are shown in\n",
"Example 10-6.\n",
"Example 10-6. app/templates/base.html: add link to profile page in the navigation bar\n",
"{% if current_user.is_authenticated %}\n",
"<li>\n",
" <a href=\"{{ url_for('main.user', username=current_user.username) }}\">\n",
" Profile\n",
" </a>\n",
"</li>\n",
"{% endif %}\n",
"Using a conditional for the profile page link is necessary because the navigation bar is\n",
"also rendered for unauthenticated users, in which case the profile link is skipped.\n",
"Figure 10-1 shows how the profile page looks in the browser. The new profile link in\n",
"the navigation bar is also shown.\n",
"Figure 10-1. User profile page\n",
"140 \n",
"| \n",
"Chapter 10: User Profiles\n",
"\n",
"If you have cloned the application’s Git repository on GitHub, you\n",
"can run git checkout 10a to check out this version of the applica‐\n",
"tion. This update contains a database migration, so remember to\n",
"run flask db upgrade after you check out the code.\n",
"Profile Editor\n",
"There are two different use cases related to editing of user profiles. The most obvious\n",
"is that users need to have access to a page where they can enter information about\n",
"themselves to present in their profile pages. A less obvious but also important\n",
"requirement is to let administrators edit the profiles of other users—not only their\n",
"personal information items but also other fields in the User model to which users\n",
"have no direct access, such as the user role. Because the two profile editing require‐\n",
"ments are substantially different, two different forms will be created.\n",
"User-Level Profile Editor\n",
"The profile editing form for regular users is shown in Example 10-7.\n",
"Example 10-7. app/main/forms.py: edit profile form\n",
"class EditProfileForm(FlaskForm):\n",
" name = StringField('Real name', validators=[Length(0, 64)])\n",
" location = StringField('Location', validators=[Length(0, 64)])\n",
" about_me = TextAreaField('About me')\n",
" submit = SubmitField('Submit')\n",
"Note that as all the fields in this form are optional, the length validator allows a length\n",
"of zero as a minimum. The route definition that uses this form is shown in\n",
"Example 10-8.\n",
"Example 10-8. app/main/views.py: edit profile route\n",
"@main.route('/edit-profile', methods=['GET', 'POST'])\n",
"@login_required\n",
"def edit_profile():\n",
" form = EditProfileForm()\n",
" if form.validate_on_submit():\n",
" current_user.name = form.name.data\n",
" current_user.location = form.location.data\n",
" current_user.about_me = form.about_me.data\n",
" db.session.add(current_user._get_current_object())\n",
" db.session.commit()\n",
" flash('Your profile has been updated.')\n",
" return redirect(url_for('.user', username=current_user.username))\n",
" form.name.data = current_user.name\n",
"Profile Editor \n",
"| \n",
"141\n",
"\n",
" form.location.data = current_user.location\n",
" form.about_me.data = current_user.about_me\n",
" return render_template('edit_profile.html', form=form)\n",
"As in previous forms, the data associated with each form field is available at\n",
"form.<field-name>.data. This is useful not only to obtain values submitted by the\n",
"user, but also to provide initial values that are shown to the user for editing. When\n",
"form.validate_on_submit() is False, the three fields in this form are initialized\n",
"from the corresponding fields in current_user. Then, when the form is submitted,\n",
"the data attributes of the form fields contain the updated values, so these are moved\n",
"back into the fields of the user object before the object is saved back to the database.\n",
"Figure 10-2 shows the profile editing page.\n",
"Figure 10-2. Profile editor\n",
"To make it easy for users to reach this page, a direct link can be added in the profile\n",
"page, as shown in Example 10-9.\n",
"142 \n",
"| \n",
"Chapter 10: User Profiles\n",
"\n",
"Example 10-9. app/templates/user.html: edit profile link\n",
"{% if user == current_user %}\n",
"<a class=\"btn btn-default\" href=\"{{ url_for('.edit_profile') }}\">\n",
" Edit Profile\n",
"</a>\n",
"{% endif %}\n",
"The conditional that encloses the link will make the link appear only when users are\n",
"viewing their own profiles.\n",
"Administrator-Level Profile Editor\n",
"The profile editing form for administrators is more complex than the one for regular\n",
"users. In addition to the three profile information fields, this form allows administra‐\n",
"tors to edit a user’s email, username, confirmed status, and role. The form is shown in\n",
"Example 10-10.\n",
"Example 10-10. app/main/forms.py: profile editing form for administrators\n",
"class EditProfileAdminForm(FlaskForm):\n",
" email = StringField('Email', validators=[DataRequired(), Length(1, 64),\n",
" Email()])\n",
" username = StringField('Username', validators=[\n",
" DataRequired(), Length(1, 64),\n",
" Regexp('^[A-Za-z][A-Za-z0-9_.]*$', 0,\n",
" 'Usernames must have only letters, numbers, dots or '\n",
" 'underscores')])\n",
" confirmed = BooleanField('Confirmed')\n",
" role = SelectField('Role', coerce=int)\n",
" name = StringField('Real name', validators=[Length(0, 64)])\n",
" location = StringField('Location', validators=[Length(0, 64)])\n",
" about_me = TextAreaField('About me')\n",
" submit = SubmitField('Submit')\n",
" def __init__(self, user, *args, **kwargs):\n",
" super(EditProfileAdminForm, self).__init__(*args, **kwargs)\n",
" self.role.choices = [(role.id, role.name)\n",
" for role in Role.query.order_by(Role.name).all()]\n",
" self.user = user\n",
" def validate_email(self, field):\n",
" if field.data != self.user.email and \\\n",
" User.query.filter_by(email=field.data).first():\n",
" raise ValidationError('Email already registered.')\n",
" def validate_username(self, field):\n",
" if field.data != self.user.username and \\\n",
"Profile Editor \n",
"| \n",
"143\n",
"\n",
" User.query.filter_by(username=field.data).first():\n",
" raise ValidationError('Username already in use.')\n",
"The SelectField is WTForm’s wrapper for the <select> HTML form control, which\n",
"implements a drop-down list, used in this form to select a user role. An instance of\n",
"SelectField must have the items set in its choices attribute. They must be given as a\n",
"list of tuples, with each tuple consisting of two values: an identifier for the item and\n",
"the text to show in the control as a string. The choices list is set in the form’s con‐\n",
"structor, with values obtained from the Role model with a query that sorts all the\n",
"roles alphabetically by name. The identifier for each tuple is set to the id of each role,\n",
"and since these are integers, a coerce=int argument is added to the SelectField\n",
"constructor so that the field values are stored as integers instead of the default, which\n",
"is strings.\n",
"The email and username fields are constructed in the same way as in the authentica‐\n",
"tion forms, but their validation requires some careful handling. The validation condi‐\n",
"tion used for both these fields must first check whether a change to the field was\n",
"made, and only when there is a change should it ensure that the new value does not\n",
"duplicate another user’s. When these fields are not changed, then validation should\n",
"pass. To implement this logic, the form’s constructor receives the user object as an\n",
"argument and saves it as a member variable, which is later used in the custom valida‐\n",
"tion methods.\n",
"The route definition for the administrator’s profile editor is shown in Example 10-11.\n",
"Example 10-11. app/main/views.py: edit profile route for administrators\n",
"from ..decorators import admin_required\n",
"@main.route('/edit-profile/<int:id>', methods=['GET', 'POST'])\n",
"@login_required\n",
"@admin_required\n",
"def edit_profile_admin(id):\n",
" user = User.query.get_or_404(id)\n",
" form = EditProfileAdminForm(user=user)\n",
" if form.validate_on_submit():\n",
" user.email = form.email.data\n",
" user.username = form.username.data\n",
" user.confirmed = form.confirmed.data\n",
" user.role = Role.query.get(form.role.data)\n",
" user.name = form.name.data\n",
" user.location = form.location.data\n",
" user.about_me = form.about_me.data\n",
" db.session.add(user)\n",
" db.session.commit()\n",
" flash('The profile has been updated.')\n",
" return redirect(url_for('.user', username=user.username))\n",
" form.email.data = user.email\n",
"144 \n",
"| \n",
"Chapter 10: User Profiles\n",
"\n",
" form.username.data = user.username\n",
" form.confirmed.data = user.confirmed\n",
" form.role.data = user.role_id\n",
" form.name.data = user.name\n",
" form.location.data = user.location\n",
" form.about_me.data = user.about_me\n",
" return render_template('edit_profile.html', form=form, user=user)\n",
"This route has largely the same structure as the simpler one for regular users, but it\n",
"includes the admin_required decorator created in Chapter 9, which will automati‐\n",
"cally return a 403 error for any users who are not administrators that try to use this\n",
"route.\n",
"The user id is given as a dynamic argument in the URL, so Flask-SQLAlchemy’s\n",
"get_or_404() convenience function can be used, knowing that if the id is invalid the\n",
"request will return a code 404 error. The SelectField used for the user role also\n",
"deserves to be studied. When setting the initial value for the field, the role_id is\n",
"assigned to field.role.data because the list of tuples set in the choices attribute\n",
"uses the numeric identifiers to reference each option. When the form is submitted,\n",
"the id is extracted from the field’s data attribute and used in a query to load the\n",
"selected role object by its id once again. The coerce=int argument used in the\n",
"SelectField declaration in the form ensures that the data attribute of this field is\n",
"always converted to an integer.\n",
"To link to this page, another button is added in the user profile page, as shown in\n",
"Example 10-12.\n",
"Example 10-12. app/templates/user.html: profile editing link for administrators\n",
"{% if current_user.is_administrator() %}\n",
"<a class=\"btn btn-danger\"\n",
" href=\"{{ url_for('.edit_profile_admin', id=user.id) }}\">\n",
" Edit Profile [Admin]\n",
"</a>\n",
"{% endif %}\n",
"This button is rendered with a different Bootstrap style to call attention to it. The\n",
"conditional that wraps it makes the button appear in profile pages only if the logged-\n",
"in user has the administrator role.\n",
"If you have cloned the application’s Git repository on GitHub, you\n",
"can run git checkout 10b to check out this version of the applica‐\n",
"tion.\n",
"Profile Editor \n",
"| \n",
"145\n",
"\n",
"User Avatars\n",
"The look of the profile pages can be improved by showing avatar pictures of users. In\n",
"this section, you will learn how to add user avatars provided by Gravatar, the leading\n",
"avatar service. Gravatar associates avatar images with email addresses. Users create an\n",
"account at https://gravatar.com and then upload their images. The service exposes the\n",
"user’s avatar through a specially crafted URL that includes the MD5 hash of the user’s\n",
"email address, which can be calculated as follows:\n",
"(venv) $ python\n",
">>> import hashlib\n",
">>> hashlib.md5('john@example.com'.encode('utf-8')).hexdigest()\n",
"'d4c74594d841139328695756648b6bd6'\n",
"The avatar URLs are then generated by appending the MD5 hash to the https://\n",
"secure.gravatar.com/avatar/ URL. For example, you can type https://secure.grava‐\n",
"tar.com/avatar/d4c74594d841139328695756648b6bd6 in your browser’s address bar\n",
"to get the avatar image for the email address john@example.com, or a default avatar\n",
"image if that email address does not have an avatar registered. After you build the\n",
"basic avatar URL, a few query string arguments can be used to configure the charac‐\n",
"teristics of the avatar image, as described in Table 10-1.\n",
"Table 10-1. Gravatar query string arguments\n",
"Argument\n",
"name\n",
"Description\n",
"s\n",
"Image size, in pixels.\n",
"r\n",
"Image rating. Options are \"g\", \"pg\", \"r\", and \"x\".\n",
"d\n",
"The default image generator for users who have no avatars registered with the Gravatar service. Options\n",
"are \"404\" to return a 404 error, a URL that points to a default image, or one of the following image\n",
"generators: \"mm\", \"identicon\", \"monsterid\", \"wavatar\", \"retro\", or \"blank\".\n",
"fd\n",
"Force the use of default avatars.\n",
"For example, adding ?d=identicon to the avatar URL for john@example.com will gen‐\n",
"erate a different default avatar that is based on geometric designs. All these options to\n",
"generate avatar URLs can be added to the User model. The implementation is shown\n",
"in Example 10-13.\n",
"Example 10-13. app/models.py: gravatar URL generation\n",
"import hashlib\n",
"from flask import request\n",
"class User(UserMixin, db.Model):\n",
" # ...\n",
" def gravatar(self, size=100, default='identicon', rating='g'):\n",
"146 \n",
"| \n",
"Chapter 10: User Profiles\n",
"\n",
" url = 'https://secure.gravatar.com/avatar'\n",
" hash = hashlib.md5(self.email.lower().encode('utf-8')).hexdigest()\n",
" return '{url}/{hash}?s={size}&d={default}&r={rating}'.format(\n",
" url=url, hash=hash, size=size, default=default, rating=rating)\n",
"The avatar URL is generated from the base URL, the MD5 hash of the user’s email\n",
"address, and the arguments, all of which have default values. Note that one of the\n",
"requirements of the Gravatar service is that the email address from which the MD5\n",
"hash is obtained is normalized to contain only lowercase alphabetical characters, so\n",
"that conversion is also added to this method. With this implementation it is easy to\n",
"generate avatar URLs in the Python shell:\n",
"(venv) $ flask shell\n",
">>> u = User(email='john@example.com')\n",
">>> u.gravatar()\n",
"'https://secure.gravatar.com/avatar/d4c74594d841139328695756648b6bd6?s=100&d=\n",
"identicon&r=g'\n",
">>> u.gravatar(size=256)\n",
"'https://secure.gravatar.com/avatar/d4c74594d841139328695756648b6bd6?s=256&d=\n",
"identicon&r=g'\n",
"The gravatar() method can also be invoked from Jinja2 templates. Example 10-14\n",
"shows how a 256-pixel avatar can be added to the profile page.\n",
"Example 10-14. app/templates/user.html: adding an avatar to the profile page\n",
"...\n",
"<img class=\"img-rounded profile-thumbnail\" src=\"{{ user.gravatar(size=256) }}\">\n",
"<div class=\"profile-header\">\n",
" ...\n",
"</div>\n",
"...\n",
"The profile-thumbnail CSS class helps with the positioning of the image on the\n",
"page. The <div> element that follows the image encapsulates the profile information\n",
"and uses the profile-header CSS class to improve the formatting. You can see the\n",
"definition of the CSS class in the GitHub repository for the application.\n",
"Using a similar approach, the base template adds a small thumbnail image of the\n",
"logged-in user in the navigation bar. To better format the avatar pictures in the page,\n",
"custom CSS classes are used. You can find these in the source code repository in a\n",
"styles.css file added to the application’s static file folder and referenced from the\n",
"base.html template. Figure 10-3 shows the user profile page with avatar.\n",
"User Avatars \n",
"| \n",
"147\n",
"\n",
"Figure 10-3. User profile page with avatar\n",
"If you have cloned the application’s Git repository on GitHub, you\n",
"can run git checkout 10c to check out this version of the applica‐\n",
"tion.\n",
"The generation of avatars requires an MD5 hash to be generated, which is a CPU-\n",
"intensive operation. If a large number of avatars need to be generated for a page, then\n",
"the computational work can add up and become significant. Since the MD5 hash for\n",
"a user will remain constant for as long as the email address stays the same, it can be\n",
"cached in the User model. Example 10-15 shows the changes to the User model to\n",
"store the MD5 hashes in the database.\n",
"Example 10-15. app/models.py: gravatar URL generation with caching of MD5 hashes\n",
"class User(UserMixin, db.Model):\n",
" # ...\n",
" avatar_hash = db.Column(db.String(32))\n",
" def __init__(self, **kwargs):\n",
" # ...\n",
" if self.email is not None and self.avatar_hash is None:\n",
"148 \n",
"| \n",
"Chapter 10: User Profiles\n",
"\n",
" self.avatar_hash = self.gravatar_hash()\n",
" def change_email(self, token):\n",
" # ...\n",
" self.email = new_email\n",
" self.avatar_hash = self.gravatar_hash()\n",
" db.session.add(self)\n",
" return True\n",
" def gravatar_hash(self):\n",
" return hashlib.md5(self.email.lower().encode('utf-8')).hexdigest()\n",
" def gravatar(self, size=100, default='identicon', rating='g'):\n",
" if request.is_secure:\n",
" url = 'https://secure.gravatar.com/avatar'\n",
" else:\n",
" url = 'http://www.gravatar.com/avatar'\n",
" hash = self.avatar_hash or self.gravatar_hash()\n",
" return '{url}/{hash}?s={size}&d={default}&r={rating}'.format(\n",
" url=url, hash=hash, size=size, default=default, rating=rating)\n",
"To avoid duplicating the logic to compute the gravatar hash, a new method,\n",
"gravatar_hash(), is added that performs this task. During model initialization, the\n",
"hash is stored in the new avatar_hash model column. If the user updates the email\n",
"address, then the hash is recalculated. The gravatar() method uses the stored hash if\n",
"available, and if not, it generates a new hash as before.\n",
"If you have cloned the application’s Git repository on GitHub, you\n",
"can run git checkout 10d to check out this version of the applica‐\n",
"tion. This update contains a database migration, so remember to\n",
"run flask db upgrade after you check out the code.\n",
"In the next chapter, the blogging engine that powers this application will be created.\n",
"User Avatars \n",
"| \n",
"149\n",
"\n",
"\n",
"CHAPTER 11\n",
"Blog Posts\n",
"This chapter is dedicated to the implementation of Flasky’s main feature, which is to\n",
"allow users to read and write blog posts. Here you will learn a few new techniques for\n",
"reuse of templates, pagination of long lists of items, and working with rich text.\n",
"Blog Post Submission and Display\n",
"To support blog posts, a new database model that represents them is necessary. This\n",
"model is shown in Example 11-1.\n",
"Example 11-1. app/models.py: Post model\n",
"class Post(db.Model):\n",
" __tablename__ = 'posts'\n",
" id = db.Column(db.Integer, primary_key=True)\n",
" body = db.Column(db.Text)\n",
" timestamp = db.Column(db.DateTime, index=True, default=datetime.utcnow)\n",
" author_id = db.Column(db.Integer, db.ForeignKey('users.id'))\n",
"class User(UserMixin, db.Model):\n",
" # ...\n",
" posts = db.relationship('Post', backref='author', lazy='dynamic')\n",
"A blog post is represented by a body, a timestamp, and a one-to-many relationship\n",
"from the User model. The body field is defined with type db.Text so that there is no\n",
"limitation on the length.\n",
"The form that will be shown in the main page of the application lets users write a blog\n",
"post. This form is very simple; it contains just a text area where the blog post can be\n",
"typed and a submit button. The form definition is shown in Example 11-2.\n",
"151\n",
"\n",
"Example 11-2. app/main/forms.py: blog post form\n",
"class PostForm(FlaskForm):\n",
" body = TextAreaField(\"What's on your mind?\", validators=[DataRequired()])\n",
" submit = SubmitField('Submit')\n",
"The index() view function handles the form and passes the list of old blog posts to\n",
"the template, as shown in Example 11-3.\n",
"Example 11-3. app/main/views.py: home page route with a blog post\n",
"@main.route('/', methods=['GET', 'POST'])\n",
"def index():\n",
" form = PostForm()\n",
" if current_user.can(Permission.WRITE_ARTICLES) and form.validate_on_submit():\n",
" post = Post(body=form.body.data,\n",
" author=current_user._get_current_object())\n",
" db.session.add(post)\n",
" db.session.commit()\n",
" return redirect(url_for('.index'))\n",
" posts = Post.query.order_by(Post.timestamp.desc()).all()\n",
" return render_template('index.html', form=form, posts=posts)\n",
"This view function passes the form and the complete list of blog posts to the template.\n",
"The list of posts is ordered by timestamp, in descending order. The blog post form is\n",
"handled in the usual manner, with the creation of a new Post instance when a valid\n",
"submission is received. The current user’s permission to write articles is checked\n",
"before allowing the new post.\n",
"Note how the author attribute of the new post object is set to the expression\n",
"current_user._get_current_object(). The current_user variable from Flask-\n",
"Login, like all context variables, is implemented as a thread-local proxy object. This\n",
"object behaves like a user object but is really a thin wrapper that contains the actual\n",
"user object inside. The database needs a real user object, which is obtained by calling\n",
"_get_current_object() on the proxy object.\n",
"The form is rendered below the greeting in the index.html template, followed by the\n",
"blog posts. The list of blog posts is a first attempt to create a blog post timeline, with\n",
"all the blog posts in the database listed in chronological order from newest to oldest.\n",
"The changes to the template are shown in Example 11-4.\n",
"152 \n",
"| \n",
"Chapter 11: Blog Posts\n",
"\n",
"Example 11-4. app/templates/index.html: home page template with blog posts\n",
"{% extends \"base.html\" %}\n",
"{% import \"bootstrap/wtf.html\" as wtf %}\n",
"...\n",
"<div>\n",
" {% if current_user.can(Permission.WRITE_ARTICLES) %}\n",
" {{ wtf.quick_form(form) }}\n",
" {% endif %}\n",
"</div>\n",
"<ul class=\"posts\">\n",
" {% for post in posts %}\n",
" <li class=\"post\">\n",
" <div class=\"profile-thumbnail\">\n",
" <a href=\"{{ url_for('.user', username=post.author.username) }}\">\n",
" <img class=\"img-rounded profile-thumbnail\"\n",
" src=\"{{ post.author.gravatar(size=40) }}\">\n",
" </a>\n",
" </div>\n",
" <div class=\"post-date\">{{ moment(post.timestamp).fromNow() }}</div>\n",
" <div class=\"post-author\">\n",
" <a href=\"{{ url_for('.user', username=post.author.username) }}\">\n",
" {{ post.author.username }}\n",
" </a>\n",
" </div>\n",
" <div class=\"post-body\">{{ post.body }}</div>\n",
" </li>\n",
" {% endfor %}\n",
"</ul>\n",
"...\n",
"Note that the User.can() method is used to skip the blog post form for users who do\n",
"not have the WRITE permission in their role. The blog post list is implemented as an\n",
"HTML unordered list, with CSS classes giving it a nicer formatting. A small avatar of\n",
"the author is rendered on the left side, and both the avatar and the author’s username\n",
"are rendered as links to the user’s profile page. The CSS styles used are stored in the\n",
"styles.css file located in the application’s static directory. You can review this file in the\n",
"GitHub repository. Figure 11-1 shows the home page with submission form and blog\n",
"post list.\n",
"If you have cloned the application’s Git repository on GitHub, you\n",
"can run git checkout 11a to check out this version of the applica‐\n",
"tion. This update contains a database migration, so remember to\n",
"run flask db upgrade after you check out the code.\n",
"Blog Post Submission and Display \n",
"| \n",
"153\n",
"\n",
"Figure 11-1. Home page with blog submission form and blog post list\n",
"Blog Posts on Profile Pages\n",
"The user profile page can be improved by showing a list of blog posts authored by the\n",
"user. Example 11-5 shows the changes to the view function to obtain the post list.\n",
"Example 11-5. app/main/views.py: profile page route with blog posts\n",
"@main.route('/user/<username>')\n",
"def user(username):\n",
" user = User.query.filter_by(username=username).first()\n",
" if user is None:\n",
" abort(404)\n",
" posts = user.posts.order_by(Post.timestamp.desc()).all()\n",
" return render_template('user.html', user=user, posts=posts)\n",
"The list of blog posts for a user is obtained from the User.posts relationship. This\n",
"works like a query object, so filters such as order_by() can be used on it like in a\n",
"regular query object.\n",
"154 \n",
"| \n",
"Chapter 11: Blog Posts\n",
"\n",
"The user.html template needs to have the same <ul> HTML tree that renders a list of\n",
"blog posts in index.html, but having to maintain two identical copies of a piece of\n",
"HTML code is not ideal. For cases like this, Jinja2’s include directive is very useful.\n",
"The snippet of HTML that generates the post list can be moved to a separate file that\n",
"both index.html and user.html can include. Example 11-6 shows how this include\n",
"looks in user.html.\n",
"Example 11-6. app/templates/user.html: profile page template with blog posts\n",
"...\n",
"<h3>Posts by {{ user.username }}</h3>\n",
"{% include '_posts.html' %}\n",
"...\n",
"To complete this reorganization, the <ul> tree from index.html is moved to the new\n",
"template _posts.html, and replaced with another include directive like the one just\n",
"shown. Note that the use of an underscore prefix in the _posts.html template name is\n",
"not a requirement; this is merely a convention to distinguish full and partial tem‐\n",
"plates.\n",
"If you have cloned the application’s Git repository on GitHub, you\n",
"can run git checkout 11b to check out this version of the applica‐\n",
"tion.\n",
"Paginating Long Blog Post Lists\n",
"As the site grows and the number of blog posts increases, it will become slow and\n",
"impractical to show the complete list of posts on the home and profile pages. Big\n",
"pages take longer to generate, download, and render in the web browser, so the qual‐\n",
"ity of the user experience decreases as the pages get larger. The solution is to paginate\n",
"the data and render it in chunks.\n",
"Creating Fake Blog Post Data\n",
"To be able to work with multiple pages of blog posts, it is necessary to have a test\n",
"database with a large volume of data. Manually adding new database entries is time\n",
"consuming and tedious; an automated solution is more appropriate. There are several\n",
"Python packages that can be used to generate fake information. A fairly complete one\n",
"is Faker, which is installed with pip:\n",
"(venv) $ pip install faker\n",
"Paginating Long Blog Post Lists \n",
"| \n",
"155\n",
"\n",
"The Faker package is not, strictly speaking, a dependency of the application, because\n",
"it is needed only during development. To separate the production dependencies from\n",
"the development dependencies, the requirements.txt file can be replaced with a\n",
"requirements subdirectory that stores different sets of dependencies. Inside this new\n",
"subdirectory, a dev.txt file can list the dependencies that are necessary for develop‐\n",
"ment and a prod.txt file can list the dependencies that are needed in production. As\n",
"there are a large number of dependencies that will be in both lists, a common.txt file is\n",
"added for those, and then the dev.txt and prod.txt lists use the -r prefix to include it.\n",
"Example 11-7 shows the dev.txt file.\n",
"Example 11-7. requirements/dev.txt: development requirements file\n",
"-r common.txt\n",
"faker==0.7.18\n",
"Example 11-8 shows a new module added to the application that contains two func‐\n",
"tions that generate fake users and posts.\n",
"Example 11-8. app/fake.py: generating fake users and blog posts\n",
"from random import randint\n",
"from sqlalchemy.exc import IntegrityError\n",
"from faker import Faker\n",
"from . import db\n",
"from .models import User, Post\n",
"def users(count=100):\n",
" fake = Faker()\n",
" i = 0\n",
" while i < count:\n",
" u = User(email=fake.email(),\n",
" username=fake.user_name(),\n",
" password='password',\n",
" confirmed=True,\n",
" name=fake.name(),\n",
" location=fake.city(),\n",
" about_me=fake.text(),\n",
" member_since=fake.past_date())\n",
" db.session.add(u)\n",
" try:\n",
" db.session.commit()\n",
" i += 1\n",
" except IntegrityError:\n",
" db.session.rollback()\n",
"def posts(count=100):\n",
" fake = Faker()\n",
" user_count = User.query.count()\n",
"156 \n",
"| \n",
"Chapter 11: Blog Posts\n",
"\n",
" for i in range(count):\n",
" u = User.query.offset(randint(0, user_count - 1)).first()\n",
" p = Post(body=fake.text(),\n",
" timestamp=fake.past_date(),\n",
" author=u)\n",
" db.session.add(p)\n",
" db.session.commit()\n",
"The attributes of these fake objects are produced by random information generators\n",
"provided by the Faker package, which can generate real-looking names, emails, sen‐\n",
"tences, and many more attributes.\n",
"The email addresses and usernames of users must be unique, but since Faker gener‐\n",
"ates these in a completely random fashion, there is a risk of having duplicates. In the\n",
"unlikely event that a duplicate is generated, the database session commit will throw\n",
"an IntegrityError exception. The exception is handled by rolling back the session to\n",
"cancel that duplicate user. The loop will run until the requested number of unique\n",
"users are generated.\n",
"The random post generation must assign a random user to each post. For this, the\n",
"offset() query filter is used. This filter discards the number of results given as an\n",
"argument. By setting a random offset and then calling first(), a different random\n",
"user is obtained each time.\n",
"If you have cloned the application’s Git repository on GitHub, you\n",
"can run git checkout 11c to check out this version of the applica‐\n",
"tion. To ensure that you have all the dependencies installed, also\n",
"run pip install -r requirements/dev.txt.\n",
"The new functions make it easy to create a large number of fake users and posts from\n",
"the Python shell:\n",
"(venv) $ flask shell\n",
">>> from app import fake\n",
">>> fake.users(100)\n",
">>> fake.posts(100)\n",
"If you run the application now, you will see a long list of random blog posts on the\n",
"home page, by many different users.\n",
"Rendering in Pages\n",
"Example 11-9 shows the changes to the home page route to support pagination.\n",
"Paginating Long Blog Post Lists \n",
"| \n",
"157\n",
"\n",
"Example 11-9. app/main/views.py: paginating the blog post list\n",
"@main.route('/', methods=['GET', 'POST'])\n",
"def index():\n",
" # ...\n",
" page = request.args.get('page', 1, type=int)\n",
" pagination = Post.query.order_by(Post.timestamp.desc()).paginate(\n",
" page, per_page=current_app.config['FLASKY_POSTS_PER_PAGE'],\n",
" error_out=False)\n",
" posts = pagination.items\n",
" return render_template('index.html', form=form, posts=posts,\n",
" pagination=pagination)\n",
"The page number to render is obtained from the request’s query string, which is avail‐\n",
"able as request.args. When a page isn’t given, a default page of 1 (the first page) is\n",
"used. The type=int argument ensures that if the argument cannot be converted to an\n",
"integer, the default value is returned.\n",
"To load a single page of records, the final call to the all() method of the query object\n",
"is replaced with Flask-SQLAlchemy’s paginate(). The paginate() method takes the\n",
"page number as its first and only required argument. An optional per_page argument\n",
"can be given to indicate the size of each page, in number of items. If this argument is\n",
"not specified, the default is 20 items per page. Another optional argument called\n",
"error_out can be set to True (the default) to issue a code 404 error when a page out‐\n",
"side of the valid range is requested. If error_out is False, pages outside of the valid\n",
"range are returned with an empty list of items. To make the page sizes configurable,\n",
"the value of the per_page argument is read from an application-specific configuration\n",
"variable called FLASKY_POSTS_PER_PAGE that is added in config.py.\n",
"With these changes, the blog post list on the home page will show a limited number\n",
"of items. To see the second page of posts, add a ?page=2 query string to the URL in\n",
"the browser’s address bar.\n",
"Adding a Pagination Widget\n",
"The return value of paginate() is an object of class Pagination, a class defined by\n",
"Flask-SQLAlchemy. This object contains several properties that are useful to generate\n",
"page links in a template, so it is passed to the template as an argument. A summary of\n",
"the attributes of the pagination object is shown in Table 11-1.\n",
"158 \n",
"| \n",
"Chapter 11: Blog Posts\n",
"\n",
"Table 11-1. Flask-SQLAlchemy pagination object attributes\n",
"Attribute\n",
"Description\n",
"items\n",
"The records in the current page\n",
"query\n",
"The source query that was paginated\n",
"page\n",
"The current page number\n",
"prev_num\n",
"The previous page number\n",
"next_num\n",
"The next page number\n",
"has_next\n",
"True if there is a next page\n",
"has_prev\n",
"True if there is a previous page\n",
"pages\n",
"The total number of pages for the query\n",
"per_page The number of items per page\n",
"total\n",
"The total number of items returned by the query\n",
"The pagination object also has some methods, listed in Table 11-2.\n",
"Table 11-2. Flask-SQLAlchemy pagination object methods\n",
"Method\n",
"Description\n",
"iter_pages(left_edge=2, \n",
"left_current=2, \n",
"right_current=5, \n",
"right_edge=2)\n",
"An iterator that returns the sequence of page numbers to display in a pagination\n",
"widget. The list will have left_edge pages on the left side, left_current\n",
"pages to the left of the current page, right_current pages to the right of the\n",
"current page, and right_edge pages on the right side. For example, for page 50\n",
"of 100 this iterator configured with default values will return the following pages: 1,\n",
"2, None, 48, 49, 50, 51, 52, 53, 54, 55, None, 99, 100. A None value in the\n",
"sequence indicates a gap in the sequence of pages.\n",
"prev()\n",
"A pagination object for the previous page.\n",
"next()\n",
"A pagination object for the next page.\n",
"Armed with this powerful object and Bootstrap’s pagination CSS classes, it is quite\n",
"easy to build a pagination footer in the template. The implementation shown in\n",
"Example 11-10 is done as a reusable Jinja2 macro.\n",
"Example 11-10. app/templates/_macros.html: pagination template macro\n",
"{% macro pagination_widget(pagination, endpoint) %}\n",
"<ul class=\"pagination\">\n",
" <li{% if not pagination.has_prev %} class=\"disabled\"{% endif %}>\n",
" <a href=\"{% if pagination.has_prev %}{{ url_for(endpoint,\n",
" page = pagination.page - 1, **kwargs) }}{% else %}#{% endif %}\">\n",
" «\n",
" </a>\n",
" </li>\n",
" {% for p in pagination.iter_pages() %}\n",
"Paginating Long Blog Post Lists \n",
"| \n",
"159\n",
"\n",
" {% if p %}\n",
" {% if p == pagination.page %}\n",
" <li class=\"active\">\n",
" <a href=\"{{ url_for(endpoint, page = p, **kwargs) }}\">{{ p }}</a>\n",
" </li>\n",
" {% else %}\n",
" <li>\n",
" <a href=\"{{ url_for(endpoint, page = p, **kwargs) }}\">{{ p }}</a>\n",
" </li>\n",
" {% endif %}\n",
" {% else %}\n",
" <li class=\"disabled\"><a href=\"#\">…</a></li>\n",
" {% endif %}\n",
" {% endfor %}\n",
" <li{% if not pagination.has_next %} class=\"disabled\"{% endif %}>\n",
" <a href=\"{% if pagination.has_next %}{{ url_for(endpoint,\n",
" page = pagination.page + 1, **kwargs) }}{% else %}#{% endif %}\">\n",
" »\n",
" </a>\n",
" </li>\n",
"</ul>\n",
"{% endmacro %}\n",
"The macro creates a Bootstrap pagination element, which is a styled unordered list. It\n",
"defines the following page links inside it:\n",
"• A “previous page” link. This link gets the disabled CSS class if the current page\n",
"is the first page.\n",
"• Links to all pages returned by the pagination object’s iter_pages() iterator.\n",
"These pages are rendered as links with an explicit page number, given as an argu‐\n",
"ment to url_for(). The page currently displayed is highlighted using the active\n",
"CSS class. Gaps in the sequence of pages are rendered with the ellipsis character.\n",
"• A “next page” link. This link will appear disabled if the current page is the last\n",
"page.\n",
"Jinja2 macros always receive keyword arguments without having to include **kwargs\n",
"in the argument list. The pagination macro passes all the keyword arguments it\n",
"receives to the url_for() call that generates the pagination links. This approach can\n",
"be used with routes such as the profile page that have a dynamic part.\n",
"The pagination_widget macro can be added below the _posts.html template\n",
"included by index.html and user.html. Example 11-11 shows how it is used in the\n",
"application’s home page.\n",
"160 \n",
"| \n",
"Chapter 11: Blog Posts\n",
"\n",
"Example 11-11. app/templates/index.html: pagination footer for blog post lists\n",
"{% extends \"base.html\" %}\n",
"{% import \"bootstrap/wtf.html\" as wtf %}\n",
"{% import \"_macros.html\" as macros %}\n",
"...\n",
"{% include '_posts.html' %}\n",
"<div class=\"pagination\">\n",
" {{ macros.pagination_widget(pagination, '.index') }}\n",
"</div>\n",
"{% endif %}\n",
"Figure 11-2 shows how the pagination links appear in the page.\n",
"Figure 11-2. Blog post pagination\n",
"If you have cloned the application’s Git repository on GitHub, you\n",
"can run git checkout 11d to check out this version of the applica‐\n",
"tion.\n",
"Rich-Text Posts with Markdown and Flask-PageDown\n",
"Plain-text posts are sufficient for short messages and status updates, but users who\n",
"want to write longer articles will find the lack of formatting very limiting. In this sec‐\n",
"tion, the text area field where posts are entered will be upgraded to support the Mark‐\n",
"down syntax and present a rich-text preview of the post.\n",
"Rich-Text Posts with Markdown and Flask-PageDown \n",
"| \n",
"161\n",
"\n",
"The implementation of this feature requires a few new packages:\n",
"• PageDown, a client-side Markdown-to-HTML converter implemented in Java‐\n",
"Script\n",
"• Flask-PageDown, a PageDown wrapper for Flask that integrates PageDown with\n",
"Flask-WTF forms\n",
"• Markdown, a server-side Markdown-to-HTML converter implemented in\n",
"Python\n",
"• Bleach, an HTML sanitizer implemented in Python\n",
"The Python packages can all be installed with pip:\n",
"(venv) $ pip install flask-pagedown markdown bleach\n",
"Using Flask-PageDown\n",
"The Flask-PageDown extension defines a PageDownField class that has the same\n",
"interface as the TextAreaField from WTForms. Before this field can be used, the\n",
"extension needs to be initialized as shown in Example 11-12.\n",
"Example 11-12. app/__init__.py: Flask-PageDown initialization\n",
"from flask_pagedown import PageDown\n",
"# ...\n",
"pagedown = PageDown()\n",
"# ...\n",
"def create_app(config_name):\n",
" # ...\n",
" pagedown.init_app(app)\n",
" # ...\n",
"To convert the text area control in the home page to a Markdown rich-text editor, the\n",
"body field of the PostForm must be changed to a PageDownField as shown in\n",
"Example 11-13.\n",
"Example 11-13. app/main/forms.py: Markdown-enabled post form\n",
"from flask_pagedown.fields import PageDownField\n",
"class PostForm(FlaskForm):\n",
" body = PageDownField(\"What's on your mind?\", validators=[Required()])\n",
" submit = SubmitField('Submit')\n",
"The Markdown preview is generated with the help of the PageDown libraries, so\n",
"these must be added to the template. Flask-PageDown simplifies this task by provid‐\n",
"162 \n",
"| \n",
"Chapter 11: Blog Posts\n",
"\n",
"ing a template macro that includes the required files from a CDN as shown in\n",
"Example 11-14.\n",
"Example 11-14. app/templates/index.html: Flask-PageDown template declaration\n",
"{% block scripts %}\n",
"{{ super() }}\n",
"{{ pagedown.include_pagedown() }}\n",
"{% endblock %}\n",
"If you have cloned the application’s Git repository on GitHub, you\n",
"can run git checkout 11e to check out this version of the applica‐\n",
"tion. To ensure that you have all the dependencies installed also run\n",
"pip install -r requirements/dev.txt.\n",
"With these changes, Markdown-formatted text typed in the text area field will be\n",
"immediately rendered as HTML in the preview area below. Figure 11-3 shows the\n",
"blog submission form with rich text.\n",
"Figure 11-3. Rich-text blog post form\n",
"Rich-Text Posts with Markdown and Flask-PageDown \n",
"| \n",
"163\n",
"\n",
"Handling Rich Text on the Server\n",
"When the form is submitted, only the raw Markdown text is sent with the POST\n",
"request; the HTML preview that is shown on the page is discarded. Sending the gen‐\n",
"erated HTML preview with the form can be considered a security risk, as it would be\n",
"fairly easy for an attacker to construct HTML sequences that do not match the Mark‐\n",
"down source and submit them. To avoid any risks, only the Markdown source text is\n",
"submitted, and once in the server it is converted again to HTML using Markdown, a\n",
"Python Markdown-to-HTML converter. The resulting HTML is sanitized with\n",
"Bleach to ensure that only a short list of allowed HTML tags are used.\n",
"The conversion of the Markdown blog posts to HTML can be done in the _posts.html\n",
"template, but this is inefficient as posts will have to be converted every time they are\n",
"rendered to a page. To avoid this repetition, the conversion can be done once when\n",
"the blog post is created and then cached in the database. The HTML code for the ren‐\n",
"dered blog post is cached in a new field added to the Post model that the template\n",
"can access directly. The original Markdown source is also kept in the database in case\n",
"the post needs to be edited. Example 11-15 shows the changes to the Post model.\n",
"Example 11-15. app/models.py: Markdown text handling in the Post model\n",
"from markdown import markdown\n",
"import bleach\n",
"class Post(db.Model):\n",
" # ...\n",
" body_html = db.Column(db.Text)\n",
" # ...\n",
" @staticmethod\n",
" def on_changed_body(target, value, oldvalue, initiator):\n",
" allowed_tags = ['a', 'abbr', 'acronym', 'b', 'blockquote', 'code',\n",
" 'em', 'i', 'li', 'ol', 'pre', 'strong', 'ul',\n",
" 'h1', 'h2', 'h3', 'p']\n",
" target.body_html = bleach.linkify(bleach.clean(\n",
" markdown(value, output_format='html'),\n",
" tags=allowed_tags, strip=True))\n",
"db.event.listen(Post.body, 'set', Post.on_changed_body)\n",
"The on_changed_body() function is registered as a listener of SQLAlchemy’s “set”\n",
"event for body, which means that it will be automatically invoked whenever the body\n",
"field is set to a new value. The handler function renders the HTML version of the\n",
"body and stores it in body_html, effectively making the conversion of the Markdown\n",
"text to HTML fully automatic.\n",
"The actual conversion is done in three steps. First, the markdown() function does an\n",
"initial conversion to HTML. The result is passed to clean(), along with the list of\n",
"164 \n",
"| \n",
"Chapter 11: Blog Posts\n",
"\n",
"approved HTML tags. The clean() function removes any tags not on the whitelist.\n",
"The final conversion is done with linkify(), another function provided by Bleach\n",
"that converts any URLs written in plain text into proper <a> links. This last step is\n",
"necessary because automatic link generation is not officially in the Markdown specifi‐\n",
"cation, but is a very convenient feature. On the client side, PageDown supports this\n",
"feature as an optional extension, so linkify() matches that functionality on the\n",
"server.\n",
"The last change is to replace post.body with post.body_html in the template when\n",
"available, as shown in Example 11-16.\n",
"Example 11-16. app/templates/_posts.html: use the HTML version of the post bodies in\n",
"the template\n",
"...\n",
"<div class=\"post-body\">\n",
" {% if post.body_html %}\n",
" {{ post.body_html | safe }}\n",
" {% else %}\n",
" {{ post.body }}\n",
" {% endif %}\n",
"</div>\n",
"...\n",
"The | safe suffix when rendering the HTML body is there to tell Jinja2 not to escape\n",
"the HTML elements. Jinja2 escapes all template variables by default as a security\n",
"measure, but the Markdown-generated HTML was generated by the server, so it is\n",
"safe to render directly as HTML.\n",
"If you have cloned the application’s Git repository on GitHub, you\n",
"can run git checkout 11f to check out this version of the applica‐\n",
"tion. This update also contains a database migration, so remember\n",
"to run flask db upgrade after you check out the code. To ensure\n",
"that you have all the dependencies installed also run pip install\n",
"-r requirements/dev.txt.\n",
"Permanent Links to Blog Posts\n",
"Users may want to share links to specific blog posts with friends on social networks.\n",
"For this purpose, each post will be assigned a page with a unique URL that references\n",
"it. The route and view function that support permanent links are shown in\n",
"Example 11-17.\n",
"Permanent Links to Blog Posts \n",
"| \n",
"165\n",
"\n",
"Example 11-17. app/main/views.py: enabling permanent links to posts\n",
"@main.route('/post/<int:id>')\n",
"def post(id):\n",
" post = Post.query.get_or_404(id)\n",
" return render_template('post.html', posts=[post])\n",
"The URLs that will be assigned to blog posts are constructed with the unique id field\n",
"assigned when the post is inserted in the database.\n",
"For some types of applications, building permanent links that use\n",
"readable URLs instead of numeric IDs may be preferred. An alter‐\n",
"native to numeric IDs is to assign each blog post a slug, which is a\n",
"unique string that is based on the title or first few words of the\n",
"post.\n",
"Note that the post.html template receives a list with a single element that is the post to\n",
"render. Sending a list is a matter of convenience, so that the _posts.html template ref‐\n",
"erenced by index.html and user.html can be used in this page as well.\n",
"The permanent links are added at the bottom of each post in the generic _posts.html\n",
"template, as shown in Example 11-18.\n",
"Example 11-18. app/templates/_posts.html: adding permanent links to posts\n",
"<ul class=\"posts\">\n",
" {% for post in posts %}\n",
" <li class=\"post\">\n",
" ...\n",
" <div class=\"post-content\">\n",
" ...\n",
" <div class=\"post-footer\">\n",
" <a href=\"{{ url_for('.post', id=post.id) }}\">\n",
" <span class=\"label label-default\">Permalink</span>\n",
" </a>\n",
" </div>\n",
" </div>\n",
" </li>\n",
" {% endfor %}\n",
"</ul>\n",
"The new post.html template that renders the permanent link page is shown in\n",
"Example 11-19. It includes the example template.\n",
"166 \n",
"| \n",
"Chapter 11: Blog Posts\n",
"\n",
"Example 11-19. app/templates/post.html: permanent link template\n",
"{% extends \"base.html\" %}\n",
"{% block title %}Flasky - Post{% endblock %}\n",
"{% block page_content %}\n",
"{% include '_posts.html' %}\n",
"{% endblock %}\n",
"If you have cloned the application’s Git repository on GitHub, you\n",
"can run git checkout 11g to check out this version of the applica‐\n",
"tion.\n",
"Blog Post Editor\n",
"The last feature related to blog posts is a post editor that allows users to edit their own\n",
"posts. The blog post editor lives in a standalone page and is also based on Flask-\n",
"PageDown, so a text area where the Markdown text of the blog post can be edited is\n",
"followed by a rendered preview. The edit_post.html template is shown in\n",
"Example 11-20.\n",
"Example 11-20. app/templates/edit_post.html: edit blog post template\n",
"{% extends \"base.html\" %}\n",
"{% import \"bootstrap/wtf.html\" as wtf %}\n",
"{% block title %}Flasky - Edit Post{% endblock %}\n",
"{% block page_content %}\n",
"<div class=\"page-header\">\n",
" <h1>Edit Post</h1>\n",
"</div>\n",
"<div>\n",
" {{ wtf.quick_form(form) }}\n",
"</div>\n",
"{% endblock %}\n",
"{% block scripts %}\n",
"{{ super() }}\n",
"{{ pagedown.include_pagedown() }}\n",
"{% endblock %}\n",
"The route that supports the blog post editor is shown in Example 11-21.\n",
"Blog Post Editor \n",
"| \n",
"167\n",
"\n",
"Example 11-21. app/main/views.py: edit blog post route\n",
"@main.route('/edit/<int:id>', methods=['GET', 'POST'])\n",
"@login_required\n",
"def edit(id):\n",
" post = Post.query.get_or_404(id)\n",
" if current_user != post.author and \\\n",
" not current_user.can(Permission.ADMIN):\n",
" abort(403)\n",
" form = PostForm()\n",
" if form.validate_on_submit():\n",
" post.body = form.body.data\n",
" db.session.add(post)\n",
" db.session.commit()\n",
" flash('The post has been updated.')\n",
" return redirect(url_for('.post', id=post.id))\n",
" form.body.data = post.body\n",
" return render_template('edit_post.html', form=form)\n",
"This view function is coded to allow only the author of a blog post to edit it, except\n",
"for administrators, who are allowed to edit posts from all users. If a user tries to edit a\n",
"post from another user, the view function responds with a 403 code. The PostForm\n",
"web form class used here is the same one used on the home page.\n",
"To complete the feature, a link to the blog post editor can be added below each blog\n",
"post, next to the permanent link, as shown in Example 11-22.\n",
"Example 11-22. app/templates/_posts.html: adding the edit blog post link\n",
"<ul class=\"posts\">\n",
" {% for post in posts %}\n",
" <li class=\"post\">\n",
" ...\n",
" <div class=\"post-content\">\n",
" ...\n",
" <div class=\"post-footer\">\n",
" ...\n",
" {% if current_user == post.author %}\n",
" <a href=\"{{ url_for('.edit', id=post.id) }}\">\n",
" <span class=\"label label-primary\">Edit</span>\n",
" </a>\n",
" {% elif current_user.is_administrator() %}\n",
" <a href=\"{{ url_for('.edit', id=post.id) }}\">\n",
" <span class=\"label label-danger\">Edit [Admin]</span>\n",
" </a>\n",
" {% endif %}\n",
" </div>\n",
" </div>\n",
" </li>\n",
" {% endfor %}\n",
"</ul>\n",
"168 \n",
"| \n",
"Chapter 11: Blog Posts\n",
"\n",
"This change adds an “Edit” link to any blog posts that are authored by the current\n",
"user. For administrators, the link is added to all posts. The administrator link is styled\n",
"differently as a visual cue that this is an administration feature. Figure 11-4 shows\n",
"how the Edit and Permalink links look in the web browser.\n",
"Figure 11-4. Edit and Permalink links in a blog post\n",
"If you have cloned the application’s Git repository on GitHub, you\n",
"can run git checkout 11h to check out this version of the applica‐\n",
"tion.\n",
"Blog Post Editor \n",
"| \n",
"169\n",
"\n",
"\n",
"CHAPTER 12\n",
"Followers\n",
"Socially aware web applications allow users to connect with other users. Different\n",
"applications call these relationships followers, friends, contacts, connections, or bud‐\n",
"dies, but the feature is the same regardless of the name, and in all cases involves keep‐\n",
"ing track of directional links between pairs of users and using these links in database\n",
"queries.\n",
"In this chapter, you will learn how to implement a follower feature for Flasky. Users\n",
"will be able to “follow” other users and choose to filter the blog post list on the home\n",
"page to include only those from the users they follow.\n",
"Database Relationships Revisited\n",
"As discussed in Chapter 5, databases establish links between records using relation‐\n",
"ships. The one-to-many relationship is the most common type of relationship, where\n",
"a record is linked with a list of related records. To implement this type of relationship,\n",
"the elements on the “many” side have a foreign key that points to the linked element\n",
"on the “one” side. The example application in its current state includes two one-to-\n",
"many relationships: one that links user roles to lists of users and another that links\n",
"users to the blog posts they authored.\n",
"Most other relationship types can be derived from the one-to-many type. The many-\n",
"to-one relationship is a one-to-many looked at from the point of view of the “many”\n",
"side. The one-to-one relationship type is a simplification of the one-to-many, where\n",
"the “many” side is constrained to have at most one element. The only relationship\n",
"type that cannot be implemented as a simple variation of the one-to-many model is\n",
"the many-to-many, which has lists of elements on both sides. This relationship is\n",
"described in detail in the following section.\n",
"171\n",
"\n",
"Many-to-Many Relationships\n",
"The one-to-many, many-to-one, and one-to-one relationships all have at least one\n",
"side with a single entity, so the links between related records are implemented with\n",
"foreign keys pointing to that one element. But how do you implement a relationship\n",
"where both sides are “many” sides?\n",
"Consider the classic example of a many-to-many relationship: a database of students\n",
"and the classes they are taking. Clearly, you can’t add a foreign key to a class in the\n",
"students table, because a student takes many classes—one foreign key is not enough.\n",
"Likewise, you cannot add a foreign key to a student in the classes table, because\n",
"classes have more than one student. Both sides need a list of foreign keys.\n",
"The solution is to add a third table to the database, called an association table. Now\n",
"the many-to-many relationship can be decomposed into two one-to-many relation‐\n",
"ships from each of the two original tables to the association table. Figure 12-1 shows\n",
"how the many-to-many relationship between students and classes is represented.\n",
"Figure 12-1. Many-to-many relationship example\n",
"The association table in this example is called registrations. Each row in this table\n",
"represents an individual registration of a student in a class.\n",
"Querying a many-to-many relationship is a two-step process. To obtain the list of\n",
"classes a student is taking, you start from the one-to-many relationship between stu‐\n",
"dents and registrations and get the list of registrations for the desired student. Then\n",
"the one-to-many relationship between classes and registrations is traversed in the\n",
"many-to-one direction to obtain all the classes associated with the registrations\n",
"retrieved for the student. Likewise, to find all the students in a class, you start from\n",
"the class and get a list of registrations, then get the students linked to those registra‐\n",
"tions.\n",
"Traversing two relationships to obtain query results sounds difficult, but for a simple\n",
"relationship like the one in the previous example, SQLAlchemy does most of the\n",
"work. Following is the code that represents the many-to-many relationship in\n",
"Figure 12-1:\n",
"172 \n",
"| \n",
"Chapter 12: Followers\n",
"\n",
"registrations = db.Table('registrations',\n",
" db.Column('student_id', db.Integer, db.ForeignKey('students.id')),\n",
" db.Column('class_id', db.Integer, db.ForeignKey('classes.id'))\n",
")\n",
"class Student(db.Model):\n",
" id = db.Column(db.Integer, primary_key=True)\n",
" name = db.Column(db.String)\n",
" classes = db.relationship('Class',\n",
" secondary=registrations,\n",
" backref=db.backref('students', lazy='dynamic'),\n",
" lazy='dynamic')\n",
"class Class(db.Model):\n",
" id = db.Column(db.Integer, primary_key=True)\n",
" name = db.Column(db.String)\n",
"The relationship is defined with the same db.relationship() construct that is used\n",
"for one-to-many relationships, but in the case of a many-to-many relationship the\n",
"additional secondary argument must be set to the association table. The relationship\n",
"can be defined in either one of the two classes, with the backref argument taking care\n",
"of exposing the relationship from the other side as well. The association table is\n",
"defined as a simple table, not as a model, since SQLAlchemy manages this table inter‐\n",
"nally.\n",
"The classes relationship uses list semantics, which makes working with a many-to-\n",
"many relationship configured in this way extremely easy. Given a student s and a\n",
"class c, the code that registers the student for the class is:\n",
">>> s.classes.append(c)\n",
">>> db.session.add(s)\n",
"The queries that list the classes student s is registered for and the list of students reg‐\n",
"istered for class c are also very simple:\n",
">>> s.classes.all()\n",
">>> c.students.all()\n",
"The students relationship available in the Class model is the one defined in the\n",
"db.backref() argument. Note that in this relationship the backref argument was\n",
"expanded to also have a lazy='dynamic' attribute, so both sides return a query that\n",
"can accept additional filters.\n",
"If student s later decides to drop class c, you can update the database as follows:\n",
">>> s.classes.remove(c)\n",
"Database Relationships Revisited \n",
"| \n",
"173\n",
"\n",
"Self-Referential Relationships\n",
"A many-to-many relationship can be used to model users following other users, but\n",
"there is a problem. In the example of students and classes, there were two very clearly\n",
"defined entities linked together by the association table. However, to represent users\n",
"following other users, it is just users—there is no second entity.\n",
"A relationship in which both sides belong to the same table is said to be self-\n",
"referential. In this case the entities on the left side of the relationship are users, which\n",
"can be called the “followers.” The entities on the right side are also users, but these are\n",
"the “followed” users. Conceptually, self-referential relationships are no different than\n",
"regular relationships, but they are harder to think about. Figure 12-2 shows a data‐\n",
"base diagram for a self-referential relationship that represents users following other\n",
"users.\n",
"Figure 12-2. Followers, many-to-many relationship\n",
"The association table in this case is called follows. Each row in this table represents a\n",
"user following another user. The one-to-many relationship pictured on the left side\n",
"associates users with the list of “follows” rows in which they are the followers. The\n",
"one-to-many relationship pictured on the right side associates users with the list of\n",
"“follows” rows in which they are the followed user.\n",
"Advanced Many-to-Many Relationships\n",
"With a self-referential many-to-many relationship configured as shown in the previ‐\n",
"ous example, the database can represent followers—but there is one limitation. A\n",
"common need when working with many-to-many relationships is to store additional\n",
"data that applies to the link between two entities. For the followers relationship, it can\n",
"be useful to store the date a user started following another user, as that will enable\n",
"lists of followers to be presented in chronological order. The only place this informa‐\n",
"174 \n",
"| \n",
"Chapter 12: Followers\n",
"\n",
"tion can be stored is in the association table, but in an implementation similar to that\n",
"of the students and classes shown earlier, the association table is an internal table that\n",
"is fully managed by SQLAlchemy.\n",
"To be able to work with custom data in the relationship, the association table must be\n",
"promoted to a proper model that the application can access. Example 12-1 shows the\n",
"new association table, represented by the Follow model.\n",
"Example 12-1. app/models.py: the follows association table as a model\n",
"class Follow(db.Model):\n",
" __tablename__ = 'follows'\n",
" follower_id = db.Column(db.Integer, db.ForeignKey('users.id'),\n",
" primary_key=True)\n",
" followed_id = db.Column(db.Integer, db.ForeignKey('users.id'),\n",
" primary_key=True)\n",
" timestamp = db.Column(db.DateTime, default=datetime.utcnow)\n",
"SQLAlchemy cannot use the association table transparently because that will not give\n",
"the application access to the custom fields in it. Instead, the many-to-many relation‐\n",
"ship must be decomposed into the two basic one-to-many relationships for the left\n",
"and right sides, and these must be defined as standard relationships. This is shown in\n",
"Example 12-2.\n",
"Example 12-2. app/models.py: a many-to-many relationship implemented as two one-\n",
"to-many relationships\n",
"class User(UserMixin, db.Model):\n",
" # ...\n",
" followed = db.relationship('Follow',\n",
" foreign_keys=[Follow.follower_id],\n",
" backref=db.backref('follower', lazy='joined'),\n",
" lazy='dynamic',\n",
" cascade='all, delete-orphan')\n",
" followers = db.relationship('Follow',\n",
" foreign_keys=[Follow.followed_id],\n",
" backref=db.backref('followed', lazy='joined'),\n",
" lazy='dynamic',\n",
" cascade='all, delete-orphan')\n",
"Here the followed and followers relationships are defined as individual one-to-\n",
"many relationships. Note that it is necessary to eliminate any ambiguity between for‐\n",
"eign keys by specifying in each relationship which foreign key to use through the\n",
"foreign_keys optional argument. The db.backref() arguments in these relation‐\n",
"ships do not apply to each other; the back references are applied to the Follow model.\n",
"Database Relationships Revisited \n",
"| \n",
"175\n",
"\n",
"The lazy argument for the back references is specified as joined. This lazy mode\n",
"causes the related object to be loaded immediately from the join query. For example,\n",
"if a user is following 100 other users, calling user.followed.all() will return a list\n",
"of 100 Follow instances, where each one has the follower and followed back refer‐\n",
"ence properties set to the respective users. The lazy='joined' mode enables this all\n",
"to happen from a single database query. If lazy is set to the default value of select,\n",
"then the follower and followed users are loaded lazily when they are first accessed\n",
"and each attribute will require an individual query, which means that obtaining the\n",
"complete list of followed users would require 100 additional database queries.\n",
"The lazy argument on the User side of both relationships has different needs. These\n",
"are on the “one” side and return the “many” side; here a mode of dynamic is used, so\n",
"that the relationship attributes return query objects instead of returning the items\n",
"directly. This allows additional filters to be added to the query before it is executed.\n",
"The cascade argument configures how actions performed on a parent object propa‐\n",
"gate to related objects. An example of a cascade option is the rule that says that when\n",
"an object is added to the database session, any objects associated with it through rela‐\n",
"tionships should automatically be added to the session as well. The default cascade\n",
"options are appropriate for most situations, but there is one case in which the default\n",
"cascade options do not work well for this many-to-many relationship. The default\n",
"cascade behavior when an object is deleted is to set the foreign key in any related\n",
"objects that link to it to a null value. But for an association table, the correct behavior\n",
"is to delete the entries that point to a record that was deleted, as this effectively\n",
"destroys the link. This is what the delete-orphan cascade option does.\n",
"The value given to cascade is a comma-separated list of cascade\n",
"options. This is somewhat confusing, but the option named all\n",
"represents all the cascade options except delete-orphan. Using the\n",
"value all, delete-orphan leaves the default cascade options\n",
"enabled and adds the delete behavior for orphans.\n",
"The application now needs to work with the two one-to-many relationships to imple‐\n",
"ment the many-to-many functionality. Since these are operations that will need to be\n",
"repeated often, it is a good idea to create helper methods in the User model for all the\n",
"possible operations. The four new methods that control this relationship are shown in\n",
"Example 12-3.\n",
"176 \n",
"| \n",
"Chapter 12: Followers\n",
"\n",
"Example 12-3. app/models.py: followers helper methods\n",
"class User(db.Model):\n",
" # ...\n",
" def follow(self, user):\n",
" if not self.is_following(user):\n",
" f = Follow(follower=self, followed=user)\n",
" db.session.add(f)\n",
" def unfollow(self, user):\n",
" f = self.followed.filter_by(followed_id=user.id).first()\n",
" if f:\n",
" db.session.delete(f)\n",
" def is_following(self, user):\n",
" if user.id is None:\n",
" return False\n",
" return self.followed.filter_by(\n",
" followed_id=user.id).first() is not None\n",
" def is_followed_by(self, user):\n",
" if user.id is None:\n",
" return False\n",
" return self.followers.filter_by(\n",
" follower_id=user.id).first() is not None\n",
"The follow() method manually inserts a Follow instance in the association table that\n",
"links a follower with a followed user, giving the application the opportunity to set the\n",
"custom field. The two users who are connecting are manually assigned to the new\n",
"Follow instance in its constructor, and then the object is added to the database ses‐\n",
"sion as usual. Note that there is no need to manually set the timestamp field because\n",
"it was defined with a default value that sets the current date and time. The\n",
"unfollow() method uses the followed relationship to locate the Follow instance that\n",
"links the user to the followed user who needs to be disconnected. To destroy the link\n",
"between the two users, the Follow object is simply deleted. The is_following() and\n",
"is_followed_by() methods search the left- and right-side one-to-many relation‐\n",
"ships, respectively, for the given user and return True if the user is found. Both ensure\n",
"that the given user has been assigned an id before issuing a query, to avoid errors if a\n",
"user that has been created but not committed to the database yet is provided.\n",
"Database Relationships Revisited \n",
"| \n",
"177\n",
"\n",
"If you have cloned the application’s Git repository on GitHub, you\n",
"can run git checkout 12a to check out this version of the applica‐\n",
"tion. This update contains a database migration, so remember to\n",
"run flask db upgrade after you check out the code.\n",
"The database part of this feature is now complete. You can find a unit test that exerci‐\n",
"ses the new database relationship in the source code repository on GitHub.\n",
"Followers on the Profile Page\n",
"The profile page of a user needs to present a “Follow” button if the user viewing it is\n",
"not a follower, or an “Unfollow” button if the user is a follower. It is also a nice addi‐\n",
"tion to show the follower and followed counts, display the lists of followers and fol‐\n",
"lowed users, and show a “Follows you” sign when appropriate. The changes to the\n",
"user profile template are shown in Example 12-4. Figure 12-3 shows how the addi‐\n",
"tions look on the profile page.\n",
"Example 12-4. app/templates/user.html: follower enhancements to the user profile\n",
"header\n",
"{% if current_user.can(Permission.FOLLOW) and user != current_user %}\n",
" {% if not current_user.is_following(user) %}\n",
" <a href=\"{{ url_for('.follow', username=user.username) }}\"\n",
" class=\"btn btn-primary\">Follow</a>\n",
" {% else %}\n",
" <a href=\"{{ url_for('.unfollow', username=user.username) }}\"\n",
" class=\"btn btn-default\">Unfollow</a>\n",
" {% endif %}\n",
"{% endif %}\n",
"<a href=\"{{ url_for('.followers', username=user.username) }}\">\n",
" Followers: <span class=\"badge\">{{ user.followers.count() }}</span>\n",
"</a>\n",
"<a href=\"{{ url_for('.followed_by', username=user.username) }}\">\n",
" Following: <span class=\"badge\">{{ user.followed.count() }}</span>\n",
"</a>\n",
"{% if current_user.is_authenticated and user != current_user and\n",
" user.is_following(current_user) %}\n",
"| <span class=\"label label-default\">Follows you</span>\n",
"{% endif %}\n",
"178 \n",
"| \n",
"Chapter 12: Followers\n",
"\n",
"Figure 12-3. Followers on the profile page\n",
"There are four new endpoints defined in these template changes. The /follow/<user‐\n",
"name> route is invoked when a user clicks the “Follow” button on another user’s pro‐\n",
"file page. The implementation is shown in Example 12-5.\n",
"Example 12-5. app/main/views.py: follow route and view function\n",
"@main.route('/follow/<username>')\n",
"@login_required\n",
"@permission_required(Permission.FOLLOW)\n",
"def follow(username):\n",
" user = User.query.filter_by(username=username).first()\n",
" if user is None:\n",
" flash('Invalid user.')\n",
" return redirect(url_for('.index'))\n",
" if current_user.is_following(user):\n",
" flash('You are already following this user.')\n",
" return redirect(url_for('.user', username=username))\n",
" current_user.follow(user)\n",
" db.session.commit()\n",
" flash('You are now following %s.' % username)\n",
" return redirect(url_for('.user', username=username))\n",
"This view function loads the requested user, verifies that it is valid and that it isn’t\n",
"already followed by the logged-in user, and then calls the follow() helper function in\n",
"Followers on the Profile Page \n",
"| \n",
"179\n",
"\n",
"the User model to establish the link. The /unfollow/<username> route is implemented\n",
"in a similar way.\n",
"The /followers/<username> route is invoked when a user clicks another user’s fol‐\n",
"lower count on the profile page. The implementation is shown in Example 12-6.\n",
"Example 12-6. app/main/views.py: followers route and view function\n",
"@main.route('/followers/<username>')\n",
"def followers(username):\n",
" user = User.query.filter_by(username=username).first()\n",
" if user is None:\n",
" flash('Invalid user.')\n",
" return redirect(url_for('.index'))\n",
" page = request.args.get('page', 1, type=int)\n",
" pagination = user.followers.paginate(\n",
" page, per_page=current_app.config['FLASKY_FOLLOWERS_PER_PAGE'],\n",
" error_out=False)\n",
" follows = [{'user': item.follower, 'timestamp': item.timestamp}\n",
" for item in pagination.items]\n",
" return render_template('followers.html', user=user, title=\"Followers of\",\n",
" endpoint='.followers', pagination=pagination,\n",
" follows=follows)\n",
"This function loads and validates the requested user, then paginates its followers\n",
"relationship using the same techniques learned in Chapter 11. Because the query for\n",
"followers returns Follow instances, the list is converted into another list that has user\n",
"and timestamp fields in each entry so that rendering is simpler.\n",
"The template that renders the follower list can be written generically so that it can be\n",
"used for lists of followers and followed users. The template receives the user, a title for\n",
"the page, the endpoint to use in the pagination links, the pagination object, and the\n",
"list of results.\n",
"The followed_by endpoint is almost identical. The only difference is that the list of\n",
"users is obtained from the user.followed relationship. The template arguments are\n",
"also adjusted accordingly.\n",
"The followers.html template is implemented with a two-column table that shows user‐\n",
"names and their avatars on the left and Flask-Moment timestamps on the right. You\n",
"can consult the source code repository on GitHub to study the implementation in\n",
"detail.\n",
"If you have cloned the application’s Git repository on GitHub, you\n",
"can run git checkout 12b to check out this version of the applica‐\n",
"tion.\n",
"180 \n",
"| \n",
"Chapter 12: Followers\n",
"\n",
"Querying Followed Posts Using a Database Join\n",
"The application’s home page currently shows all the posts in the database in descend‐\n",
"ing chronological order. With the followers feature now complete, it would be a nice\n",
"addition to give users the option to view blog posts from only the users they follow.\n",
"The obvious way to load all the posts authored by followed users is to first get the list\n",
"of those users and then get the posts from each and sort them into a single list. Of\n",
"course, that approach does not scale well; the effort required to obtain this combined\n",
"list will grow as the database grows, and operations such as pagination cannot be\n",
"done efficiently. This problem is commonly known as the “N+1 problem,” because\n",
"working with the database in this way requires issuing N+1 database queries, with N\n",
"being the number of results returned by the first query. The key to obtaining the blog\n",
"posts with good performance regardless of the database size is doing it all with a sin‐\n",
"gle query.\n",
"The database operation that can do this is called a join. A join operation takes two or\n",
"more tables and finds all the combinations of rows that satisfy a given condition. The\n",
"resulting combined rows are inserted into a temporary table that is the result of the\n",
"join. The best way to explain how joins work is through an example.\n",
"Table 12-1 shows an example users table with three users.\n",
"Table 12-1. users table\n",
"id username\n",
"1\n",
"john\n",
"2\n",
"susan\n",
"3\n",
"david\n",
"Table 12-2 shows the corresponding posts table, with some blog posts.\n",
"Table 12-2. posts table\n",
"id author_id body\n",
"1\n",
"2\n",
"Blog post by susan\n",
"2\n",
"1\n",
"Blog post by john\n",
"3\n",
"3\n",
"Blog post by david\n",
"4\n",
"1\n",
"Second blog post by john\n",
"Finally, Table 12-3 shows who is following whom. In this table you can see that john is\n",
"following david, susan is following john and david, and david is not following anyone.\n",
"Querying Followed Posts Using a Database Join \n",
"| \n",
"181\n",
"\n",
"Table 12-3. follows table\n",
"follower_id\n",
"followed_id\n",
"1\n",
"3\n",
"2\n",
"1\n",
"2\n",
"3\n",
"To obtain the list of posts by users followed by the user susan, the posts and follows\n",
"tables must be combined. First the follows table is filtered to keep just the rows that\n",
"have susan as the follower, which in this example are the last two rows. Then a tem‐\n",
"porary join table is created from all the possible combinations of rows from the posts\n",
"and filtered follows tables in which the author_id of the post is the same as the\n",
"followed_id of the follow, effectively selecting any posts that appear in the list of\n",
"users susan is following. Table 12-4 shows the result of the join operation. The col‐\n",
"umns that were used to perform the join are marked with an * in this table.\n",
"Table 12-4. Joined table\n",
"id author_id*\n",
"body\n",
"follower_id\n",
"followed_id*\n",
"2\n",
"1\n",
"Blog post by john\n",
"2\n",
"1\n",
"3\n",
"3\n",
"Blog post by david\n",
"2\n",
"3\n",
"4\n",
"1\n",
"Second blog post by john\n",
"2\n",
"1\n",
"This table contains exactly the list of blog posts authored by users that susan is follow‐\n",
"ing. The Flask-SQLAlchemy query that performs the join operation as described is\n",
"fairly complex:\n",
"return db.session.query(Post).select_from(Follow).\\\n",
" filter_by(follower_id=self.id).\\\n",
" join(Post, Follow.followed_id == Post.author_id)\n",
"All the queries that you have seen so far start from the query attribute of the model\n",
"that is queried. That format does not work well for this query, because the query\n",
"needs to return posts rows, yet the first operation that needs to be done is to apply a\n",
"filter to the follows table. So, a more basic form of the query is used instead. To fully\n",
"understand this query, each part should be looked at individually:\n",
"• db.session.query(Post) specifies that this is going to be a query that returns\n",
"Post objects.\n",
"• select_from(Follow) says that the query begins with the Follow model.\n",
"• filter_by(follower_id=self.id) performs the filtering of the follows table by\n",
"the follower user.\n",
"182 \n",
"| \n",
"Chapter 12: Followers\n",
"\n",
"• join(Post, Follow.followed_id == Post.author_id) joins the results of\n",
"filter_by() with the Post objects.\n",
"The query can be simplified by swapping the order of the filter and the join:\n",
"return Post.query.join(Follow, Follow.followed_id == Post.author_id)\\\n",
" .filter(Follow.follower_id == self.id)\n",
"Issuing the join operation first means the query can be started from Post.query, so\n",
"now the only two filters that need to be applied are join() and filter(). It may\n",
"seem that doing the join first and then the filtering would be more work, but in real‐\n",
"ity these two queries are equivalent. SQLAlchemy first collects all the filters and then\n",
"generates the query in the most efficient way. The native SQL instructions for these\n",
"two queries are nearly identical, something that you can confirm by printing the\n",
"query object converted to a string (i.e., print(str(query))). The final version of this\n",
"query is added to the Post model, as shown in Example 12-7.\n",
"Example 12-7. app/models.py: obtaining followed posts\n",
"class User(db.Model):\n",
" # ...\n",
" @property\n",
" def followed_posts(self):\n",
" return Post.query.join(Follow, Follow.followed_id == Post.author_id)\\\n",
" .filter(Follow.follower_id == self.id)\n",
"Note that the followed_posts() method is defined as a property so that it does not\n",
"need the (). That way, all relationships have a consistent syntax.\n",
"If you have cloned the application’s Git repository on GitHub, you\n",
"can run git checkout 12c to check out this version of the applica‐\n",
"tion.\n",
"Joins are extremely hard to wrap your head around; you may need to experiment\n",
"with the example code in a shell before it all sinks in.\n",
"Showing Followed Posts on the Home Page\n",
"The home page can now give users the choice to view all blog posts or just those from\n",
"followed users. Example 12-8 shows how this choice is implemented.\n",
"Showing Followed Posts on the Home Page \n",
"| \n",
"183\n",
"\n",
"Example 12-8. app/main/views.py: showing all or followed posts\n",
"@main.route('/', methods = ['GET', 'POST'])\n",
"def index():\n",
" # ...\n",
" show_followed = False\n",
" if current_user.is_authenticated:\n",
" show_followed = bool(request.cookies.get('show_followed', ''))\n",
" if show_followed:\n",
" query = current_user.followed_posts\n",
" else:\n",
" query = Post.query\n",
" pagination = query.order_by(Post.timestamp.desc()).paginate(\n",
" page, per_page=current_app.config['FLASKY_POSTS_PER_PAGE'],\n",
" error_out=False)\n",
" posts = pagination.items\n",
" return render_template('index.html', form=form, posts=posts,\n",
" show_followed=show_followed, pagination=pagination)\n",
"The choice of showing all or followed posts is stored in a cookie called\n",
"show_followed that, when set to a nonempty string, indicates that only followed\n",
"posts should be shown. Cookies are stored in the request object as a\n",
"request.cookies dictionary. The string value of the cookie is converted to a Boolean,\n",
"and based on its value a query local variable is set to the query that obtains the com‐\n",
"plete or filtered list of blog posts. To show all the posts, the top-level query\n",
"Post.query is used, and the recently added User.followed_posts property is used\n",
"when the list should be restricted to followed users. The query stored in the query\n",
"local variable is then paginated and the results sent to the template as before.\n",
"The show_followed cookie is set in two new routes, shown in Example 12-9.\n",
"Example 12-9. app/main/views.py: selection of all or followed posts\n",
"@main.route('/all')\n",
"@login_required\n",
"def show_all():\n",
" resp = make_response(redirect(url_for('.index')))\n",
" resp.set_cookie('show_followed', '', max_age=30*24*60*60) # 30 days\n",
" return resp\n",
"@main.route('/followed')\n",
"@login_required\n",
"def show_followed():\n",
" resp = make_response(redirect(url_for('.index')))\n",
" resp.set_cookie('show_followed', '1', max_age=30*24*60*60) # 30 days\n",
" return resp\n",
"184 \n",
"| \n",
"Chapter 12: Followers\n",
"\n",
"Links to these routes are added to the home page template. When they are invoked,\n",
"the show_followed cookie is set to the proper value and a redirect back to the home\n",
"page is issued.\n",
"Cookies can be set only on a response object, so these routes need to create a\n",
"response object through make_response() instead of letting Flask do this.\n",
"The set_cookie() function takes the cookie name and the value as the first two argu‐\n",
"ments. The max_age optional argument sets the number of seconds until the cookie\n",
"expires. Not including this argument makes the cookie expire when the browser win‐\n",
"dow is closed. In this case, a maximum age of 30 days is set so that the setting is\n",
"remembered even if the user does not return to the application for several days.\n",
"The changes to the template add two navigation tabs at the top of the page that invoke\n",
"the /all or /followed routes to set the correct settings in the session. You can inspect\n",
"the template changes in detail in the source code repository on GitHub. Figure 12-4\n",
"shows how the home page looks with these changes.\n",
"Figure 12-4. Followed posts on the home page\n",
"Showing Followed Posts on the Home Page \n",
"| \n",
"185\n",
"\n",
"If you have cloned the application’s Git repository on GitHub, you\n",
"can run git checkout 12d to check out this version of the applica‐\n",
"tion.\n",
"If you try the application at this point and switch to the followed list of posts, you will\n",
"notice that your own posts do not appear in the list. This is of course correct, because\n",
"users are not followers of themselves.\n",
"Even though the queries are working as designed, most users will expect to see their\n",
"own posts when they are looking at those of their friends. The easiest way to address\n",
"this issue is to register all users as their own followers at the time they are created.\n",
"This trick is shown in Example 12-10.\n",
"Example 12-10. app/models.py: making users their own followers when they are created\n",
"class User(UserMixin, db.Model):\n",
" # ...\n",
" def __init__(self, **kwargs):\n",
" # ...\n",
" self.follow(self)\n",
"Unfortunately, you likely have several users in the database who are already created\n",
"and are not following themselves. If the database is small and easy to regenerate, then\n",
"it can be deleted and re-created, but if that is not an option, then adding an update\n",
"function that fixes existing users is the proper solution. This is shown in\n",
"Example 12-11.\n",
"Example 12-11. app/models.py: making users their own followers\n",
"class User(UserMixin, db.Model):\n",
" # ...\n",
" @staticmethod\n",
" def add_self_follows():\n",
" for user in User.query.all():\n",
" if not user.is_following(user):\n",
" user.follow(user)\n",
" db.session.add(user)\n",
" db.session.commit()\n",
" # ...\n",
"Now the database can be updated by running the previous example function from the\n",
"shell:\n",
"(venv) $ flask shell\n",
">>> User.add_self_follows()\n",
"186 \n",
"| \n",
"Chapter 12: Followers\n",
"\n",
"Creating functions that introduce updates to the database is a common technique\n",
"used to update applications that are deployed, as running a scripted update is less\n",
"error prone than updating databases manually. In Chapter 17 you will see how this\n",
"function and others like it can be incorporated into a deployment script.\n",
"Making all users self-followers makes the application more usable, but this change\n",
"introduces a few complications. The follower and followed user counts shown in the\n",
"user profile page are now increased by one due to the self-follower links. The num‐\n",
"bers need to be decreased by one to be accurate, which is easy to do directly in the\n",
"template \n",
"by \n",
"rendering \n",
"{{ \n",
"user.followers.count() \n",
"- \n",
"1 \n",
"}} \n",
"and\n",
"{{ user.followed.count() - 1 }}. The lists of followers and followed users also\n",
"must be adjusted to not show the same user, another simple task to do in the template\n",
"with a conditional. Finally, any unit tests that check follower counts are also affected\n",
"by the self-follower links and must be adjusted to account for the self-followers.\n",
"If you have cloned the application’s Git repository on GitHub, you\n",
"can run git checkout 12e to check out this version of the applica‐\n",
"tion.\n",
"In the next chapter, the user comment subsystem will be implemented—another very\n",
"important feature of socially aware applications.\n",
"Showing Followed Posts on the Home Page \n",
"| \n",
"187\n",
"\n",
"\n",
"CHAPTER 13\n",
"User Comments\n",
"Allowing users to interact is key to the success of a social blogging platform. In this\n",
"chapter, you will learn how to implement user comments. The techniques presented\n",
"are generic enough to be directly applicable to a large number of socially enabled\n",
"applications.\n",
"Database Representation of Comments\n",
"Comments are not very different from blog posts. Both have a body, an author, and a\n",
"timestamp, and in this particular implementation both are written with Markdown\n",
"syntax. Figure 13-1 shows a diagram of the comments table and its relationships with\n",
"other tables in the database.\n",
"Figure 13-1. Database representation of blog post comments\n",
"Comments apply to specific blog posts, so a one-to-many relationship from the posts\n",
"table is defined. This relationship can be used to obtain the list of comments associ‐\n",
"ated with a particular blog post.\n",
"The comments table is also in a one-to-many relationship with the users table. This\n",
"relationship gives access to all the comments made by a user, and indirectly how\n",
"189\n",
"\n",
"many comments a user has written, a piece of information that can be interesting to\n",
"show in user profile pages. The definition of the Comment model is shown in\n",
"Example 13-1.\n",
"Example 13-1. app/models.py: comment model\n",
"class Comment(db.Model):\n",
" __tablename__ = 'comments'\n",
" id = db.Column(db.Integer, primary_key=True)\n",
" body = db.Column(db.Text)\n",
" body_html = db.Column(db.Text)\n",
" timestamp = db.Column(db.DateTime, index=True, default=datetime.utcnow)\n",
" disabled = db.Column(db.Boolean)\n",
" author_id = db.Column(db.Integer, db.ForeignKey('users.id'))\n",
" post_id = db.Column(db.Integer, db.ForeignKey('posts.id'))\n",
" @staticmethod\n",
" def on_changed_body(target, value, oldvalue, initiator):\n",
" allowed_tags = ['a', 'abbr', 'acronym', 'b', 'code', 'em', 'i',\n",
" 'strong']\n",
" target.body_html = bleach.linkify(bleach.clean(\n",
" markdown(value, output_format='html'),\n",
" tags=allowed_tags, strip=True))\n",
"db.event.listen(Comment.body, 'set', Comment.on_changed_body)\n",
"The attributes of the Comment model are almost the same as those of Post. One addi‐\n",
"tion is the disabled field, a Boolean that will be used by moderators to suppress com‐\n",
"ments that are inappropriate or offensive. Like blog posts, comments define an event\n",
"that triggers any time the body field changes, automating the rendering of the Mark‐\n",
"down text to HTML. The process is identical to what was done for blog posts in\n",
"Chapter 11, but since comments tend to be short, the list of HTML tags that are\n",
"allowed in the conversion from Markdown is more restrictive, the paragraph-related\n",
"tags have been removed, and only the character formatting tags are left.\n",
"To complete the database changes, the User and Post models must define the one-to-\n",
"many relationships with the comments table, as shown in Example 13-2.\n",
"Example 13-2. app/models.py: one-to-many relationships from users and posts to\n",
"comments\n",
"class User(db.Model):\n",
" # ...\n",
" comments = db.relationship('Comment', backref='author', lazy='dynamic')\n",
"class Post(db.Model):\n",
" # ...\n",
" comments = db.relationship('Comment', backref='post', lazy='dynamic')\n",
"190 \n",
"| \n",
"Chapter 13: User Comments\n",
"\n",
"Comment Submission and Display\n",
"In this application, comments are displayed on the individual blog post pages that\n",
"were added as permanent links in Chapter 11. A submission form is also included on\n",
"these pages. Example 13-3 shows the web form that will be used to enter comments—\n",
"an extremely simple form that only has a text field and a submit button.\n",
"Example 13-3. app/main/forms.py: comment input form\n",
"class CommentForm(FlaskForm):\n",
" body = StringField('', validators=[DataRequired()])\n",
" submit = SubmitField('Submit')\n",
"Example 13-4 shows the updated /post/<int:id> route with support for comments.\n",
"Example 13-4. app/main/views.py: blog post comments support\n",
"@main.route('/post/<int:id>', methods=['GET', 'POST'])\n",
"def post(id):\n",
" post = Post.query.get_or_404(id)\n",
" form = CommentForm()\n",
" if form.validate_on_submit():\n",
" comment = Comment(body=form.body.data,\n",
" post=post,\n",
" author=current_user._get_current_object())\n",
" db.session.add(comment)\n",
" db.session.commit()\n",
" flash('Your comment has been published.')\n",
" return redirect(url_for('.post', id=post.id, page=-1))\n",
" page = request.args.get('page', 1, type=int)\n",
" if page == -1:\n",
" page = (post.comments.count() - 1) // \\\n",
" current_app.config['FLASKY_COMMENTS_PER_PAGE'] + 1\n",
" pagination = post.comments.order_by(Comment.timestamp.asc()).paginate(\n",
" page, per_page=current_app.config['FLASKY_COMMENTS_PER_PAGE'],\n",
" error_out=False)\n",
" comments = pagination.items\n",
" return render_template('post.html', posts=[post], form=form,\n",
" comments=comments, pagination=pagination)\n",
"This view function instantiates the comment form and sends it to the post.html tem‐\n",
"plate for rendering. The logic that inserts a new comment when the form is submitted\n",
"is similar to the handling of blog posts. As in the Post case, the author of the com‐\n",
"ment cannot be set directly to current_user because this is a context variable proxy\n",
"object. The expression current_user._get_current_object() returns the actual\n",
"User object.\n",
"Comment Submission and Display \n",
"| \n",
"191\n",
"\n",
"The comments are sorted by their timestamp in chronological order, so new com‐\n",
"ments are always added at the bottom of the list. When a new comment is entered,\n",
"the redirect that ends the request goes back to the same URL, but the url_for()\n",
"function sets the page to -1, a special page number that is used to request the last\n",
"page of comments so that the comment just entered is seen on the page. When the\n",
"page number is obtained from the query string and found to be -1, a calculation with\n",
"the number of comments and the page size is done to obtain the actual page number\n",
"to use.\n",
"The list of comments associated with the post is obtained through the post.comments\n",
"one-to-many relationship, sorted by comment timestamp, and paginated with the\n",
"same techniques used for blog posts. The comments and the pagination object are\n",
"sent to the template for rendering. The FLASKY_COMMENTS_PER_PAGE configuration\n",
"variable is added to config.py to control the size of each page of comments.\n",
"The comment rendering is defined in a new template, _comments.html, that is similar\n",
"to _posts.html but uses a different set of CSS classes. This template is included by\n",
"_posts.html below the body of the post, followed by a call to the pagination macro.\n",
"You can review the changes to the templates in the application’s GitHub repository.\n",
"To complete this feature, blog posts shown on the home and profile pages need links\n",
"to the pages with the comments. This is shown in Example 13-5.\n",
"Example 13-5. _app/templates/_posts.html: link to blog post comments\n",
"<a href=\"{{ url_for('.post', id=post.id) }}#comments\">\n",
" <span class=\"label label-primary\">\n",
" {{ post.comments.count() }} Comments\n",
" </span>\n",
"</a>\n",
"Note how the text of the link includes the number of comments, which is easily\n",
"obtained from the one-to-many relationship between the posts and comments tables\n",
"using SQLAlchemy’s count() filter.\n",
"Also of interest is the structure of the link to the comments page, which is built as the\n",
"permanent link for the post with a #comments suffix added. This last part is called a\n",
"URL fragment and is used to indicate an initial scroll position for the page. The web\n",
"browser looks for an element with the id given and scrolls the page so that element\n",
"appears at the top of the page. This initial position is set to the “Comments” heading\n",
"in the post.html template, which is written as <h4 id=\"comments\">Comments</h4>.\n",
"Figure 13-2 shows how the comments appear on the page.\n",
"192 \n",
"| \n",
"Chapter 13: User Comments\n",
"\n",
"Figure 13-2. Blog post comments\n",
"An additional change was made to the pagination macro. The pagination links for\n",
"comments also need the #comments fragment added, so a fragment argument was\n",
"added to the macro and passed in the macro invocation from the post.html template.\n",
"If you have cloned the application’s Git repository on GitHub, you\n",
"can run git checkout 13a to check out this version of the applica‐\n",
"tion. This update contains a database migration, so remember to\n",
"run flask db upgrade after you check out the code.\n",
"Comment Moderation\n",
"In Chapter 9 a list of user roles was defined, each with a list of permissions. One of\n",
"the permissions was Permission.MODERATE, which gives users who have it in their\n",
"roles the power to moderate comments made by others.\n",
"This feature will be exposed as a link in the navigation bar that appears only to users\n",
"who are permitted to use it. This is done in the base.html template using a condi‐\n",
"tional, as shown in Example 13-6.\n",
"Comment Moderation \n",
"| \n",
"193\n",
"\n",
"Example 13-6. app/templates/base.html: Moderate Comments link in navigation bar\n",
"...\n",
"{% if current_user.can(Permission.MODERATE) %}\n",
"<li><a href=\"{{ url_for('main.moderate') }}\">Moderate Comments</a></li>\n",
"{% endif %}\n",
"...\n",
"The moderation page shows the comments for all the posts in the same list, with the\n",
"most recent comments shown first. Below each comment is a button that can toggle\n",
"the disabled attribute. The /moderate route is shown in Example 13-7.\n",
"Example 13-7. app/main/views.py: comment moderation route\n",
"@main.route('/moderate')\n",
"@login_required\n",
"@permission_required(Permission.MODERATE)\n",
"def moderate():\n",
" page = request.args.get('page', 1, type=int)\n",
" pagination = Comment.query.order_by(Comment.timestamp.desc()).paginate(\n",
" page, per_page=current_app.config['FLASKY_COMMENTS_PER_PAGE'],\n",
" error_out=False)\n",
" comments = pagination.items\n",
" return render_template('moderate.html', comments=comments,\n",
" pagination=pagination, page=page)\n",
"This is a very simple function that reads a page of comments from the database and\n",
"passes them on to a template for rendering. Along with the comments, the template\n",
"receives the pagination object and the current page number.\n",
"The moderate.html template, shown in Example 13-8, is also simple because it relies\n",
"on the _comments.html subtemplate created earlier for the rendering of the com‐\n",
"ments.\n",
"Example 13-8. app/templates/moderate.html: comment moderation template\n",
"{% extends \"base.html\" %}\n",
"{% import \"_macros.html\" as macros %}\n",
"{% block title %}Flasky - Comment Moderation{% endblock %}\n",
"{% block page_content %}\n",
"<div class=\"page-header\">\n",
" <h1>Comment Moderation</h1>\n",
"</div>\n",
"{% set moderate = True %}\n",
"{% include '_comments.html' %}\n",
"{% if pagination %}\n",
"<div class=\"pagination\">\n",
"194 \n",
"| \n",
"Chapter 13: User Comments\n",
"\n",
" {{ macros.pagination_widget(pagination, '.moderate') }}\n",
"</div>\n",
"{% endif %}\n",
"{% endblock %}\n",
"This template defers the rendering of the comments to the _comments.html template,\n",
"but before it hands control to the subordinate template it uses Jinja2’s set directive to\n",
"define a moderate template variable set to True. This variable is used by the _com‐\n",
"ments.html template to determine whether the moderation features need to be ren‐\n",
"dered.\n",
"The portion of the _comments.html template that renders the body of each comment\n",
"needs to be modified in two ways. For regular users (when the moderate variable is\n",
"not set), any comments that are marked as disabled should be suppressed. For mod‐\n",
"erators (when moderate is set to True), the body of the comment must be rendered\n",
"regardless of the disabled state, and below the body a button should be included to\n",
"toggle the state. Example 13-9 shows these changes.\n",
"Example 13-9. app/templates/_comments.html: rendering of the comment bodies\n",
"...\n",
"<div class=\"comment-body\">\n",
" {% if comment.disabled %}\n",
" <p></p><i>This comment has been disabled by a moderator.</i></p>\n",
" {% endif %}\n",
" {% if moderate or not comment.disabled %}\n",
" {% if comment.body_html %}\n",
" {{ comment.body_html | safe }}\n",
" {% else %}\n",
" {{ comment.body }}\n",
" {% endif %}\n",
" {% endif %}\n",
"</div>\n",
"{% if moderate %}\n",
" <br>\n",
" {% if comment.disabled %}\n",
" <a class=\"btn btn-default btn-xs\" href=\"{{ url_for('.moderate_enable',\n",
" id=comment.id, page=page) }}\">Enable</a>\n",
" {% else %}\n",
" <a class=\"btn btn-danger btn-xs\" href=\"{{ url_for('.moderate_disable',\n",
" id=comment.id, page=page) }}\">Disable</a>\n",
" {% endif %}\n",
"{% endif %}\n",
"...\n",
"With these changes, users will see a short notice for disabled comments. Moderators\n",
"will see both the notice and the comment body. Moderators will also see a button to\n",
"toggle the disabled state below each comment. The button invokes one of two new\n",
"Comment Moderation \n",
"| \n",
"195\n",
"\n",
"routes, depending on which of the two possible states the comment is changing to.\n",
"Example 13-10 shows how these routes are defined.\n",
"Example 13-10. app/main/views.py: comment moderation routes\n",
"@main.route('/moderate/enable/<int:id>')\n",
"@login_required\n",
"@permission_required(Permission.MODERATE)\n",
"def moderate_enable(id):\n",
" comment = Comment.query.get_or_404(id)\n",
" comment.disabled = False\n",
" db.session.add(comment)\n",
" return redirect(url_for('.moderate',\n",
" page=request.args.get('page', 1, type=int)))\n",
"@main.route('/moderate/disable/<int:id>')\n",
"@login_required\n",
"@permission_required(Permission.MODERATE)\n",
"def moderate_disable(id):\n",
" comment = Comment.query.get_or_404(id)\n",
" comment.disabled = True\n",
" db.session.add(comment)\n",
" return redirect(url_for('.moderate',\n",
" page=request.args.get('page', 1, type=int)))\n",
"The comment enable and disable routes load the comment object, set the disabled\n",
"field to the proper value, and write it back to the database. At the end, they redirect\n",
"back to the comment moderation page (shown in Figure 13-3), and if a page argu‐\n",
"ment was given in the query string, they include it in the redirect. The buttons in the\n",
"_comments.html template are rendered with the page argument so that the redirect\n",
"brings the user back to the same page.\n",
"196 \n",
"| \n",
"Chapter 13: User Comments\n",
"\n",
"Figure 13-3. Comment moderation page\n",
"If you have cloned the application’s Git repository on GitHub, you\n",
"can run git checkout 13b to check out this version of the applica‐\n",
"tion.\n",
"The topic of social features is completed with this chapter. In the next chapter, you\n",
"will learn how to expose the application functionality as an API that clients such as\n",
"smartphone apps can use.\n",
"Comment Moderation \n",
"| \n",
"197\n",
"\n",
"\n",
"CHAPTER 14\n",
"Application Programming Interfaces\n",
"In recent years, there has been a trend in web applications to move more and more of\n",
"the business logic to the client side, producing an architecture that is known as Rich\n",
"Internet Applications (RIAs). In RIAs, the server’s main (and sometimes only) func‐\n",
"tion is to provide the client application with data retrieval and storage services. In this\n",
"model, the server becomes a web service or application programming interface (API).\n",
"There are several protocols by which RIAs can communicate with a web service.\n",
"Remote procedure call (RPC) protocols such as XML-RPC or its derivative, the Sim‐\n",
"plified Object Access Protocol (SOAP), were popular choices a few years ago. More\n",
"recently, the Representational State Transfer (REST) architecture has emerged as the\n",
"favorite for web applications due to its being built on the familiar model of the World\n",
"Wide Web.\n",
"Flask is an ideal framework to build RESTful web services, thanks to its lightweight\n",
"nature. In this chapter, you will learn how to implement a Flask-based RESTful API.\n",
"Introduction to REST\n",
"Roy Fielding’s PhD dissertation describes the REST architectural style for web serv‐\n",
"ices in terms of its six defining characteristics:\n",
"Client–server\n",
"There must be a clear separation between clients and servers.\n",
"Stateless\n",
"A client request must contain all the information that is necessary to carry it out.\n",
"The server must not store any state about the client that persists from one request\n",
"to the next.\n",
"199\n",
"\n",
"Cache\n",
"Responses from the server can be labeled as cacheable or noncacheable so that\n",
"clients (or intermediaries between clients and servers) can use a cache for optimi‐\n",
"zation purposes.\n",
"Uniform interface\n",
"The protocol by which clients access server resources must be consistent, well\n",
"defined, and standardized. This is the most complex aspect of REST, covering the\n",
"use of unique resource identifiers, resource representations, self-descriptive mes‐\n",
"sages between client and server, and hypermedia.\n",
"Layered system\n",
"Proxy servers, caches, or gateways can be inserted between clients and servers as\n",
"necessary to improve performance, reliability, and scalability.\n",
"Code-on-demand\n",
"Clients can optionally download code from the server to execute in their context.\n",
"Resources Are Everything\n",
"The concept of resources is core to the REST architectural style. In this context, a\n",
"resource is an item of interest in the domain of the application. For example, in the\n",
"blogging application, users, blog posts, and comments are all resources.\n",
"Each resource must have a unique identifier that represents it. When working with\n",
"HTTP, identifiers for resources are URLs. Continuing with the blogging example, a\n",
"blog post could be represented by the URL /api/posts/12345, where 12345 is the iden‐\n",
"tifier for a post, such as the post’s database primary key. The format or contents of the\n",
"URL do not really matter; all that matters is that each resource URL uniquely identi‐\n",
"fies a resource.\n",
"A collection of all the resources in a class also has an assigned URL. The URL for the\n",
"collection of blog posts could be /api/posts/ and the URL for the collection of all com‐\n",
"ments could be /api/comments/.\n",
"An API can also define collection URLs that represent logical subsets of all the\n",
"resources in a class. For example, the collection of all comments in blog post 12345\n",
"could be represented by the URL /api/posts/12345/comments/. It is common to define\n",
"URLs that represent collections of resources with a trailing slash, as this gives them a\n",
"“subdirectory” representation.\n",
"Be aware that Flask applies special treatment to routes that end\n",
"with a slash. If a client requests a URL without a trailing slash and\n",
"there is a matching route that has a slash at the end, then Flask will\n",
"automatically respond with a redirect to the trailing-slash URL. No\n",
"redirects are issued for the reverse case.\n",
"200 \n",
"| \n",
"Chapter 14: Application Programming Interfaces\n",
"\n",
"Request Methods\n",
"The client application sends requests to the server at the established resource URLs\n",
"and uses the request method to indicate the desired operation. To obtain the list of\n",
"available blog posts in the blogging API the client would send a GET request to http://\n",
"www.example.com/api/posts/, and to insert a new blog post it would send a POST\n",
"request to the same URL, with the contents of the blog post in the request body. To\n",
"retrieve blog post 12345 the client would send a GET request to http://www.exam‐\n",
"ple.com/api/posts/12345. Table 14-1 lists the request methods that are commonly used\n",
"in RESTful APIs, with their meanings.\n",
"Table 14-1. HTTP request methods in RESTful APIs\n",
"Request\n",
"method\n",
"Target\n",
"Description\n",
"HTTP response\n",
"status code\n",
"GET\n",
"Individual resource URL\n",
"Obtain the resource.\n",
"200\n",
"GET\n",
"Resource collection URL Obtain the collection of resources (or one page from it if the\n",
"server implements pagination).\n",
"200\n",
"POST\n",
"Resource collection URL Create a new resource and add it to the collection. The server\n",
"chooses the URL of the new resource and returns it in a\n",
"Location header in the response.\n",
"201\n",
"PUT\n",
"Individual resource URL\n",
"Modify an existing resource. Alternatively, this method can also\n",
"be used to create a new resource when the client can choose the\n",
"resource URL.\n",
"200 or 204\n",
"DELETE\n",
"Individual resource URL\n",
"Delete a resource.\n",
"200 or 204\n",
"DELETE\n",
"Resource collection URL Delete all resources in the collection.\n",
"200 or 204\n",
"The REST architecture does not require that all methods be imple‐\n",
"mented for a resource. If the client invokes a method that is not\n",
"supported for a given resource, then a response with the 405 status\n",
"code (Method Not Allowed) should be returned. Flask handles this\n",
"error automatically.\n",
"The GET, POST, PUT, and DELETE request methods are not the only ones. The HTTP\n",
"protocol relies on other methods, such as HEAD and OPTIONS, which are automatically\n",
"implemented by Flask.\n",
"Request and Response Bodies\n",
"Resources are sent back and forth between client and server in the bodies of requests\n",
"and responses, but REST does not specify the format to use to encode resources. The\n",
"Content-Type header in requests and responses is used to indicate the format in\n",
"which a resource is encoded in the body. The standard content negotiation mecha‐\n",
"Introduction to REST \n",
"| \n",
"201\n",
"\n",
"nisms in the HTTP protocol can be used between client and server to agree on a for‐\n",
"mat that both support.\n",
"The two formats commonly used with RESTful web services are JavaScript Object\n",
"Notation (JSON) and Extensible Markup Language (XML). For web-based RIAs,\n",
"JSON is attractive due to being much more concise than XML, and because of its\n",
"close ties to JavaScript, the client-side scripting language used by web browsers.\n",
"Returning to the blog example API, a blog post resource could have the following\n",
"JSON representation:\n",
"{\n",
" \"self_url\": \"http://www.example.com/api/posts/12345\",\n",
" \"title\": \"Writing RESTful APIs in Python\",\n",
" \"author_url\": \"http://www.example.com/api/users/2\",\n",
" \"body\": \"... text of the article here ...\",\n",
" \"comments_url\": \"http://www.example.com/api/posts/12345/comments\"\n",
"}\n",
"Note how the url, author_url, and comments_url fields are fully qualified resource\n",
"URLs. This is important because these URLs allow the client to discover new resour‐\n",
"ces.\n",
"In a well-designed RESTful API, the client knows a short list of top-level resource\n",
"URLs and then discovers the rest from links included in responses, similar to how\n",
"you can discover new web pages while browsing the web by clicking on links that\n",
"appear in pages that you know about.\n",
"Versioning\n",
"In a traditional server-centric web application, the server has full control of the appli‐\n",
"cation. When an application is updated, installing the new version on the server is\n",
"enough to update all users because even the parts of the application that run in the\n",
"user’s web browser are downloaded from the server.\n",
"The situation with RIAs and web services is more complicated, because often clients\n",
"are developed independently of the server—maybe even by different people. Consider\n",
"the case of an application where the RESTful web service is used by a variety of clients\n",
"including web browsers and native smartphone clients. The web browser client can\n",
"be updated on the server at any time, but the smartphone apps cannot be updated by\n",
"force; the smartphone owner needs to allow the update to happen. Even if the smart‐\n",
"phone owner is willing to update, it is not possible to orchestrate the upgrade of all\n",
"existing instances of smartphone applications to coincide exactly with the deploy‐\n",
"ment of the new server version.\n",
"For these reasons, web services need to be more tolerant than regular web applica‐\n",
"tions and be able to work with old versions of their clients. Changes to a web service\n",
"must be done with extreme care, because backward-incompatible changes can cause\n",
"202 \n",
"| \n",
"Chapter 14: Application Programming Interfaces\n",
"\n",
"existing clients to break until they are upgraded. A common practice is to give web\n",
"services a version, which is added to all URLs defined in that version of the server\n",
"application. For example, the first release of the blogging web service could expose\n",
"the collection of blog posts at /api/v1/posts/.\n",
"Including the web service version in the URL helps keep old and new features organ‐\n",
"ized so that the server can provide new features to new clients while continuing to\n",
"support old clients. An update to the blogging service could change the JSON format\n",
"of blog posts and now expose blog posts as /api/v2/posts/, while keeping the older\n",
"JSON format for clients that connect to /api/v1/posts/.\n",
"Although supporting multiple versions of the server can become a maintenance bur‐\n",
"den, there are situations in which this is the only way to allow the application to grow\n",
"without causing problems to existing deployments. Older service versions can be\n",
"deprecated and later removed, once all clients have migrated to a newer version.\n",
"RESTful Web Services with Flask\n",
"Flask makes it very easy to create RESTful web services. The familiar route() decora‐\n",
"tor along with its methods optional argument can be used to declare the routes that\n",
"handle the resource URLs exposed by the service. Working with JSON data is also\n",
"simple, as JSON data included with a request can be obtained in dictionary format by\n",
"calling request.get_json(), and a response that needs to contain JSON can be easily\n",
"generated from a Python dictionary using Flask’s jsonify() helper function.\n",
"The following sections show how Flasky can be extended with a RESTful web service\n",
"that gives clients access to blog posts and related resources.\n",
"Creating an API Blueprint\n",
"The routes associated with a RESTful API form a self-contained subset of the applica‐\n",
"tion, so putting them in their own blueprint is the best way to keep them well organ‐\n",
"ized. The general structure of the API blueprint within the application is shown in\n",
"Example 14-1.\n",
"Example 14-1. API blueprint structure\n",
"|-flasky\n",
" |-app/\n",
" |-api\n",
" |-__init__.py\n",
" |-users.py\n",
" |-posts.py\n",
" |-comments.py\n",
" |-authentication.py\n",
" |-errors.py\n",
" |-decorators.py\n",
"RESTful Web Services with Flask \n",
"| \n",
"203\n",
"\n",
"Note how the package used for the API includes a version number in its name. If in\n",
"the future a backward-incompatible version of the API needs to be introduced, it can\n",
"be added as a separate package with a different version number and both APIs can be\n",
"included in the application.\n",
"The API blueprint implements each resource in a separate module. Modules to take\n",
"care of authentication and error handling and to provide custom decorators are also\n",
"included. The blueprint constructor is shown in Example 14-2.\n",
"Example 14-2. app/api/__init__.py: API blueprint creation\n",
"from flask import Blueprint\n",
"api = Blueprint('api', __name__)\n",
"from . import authentication, posts, users, comments, errors\n",
"The structure of the blueprint package constructor is similar to that of the other blue‐\n",
"prints. Importing all the components of the blueprint is necessary so that routes and\n",
"other handlers are registered. Since many of these modules need to import the api\n",
"blueprint referenced here, the imports are done at the bottom to help prevent errors\n",
"due to circular dependencies.\n",
"The registration of the API blueprint is shown in Example 14-3.\n",
"Example 14-3. app/init.py: API blueprint registration\n",
"def create_app(config_name):\n",
" # ...\n",
" from .api import api as api_blueprint\n",
" app.register_blueprint(api_blueprint, url_prefix='/api/v1')\n",
" # ...\n",
"The API blueprint is registered with a URL prefix, so that all its routes will have their\n",
"URLs prefixed with /api/v1. Adding a prefix when registering the blueprint is a good\n",
"idea because it eliminates the need to hardcode the version number in every blueprint\n",
"route.\n",
"Error Handling\n",
"A RESTful web service informs the client of the status of a request by sending the\n",
"appropriate HTTP status code in the response, plus any additional information in the\n",
"response body. The typical status codes that a client can expect to see from a web ser‐\n",
"vice are listed in Table 14-2.\n",
"204 \n",
"| \n",
"Chapter 14: Application Programming Interfaces\n",
"\n",
"Table 14-2. HTTP response status codes typically returned by APIs\n",
"HTTP\n",
"status\n",
"code\n",
"Name\n",
"Description\n",
"200\n",
"OK\n",
"The request was completed successfully.\n",
"201\n",
"Created\n",
"The request was completed successfully and a new resource was created as a result.\n",
"202\n",
"Accepted\n",
"The request was accepted for processing, but it is still in progress and will run\n",
"asynchronously.\n",
"204\n",
"No Content\n",
"The request was completed successfully and there is no data to return in the response.\n",
"400\n",
"Bad Request\n",
"The request is invalid or inconsistent.\n",
"401\n",
"Unauthorized\n",
"The request does not include authentication information or the credentials provided are\n",
"invalid.\n",
"403\n",
"Forbidden\n",
"The authentication credentials sent with the request are insufficient for the request.\n",
"404\n",
"Not Found\n",
"The resource referenced in the URL was not found.\n",
"405\n",
"Method Not Allowed The method requested is not supported for the given resource.\n",
"500\n",
"Internal Server Error\n",
"An unexpected error occurred while processing the request.\n",
"The handling of status codes 404 and 500 presents a small complication, in that these\n",
"errors are normally generated by Flask on its own, and will return an HTML\n",
"response. This can confuse an API client, which will likely expect all responses in\n",
"JSON format.\n",
"One way to generate appropriate responses for all clients is to make the error han‐\n",
"dlers adapt their responses based on the format requested by the client, a technique\n",
"called content negotiation. Example 14-4 shows an improved 404 error handler that\n",
"responds with JSON to web service clients and with HTML to others. The 500 error\n",
"handler is written in a similar way.\n",
"Example 14-4. app/api/errors.py: 404 error handler with HTTP content negotiation\n",
"@main.app_errorhandler(404)\n",
"def page_not_found(e):\n",
" if request.accept_mimetypes.accept_json and \\\n",
" not request.accept_mimetypes.accept_html:\n",
" response = jsonify({'error': 'not found'})\n",
" response.status_code = 404\n",
" return response\n",
" return render_template('404.html'), 404\n",
"This new version of the error handler checks the Accept request header, which is\n",
"decoded into request.accept_mimetypes, to determine what format the client wants\n",
"the response in. Browsers generally do not specify any restrictions on response for‐\n",
"mats, but API clients typically do. The JSON response is generated only for clients\n",
"that include JSON in their list of accepted formats, but not HTML.\n",
"RESTful Web Services with Flask \n",
"| \n",
"205\n",
"\n",
"The remaining status codes are generated explicitly by the web service, so they can be\n",
"implemented as helper functions inside the blueprint in the errors.py module.\n",
"Example 14-5 shows the implementation of the 403 error; the others are similar.\n",
"Example 14-5. app/api/errors.py: API error handler for status code 403\n",
"def forbidden(message):\n",
" response = jsonify({'error': 'forbidden', 'message': message})\n",
" response.status_code = 403\n",
" return response\n",
"View functions in the API blueprint can invoke these auxiliary functions to generate\n",
"error responses when necessary.\n",
"User Authentication with Flask-HTTPAuth\n",
"Web services, like regular web applications, need to protect information and ensure\n",
"that it is not given to unauthorized parties. For this reason, RIAs must ask their users\n",
"for login credentials and pass them to the server for verification.\n",
"It was mentioned earlier that one of the characteristics of RESTful web services is that\n",
"they are stateless, which means that the server is not allowed to “remember” anything\n",
"about the client between requests. Clients need to provide all the information neces‐\n",
"sary to carry out a request in the request itself, so all requests must include user cre‐\n",
"dentials.\n",
"The current login functionality implemented with the help of Flask-Login stores data\n",
"in the user session, which Flask stores by default in a client-side cookie, so the server\n",
"does not store any user-related information; it asks the client to store it instead. It\n",
"would appear that this implementation complies with the stateless requirement of\n",
"REST, but the use of cookies in RESTful web services falls into a gray area, as it can be\n",
"cumbersome for clients that are not web browsers to implement them. For that rea‐\n",
"son, it is generally seen as a bad design choice to use cookies in APIs.\n",
"The stateless requirement of REST may seem overly strict, but it is\n",
"not arbitrary. Stateless servers can scale very easily. If servers store\n",
"information about clients, it is necessary to ensure that the same\n",
"server always gets requests from a given client, or else to use shared\n",
"storage for client data. Both are complex problems to solve that do\n",
"not exist when the server is stateless.\n",
"Because the RESTful architecture is based on the HTTP protocol, HTTP authentica‐\n",
"tion is the preferred method used to send credentials, either in its Basic or Digest fla‐\n",
"vor. With HTTP authentication, user credentials are included in an Authorization\n",
"header with all requests.\n",
"206 \n",
"| \n",
"Chapter 14: Application Programming Interfaces\n",
"\n",
"The HTTP authentication protocol is simple enough that it can be implemented\n",
"directly, but the Flask-HTTPAuth extension provides a convenient wrapper that hides\n",
"the protocol details in a decorator similar to Flask-Login’s login_required.\n",
"Flask-HTTPAuth is installed with pip:\n",
"(venv) $ pip install flask-httpauth\n",
"To initialize the extension for HTTP Basic authentication, an object of class\n",
"HTTPBasicAuth must be created. Like Flask-Login, Flask-HTTPAuth makes no\n",
"assumptions about the procedure required to verify user credentials, so this informa‐\n",
"tion is given in a callback function. Example 14-6 shows how the extension is initial‐\n",
"ized and provided with a verification callback.\n",
"Example 14-6. app/api/authentication.py: Flask-HTTPAuth initialization\n",
"from flask_httpauth import HTTPBasicAuth\n",
"auth = HTTPBasicAuth()\n",
"@auth.verify_password\n",
"def verify_password(email, password):\n",
" if email == '':\n",
" return False\n",
" user = User.query.filter_by(email = email).first()\n",
" if not user:\n",
" return False\n",
" g.current_user = user\n",
" return user.verify_password(password)\n",
"Because this type of user authentication will be used only in the API blueprint, the\n",
"Flask-HTTPAuth extension is initialized in the blueprint package, and not in the\n",
"application package like other extensions.\n",
"The email and password are verified using the existing support in the User model.\n",
"The verification callback returns True when the login is valid and False otherwise.\n",
"The Flask-HTTPAuth extension also will invoke the callback for requests that carry\n",
"no authentication, setting both arguments to the empty string. In this case, when\n",
"email is an empty string, the function immediately returns False to block the\n",
"request; for certain applications it may be acceptable to allow the anonymous user by\n",
"returning True. The authentication callback saves the authenticated user in Flask’s g\n",
"context variable so that the view function can access it later.\n",
"Because user credentials are being exchanged with every request, it\n",
"is extremely important that the API routes are exposed over secure\n",
"HTTP so that all requests and responses are encrypted in transit.\n",
"RESTful Web Services with Flask \n",
"| \n",
"207\n",
"\n",
"When the authentication credentials are invalid, the server returns a 401 status code\n",
"response to the client. Flask-HTTPAuth generates a response with this status code by\n",
"default, but to ensure that the response is consistent with other errors returned by the\n",
"API, the error response can be customized as shown in Example 14-7.\n",
"Example 14-7. _app/api/authentication.py: Flask-HTTPAuth error handler\n",
"from .errors import unauthorized\n",
"@auth.error_handler\n",
"def auth_error():\n",
" return unauthorized('Invalid credentials')\n",
"To protect a route, the auth.login_required decorator is used:\n",
"@api.route('/posts/')\n",
"@auth.login_required\n",
"def get_posts():\n",
" pass\n",
"But since all the routes in the blueprint need to be protected in the same way, the\n",
"login_required decorator can be included once in a before_request handler for the\n",
"blueprint, as shown in Example 14-8.\n",
"Example 14-8. app/api/authentication.py: before_request handler with authentication\n",
"from .errors import forbidden\n",
"@api.before_request\n",
"@auth.login_required\n",
"def before_request():\n",
" if not g.current_user.is_anonymous and \\\n",
" not g.current_user.confirmed:\n",
" return forbidden('Unconfirmed account')\n",
"Now the authentication checks will be done automatically for all the routes in the\n",
"blueprint. As an additional check, the before_request handler also rejects authenti‐\n",
"cated users who have not confirmed their accounts.\n",
"Token-Based Authentication\n",
"Clients must send authentication credentials with every request. To avoid having to\n",
"constantly transfer sensitive information such as a password, a token-based authenti‐\n",
"cation solution can be used.\n",
"In token-based authentication, the client requests an access token by sending a\n",
"request that includes the login credentials as authentication. The token can then be\n",
"used in place of the login credentials to authenticate requests. For security reasons,\n",
"208 \n",
"| \n",
"Chapter 14: Application Programming Interfaces\n",
"\n",
"tokens are issued with an associated expiration. When a token expires, the client must\n",
"reauthenticate to get a new one. The risk of a token getting into the wrong hands is\n",
"limited due to its short lifespan. Example 14-9 shows the two new methods added to\n",
"the User model that support generation and verification of authentication tokens\n",
"using itsdangerous.\n",
"Example 14-9. app/models.py: token-based authentication support\n",
"class User(db.Model):\n",
" # ...\n",
" def generate_auth_token(self, expiration):\n",
" s = Serializer(current_app.config['SECRET_KEY'],\n",
" expires_in=expiration)\n",
" return s.dumps({'id': self.id}).decode('utf-8')\n",
" @staticmethod\n",
" def verify_auth_token(token):\n",
" s = Serializer(current_app.config['SECRET_KEY'])\n",
" try:\n",
" data = s.loads(token)\n",
" except:\n",
" return None\n",
" return User.query.get(data['id'])\n",
"The generate_auth_token() method returns a signed token that encodes the user’s\n",
"id field. An expiration time given in seconds is also used. The verify_auth_token()\n",
"method takes a token and, if it’s found to be valid, returns the user stored in it. This is\n",
"a static method, as the user will be known only after the token is decoded.\n",
"To authenticate requests that come with a token, the verify_password callback for\n",
"Flask-HTTPAuth must be modified to accept tokens as well as regular credentials. \n",
"The updated callback is shown in Example 14-10.\n",
"Example 14-10. app/api/authentication.py: improved authentication verification with\n",
"token support\n",
"@auth.verify_password\n",
"def verify_password(email_or_token, password):\n",
" if email_or_token == '':\n",
" return False\n",
" if password == '':\n",
" g.current_user = User.verify_auth_token(email_or_token)\n",
" g.token_used = True\n",
" return g.current_user is not None\n",
" user = User.query.filter_by(email=email_or_token).first()\n",
" if not user:\n",
" return False\n",
" g.current_user = user\n",
"RESTful Web Services with Flask \n",
"| \n",
"209\n",
"\n",
" g.token_used = False\n",
" return user.verify_password(password)\n",
"In this new version, the first authentication argument can be the email address or an\n",
"authentication token. If this field is blank, an anonymous user is assumed, as before.\n",
"If the password is blank, then the email_or_token field is assumed to be a token and\n",
"validated as such. If both fields are nonempty then regular email and password\n",
"authentication is assumed. With this implementation, token-based authentication is\n",
"optional; it is up to each client to use it or not. To give view functions the ability to\n",
"distinguish between the two authentication methods a g.token_used variable is\n",
"added.\n",
"The route that returns authentication tokens to the client is also added to the API\n",
"blueprint. The implementation is shown in Example 14-11.\n",
"Example 14-11. app/api/authentication.py: authentication token generation\n",
"@api.route('/tokens/', methods=['POST'])\n",
"def get_token():\n",
" if g.current_user.is_anonymous or g.token_used:\n",
" return unauthorized('Invalid credentials')\n",
" return jsonify({'token': g.current_user.generate_auth_token(\n",
" expiration=3600), 'expiration': 3600})\n",
"Since this route is in the blueprint, the authentication mechanisms added to the\n",
"before_request handler also apply to it. To prevent clients from authenticating to\n",
"this route using a previously obtained token instead of an email address and pass‐\n",
"word, the g.token_used variable is checked, and requests authenticated with a token\n",
"are rejected. The purpose of this is to prevent users from bypassing the token expira‐\n",
"tion by requesting a new token using the old token as authentication. The function\n",
"returns a token in the JSON response with a validity period of one hour. The period is\n",
"also included in the JSON response.\n",
"Serializing Resources to and from JSON\n",
"A frequent need when writing a web service is to convert internal representations of\n",
"resources to and from JSON, which is the transport format used in HTTP requests\n",
"and responses. The process of converting an internal representation to a transport\n",
"format such as JSON is called serialization. Example 14-12 shows a new to_json()\n",
"method added to the Post class.\n",
"210 \n",
"| \n",
"Chapter 14: Application Programming Interfaces\n",
"\n",
"Example 14-12. app/models.py: converting a post to a JSON serializable dictionary\n",
"class Post(db.Model):\n",
" # ...\n",
" def to_json(self):\n",
" json_post = {\n",
" 'url': url_for('api.get_post', id=self.id),\n",
" 'body': self.body,\n",
" 'body_html': self.body_html,\n",
" 'timestamp': self.timestamp,\n",
" 'author_url': url_for('api.get_user', id=self.author_id),\n",
" 'comments_url': url_for('api.get_post_comments', id=self.id),\n",
" 'comment_count': self.comments.count()\n",
" }\n",
" return json_post\n",
"The url, author_url, and comments_url fields need to return the URLs for the\n",
"respective resources, so these are generated with url_for() calls to other routes that\n",
"will be defined in the API blueprint.\n",
"This example shows how it is possible to return “made-up” attributes in the represen‐\n",
"tation of a resource. The comment_count field returns the number of comments that\n",
"exist for the blog post. Although this is not a real attribute of the model, it is included\n",
"in the resource representation as a convenience to the client.\n",
"The to_json() method for User models can be constructed in a similar way. This\n",
"method is shown in Example 14-13.\n",
"Example 14-13. app/models.py: converting a user to a JSON serializable dictionary\n",
"class User(UserMixin, db.Model):\n",
" # ...\n",
" def to_json(self):\n",
" json_user = {\n",
" 'url': url_for('api.get_user', id=self.id),\n",
" 'username': self.username,\n",
" 'member_since': self.member_since,\n",
" 'last_seen': self.last_seen,\n",
" 'posts_url': url_for('api.get_user_posts', id=self.id),\n",
" 'followed_posts_url': url_for('api.get_user_followed_posts',\n",
" id=self.id),\n",
" 'post_count': self.posts.count()\n",
" }\n",
" return json_user\n",
"Note how in this method some of the attributes of the user, such as email and role,\n",
"are omitted from the response for privacy reasons. This example again demonstrates\n",
"RESTful Web Services with Flask \n",
"| \n",
"211\n",
"\n",
"that the representation of a resource offered to clients does not need to be identical to\n",
"the internal definition of the corresponding database model.\n",
"The inverse of serialization is called deserialization. Deserializing a JSON structure\n",
"back to a model presents the challenge that some of the data coming from the client\n",
"might be invalid, wrong, or unnecessary. Example 14-14 shows the method that cre‐\n",
"ates a Post from JSON.\n",
"Example 14-14. app/models.py: creating a blog post from JSON\n",
"from app.exceptions import ValidationError\n",
"class Post(db.Model):\n",
" # ...\n",
" @staticmethod\n",
" def from_json(json_post):\n",
" body = json_post.get('body')\n",
" if body is None or body == '':\n",
" raise ValidationError('post does not have a body')\n",
" return Post(body=body)\n",
"As you can see, this implementation chooses to only use the body attribute from the\n",
"JSON dictionary. The body_html attribute is ignored since the server-side Markdown\n",
"rendering is automatically triggered by an SQLAlchemy event whenever the body\n",
"attribute is modified. The timestamp attribute does not need to be given unless the\n",
"client is allowed to back- or future-date posts, which is not a feature this application\n",
"supports. The author_url field is not used because the client has no authority to\n",
"select the author of a blog post; the only possible value for this field is that of the\n",
"authenticated user. The comments_url and comment_count attributes are automati‐\n",
"cally generated from a database relationship, so there is no useful information in\n",
"them that is needed to create a Post. Finally, the url field is ignored because in this\n",
"implementation the resource URLs are defined by the server, not the client.\n",
"Note how error checking is done. If the body field is missing or empty then a\n",
"ValidationError exception is raised. Raising an exception is in this case the appro‐\n",
"priate way to deal with the error because this method does not have enough knowl‐\n",
"edge to properly handle the error condition. The exception effectively passes the\n",
"error up to the caller, enabling higher-level code to do the error handling. The\n",
"ValidationError class is implemented as a simple subclass of Python’s ValueError.\n",
"This implementation is shown in Example 14-15.\n",
"Example 14-15. app/exceptions.py: ValidationError exception\n",
"class ValidationError(ValueError):\n",
" pass\n",
"212 \n",
"| \n",
"Chapter 14: Application Programming Interfaces\n",
"\n",
"The application now needs to handle this exception by providing the appropriate\n",
"response to the client. To avoid having to add exception-catching code in view func‐\n",
"tions, a global exception handler can be installed using Flask’s errorhandler decora‐\n",
"tor. A handler for the ValidationError exception is shown in Example 14-16.\n",
"Example 14-16. app/api/errors.py: API error handler for ValidationError exceptions\n",
"@api.errorhandler(ValidationError)\n",
"def validation_error(e):\n",
" return bad_request(e.args[0])\n",
"The errorhandler decorator is the same one that is used to register handlers for\n",
"HTTP status codes, but in this usage it takes an Exception class as an argument. The\n",
"decorated function will be invoked any time an exception of the given class is raised.\n",
"Note that the decorator is obtained from the API blueprint, so this handler will be\n",
"invoked only when the exception is raised while a route from the blueprint is being\n",
"handled. Using this technique, the code in view functions can be written very cleanly\n",
"and concisely, without the need to include error checking. For example:\n",
"@api.route('/posts/', methods=['POST'])\n",
"def new_post():\n",
" post = Post.from_json(request.json)\n",
" post.author = g.current_user\n",
" db.session.add(post)\n",
" db.session.commit()\n",
" return jsonify(post.to_json())\n",
"Implementing Resource Endpoints\n",
"What remains is to implement the routes that handle the different resources. The GET\n",
"requests are typically the easiest because they just return information and don’t need\n",
"to make any changes. Example 14-17 shows the two GET handlers for blog posts.\n",
"Example 14-17. app/api/posts.py: GET resource handlers for posts\n",
"@api.route('/posts/')\n",
"def get_posts():\n",
" posts = Post.query.all()\n",
" return jsonify({ 'posts': [post.to_json() for post in posts] })\n",
"@api.route('/posts/<int:id>')\n",
"def get_post(id):\n",
" post = Post.query.get_or_404(id)\n",
" return jsonify(post.to_json())\n",
"The first route handles the request for the collection of posts. This function uses a list\n",
"comprehension to generate the JSON version of all the posts. The second route\n",
"RESTful Web Services with Flask \n",
"| \n",
"213\n",
"\n",
"returns a single blog post and responds with a code 404 error when the given id is\n",
"not found in the database.\n",
"The POST handler for blog post resources inserts a new blog post in the database. This\n",
"route is shown in Example 14-18.\n",
"Example 14-18. app/api/posts.py: POST resource handler for posts\n",
"@api.route('/posts/', methods=['POST'])\n",
"@permission_required(Permission.WRITE)\n",
"def new_post():\n",
" post = Post.from_json(request.json)\n",
" post.author = g.current_user\n",
" db.session.add(post)\n",
" db.session.commit()\n",
" return jsonify(post.to_json()), 201, \\\n",
" {'Location': url_for('api.get_post', id=post.id)}\n",
"This view function is wrapped in a permission_required decorator (shown in an\n",
"upcoming example) that ensures that the authenticated user has the permission to\n",
"write blog posts. The actual creation of the blog post is straightforward due to the\n",
"error handling support that was implemented previously. A blog post is created from\n",
"the JSON data and its author is explicitly assigned as the authenticated user. After the\n",
"model is written to the database, a 201 status code is returned and a Location header\n",
"is added with the URL of the newly created resource.\n",
"Note that as a convenience to clients, the body of the response includes the new\n",
"resource. This will save the client from having to issue a GET request for it immedi‐\n",
"ately after creating the resource.\n",
"The permission_required decorator used to prevent unauthorized users from creat‐\n",
"ing new blog posts is similar to the one used in the application but is customized for\n",
"the API blueprint. The implementation is shown in Example 14-19.\n",
"Example 14-19. app/api/decorators.py: permission_required decorator\n",
"def permission_required(permission):\n",
" def decorator(f):\n",
" @wraps(f)\n",
" def decorated_function(*args, **kwargs):\n",
" if not g.current_user.can(permission):\n",
" return forbidden('Insufficient permissions')\n",
" return f(*args, **kwargs)\n",
" return decorated_function\n",
" return decorator\n",
"214 \n",
"| \n",
"Chapter 14: Application Programming Interfaces\n",
"\n",
"The PUT handler for blog posts, used for editing existing resources, is shown in\n",
"Example 14-20.\n",
"Example 14-20. app/api/posts.py: PUT resource handler for posts\n",
"@api.route('/posts/<int:id>', methods=['PUT'])\n",
"@permission_required(Permission.WRITE)\n",
"def edit_post(id):\n",
" post = Post.query.get_or_404(id)\n",
" if g.current_user != post.author and \\\n",
" not g.current_user.can(Permission.ADMIN):\n",
" return forbidden('Insufficient permissions')\n",
" post.body = request.json.get('body', post.body)\n",
" db.session.add(post)\n",
" db.session.commit()\n",
" return jsonify(post.to_json())\n",
"The permission checks are more complex in this case. The standard check for per‐\n",
"mission to write blog posts is done with the decorator, but to allow a user to edit a\n",
"blog post the function must also ensure that the user is the author of the post or else\n",
"is an administrator. This check is added explicitly to the view function. If this check\n",
"had to be added in many view functions, building a decorator for it would be a good\n",
"way to avoid code repetition.\n",
"Since the application does not allow deletion of posts, the handler for the DELETE\n",
"request method does not need to be implemented.\n",
"The resource handlers for users and comments are implemented in a similar way.\n",
"Table 14-3 lists the set of resources implemented for this application and the HTTP\n",
"methods each supports. The complete implementation is available for you to study in\n",
"the GitHub repository for this application.\n",
"Table 14-3. Flasky API resources\n",
"Resource URL\n",
"Method\n",
"Description\n",
"/users/<int:id>\n",
"GET\n",
"Return a user.\n",
"/users/<int:id>/posts/\n",
"GET\n",
"Return all the blog posts written by a user.\n",
"/users/<int:id>/timeline/\n",
"GET\n",
"Return all the blog posts followed by a user.\n",
"/posts/\n",
"GET\n",
"Return all the blog posts.\n",
"/posts/\n",
"POST\n",
"Create a new blog post.\n",
"/posts/<int:id>\n",
"GET\n",
"Return a blog post.\n",
"/posts/<int:id>\n",
"PUT\n",
"Modify a blog post.\n",
"/posts/<int:id>/comments/\n",
"GET\n",
"Return the comments on a blog post.\n",
"/posts/<int:id>/comments/\n",
"POST\n",
"Add a comment to a blog post.\n",
"/comments/\n",
"GET\n",
"Return all the comments.\n",
"RESTful Web Services with Flask \n",
"| \n",
"215\n",
"\n",
"Resource URL\n",
"Method\n",
"Description\n",
"/comments/<int:id>\n",
"GET\n",
"Return a comment.\n",
"Note that the resources that were implemented offer only a subset of the functionality\n",
"that is available through the web application. The list of supported resources could be\n",
"expanded if necessary, such as to expose followers, to enable comment moderation,\n",
"and to implement any other features that an API client might need.\n",
"Pagination of Large Resource Collections\n",
"The GET requests that return a collection of resources can be extremely expensive and\n",
"difficult to manage for very large collections. Like web applications, web services can\n",
"choose to paginate collections.\n",
"Example 14-21 shows a possible implementation of pagination for the list of blog\n",
"posts.\n",
"Example 14-21. app/api/posts.py: Post pagination\n",
"@api.route('/posts/')\n",
"def get_posts():\n",
" page = request.args.get('page', 1, type=int)\n",
" pagination = Post.query.paginate(\n",
" page, per_page=current_app.config['FLASKY_POSTS_PER_PAGE'],\n",
" error_out=False)\n",
" posts = pagination.items\n",
" prev = None\n",
" if pagination.has_prev:\n",
" prev = url_for('api.get_posts', page=page-1)\n",
" next = None\n",
" if pagination.has_next:\n",
" next = url_for('api.get_posts', page=page+1)\n",
" return jsonify({\n",
" 'posts': [post.to_json() for post in posts],\n",
" 'prev_url': prev,\n",
" 'next_url': next,\n",
" 'count': pagination.total\n",
" })\n",
"The posts field in the JSON response contains the data items as before, but now it is\n",
"just a page and not the complete set. The prev_url and next_url items contain the\n",
"resource URLs for the previous and following pages, or None when a page in that\n",
"direction is not available. The count value is the total number of items in the collec‐\n",
"tion.\n",
"This technique can be applied to all the routes that return collections.\n",
"216 \n",
"| \n",
"Chapter 14: Application Programming Interfaces\n",
"\n",
"If you have cloned the application’s Git repository on GitHub, you\n",
"can run git checkout 14a to check out this version of the applica‐\n",
"tion. To ensure that you have all the dependencies installed, also\n",
"run pip install -r requirements/dev.txt.\n",
"Testing Web Services with HTTPie\n",
"To test a web service, an HTTP client must be used. The two most used clients for\n",
"testing Python web services from the command line are cURL and HTTPie. While\n",
"both are useful tools, the latter has a much more concise and readable command line\n",
"syntax that is tailored specifically to API requests. HTTPie is installed with pip:\n",
"(venv) $ pip install httpie\n",
"Assuming the development server is running on the default http://127.0.0.1:5000\n",
"address, a GET request can be issued from another terminal window as follows:\n",
"(venv) $ http --json --auth <email>:<password> GET \\\n",
"> http://127.0.0.1:5000/api/v1/posts\n",
"HTTP/1.0 200 OK\n",
"Content-Length: 7018\n",
"Content-Type: application/json\n",
"Date: Sun, 22 Dec 2013 08:11:24 GMT\n",
"Server: Werkzeug/0.9.4 Python/2.7.3\n",
"{\n",
" \"posts\": [\n",
" ...\n",
" ],\n",
" \"prev_url\": null\n",
" \"next_url\": \"http://127.0.0.1:5000/api/v1/posts/?page=2\",\n",
" \"count\": 150\n",
"}\n",
"Note the pagination links included in the response. Since this is the first page, a previ‐\n",
"ous page is not defined, but a URL to obtain the next page and a total count were\n",
"returned.\n",
"The following command sends a POST request to add a new blog post:\n",
"(venv) $ http --auth <email>:<password> --json POST \\ \n",
"> http://127.0.0.1:5000/api/v1/posts/ \\ \n",
"> \"body=I'm adding a post from the *command line*.\"\n",
"HTTP/1.0 201 CREATED\n",
"Content-Length: 360\n",
"Content-Type: application/json\n",
"Date: Sun, 22 Dec 2013 08:30:27 GMT\n",
"Location: http://127.0.0.1:5000/api/v1/posts/111\n",
"Server: Werkzeug/0.9.4 Python/2.7.3\n",
"{\n",
"RESTful Web Services with Flask \n",
"| \n",
"217\n",
"\n",
" \"author\": \"http://127.0.0.1:5000/api/v1/users/1\",\n",
" \"body\": \"I'm adding a post from the *command line*.\",\n",
" \"body_html\": \"<p>I'm adding a post from the <em>command line</em>.</p>\",\n",
" \"comments\": \"http://127.0.0.1:5000/api/v1/posts/111/comments\",\n",
" \"comment_count\": 0,\n",
" \"timestamp\": \"Sun, 22 Dec 2013 08:30:27 GMT\",\n",
" \"url\": \"http://127.0.0.1:5000/api/v1/posts/111\"\n",
"}\n",
"To use authentication tokens instead of a username and password, a POST request\n",
"to /api/v1/tokens/ is sent first:\n",
"(venv) $ http --auth <email>:<password> --json POST \\\n",
"> http://127.0.0.1:5000/api/v1/tokens/\n",
"HTTP/1.0 200 OK\n",
"Content-Length: 162\n",
"Content-Type: application/json\n",
"Date: Sat, 04 Jan 2014 08:38:47 GMT\n",
"Server: Werkzeug/0.9.4 Python/3.3.3\n",
"{\n",
" \"expiration\": 3600,\n",
" \"token\": \"eyJpYXQiOjEzODg4MjQ3MjcsImV4cCI6MTM4ODgyODMyNywiYWxnIjoiSFMy...\"\n",
"}\n",
"And now the returned token can be used to make calls into the API for the next hour\n",
"by passing it along in the username field and leaving the password empty:\n",
"(venv) $ http --json --auth eyJpYXQ...: GET http://127.0.0.1:5000/api/v1/posts/ \n",
"When the token expires, requests will be returned with a code 401 error, indicating\n",
"that a new token needs to be obtained.\n",
"Congratulations! This chapter completes Part II, and with that the feature develop‐\n",
"ment phase of Flasky is complete. The next step is obviously to deploy it, and that\n",
"brings a new set of challenges that are the subject of Part III.\n",
"218 \n",
"| \n",
"Chapter 14: Application Programming Interfaces\n",
"\n",
"PART III\n",
"The Last Mile\n",
"\n",
"\n",
"CHAPTER 15\n",
"Testing\n",
"There are two very good reasons for writing unit tests. When implementing new\n",
"functionality, unit tests are used to confirm that the new code is working in the\n",
"expected way. The same result can be obtained by testing manually, but of course\n",
"automated tests save time and effort because they can be repeated easily.\n",
"A second, more important reason is that each time the application is modified, all the\n",
"unit tests built around it can be executed to ensure that there are no regressions in the\n",
"existing code; in other words, that the new changes did not affect the way the older\n",
"code works.\n",
"Unit tests have been a part of Flasky since the very beginning, with tests designed to\n",
"exercise specific features of the application implemented in the database model\n",
"classes. These classes are easy to test outside of the context of a running application,\n",
"so given that it takes little effort, implementing unit tests for all the features that exist\n",
"in the database models is the best way to ensure at least that part of the application\n",
"starts robust and stays that way.\n",
"This chapter discusses ways to improve and extend unit testing to other areas of the\n",
"application.\n",
"Obtaining Code Coverage Reports\n",
"Having a test suite is important, but it is equally important to know how good or bad\n",
"it is. Code coverage tools measure how much of the application is exercised by unit\n",
"tests and can provide a detailed report that indicates which parts of the application\n",
"code are not being tested. This information is invaluable, because it can be used to\n",
"direct the effort of writing new tests to the areas that need it most.\n",
"221\n",
"\n",
"Python has an excellent code coverage tool appropriately called coverage. You can\n",
"install it with pip:\n",
"(venv) $ pip install coverage\n",
"This tool comes as a command-line script that can launch any Python application\n",
"with code coverage enabled, but it also provides more convenient scripting access to\n",
"start the coverage engine programmatically. To have coverage metrics nicely integra‐\n",
"ted into the flask test command added in Chapter 7, a --coverage option can be\n",
"added. The implementation of this option is shown in Example 15-1.\n",
"Example 15-1. flasky.py: coverage metrics\n",
"import os\n",
"import sys\n",
"import click\n",
"COV = None\n",
"if os.environ.get('FLASK_COVERAGE'):\n",
" import coverage\n",
" COV = coverage.coverage(branch=True, include='app/*')\n",
" COV.start()\n",
"# ...\n",
"@app.cli.command()\n",
"@click.option('--coverage/--no-coverage', default=False,\n",
" help='Run tests under code coverage.')\n",
"def test(coverage):\n",
" \"\"\"Run the unit tests.\"\"\"\n",
" if coverage and not os.environ.get('FLASK_COVERAGE'):\n",
" os.environ['FLASK_COVERAGE'] = '1'\n",
" os.execvp(sys.executable, [sys.executable] + sys.argv)\n",
" import unittest\n",
" tests = unittest.TestLoader().discover('tests')\n",
" unittest.TextTestRunner(verbosity=2).run(tests)\n",
" if COV:\n",
" COV.stop()\n",
" COV.save()\n",
" print('Coverage Summary:')\n",
" COV.report()\n",
" basedir = os.path.abspath(os.path.dirname(__file__))\n",
" covdir = os.path.join(basedir, 'tmp/coverage')\n",
" COV.html_report(directory=covdir)\n",
" print('HTML version: file://%s/index.html' % covdir)\n",
" COV.erase()\n",
"The code coverage support is enabled by passing the --coverage option to the flask\n",
"test command. To add the Boolean option to the test custom command, the\n",
"222 \n",
"| \n",
"Chapter 15: Testing\n",
"\n",
"click.option decorator is used. Click then passes the value of the Boolean flag as an\n",
"argument to the function.\n",
"But integrating code coverage in the flasky.py script presents a small problem. By the\n",
"time the --coverage option is received in the test() function, it is already too late to\n",
"enable coverage metrics; by that time all the code in the global scope has already exe‐\n",
"cuted. So, to get accurate metrics, the script recursively restarts itself after setting the\n",
"FLASK_COVERAGE environment variable. In the second run, the top of the script finds\n",
"that the environment variable is set and turns on coverage from the start, even before\n",
"all the application imports.\n",
"The coverage.coverage() function starts the coverage engine. The branch=True\n",
"option enables branch coverage analysis, which, in addition to tracking which lines of\n",
"code execute, checks whether for every conditional both the True and False cases\n",
"have executed. The include option is used to limit coverage analysis to the files that\n",
"are inside the application package, which is the only code that needs to be measured.\n",
"Without the include option, all the extensions installed in the virtual environment\n",
"and the code for the tests itself would be included in the coverage reports—and that\n",
"would add a lot of noise to the report.\n",
"After all the tests have executed, the test() function writes a report to the console\n",
"and also writes a nicer HTML report to disk. The HTML version shows all the source\n",
"code annotated with colors that indicate the lines that are covered by the tests and the\n",
"ones that are not.\n",
"If you have cloned the application’s Git repository on GitHub, you\n",
"can run git checkout 15a to check out this version of the applica‐\n",
"tion. To ensure that you have all the dependencies installed, also\n",
"run pip install -r requirements/dev.txt.\n",
"An example of the text-based report follows:\n",
"(venv) $ flask test --coverage\n",
"...\n",
".----------------------------------------------------------------------\n",
"Ran 23 tests in 6.337s\n",
"OK\n",
"Coverage Summary:\n",
"Name Stmts Miss Branch BrPart Cover\n",
"----------------------------------------------------------------\n",
"app/__init__.py 32 0 0 0 100%\n",
"app/api_v1/__init__.py 3 0 0 0 100%\n",
"app/api_v1/authentication.py 29 18 10 0 28%\n",
"app/api_v1/comments.py 40 30 12 0 19%\n",
"app/api_v1/decorators.py 11 3 2 0 62%\n",
"Obtaining Code Coverage Reports \n",
"| \n",
"223\n",
"\n",
"app/api_v1/errors.py 17 10 0 0 41%\n",
"app/api_v1/posts.py 36 24 8 0 27%\n",
"app/api_v1/users.py 30 24 12 0 14%\n",
"app/auth/__init__.py 3 0 0 0 100%\n",
"app/auth/forms.py 45 8 8 0 70%\n",
"app/auth/views.py 116 91 42 0 16%\n",
"app/decorators.py 14 3 2 0 69%\n",
"app/email.py 15 9 0 0 40%\n",
"app/exceptions.py 2 0 0 0 100%\n",
"app/main/__init__.py 6 1 0 0 83%\n",
"app/main/errors.py 20 15 6 0 19%\n",
"app/main/forms.py 39 7 6 0 71%\n",
"app/main/views.py 178 140 34 0 18%\n",
"app/models.py 236 42 42 6 79%\n",
"----------------------------------------------------------------\n",
"TOTAL 872 425 184 6 45%\n",
"HTML version: file:///home/flask/flasky/tmp/coverage/index.html\n",
"The report shows an overall coverage of 45%, which is not terrible, but isn’t very good\n",
"either. The model classes, which have received all the unit testing attention so far,\n",
"constitute a total of 236 statements, of which 79% are covered in tests. Obviously the\n",
"views.py files in the main and auth blueprints and the routes in the api_v1 blueprint\n",
"all have very low coverage, since these are not exercised in any of the existing unit\n",
"tests. And of course, these coverage metrics are not indicative of how much bug-free\n",
"code exists in the project, since other factors (such as the quality of the tests) play a\n",
"big role in that.\n",
"Armed with this report, it is easy to determine where tests need to be added to the\n",
"test suite to improve coverage—but unfortunately, not all parts of the application can\n",
"be tested as easily as the database models. The next two sections discuss more\n",
"advanced testing strategies that can be applied to view functions, forms, and tem‐\n",
"plates.\n",
"The Flask Test Client\n",
"Some portions of the application code rely heavily on the environment that is created\n",
"by a running application. For example, you can’t simply invoke the code in a view\n",
"function to test it, since the function may need to access Flask context variables such\n",
"as request or session, it may be expecting form data provided in a POST request, and\n",
"it may also require a logged-in user. In short, view functions can run only within the\n",
"context of a request and a running application.\n",
"Flask comes equipped with a test client to try to address this problem, at least to some\n",
"extent. The test client replicates the environment that exists when an application is\n",
"running inside a web server, allowing tests to act as clients and send requests.\n",
"The view functions do not see any major differences when executed under the test\n",
"client; requests are received and routed to the appropriate view functions, from which\n",
"224 \n",
"| \n",
"Chapter 15: Testing\n",
"\n",
"responses are generated and returned. After a view function executes, its response is\n",
"passed to the test, which can check it for correctness.\n",
"Testing Web Applications\n",
"Example 15-2 shows a unit testing framework that uses the test client.\n",
"Example 15-2. tests/test_client.py: framework for tests using the Flask test client\n",
"import unittest\n",
"from app import create_app, db\n",
"from app.models import User, Role\n",
"class FlaskClientTestCase(unittest.TestCase):\n",
" def setUp(self):\n",
" self.app = create_app('testing')\n",
" self.app_context = self.app.app_context()\n",
" self.app_context.push()\n",
" db.create_all()\n",
" Role.insert_roles()\n",
" self.client = self.app.test_client(use_cookies=True)\n",
" def tearDown(self):\n",
" db.session.remove()\n",
" db.drop_all()\n",
" self.app_context.pop()\n",
" def test_home_page(self):\n",
" response = self.client.get('/')\n",
" self.assertEqual(response.status_code, 200)\n",
" self.assertTrue('Stranger' in response.get_data(as_text=True))\n",
"Compared to tests/test_basics.py, this module adds a self.client instance variable,\n",
"which is the Flask test client object. This object exposes methods that issue requests\n",
"into the application. When the test client is created with the use_cookies option\n",
"enabled, it will accept and send cookies in the same way browsers do, so functionality\n",
"that relies on cookies to recall context between requests can be used. In particular,\n",
"this approach enables the use of user sessions, which are stored in cookies.\n",
"The test_home_page() test is a simple example of what the test client can do. In this\n",
"example, a request for the root URL of the application is issued. The return value of\n",
"the get() method of the test client is a Flask response object containing the response\n",
"returned by the invoked view function. To check whether the test was successful, the\n",
"status code of the response is checked, and then the body of the response, obtained\n",
"from response.get_data(), is searched for the word \"Stranger\", which is part of\n",
"the “Hello, Stranger!” greeting shown to anonymous users. Note that get_data()\n",
"The Flask Test Client \n",
"| \n",
"225\n",
"\n",
"returns the response body as a byte array by default; passing as_text=True converts it\n",
"to a string, which is easier to work with.\n",
"The test client can also send POST requests that include form data using the post()\n",
"method, but submitting forms presents a small complication. As discussed in Chap‐\n",
"ter 4, all forms generated by Flask-WTF have a hidden field with a CSRF token that\n",
"needs to be submitted along with the form. To be able to send the CSRF token, a test\n",
"would need to request the page that displays the form, then parse the HTML returned\n",
"in that response and extract the token, so that it can then send it with the form data.\n",
"To avoid the hassle of dealing with CSRF tokens in tests, it is better to disable CSRF\n",
"protection in the testing configuration. This is shown in Example 15-3.\n",
"Example 15-3. config.py: disabling CSRF protection in the testing configuration\n",
"class TestingConfig(Config):\n",
" #...\n",
" WTF_CSRF_ENABLED = False\n",
"Example 15-4 shows a more advanced unit test that simulates a new user registering\n",
"an account, logging in, confirming the account with a confirmation token, and finally\n",
"logging out.\n",
"Example 15-4. tests/test_client.py: simulation of a new user workflow with the Flask test\n",
"client\n",
"class FlaskClientTestCase(unittest.TestCase):\n",
" # ...\n",
" def test_register_and_login(self):\n",
" # register a new account\n",
" response = self.client.post('/auth/register', data={\n",
" 'email': 'john@example.com',\n",
" 'username': 'john',\n",
" 'password': 'cat',\n",
" 'password2': 'cat'\n",
" })\n",
" self.assertEqual(response.status_code, 302)\n",
" # log in with the new account\n",
" response = self.client.post('/auth/login', data={\n",
" 'email': 'john@example.com',\n",
" 'password': 'cat'\n",
" }, follow_redirects=True)\n",
" self.assertEqual(response.status_code, 200)\n",
" self.assertTrue(re.search('Hello,\\s+john!',\n",
" response.get_data(as_text=True)))\n",
" self.assertTrue(\n",
" 'You have not confirmed your account yet' in response.get_data(\n",
" as_text=True))\n",
"226 \n",
"| \n",
"Chapter 15: Testing\n",
"\n",
" # send a confirmation token\n",
" user = User.query.filter_by(email='john@example.com').first()\n",
" token = user.generate_confirmation_token()\n",
" response = self.client.get('/auth/confirm/{}'.format(token),\n",
" follow_redirects=True)\n",
" user.confirm(token)\n",
" self.assertEqual(response.status_code, 200)\n",
" self.assertTrue(\n",
" 'You have confirmed your account' in response.get_data(\n",
" as_text=True))\n",
" # log out\n",
" response = self.client.get('/auth/logout', follow_redirects=True)\n",
" self.assertEqual(response.status_code, 200)\n",
" self.assertTrue('You have been logged out' in response.get_data(\n",
" as_text=True))\n",
"The test begins with a form submission to the registration route. The data argument\n",
"to post() is a dictionary with the form fields, which must exactly match the field\n",
"names defined in the HTML form. Since CSRF protection is now disabled in the test‐\n",
"ing configuration, there is no need to send the CSRF token with the form.\n",
"The /auth/register route can respond in two ways. If the registration data is valid, a\n",
"redirect sends the user to the login page. In the case of an invalid registration, the\n",
"response renders the page with the registration form again, including any appropriate\n",
"error messages. To validate that the registration was accepted, the test checks that the\n",
"status code of the response is 302, which is the code for a redirect.\n",
"The second section of the test issues a login request to the application using the email\n",
"and password just registered. This is done with a POST request to the /auth/login\n",
"route. This time a follow_redirects=True argument is included in the post() call to\n",
"make the test client work like a browser and automatically issue a GET request for the\n",
"redirected URL. With this option, status code 302 will not be returned; instead, the\n",
"response from the redirected URL is returned.\n",
"A successful response to the login submission would now have a page that greets the\n",
"user by their username and then indicates that the account needs to be confirmed to\n",
"gain access. Two assert statements verify that this is the page returned. Here, it is\n",
"interesting to note that a search for the string 'Hello, john!' would not work\n",
"because this string is assembled from static and dynamic portions, so due to the way\n",
"the Jinja2 template was created the final HTML has extra whitespace in between these\n",
"two words. To avoid an error in this test due to the whitespace, a regular expression is\n",
"used.\n",
"The next step is to confirm the account, which presents another small obstacle. The\n",
"confirmation URL is sent to the user by email during registration, so there is no easy\n",
"way to access it from the test. The solution presented in the test bypasses the token\n",
"The Flask Test Client \n",
"| \n",
"227\n",
"\n",
"that was generated as part of the registration and generates another one directly from\n",
"the User instance. Another possibility would have been to extract the token by pars‐\n",
"ing the email body, which Flask-Mail saves when running in a testing configuration.\n",
"With the token at hand, the next step of the test is to simulate the user clicking the\n",
"confirmation token URL received by email. This is achieved by sending a GET request\n",
"to the confirmation URL, which includes the token. The response to this request is a\n",
"redirect to the home page, but once again follow_redirects=True is specified, so the\n",
"test client requests the redirected page automatically and returns it. The response is\n",
"checked for the greeting and a flashed message that informs the user that the confir‐\n",
"mation was successful.\n",
"The final step in this test is to send a GET request to the logout route; to confirm that\n",
"this has worked, the test searches for the flashed message in the response.\n",
"If you have cloned the application’s Git repository on GitHub, you\n",
"can run git checkout 15b to check out this version of the applica‐\n",
"tion.\n",
"Testing Web Services\n",
"The Flask test client can also be used to test RESTful web services. Example 15-5\n",
"shows an example unit test class with two tests.\n",
"Example 15-5. tests/test_api.py: RESTful API testing with the Flask test client\n",
"class APITestCase(unittest.TestCase):\n",
" # ...\n",
" def get_api_headers(self, username, password):\n",
" return {\n",
" 'Authorization':\n",
" 'Basic ' + b64encode(\n",
" (username + ':' + password).encode('utf-8')).decode('utf-8'),\n",
" 'Accept': 'application/json',\n",
" 'Content-Type': 'application/json'\n",
" }\n",
" def test_no_auth(self):\n",
" response = self.client.get(url_for('api.get_posts'),\n",
" content_type='application/json')\n",
" self.assertEqual(response.status_code, 401)\n",
" def test_posts(self):\n",
" # add a user\n",
" r = Role.query.filter_by(name='User').first()\n",
" self.assertIsNotNone(r)\n",
"228 \n",
"| \n",
"Chapter 15: Testing\n",
"\n",
" u = User(email='john@example.com', password='cat', confirmed=True,\n",
" role=r)\n",
" db.session.add(u)\n",
" db.session.commit()\n",
" # write a post\n",
" response = self.client.post(\n",
" '/api/v1/posts/',\n",
" headers=self.get_api_headers('john@example.com', 'cat'),\n",
" data=json.dumps({'body': 'body of the *blog* post'}))\n",
" self.assertEqual(response.status_code, 201)\n",
" url = response.headers.get('Location')\n",
" self.assertIsNotNone(url)\n",
" # get the new post\n",
" response = self.client.get(\n",
" url,\n",
" headers=self.get_api_headers('john@example.com', 'cat'))\n",
" self.assertEqual(response.status_code, 200)\n",
" json_response = json.loads(response.get_data(as_text=True))\n",
" self.assertEqual('http://localhost' + json_response['url'], url)\n",
" self.assertEqual(json_response['body'], 'body of the *blog* post')\n",
" self.assertEqual(json_response['body_html'],\n",
" '<p>body of the <em>blog</em> post</p>')\n",
"The setUp() and tearDown() methods for testing the API are the same as for the reg‐\n",
"ular application, but the cookie support does not need to be configured because the\n",
"API does not use it. The get_api_headers() method is a helper method that returns\n",
"the common headers that need to be sent with most API requests. These include the\n",
"authentication credentials and the MIME type-related headers.\n",
"The test_no_auth() test is a simple test that ensures that a request that does not\n",
"include authentication credentials is rejected with error code 401. The test_posts()\n",
"test adds a user to the database and then uses the RESTful API to insert a blog post\n",
"and then read it back. Any requests that send data in the body must encode it with\n",
"json.dumps(), because the Flask test client does not automatically encode to JSON.\n",
"Likewise, response bodies are also returned in JSON format and must be decoded\n",
"with json.loads() before they can be inspected.\n",
"If you have cloned the application’s Git repository on GitHub, you\n",
"can run git checkout 15c to check out this version of the applica‐\n",
"tion.\n",
"The Flask Test Client \n",
"| \n",
"229\n",
"\n",
"End-to-End Testing with Selenium\n",
"The Flask test client cannot fully emulate the environment of a running application.\n",
"For example, any application that relies on JavaScript code running in the client\n",
"browser will not work, as the JavaScript code included in the responses will be\n",
"returned to the test without being executed.\n",
"When tests require the complete environment, there is no other choice than to use a\n",
"real web browser connected to the application running on a real web server. Fortu‐\n",
"nately, most web browsers can be automated. Selenium is a web browser automation\n",
"tool that supports the most popular web browsers in the three major operating sys‐\n",
"tems.\n",
"The Python interface for Selenium is installed with pip:\n",
"(venv) $ pip install selenium\n",
"Selenium requires a driver for the desired web browser to be installed separately, in\n",
"addition to the browser itself. There are drivers for all major web browsers, so an\n",
"application could set up a sophisticated framework to test several browsers. For this\n",
"application, however, only the Google Chrome web browser will be used for automa‐\n",
"ted tests, with its corresponding driver, ChromeDriver. If you are using a macOS\n",
"computer with the brew package installer, you can install ChromeDriver as follows:\n",
"(venv) $ brew install chromedriver\n",
"For Linux, Microsoft Windows, or a macOS computer without brew, you can down‐\n",
"load a regular ChromeDriver installer from the ChromeDriver website.\n",
"Testing with Selenium requires the application to be running inside a web server that\n",
"is listening for real HTTP requests. The method that will be shown in this section\n",
"starts the application with the development server in a background thread while the\n",
"tests run on the main thread. Under the control of the tests, Selenium launches a web\n",
"browser and makes it connect to the application to perform the required operations.\n",
"A problem with this approach is that after all the tests have completed, the Flask\n",
"server needs to be stopped, ideally in a graceful way, so that background tasks such as\n",
"the code coverage engine can cleanly complete their work. The Werkzeug web server\n",
"has a shutdown option, but because the server is running isolated in its own thread,\n",
"the only way to ask the server to shut down is by sending a regular HTTP request.\n",
"Example 15-6 shows the implementation of a server shutdown route.\n",
"230 \n",
"| \n",
"Chapter 15: Testing\n",
"\n",
"Example 15-6. _app/main/views.py: server shutdown route\n",
"@main.route('/shutdown')\n",
"def server_shutdown():\n",
" if not current_app.testing:\n",
" abort(404)\n",
" shutdown = request.environ.get('werkzeug.server.shutdown')\n",
" if not shutdown:\n",
" abort(500)\n",
" shutdown()\n",
" return 'Shutting down...'\n",
"The shutdown route will work only when the application is running in testing mode;\n",
"invoking it in other configurations will return a 404 status code response. The actual\n",
"shutdown procedure involves calling a shutdown function that Werkzeug exposes in\n",
"the environment. After calling this function and returning from the request, the\n",
"development web server will know that it needs to exit gracefully.\n",
"Example 15-7 shows the layout of a test case that is configured to run tests with Sele‐\n",
"nium.\n",
"Example 15-7. tests/test_selenium.py: framework for tests using Selenium\n",
"from selenium import webdriver\n",
"class SeleniumTestCase(unittest.TestCase):\n",
" client = None\n",
" @classmethod\n",
" def setUpClass(cls):\n",
" # start Chrome\n",
" options = webdriver.ChromeOptions()\n",
" options.add_argument('headless')\n",
" try:\n",
" cls.client = webdriver.Chrome(chrome_options=options)\n",
" except:\n",
" pass\n",
" # skip these tests if the browser could not be started\n",
" if cls.client:\n",
" # create the application\n",
" cls.app = create_app('testing')\n",
" cls.app_context = cls.app.app_context()\n",
" cls.app_context.push()\n",
" # suppress logging to keep unittest output clean\n",
" import logging\n",
" logger = logging.getLogger('werkzeug')\n",
" logger.setLevel(\"ERROR\")\n",
"End-to-End Testing with Selenium \n",
"| \n",
"231\n",
"\n",
" # create the database and populate with some fake data\n",
" db.create_all()\n",
" Role.insert_roles()\n",
" fake.users(10)\n",
" fake.posts(10)\n",
" # add an administrator user\n",
" admin_role = Role.query.filter_by(permissions=0xff).first()\n",
" admin = User(email='john@example.com',\n",
" username='john', password='cat',\n",
" role=admin_role, confirmed=True)\n",
" db.session.add(admin)\n",
" db.session.commit()\n",
" # start the Flask server in a thread\n",
" cls.server_thread = threading.Thread(\n",
" target=cls.app.run, kwargs={'debug': 'false',\n",
" 'use_reloader': False,\n",
" 'use_debugger': False})\n",
" cls.server_thread.start()\n",
" @classmethod\n",
" def tearDownClass(cls):\n",
" if cls.client:\n",
" # stop the Flask server and the browser\n",
" cls.client.get('http://localhost:5000/shutdown')\n",
" cls.client.quit()\n",
" cls.server_thread.join()\n",
" # destroy database\n",
" db.drop_all()\n",
" db.session.remove()\n",
" # remove application context\n",
" cls.app_context.pop()\n",
" def setUp(self):\n",
" if not self.client:\n",
" self.skipTest('Web browser not available')\n",
" def tearDown(self):\n",
" pass\n",
"The setUpClass() and tearDownClass() class methods are invoked before and after\n",
"the tests in this class execute. The setup involves starting an instance of Chrome\n",
"through Selenium’s webdriver API, and creating an application and a database with\n",
"some initial fake data for tests to use. The application is started in a thread using the\n",
"app.run() method. At the end the application receives a request to /shutdown, which\n",
"causes the background thread to end. The browser is then closed and the test data‐\n",
"base removed.\n",
"232 \n",
"| \n",
"Chapter 15: Testing\n",
"\n",
"Before the Flask command-line interface based on Click was intro‐\n",
"duced, you had to start the Flask development web server by call‐\n",
"ing app.run() from the application’s main script, or else use a\n",
"third-party extension such as Flask-Script. While using app.run()\n",
"to start a server is now replaced with the flask run command, the\n",
"app.run() method continues to be supported, and here you can\n",
"see how it can still be useful for complex unit testing situations.\n",
"Selenium supports many other web browsers besides Chrome.\n",
"Consult the Selenium documentation if you wish to use another\n",
"web browser or test additional browsers.\n",
"The setUp() method that runs before each test skips tests if Selenium cannot start the\n",
"web browser in the startUpClass() method. In Example 15-8 you can see an exam‐\n",
"ple test built with Selenium.\n",
"Example 15-8. tests/test_selenium.py: example Selenium unit test\n",
"class SeleniumTestCase(unittest.TestCase):\n",
" # ...\n",
" def test_admin_home_page(self):\n",
" # navigate to home page\n",
" self.client.get('http://localhost:5000/')\n",
" self.assertTrue(re.search('Hello,\\s+Stranger!',\n",
" self.client.page_source))\n",
" # navigate to login page\n",
" self.client.find_element_by_link_text('Log In').click()\n",
" self.assertIn('<h1>Login</h1>', self.client.page_source)\n",
" # log in\n",
" self.client.find_element_by_name('email').\\\n",
" send_keys('john@example.com')\n",
" self.client.find_element_by_name('password').send_keys('cat')\n",
" self.client.find_element_by_name('submit').click()\n",
" self.assertTrue(re.search('Hello,\\s+john!', self.client.page_source))\n",
" # navigate to the user's profile page\n",
" self.client.find_element_by_link_text('Profile').click()\n",
" self.assertIn('<h1>john</h1>', self.client.page_source)\n",
"This test logs in to the application using the administrator account that was created in\n",
"setUpClass() and then opens the user’s profile page. Note how different the testing\n",
"methodology is from the Flask test client. When testing with Selenium, tests send\n",
"commands to the web browser and never interact with the application directly. The\n",
"End-to-End Testing with Selenium \n",
"| \n",
"233\n",
"\n",
"commands closely match the actions that a real user would perform with a mouse or\n",
"keyboard.\n",
"The test begins with a call to get() with the home page of the application. In the\n",
"browser, this causes the URL to be entered in the address bar. To verify this step, the\n",
"page source is checked for the “Hello, Stranger!” greeting.\n",
"To go to the sign-in page, the test looks for the “Log In” link using\n",
"find_element_by_link_text() and then calls click() on it to trigger a real click in\n",
"the browser. Selenium provides several find_element_by...() convenience methods\n",
"that can search for elements within the HTML page in different ways.\n",
"To log in to the application, the test locates the email and password form fields by\n",
"their names using find_element_by_name() and then writes text into them with\n",
"send_keys(). The form is submitted by calling click() on the submit button. The\n",
"personalized greeting is checked to ensure that the login was successful and the\n",
"browser is now on the home page.\n",
"The final part of the test locates the “Profile” link in the navigation bar and clicks it.\n",
"To verify that the profile page was loaded, the heading with the username is searched\n",
"in the page source.\n",
"If you have cloned the application’s Git repository on GitHub, you\n",
"can run git checkout 15d to check out this version of the applica‐\n",
"tion. This update contains a database migration, so remember to\n",
"run flask db upgrade after you check out the code. To ensure that\n",
"you have all the dependencies installed, also run pip install -r\n",
"requirements/dev.txt.\n",
"When you run the unit tests with the flask test command there will be no visible\n",
"difference. The test_admin_home_page unit test in Example 15-8 will run a headless\n",
"Chrome instance and perform all the actions on it. If you want to see the actions per‐\n",
"formed \n",
"in \n",
"a \n",
"real \n",
"Chrome \n",
"window, \n",
"comment \n",
"out \n",
"the \n",
"line\n",
"options.add_argument('headless') in the setUpClass() method, so that Selenium\n",
"creates a regular Chrome window.\n",
"Is It Worth It?\n",
"By now you may be asking yourself if testing using the Flask test client or Selenium is\n",
"really worth the trouble. It is a valid question, and it does not have a simple answer.\n",
"Whether you like it or not, your application will be tested. If you don’t test it yourself,\n",
"then your users will become the unwilling testers; they will find the bugs, and then\n",
"you will have to fix them under pressure. Simple and focused tests like the ones that\n",
"exercise database models and other parts of the application that can be executed out‐\n",
"234 \n",
"| \n",
"Chapter 15: Testing\n",
"\n",
"side of the context of an application should always be carried out, as they have a very\n",
"low cost and ensure the proper functioning of the core pieces of application logic.\n",
"End-to-end tests of the type that the Flask test client and Selenium can carry out are\n",
"sometimes necessary, but due to the increased complexity of writing them, they\n",
"should be used only for functionality that cannot be tested in isolation. The applica‐\n",
"tion code should be organized so that it is possible to push the business logic into\n",
"application modules that are independent of the context of the application, and thus\n",
"can be tested more easily. The code that exists in view functions should be simple and\n",
"just act as a thin layer that accepts requests and invokes the corresponding actions in\n",
"other classes or functions that encapsulate the application logic.\n",
"So yes, testing is absolutely worth it. But it is important to design an efficient testing\n",
"strategy and write code that can take advantage of it.\n",
"Is It Worth It? \n",
"| \n",
"235\n",
"\n",
"\n",
"CHAPTER 16\n",
"Performance\n",
"Nobody likes slow applications. Long waits for pages to load frustrate users, so it is\n",
"important to detect and correct performance problems as soon as they appear. In this\n",
"chapter, two important performance aspects of web applications are considered.\n",
"Logging Slow Database Performance\n",
"When application performance slowly degenerates with time, it is likely due to slow\n",
"database queries, which get worse as the size of the database grows. Optimizing data‐\n",
"base queries can be as simple as adding more indexes or as complex as adding a cache\n",
"between the application and the database. The explain statement, available in most\n",
"database query languages, shows the steps the database takes to execute a given query,\n",
"often exposing inefficiencies in database or index design.\n",
"But before starting to optimize queries, it is necessary to determine which queries are\n",
"the ones that are worth optimizing. During a typical request several database queries\n",
"may be issued, so it is often hard to identify which of all the queries are the slow ones.\n",
"Flask-SQLAlchemy has an option to record statistics about database queries issued\n",
"during a request. In Example 16-1 you can see how this feature can be used to log\n",
"queries that are slower than a configured threshold.\n",
"Example 16-1. app/main/views.py: reporting slow database queries\n",
"from flask_sqlalchemy import get_debug_queries\n",
"@main.after_app_request\n",
"def after_request(response):\n",
" for query in get_debug_queries():\n",
" if query.duration >= current_app.config['FLASKY_SLOW_DB_QUERY_TIME']:\n",
" current_app.logger.warning(\n",
"237\n",
"\n",
" 'Slow query: %s\\nParameters: %s\\nDuration: %fs\\nContext: %s\\n' %\n",
" (query.statement, query.parameters, query.duration,\n",
" query.context))\n",
" return response\n",
"This functionality is attached to an after_app_request handler, which works in a\n",
"similar way to the before_app_request handler but is invoked after the view func‐\n",
"tion that handles the request returns. Flask passes the response object to the\n",
"after_app_request handler in case it needs to be modified.\n",
"In this case, the after_app_request handler does not modify the response; it just\n",
"gets the query timings recorded by Flask-SQLAlchemy and then logs the slow ones to\n",
"the application logger that Flask sets up at app.logger, before returning the response,\n",
"which will then be sent to the client.\n",
"The get_debug_queries() function returns the queries issued during the request as a\n",
"list. The information provided for each query is shown in Table 16-1.\n",
"Table 16-1. Query statistics recorded by Flask-SQLAlchemy\n",
"Name\n",
"Description\n",
"statement\n",
"The SQL statement\n",
"parameters\n",
"The parameters used with the SQL statement\n",
"start_time The time the query was issued\n",
"end_time\n",
"The time the query returned\n",
"duration\n",
"The duration of the query in seconds\n",
"context\n",
"A string that indicates the source code location where the query was issued\n",
"The after_app_request handler walks the list and logs any queries that lasted longer\n",
"than a threshold given in the configuration variable FLASKY_SLOW_DB_QUERY_TIME.\n",
"The logging is issued at the warning level in this application, but in some cases it may\n",
"make sense to treat slow database alerts as errors.\n",
"The get_debug_queries() function is enabled only in debug mode by default.\n",
"Unfortunately, database performance problems rarely show up during development\n",
"because much smaller databases are used. For this reason, it is much more useful to\n",
"enable this option in production. Example 16-2 shows the configuration changes that\n",
"are necessary to enable database query performance monitoring in production mode.\n",
"238 \n",
"| \n",
"Chapter 16: Performance\n",
"\n",
"Example 16-2. config.py: configuration for slow query reporting\n",
"class Config:\n",
" # ...\n",
" SQLALCHEMY_RECORD_QUERIES = True\n",
" FLASKY_SLOW_DB_QUERY_TIME = 0.5\n",
" # ...\n",
"SQLALCHEMY_RECORD_QUERIES tells Flask-SQLAlchemy to enable the recording of\n",
"query statistics. The slow query threshold is set to half a second. Both configuration\n",
"variables were included in the base Config class, so they will be enabled for all config‐\n",
"urations.\n",
"Whenever a slow query is detected, an entry will be written to Flask’s application log‐\n",
"ger. To be able to store these log entries, the logger must be configured. The logging\n",
"configuration largely depends on the platform that hosts the application. Some exam‐\n",
"ples are shown in Chapter 17.\n",
"If you have cloned the application’s Git repository on GitHub, you\n",
"can run git checkout 16a to check out this version of the applica‐\n",
"tion.\n",
"Source Code Profiling\n",
"Another possible source of performance problems is high CPU consumption, caused\n",
"by functions that perform heavy computing. Source code profilers are useful in find‐\n",
"ing the slowest parts of an application. A profiler watches a running application and\n",
"records the functions that are called and how long each takes to run. It then produces\n",
"a detailed report showing the slowest functions.\n",
"Profiling is typically done only in a development environment. A\n",
"source code profiler makes the application run much slower than\n",
"normal, because it has to observe and take notes on all that is hap‐\n",
"pening in real time. Profiling on a production system is not recom‐\n",
"mended, unless a lightweight profiler specifically designed to run in\n",
"a production environment is used.\n",
"Flask’s development web server, which comes from Werkzeug, can optionally enable\n",
"the Python profiler for each request. Example 16-3 adds a new command-line option\n",
"to the application that starts the web server under the profiler.\n",
"Source Code Profiling \n",
"| \n",
"239\n",
"\n",
"Example 16-3. flasky.py: running the application under the request profiler\n",
"@app.cli.command()\n",
"@click.option('--length', default=25,\n",
" help='Number of functions to include in the profiler report.')\n",
"@click.option('--profile-dir', default=None,\n",
" help='Directory where profiler data files are saved.')\n",
"def profile(length, profile_dir):\n",
" \"\"\"Start the application under the code profiler.\"\"\"\n",
" from werkzeug.contrib.profiler import ProfilerMiddleware\n",
" app.wsgi_app = ProfilerMiddleware(app.wsgi_app, restrictions=[length],\n",
" profile_dir=profile_dir)\n",
" app.run(debug=False)\n",
"This command attaches the ProfilerMiddleware from Werkzeug to the application,\n",
"through its wsgi_app attribute. WSGI middlewares are invoked each time the web\n",
"server dispatches a request to the application and can modify the way the request is\n",
"handled, in this case by capturing profiling data. Note that the application is then\n",
"started programmatically using the app.run() method.\n",
"If you have cloned the application’s Git repository on GitHub, you\n",
"can run git checkout 16b to check out this version of the applica‐\n",
"tion.\n",
"When the application is started with flask profile, the console will show the pro‐\n",
"filer statistics for each request, which will include the slowest 25 functions. The\n",
"--length option can be used to change the number of functions shown in the report.\n",
"If the --profile-dir option is given, the profile data for each request is saved to a file\n",
"in the given directory. The profiler data files can be used to generate more detailed\n",
"reports that include a call graph. For more information on the Python profiler, con‐\n",
"sult the official documentation.\n",
"The preparations for deployment are complete. The next chapter will give you an\n",
"overview of what to expect when deploying your application.\n",
"240 \n",
"| \n",
"Chapter 16: Performance\n",
"\n",
"CHAPTER 17\n",
"Deployment\n",
"The web development server that comes bundled with Flask is not robust, secure, or\n",
"efficient enough to work in a production environment. In this chapter, production\n",
"deployment options for Flask applications are examined.\n",
"Deployment Workflow\n",
"Regardless of the hosting method used, there are a series of tasks that must be carried\n",
"out when the application is installed on a production server. These include the cre‐\n",
"ation or update of the database tables.\n",
"Having to run these tasks manually each time the application is installed or upgraded\n",
"is error prone and time consuming. Instead, a command that performs all the\n",
"required tasks can be added to flasky.py.\n",
"Example 17-1 shows a deploy command implementation that is appropriate for\n",
"Flasky.\n",
"Example 17-1. flasky.py: deploy command\n",
"from flask_migrate import upgrade\n",
"from app.models import Role, User\n",
"@manager.command\n",
"def deploy():\n",
" \"\"\"Run deployment tasks.\"\"\"\n",
" # migrate database to latest revision\n",
" upgrade()\n",
" # create or update user roles\n",
" Role.insert_roles()\n",
"241\n",
"\n",
" # ensure all users are following themselves\n",
" User.add_self_follows()\n",
"The functions invoked by this command were all created before; they are just invoked\n",
"all together from a single command to simplify the deployment of the application.\n",
"If you have cloned the application’s Git repository on GitHub, you\n",
"can run git checkout 17a to check out this version of the applica‐\n",
"tion.\n",
"These functions are all designed in a way that causes no problems if they are executed\n",
"multiple times. Designing update functions in this way makes it possible to run just\n",
"this deploy command every time an installation or upgrade is done without having to\n",
"worry about side effects caused by a function that runs at the wrong time.\n",
"Logging of Errors During Production\n",
"When the application is running in debug mode, Werkzeug’s interactive debugger\n",
"appears whenever an error occurs. The stack trace of the error is displayed on the web\n",
"page, and it is possible to look at the source code and even evaluate expressions in the\n",
"context of each stack frame using Flask’s interactive web-based debugger.\n",
"The debugger is an excellent tool to debug application problems during development,\n",
"but obviously it cannot be used in a production deployment. Errors that occur in pro‐\n",
"duction are silenced and instead the user receives a discrete code 500 error page. But\n",
"luckily, the stack traces of these errors are not completely lost, as Flask writes them to\n",
"a log file.\n",
"During startup, Flask creates an instance of Python’s logging.Logger class and\n",
"attaches it to the application instance as app.logger. In debug mode, this logger\n",
"writes to the console, but in production mode there are no handlers configured for it\n",
"by default. Unless a handler is added, logs are not stored. The changes in\n",
"Example 17-2 configure a logging handler that sends the errors that occur while run‐\n",
"ning under the production configuration to the administrator email address config‐\n",
"ured in the FLASKY_ADMIN setting.\n",
"Example 17-2. config.py: sending email for application errors\n",
"class ProductionConfig(Config):\n",
" # ...\n",
" @classmethod\n",
" def init_app(cls, app):\n",
" Config.init_app(app)\n",
"242 \n",
"| \n",
"Chapter 17: Deployment\n",
"\n",
" # email errors to the administrators\n",
" import logging\n",
" from logging.handlers import SMTPHandler\n",
" credentials = None\n",
" secure = None\n",
" if getattr(cls, 'MAIL_USERNAME', None) is not None:\n",
" credentials = (cls.MAIL_USERNAME, cls.MAIL_PASSWORD)\n",
" if getattr(cls, 'MAIL_USE_TLS', None):\n",
" secure = ()\n",
" mail_handler = SMTPHandler(\n",
" mailhost=(cls.MAIL_SERVER, cls.MAIL_PORT),\n",
" fromaddr=cls.FLASKY_MAIL_SENDER,\n",
" toaddrs=[cls.FLASKY_ADMIN],\n",
" subject=cls.FLASKY_MAIL_SUBJECT_PREFIX + ' Application Error',\n",
" credentials=credentials,\n",
" secure=secure)\n",
" mail_handler.setLevel(logging.ERROR)\n",
" app.logger.addHandler(mail_handler)\n",
"Recall that all configuration classes have an init_app() static method that is invoked\n",
"by create_app(), which so far has not been used. In the implementation of this\n",
"method for the ProductionConfig class, the application logger is now configured\n",
"with a log handler that sends errors to an email recipient.\n",
"The logging level of the email logger is set to logging.ERROR, so only severe problems\n",
"are going to be emailed. Messages logged on lesser levels can be logged to a file,\n",
"syslog, or any other supported destination by adding the proper logging handlers.\n",
"The logging method to use for these messages largely depends on the hosting plat‐\n",
"form.\n",
"If you have cloned the application’s Git repository on GitHub, you\n",
"can run git checkout 17b to check out this version of the applica‐\n",
"tion.\n",
"Cloud Deployment\n",
"The trend in application hosting is to host “in the cloud,” but this can mean many\n",
"different things. At the most basic level, cloud hosting can mean that the application\n",
"is installed on one or more virtual servers, which for all intents and purposes operate\n",
"and feel like physical machines, but in reality are virtual machines managed by the\n",
"cloud operator. An example of these types of servers are those available through the\n",
"EC2 service from Amazon Web Services (AWS). Deploying an application to a virtual\n",
"server is similar to doing a traditional deployment to a dedicated server, as described\n",
"later in this chapter.\n",
"Cloud Deployment \n",
"| \n",
"243\n",
"\n",
"A more advanced deployment model is based on containers. A container isolates an\n",
"application in an image of the application and its environment. A container image\n",
"includes the application plus all the dependencies it needs to run. A container plat‐\n",
"form, such as Docker, can then install and execute a pregenerated container image on\n",
"any system in which it runs.\n",
"Another deployment option, formally known as Platform as a Service (PaaS), frees\n",
"the application developer from the mundane tasks of installing and maintaining the\n",
"hardware and software platforms on which the application runs. In the PaaS model, a\n",
"service provider offers a fully managed platform on which applications can run. All\n",
"the application developer needs to do is upload the application code to the servers\n",
"maintained by the provider, after which it automatically becomes available, usually\n",
"within seconds. Most PaaS providers offer ways to dynamically “scale” the application\n",
"by adding or removing servers as necessary to keep up with the number of requests\n",
"received.\n",
"The remainder of this chapter offers an introduction to Heroku (one of the most pop‐\n",
"ular PaaS providers), Docker containers, and finally traditional deployments, which\n",
"are suitable for dedicated or virtual servers.\n",
"The Heroku Platform\n",
"Heroku was one of the first PaaS providers, having been in business since 2007. The\n",
"Heroku platform is very flexible and supports a long list of programming languages,\n",
"including Python. To deploy an application to Heroku, the developer uses Git to push\n",
"the application to Heroku’s special Git server, which automatically triggers the instal‐\n",
"lation, upgrade, configuration, and deployment of the application.\n",
"Heroku uses units of computing called dynos to measure usage and charge for the\n",
"service. The most common type of dyno is the web dyno, which represents a web\n",
"server instance. An application can increase its request handling capacity by deploy‐\n",
"ing more web dynos, each running an instance of the application. Another type of\n",
"dyno is the worker dyno, which is used to perform background jobs or other support\n",
"tasks.\n",
"The platform provides a large number of plug-ins and add-ons for databases, email\n",
"support, and many other services. The following sections expand on some of the\n",
"details involved in deploying Flasky to Heroku.\n",
"Preparing the Application\n",
"To work with Heroku, the application must be hosted in a Git repository. If you are\n",
"working with an application that is hosted on a remote Git server, such as GitHub or\n",
"Bitbucket, cloning the application will create a local Git repository that is perfect to\n",
"244 \n",
"| \n",
"Chapter 17: Deployment\n",
"\n",
"use with Heroku. If the application isn’t already hosted in a Git repository, you’ll need\n",
"to create one for it on your development machine.\n",
"If you plan on hosting your application on Heroku, it is a good idea\n",
"to start using Git from the very beginning. GitHub has installation\n",
"and setup guides for the three major operating systems in its help\n",
"guide.\n",
"Creating a Heroku account\n",
"You must create an account with Heroku before you can use the service. Heroku pro‐\n",
"vides a free tier that allows you to host a few simple applications, so this is a great\n",
"platform to experiment with.\n",
"Installing the Heroku CLI\n",
"To work with the Heroku service, the Heroku CLI must be installed. This is a\n",
"command-line client that manages the interactions with the service. Heroku provides\n",
"installers for the three major operating systems.\n",
"The first thing to do after installing the CLI is to authenticate with your Heroku\n",
"account through the heroku login command:\n",
"$ heroku login\n",
"Enter your Heroku credentials.\n",
"Email: <your-email-address>\n",
"Password: <your-password>\n",
"It is important that your SSH public key is uploaded to Heroku, as\n",
"this is what enables the git push command. Normally the login\n",
"command creates and uploads an SSH public key automatically,\n",
"but the heroku keys:add command can be used to upload your\n",
"public key separately from the login command or if you need to\n",
"upload additional keys.\n",
"Creating an application\n",
"The next step is to create an application. Before this is done, the application needs to\n",
"be under Git source control. If you have been using the GitHub repository to follow\n",
"along with the code in this book, then you already have a Git repository. If not, you\n",
"will need to create one now. To register the application with Heroku, run the follow‐\n",
"ing command from the application’s top-level directory:\n",
"$ heroku create <appname>\n",
"Creating <appname>... done\n",
"https://<appname>.herokuapp.com/ | https://git.heroku.com/<appname>.git\n",
"The Heroku Platform \n",
"| \n",
"245\n",
"\n",
"Heroku application names must be unique across all customers, so you need to think\n",
"of a name that is not taken by any other application. As indicated by the output of the\n",
"create command, once deployed the application will be available at https://<app‐\n",
"name>.herokuapp.com. Heroku also supports using a custom domain name for your\n",
"application.\n",
"As part of the application creation, Heroku creates a Git server dedicated to your\n",
"application at https://git.heroku.com/<appname>.git. The create command adds this\n",
"server to your local Git repository as a git remote with the name heroku:\n",
"$ git remote show heroku\n",
"* remote heroku\n",
" Fetch URL: https://git.heroku.com/<appname>.git\n",
" Push URL: https://git.heroku.com/<appname>.git\n",
" HEAD branch: (unknown)\n",
"The flask command requires the FLASK_APP environment variable to be set to work.\n",
"To make sure that any commands that are executed in the Heroku environment suc‐\n",
"ceed, it is a good idea to register this environment variable so that it is always set\n",
"when Heroku executes commands related to this application. This can be done with\n",
"the config command:\n",
"$ heroku config:set FLASK_APP=flasky.py\n",
"Setting FLASK_APP and restarting <appname>... done, v4\n",
"FLASK_APP: flasky.py\n",
"Provisioning a database\n",
"Heroku supports Postgres databases as an add-on. The free service tier includes a\n",
"small database of up to 10,000 rows. To attach a Postgres database to your application,\n",
"use the following command:\n",
"$ heroku addons:create heroku-postgresql:hobby-dev\n",
"Creating heroku-postgresql:hobby-dev on <appname>... free\n",
"Database has been created and is available\n",
" ! This database is empty. If upgrading, you can transfer\n",
" ! data from another database with pg:copy\n",
"Created postgresql-cubic-41298 as DATABASE_URL\n",
"Use heroku addons:docs heroku-postgresql to view documentation\n",
"As indicated by the output of the command, once the application runs inside the Her‐\n",
"oku platform, it will see the database location and credentials in the DATABASE_URL\n",
"environment variable. The format of this variable is a URL, exactly in the format\n",
"SQLAlchemy expects. Recall that the config.py script uses the value of DATABASE_URL\n",
"if it is defined, so the connection to the Postgres database will work automatically.\n",
"246 \n",
"| \n",
"Chapter 17: Deployment\n",
"\n",
"Configuring logging\n",
"Logging of fatal errors by email was added earlier, but in addition to that it is impor‐\n",
"tant to configure logging of lesser message categories. A good example of these types\n",
"of messages are the warnings for slow database queries added in Chapter 16.\n",
"Heroku considers any output written by the application to stdout or stderr logs, so\n",
"a logging handler needs to be added to generate this output. The logging output is\n",
"captured by Heroku and made accessible through the Heroku client with the heroku\n",
"logs command.\n",
"The logging configuration can be added to the ProductionConfig class in its\n",
"init_app() static method. But since this type of logging is specific to Heroku, a bet‐\n",
"ter approach is to define a new configuration specifically for this platform, leaving\n",
"ProductionConfig as a baseline configuration for different types of production plat‐\n",
"forms. The HerokuConfig class is shown in Example 17-3.\n",
"Example 17-3. config.py: Heroku configuration\n",
"class HerokuConfig(ProductionConfig):\n",
" @classmethod\n",
" def init_app(cls, app):\n",
" ProductionConfig.init_app(app)\n",
" # log to stderr\n",
" import logging\n",
" from logging import StreamHandler\n",
" file_handler = StreamHandler()\n",
" file_handler.setLevel(logging.INFO)\n",
" app.logger.addHandler(file_handler)\n",
"When the application is executed by Heroku, it needs to know that this new configu‐\n",
"ration needs to be used. The application instance created in flasky.py uses the\n",
"FLASK_CONFIG environment variable to know what configuration to use, so this vari‐\n",
"able needs to be set appropriately in the Heroku environment. Environment variables\n",
"for the Heroku environment are set using the Heroku client’s config:set command:\n",
"$ heroku config:set FLASK_CONFIG=heroku\n",
"Setting FLASK_CONFIG and restarting <appname>... done, v4\n",
"FLASK_CONFIG: heroku\n",
"To increase the security of your application, it is a good idea to configure a difficult-\n",
"to-guess string as the application’s secret key, which is used to sign the user session\n",
"and the authentication tokens. The Config base class includes the SECRET_KEY\n",
"attribute for this purpose, and sets its value from an environment variable of the same\n",
"name if it exists. When working on the application in your development system it is\n",
"okay to leave this variable undefined and let the Config class configure a hardcoded\n",
"The Heroku Platform \n",
"| \n",
"247\n",
"\n",
"value, but on a production platform it is extremely important to set a strong secret\n",
"key that is not known to anyone, since a leaked key will enable an attacker to forge\n",
"the contents of the user session or generate valid tokens. To make your key secure,\n",
"just set the SECRET_KEY environment variable to a unique string that is not stored\n",
"anywhere:\n",
"$ heroku config:set SECRET_KEY=d68653675379485599f7876a3b469a57\n",
"Setting SECRET_KEY and restarting <appname>... done, v4\n",
"SECRET_KEY: d68653675379485599f7876a3b469a57\n",
"There are many ways to generate random strings that are appropriate to be used as\n",
"secret keys. You can do so with Python as follows:\n",
"(venv) $ python -c \"import uuid; print(uuid.uuid4().hex)\"\n",
"d68653675379485599f7876a3b469a57\n",
"Configuring email\n",
"Heroku does not provide an SMTP server, so an external server must be configured.\n",
"There are several third-party add-ons that integrate production-ready email sending\n",
"support with Heroku, but for testing and evaluation purposes it is sufficient to use the\n",
"default Gmail configuration inherited from the base Config class.\n",
"Because it can be a security risk to embed login credentials directly in the script, the\n",
"username and password to access the Gmail SMTP server are provided as environ‐\n",
"ment variables (if you haven’t yet, it is a very good idea that instead of using your per‐\n",
"sonal email account you create a secondary email to use for testing):\n",
"$ heroku config:set MAIL_USERNAME=<your-gmail-username>\n",
"$ heroku config:set MAIL_PASSWORD=<your-gmail-password>\n",
"Adding a top-level requirements file\n",
"Heroku installs package dependencies from a requirements.txt file stored in the top-\n",
"level directory of the application. All the dependencies in this file will be imported\n",
"into a virtual environment managed by Heroku as part of the deployment.\n",
"The Heroku requirements file must include all the common requirements for the\n",
"production version of the application, plus the psycopg2 package that enables SQL‐\n",
"Alchemy to access the Postgres database. A heroku.txt file with these dependencies\n",
"can be added in the requirements directory and then imported from the top-level\n",
"requirements.txt file as shown in Example 17-4.\n",
"Example 17-4. requirements.txt: Heroku requirements file\n",
"-r requirements/heroku.txt\n",
"248 \n",
"| \n",
"Chapter 17: Deployment\n",
"\n",
"Enabling Secure HTTP with Flask-SSLify\n",
"When the user logs in to the application by submitting a username and a password in\n",
"a web form, these values are at risk of being intercepted by a malicious third party, as\n",
"discussed several times before. During development this is not a problem, but this\n",
"risk needs to be eliminated when you deploy the application on a production server.\n",
"To prevent user credentials from being exposed while in transit, it is necessary to use\n",
"secure HTTP, which encrypts all the communications between clients and the server\n",
"using public key cryptography.\n",
"Heroku makes all applications that are accessed on the herokuapp.com domain avail‐\n",
"able on both http:// and https:// without any configuration required. Because the\n",
"application runs on Heroku’s domain, it will use Heroku’s own SSL certificate. The\n",
"only necessary action to fully secure the application is to intercept any requests sent\n",
"to the http:// interface and redirect them to https://, which is exactly what the Flask-\n",
"SSLify extension does.\n",
"As usual, Flask-SSLify is installed with pip:\n",
"(venv) $ pip install flask-sslify\n",
"The code that activates this extension is added to the application factory function, as\n",
"shown in Example 17-5.\n",
"Example 17-5. app/__init__.py: redirecting all requests to secure HTTP\n",
"def create_app(config_name):\n",
" # ...\n",
" if app.config['SSL_REDIRECT']:\n",
" from flask_sslify import SSLify\n",
" sslify = SSLify(app)\n",
" # ...\n",
"Support for SSL needs to be enabled only in production mode, and only when the\n",
"platform supports it. To make it easy to switch SSL on and off, a new configuration\n",
"variable called SSL_REDIRECT is added. The base Config class sets it to False, so that\n",
"SSL redirects are not used by default, and the class HerokuConfig overrides it so that\n",
"only on that configuration are the redirects issued. The implementation of this con‐\n",
"figuration variable is shown in Example 17-6.\n",
"The Heroku Platform \n",
"| \n",
"249\n",
"\n",
"Example 17-6. config.py: configuring the use of SSL\n",
"class Config:\n",
" # ...\n",
" SSL_REDIRECT = False\n",
"class HerokuConfig(ProductionConfig):\n",
" # ...\n",
" SSL_REDIRECT = True if os.environ.get('DYNO') else False\n",
"The value of SSL_REDIRECT in HerokuConfig is only set to True if the environment\n",
"variable DYNO exists. This variable is set by Heroku in its environment, so using the\n",
"Heroku configuration for local testing does not activate the SSL redirects.\n",
"With these changes, the users will be forced to use the SSL server when accessing the\n",
"application on Heroku—but there is one more detail that needs to be handled to\n",
"make this support complete. When using Heroku, clients do not connect to the appli‐\n",
"cation directly but to a reverse proxy server. The reverse proxy server receives requests\n",
"from many applications, and forwards them to each of them as appropriate. In this\n",
"type of setup, only the proxy server runs in SSL mode; the SSL connection is termi‐\n",
"nated at the proxy server, and applications receive the forwarded requests from the\n",
"proxy server without encryption. This presents a problem when the application needs\n",
"to generate absolute URLs, because in the Flask application the request object\n",
"describes the forwarded request, which is not encrypted, and not the original request\n",
"sent by the client through an encrypted connection.\n",
"An example of the problem this can cause is with the generation of account confirma‐\n",
"tion or password reset links that are sent by email to users. When url_for() is called\n",
"with _external=True to generate an absolute URL for these links, Flask will use\n",
"http:// for them, because it does not know that there is a reverse proxy that is accept‐\n",
"ing encrypted connections from the outside.\n",
"Proxy servers pass information that describes the original request from the client to\n",
"the redirected web servers through custom HTTP headers, so it is possible to deter‐\n",
"mine whether the user is communicating with the application over SSL by looking at\n",
"these headers. Werkzeug provides a WSGI middleware that checks the custom head‐\n",
"ers from the proxy server and updates the request object accordingly so that, for\n",
"example, request.is_secure reflects the encryption state of the request that the cli‐\n",
"ent sent to the reverse proxy server and not the request that the proxy server then\n",
"forwarded to the application. Example 17-7 shows how to add the ProxyFix middle‐\n",
"ware to the application.\n",
"250 \n",
"| \n",
"Chapter 17: Deployment\n",
"\n",
"Example 17-7. config.py: adding support for proxy servers\n",
"class HerokuConfig(ProductionConfig):\n",
" # ...\n",
" @classmethod\n",
" def init_app(cls, app):\n",
" # ...\n",
" # handle reverse proxy server headers\n",
" from werkzeug.contrib.fixers import ProxyFix\n",
" app.wsgi_app = ProxyFix(app.wsgi_app)\n",
"The middleware is added in the initialization method for the Heroku configuration.\n",
"WSGI middlewares such as ProxyFix are added by wrapping the WSGI application.\n",
"When a request comes, the middlewares get a chance to inspect the environment and\n",
"make changes before the request is processed. The ProxyFix middleware is necessary\n",
"not only for Heroku but in any deployment that uses a reverse proxy server.\n",
"Running a production web server\n",
"Heroku expects applications to start their own production web server and configure\n",
"it to listen to requests on the port number set in the environment variable PORT.\n",
"The development web server that comes with Flask will perform very poorly in this\n",
"situation because it is not designed to run in a production environment. Two \n",
"production-ready web servers that work well with Flask applications are Gunicorn\n",
"and uWSGI.\n",
"It is a good idea to install the chosen web server in the local virtual environment, so\n",
"that it can be tested in a way similar to how it will run in the Heroku environment.\n",
"For example, Gunicorn is installed as follows:\n",
"(venv) $ pip install gunicorn\n",
"To run the application locally under Gunicorn, use the following command:\n",
"(venv) $ gunicorn flasky:app\n",
"[2017-08-03 23:54:36 -0700] [INFO] Starting gunicorn 19.7.1\n",
"[2017-08-03 23:54:36 -0700] [INFO] Listening at: http://127.0.0.1:8000 (68982)\n",
"[2017-08-03 23:54:36 -0700] [INFO] Using worker: sync\n",
"[2017-08-03 23:54:36 -0700] [INFO] Booting worker with pid: 68985\n",
"The flasky:app argument tells Gunicorn where the application instance is located.\n",
"The name given before the colon is the package or module that defines this instance,\n",
"while the name after the colon is the actual application instance name. Note that\n",
"Gunicorn uses port 8000 by default, not 5000 like Flask. Like the Flask development\n",
"web server, you can exit Gunicorn with Ctrl+C.\n",
"The Heroku Platform \n",
"| \n",
"251\n",
"\n",
"The Gunicorn web server does not work on Microsoft Windows.\n",
"The other recommended web server, uWSGI, does work on Win‐\n",
"dows, but it can be difficult to install due to it being written in\n",
"native code. If you want to test the Heroku deployment on your\n",
"Windows system, you can use Waitress, which is another pure\n",
"Python web server that is in many ways similar to Gunicorn but\n",
"has the advantage that it fully supports Windows. Waitress is\n",
"installed with pip:\n",
"(venv) $ pip install waitress\n",
"To start the Waitress web server, use the waitress-serve com‐\n",
"mand:\n",
"(venv) $ waitress-serve --port 8000 flasky:app\n",
"Adding a Procfile\n",
"Heroku needs to know what command to use to start the application. This command\n",
"is given in a special file called Procfile. This file must be included in the top-level\n",
"directory of the application.\n",
"Example 17-8 shows the contents of this file.\n",
"Example 17-8. Procfile: Heroku Procfile\n",
"web: gunicorn flasky:app\n",
"The format for the Procfile is very simple: in each line a task name is given, followed\n",
"by a colon and then the command that runs the task. The task name web is special; it\n",
"is recognized by Heroku as the task that starts the web server. Heroku will give this\n",
"task a PORT environment variable set to the port on which the application needs to\n",
"listen for requests. Gunicorn by default honors the PORT variable if it is set in the\n",
"environment, so there is no need to include it in the startup command.\n",
"If you are using Microsoft Windows, or need your application to be\n",
"fully compatible with that platform, you can instead use the Wait‐\n",
"ress web server:\n",
"web: waitress-serve --port=$PORT flasky:app\n",
"Applications can declare additional tasks with names other than\n",
"web in the Procfile. Each task included in the Procfile will be started\n",
"on its own dyno.\n",
"252 \n",
"| \n",
"Chapter 17: Deployment\n",
"\n",
"If you have cloned the application’s Git repository on GitHub, you\n",
"can run git checkout 17c to check out this version of the applica‐\n",
"tion. If you are using Microsoft Windows, run git checkout 17c-\n",
"waitress to check out a version of the application configured to\n",
"use the Waitress web server instead of Gunicorn.\n",
"Testing with Heroku Local\n",
"The Heroku CLI includes the local command, used to run the application locally in\n",
"a very similar way to how it runs on the Heroku servers. However, environment vari‐\n",
"ables such as FLASK_APP are not available when running the application locally. The\n",
"heroku local command looks for environment variables that configure the applica‐\n",
"tion in a file named .env in the top-level directory of the application. For example,\n",
"the .env file can contain the following variables:\n",
"FLASK_APP=flasky.py\n",
"FLASK_CONFIG=heroku\n",
"MAIL_USERNAME=<your-gmail-username>\n",
"MAIL_PASSWORD=<your-gmail-password>\n",
"Because the .env file contains passwords and other sensitive\n",
"account information, it should never be added to source control.\n",
"Before the application can be started, the deployment task needs to be executed to set\n",
"up the database. One-off tasks can be executed with the local:run command:\n",
"(venv) $ heroku local:run flask deploy\n",
"[OKAY] Loaded ENV .env File as KEY=VALUE Format\n",
"INFO Context impl SQLiteImpl.\n",
"INFO Will assume non-transactional DDL.\n",
"INFO Running upgrade -> 38c4e85512a9, initial migration\n",
"INFO Running upgrade 38c4e85512a9 -> 456a945560f6, login support\n",
"INFO Running upgrade 456a945560f6 -> 190163627111, account confirmation\n",
"INFO Running upgrade 190163627111 -> 56ed7d33de8d, user roles\n",
"INFO Running upgrade 56ed7d33de8d -> d66f086b258, user information\n",
"INFO Running upgrade d66f086b258 -> 198b0eebcf9, caching of avatar hashes\n",
"INFO Running upgrade 198b0eebcf9 -> 1b966e7f4b9e, post model\n",
"INFO Running upgrade 1b966e7f4b9e -> 288cd3dc5a8, rich text posts\n",
"INFO Running upgrade 288cd3dc5a8 -> 2356a38169ea, followers\n",
"INFO Running upgrade 2356a38169ea -> 51f5ccfba190, comments\n",
"The Heroku Platform \n",
"| \n",
"253\n",
"\n",
"The heroku local command reads the Procfile and executes the tasks defined by it:\n",
"(venv) $ heroku local\n",
"[OKAY] Loaded ENV .env File as KEY=VALUE Format\n",
"11:37:49 AM web.1 | [INFO] Starting gunicorn 19.7.1\n",
"11:37:49 AM web.1 | [INFO] Listening at: http://0.0.0.0:5000 (91686)\n",
"11:37:49 AM web.1 | [INFO] Using worker: sync\n",
"11:37:49 AM web.1 | [INFO] Booting worker with pid: 91689\n",
"The logging output of all the tasks started by this command is consolidated into a sin‐\n",
"gle stream that is printed to the console, with each line prefixed with a timestamp and\n",
"the task name.\n",
"The heroku local command also allows simulation of the use of multiple dynos to\n",
"scale the application. The following command starts three web workers, each listen‐\n",
"ing on a different port:\n",
"(venv) $ heroku local web=3\n",
"Deploying with git push\n",
"The final step in the process is to upload the application to the Heroku servers. Make\n",
"sure that all the changes are committed to the local Git repository and then use git\n",
"push heroku master to upload the application to the heroku remote:\n",
"$ git push heroku master\n",
"Counting objects: 502, done.\n",
"Delta compression using up to 8 threads.\n",
"Compressing objects: 100% (426/426), done.\n",
"Writing objects: 100% (502/502), 108.03 KiB | 0 bytes/s, done.\n",
"Total 502 (delta 303), reused 146 (delta 61)\n",
"remote: Compressing source files... done.\n",
"remote: Building source:\n",
"remote:\n",
"remote: -----> Python app detected\n",
"remote: -----> Installing python-3.6.2\n",
"remote: -----> Installing pip\n",
"remote: -----> Installing requirements with pip\n",
"...\n",
"remote: -----> Discovering process types\n",
"remote: Procfile declares types -> web\n",
"remote:\n",
"remote: -----> Compressing...\n",
"remote: Done: 49.4M\n",
"remote: -----> Launching...\n",
"remote: Released v8\n",
"remote: https://<appname>.herokuapp.com/ deployed to Heroku\n",
"remote:\n",
"remote: Verifying deploy... done.\n",
"To https://git.heroku.com/<appname>.git\n",
" * [new branch] master -> master\n",
"254 \n",
"| \n",
"Chapter 17: Deployment\n",
"\n",
"The application is now deployed and running, but it is not going to work correctly\n",
"because the deploy command that initializes the database tables has not been exe‐\n",
"cuted yet. The Heroku client can run this command as follows:\n",
"$ heroku run flask deploy\n",
"Running flask deploy on <appname>... up, run.3771 (Free)\n",
"INFO [alembic.runtime.migration] Context impl PostgresqlImpl.\n",
"INFO [alembic.runtime.migration] Will assume transactional DDL.\n",
"...\n",
"After the database tables are created and configured, the application can be restarted\n",
"so that it starts cleanly with an updated database:\n",
"$ heroku restart\n",
"Restarting dynos on <appname>... done\n",
"The application should now be fully deployed and online at https://<appname>.hero‐\n",
"kuapp.com.\n",
"Reviewing application logs\n",
"The logging output generated by the application is captured by Heroku. To view the\n",
"contents of the log, use the logs command:\n",
"$ heroku logs\n",
"During testing it can also be convenient to “tail” the log file, which can be done as\n",
"follows:\n",
"$ heroku logs -t\n",
"Deploying an Upgrade\n",
"When a Heroku application needs to be upgraded the same process needs to be\n",
"repeated. After all the changes have been committed to the Git repository, the follow‐\n",
"ing commands perform an upgrade:\n",
"$ heroku maintenance:on\n",
"$ git push heroku master\n",
"$ heroku run flask deploy\n",
"$ heroku restart\n",
"$ heroku maintenance:off\n",
"The maintenance option available on the Heroku CLI will take the application offline\n",
"during the upgrade and will show a static page that informs users that the site will be\n",
"coming back soon. This prevents users from accessing the application while it is\n",
"going through the upgrade process.\n",
"The Heroku Platform \n",
"| \n",
"255\n",
"\n",
"Docker Containers\n",
"You are now familiar with Heroku, which is a fairly high-level deployment option. In\n",
"this section you will learn how to work with containers, and in particular with the\n",
"Docker platform, which is not as automated as a PaaS but provides more flexibility\n",
"and is not tied to a specific cloud provider.\n",
"Containers are a special type of virtual machine that run on top of the kernel of the\n",
"host operating system, unlike standard virtual machines, which have their own vir‐\n",
"tualized kernel and hardware. Because the virtualization stops at the kernel, contain‐\n",
"ers are much more lightweight and efficient than virtual machines, but they require\n",
"dedicated support built into the operating system. The Linux kernel has full support\n",
"for containers.\n",
"Installing Docker\n",
"The most popular container platform is Docker, which has a free Community Edition\n",
"(known as Docker CE) and a subscription-based Enterprise Edition (Docker EE).\n",
"Docker can be installed on the three major desktop operating systems, and also on\n",
"cloud servers. The easiest way to develop and test a “containerized” application is to\n",
"install Docker CE on your development system. For macOS and Microsoft Windows\n",
"there are one-click installers available from the Docker Store. This page also includes\n",
"installation instructions for CentOS, Fedora, Debian, and Ubuntu Linux distribu‐\n",
"tions.\n",
"After you complete the installation of Docker CE on your system, you should be able\n",
"to access the docker command from your terminal:\n",
"$ docker version\n",
"Client:\n",
" Version: 17.06.0-ce\n",
" API version: 1.30\n",
" Go version: go1.8.3\n",
" Git commit: 02c1d87\n",
" Built: Fri Jun 23 21:31:53 2017\n",
" OS/Arch: darwin/amd64\n",
"Server:\n",
" Version: 17.06.0-ce\n",
" API version: 1.30 (minimum version 1.12)\n",
" Go version: go1.8.3\n",
" Git commit: 02c1d87\n",
" Built: Fri Jun 23 21:51:55 2017\n",
" OS/Arch: linux/amd64\n",
" Experimental: true\n",
"256 \n",
"| \n",
"Chapter 17: Deployment\n",
"\n",
"Docker for Windows requires Microsoft’s Hyper-V feature to be\n",
"enabled. The installer will normally enable it for you, but if Docker\n",
"does not appear to work correctly after installation, the state of the\n",
"Hyper-V hypervisor is the first thing to check. You should keep in\n",
"mind that enabling Hyper-V on your Windows machine will pre‐\n",
"vent other hypervisors (such as Oracle’s VirtualBox) from working.\n",
"If your system does not support Hyper-V virtualization, or you\n",
"need a Docker solution that does not render other virtualization\n",
"technologies unusable, you may want to install Docker Toolbox, a\n",
"legacy Docker product for Windows that is based on VirtualBox.\n",
"Building a Container Image\n",
"The first task when working with containers is to build a container image for the\n",
"application. An image is a snapshot of a container’s filesystem, used as a template\n",
"when starting new containers. Docker expects the instructions to create the image to\n",
"be provided in a file named Dockerfile. Example 17-9 shows a Dockerfile that builds\n",
"the application featured in this book.\n",
"Example 17-9. Dockerfile: container image build script\n",
"FROM python:3.6-alpine\n",
"ENV FLASK_APP flasky.py\n",
"ENV FLASK_CONFIG docker\n",
"RUN adduser -D flasky\n",
"USER flasky\n",
"WORKDIR /home/flasky\n",
"COPY requirements requirements\n",
"RUN python -m venv venv\n",
"RUN venv/bin/pip install -r requirements/docker.txt\n",
"COPY app app\n",
"COPY migrations migrations\n",
"COPY flasky.py config.py boot.sh ./\n",
"# runtime configuration\n",
"EXPOSE 5000\n",
"ENTRYPOINT [\"./boot.sh\"]\n",
"The build commands that can be included in a Dockerfile are documented in detail in\n",
"the Dockerfile reference. In essence, these are deployment commands that install and\n",
"configure the application in the container’s filesystem, which is isolated from your\n",
"system.\n",
"Docker Containers \n",
"| \n",
"257\n",
"\n",
"The FROM command is required in all Dockerfiles to specify a base container image to\n",
"start from. In most cases, this is going to be an image that is publicly available in\n",
"Docker Hub, Docker’s container image repository. The repository contains official\n",
"images for several Python interpreter versions. These are images that have a base\n",
"operating system with Python installed on it. Images are specified with a name and a\n",
"tag. The name of the official Docker Hub Python image is simply python. The differ‐\n",
"ent tags that are available can be seen in the Docker Hub page for the image. For the\n",
"python image, tags are used to specify the desired interpreter version and platform.\n",
"For this application, a 3.6 interpreter built on top of the Alpine Linux distribution is\n",
"used. Alpine Linux is a platform commonly used in container images due to its small\n",
"size.\n",
"The macOS and Windows versions of Docker are able to run\n",
"Linux-based containers.\n",
"The ENV command defines runtime environment variables. This command takes two\n",
"arguments: a variable name and its value. Any environment variables defined with\n",
"this command will be available when a container based on this image is executed. The\n",
"FLASK_APP variable required by the flask command is defined here, as is\n",
"FLASK_CONFIG, which is the name of the configuration class the application uses to\n",
"configure itself when it starts. The Docker deployment will use a new configuration\n",
"called docker, implemented in a DockerConfig class as shown in Example 17-10. This\n",
"new configuration class inherits from ProductionConfig and just configures logging\n",
"to be directed to stderr, which Docker automatically captures and exposes through\n",
"the docker logs command.\n",
"Example 17-10. config.py: Docker configuration\n",
"class DockerConfig(ProductionConfig):\n",
" @classmethod\n",
" def init_app(cls, app):\n",
" ProductionConfig.init_app(app)\n",
" # log to stderr\n",
" import logging\n",
" from logging import StreamHandler\n",
" file_handler = StreamHandler()\n",
" file_handler.setLevel(logging.INFO)\n",
" app.logger.addHandler(file_handler)\n",
"config = {\n",
" # ...\n",
"258 \n",
"| \n",
"Chapter 17: Deployment\n",
"\n",
" 'docker': DockerConfig,\n",
" # ...\n",
"}\n",
"The RUN command executes a command in the context of the container image. In the\n",
"first occurrence of RUN, a flasky user is created inside the container. The adduser com‐\n",
"mand is part of Alpine Linux, and is available in the base image selected by the FROM\n",
"command. The -D argument to adduser suppresses an interactive prompt for the\n",
"user’s password.\n",
"The USER command selects the user under which the container will run, and also the\n",
"user for the remaining commands in the Dockerfile. Docker uses the root user by\n",
"default, but it is considered a good practice to switch to a regular user when root\n",
"access isn’t needed.\n",
"The WORKDIR command defines the top-level directory where the application is going\n",
"to be installed. For this application, the home directory for the newly created flasky\n",
"user is used. The remaining commands in the Dockerfile will execute with this direc‐\n",
"tory as the current directory.\n",
"The COPY command copies files from the local filesystem to the container’s filesystem.\n",
"The requirements, app, and migrations directories are copied in their entirety, and\n",
"then the top-level flasky.py, config.py, and new boot.sh files (discussed shortly) are\n",
"copied as well.\n",
"The two additional RUN commands create a virtual environment and install the\n",
"requirements in it. A dedicated requirements file was created for Docker as require‐\n",
"ments/docker.txt. This file imports all the dependencies from requirements/\n",
"common.txt and adds Gunicorn, which will be used as a web server as in the Heroku\n",
"deployment.\n",
"The EXPOSE command defines the port on which the application running inside the\n",
"container will install its server. When the container is started, Docker will map this\n",
"port to a real port on the host machine, so that the container can receive requests\n",
"from the outside world.\n",
"The final command is ENTRYPOINT. This command specifies how to execute the appli‐\n",
"cation when the container is started. The new boot.sh file, copied into the container\n",
"above, is used as the startup script. Example 17-11 shows the contents of this file.\n",
"Example 17-11. boot.sh: container startup script\n",
"#!/bin/sh\n",
"source venv/bin/activate\n",
"flask deploy\n",
"exec gunicorn -b 0.0.0.0:5000 --access-logfile - --error-logfile - flasky:app\n",
"Docker Containers \n",
"| \n",
"259\n",
"\n",
"The script starts by activating the venv virtual environment that was created as part of\n",
"the build. Then it runs the application’s deploy command, built earlier in this chapter\n",
"and also used for the Heroku deployment. This will create a new database, upgrade it\n",
"to the latest version, and insert the default roles. Because the DATABASE_URL environ‐\n",
"ment variable hasn’t been set, the database will use the SQLite engine. Then a Guni‐\n",
"corn server listening on port 5000 is started. Docker captures all the output from the\n",
"application and presents it as logs, so Gunicorn is configured to write both its access\n",
"and error log files to standard output. Starting Gunicorn with exec makes the Guni‐\n",
"corn process take over the process running the boot.sh file. This is done because\n",
"Docker pays special attention to the process that starts a container, and expects it to\n",
"be the main process throughout its life. When this process ends, the container ends as\n",
"well.\n",
"If you have cloned the application’s Git repository on GitHub, you\n",
"can run git checkout 17d to check out this version of the applica‐\n",
"tion.\n",
"A container image for Flasky can now be built as follows:\n",
"$ docker build -t flasky:latest .\n",
"Sending build context to Docker daemon 51.08MB\n",
"Step 1/14 : FROM python:3.6-alpine\n",
" ---> a6beab4fa70b\n",
"...\n",
"Successfully built 930e17a89b42\n",
"Successfully tagged flasky:latest\n",
"The -t argument to docker build gives a name and tag to the container image, sepa‐\n",
"rated by a colon. The latest tag name is typically used for the most up-to-date ver‐\n",
"sion of a container image. The dot at the end of the build command sets the current\n",
"directory as the top-level directory during the build. Docker will look for the Docker‐\n",
"file in this directory, and will also make the files in this directory and all sub-\n",
"directories available to be added to the container image.\n",
"As a result of a successful docker build command, the built container image is\n",
"stored in a local image repository. The docker images command shows the contents\n",
"of the image repository on your system:\n",
"$ docker images\n",
"REPOSITORY TAG IMAGE ID CREATED SIZE\n",
"flasky latest 930e17a89b42 5 minutes ago 127MB\n",
"python 3.6-alpine a6beab4fa70b 3 weeks ago 88.7MB\n",
"260 \n",
"| \n",
"Chapter 17: Deployment\n",
"\n",
"This listing includes the just-built flasky:latest image and also the base Python 3.6\n",
"interpreter image referenced in the FROM Dockerfile, which Docker downloads and\n",
"installs as part of the build.\n",
"Running a Container\n",
"Once a container image for the application is built, all that remains is to run it. The\n",
"docker run command makes this a very simple task:\n",
"$ docker run --name flasky -d -p 8000:5000 \\\n",
" -e SECRET_KEY=57d40f677aff4d8d96df97223c74d217 \\\n",
" -e MAIL_USERNAME=<your-gmail-username> \\\n",
" -e MAIL_PASSWORD=<your-gmail-password> flasky:latest\n",
"The --name option gives the container a name. Naming containers is optional; if a\n",
"name is not given, Docker generates one using randomly selected words.\n",
"The -d option starts the container in detached mode, which means that the container\n",
"will run in the background on your system. A container that is not detached runs as a\n",
"foreground task attached to the console session.\n",
"The -p option maps port 8000 in the host system to port 5000 inside the container.\n",
"Docker provides the flexibility of mapping container ports to any port in the host sys‐\n",
"tem. This mapping enables two or more instances of the same container image to run\n",
"on different host ports, while each instance uses its own virtualized port 5000.\n",
"The -e option defines environment variables that are going to exist in the context of\n",
"the container, in addition to any variables defined at build time with the ENV com‐\n",
"mand in the Dockerfile. The value assigned to the SECRET_KEY variable ensures that\n",
"user sessions and tokens are signed with a unique and very hard to guess key. You\n",
"should generate your own unique key for this variable. The values for the\n",
"MAIL_USERNAME and MAIL_PASSWORD variables configure email sending through the\n",
"Gmail service. For a production deployment that uses a different email service pro‐\n",
"vider the MAIL_SERVER, MAIL_PORT, and MAIL_USE_TLS variables should be defined as\n",
"well.\n",
"The final argument in the docker run command is the container image and tag to\n",
"execute. This should match the name and tag given as the -t option to the docker\n",
"build command.\n",
"When the container starts in the background, the docker run command prints the\n",
"container ID to the console. This is a 256-bit unique identifier printed in hexadecimal\n",
"notation. This ID can be used in any commands that require a reference to a con‐\n",
"tainer (in practice, only the first few characters of the ID need to be provided, such\n",
"that the container can be uniquely identified).\n",
"Docker Containers \n",
"| \n",
"261\n",
"\n",
"To confirm that the container is running, the docker ps command can be used:\n",
"$ docker ps\n",
"CONTAINER ID IMAGE CREATED STATUS PORTS NAMES\n",
"71357ee776ae flasky:latest 4 secs ago Up 8 secs 0.0.0.0:8000->5000/tcp flasky\n",
"Since the container is now up and running, you can access the containerized applica‐\n",
"tion on port 8000 of your system, either locally as http://localhost:8000 or from any\n",
"other computer in the network as http://<ip-address>:8000.\n",
"To stop this container, use the docker stop command:\n",
"$ docker stop 71357ee776ae\n",
"71357ee776ae\n",
"The stop command stops the container but does not remove it from the system. To\n",
"remove it, use the docker rm command:\n",
"$ docker rm 71357ee776ae\n",
"71357ee776ae\n",
"These two operations can be combined into one with docker rm -f:\n",
"$ docker rm -f 71357ee776ae\n",
"71357ee776ae\n",
"Inspecting a Running Container\n",
"When a container appears to misbehave, it might be necessary to debug it. The most\n",
"obvious debugging mechanism is to add logging statements to the application and\n",
"then monitor the running container with the docker logs command.\n",
"In some situations, however, it might be more convenient to open a shell session on\n",
"the running container so that it can be inspected more closely. The docker exec\n",
"command makes this possible:\n",
"$ docker exec -it 71357ee776ae sh\n",
"In this example, Docker is going to open a shell session with sh (the Unix shell)\n",
"without interrupting the container. The -it options connect the terminal session\n",
"from which the command is issued to the new process, so that the shell can be oper‐\n",
"ated interactively. If the container includes other, more advanced shells such as bash\n",
"or even a Python interpreter, they can be used as well.\n",
"A common strategy when troubleshooting containers is to create a special image\n",
"loaded with additional tools such as a debugger that can later be invoked from a shell\n",
"session.\n",
"262 \n",
"| \n",
"Chapter 17: Deployment\n",
"\n",
"Pushing Your Container Image to an External Registry\n",
"Having a container image locally is convenient when developing and testing an appli‐\n",
"cation, but when you are ready to share the image with others, you have to push it to\n",
"an external registry server.\n",
"The Docker Hub registry is Docker’s image repository, a convenient service where\n",
"you can host your images. A free Docker Hub account allows you to store an unlimi‐\n",
"ted number of public container images, but only one private image. Paid plans\n",
"increase the number of private images you can host. To create your Docker Hub\n",
"account, go to https://hub.docker.com.\n",
"Once you have a Docker Hub account, you can log in to it from the command line\n",
"with the docker login command:\n",
"$ docker login\n",
"Login with your Docker ID to push and pull images from Docker Hub.\n",
"Username: <your-dockerhub-username>\n",
"Password: <your-dockerhub-password>\n",
"Login Succeeded\n",
"To log in to a container image repository other than Docker Hub,\n",
"pass the address of your repository as an argument to docker\n",
"login.\n",
"Local container images are given a simple name. To prepare to push an image to\n",
"Docker Hub, the image name must be prefixed with the Docker Hub account name\n",
"and a slash as a separator. The flasky:latest image built earlier can be given a sec‐\n",
"ondary name properly formatted for pushing to Docker Hub with the docker tag\n",
"command:\n",
"$ docker tag flasky:latest <your-dockerhub-username>/flasky:latest\n",
"To upload the image to Docker Hub, use the docker push command:\n",
"$ docker push <your-dockerhub-username>/flasky:latest\n",
"The container image is now publicly available, and anybody can start a container\n",
"based on it with the docker run command:\n",
"$ docker run --name flasky -d -p 8000:5000 \\\n",
"<your-dockerhub-username>/flasky:latest\n",
"Docker Containers \n",
"| \n",
"263\n",
"\n",
"Using an External Database\n",
"One disadvantage of the way Flasky was deployed as a Docker container is that the\n",
"default SQLite database lives in the same container as the application. This makes it\n",
"very difficult to perform an upgrade, because once a running container is stopped,\n",
"the database is gone with it.\n",
"A better approach is to host the database server separately from the application con‐\n",
"tainer. That makes upgrading the application while preserving the database an easy\n",
"task, since all that is needed is to replace the application container with a new one.\n",
"Docker promotes a modular approach to building an application, in which each ser‐\n",
"vice is hosted in its own container. There are public container images available for\n",
"MySQL, Postgres, and many other database servers. The docker run command can\n",
"be used to deploy any of these directly to your system. The following command\n",
"deploys a MySQL 5.7 database server to your system:\n",
"$ docker run --name mysql -d -e MYSQL_RANDOM_ROOT_PASSWORD=yes \\\n",
" -e MYSQL_DATABASE=flasky -e MYSQL_USER=flasky \\\n",
" -e MYSQL_PASSWORD=<database-password> \\\n",
" mysql/mysql-server:5.7 \n",
"This command creates a container named mysql that runs in the background. The -e\n",
"option assigns a few environment variables that this container takes as configuration.\n",
"These and many other variables are documented in the Docker Hub page for the\n",
"MySQL image. The preceding command configures the database with a randomly\n",
"generated root password (use docker logs mysql right after starting the container to\n",
"see the assigned password in the logs), and with a brand-new database called flasky\n",
"that is configured to be accessed by a user named flasky as well. You need to provide a\n",
"secure password for this user as a value for the MYSQL_PASSWORD environment vari‐\n",
"able.\n",
"To be able to connect to a MySQL database, SQLAlchemy requires a supported\n",
"MySQL client package such as pymysql to be installed. This package can be added to\n",
"the docker.txt requirements file.\n",
"If you have cloned the application’s Git repository on GitHub, you\n",
"can run git checkout 17e to check out this version of the applica‐\n",
"tion.\n",
"The change made to the requirements/docker.txt file requires the container image to\n",
"be rebuilt:\n",
"$ docker build -t flasky:latest .\n",
"264 \n",
"| \n",
"Chapter 17: Deployment\n",
"\n",
"If you are still running the previous application container, stop it and remove it with\n",
"docker rm -f. Then start a new container with the updated application:\n",
"$ docker run -d -p 8000:5000 --link mysql:dbserver \\\n",
" -e DATABASE_URL=mysql+pymysql://flasky:<database-password>@dbserver/flasky \\\n",
" -e MAIL_USERNAME=<your-gmail-username> -e MAIL_PASSWORD=<your-gmail-password> \\\n",
" flasky:latest\n",
"There are two additions to the docker run command shown here. The --link option\n",
"configures a connection between the new container and another existing one. The\n",
"argument to --link consists of two names separated by a colon: the source container\n",
"name or ID, and an alias for that container in the container being created. In this\n",
"example the source container is mysql, the database container started earlier. This\n",
"container is going to be accessible in the new Flasky container with the dbserver\n",
"hostname.\n",
"To complete the configuration, a DATABASE_URL environment variable is added, with a\n",
"connection URL that points to the flasky database in the mysql container. The\n",
"dbserver alias is used as the database host, as Docker makes sure that this name\n",
"resolves to the IP address of the linked container. The value of the MYSQL_PASSWORD\n",
"environment variable set in the mysql container must be included in the connection\n",
"URL for this container as well. The value of DATABASE_URL overrides the default\n",
"SQLite database, so with this simple change the container will be configured to con‐\n",
"nect to the MySQL database.\n",
"The Docker Hub repository is a gold mine of very useful applica‐\n",
"tions and services that are packaged and ready to use in a Docker\n",
"environment, either standalone or as base images for your own\n",
"containers. You will find that all sorts of projects (including data‐\n",
"bases, web servers, load balancers, programming languages, operat‐\n",
"ing systems, and more) offer official images.\n",
"Container Orchestration with Docker Compose\n",
"Containerized applications are usually composed of several running containers. You\n",
"have seen in the previous section that the main application and the database server\n",
"run in independent containers. As the application grows in complexity, it will invaria‐\n",
"bly need more containers. Some applications are going to require additional services,\n",
"such as message queues or caches. Other applications may take advantage of a micro‐\n",
"services architecture and have a distributed structure with several smaller sub-\n",
"applications, each running in its own container. Applications that have to handle high\n",
"loads or need to be fault-tolerant will want to scale out by running several instances\n",
"behind a load balancer.\n",
"Docker Containers \n",
"| \n",
"265\n",
"\n",
"As the number of containers that are part of the application increases, the task of\n",
"managing and coordinating all these containers is going to become much harder if\n",
"Docker alone is used. Container orchestration frameworks built on top of Docker help\n",
"with this task.\n",
"The Compose toolset provides basic orchestration functionality, included with the\n",
"Docker installation. With Compose, the containers that are part of an application are\n",
"described in a configuration file, typically named docker-compose.yml. The docker-\n",
"compose command can then start all the containers associated with the application\n",
"using a single command.\n",
"Example 17-12 shows a docker-compose.yml file that represents the containerized Fla‐\n",
"sky along with its MySQL service.\n",
"Example 17-12. docker-compose.yml: compose configuration\n",
"version: '3'\n",
"services:\n",
" flasky:\n",
" build: .\n",
" ports:\n",
" - \"8000:5000\"\n",
" env_file: .env\n",
" links:\n",
" - mysql:dbserver\n",
" restart: always\n",
" mysql:\n",
" image: \"mysql/mysql-server:5.7\"\n",
" env_file: .env-mysql\n",
" restart: always\n",
"This file is written in YAML, which is a clean and simple format that can represent\n",
"hierarchical structures that are composed of key-value maps and lists. The version\n",
"key specifies which version of Compose is used, and the services key defines the\n",
"containers of the application as its children. In the case of Flasky, these are two serv‐\n",
"ices named flasky and mysql.\n",
"For services such as flasky, which are built as part of the application, the subkeys\n",
"specify the arguments that are given to the docker build and docker run com‐\n",
"mands. The build key specifies the build directory, where the Dockerfile is located.\n",
"The ports key specifies the network port mappings. The env_file key is a conve‐\n",
"nient way to define several environment variables that the container needs. The links\n",
"key establishes a link to the MySQL container, by exposing it with the hostname\n",
"dbserver. The restart key set to always provides a simple way for Docker to auto‐\n",
"matically restart the container if it exits unexpectedly. The .env file for this deploy‐\n",
"ment should have the following variables in it:\n",
"266 \n",
"| \n",
"Chapter 17: Deployment\n",
"\n",
"FLASK_APP=flasky.py\n",
"FLASK_CONFIG=docker\n",
"SECRET_KEY=3128b4588e7f4305b5501025c13ceca5\n",
"MAIL_USERNAME=<your-gmail-username>\n",
"MAIL_PASSWORD=<your-gmail-password>\n",
"DATABASE_URL=mysql+pymysql://flasky:<database-password>@dbserver/flasky\n",
"The mysql service has a simpler structure, because this is a service that is started from\n",
"a stock image that does not require a build step. The image key specifies the name\n",
"and tag of the container image to use for this service. As with the docker run com‐\n",
"mand, Docker will download this image from the container image registry. The\n",
"env_file and restart keys are similar to those used in the flasky container. Note\n",
"how the environment variables for the MySQL container are stored in a separate file\n",
"named .env-mysql. While it would be easier to add the environment variables needed\n",
"by all containers to the .env file, it is a good practice to prevent one container from\n",
"having access to the secrets of another. The .env-mysql file needs the following envi‐\n",
"ronment variables defined:\n",
"MYSQL_RANDOM_ROOT_PASSWORD=yes\n",
"MYSQL_DATABASE=flasky\n",
"MYSQL_USER=flasky\n",
"MYSQL_PASSWORD=<database-password>\n",
"The .env and .env-mysql files contain passwords and other sensitive\n",
"information, so they should never be added to source control.\n",
"A complete reference for the docker-compose.yml file is found at\n",
"“the Docker website”.\n",
"A typical problem with orchestrated systems is that containers are started in the\n",
"wrong order—or in the correct order, but without giving the containers for base serv‐\n",
"ices enough time to start and initialize before starting higher-level containers that\n",
"depend on them. In the case of Flasky, the mysql container needs to start first, so that\n",
"the database is up and running when the flasky container starts. Then it can connect\n",
"to the database, apply the database migrations, and finally start the web server.\n",
"Compose will start the mysql and flasky containers in the right order, because it will\n",
"detect the dependency between them from the links key in the flasky container. But\n",
"Compose is not going to wait for MySQL to start, which might take a few seconds.\n",
"When designing distributed systems, it is a good practice to implement retries in all\n",
"connections to external services. Example 17-13 shows how the boot.sh script that\n",
"Docker Containers \n",
"| \n",
"267\n",
"\n",
"starts the flasky container can be made more robust by retrying the flask deploy\n",
"command, which retries the database upgrade until it succeeds.\n",
"Example 17-13. boot.sh: waiting for the database to be up\n",
"#!/bin/sh\n",
"source venv/bin/activate\n",
"while true; do\n",
" flask deploy\n",
" if [[ \"$?\" == \"0\" ]]; then\n",
" break\n",
" fi\n",
" echo Deploy command failed, retrying in 5 secs...\n",
" sleep 5\n",
"done\n",
"exec gunicorn -b :5000 --access-logfile - --error-logfile - flasky:app\n",
"By running flask deploy inside a retry loop, the container will be able to tolerate\n",
"failures due to the database service not being immediately ready to accept requests.\n",
"If you have cloned the application’s Git repository on GitHub, you\n",
"can run git checkout 17f to check out this version of the applica‐\n",
"tion. Also make sure that the .env and .env-mysql environment files\n",
"are created and populated with values correct for your environ‐\n",
"ment.\n",
"Now that the Compose configuration is complete, the application can be started with\n",
"the docker-compose up command:\n",
"$ docker-compose up -d --build\n",
"The --build option to docker-compose up indicates that a build step should run\n",
"before launching the application. This will cause the flasky container image to be\n",
"built. After the image is created, the mysql and flasky containers will be started in\n",
"that order. The -d option starts the containers in detached mode, as with the single\n",
"container. After a few seconds, the application should be up and running in the back‐\n",
"ground, and you should be able to connect to it at http://localhost:8000.\n",
"Compose consolidates the logging from all the containers into a single stream, which\n",
"you can see with the docker-compose logs command:\n",
"$ docker-compose logs\n",
"Or, if you want to constantly monitor the log stream:\n",
"$ docker-compose logs -f\n",
"268 \n",
"| \n",
"Chapter 17: Deployment\n",
"\n",
"The docker-compose ps command shows a summary of all the application contain‐\n",
"ers that are running and their state:\n",
"$ docker-compose ps\n",
" Name Command State Ports\n",
"------------------------------------------------------------------------\n",
"flasky_flasky_1 ./boot.sh Up 0.0.0.0:8000->5000/tcp\n",
"flasky_mysql_1 /entrypoint.sh mysqld Up 3306/tcp, 33060/tcp\n",
"To upgrade an application to a new version, simply make the necessary changes to it\n",
"and repeat the docker-compose up command used previously to start it. Compose\n",
"will rebuild the application container if anything changed, and then replace the older\n",
"container with a fresh one.\n",
"To stop the application, use the docker-compose down command, or docker-compose\n",
"rm --stop --force if you also want to remove the stopped containers.\n",
"Cleaning Up Old Containers and Images\n",
"As you work with containers, your system will invariably accumulate old containers\n",
"or images that are not needed anymore. It is a good idea to routinely review and clean\n",
"those up, so that they don’t take up space on the system.\n",
"To see the list of containers in the system, use the following command:\n",
"$ docker ps -a\n",
"This will show containers that are running, and containers that were stopped but are\n",
"still in the system. To delete any containers from this list, use the docker rm -f com‐\n",
"mand and provide the names or IDs to remove:\n",
"$ docker rm -f <name-or-id> <name-or-id> ...\n",
"To see the list of container images stored in your system, use the docker images\n",
"command. If there are any images that you want to remove, you can do so with the\n",
"docker rmi command.\n",
"Some containers create virtual volumes on the host computer that are used for storage\n",
"outside of the container filesystem. The MySQL container image, for example, puts all\n",
"the database files in a volume. You can view a list of all the allocated volumes in your\n",
"system with docker volume ls. To remove a volume that is unused, use docker\n",
"volume rm.\n",
"If you prefer a more automatic cleanup, the docker system prune --volumes com‐\n",
"mand will remove any unused images or volumes, and any stopped containers that\n",
"are still in the system.\n",
"Docker Containers \n",
"| \n",
"269\n",
"\n",
"Using Docker in Production\n",
"Many people consider Docker a development and testing platform only. While the\n",
"techniques presented in the previous sections can be used to deploy applications on\n",
"production servers running Docker, there are some limitations and security concerns\n",
"that need to be considered:\n",
"Monitoring and alerting\n",
"What happens if a containerized application crashes? Docker can restart a con‐\n",
"tainer that exits unexpectedly, but it will not monitor your containers, nor will it\n",
"send alerts when they behave erratically.\n",
"Logging\n",
"Docker maintains a separate log stream for each container. Compose improves\n",
"this by offering a consolidated stream, but without long-term storage or search‐\n",
"ing and filtering capabilities.\n",
"Management of secrets\n",
"Configuring passwords and other credentials through environment variables is\n",
"insecure, since Docker exposes pre-configured environment variables via the\n",
"docker inspect command or through its API.\n",
"Reliability and scaling\n",
"To help with fault tolerance, or to accommodate increasing load demands, it is\n",
"necessary to run several instances of the application on several hosts and behind\n",
"one or more load balancers.\n",
"These limitations are generally addressed by more elaborated orchestration frame‐\n",
"works built on top of Docker or other container runtimes. Frameworks such as\n",
"Docker Swarm (now incorporated into Docker), Apache Mesos, and Kubernetes are\n",
"good choices for building robust container deployments.\n",
"Traditional Deployments\n",
"So far you have seen how Heroku and Docker manage deployments. To complete this\n",
"review of deployment strategies, this section will describe a traditional hosting\n",
"option, which involves buying or renting a server, either physical or virtual, and man‐\n",
"ually setting up all the required components on it. This is obviously the most labori‐\n",
"ous option of all, but it can be a convenient option when you have terminal access to\n",
"production server hardware. The following sections will give you an idea of the work\n",
"involved.\n",
"270 \n",
"| \n",
"Chapter 17: Deployment\n",
"\n",
"Server Setup\n",
"There are several administration tasks that must be performed on the server before it\n",
"can host applications:\n",
"• Install a database server such as MySQL or Postgres. Using an SQLite database is\n",
"also possible but is not recommended for a production server due to its many\n",
"limitations with regard to modification of existing database schemas.\n",
"• Install a Mail Transport Agent (MTA) such as Sendmail or Postfix to send email\n",
"out to users. Using Gmail in a production application is not possible, as this ser‐\n",
"vice has very restrictive quotas and specifically prohibits commercial use in its\n",
"terms of service.\n",
"• Install a production-ready web server such as Gunicorn or uWSGI.\n",
"• Install a process-monitoring utility such as Supervisor, that immediately restarts\n",
"the web server if it crashes or after the host is power-cycled.\n",
"• Install and configure an SSL certificate to enable secure HTTP.\n",
"• (Optional but highly recommended) Install a front-end reverse proxy web server\n",
"such as nginx or Apache. This server is configured to serve static files directly and\n",
"forward application requests into the application’s web server, which is listening\n",
"on a private port on localhost.\n",
"• Secure the server. This includes several tasks that have the goal of reducing vul‐\n",
"nerabilities in the server such as installing firewalls, removing unused software\n",
"and services, and so on.\n",
"Instead of manually performing these tasks, create a scripted\n",
"deployment using an automation framework such as Ansible, Chef,\n",
"or Puppet.\n",
"Importing Environment Variables\n",
"Similarly to Heroku and Docker, an application running on a standalone server relies\n",
"on certain settings such as the database connection URL, email server credentials, etc.\n",
"being provided in environment variables.\n",
"Because there is no Heroku or Docker to configure these variables before the applica‐\n",
"tion starts, the procedure to set the variables is dependent on the platform and tools\n",
"used. To make the configuration of environment variables easier and uniform across\n",
"deployment platforms, the short code block in Example 17-14 imports into the envi‐\n",
"ronment a .env file similar to the one used with the heroku local and docker-\n",
"Traditional Deployments \n",
"| \n",
"271\n",
"\n",
"compose commands, using a Python package called python-dotenv that needs to be\n",
"installed with pip. This is done in flasky.py before the application instance is created,\n",
"so that by the time the configuration is imported these variables are accessible in the\n",
"environment.\n",
"Example 17-14. flasky.py: importing the environment from the .env file\n",
"import os\n",
"from dotenv import load_dotenv\n",
"dotenv_path = os.path.join(os.path.dirname(__file__), '.env')\n",
"if os.path.exists(dotenv_path):\n",
" load_dotenv(dotenv_path)\n",
"The .env file can define the FLASK_CONFIG variable that selects the configuration to\n",
"use, the DATABASE_URL connection, the email server credentials, etc. As explained\n",
"before, a .env file should not be added to source control due to the sensitive nature of\n",
"some of the items in it.\n",
"If you created a .env file for use with Heroku or Docker, review it\n",
"and adjust it appropriately, because with the changes just made, the\n",
"application will import the variables defined in this file for all con‐\n",
"figurations.\n",
"Setting Up Logging\n",
"For Unix-based servers, logging can be sent to the syslog daemon. A new configura‐\n",
"tion specifically for Unix can be created as a subclass of ProductionConfig, as shown\n",
"in Example 17-15.\n",
"Example 17-15. config.py: Unix example configuration\n",
"class UnixConfig(ProductionConfig):\n",
" @classmethod\n",
" def init_app(cls, app):\n",
" ProductionConfig.init_app(app)\n",
" # log to syslog\n",
" import logging\n",
" from logging.handlers import SysLogHandler\n",
" syslog_handler = SysLogHandler()\n",
" syslog_handler.setLevel(logging.WARNING)\n",
" app.logger.addHandler(syslog_handler)\n",
"With this configuration, application logs will be written to the configured syslog mes‐\n",
"sages file, typically /var/log/messages or /var/log/syslog depending on the Linux distri‐\n",
"272 \n",
"| \n",
"Chapter 17: Deployment\n",
"\n",
"bution. The syslog service can be configured to write a separate log file for application\n",
"logs, or to send the logs to a different machine if desired.\n",
"If you have cloned the application’s Git repository on GitHub, you\n",
"can run git checkout 17g to check out this version of the applica‐\n",
"tion.\n",
"Traditional Deployments \n",
"| \n",
"273\n",
"\n",
"\n",
"CHAPTER 18\n",
"Additional Resources\n",
"You are pretty much done with this book. Congratulations! I hope the topics that I\n",
"have covered have given you a solid base to begin building your own applications\n",
"with Flask. The code examples are open source and have a permissive license, so you\n",
"are welcome to use as much of my code as you want to seed your projects, even if\n",
"they are of a commercial nature. In this short final chapter, I want to give you a list of\n",
"additional tips and resources that might be useful as you continue working with\n",
"Flask.\n",
"Using an Integrated Development Environment (IDE)\n",
"Developing Flask applications in an integrated development environment (IDE) can\n",
"be very convenient, since features such as code completion and an interactive debug‐\n",
"ger can speed up the coding process considerably. Some of the IDEs that work well\n",
"with Flask are listed here:\n",
"PyCharm\n",
"IDE from JetBrains with Community (free) and Professional (paid) editions,\n",
"both compatible with Flask applications. Available on Linux, macOS, and Win‐\n",
"dows.\n",
"Visual Studio Code\n",
"Open source IDE from Microsoft. A third-party Python plug-in must be installed\n",
"to have access to code completion and debugging features with Flask applica‐\n",
"tions. Available on Linux, macOS, and Windows.\n",
"PyDev\n",
"Open source IDE based on Eclipse. Available on Linux, macOS, and Windows.\n",
"275\n",
"\n",
"Finding Flask Extensions\n",
"The examples in this book rely on several extensions and packages, but there are\n",
"many more that are also useful and were not discussed. The following is a short list of\n",
"some additional packages that are worth exploring:\n",
"• Flask-Babel: Internationalization and localization support\n",
"• Marshmallow: Serialization and deserialization of Python objects, useful for API\n",
"resource representations\n",
"• Celery: Task queue for processing background jobs\n",
"• Frozen-Flask: Conversion of a Flask application to a static website\n",
"• Flask-DebugToolbar: In-browser debugging tools\n",
"• Flask-Assets: Merging, minifying, and compiling of CSS and JavaScript assets\n",
"• Flask-Session: Alternative implementation of user sessions that use server-side\n",
"storage\n",
"• Flask-SocketIO: Socket.IO server implementation with support for WebSocket\n",
"and long-polling\n",
"If the functionality that you need for your project is not covered by any of the exten‐\n",
"sions and packages mentioned in this book, then your first destination to look for\n",
"additional extensions should be the official Flask Extension Registry. Other good\n",
"places to search are the Python Package Index, GitHub, and Bitbucket.\n",
"Getting Help\n",
"If you reach a point where you are blocked by an issue that you cannot resolve on\n",
"your own, you should keep in mind that there is a community of Flask developers\n",
"like you that will be happy to help you.\n",
"A great place to ask questions about Flask or any related extensions is Stack Overflow.\n",
"Other developers that see your question and know how to answer will post their\n",
"answers, which are voted up or down according to their quality. You, as the owner of\n",
"the question, can then select the best answer. All questions and their answers stay on\n",
"the site and appear in search results. So, by asking your question on this platform,\n",
"you help grow the collection of information about Flask.\n",
"Reddit also has a friendly Flask-dedicated subreddit where you can post questions.\n",
"Finally, if you use IRC, the #pocoo channel on Freenode is frequented by Flask devel‐\n",
"opers of all levels who can help you one-on-one with your problem.\n",
"276 \n",
"| \n",
"Chapter 18: Additional Resources\n",
"\n",
"Getting Involved with Flask\n",
"Flask would not be as awesome as it is without the work done by its community of\n",
"developers. As you are now becoming part of this community and benefiting from\n",
"the work of so many volunteers, you should consider finding a way to give something\n",
"back. Here are some ideas to help you get started:\n",
"• Review the documentation for Flask or your favorite related project and submit\n",
"corrections or improvements.\n",
"• Translate the documentation into a new language.\n",
"• Answer questions on Q&A sites such as Stack Overflow.\n",
"• Talk about your work with your peers at user group meetings or conferences.\n",
"• Contribute bug fixes or improvements to packages that you use.\n",
"• Write new Flask extensions and release them as open source.\n",
"• Release your applications as open source.\n",
"I hope you decide to volunteer in one of these ways, or any others that are meaningful\n",
"to you. If you do, thank you!\n",
"Getting Involved with Flask \n",
"| \n",
"277\n",
"\n",
"\n",
"Index\n",
"A\n",
"abort function, 22, 231\n",
"absolute URLs (in links), 37\n",
"account confirmation, 118-125\n",
"generating confirmation tokens with its‐\n",
"dangerous, 118\n",
"sending confirmation emails, 120-124\n",
"account management, 125\n",
"role assignment to users, 135\n",
"activation, virtual environments, 4\n",
"administrator roles, 127\n",
"assignment of, 131\n",
"administrators, user profile editor for, 143-145\n",
"admin_required decorator, 145\n",
"after_app_request hook, 238\n",
"after_request hook, 20\n",
"Alembic database migrations, 74\n",
"Alpine Linux, 258\n",
"AnonymousUser custom class, 132\n",
"Apache Mesos, 270\n",
"APIs (application programming interfaces),\n",
"199-218\n",
"introduction to REST, 199-203\n",
"resources, 200\n",
"versioning web services, 202\n",
"RESTful web services with Flask, 203-218\n",
"app.add_url_rule method, 8, 19\n",
"app.cli.command decorator, 96\n",
"app.config object, 44\n",
"app.run method, 11\n",
"app.shell_context_processor decorator, 72\n",
"application context, 18\n",
"and email on background thread, 83\n",
"application directory, creating, 2\n",
"application instance, 7\n",
"application structure, basic, 7-23\n",
"command-line options, 15\n",
"complete application example, 9\n",
"debug mode, 13\n",
"development server, 10\n",
"dynamic routes, 12\n",
"Flask extensions, 23\n",
"initializing applications, 7\n",
"request-response cycle, 17-22\n",
"routes and view functions, 8\n",
"applications, large, structure of, 85-97\n",
"application package, 88-92\n",
"implementing application functionality\n",
"in a blueprint, 90-92\n",
"using an application factory, 88-89\n",
"application script, 93\n",
"configuration options, 86-88\n",
"database setup, 96\n",
"project structure, 85\n",
"requirements file, 93\n",
"running the application, 97\n",
"unit tests, 94\n",
"app_errorhandler decorator, 91, 205\n",
"association tables (database), 65, 172\n",
"followers table as a model, 174\n",
"auth.login_required decorator, 208\n",
"authentication, 101-125\n",
"account confirmation, 118-125\n",
"account management, 125\n",
"creating blueprint for, 105\n",
"Flask extensions for, 101\n",
"Flask-Mail Gmail account, 80\n",
"in API blueprint, 204\n",
"279\n",
"\n",
"new user registration, 115-118\n",
"password security, 102-105\n",
"token-based, 208-210\n",
"user authentication with Flask-Login,\n",
"107-115\n",
"with Flask-HTTPAuth, 206\n",
"with Heroku account, 245\n",
"automation frameworks, 271\n",
"avatars, 146-149\n",
"avatar in profile page, 147\n",
"blog post author, 153\n",
"Gravatar query string arguments, 146\n",
"Gravatar URL generation, 146\n",
"AWS EC2, 243\n",
"B\n",
"background jobs, for sending email, 84\n",
"background thread, email on, 83\n",
"bash, 2\n",
"before_app_request decorator, 122, 138\n",
"before_first_request hook, 20\n",
"before_request hook, 20, 122\n",
"before_request handler with authentication,\n",
"208\n",
"Bleach package, 164\n",
"blocks (in base templates), 29\n",
"available blocks in Flash-Bootstrap, 32\n",
"blog posts, 151-169\n",
"editor for, 167-169\n",
"on profile pages, 154\n",
"paginating long lists of, 155-161\n",
"permanent links to, 165-167\n",
"querying followed posts using database join,\n",
"181-183\n",
"rich text posts with Markdown and Flask-\n",
"PageDown, 161-165\n",
"showing followed posts on home page,\n",
"183-187\n",
"submission and display of, 151-154\n",
"blueprints, 90-92\n",
"creating, 90\n",
"creating authentication blueprint, 105\n",
"creating for RESTful API, 203\n",
"error handlers in, 91\n",
"registration with app in factory function, 91\n",
"RESTful API blueprint registration, 204\n",
"routes in, 91\n",
"BooleanField class, 109\n",
"boot.sh (container startup script), 259\n",
"Bootstrap, integration using Flash-Bootstrap,\n",
"30-33\n",
"business logic, 25\n",
"C\n",
"cardinality, 58\n",
"Click package, 1\n",
"cloud, deployment to, 243\n",
"code coverage reports, 221-224\n",
"code examples from this book, xiii\n",
"collections (NoSQL databases, 58\n",
"columns (database), 57\n",
"db.Column class, 62\n",
"SQLAlchemy column options, 63\n",
"SQLAlchemy column types, 63\n",
"command-line interface (CLI), installing for\n",
"Heroku, 245\n",
"command-line options, flask command, 15\n",
"comments (user) (see user comments)\n",
"committing database sessions, 67\n",
"conditional statements (in templates), 28, 48\n",
"Config class, 87\n",
"configuration\n",
"applications created by application script, 93\n",
"applications created by factory function, 89\n",
"applications deployed on Heroku platform,\n",
"247\n",
"configuring email for applications on Her‐\n",
"oku, 248\n",
"Docker deployment, 258\n",
"for slow query reporting, 238\n",
"large applications, options for, 86-88\n",
"sending email for application errors, 242\n",
"Unix-based servers, logging, 272\n",
"containers, 244, 256\n",
"(see also Docker)\n",
"content negotiation, 205\n",
"context processors, 134\n",
"contexts, 17\n",
"for email on background thread, 83\n",
"shell context, adding, 72\n",
"control structures (Jinja2), 28\n",
"cookies\n",
"client-side, user sessions in, 52\n",
"setting in response object, 21\n",
"showing followed posts, 184\n",
"Coordinated Universal Time (UTC), 38\n",
"coverage tool, 222\n",
"(see also code coverage reports)\n",
"280 \n",
"| \n",
"Index\n",
"\n",
"create_app factory function\n",
"attaching authentication blueprint to app,\n",
"106\n",
"cross-site request forgery (CSRF) attacks, 44\n",
"CSS\n",
"Bootstrap CSS files, 30, 33\n",
"Bootstrap pagination classes, 159\n",
"classes for avatar in profile page, 147\n",
"styles for blog posts, 153\n",
"cURL, 217\n",
"current_time variable, 39\n",
"current_user context variable, 113, 142\n",
"current_user.can function, 132\n",
"current_user.is_administrator function, 132\n",
"current_user.is_authenticated property, 110,\n",
"114\n",
"current_user._get_current_object method, 152\n",
"Cygwin, 2\n",
"D\n",
"database (in database URLs), 61\n",
"databases, 57-77\n",
"creating tables, 66\n",
"deleting rows, 68\n",
"Flask support for, xi\n",
"inserting rows, 66\n",
"integration with Python shell, 72\n",
"large applications using different databases,\n",
"87\n",
"logging slow performance, 237-239\n",
"making users their own followers in the\n",
"database, 186\n",
"management with Flask-SQLAlchemy, 61\n",
"migrations with Flask-Migrate, 73-77\n",
"adding more migrations, 76\n",
"upgrading the database, 75\n",
"model definition, 62-64\n",
"modifying rows, 68\n",
"NoSQL, 58\n",
"of user roles, 127-131\n",
"adding new roles in shell session, 134\n",
"Post model for blog posts, 151\n",
"Markdown text handling, 164\n",
"provisioning a database on Heroku, 246\n",
"Python database frameworks, 59-60\n",
"querying followed posts using database join,\n",
"181-183\n",
"filter_by query filter, 182\n",
"join query filter, 182\n",
"querying rows, 68\n",
"relational model, 57\n",
"relationships in, 64-65, 171-178\n",
"association table, 172\n",
"representation of blog post comments,\n",
"189-191\n",
"setup in a large application, 96\n",
"SQL, 57\n",
"SQL vs. NoSQL, 59\n",
"storing MD5 hashes for user avatars, 148\n",
"use in view functions, 71-72\n",
"user information in, 137\n",
"user, password hashes stored in, 102\n",
"using an external database with Docker con‐\n",
"tainers, 264\n",
"DATABASE_URL environment variable, 246,\n",
"265\n",
"DataRequired form field validator, 45, 49, 109\n",
"dates and time\n",
"last visit date for users, 138\n",
"localization with Flask-Moment, 38\n",
"timestamps in user information database,\n",
"137\n",
"db object, 62\n",
"db.Column class, 62\n",
"db.create_all function, 66, 75\n",
"db.ForeignKey function, 64\n",
"db.relationship function, 64\n",
"db.session object, 67\n",
"db.session.add method, 68\n",
"db.session.commit method, 67, 121\n",
"db.session.delete method, 68\n",
"db.session.rollback method, 68\n",
"debugging\n",
"debug mode, 13, 93\n",
"--debugger and --no-debugger command-\n",
"line options, 16\n",
"of errors during production, 242\n",
"debugging subsystem, 1\n",
"decorators, 8\n",
"custom, checking user permissions, 132\n",
"order of, in view functions using multiple\n",
"decorators, 133\n",
"request hooks implemented as, 20\n",
"DELETE request method (HTTP), 201\n",
"denormalization (NoSQL databases), 59\n",
"dependencies, 1\n",
"for applications deployed on Heroku, 248\n",
"for development vs. production, 156\n",
"Index \n",
"| \n",
"281\n",
"\n",
"installing into virtual environment with pip,\n",
"5\n",
"requirements file for large applications, 93\n",
"deploy command, 241\n",
"deployment, 241-273\n",
"Docker containers, 256-270\n",
"in the cloud, 243\n",
"logging errors during production, 242\n",
"on Heroku platform, 244-255\n",
"preparing the application, 244-253\n",
"traditional, 270-273\n",
"importing environment variables, 271\n",
"server setup, 271\n",
"setting up logging, 272\n",
"workflow, 241\n",
"deserialization (APIs), 212\n",
"development web server, 10\n",
"DEV_DATABASE_URL environment variable,\n",
"96\n",
"Docker, 244, 256-270\n",
"building a Docker image, 257\n",
"container orchestration with Compose,\n",
"265-269\n",
"Dockerfile, 257\n",
"images command, 260, 269\n",
"installing, 256\n",
"login command, 263\n",
"logs command, 262, 264\n",
"ps command, 269\n",
"push command, 263\n",
"rm command, 262, 269\n",
"rmi command, 269\n",
"run command, 261, 264\n",
"stop command, 262\n",
"Swarm, 270\n",
"system command, 269\n",
"tag command, 263\n",
"using an external database, 264\n",
"using in production, 270\n",
"version command, 256\n",
"volume command, 269\n",
"Docker Compose, 265\n",
"docker-compose.yml file, 266\n",
"logs command, 268\n",
"ps command, 269\n",
"up command, 268\n",
"Docker Hub, 263\n",
"applications and services on, 265\n",
"document-oriented databases, 57\n",
"dynamic routes, 9\n",
"dynamic URLs, generating with url_for func‐\n",
"tion, 37\n",
"dynos (Heroku), 244\n",
"E\n",
"EC2 service (AWS), 243\n",
"email, 79\n",
"(see also Flask-Mail)\n",
"configuring for applications on Heroku, 248\n",
"configuring for Docker container, 261\n",
"confirming user accounts, 120-124\n",
"handling address changes for user accounts,\n",
"125\n",
"sending for application errors, 242\n",
"entity-relationship diagrams, 58\n",
".env file, 253, 266-267, 271\n",
"environment variables\n",
"defined in Dockerfile, 258\n",
"importing in traditional deployment, 271\n",
"in large application configuration, 87\n",
"EqualTo form field validator, 116\n",
"error handling\n",
"API error handler for ValidationError, 212\n",
"error handlers in app blueprints, 91\n",
"Flask-HTTPAuth error handler, 208\n",
"in RESTful web services, 204\n",
"with content negotiation, 205\n",
"error pages, custom, 33-36\n",
"errors, logging during production, 242\n",
"extends directive, 30, 32\n",
"extensibility of Flask, xi\n",
"extensions, 1, 23, 30\n",
"additional Flask extensions and packages,\n",
"276\n",
"initialization, 31\n",
"F\n",
"factory function, creating applications with, 88\n",
"fake blog post data, creating, 155-157\n",
"Faker package, 155\n",
"filters (database), 27\n",
"offset() query filter, 157\n",
"query of followed posts using database join,\n",
"183\n",
"using with database queries, 68\n",
"filter_by method, 69\n",
"SQLAlchemy filters for, 69\n",
"flash function, 53\n",
"282 \n",
"| \n",
"Index\n",
"\n",
"Flask\n",
"application factory function, 88\n",
"app_errorhandler decorator, 91, 205\n",
"basic multiple-file application structure, 85\n",
"custom commands, 96\n",
"dynamic routes, 9\n",
"extensions, 30\n",
"Flask class, 7\n",
"flask command options, 15\n",
"installing into virtual environment with pip,\n",
"5\n",
"server shutdown, 230\n",
"test client, 224-229\n",
"working with, additional resources for,\n",
"275-277\n",
"flask db downgrade command, 76\n",
"flask db migrate command, 75-76\n",
"flask db stamp command, 76\n",
"flask db upgrade command, 75-76\n",
"flask deploy command, 268\n",
"Flask Extension Registry, 276\n",
"flask run command, 10\n",
"--host argument, 16\n",
"options, 16\n",
"flask shell command, 15, 66, 72\n",
"flask test command, --coverage option, 222\n",
"Flask-Bootstrap, 30-33\n",
"blocks, 29\n",
"initialization, 30\n",
"installing, 30\n",
"quick_form macro, 47\n",
"wtf.quick_form Jinja2 macro, 110\n",
"wtf.quick_form method, 47\n",
"Flask-HTTPAuth, 206\n",
"before_request handler with authentication,\n",
"208\n",
"error handler, 208\n",
"initialization, 207\n",
"token-based authentication support, 209\n",
"Flask-Login, 107-115\n",
"adding a login form, 109\n",
"AnonymousUserMixin class, 132\n",
"current_user context variable, 113, 152\n",
"how it works, 113\n",
"LoginManager class, 108\n",
"login_manager.anonymous_user attribute,\n",
"132\n",
"login_required decorator, 108, 114\n",
"login_user function, 111\n",
"logout_user function, 113\n",
"preparing User model for logins, 107\n",
"signing users in, 111\n",
"signing users out, 112\n",
"testing logins, 114\n",
"UserMixin class, 107\n",
"user_loader decorator, 108\n",
"Flask-Mail, 79-84\n",
"initialization, 80\n",
"integrating emails with the application, 81\n",
"sending asynchronous email, 83\n",
"sending email from Python shell, 81\n",
"sending email through Gmail, 80\n",
"SMTP server configuration keys, 79\n",
"Flask-Migrate, 73-77\n",
"adding more migrations, 76\n",
"considerations in changing database sche‐\n",
"mas, 74\n",
"creating or upgrading database tables in\n",
"large application, 96\n",
"initialization, 73\n",
"upgrading the database, 75\n",
"Flask-Moment, 38\n",
"format function, 40\n",
"fromNow function, 40\n",
"locale function, 41\n",
"Flask-PageDown, 162-164\n",
"initialization, 162\n",
"Markdown-enabled post form, 162\n",
"Flask-SQLAlchemy, 60\n",
"add session method, 67-68\n",
"column options, 63\n",
"create_all method, 66, 95\n",
"database management with, 61\n",
"delete session method, 68\n",
"drop_all method, 66\n",
"enabling recording of query statistics, 239\n",
"filter_by query filter, 71\n",
"first_or_404 query method, 139\n",
"get_debug_queries function, 237\n",
"get_or_404 convenience function, 145\n",
"models, 62\n",
"MySQL configuration, 61\n",
"paginate method, 158\n",
"pagination object attributes, 158\n",
"pagination object methods, 159\n",
"Postgres configuration, 61\n",
"query executors, 69\n",
"query filters, 69\n",
"Index \n",
"| \n",
"283\n",
"\n",
"query object (database), 68\n",
"query statistics recorded by, 238\n",
"querying followed posts using databse join,\n",
"182\n",
"SQLALCHEMY_DATABASE_URI configu‐\n",
"ration, 61\n",
"SQLALCHEMY_TRACK_MODIFICA‐\n",
"TIONS configuration, 61\n",
"SQLite configuration, 61\n",
"Flask-SSLify, 249\n",
"Flask-WTF, 43\n",
"BooleanField class, 109\n",
"configuration, 44\n",
"cross-site request forgery (CSRF), 44\n",
"DataRequired validator, 45, 109\n",
"disabling CSRF tokens in unit tests, 226\n",
"FlaskForm class, 44\n",
"form fields, 45\n",
"Length validator, 109\n",
"login form, 109\n",
"PasswordField class, 109\n",
"rendering, 47\n",
"StringField class, 45, 109\n",
"SubmitField class, 45, 109\n",
"using to render a form, 47\n",
"validate_on_submit method, 49, 111\n",
"validators, 46\n",
"FlaskForm class, 44\n",
"Flasky, Docker container image for, 260\n",
"flasky.py, 266, 272\n",
"coverage command, 222\n",
"deploy command, 241, 253, 255, 260\n",
"profile command, 239\n",
"FLASKY_ADMIN environment variable, 83,\n",
"131\n",
"FLASKY_COMMENTS_PER_PAGE configu‐\n",
"ration variable, 192\n",
"FLASKY_POSTS_PER_PAGE configuration\n",
"variable, 158\n",
"FLASK_APP environment variable, 10, 66, 93,\n",
"246\n",
"setting by default, 97\n",
"FLASK_CONFIG environment variable, 93,\n",
"247\n",
"FLASK_COVERAGE environment variable,\n",
"223\n",
"FLASK_DEBUG environment variable, 14, 93\n",
"setting by default, 97\n",
"followers, 171-187\n",
"database relationships and, 171-178\n",
"on the profile page, 178-180\n",
"showing followed posts on home page,\n",
"183-187\n",
"for loops, 28\n",
"foreign keys, 57, 64\n",
"form.hidden_tag element, 47\n",
"form.validate_on_submit method, 142\n",
"format function, 40\n",
"forms (see web forms)\n",
"functools package, 133\n",
"G\n",
"g context variable, 18, 21\n",
"GET request method (HTTP), 19\n",
"in redirects, 51\n",
"in RESTful APIs, 201\n",
"resource handlers for blog posts, 213\n",
"view function handling GET requests, 48\n",
"get_flashed_messages function, 54\n",
"Git\n",
"downloading example code, 2\n",
"server dedicated to Heroku application, 246\n",
"source code for code examples, xiii\n",
"uploading applications to Heroku server\n",
"with git push, 254\n",
"using with applications on Heroku, 244\n",
"Gmail, Flask-Mail cofiguration for, 80\n",
"Gravatar service, 146\n",
"Gunicorn web server, 251-252\n",
"H\n",
"hashes\n",
"MD5 hash for avatar URLs, 146\n",
"caching of, 148\n",
"password hashing, 102\n",
"using Werkzeug security module, 102\n",
"HEAD request method (HTTP), 19\n",
"help from Flask developer community, 276\n",
"Heroku platform, 244-255\n",
"adding a Procfile, 252\n",
"adding a top-level requirements file, 248\n",
"addons:create command, 246\n",
"CLI tool, 245\n",
"config command, 246\n",
"config:set command, 247\n",
"configuring email, 248\n",
"configuring logging, 247\n",
"create command, 246\n",
"284 \n",
"| \n",
"Index\n",
"\n",
"creating a Heroku account, 245\n",
"creating an application, 245\n",
"deploying application upgrades to, 255\n",
"deploying applications to, using git push,\n",
"254\n",
"enabling secure HTTP with Flask-SSLify,\n",
"249\n",
"login command, 245\n",
"logs ommand, 247\n",
"maintenance command, 255\n",
"provisioning a database, 246\n",
"reviewing application logs, 255\n",
"running a production web server, 251\n",
"testing with heroku local command, 253\n",
"hostname (database URLs), 61\n",
"HTML\n",
"Markdown-to-HTML converter, 164\n",
"rendering of forms to, 47-48\n",
"HTTP (secure), enabling with Flask-SSLify, 249\n",
"HTTP authentication, 206\n",
"HTTP methods, 19\n",
"and resource handlers for RESTful web ser‐\n",
"vice, 215\n",
"request methods in RESTful APIs, 201\n",
"HTTP status codes, 21\n",
"404 error, 33, 145\n",
"RESTful API error handler for 403 status\n",
"code, 206\n",
"returned by RESTful APIs, 204\n",
"HTTPBasicAuth class, 207\n",
"HTTPie, using to test web services, 217-218\n",
"I\n",
"images (container), 244\n",
"building a Docker container image, 257\n",
"cleaning up, 269\n",
"importing files, template macros, 29\n",
"included files, 29\n",
"inheritance in Jinja2 templates, 29, 31\n",
"init_app method, 88\n",
"insert_roles method, 131\n",
"integrated development environments (IDEs),\n",
"275\n",
"itsdangerous package, 119\n",
"generating confirmation tokens for user\n",
"accounts, 119\n",
"token-based authentication support, 209\n",
"J\n",
"JavaScript files (Bootstrap), 30, 33\n",
"JavaScript, moment.js library, 38\n",
"Jinja2 package, 1, 26-30\n",
"block directive, 29\n",
"control structures, 28\n",
"for directive, 28\n",
"macro directive, 29\n",
"extends directive, 30\n",
"import directive, 29, 47\n",
"include directive, 29\n",
"rendering templates, 26\n",
"safe filter, 28\n",
"set directive, 195\n",
"super macro, 30\n",
"variables, 27\n",
"filters for, 27\n",
"wtf.quick_form macro, 110\n",
"joins (database)\n",
"joined lazy argument for back references,\n",
"175\n",
"using in databse query of followed posts,\n",
"181\n",
"jQuery.js library, 39\n",
"JSON\n",
"serializing resources to and from, 210-213\n",
"use in RESTful web services, 202\n",
"JSON Web Signatures (JWSs), 119\n",
"jsonify helper function, 203\n",
"junction tables (see association tables (data‐\n",
"base))\n",
"K\n",
"key-value databases, 57\n",
"Kubernetes, 270\n",
"L\n",
"language codes, 41\n",
"links, 36\n",
"blog post editor, 168\n",
"moderate comments link in navigation bar,\n",
"193\n",
"permanent links to blog posts, 165-167\n",
"profile edit link, 142\n",
"profile edit link for administrator, 145\n",
"to blog post comments, 192\n",
"to user profile page in navigation bar, 140\n",
"locale function, 41\n",
"Index \n",
"| \n",
"285\n",
"\n",
"localization of dates and time, 38\n",
"logging\n",
"configuring on Heroku platform, 247\n",
"Docker configuration for, 258\n",
"docker logs command, 262\n",
"of errors during production, 242\n",
"reviewing application logs on Heroku plat‐\n",
"form, 255\n",
"setting up in traditional deployments, 272\n",
"login view function, 111\n",
"login_manager.anonymous_user attribute, 132\n",
"login_manager.user_loader decorator, 108\n",
"login_required decorator, 108, 114, 122, 208\n",
"M\n",
"macros, 29\n",
"MAIL_PASSWORD environment variable, 80\n",
"MAIL_USERNAME environment variable, 80\n",
"make_response function, 21, 185\n",
"many-to-many relationships, 65, 172\n",
"advanced, 174\n",
"followers helper methods, 176\n",
"implementation as one-to-many rela‐\n",
"tionships, 175\n",
"self-referential, 174\n",
"many-to-one relationships, 65\n",
"Markdown, 162-165\n",
"conversion to HTML on the server, 164\n",
"post form enabled for, 162\n",
"messages, flashing from forms, 53-55\n",
"methods argument, 48\n",
"microservices, 265\n",
"Microsoft Windows (see Windows systems)\n",
"migration scripts (database), 74\n",
"creating with flask db migrate, 75\n",
"model definition (database), 62-64\n",
"moment.js library, 38\n",
"formatting options for dates and time, 40\n",
"MySQL databases, 264-265, 271\n",
"N\n",
"NameForm class, 45\n",
"namespaces in blueprints, 92\n",
"NoSQL databases, 57-58\n",
"Flask support for, xi\n",
"SQL databases vs., 59\n",
"O\n",
"OAuth2 authentication, 80\n",
"object-document mappers (ODMs), 60\n",
"object-relational mappers (ORMs), 60\n",
"model, 62\n",
"one-to-many relationships, 58, 64\n",
"comments table to users table, 189\n",
"many-to-many relationship implemented\n",
"as, 175\n",
"querying, 70\n",
"one-to-one relationships, 65\n",
"OPTIONS request method (HTTP), 19\n",
"orchestration (container) with docker-\n",
"compose, 265-269\n",
"P\n",
"PageDown library, 162\n",
"pagination\n",
"of large resource collections, 216\n",
"of long blog post lists, 155-161\n",
"adding a pagination widget, 158-161\n",
"creating fake blog post data, 155\n",
"rendering in pages, 157\n",
"of user comments on posts, 192\n",
"PasswordField class, 109\n",
"passwords\n",
"password in database URLs, 61\n",
"security, 102-105\n",
"updates and resets for user accounts, 125\n",
"performance, 237-240\n",
"logging slow database performance, 237-239\n",
"source code profiling, 239-240\n",
"permissions, 127\n",
"comment moderation, 193\n",
"custom decorators checking, 132\n",
"evaluating for a user, 132\n",
"in user roles database, 128\n",
"constants for permissions, 128\n",
"methods for managing, 129\n",
"roles supported with permissions, 130\n",
"unit tests for, 134\n",
"permission_required decorator, 214\n",
"pip, 5\n",
"Platform as a Service (PaaS), 244\n",
"POST request method (HTTP), 43\n",
"in RESTful APIs, 201\n",
"redirect response to POST requests, 51\n",
"resource handler for blog posts, 214\n",
"view function handling POST requests, 48\n",
"286 \n",
"| \n",
"Index\n",
"\n",
"Post/Redirect/Get pattern, 52\n",
"logins and, 112\n",
"Postfix, 271\n",
"Postgres databases, 246, 271\n",
"presentation logic, 25\n",
"primary key (database), 57\n",
"primay key column, Flask-SQLAlchemy\n",
"requirement for, 64\n",
"Procfile (applications on Heroku), 252\n",
"profile-header CSS class, 147\n",
"profile-thumbnail CSS class, 147\n",
"profiles, 137-149\n",
"blog post author username and avatar, links\n",
"to profile page, 153\n",
"blog posts on profile pages, 154\n",
"creating user profile page, 138-141\n",
"editor for, 141-145\n",
"administrator-level editor, 143-145\n",
"user-level editor, 141\n",
"followers on the profile page, 178-180\n",
"information in, 137\n",
"user avatars, 146-149\n",
"profiling source code, 239\n",
"proxy servers, 250, 271\n",
"psycopg2 package, 248\n",
"PUT request method (HTTP), 201\n",
"PUT resource handler for blog posts, 215\n",
"pymysql package, 264\n",
"Python, 1\n",
"creating virtual environments with Python\n",
"2, 3\n",
"creating virtual environments with Python\n",
"3, 3\n",
"database frameworks, 59-60\n",
"database integration with Python shell, 72\n",
"installing packages with pip, 5\n",
"interpreter images on Docker Hub, 258\n",
"Python Package Index, 276\n",
"python-dotenv package, 272\n",
"Q\n",
"query object (database), 68\n",
"R\n",
"redirect function, 22, 53\n",
"redirects, 22, 51-53\n",
"SSL, 249\n",
"Regexp form field validator, 116\n",
"registration of new users, 115-118\n",
"adding user registration form, 115\n",
"registering users, 117\n",
"regressions, 221\n",
"relational databases, 57\n",
"(see also SQL databases)\n",
"Flask support for, xi\n",
"relationships (database), 57, 64-65, 171-178\n",
"dynamic relationships, 70\n",
"many-to-many, 172\n",
"advanced, 174\n",
"querying a one-to-many relationship, 70\n",
"self-referential, 174\n",
"SQLAlchemy options for, 65\n",
"relative URLs (in links), 37\n",
"REMEMBER_COOKIE_DURATION option,\n",
"111\n",
"remote procedure call (RPC) protocols, 199\n",
"rendering (templates), 25\n",
"render_template function, 27, 49, 53\n",
"Representational State Transfer (see REST)\n",
"request context, 18\n",
"request-response cycle, 17-22\n",
"application and request contexts, 17\n",
"HTTP request methods, 19\n",
"request and response bodies in RESTful\n",
"APIs, 201\n",
"request dispatching, 18\n",
"request hooks, 20\n",
"request methods in RESTful APIs, 201\n",
"request object, 19\n",
"requests, 8\n",
"response formats for RESTful API clients,\n",
"205\n",
"responses, 8, 21\n",
"response object, 21\n",
"requirements file, 93, 248\n",
"development requirements file, 156\n",
"top-level requirements file for Heroku plat‐\n",
"form, 248\n",
"resources\n",
"implementing endpoints for, 213-216\n",
"pagination of large collections, 216\n",
"serializing to and from JSON, 210-213\n",
"URLs for, 202\n",
"resources for working with Flask, 275-277\n",
"getting help, 276\n",
"getting involved with the Flask community,\n",
"277\n",
"Index \n",
"| \n",
"287\n",
"\n",
"integrated development environments\n",
"(IDEs), 275\n",
"REST, 199\n",
"defining characteristics for web services\n",
"architecture, 199\n",
"request and response bodies, 201\n",
"request methods, 201\n",
"resources, concept of, 200\n",
"versioning of web services, 202\n",
"RESTful web services with Flask, 203-218\n",
"creating an API blueprint, 203\n",
"error handling, 204\n",
"implementing resource endpoints, 213-216\n",
"pagination of large resource collections, 216\n",
"serializing resources to and from JSON,\n",
"210-213\n",
"testing with HTTPie, 217-218\n",
"token-based authentication, 208-210\n",
"user authentication with Flask-HTTPAuth,\n",
"206\n",
"reverse proxy servers, 250, 271\n",
"rich internet applications (RIAs), 199\n",
"rich text posts, using Markdown and Flask-\n",
"PageDown, 161-165\n",
"handling rich text on the server, 164\n",
"roles, 127-135\n",
"adding to development database in shell ses‐\n",
"sion, 134\n",
"assignment of, 131\n",
"database representation of, 127-131\n",
"method creating roles, 130\n",
"unit tests for, 134\n",
"verification of, 132-135\n",
"rolling back database sessions, 68\n",
"Ronacher, Armin, 1\n",
"route decorator, 133\n",
"routes, 8\n",
"access by authenticated users only, 108\n",
"authentication token generation, 210\n",
"blog post comments support, 191\n",
"comment moderation, 196\n",
"dynamic, 12\n",
"editor for blog posts, 167\n",
"follow route, 179\n",
"home page route with blog posts, 152\n",
"pagination support, 157\n",
"in authentication blueprint, 105\n",
"in blueprints, 91\n",
"permanent links to blog posts, 165\n",
"profile edit route, 141\n",
"profile edit route for administrators, 144\n",
"profile page route, 138\n",
"profile page route with blog posts, 154\n",
"registration route with confirmation email,\n",
"120\n",
"selection of all or followed posts, 184\n",
"sign out, 113\n",
"user registration, 117\n",
"routing subsystem, 1\n",
"rows (database), 57\n",
"deleting, 68\n",
"inserting, 66\n",
"modifying, 68\n",
"querying, 68\n",
"S\n",
"secret key, 44, 87, 119\n",
"for applications on Heroku platform, 247\n",
"secure HTTP, 249\n",
"SelectField class, 144\n",
"Selenium, end-to-end testing with, 230-234\n",
"self-referential relationships, 174\n",
"Sendmail, 271\n",
"serialization\n",
"deserializing resources from JSON, 212\n",
"serializing resources to JSON, 210\n",
"server setup in traditional deployment, 271\n",
"server shutdown, 230\n",
"session context variable, 18, 52\n",
"session.get method, 53\n",
"sessions (database), 67\n",
"committing, 67\n",
"rolling back, 68\n",
"sessions (user), 44\n",
"redirects and, 51\n",
"set_cookie method, 21, 185\n",
"shell context processor, 72\n",
"SMTP server, 79\n",
"smtplib package, 79\n",
"source code profiling, 239\n",
"SQL (Structured Query Language), 57\n",
"SQL databases, 57\n",
"NoSQL vs., 59\n",
"SQLAlchemy, 60\n",
"column options, 63\n",
"column types, 63\n",
"inspecting native SQL query generated by,\n",
"69\n",
"288 \n",
"| \n",
"Index\n",
"\n",
"Markdown text conversion to HTML, 164\n",
"query executors, 69\n",
"query filters, 69\n",
"relationship options, 65\n",
"SQLALCHEMY_DATABASE_URI, 61, 87\n",
"SQLALCHEMY_TRACK_MODIFICATIONS,\n",
"61\n",
"SQLite databases, 271\n",
"SSL_REDIRECT variable, 249, 250\n",
"stack traces, 242\n",
"stateless web services, 206\n",
"static files, 37\n",
"static methods, 131\n",
"status codes (HTTP), 21\n",
"StringField class, 45, 109\n",
"SubmitField class, 45, 109\n",
"super function, 30, 33\n",
"syslog, 272\n",
"T\n",
"__tablename__ class variable, 62\n",
"tables (database), 57\n",
"creating, 66\n",
"creating or upgrading in large application,\n",
"96\n",
"joins, 58\n",
"teardown_request hook, 20\n",
"templates, 25-41\n",
"adding Permission class to template context,\n",
"134\n",
"Bootstrap integration using Flash-\n",
"Bootstrap, 30-33\n",
"comment moderation, 194\n",
"confirmation email used by authentication\n",
"blueprint, 121\n",
"custom error pages, 33-36\n",
"defined, 25\n",
"edit blog post template, 167\n",
"flash message rendering, 54\n",
"Flask-PageDown template declaration, 162\n",
"follower enhancements to profile header,\n",
"178\n",
"for authentication blueprint, 105\n",
"for email messages, 81\n",
"for login form, 109\n",
"for new user registration form, 116\n",
"for user profile, 139\n",
"greeting logged-in user, 114\n",
"home page template with blog posts, 152\n",
"Jinja2 template engine, 26-30\n",
"links, 36\n",
"localizing dates and time with Flask-\n",
"Moment, 38\n",
"login template, updating to render login\n",
"form, 112\n",
"pagination footer for blog post lists, 160\n",
"pagination template macro, 159\n",
"permanent link to blog posts, 166\n",
"profile page template with blog posts, 155\n",
"static files, 37\n",
"templates folder, 26\n",
"using to render a form to HTML, 47\n",
"test command to run unit tests, 95\n",
"testing, 221-235\n",
"assessing worth of, 234\n",
"end-to-end, using Selenium, 230-234\n",
"getting code coverage reports, 221-224\n",
"of web services with HTTPie, 217-218\n",
"password hashing tests, 104\n",
"unit tests file for large applications, 94\n",
"unit tests for roles and permissions, 134\n",
"using Flask test client, 224-229\n",
"testing web applications, 225-228\n",
"testing web services, 228-229\n",
"verifying login functionality, 114\n",
"time (see dates and time)\n",
"timestamps, working with, using Flask-\n",
"Moment, 39\n",
"token-based authentication, 208-210, 218\n",
"transactions, 67\n",
"(see also sessions (database))\n",
"U\n",
"unconfirmed accounts\n",
"filtering in before_app_request handler, 122\n",
"page presented asking for account confir‐\n",
"mation, 123\n",
"unittest package, 95\n",
"URL fragments, 192\n",
"URLs\n",
"application routes, 9\n",
"application URL map, 19\n",
"avatar, 146\n",
"database, in Flask-SQLAlchemy, 61\n",
"for resources, 200\n",
"for resoures\n",
"fully-qualified, 202\n",
"Index \n",
"| \n",
"289\n",
"\n",
"in confirmation emails for user accounts,\n",
"121\n",
"in links, 37\n",
"url_for function, 37, 53, 92, 121\n",
"url_prefix argument, 106\n",
"user authentication (see authentication)\n",
"user comments, 189-197\n",
"database representation of, 189-191\n",
"moderation of, 193-197\n",
"submission and display of, 191-193\n",
"user loader function, 108\n",
"User model\n",
"preparing for logins, 107\n",
"preparing for password hashing, 102\n",
"user account token generation and verifica‐\n",
"tion, 119\n",
"user profiles (see profiles)\n",
"user roles (see roles)\n",
"user sessions, 44, 52\n",
"expiration, long-term cookie for, 111\n",
"User.can method, 153\n",
"username (database URLs), 61\n",
"users\n",
"making existing users their own followers,\n",
"186\n",
"making their own followers on construc‐\n",
"tion, 186\n",
"UTC (Coordinated Universal Time), 38\n",
"uWSGI web server, 252\n",
"V\n",
"validate_on_submit method, 49, 111\n",
"ValidationError, 116, 212\n",
"RESTful API error handler for, 213\n",
"validators, 44, 109\n",
"built-in, WTForms package, 46\n",
"implemented as methods, 116\n",
"variables, 26-27\n",
"filters for, 27\n",
"venv package (Python), 3\n",
"verify_password method, 111\n",
"view functions, 8\n",
"confirming user accounts, 121\n",
"database use in, 71-72\n",
"for blog post comments, 191\n",
"for blog post editor, 168\n",
"for followers on profile page, 179\n",
"for permanent links to blog posts, 165\n",
"form handling in, 48-51\n",
"in authentication blueprint, 105\n",
"in blueprints, 92\n",
"login function implementation, 111\n",
"order of decorators in, 133\n",
"purposes of, 25\n",
"virtual environments, 2\n",
"activating, 4\n",
"creating with Python 2, 3\n",
"creating with Python 3, 3\n",
"deactivating, 5\n",
"installing Flask into, 5\n",
"using without activating, 5\n",
"virtual machines, 256\n",
"virtual servers, 243\n",
"virtualenv utility, 3\n",
"volumes (Docker), removing, 269\n",
"W\n",
"Waitress web server, 252\n",
"web browsers, Selenium automation tool, 230\n",
"web dynos (Heroku), 244\n",
"web forms, 43-55\n",
"blog post form, 151\n",
"configuration, 44\n",
"flashing a message, 53-55\n",
"form classes, 44-47\n",
"generated by Flash-WTF, CSRF tokens in,\n",
"226\n",
"handling in view functions, 48-51\n",
"HTML rendering of, 47-48\n",
"in blueprints, 92\n",
"login form, 109\n",
"profile edit form, 141\n",
"profile editing form for administrators, 143\n",
"redirects and user sessions, 51-53\n",
"user registration form, 115\n",
"Web Server Gateway Interface (WSGI), 1, 7\n",
"web servers\n",
"installing in traditional deployment, 271\n",
"running production web server on Heroku,\n",
"251\n",
"web services, 199, 203\n",
"(see also RESTful web services with Flask)\n",
"testing RESTful web services using Flask test\n",
"client, 228-229\n",
"Werkzeug (security module), 1, 102, 242\n",
"generate_password_hash function, 103\n",
"ProfilerMiddleware WSGI middleware, 240\n",
"ProxyFix WSGI middleware, 250\n",
"290 \n",
"| \n",
"Index\n",
"\n",
"verify_password method, 103\n",
"Windows Subsystem for Linux (WSL), 2\n",
"Windows systems, 2\n",
"Docker for Windows, Hyper-V feature and,\n",
"257\n",
"testing Heroku deployment, using Waitress\n",
"web server, 252\n",
"worker dynos (Heroku), 244\n",
"wtf.quick_form function, 47\n",
"WTForms package, 43\n",
"built-in validators, 46\n",
"Regexp validator, 116\n",
"SelectField wrapper class, 144\n",
"standard HTML fields supported by, 45\n",
"X\n",
"XML in RESTful web services, 202\n",
"Index \n",
"| \n",
"291\n",
"\n",
"About the Author\n",
"Miguel Grinberg has over 25 years of experience as a software engineer. He has a\n",
"blog where he writes about a variety of topics, including web development, robotics,\n",
"photography, and the occasional movie review. He lives in Portland, Oregon.\n",
"Colophon\n",
"The animal on the cover of Flask Web Development is a Pyrenean Mastiff (a breed of\n",
"Canis lupus familiaris). These giant Spanish dogs are descended from an ancient live‐\n",
"stock guardian dog called the Molossus, which was bred by the Greeks and Romans\n",
"and is now extinct. However, this ancestor is known to have played a role in the cre‐\n",
"ation of many breeds that are common today, such as the Rottweiler, Great Dane,\n",
"Newfoundland, and Cane Corso. Pyrenean Mastiffs have only been recognized as a\n",
"pure breed since 1977, and the Pyrenean Mastiff Club of America is working to pro‐\n",
"mote these dogs as pets in the United States.\n",
"After the Spanish Civil War, the population of Pyrenean Mastiffs in their native\n",
"homeland plummeted, and the breed only survived due to the dedicated work of a\n",
"few scattered breeders throughout the country. The modern gene pool for Pyreneans\n",
"stems from this postwar population, making them prone to genetic diseases like hip\n",
"dysplasia. Today, responsible owners make sure their dogs are tested for diseases and\n",
"x-rayed to look for hip abnormalities before being bred.\n",
"Adult male Pyrenean Mastiffs can reach upwards of 200 pounds when fully grown, so\n",
"owning this dog requires a commitment to good training and plenty of outdoor time.\n",
"Despite their size and history as hunters of bears and wolves, the Pyrenean has a very\n",
"calm temperament and is an excellent family dog. They can be relied upon to take\n",
"care of children and protect the home, while at the same time being docile with other\n",
"dogs. With proper socialization and strong leadership, the Pyrenean Mastiff thrives in\n",
"a home environment and will provide an excellent guardian and companion.\n",
"Many of the animals on O’Reilly covers are endangered; all of them are important to\n",
"the world. To learn more about how you can help, go to animals.oreilly.com.\n",
"The cover image is from J. G. Wood’s Animate Creation. The cover fonts are URW\n",
"Typewriter and Guardian Sans. The text font is Adobe Minion Pro; the heading font\n",
"is Adobe Myriad Condensed; and the code font is Dalton Maag’s Ubuntu Mono.\n",
"\n",
"Text Statistics:\n",
"Word Count: 98815\n",
"Sentence Count: 4310\n",
"Average Word Length: 4.45\n"
]
}
],
"source": [
"import fitz # PyMuPDF\n",
"import nltk\n",
"from nltk.tokenize import word_tokenize, sent_tokenize\n",
"\n",
"# Download necessary NLTK data files\n",
"nltk.download('punkt')\n",
"\n",
"def extract_text_from_pdf(pdf_path):\n",
" pdf_document = fitz.open(pdf_path)\n",
" text_content = []\n",
"\n",
" for page_num in range(pdf_document.page_count):\n",
" page = pdf_document.load_page(page_num)\n",
" text_content.append(page.get_text())\n",
"\n",
" return '\\n'.join(text_content)\n",
"\n",
"def text_statistics(text):\n",
" words = word_tokenize(text)\n",
" sentences = sent_tokenize(text)\n",
" word_count = len(words)\n",
" sentence_count = len(sentences)\n",
" average_word_length = sum(len(word) for word in words) / word_count\n",
"\n",
" return {\n",
" 'word_count': word_count,\n",
" 'sentence_count': sentence_count,\n",
" 'average_word_length': average_word_length\n",
" }\n",
"\n",
"# Example usage\n",
"fname = '/home/ys/Documents/Flask Web Development - Miguel Grinberg.pdf'\n",
"text = extract_text_from_pdf(fname)\n",
"print(text)\n",
"\n",
"# Generate text statistics\n",
"stats = text_statistics(text)\n",
"print(\"Text Statistics:\")\n",
"print(f\"Word Count: {stats['word_count']}\")\n",
"print(f\"Sentence Count: {stats['sentence_count']}\")\n",
"print(f\"Average Word Length: {stats['average_word_length']:.2f}\")"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": []
}
],
"metadata": {
"kernelspec": {
"display_name": "General",
"language": "python",
"name": "python3"
},
"language_info": {
"codemirror_mode": {
"name": "ipython",
"version": 3
},
"file_extension": ".py",
"mimetype": "text/x-python",
"name": "python",
"nbconvert_exporter": "python",
"pygments_lexer": "ipython3",
"version": "3.11.2"
}
},
"nbformat": 4,
"nbformat_minor": 4
}