mirror of https://github.com/mitsuhiko/flask.git
Armin Ronacher
15 years ago
9 changed files with 394 additions and 14 deletions
|
After Width: | Height: | Size: 52 KiB |
@ -0,0 +1,354 @@
|
||||
.. _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. |
||||
|
||||
Here a screenshot from the final application: |
||||
|
||||
.. image:: _static/flaskr.png |
||||
:align: center |
||||
:class: screenshot |
||||
:alt: screenshot of the final application |
||||
|
||||
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. |
||||
|
||||
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:: |
||||
|
||||
# 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' |
||||
|
||||
The `with_statement` and :func:`~contextlib.closing` function are used to |
||||
make dealing with the database connection easier later on for setting up |
||||
the initial database. 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 |
||||
|
||||
We can also add a method to easily connect to the database sepcified:: |
||||
|
||||
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() |
||||
|
||||
.. 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. |
||||
|
||||
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. |
||||
|
||||
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:: |
||||
|
||||
def init_db(): |
||||
with closing(connect_db()) as db: |
||||
with app.open_resource('schema.sql') as f: |
||||
db.cursor().executescript(f.read()) |
||||
db.commit() |
||||
|
||||
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() |
||||
|
||||
The :meth:`~flask.Flask.open_resource` 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 and |
||||
close the transaction. |
||||
|
||||
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.request_init` and |
||||
:meth:`~flask.Flask.request_shutdown` decorators:: |
||||
|
||||
@app.request_init |
||||
def before_request(): |
||||
g.db = connect_db() |
||||
|
||||
@app.request_shutdown |
||||
def after_request(response): |
||||
g.db.close() |
||||
return response |
||||
|
||||
Functions marked with :meth:`~flask.Flask.request_init` are called before |
||||
a request and passed no arguments, functions marked with |
||||
:meth:`~flask.Flask.request_shutdown` 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 for of them: |
||||
|
||||
Show Entries |
||||
```````````` |
||||
|
||||
This view shows all the entries stored in the database:: |
||||
|
||||
@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:: |
||||
|
||||
@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')) |
||||
|
||||
Login and Logout |
||||
```````````````` |
||||
|
||||
These functions are used to sign the user in and out:: |
||||
|
||||
@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) |
||||
|
||||
@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. |
||||
|
||||
Put the following templates into the `templates` folder: |
||||
|
||||
layout.html |
||||
``````````` |
||||
|
||||
.. 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 |
||||
````````````````` |
||||
|
||||
.. sourcecode:: html+jinja |
||||
|
||||
{% extends "layout.html" %} |
||||
{% block body %} |
||||
{% if g.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 |
||||
`````````` |
||||
|
||||
.. 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 %} |
||||
Loading…
Reference in new issue