mirror of https://github.com/mitsuhiko/flask.git
Armin Ronacher
15 years ago
15 changed files with 601 additions and 569 deletions
@ -1,484 +0,0 @@ |
|||||||
.. _tutorial: |
|
||||||
|
|
||||||
Tutorial |
|
||||||
======== |
|
||||||
|
|
||||||
You want to develop an application with Python and Flask? Here you have |
|
||||||
the chance to learn that by example. In this tutorial we will create a |
|
||||||
simple microblog application. It only supports one user that can create |
|
||||||
text-only entries and there are no feeds or comments, but it still |
|
||||||
features everything you need to get started. We will use Flask and SQLite |
|
||||||
as database which comes out of the box with Python, so there is nothing |
|
||||||
else you need. |
|
||||||
|
|
||||||
If you want the full sourcecode in advance or for comparison, check out |
|
||||||
the `example source`_. |
|
||||||
|
|
||||||
.. _example source: |
|
||||||
http://github.com/mitsuhiko/flask/tree/master/examples/flaskr/ |
|
||||||
|
|
||||||
Introducing Flaskr |
|
||||||
------------------ |
|
||||||
|
|
||||||
We will call our blogging application flaskr here, feel free to chose a |
|
||||||
less web-2.0-ish name ;) Basically we want it to do the following things: |
|
||||||
|
|
||||||
1. let the user sign in and out with credentials specified in the |
|
||||||
configuration. Only one user is supported. |
|
||||||
2. when the user is logged in he or she can add new entries to the page |
|
||||||
consisting of a text-only title and some HTML for the text. This HTML |
|
||||||
is not sanitized because we trust the user here. |
|
||||||
3. the page shows all entries so far in reverse order (newest on top) and |
|
||||||
the user can add new ones from there if logged in. |
|
||||||
|
|
||||||
We will be using SQlite3 directly for that application because it's good |
|
||||||
enough for an application of that size. For larger applications however |
|
||||||
it makes a lot of sense to use `SQLAlchemy`_ that handles database |
|
||||||
connections in a more intelligent way, allows you to target different |
|
||||||
relational databases at once and more. You might also want to consider |
|
||||||
one of the popular NoSQL databases if your data is more suited for those. |
|
||||||
|
|
||||||
Here a screenshot from the final application: |
|
||||||
|
|
||||||
.. image:: _static/flaskr.png |
|
||||||
:align: center |
|
||||||
:class: screenshot |
|
||||||
:alt: screenshot of the final application |
|
||||||
|
|
||||||
.. _SQLAlchemy: http://www.sqlalchemy.org/ |
|
||||||
|
|
||||||
Step 0: Creating The Folders |
|
||||||
---------------------------- |
|
||||||
|
|
||||||
Before we get started, let's create the folders needed for this |
|
||||||
application:: |
|
||||||
|
|
||||||
/flaskr |
|
||||||
/static |
|
||||||
/templates |
|
||||||
|
|
||||||
The `flaskr` folder is not a python package, but just something where we |
|
||||||
drop our files. Directly into this folder we will then put our database |
|
||||||
schema as well as main module in the following steps. The files inside |
|
||||||
the `static` folder are available to users of the application via `HTTP`. |
|
||||||
This is the place where css and javascript files go. Inside the |
|
||||||
`templates` folder Flask will look for `Jinja2`_ templates. Drop all the |
|
||||||
templates there. |
|
||||||
|
|
||||||
.. _Jinja2: http://jinja.pocoo.org/2/ |
|
||||||
|
|
||||||
Step 1: Database Schema |
|
||||||
----------------------- |
|
||||||
|
|
||||||
First we want to create the database schema. For this application only a |
|
||||||
single table is needed and we only want to support SQLite so that is quite |
|
||||||
easy. Just put the following contents into a file named `schema.sql` in |
|
||||||
the just created `flaskr` folder: |
|
||||||
|
|
||||||
.. sourcecode:: sql |
|
||||||
|
|
||||||
drop table if exists entries; |
|
||||||
create table entries ( |
|
||||||
id integer primary key autoincrement, |
|
||||||
title string not null, |
|
||||||
text string not null |
|
||||||
); |
|
||||||
|
|
||||||
This schema consists of a single table called `entries` and each row in |
|
||||||
this table has an `id`, a `title` and a `text`. The `id` is an |
|
||||||
automatically incrementing integer and a primary key, the other two are |
|
||||||
strings that must not be null. |
|
||||||
|
|
||||||
Step 2: Application Setup Code |
|
||||||
------------------------------ |
|
||||||
|
|
||||||
Now that we have the schema in place we can create the application module. |
|
||||||
Let's call it `flaskr.py` inside the `flaskr` folder. For starters we |
|
||||||
will add the imports we will need as well as the config section. For |
|
||||||
small applications it's a possibility to drop the configuration directly |
|
||||||
into the module which we will be doing here. However a cleaner solution |
|
||||||
would be to create a separate `.ini` or `.py` file and load that or import |
|
||||||
the values from there. |
|
||||||
|
|
||||||
:: |
|
||||||
|
|
||||||
# all the imports |
|
||||||
import sqlite3 |
|
||||||
from flask import Flask, request, session, g, redirect, url_for, \ |
|
||||||
abort, render_template, flash |
|
||||||
|
|
||||||
# configuration |
|
||||||
DATABASE = '/tmp/flaskr.db' |
|
||||||
DEBUG = True |
|
||||||
SECRET_KEY = 'development key' |
|
||||||
USERNAME = 'admin' |
|
||||||
PASSWORD = 'default' |
|
||||||
|
|
||||||
Next we can create our actual application and initialize it with the |
|
||||||
config:: |
|
||||||
|
|
||||||
# create our little application :) |
|
||||||
app = Flask(__name__) |
|
||||||
app.secret_key = SECRET_KEY |
|
||||||
app.debug = DEBUG |
|
||||||
|
|
||||||
The `secret_key` is needed to keep the client-side sessions secure. |
|
||||||
Choose that key wisely and as hard to guess and complex as possible. The |
|
||||||
debug flag enables or disables the interactive debugger. Never leave |
|
||||||
debug mode activated in a production system because it will allow users to |
|
||||||
executed code on the server! |
|
||||||
|
|
||||||
We also add a method to easily connect to the database specified. That |
|
||||||
can be used to open a connection on request and also from the interactive |
|
||||||
Python shell or a script. This will come in handy later |
|
||||||
|
|
||||||
:: |
|
||||||
|
|
||||||
def connect_db(): |
|
||||||
return sqlite3.connect(DATABASE) |
|
||||||
|
|
||||||
Finally we just add a line to the bottom of the file that fires up the |
|
||||||
server if we run that file as standalone application:: |
|
||||||
|
|
||||||
if __name__ == '__main__': |
|
||||||
app.run() |
|
||||||
|
|
||||||
With that out of the way you should be able to start up the application |
|
||||||
without problems. When you head over to the server you will get an 404 |
|
||||||
page not found error because we don't have any views yet. But we will |
|
||||||
focus on that a little later. First we should get the database working. |
|
||||||
|
|
||||||
.. admonition:: Troubleshooting |
|
||||||
|
|
||||||
If you notice later that the browser cannot connect to the server |
|
||||||
during development, you might want to try this line instead:: |
|
||||||
|
|
||||||
app.run(host='127.0.0.1') |
|
||||||
|
|
||||||
In a nutshell: Werkzeug starts up as IPv6 on many operating systems by |
|
||||||
default and not every browser is happy with that. This forces IPv4 |
|
||||||
usage. |
|
||||||
|
|
||||||
Step 3: Creating The Database |
|
||||||
----------------------------- |
|
||||||
|
|
||||||
Flaskr is a database powered application as outlined earlier, and more |
|
||||||
precisely, an application powered by a relational database system. Such |
|
||||||
systems need a schema that tells them how to store that information. So |
|
||||||
before starting the server for the first time it's important to create |
|
||||||
that schema. |
|
||||||
|
|
||||||
Such a schema can be created by piping the `schema.sql` file into the |
|
||||||
`sqlite3` command as follows:: |
|
||||||
|
|
||||||
sqlite3 /tmp/flaskr.db < schema.sql |
|
||||||
|
|
||||||
The downside of this is that it requires the sqlite3 command to be |
|
||||||
installed which is not necessarily the case on every system. Also one has |
|
||||||
to provide the path to the database there which leaves some place for |
|
||||||
errors. It's a good idea to add a function that initializes the database |
|
||||||
for you to the application. |
|
||||||
|
|
||||||
If you want to do that, you first have to import the |
|
||||||
:func:`contextlib.closing` function from the contextlib package. If you |
|
||||||
want to use Python 2.5 it's also necessary to enable the `with` statement |
|
||||||
first (`__future__` imports must be the very first import):: |
|
||||||
|
|
||||||
from __future__ import with_statement |
|
||||||
from contextlib import closing |
|
||||||
|
|
||||||
Next we can create a function called `init_db` that initializes the |
|
||||||
database. For this we can use the `connect_db` function we defined |
|
||||||
earlier. Just add that function below the `connect_db` function:: |
|
||||||
|
|
||||||
def init_db(): |
|
||||||
with closing(connect_db()) as db: |
|
||||||
with app.open_resource('schema.sql') as f: |
|
||||||
db.cursor().executescript(f.read()) |
|
||||||
db.commit() |
|
||||||
|
|
||||||
The :func:`~contextlib.closing` helper function allows us to keep a |
|
||||||
connection open for the duration of the `with` block. The |
|
||||||
:func:`~flask.Flask.open_resource` method of the application object |
|
||||||
supports that functionality out of the box, so it can be used in the |
|
||||||
`with` block directly. This function opens a file from the resource |
|
||||||
location (your `flaskr` folder) and allows you to read from it. We are |
|
||||||
using this here to execute a script on the database connection. |
|
||||||
|
|
||||||
When we connect to a database we get a connection object (here called |
|
||||||
`db`) that can give us a cursor. On that cursor there is a method to |
|
||||||
execute a complete script. Finally we only have to commit the changes. |
|
||||||
SQLite 3 and other transactional databases will not commit unless you |
|
||||||
explicitly tell it to. |
|
||||||
|
|
||||||
Now it is possible to create a database by starting up a Python shell and |
|
||||||
importing and calling that function:: |
|
||||||
|
|
||||||
>>> from flaskr import init_db |
|
||||||
>>> init_db() |
|
||||||
|
|
||||||
Step 4: Request Database Connections |
|
||||||
------------------------------------ |
|
||||||
|
|
||||||
Now we know how we can open database connections and use them for scripts, |
|
||||||
but how can we elegantly do that for requests? We will need the database |
|
||||||
connection in all our functions so it makes sense to initialize them |
|
||||||
before each request and shut them down afterwards. |
|
||||||
|
|
||||||
Flask allows us to do that with the :meth:`~flask.Flask.before_request` and |
|
||||||
:meth:`~flask.Flask.after_request` decorators:: |
|
||||||
|
|
||||||
@app.before_request |
|
||||||
def before_request(): |
|
||||||
g.db = connect_db() |
|
||||||
|
|
||||||
@app.after_request |
|
||||||
def after_request(response): |
|
||||||
g.db.close() |
|
||||||
return response |
|
||||||
|
|
||||||
Functions marked with :meth:`~flask.Flask.before_request` are called before |
|
||||||
a request and passed no arguments, functions marked with |
|
||||||
:meth:`~flask.Flask.after_request` are called after a request and |
|
||||||
passed the response that will be sent to the client. They have to return |
|
||||||
that response object or a different one. In this case we just return it |
|
||||||
unchanged. |
|
||||||
|
|
||||||
We store our current database connection on the special :data:`~flask.g` |
|
||||||
object that flask provides for us. This object stores information for one |
|
||||||
request only and is available from within each function. Never store such |
|
||||||
things on other objects because this would not work with threaded |
|
||||||
environments. That special :data:`~flask.g` object does some magic behind |
|
||||||
the scenes to ensure it does the right thing. |
|
||||||
|
|
||||||
Step 5: The View Functions |
|
||||||
-------------------------- |
|
||||||
|
|
||||||
Now that the database connections are working we can start writing the |
|
||||||
view functions. We will need four of them: |
|
||||||
|
|
||||||
Show Entries |
|
||||||
```````````` |
|
||||||
|
|
||||||
This view shows all the entries stored in the database. It listens on the |
|
||||||
root of the application and will select title and text from the database. |
|
||||||
The one with the highest id (the newest entry) on top. The rows returned |
|
||||||
from the cursor are tuples with the columns ordered like specified in the |
|
||||||
select statement. This is good enough for small applications like here, |
|
||||||
but you might want to convert them into a dict. If you are interested how |
|
||||||
to do that, check out the :ref:`easy-querying` example. |
|
||||||
|
|
||||||
The view function will pass the entries as dicts to the |
|
||||||
`show_entries.html` template and return the rendered one:: |
|
||||||
|
|
||||||
@app.route('/') |
|
||||||
def show_entries(): |
|
||||||
cur = g.db.execute('select title, text from entries order by id desc') |
|
||||||
entries = [dict(title=row[0], text=row[1]) for row in cur.fetchall()] |
|
||||||
return render_template('show_entries.html', entries=entries) |
|
||||||
|
|
||||||
Add New Entry |
|
||||||
````````````` |
|
||||||
|
|
||||||
This view lets the user add new entries if he's logged in. This only |
|
||||||
responds to `POST` requests, the actual form is shown on the |
|
||||||
`show_entries` page. If everything worked out well we will |
|
||||||
:func:`~flask.flash` an information message to the next request and |
|
||||||
redirect back to the `show_entries` page:: |
|
||||||
|
|
||||||
@app.route('/add', methods=['POST']) |
|
||||||
def add_entry(): |
|
||||||
if not session.get('logged_in'): |
|
||||||
abort(401) |
|
||||||
g.db.execute('insert into entries (title, text) values (?, ?)', |
|
||||||
[request.form['title'], request.form['text']]) |
|
||||||
g.db.commit() |
|
||||||
flash('New entry was successfully posted') |
|
||||||
return redirect(url_for('show_entries')) |
|
||||||
|
|
||||||
Note that we check that the user is logged in here (the `logged_in` key is |
|
||||||
present in the session and `True`). |
|
||||||
|
|
||||||
Login and Logout |
|
||||||
```````````````` |
|
||||||
|
|
||||||
These functions are used to sign the user in and out. Login checks the |
|
||||||
username and password against the ones from the configuration and sets the |
|
||||||
`logged_in` key in the session. If the user logged in successfully that |
|
||||||
key is set to `True` and the user is redirected back to the `show_entries` |
|
||||||
page. In that case also a message is flashed that informs the user he or |
|
||||||
she was logged in successfully. If an error occoured the template is |
|
||||||
notified about that and the user asked again:: |
|
||||||
|
|
||||||
@app.route('/login', methods=['GET', 'POST']) |
|
||||||
def login(): |
|
||||||
error = None |
|
||||||
if request.method == 'POST': |
|
||||||
if request.form['username'] != USERNAME: |
|
||||||
error = 'Invalid username' |
|
||||||
elif request.form['password'] != PASSWORD: |
|
||||||
error = 'Invalid password' |
|
||||||
else: |
|
||||||
session['logged_in'] = True |
|
||||||
flash('You were logged in') |
|
||||||
return redirect(url_for('show_entries')) |
|
||||||
return render_template('login.html', error=error) |
|
||||||
|
|
||||||
The logout function on the other hand removes that key from the session |
|
||||||
again. We use a neat trick here: if you use the :meth:`~dict.pop` method |
|
||||||
of the dict and pass a second parameter to it (the default) the method |
|
||||||
will delete the key from the dictionary if present or do nothing when that |
|
||||||
key was not in there. This is helpful because we don't have to check in |
|
||||||
that case if the user was logged in. |
|
||||||
|
|
||||||
:: |
|
||||||
|
|
||||||
@app.route('/logout') |
|
||||||
def logout(): |
|
||||||
session.pop('logged_in', None) |
|
||||||
flash('You were logged out') |
|
||||||
return redirect(url_for('show_entries')) |
|
||||||
|
|
||||||
Step 6: The Templates |
|
||||||
--------------------- |
|
||||||
|
|
||||||
Now we should start working on the templates. If we request the URLs now |
|
||||||
we would only get an exception that Flask cannot find the templates. The |
|
||||||
templates are using `Jinja2`_ syntax and have autoescaping enabled by |
|
||||||
default. This means that unless you mark a value in the code with |
|
||||||
:class:`~flask.Markup` or with the ``|safe`` filter in the template, |
|
||||||
Jinja2 will ensure that special characters such as ``<`` or ``>`` are |
|
||||||
escaped with their XML equivalents. |
|
||||||
|
|
||||||
We are also using template inheritance which makes it possible to reuse |
|
||||||
the layout of the website in all pages. |
|
||||||
|
|
||||||
Put the following templates into the `templates` folder: |
|
||||||
|
|
||||||
layout.html |
|
||||||
``````````` |
|
||||||
|
|
||||||
This template contains the HTML skeleton, the header and a link to log in |
|
||||||
(or log out if the user was already logged in). It also displays the |
|
||||||
flashed messages if there are any. The ``{% block body %}`` block can be |
|
||||||
replaced by a block of the same name (``body``) in a child template. |
|
||||||
|
|
||||||
The :class:`~flask.session` dict is available in the template as well and |
|
||||||
you can use that to check if the user is logged in or not. Note that in |
|
||||||
Jinja you can access missing attributes and items of objects / dicts which |
|
||||||
makes the following code work, even if there is no ``'logged_in'`` key in |
|
||||||
the session: |
|
||||||
|
|
||||||
.. sourcecode:: html+jinja |
|
||||||
|
|
||||||
<!doctype html> |
|
||||||
<title>Flaskr</title> |
|
||||||
<link rel=stylesheet type=text/css href="{{ url_for('static', filename='style.css') }}"> |
|
||||||
<div class=page> |
|
||||||
<h1>Flaskr</h1> |
|
||||||
<div class=metanav> |
|
||||||
{% if not session.logged_in %} |
|
||||||
<a href="{{ url_for('login') }}">log in</a> |
|
||||||
{% else %} |
|
||||||
<a href="{{ url_for('logout') }}">log out</a> |
|
||||||
{% endif %} |
|
||||||
</div> |
|
||||||
{% for message in get_flashed_messages() %} |
|
||||||
<div class=flash>{{ message }}</div> |
|
||||||
{% endfor %} |
|
||||||
{% block body %}{% endblock %} |
|
||||||
</div> |
|
||||||
|
|
||||||
show_entries.html |
|
||||||
````````````````` |
|
||||||
|
|
||||||
This template extends the `layout.html` template from above to display the |
|
||||||
messages. Note that the `for` loop iterates over the messages we passed |
|
||||||
in with the :func:`~flask.render_template` function. We also tell the |
|
||||||
form to submit to your `add_entry` function and use `POST` as `HTTP` |
|
||||||
method: |
|
||||||
|
|
||||||
.. sourcecode:: html+jinja |
|
||||||
|
|
||||||
{% extends "layout.html" %} |
|
||||||
{% block body %} |
|
||||||
{% if session.logged_in %} |
|
||||||
<form action="{{ url_for('add_entry') }}" method=post class=add-entry> |
|
||||||
<dl> |
|
||||||
<dt>Title: |
|
||||||
<dd><input type=text size=30 name=title> |
|
||||||
<dt>Text: |
|
||||||
<dd><textarea name=text rows=5 cols=40></textarea> |
|
||||||
<dd><input type=submit value=Share> |
|
||||||
</dl> |
|
||||||
</form> |
|
||||||
{% endif %} |
|
||||||
<ul class=entries> |
|
||||||
{% for entry in entries %} |
|
||||||
<li><h2>{{ entry.title }}</h2>{{ entry.text|safe }} |
|
||||||
{% else %} |
|
||||||
<li><em>Unbelievable. No entries here so far</em> |
|
||||||
{% endfor %} |
|
||||||
</ul> |
|
||||||
{% endblock %} |
|
||||||
|
|
||||||
login.html |
|
||||||
`````````` |
|
||||||
|
|
||||||
Finally the login template which basically just displays a form to allow |
|
||||||
the user to login: |
|
||||||
|
|
||||||
.. sourcecode:: html+jinja |
|
||||||
|
|
||||||
{% extends "layout.html" %} |
|
||||||
{% block body %} |
|
||||||
<h2>Login</h2> |
|
||||||
{% if error %}<p class=error><strong>Error:</strong> {{ error }}{% endif %} |
|
||||||
<form action="{{ url_for('login') }}" method=post> |
|
||||||
<dl> |
|
||||||
<dt>Username: |
|
||||||
<dd><input type=text name=username> |
|
||||||
<dt>Password: |
|
||||||
<dd><input type=password name=password> |
|
||||||
<dd><input type=submit value=Login> |
|
||||||
</dl> |
|
||||||
</form> |
|
||||||
{% endblock %} |
|
||||||
|
|
||||||
Step 7: Adding Style |
|
||||||
-------------------- |
|
||||||
|
|
||||||
Now that everything else works, it's time to add some style to the |
|
||||||
application. Just create a stylesheet called `style.css` in the `static` |
|
||||||
folder we created before: |
|
||||||
|
|
||||||
.. sourcecode:: css |
|
||||||
|
|
||||||
body { font-family: sans-serif; background: #eee; } |
|
||||||
a, h1, h2 { color: #377BA8; } |
|
||||||
h1, h2 { font-family: 'Georgia', serif; margin: 0; } |
|
||||||
h1 { border-bottom: 2px solid #eee; } |
|
||||||
h2 { font-size: 1.2em; } |
|
||||||
|
|
||||||
.page { margin: 2em auto; width: 35em; border: 5px solid #ccc; |
|
||||||
padding: 0.8em; background: white; } |
|
||||||
.entries { list-style: none; margin: 0; padding: 0; } |
|
||||||
.entries li { margin: 0.8em 1.2em; } |
|
||||||
.entries li h2 { margin-left: -1em; } |
|
||||||
.add-entry { font-size: 0.9em; border-bottom: 1px solid #ccc; } |
|
||||||
.add-entry dl { font-weight: bold; } |
|
||||||
.metanav { text-align: right; font-size: 0.8em; padding: 0.3em; |
|
||||||
margin-bottom: 1em; background: #fafafa; } |
|
||||||
.flash { background: #CEE5F5; padding: 0.5em; |
|
||||||
border: 1px solid #AACBE2; } |
|
||||||
.error { background: #F0D6D6; padding: 0.5em; } |
|
||||||
|
|
||||||
Bonus: Testing the Application |
|
||||||
------------------------------- |
|
||||||
|
|
||||||
Now that you have finished the application and everything works as |
|
||||||
expected, it's probably not the best idea to add automated tests to |
|
||||||
simplify modifications in the future. The application above is used as a |
|
||||||
basic example of how to perform unittesting in the :ref:`testing` section |
|
||||||
of the documentation. Go there to see how easy it is to test Flask |
|
||||||
applications. |
|
||||||
@ -0,0 +1,27 @@ |
|||||||
|
Step 7: Adding Style |
||||||
|
==================== |
||||||
|
|
||||||
|
Now that everything else works, it's time to add some style to the |
||||||
|
application. Just create a stylesheet called `style.css` in the `static` |
||||||
|
folder we created before: |
||||||
|
|
||||||
|
.. sourcecode:: css |
||||||
|
|
||||||
|
body { font-family: sans-serif; background: #eee; } |
||||||
|
a, h1, h2 { color: #377BA8; } |
||||||
|
h1, h2 { font-family: 'Georgia', serif; margin: 0; } |
||||||
|
h1 { border-bottom: 2px solid #eee; } |
||||||
|
h2 { font-size: 1.2em; } |
||||||
|
|
||||||
|
.page { margin: 2em auto; width: 35em; border: 5px solid #ccc; |
||||||
|
padding: 0.8em; background: white; } |
||||||
|
.entries { list-style: none; margin: 0; padding: 0; } |
||||||
|
.entries li { margin: 0.8em 1.2em; } |
||||||
|
.entries li h2 { margin-left: -1em; } |
||||||
|
.add-entry { font-size: 0.9em; border-bottom: 1px solid #ccc; } |
||||||
|
.add-entry dl { font-weight: bold; } |
||||||
|
.metanav { text-align: right; font-size: 0.8em; padding: 0.3em; |
||||||
|
margin-bottom: 1em; background: #fafafa; } |
||||||
|
.flash { background: #CEE5F5; padding: 0.5em; |
||||||
|
border: 1px solid #AACBE2; } |
||||||
|
.error { background: #F0D6D6; padding: 0.5em; } |
||||||
@ -0,0 +1,33 @@ |
|||||||
|
Step 4: Request Database Connections |
||||||
|
------------------------------------ |
||||||
|
|
||||||
|
Now we know how we can open database connections and use them for scripts, |
||||||
|
but how can we elegantly do that for requests? We will need the database |
||||||
|
connection in all our functions so it makes sense to initialize them |
||||||
|
before each request and shut them down afterwards. |
||||||
|
|
||||||
|
Flask allows us to do that with the :meth:`~flask.Flask.before_request` and |
||||||
|
:meth:`~flask.Flask.after_request` decorators:: |
||||||
|
|
||||||
|
@app.before_request |
||||||
|
def before_request(): |
||||||
|
g.db = connect_db() |
||||||
|
|
||||||
|
@app.after_request |
||||||
|
def after_request(response): |
||||||
|
g.db.close() |
||||||
|
return response |
||||||
|
|
||||||
|
Functions marked with :meth:`~flask.Flask.before_request` are called before |
||||||
|
a request and passed no arguments, functions marked with |
||||||
|
:meth:`~flask.Flask.after_request` are called after a request and |
||||||
|
passed the response that will be sent to the client. They have to return |
||||||
|
that response object or a different one. In this case we just return it |
||||||
|
unchanged. |
||||||
|
|
||||||
|
We store our current database connection on the special :data:`~flask.g` |
||||||
|
object that flask provides for us. This object stores information for one |
||||||
|
request only and is available from within each function. Never store such |
||||||
|
things on other objects because this would not work with threaded |
||||||
|
environments. That special :data:`~flask.g` object does some magic behind |
||||||
|
the scenes to ensure it does the right thing. |
||||||
@ -0,0 +1,57 @@ |
|||||||
|
Step 3: Creating The Database |
||||||
|
============================= |
||||||
|
|
||||||
|
Flaskr is a database powered application as outlined earlier, and more |
||||||
|
precisely, an application powered by a relational database system. Such |
||||||
|
systems need a schema that tells them how to store that information. So |
||||||
|
before starting the server for the first time it's important to create |
||||||
|
that schema. |
||||||
|
|
||||||
|
Such a schema can be created by piping the `schema.sql` file into the |
||||||
|
`sqlite3` command as follows:: |
||||||
|
|
||||||
|
sqlite3 /tmp/flaskr.db < schema.sql |
||||||
|
|
||||||
|
The downside of this is that it requires the sqlite3 command to be |
||||||
|
installed which is not necessarily the case on every system. Also one has |
||||||
|
to provide the path to the database there which leaves some place for |
||||||
|
errors. It's a good idea to add a function that initializes the database |
||||||
|
for you to the application. |
||||||
|
|
||||||
|
If you want to do that, you first have to import the |
||||||
|
:func:`contextlib.closing` function from the contextlib package. If you |
||||||
|
want to use Python 2.5 it's also necessary to enable the `with` statement |
||||||
|
first (`__future__` imports must be the very first import):: |
||||||
|
|
||||||
|
from __future__ import with_statement |
||||||
|
from contextlib import closing |
||||||
|
|
||||||
|
Next we can create a function called `init_db` that initializes the |
||||||
|
database. For this we can use the `connect_db` function we defined |
||||||
|
earlier. Just add that function below the `connect_db` function:: |
||||||
|
|
||||||
|
def init_db(): |
||||||
|
with closing(connect_db()) as db: |
||||||
|
with app.open_resource('schema.sql') as f: |
||||||
|
db.cursor().executescript(f.read()) |
||||||
|
db.commit() |
||||||
|
|
||||||
|
The :func:`~contextlib.closing` helper function allows us to keep a |
||||||
|
connection open for the duration of the `with` block. The |
||||||
|
:func:`~flask.Flask.open_resource` method of the application object |
||||||
|
supports that functionality out of the box, so it can be used in the |
||||||
|
`with` block directly. This function opens a file from the resource |
||||||
|
location (your `flaskr` folder) and allows you to read from it. We are |
||||||
|
using this here to execute a script on the database connection. |
||||||
|
|
||||||
|
When we connect to a database we get a connection object (here called |
||||||
|
`db`) that can give us a cursor. On that cursor there is a method to |
||||||
|
execute a complete script. Finally we only have to commit the changes. |
||||||
|
SQLite 3 and other transactional databases will not commit unless you |
||||||
|
explicitly tell it to. |
||||||
|
|
||||||
|
Now it is possible to create a database by starting up a Python shell and |
||||||
|
importing and calling that function:: |
||||||
|
|
||||||
|
>>> from flaskr import init_db |
||||||
|
>>> init_db() |
||||||
@ -0,0 +1,19 @@ |
|||||||
|
Step 0: Creating The Folders |
||||||
|
============================ |
||||||
|
|
||||||
|
Before we get started, let's create the folders needed for this |
||||||
|
application:: |
||||||
|
|
||||||
|
/flaskr |
||||||
|
/static |
||||||
|
/templates |
||||||
|
|
||||||
|
The `flaskr` folder is not a python package, but just something where we |
||||||
|
drop our files. Directly into this folder we will then put our database |
||||||
|
schema as well as main module in the following steps. The files inside |
||||||
|
the `static` folder are available to users of the application via `HTTP`. |
||||||
|
This is the place where css and javascript files go. Inside the |
||||||
|
`templates` folder Flask will look for `Jinja2`_ templates. Drop all the |
||||||
|
templates there. |
||||||
|
|
||||||
|
.. _Jinja2: http://jinja.pocoo.org/2/ |
||||||
@ -0,0 +1,32 @@ |
|||||||
|
.. _tutorial: |
||||||
|
|
||||||
|
Tutorial |
||||||
|
======== |
||||||
|
|
||||||
|
You want to develop an application with Python and Flask? Here you have |
||||||
|
the chance to learn that by example. In this tutorial we will create a |
||||||
|
simple microblog application. It only supports one user that can create |
||||||
|
text-only entries and there are no feeds or comments, but it still |
||||||
|
features everything you need to get started. We will use Flask and SQLite |
||||||
|
as database which comes out of the box with Python, so there is nothing |
||||||
|
else you need. |
||||||
|
|
||||||
|
If you want the full sourcecode in advance or for comparison, check out |
||||||
|
the `example source`_. |
||||||
|
|
||||||
|
.. _example source: |
||||||
|
http://github.com/mitsuhiko/flask/tree/master/examples/flaskr/ |
||||||
|
|
||||||
|
.. toctree:: |
||||||
|
:maxdepth: 2 |
||||||
|
|
||||||
|
introduction |
||||||
|
folders |
||||||
|
schema |
||||||
|
setup |
||||||
|
dbcon |
||||||
|
dbinit |
||||||
|
views |
||||||
|
templates |
||||||
|
css |
||||||
|
testing |
||||||
@ -0,0 +1,29 @@ |
|||||||
|
Introducing Flaskr |
||||||
|
================== |
||||||
|
|
||||||
|
We will call our blogging application flaskr here, feel free to chose a |
||||||
|
less web-2.0-ish name ;) Basically we want it to do the following things: |
||||||
|
|
||||||
|
1. let the user sign in and out with credentials specified in the |
||||||
|
configuration. Only one user is supported. |
||||||
|
2. when the user is logged in he or she can add new entries to the page |
||||||
|
consisting of a text-only title and some HTML for the text. This HTML |
||||||
|
is not sanitized because we trust the user here. |
||||||
|
3. the page shows all entries so far in reverse order (newest on top) and |
||||||
|
the user can add new ones from there if logged in. |
||||||
|
|
||||||
|
We will be using SQlite3 directly for that application because it's good |
||||||
|
enough for an application of that size. For larger applications however |
||||||
|
it makes a lot of sense to use `SQLAlchemy`_ that handles database |
||||||
|
connections in a more intelligent way, allows you to target different |
||||||
|
relational databases at once and more. You might also want to consider |
||||||
|
one of the popular NoSQL databases if your data is more suited for those. |
||||||
|
|
||||||
|
Here a screenshot from the final application: |
||||||
|
|
||||||
|
.. image:: ../_static/flaskr.png |
||||||
|
:align: center |
||||||
|
:class: screenshot |
||||||
|
:alt: screenshot of the final application |
||||||
|
|
||||||
|
.. _SQLAlchemy: http://www.sqlalchemy.org/ |
||||||
@ -0,0 +1,21 @@ |
|||||||
|
Step 1: Database Schema |
||||||
|
======================= |
||||||
|
|
||||||
|
First we want to create the database schema. For this application only a |
||||||
|
single table is needed and we only want to support SQLite so that is quite |
||||||
|
easy. Just put the following contents into a file named `schema.sql` in |
||||||
|
the just created `flaskr` folder: |
||||||
|
|
||||||
|
.. sourcecode:: sql |
||||||
|
|
||||||
|
drop table if exists entries; |
||||||
|
create table entries ( |
||||||
|
id integer primary key autoincrement, |
||||||
|
title string not null, |
||||||
|
text string not null |
||||||
|
); |
||||||
|
|
||||||
|
This schema consists of a single table called `entries` and each row in |
||||||
|
this table has an `id`, a `title` and a `text`. The `id` is an |
||||||
|
automatically incrementing integer and a primary key, the other two are |
||||||
|
strings that must not be null. |
||||||
@ -0,0 +1,69 @@ |
|||||||
|
Step 2: Application Setup Code |
||||||
|
============================== |
||||||
|
|
||||||
|
Now that we have the schema in place we can create the application module. |
||||||
|
Let's call it `flaskr.py` inside the `flaskr` folder. For starters we |
||||||
|
will add the imports we will need as well as the config section. For |
||||||
|
small applications it's a possibility to drop the configuration directly |
||||||
|
into the module which we will be doing here. However a cleaner solution |
||||||
|
would be to create a separate `.ini` or `.py` file and load that or import |
||||||
|
the values from there. |
||||||
|
|
||||||
|
:: |
||||||
|
|
||||||
|
# all the imports |
||||||
|
import sqlite3 |
||||||
|
from flask import Flask, request, session, g, redirect, url_for, \ |
||||||
|
abort, render_template, flash |
||||||
|
|
||||||
|
# configuration |
||||||
|
DATABASE = '/tmp/flaskr.db' |
||||||
|
DEBUG = True |
||||||
|
SECRET_KEY = 'development key' |
||||||
|
USERNAME = 'admin' |
||||||
|
PASSWORD = 'default' |
||||||
|
|
||||||
|
Next we can create our actual application and initialize it with the |
||||||
|
config:: |
||||||
|
|
||||||
|
# create our little application :) |
||||||
|
app = Flask(__name__) |
||||||
|
app.secret_key = SECRET_KEY |
||||||
|
app.debug = DEBUG |
||||||
|
|
||||||
|
The `secret_key` is needed to keep the client-side sessions secure. |
||||||
|
Choose that key wisely and as hard to guess and complex as possible. The |
||||||
|
debug flag enables or disables the interactive debugger. Never leave |
||||||
|
debug mode activated in a production system because it will allow users to |
||||||
|
executed code on the server! |
||||||
|
|
||||||
|
We also add a method to easily connect to the database specified. That |
||||||
|
can be used to open a connection on request and also from the interactive |
||||||
|
Python shell or a script. This will come in handy later |
||||||
|
|
||||||
|
:: |
||||||
|
|
||||||
|
def connect_db(): |
||||||
|
return sqlite3.connect(DATABASE) |
||||||
|
|
||||||
|
Finally we just add a line to the bottom of the file that fires up the |
||||||
|
server if we run that file as standalone application:: |
||||||
|
|
||||||
|
if __name__ == '__main__': |
||||||
|
app.run() |
||||||
|
|
||||||
|
With that out of the way you should be able to start up the application |
||||||
|
without problems. When you head over to the server you will get an 404 |
||||||
|
page not found error because we don't have any views yet. But we will |
||||||
|
focus on that a little later. First we should get the database working. |
||||||
|
|
||||||
|
.. admonition:: Troubleshooting |
||||||
|
|
||||||
|
If you notice later that the browser cannot connect to the server |
||||||
|
during development, you might want to try this line instead:: |
||||||
|
|
||||||
|
app.run(host='127.0.0.1') |
||||||
|
|
||||||
|
In a nutshell: Werkzeug starts up as IPv6 on many operating systems by |
||||||
|
default and not every browser is happy with that. This forces IPv4 |
||||||
|
usage. |
||||||
@ -0,0 +1,107 @@ |
|||||||
|
Step 6: The Templates |
||||||
|
===================== |
||||||
|
|
||||||
|
Now we should start working on the templates. If we request the URLs now |
||||||
|
we would only get an exception that Flask cannot find the templates. The |
||||||
|
templates are using `Jinja2`_ syntax and have autoescaping enabled by |
||||||
|
default. This means that unless you mark a value in the code with |
||||||
|
:class:`~flask.Markup` or with the ``|safe`` filter in the template, |
||||||
|
Jinja2 will ensure that special characters such as ``<`` or ``>`` are |
||||||
|
escaped with their XML equivalents. |
||||||
|
|
||||||
|
We are also using template inheritance which makes it possible to reuse |
||||||
|
the layout of the website in all pages. |
||||||
|
|
||||||
|
Put the following templates into the `templates` folder: |
||||||
|
|
||||||
|
.. _Jinja2: http://jinja.pocoo.org/2/documentation/templates |
||||||
|
|
||||||
|
layout.html |
||||||
|
----------- |
||||||
|
|
||||||
|
This template contains the HTML skeleton, the header and a link to log in |
||||||
|
(or log out if the user was already logged in). It also displays the |
||||||
|
flashed messages if there are any. The ``{% block body %}`` block can be |
||||||
|
replaced by a block of the same name (``body``) in a child template. |
||||||
|
|
||||||
|
The :class:`~flask.session` dict is available in the template as well and |
||||||
|
you can use that to check if the user is logged in or not. Note that in |
||||||
|
Jinja you can access missing attributes and items of objects / dicts which |
||||||
|
makes the following code work, even if there is no ``'logged_in'`` key in |
||||||
|
the session: |
||||||
|
|
||||||
|
.. sourcecode:: html+jinja |
||||||
|
|
||||||
|
<!doctype html> |
||||||
|
<title>Flaskr</title> |
||||||
|
<link rel=stylesheet type=text/css href="{{ url_for('static', filename='style.css') }}"> |
||||||
|
<div class=page> |
||||||
|
<h1>Flaskr</h1> |
||||||
|
<div class=metanav> |
||||||
|
{% if not session.logged_in %} |
||||||
|
<a href="{{ url_for('login') }}">log in</a> |
||||||
|
{% else %} |
||||||
|
<a href="{{ url_for('logout') }}">log out</a> |
||||||
|
{% endif %} |
||||||
|
</div> |
||||||
|
{% for message in get_flashed_messages() %} |
||||||
|
<div class=flash>{{ message }}</div> |
||||||
|
{% endfor %} |
||||||
|
{% block body %}{% endblock %} |
||||||
|
</div> |
||||||
|
|
||||||
|
show_entries.html |
||||||
|
----------------- |
||||||
|
|
||||||
|
This template extends the `layout.html` template from above to display the |
||||||
|
messages. Note that the `for` loop iterates over the messages we passed |
||||||
|
in with the :func:`~flask.render_template` function. We also tell the |
||||||
|
form to submit to your `add_entry` function and use `POST` as `HTTP` |
||||||
|
method: |
||||||
|
|
||||||
|
.. sourcecode:: html+jinja |
||||||
|
|
||||||
|
{% extends "layout.html" %} |
||||||
|
{% block body %} |
||||||
|
{% if session.logged_in %} |
||||||
|
<form action="{{ url_for('add_entry') }}" method=post class=add-entry> |
||||||
|
<dl> |
||||||
|
<dt>Title: |
||||||
|
<dd><input type=text size=30 name=title> |
||||||
|
<dt>Text: |
||||||
|
<dd><textarea name=text rows=5 cols=40></textarea> |
||||||
|
<dd><input type=submit value=Share> |
||||||
|
</dl> |
||||||
|
</form> |
||||||
|
{% endif %} |
||||||
|
<ul class=entries> |
||||||
|
{% for entry in entries %} |
||||||
|
<li><h2>{{ entry.title }}</h2>{{ entry.text|safe }} |
||||||
|
{% else %} |
||||||
|
<li><em>Unbelievable. No entries here so far</em> |
||||||
|
{% endfor %} |
||||||
|
</ul> |
||||||
|
{% endblock %} |
||||||
|
|
||||||
|
login.html |
||||||
|
---------- |
||||||
|
|
||||||
|
Finally the login template which basically just displays a form to allow |
||||||
|
the user to login: |
||||||
|
|
||||||
|
.. sourcecode:: html+jinja |
||||||
|
|
||||||
|
{% extends "layout.html" %} |
||||||
|
{% block body %} |
||||||
|
<h2>Login</h2> |
||||||
|
{% if error %}<p class=error><strong>Error:</strong> {{ error }}{% endif %} |
||||||
|
<form action="{{ url_for('login') }}" method=post> |
||||||
|
<dl> |
||||||
|
<dt>Username: |
||||||
|
<dd><input type=text name=username> |
||||||
|
<dt>Password: |
||||||
|
<dd><input type=password name=password> |
||||||
|
<dd><input type=submit value=Login> |
||||||
|
</dl> |
||||||
|
</form> |
||||||
|
{% endblock %} |
||||||
@ -0,0 +1,9 @@ |
|||||||
|
Bonus: Testing the Application |
||||||
|
=============================== |
||||||
|
|
||||||
|
Now that you have finished the application and everything works as |
||||||
|
expected, it's probably not the best idea to add automated tests to |
||||||
|
simplify modifications in the future. The application above is used as a |
||||||
|
basic example of how to perform unittesting in the :ref:`testing` section |
||||||
|
of the documentation. Go there to see how easy it is to test Flask |
||||||
|
applications. |
||||||
@ -0,0 +1,87 @@ |
|||||||
|
Step 5: The View Functions |
||||||
|
========================== |
||||||
|
|
||||||
|
Now that the database connections are working we can start writing the |
||||||
|
view functions. We will need four of them: |
||||||
|
|
||||||
|
Show Entries |
||||||
|
------------ |
||||||
|
|
||||||
|
This view shows all the entries stored in the database. It listens on the |
||||||
|
root of the application and will select title and text from the database. |
||||||
|
The one with the highest id (the newest entry) on top. The rows returned |
||||||
|
from the cursor are tuples with the columns ordered like specified in the |
||||||
|
select statement. This is good enough for small applications like here, |
||||||
|
but you might want to convert them into a dict. If you are interested how |
||||||
|
to do that, check out the :ref:`easy-querying` example. |
||||||
|
|
||||||
|
The view function will pass the entries as dicts to the |
||||||
|
`show_entries.html` template and return the rendered one:: |
||||||
|
|
||||||
|
@app.route('/') |
||||||
|
def show_entries(): |
||||||
|
cur = g.db.execute('select title, text from entries order by id desc') |
||||||
|
entries = [dict(title=row[0], text=row[1]) for row in cur.fetchall()] |
||||||
|
return render_template('show_entries.html', entries=entries) |
||||||
|
|
||||||
|
Add New Entry |
||||||
|
------------- |
||||||
|
|
||||||
|
This view lets the user add new entries if he's logged in. This only |
||||||
|
responds to `POST` requests, the actual form is shown on the |
||||||
|
`show_entries` page. If everything worked out well we will |
||||||
|
:func:`~flask.flash` an information message to the next request and |
||||||
|
redirect back to the `show_entries` page:: |
||||||
|
|
||||||
|
@app.route('/add', methods=['POST']) |
||||||
|
def add_entry(): |
||||||
|
if not session.get('logged_in'): |
||||||
|
abort(401) |
||||||
|
g.db.execute('insert into entries (title, text) values (?, ?)', |
||||||
|
[request.form['title'], request.form['text']]) |
||||||
|
g.db.commit() |
||||||
|
flash('New entry was successfully posted') |
||||||
|
return redirect(url_for('show_entries')) |
||||||
|
|
||||||
|
Note that we check that the user is logged in here (the `logged_in` key is |
||||||
|
present in the session and `True`). |
||||||
|
|
||||||
|
Login and Logout |
||||||
|
---------------- |
||||||
|
|
||||||
|
These functions are used to sign the user in and out. Login checks the |
||||||
|
username and password against the ones from the configuration and sets the |
||||||
|
`logged_in` key in the session. If the user logged in successfully that |
||||||
|
key is set to `True` and the user is redirected back to the `show_entries` |
||||||
|
page. In that case also a message is flashed that informs the user he or |
||||||
|
she was logged in successfully. If an error occoured the template is |
||||||
|
notified about that and the user asked again:: |
||||||
|
|
||||||
|
@app.route('/login', methods=['GET', 'POST']) |
||||||
|
def login(): |
||||||
|
error = None |
||||||
|
if request.method == 'POST': |
||||||
|
if request.form['username'] != USERNAME: |
||||||
|
error = 'Invalid username' |
||||||
|
elif request.form['password'] != PASSWORD: |
||||||
|
error = 'Invalid password' |
||||||
|
else: |
||||||
|
session['logged_in'] = True |
||||||
|
flash('You were logged in') |
||||||
|
return redirect(url_for('show_entries')) |
||||||
|
return render_template('login.html', error=error) |
||||||
|
|
||||||
|
The logout function on the other hand removes that key from the session |
||||||
|
again. We use a neat trick here: if you use the :meth:`~dict.pop` method |
||||||
|
of the dict and pass a second parameter to it (the default) the method |
||||||
|
will delete the key from the dictionary if present or do nothing when that |
||||||
|
key was not in there. This is helpful because we don't have to check in |
||||||
|
that case if the user was logged in. |
||||||
|
|
||||||
|
:: |
||||||
|
|
||||||
|
@app.route('/logout') |
||||||
|
def logout(): |
||||||
|
session.pop('logged_in', None) |
||||||
|
flash('You were logged out') |
||||||
|
return redirect(url_for('show_entries')) |
||||||
Loading…
Reference in new issue