-
A Quick Flask Walkthrough
-
-
If you've already set up your virtualenv and installed flask, you can simply
-activate it and skip down to Kicking the Tires
-
If not...
-
-
Practice Safe Development
-
We are going to install Flask, and the packages it requires, into a
-virtualenv.
-
This will ensure that it is isolated from everything else we do in class (and
-vice versa)
-
-
Remember the basic format for creating a virtualenv:
-
-$ python virtualenv.py [options] <ENV>
-<or>
-$ virtualenv [options] <ENV>
-
-
-
-
-
Set Up a VirtualEnv
-
Start by creating your virtualenv:
-
-$ python virtualenv.py flaskenv
-<or>
-$ virtualenv flaskenv
-...
-
-
-
Then, activate it:
-
-$ source flaskenv/bin/activate
-<or>
-C:\> flaskenv\Scripts\activate
-
-
-
-
-
Install Flask
-
Finally, install Flask using setuptools or pip:
-
-(flaskenv)$ pip install flask
-Downloading/unpacking flask
- Downloading Flask-0.10.1.tar.gz (544kB): 544kB downloaded
-...
-Installing collected packages: flask, Werkzeug, Jinja2,
- itsdangerous, markupsafe
-...
-Successfully installed flask Werkzeug Jinja2 itsdangerous
- markupsafe
-
-
-
-
Kicking the Tires
-
We've installed the Flask microframework and all of its dependencies.
-
Now, let's see what it can do
-
With your flaskenv activated, create a file called flask_intro.py and
-open it in your text editor.
-
-
-
Flask
-
Getting started with Flask is pretty straightforward. Here's a complete,
-simple app. Type it into flask_intro.py:
-
-from flask import Flask
-app = Flask(__name__)
-
-@app.route('/')
-def hello_world():
- return 'Hello World!'
-
-if __name__ == '__main__':
- app.run()
-
-
-
-
Running our App
-
As you might expect by now, the last block in our flask_intro.py file
-allows us to run this as a python program. Save your file, and in your
-terminal try this:
-
-(flaskenv)$ python flask_intro.py
-
-
Load http://localhost:5000 in your browser to see it in action.
-
-
-
Debugging our App
-
Last week, cgitb provided us with useful feedback when building an app.
-Flask has similar functionality. Make the following changes to your
-flask_intro.py file:
-
-def hello_world():
- bar = 1 / 0
- return 'Hello World!'
-
-if __name__ == '__main__':
- app.run(debug=True)
-
-
Restart your app and then reload your browser to see what happens.
-
Click in the stack trace that appears in your browser. Notice anything fun?
-
(clean up the error when you're done playing).
-
-
-
Your work so far
-
-- You instantiated a Flask app with a name that represents the package or
-module containing the app
-- Because our app is a single Python module, this should be __name__
-- This is used to help the Flask app figure out where to look for
-resources
-
-
-- You defined a function that returned a response body
-- You told the app which requests should use that function with a route
-
-
Let's take a look at how that last bit works for a moment...
-
-
-
URL Routing
-
Remember our bookdb exercise? How did you end up solving the problem of
-mapping an HTTP request to the right function?
-
Flask solves this problem by using the route decorator from your app.
-
A 'route' takes a URL rule (more on that in a minute) and maps it to an
-endpoint and a function.
-
When a request arrives at a URL that matches a known rule, the function is
-called.
-
-
-
URL Rules
-
URL Rules are strings that represent what environ['PATH_INFO'] will look like.
-
They are added to a mapping on the Flask object called the url_map
-
You can call app.add_url_rule() to add a new one
-
Or you can use what we've used, the app.route() decorator
-
-
-
Function or Decorator
-
-def index():
- """some function that returns something"""
- # ...
-
-app.add_url_rule('/', 'homepage', index)
-
-
-
is identical to
-
-@app.route('/', 'homepage')
-def index():
- """some function that returns something"""
- # ...
-
-
-
-
-
Routes Can Be Dynamic
-
A placeholder in a URL rule becomes a named arg to your function (add these
-to flask_intro.py):
-
-@app.route('/profile/<username>')
-def show_profile(username):
- return "My username is %s" % username
-
-
And converters ensure the incoming argument is of the correct type.
-
-@app.route('/div/<float:val>/')
-def divide(val):
- return "%0.2f divided by 2 is %0.2f" % (val, val / 2)
-
-
-
-
Routes Can Be Filtered
-
You can also determine which HTTP methods a given route will accept:
-
-@app.route('/blog/entry/<int:id>/', methods=['GET',])
-def read_entry(id):
- return "reading entry %d" % id
-
-@app.route('/blog/entry/<int:id>/', methods=['POST', ])
-def write_entry(id):
- return 'writing entry %d' % id
-
-
After adding that to flask_intro.py and saving, try loading
-http://localhost:5000/blog/entry/23/ into your browser. Which was called?
-
-
-
Routes Can Be Reversed
-
Reversing a URL means the ability to generate the url that would result in a
-given endpoint being called.
-
This means you don't have to hard-code your URLs when building links
-
That means you can change the URLs for your app without changing code or
-templates
-
This is called decoupling and it is a good thing
-
-
-
Reversing URLs in Flask
-
In Flask, you reverse a url with the url_for function.
-
-- url_for requires an HTTP request context to work
-- You can fake an HTTP request when working in a terminal (or testing)
-- Use the test_request_context method of your app object
-- This is a great chance to use the Python with statement
-- Don't type this
-
-
-from flask import url_for
-with app.test_request_context():
- print url_for('endpoint', **kwargs)
-
-
-
-
Reversing in Action
-
Quit your Flask app with ^C. Then start a python interpreter in that same
-terminal and import your flask_intro.py module:
-
->>> from flask_intro import app
->>> from flask import url_for
->>> with app.test_request_context():
-... print url_for('show_profile', username="cris")
-... print url_for('divide', val=23.7)
-...
-'/profile/cris/'
-'/div/23.7/'
->>>
-
-
-
-
Enough for Now
-
That will give you plenty to think about before class. We'll put this all to
-good use building a real flask app in our next session.
-
-
-
SQL Persistence in Python
-
-
In this tutorial, you'll walk through some basic concepts of data persistence
-using the Python stdlib implementation of DB API 2, sqlite3
-
-
Data Persistence
-
There are many models for persistance of data.
-
-- Flat files
-- Relational Database (SQL RDBMs like PostgreSQL, MySQL, SQLServer, Oracle)
-- Object Stores (Pickle, ZODB)
-- NoSQL Databases (CouchDB, MongoDB, etc)
-
-
It's also one of the most contentious issues in app design.
-
For this reason, it's one of the things that most Small Frameworks leave
-undecided.
-
-
-
Simple SQL
-
PEP 249 describes a
-common API for database connections called DB-API 2.
-
-
The goal was to
-
-achieve a consistency leading to more easily understood modules, code
-that is generally more portable across databases, and a broader reach
-of database connectivity from Python
-source: http://www.python.org/dev/peps/pep-0248/
-
-
-
-
-
A Note on DB API
-
It is important to remember that PEP 249 is only a specification.
-
There is no code or package for DB-API 2 on it's own.
-
Since 2.5, the Python Standard Library has provided a reference
-implementation of the api
-based on SQLite3
-
Before Python 2.5, this package was available as pysqlite
-
-
-
Using DB API
-
To use the DB API with any database other than SQLite3, you must have an
-underlying API package available.
-
-
Implementations are available for:
-
-- PostgreSQL (psycopg2, txpostgres, ...)
-- MySQL (mysql-python, PyMySQL, ...)
-- MS SQL Server (adodbapi, pymssql, mxODBC, pyodbc, ...)
-- Oracle (cx_Oracle, mxODBC, pyodbc, ...)
-- and many more...
-
-
source: http://wiki.python.org/moin/DatabaseInterfaces
-
-
-
-
Installing API Packages
-
Most db api packages can be installed using typical Pythonic methods:
-
-$ easy_install psycopg2
-$ pip install mysql-python
-...
-
-
Most api packages will require that the development headers for the underlying
-database system be available. Without these, the C symbols required for
-communication with the db are not present and the wrapper cannot work.
-
-
-
Not Today
-
We don't want to spend the next hour getting a package installed, so let's use
-sqlite3 instead.
-
I do not recommend using sqlite3 for production web applications, there are
-too many ways in which it falls short
-
But it will provide a solid learning tool
-
-
-
Getting Started
-
In the class resources folder, you'll find an sql directory. Copy that to
-your working directory.
-
Open the file createdb.py in your text editor. Edit main like so:
-
-def main():
- conn = sqlite3.connect(DB_FILENAME)
- if DB_IS_NEW:
- print 'Need to create database and schema'
- else:
- print 'Database exists, assume schema does, too.'
- conn.close()
-
-
-
-
Try It Out
-
Run the createdb.py script to see it in effect:
-
-$ python createdb.py
-Need to create database and schema
-$ python createdb.py
-Database exists, assume schema does, too.
-$ ls
-books.db
-...
-
-
Sqlite3 will automatically create a new database when you connect for the
-first time, if one does not exist.
-
-
-
Set Up A Schema
-
Make the following changes to createdb.py:
-
-DB_FILENAME = 'books.db'
-SCHEMA_FILENAME = 'ddl.sql' # <- this is new
-DB_IS_NEW = not os.path.exists(DB_FILENAME)
-
-def main():
- with sqlite3.connect(DB_FILENAME) as conn: # <- context mgr
- if DB_IS_NEW: # A whole new if clause:
- print 'Creating schema'
- with open(SCHEMA_FILENAME, 'rt') as f:
- schema = f.read()
- conn.executescript(schema)
- else:
- print 'Database exists, assume schema does, too.'
- # delete the `conn.close()` that was here.
-
-
-
-
Verify Your Work
-
Quit your python interpreter and delete the file books.db
-
-
Then run the script from the command line again to try it out:
-
-$ python createdb.py
-Creating schema
-$ python createdb.py
-Database exists, assume schema does, too.
-
-
-
-
-
Introspect the Database
-
Add the following to createdb.py:
-
-# in the imports, add this line:
-from utils import show_table_metadata
-
-else:
- # in the else clause, replace the print statement with this:
- print "Database exists, introspecting:"
- tablenames = ['author', 'book']
- cursor = conn.cursor()
- for name in tablenames:
- print "\n"
- show_table_metadata(cursor, name)
-
-
Then try running python createdb.py again
-
-
-
My Results
-
-$ python createdb.py
-Table Metadata for 'author':
-cid | name | type | notnull | dflt_value | pk |
------------+------------+------------+------------+------------+------------+-
-0 | authorid | INTEGER | 1 | None | 1 |
------------+------------+------------+------------+------------+------------+-
-1 | name | TEXT | 0 | None | 0 |
------------+------------+------------+------------+------------+------------+-
-
-
-Table Metadata for 'book':
-cid | name | type | notnull | dflt_value | pk |
------------+------------+------------+------------+------------+------------+-
-0 | bookid | INTEGER | 1 | None | 1 |
------------+------------+------------+------------+------------+------------+-
-1 | title | TEXT | 0 | None | 0 |
------------+------------+------------+------------+------------+------------+-
-2 | author | INTEGER | 1 | None | 0 |
------------+------------+------------+------------+------------+------------+-
-
-
-
-
Inserting Data
-
Let's load up some data. Fire up your interpreter and type:
-
->>> import sqlite3
->>> insert = """
-... INSERT INTO author (name) VALUES("Iain M. Banks");"""
->>> with sqlite3.connect("books.db") as conn:
-... cur = conn.cursor()
-... cur.execute(insert)
-... cur.rowcount
-... cur.close()
-...
-<sqlite3.Cursor object at 0x10046e880>
-1
->>>
-
-
Did that work?
-
-
-
Querying Data
-
Let's query our database to find out:
-
->>> query = """
-... SELECT * from author;"""
->>> with sqlite3.connect("books.db") as conn:
-... cur = conn.cursor()
-... cur.execute(query)
-... rows = cur.fetchall()
-... for row in rows:
-... print row
-...
-<sqlite3.Cursor object at 0x10046e8f0>
-(1, u'Iain M. Banks')
-
-
Alright! We've got data in there. Let's make it more efficient
-
-
-
Parameterized Statements
-
Try this:
-
->>> insert = """
-... INSERT INTO author (name) VALUES(?);"""
->>> authors = [["China Mieville"], ["Frank Herbert"],
-... ["J.R.R. Tolkien"], ["Susan Cooper"], ["Madeline L'Engle"]]
->>> with sqlite3.connect("books.db") as conn:
-... cur = conn.cursor()
-... cur.executemany(insert, authors)
-... print cur.rowcount
-... cur.close()
-...
-<sqlite3.Cursor object at 0x10046e8f0>
-5
-
-
-
-
Check Your Work
-
Again, query the database:
-
->>> query = """
-... SELECT * from author;"""
->>> with sqlite3.connect("books.db") as conn:
-... cur = conn.cursor()
-... cur.execute(query)
-... rows = cur.fetchall()
-... for row in rows:
-... print row
-...
-<sqlite3.Cursor object at 0x10046e8f0>
-(1, u'Iain M. Banks')
-...
-(4, u'J.R.R. Tolkien')
-(5, u'Susan Cooper')
-(6, u"Madeline L'Engle")
-
-
-
-
Transactions
-
Transactions group operations together, allowing you to verify them before
-the results hit the database.
-
In SQLite3, data-altering statements require an explicit commit unless
-auto-commit has been enabled.
-
The with statements we've used take care of committing when the context
-manager closes.
-
Let's change that so we can see what happens explicitly
-
-
-
Populating the Database
-
Let's start by seeing what happens when you try to look for newly added data
-before the insert transaction is committed.
-
Begin by quitting your interpreter and deleting books.db.
-
-
Then re-create the database, empty:
-
-$ python createdb.py
-Creating schema
-
-
-
-
-
Setting Up the Test
-
Open populatedb.py in your editor, replace the final print:
-
-conn1 = sqlite3.connect(DB_FILENAME)
-conn2 = sqlite3.connect(DB_FILENAME)
-print "\nOn conn1, before insert:"
-show_authors(conn1)
-authors = ([author] for author in AUTHORS_BOOKS.keys())
-cur = conn1.cursor()
-cur.executemany(author_insert, authors)
-print "\nOn conn1, after insert:"
-show_authors(conn1)
-print "\nOn conn2, before commit:"
-show_authors(conn2)
-conn1.commit()
-print "\nOn conn2, after commit:"
-show_authors(conn2)
-conn1.close()
-conn2.close()
-
-
-
-
Running the Test
-
Quit your python interpreter and run the populatedb.py script:
-
-On conn1, before insert:
-no rows returned
-On conn1, after insert:
-(1, u'China Mieville')
-(2, u'Frank Herbert')
-(3, u'Susan Cooper')
-(4, u'J.R.R. Tolkien')
-(5, u"Madeline L'Engle")
-
-On conn2, before commit:
-no rows returned
-On conn2, after commit:
-(1, u'China Mieville')
-(2, u'Frank Herbert')
-(3, u'Susan Cooper')
-(4, u'J.R.R. Tolkien')
-(5, u"Madeline L'Engle")
-
-
-
-
Rollback
-
That's all well and good, but what happens if an error occurs?
-
Transactions can be rolled back in order to wipe out partially completed work.
-
Like with commit, using connect as a context manager in a with
-statement will automatically rollback for exceptions.
-
Let's rewrite our populatedb script so it explicitly commits or rolls back a
-transaction depending on exceptions occurring
-
-
-
Edit populatedb.py (slide 1)
-
First, add the following function above the if __name__ == '__main__'
-block:
-
-def populate_db(conn):
- authors = ([author] for author in AUTHORS_BOOKS.keys())
- cur = conn.cursor()
- cur.executemany(author_insert, authors)
-
- for author in AUTHORS_BOOKS.keys():
- params = ([book, author] for book in AUTHORS_BOOKS[author])
- cur.executemany(book_insert, params)
-
-
-
-
Edit populatedb.py (slide 2)
-
Then, in the runner:
-
-with sqlite3.connect(DB_FILENAME) as conn1:
- with sqlite3.connect(DB_FILENAME) as conn2:
- try:
- populate_db(conn1)
- print "\nauthors and books on conn2 before commit:"
- show_authors(conn2)
- show_books(conn2)
- except sqlite3.Error:
- conn1.rollback()
- print "\nauthors and books on conn2 after rollback:"
- show_authors(conn2)
- show_books(conn2)
- raise
- else:
- conn1.commit()
- print "\nauthors and books on conn2 after commit:"
- show_authors(conn2)
- show_books(conn2)
-
-
-
-
Try it Out
-
Remove books.db and recrete the database, then run our script:
-
-$ rm books.db
-$ python createdb.py
-Creating schema
-$ python populatedb.py
-
-
-authors and books on conn2 after rollback:
-no rows returned
-no rows returned
-Traceback (most recent call last):
- File "populatedb.py", line 57, in <module>
- populate_db(conn1)
- File "populatedb.py", line 46, in populate_db
- cur.executemany(book_insert, params)
-sqlite3.InterfaceError: Error binding parameter 0 - probably unsupported type.
-
-
-
-
Oooops, Fix It
-
Okay, we got an error, and the transaction was rolled back correctly.
-
-
Open utils.py and find this:
-
-'Susan Cooper': ["The Dark is Rising", ["The Greenwitch"]],
-
-
-
-
Fix it like so:
-
-'Susan Cooper': ["The Dark is Rising", "The Greenwitch"],
-
-
-
It appears that we were attempting to bind a list as a parameter. Ooops.
-
-
-
Try It Again
-
-
Now that the error in our data is repaired, let's try again:
-
-$ python populatedb.py
-
-
-
-Reporting authors and books on conn2 before commit:
-no rows returned
-no rows returned
-Reporting authors and books on conn2 after commit:
-(1, u'China Mieville')
-(2, u'Frank Herbert')
-(3, u'Susan Cooper')
-(4, u'J.R.R. Tolkien')
-(5, u"Madeline L'Engle")
-(1, u'Perdido Street Station', 1)
-(2, u'The Scar', 1)
-(3, u'King Rat', 1)
-(4, u'Dune', 2)
-(5, u"Hellstrom's Hive", 2)
-(6, u'The Dark is Rising', 3)
-(7, u'The Greenwitch', 3)
-(8, u'The Hobbit', 4)
-(9, u'The Silmarillion', 4)
-(10, u'A Wrinkle in Time', 5)
-(11, u'A Swiftly Tilting Planet', 5)
-
-
-
-
Congratulations
-
You've just created a small database of books and authors. The transactional
-protections you've used let you rest comfortable, knowing that so long as the
-process completed, you've got the data you sent.
-
We'll see more of this when we build our flask app.
-
-
-
An Introduction To Django
-
-
In this tutorial, you'll walk through creating a very simple microblog
-application using Django.
-
-
Practice Safe Development
-
We'll install Django and any other packages we use with it in a virtualenv.
-
This will ensure that it is isolated from everything else we do in class (and
-vice versa)
-
-
Remember the basic format for creating a virtualenv:
-
-$ python virtualenv.py [options] <ENV>
-<or>
-$ virtualenv [options] <ENV>
-
-
-
-
-
Set Up a VirtualEnv
-
Start by creating your virtualenv:
-
-$ python virtualenv.py djangoenv
-<or>
-$ virtualenv djangoenv
-...
-
-
-
Then, activate it:
-
-$ source djangoenv/bin/activate
-<or>
-C:\> djangoenv\Scripts\activate
-
-
-
-
-
Install Django
-
Finally, install Django 1.6.2 using pip:
-
-(djangoenv)$ pip install Django==1.6.2
-Downloading/unpacking Django==1.5.2
- Downloading Django-1.6.2.tar.gz (8.0MB): 8.0MB downloaded
- Running setup.py egg_info for package Django
- changing mode of /path/to/djangoenv/bin/django-admin.py to 755
-Successfully installed Django
-Cleaning up...
-(djangoenv)$
-
-
-
-
Starting a Project
-
Everything in Django stems from the project
-
To get started learning, we'll create one
-
We'll use a script installed by Django, django-admin.py:
-
-(djangoenv)$ django-admin.py startproject mysite
-
-
This will create a folder called 'mysite'. Let's take a look at it:
-
-
-
Project Layout
-
The folder created by django-admin.py contains the following structure:
-
-mysite
-├── manage.py
-└── mysite
- ├── __init__.py
- ├── settings.py
- ├── urls.py
- └── wsgi.py
-
-
If what you see doesn't match that, you're using an older version of Django.
-Make sure you've installed 1.6.2.
-
-
-
What Got Created
-
-- outer *mysite* folder: this is just a container and can be renamed or
-moved at will
-- inner *mysite* folder: this is your project directory. It should not be
-renamed.
-- __init__.py: magic file that makes mysite a python package.
-- settings.py: file which holds configuration for your project, more soon.
-- urls.py: file which holds top-level URL configuration for your project,
-more soon.
-- wsgi.py: binds a wsgi application created from your project to the
-symbol application
-- manage.py: a management control script.
-
-
-
-
django-admin.py and manage.py
-
django-admin.py provides a hook for administrative tasks and abilities:
-
-- creating a new project or app
-- running the development server
-- executing tests
-- entering a python interpreter
-- entering a database shell session with your database
-- much much more (run django-admin.py without an argument)
-
-
manage.py wraps this functionality, adding the full environment of your
-project.
-
-
-
How manage.py Works
-
Look in the manage.py script Django created for you. You'll see this:
-
-#!/usr/bin/env python
-import os
-import sys
-
-if __name__ == "__main__":
- os.environ.setdefault("DJANGO_SETTINGS_MODULE", "mysite.settings")
- ...
-
-
The environmental var DJANGO_SETTINGS_MODULE is how the manage.py
-script is made aware of your project's environment. This is why you shouldn't
-rename the project package.
-
-
-
Development Server
-
At this point, you should be ready to use the development server:
-
-(djangoenv)$ cd mysite
-(djangoenv)$ python manage.py runserver
-...
-
-
Load http://localhost:8000 in your browser.
-
-
-
A Blank Slate
-
You should see this:
-
-
Do you?
-
-
-
Connecting A Database
-
Django supplies its own ORM (Object-Relational Mapper)
-
This ORM sits on top of the DB-API implementation you choose.
-
You must provide connection information through Django configuration.
-
All Django configuration takes place in settings.py in your project
-folder.
-
-
-
Your Database Settings
-
Edit your settings.py to match:
-
-DATABASES = {
- 'default': {
- 'ENGINE': 'django.db.backends.sqlite3',
- 'NAME': 'mysite.db',
- }
-}
-
-
There are other database settings, but they are not used with sqlite3, we'll
-ignore them for now.
-
-
-
Django and Your Database
-
Django's ORM provides a layer of abstraction between you and SQL
-
You write Python classes called models describing the object that make up
-your system.
-
The ORM handles converting data from these objects into SQL statements (and
-back)
-
We'll learn much more about this in a bit
-
-
-
Django Organization
-
We've created a Django project. In Django a project represents a whole
-website:
-
-- global configuration settings
-- inclusion points for additional functionality
-- master list of URL endpoints
-
-
A Django app encapsulates a unit of functionality:
-
-- A blog section
-- A discussion forum
-- A content tagging system
-
-
-
-
Apps Make Up a Project
-
One project can (and likely will) consist of many apps
-
-
-
Core Django Apps
-
Django already includes some apps for you.
-
-
They're in settings.py in the INSTALLED_APPS setting:
-
-INSTALLED_APPS = (
- 'django.contrib.auth',
- 'django.contrib.contenttypes',
- 'django.contrib.sessions',
- 'django.contrib.sites',
- 'django.contrib.messages',
- 'django.contrib.staticfiles',
- # Uncomment the next line to enable the admin:
- # 'django.contrib.admin',
- # Uncomment the next line to enable admin documentation:
- # 'django.contrib.admindocs',
-)
-
-
-
-
-
Creating the Database
-
These apps define models of their own, tables must be created.
-
-
You make them by running the syncdb management command:
-
-(djangoenv)$ python manage.py syncdb
-Creating tables ...
-Creating table auth_permission
-Creating table auth_group_permissions
-Creating table auth_group
-...
-You just installed Django's auth system, ...
-Would you like to create one now? (yes/no):
-
-
-
Add your first user at this prompt. I strongly suggest you use the username
-'admin' and give it the password 'admin'. If you don't, make sure you remember
-the values you use.
-
-
-
Our Class App
-
We are going to build an app to add to our project. To start with our app
-will be a lot like the Flask app we finished last time.
-
As stated above, an app represents a unit within a system, the project. We
-have a project, we need to create an app
-
-
-
Create an App
-
This is accomplished using manage.py.
-
In your terminal, make sure you are in the outer mysite directory, where the
-file manage.py is located. Then:
-
-(djangoenv)$ python manage.py startapp myblog
-
-
-
-
What is Created
-
This should leave you with the following structure:
-
-mysite
-├── manage.py
-├── myblog
-│ ├── __init__.py
-│ ├── admin.py
-│ ├── models.py
-│ ├── tests.py
-│ └── views.py
-└── mysite
- ├── __init__.py
- ...
-
-
We'll start by defining the main Python class for our blog system, a Post.
-
-
-
Django Models
-
Any Python class in Django that is meant to be persisted must inherit from
-the Django Model class.
-
This base class hooks in to the ORM functionality converting Python code to
-SQL.
-
You can override methods from the base Model class to alter how this works
-or write new methods to add functionality.
-
Learn more about models
-
-
-
Our Post Model
-
Open the models.py file created in our myblog package. Add the
-following:
-
-from django.db import models #<-- This is already in the file
-from django.contrib.auth.models import User
-
-class Post(models.Model):
- title = models.CharField(max_length=128)
- text = models.TextField(blank=True)
- author = models.ForeignKey(User)
- created_date = models.DateTimeField(auto_now_add=True)
- modified_date = models.DateTimeField(auto_now=True)
- published_date = models.DateTimeField(blank=True, null=True)
-
-
-
-
Model Fields
-
We've created a subclass of the Django Model class and added a bunch of
-attributes.
-
-- These attributes are all instances of Field classes defined in Django
-- Field attributes on a model map to columns in a database table
-- The arguments you provide to each Field customize how it works
-- This means both how it operates in Django and how it is defined in SQL
-
-
-- There are arguments shared by all Field types
-- There are also arguments specific to individual types
-
-
You can read much more about Model Fields and options
-
-
-
Field Details
-
There are some features of our fields worth mentioning in specific:
-
Notice we have no field that is designated as the primary key
-
-- You can make a field the primary key by adding primary_key=True in the
-arguments
-- If you do not, Django will automatically create one. This field is always
-called id
-- No matter what the primary key field is called, its value is always
-available on a model instance as the pk attribute.
-
-
-
-
Field Details
-
-title = models.CharField(max_length=128)
-
-
The required max_length argument is specific to CharField fields.
-
It affects both the Python and SQL behavior of a field.
-
In python, it is used to validate supplied values during model validation
-
In SQL it is used in the column definition: VARCHAR(128)
-
-
-
Field Details
-
-author = models.ForeignKey(User)
-
-
Django also models SQL relationships as specific field types.
-
The required positional argument is the class of the related Model.
-
By default, the reverse relation is implemented as the attribute
-<fieldname>_set.
-
You can override this by providing the related_name argument.
-
-
-
Field Details
-
-created_date = models.DateTimeField(auto_now_add=True)
-modified_date = models.DateTimeField(auto_now=True)
-
-
auto_now_add is available on all date and time fields. It sets the value
-of the field to now when an instance is first saved.
-
auto_now is similar, but sets the value anew each time an instance is
-saved.
-
Setting either of these will cause the editable attribute of a field to be
-set to False.
-
-
-
Field Details
-
-text = models.TextField(blank=True)
-# ...
-published_date = models.DateTimeField(blank=True, null=True)
-
-
The argument blank is shared across all field types. The default is
-False
-
This argument affects only the Python behavior of a field, determining if the
-field is required
-
The related null argument affects the SQL definition of a field: is the
-column NULL or NOT NULL
-
-
-
Hooking it Up
-
In order to use our new model, we need Django to know about our app
-
This is accomplished by configuration in the settings.py file.
-
Open that file now, in your editor, and find the INSTALLED_APPS setting.
-
-
-
Installing Apps
-
You extend Django functionality by installing apps. This is pretty simple:
-
-INSTALLED_APPS = (
- 'django.contrib.auth',
- 'django.contrib.contenttypes',
- 'django.contrib.sessions',
- 'django.contrib.sites',
- 'django.contrib.messages',
- 'django.contrib.staticfiles',
- 'myblog', # <- YOU ADD THIS PART
-)
-
-
-
-
Setting Up the Database
-
You know what the next step will be:
-
-(djangoenv)$ python manage.py syncdb
-Creating tables ...
-Creating table myblog_post
-Installing custom SQL ...
-Installing indexes ...
-Installed 0 object(s) from 0 fixture(s)
-
-
Django has now created a table for our model.
-
Notice that the table name is a combination of the name of our app and the
-name of our model.
-
-
-
The Django Shell
-
Django provides a management command shell:
-
-- Shares the same sys.path as your project, so all installed python
-packages are present.
-- Imports the settings.py file from your project, and so shares all
-installed apps and other settings.
-- Handles connections to your database, so you can interact with live data
-directly.
-
-
Let's explore the Model Instance API directly using this shell:
-
-(djangoenv)$ python manage.py shell
-
-
-
-
Creating Instances
-
Instances of our model can be created by simple instantiation:
-
->>> from myblog.models import Post
->>> p1 = Post(title="My first post",
-... text="This is the first post I've written")
->>> p1
-<Post: Post object>
-
-
-
We can also validate that our new object is okay before we try to save it:
-
->>> p1.full_clean()
-Traceback (most recent call last):
- ...
-ValidationError: {'author': [u'This field cannot be null.']}
-
-
-
-
-
Django Model Managers
-
We have to hook our Post to an author, which must be a User.
-
To do this, we need to have an instance of the User class.
-
We can use the User model manager to run table-level operations like
-SELECT:
-
All Django models have a manager. By default it is accessed through the
-objects class attribute.
-
-
-
Making a ForeignKey Relation
-
Let's use the manager to get an instance of the User class:
-
->>> from django.contrib.auth.models import User
->>> all_users = User.objects.all()
->>> all_users
-[<User: cewing>]
->>> u1 = all_users[0]
->>> p1.author = u1
-
-
-
And now our instance should validate properly:
-
->>> p1.full_clean()
->>>
-
-
-
-
-
Saving New Objects
-
Our model has three date fields, two of which are supposed to be
-auto-populated:
-
->>> print(p1.created_date)
-None
->>> print(p1.modified_date)
-None
-
-
-
When we save our post, these fields will get values assigned:
-
->>> p1.save()
->>> p1.created_date
-datetime.datetime(2013, 7, 26, 20, 2, 38, 104217, tzinfo=<UTC>)
->>> p1.modified_date
-datetime.datetime(2013, 7, 26, 20, 2, 38, 104826, tzinfo=<UTC>)
-
-
-
-
-
Updating An Instance
-
Models operate much like 'normal' python objects.
-
-
To change the value of a field, simply set the instance attribute to a new
-value. Call save() to persist the change:
-
->>> p1.title = p1.title + " (updated)"
->>> p1.save()
->>> p1.title
-'My first post (updated)'
-
-
-
-
-
Create a Few Posts
-
Let's create a few more posts so we can explore the Django model manager query
-API:
-
->>> p2 = Post(title="Another post",
-... text="The second one created",
-... author=u1).save()
->>> p3 = Post(title="The third one",
-... text="With the word 'heffalump'",
-... author=u1).save()
->>> p4 = Post(title="Posters are great decoration",
-... text="When you are a poor college student",
-... author=u1).save()
->>> Post.objects.count()
-4
-
-
-
-
The Django Query API
-
The manager on each model class supports a full-featured query API.
-
API methods take keyword arguments, where the keywords are special
-constructions combining field names with field lookups:
-
-- title__exact="The exact title"
-- text__contains="decoration"
-- id__in=range(1,4)
-- published_date__lte=datetime.datetime.now()
-
-
Each keyword argument generates an SQL clause.
-
-
-
QuerySets
-
API methods can be divided into two basic groups: methods that return
-QuerySets and those that do not.
-
The former may be chained without hitting the database:
-
->>> a = Post.objects.all() #<-- no query yet
->>> b = a.filter(title__icontains="post") #<-- not yet
->>> c = b.exclude(text__contains="created") #<-- nope
->>> [(p.title, p.text) for p in c] #<-- This will issue the query
-
-
-
Conversely, the latter will issue an SQL query when executed.
-
->>> a.count() # immediately executes an SQL query
-
-
-
-
-
QuerySets and SQL
-
If you are curious, you can see the SQL that a given QuerySet will use:
-
->>> print(c.query)
-SELECT "myblog_post"."id", "myblog_post"."title",
- "myblog_post"."text", "myblog_post"."author_id",
- "myblog_post"."created_date", "myblog_post"."modified_date",
- "myblog_post"."published_date"
-FROM "myblog_post"
-WHERE ("myblog_post"."title" LIKE %post% ESCAPE '\'
- AND NOT ("myblog_post"."text" LIKE %created% ESCAPE '\' )
-)
-
-
The SQL will vary depending on which DBAPI backend you use (yay ORM!!!)
-
-
-
Exploring the QuerySet API
-
See https://docs.djangoproject.com/en/1.6/ref/models/querysets
-
->>> [p.pk for p in Post.objects.all().order_by('created_date')]
-[1, 2, 3, 4]
->>> [p.pk for p in Post.objects.all().order_by('-created_date')]
-[4, 3, 2, 1]
->>> [p.pk for p in Post.objects.filter(title__contains='post')]
-[1, 2, 4]
->>> [p.pk for p in Post.objects.exclude(title__contains='post')]
-[3]
->>> qs = Post.objects.exclude(title__contains='post')
->>> qs = qs.exclude(id__exact=3)
->>> [p.pk for p in qs]
-[]
->>> qs = Post.objects.exclude(title__contains='post', id__exact=3)
->>> [p.pk for p in qs]
-[1, 2, 3, 4]
-
-
-
-
Updating via QuerySets
-
You can update all selected objects at the same time.
-
Changes are persisted without needing to call save.
-
->>> qs = Post.objects.all()
->>> [p.published_date for p in qs]
-[None, None, None, None]
->>> from datetime import datetime
->>> from django.utils.timezone import UTC
->>> utc = UTC()
->>> now = datetime.now(utc)
->>> qs.update(published_date=now)
-4
->>> [p.published_date for p in qs]
-[datetime.datetime(2013, 7, 27, 1, 20, 30, 505307, tzinfo=<UTC>),
- ...]
-
-
-
-
Testing Our Model
-
As with any project, we want to test our work. Django provides a testing
-framework to allow this.
-
Django supports both unit tests and doctests. I strongly suggest using
-unit tests.
-
You add tests for your app to the file tests.py, which should be at the
-same package level as models.py.
-
Locate and open this file in your editor.
-
-
-
Django TestCase Classes
-
SimpleTestCase is for basic unit testing with no ORM requirements
-
TransactionTestCase is useful if you need to test transactional
-actions (commit and rollback) in the ORM
-
TestCase is used when you require ORM access and a test client
-
LiveServerTestCase launches the django server during test runs for
-front-end acceptance tests.
-
-
-
Testing Data
-
Sometimes testing requires base data to be present. We need a User for ours.
-
Django provides fixtures to handle this need.
-
Create a directory called fixtures inside your myblog app directory.
-
Copy the file myblog_test_fixture.json from the class resources into this
-directory, it contains users for our tests.
-
-
-
Setting Up Tests
-
Now that we have a fixture, we need to instruct our tests to use it.
-
-
Edit tests.py (which comes with one test already) to look like this:
-
-from django.test import TestCase
-from django.contrib.auth.models import User
-
-class PostTestCase(TestCase):
- fixtures = ['myblog_test_fixture.json', ]
-
- def setUp(self):
- self.user = User.objects.get(pk=1)
-
-
-
-
-
Our First Enhancement
-
Look at the way our Post represents itself in the Django shell:
-
->>> [p for p in Post.objects.all()]
-[<Post: Post object>, <Post: Post object>,
- <Post: Post object>, <Post: Post object>]
-
-
Wouldn't it be nice if the posts showed their titles instead?
-
In Django, the __unicode__ method is used to determine how a Model
-instance represents itself.
-
Then, calling unicode(instance) gives the desired result.
-
-
-
Write The Test
-
Let's write a test that demonstrates our desired outcome:
-
-# add this import at the top
-from myblog.models import Post
-
-# and this test method to the PostTestCase
-def test_unicode(self):
- expected = "This is a title"
- p1 = Post(title=expected)
- actual = unicode(p1)
- self.assertEqual(expected, actual)
-
-
-
-
Run The Test
-
To run tests, use the test management command
-
Without arguments, it will run all TestCases it finds in all installed apps
-
You can pass the name of a single app to focus on those tests
-
Quit your Django shell and in your terminal run the test we wrote:
-
-(djangoenv)$ python manage.py test myblog
-
-
-
-
The Result
-
We have yet to implement this enhancement, so our test should fail:
-
-Creating test database for alias 'default'...
-F
-======================================================================
-FAIL: test_unicode (myblog.tests.PostTestCase)
-----------------------------------------------------------------------
-Traceback (most recent call last):
- File "/Users/cewing/projects/training/uw_pce/training.python_web/scripts/session07/mysite/myblog/tests.py", line 15, in test_unicode
- self.assertEqual(expected, actual)
-AssertionError: 'This is a title' != u'Post object'
-
-----------------------------------------------------------------------
-Ran 1 test in 0.007s
-
-FAILED (failures=1)
-Destroying test database for alias 'default'...
-
-
-
-
Make it Pass
-
Let's add an appropriate __unicode__ method to our Post class
-
It will take self as its only argument
-
And it should return its own title as the result
-
Go ahead and take a stab at this in models.py
-
-class Post(models.Model):
- #...
-
- def __unicode__(self):
- return self.title
-
-
-
-
Did It Work?
-
Re-run the tests to see:
-
-(djangoenv)$ python manage.py test myblog
-Creating test database for alias 'default'...
-.
-----------------------------------------------------------------------
-Ran 1 test in 0.007s
-
-OK
-Destroying test database for alias 'default'...
-
-
YIPEEEE!
-
-
-
What to Test
-
In any framework, the question arises of what to test. Much of your app's
-functionality is provided by framework tools. Does that need testing?
-
I usually don't write tests covering features provided directly by the
-framework.
-
I do write tests for functionality I add, and for places where I make
-changes to how the default functionality works.
-
This is largely a matter of style and taste (and of budget).
-
-
-
-
The Django Admin
-
There are some who believe that Django has been Python's killer app
-
And without doubt the Django Admin is a killer feature for Django.
-
To demonstrate this, we are going to set up the admin for our blog
-
-
-
Using the Admin
-
The Django Admin is, itself, an app, installed by default (as of 1.6).
-
Open the settings.py file from our mysite project package and
-verify that you see it in the list:
-
-INSTALLED_APPS = (
- 'django.contrib.admin', # <- already present
- # ...
- 'django.contrib.staticfiles', # <- already present
- 'myblog', # <- already present
-)
-
-
-
-
Accessing the Admin
-
What we need now is to allow the admin to be seen through a web browser.
-
To do that, we'll have to add some URLs to our project.
-
-
-
Django URL Resolution
-
Django too has a system for dispatching requests to code: the urlconf.
-
-- A urlconf is a an iterable of calls to the django.conf.urls.url function
-- This function takes:
-- a regexp rule, representing the URL
-- a callable to be invoked (or a name identifying one)
-- an optional name kwarg, used to reverse the URL
-- other optional arguments we will skip for now
-
-
-- The function returns a resolver that matches the request path to the
-callable
-
-
-
-
urlpatterns
-
I said above that a urlconf is an iterable.
-
That iterable is generally built by calling the django.conf.urls.patterns
-function.
-
It's best to build it that way, but in reality, any iterable will do.
-
However, the name you give this iterable is not flexible.
-
Django will load the urlconf named urlpatterns that it finds in the file
-named in settings.ROOT_URLCONF.
-
-
-
Including URLs
-
Many Django add-on apps, like the Django Admin, come with their own urlconf
-
It is standard to include these urlconfs by rooting them at some path in your
-site.
-
-
You can do this by using the django.conf.urls.include function as the
-callable in a url call:
-
-url(r'^forum/', include('random.forum.app.urls'))
-
-
-
-
-
Including the Admin
-
We can use this to add all the URLs provided by the Django admin in one
-stroke.
-
-
verify the following lines in urls.py:
-
-from django.contrib import admin #<- make sure these two are
-admin.autodiscover() #<- present and uncommented
-
-urlpatterns = patterns('',
- ...
- url(r'^admin/', include(admin.site.urls)), #<- and this
-)
-
-
-
-
-
Using the Development Server
-
We can now view the admin. We'll use the Django development server.
-
In your terminal, use the runserver management command to start the
-development server:
-
-(djangoenv)$ python manage.py runserver
-Validating models...
-
-0 errors found
-Django version 1.4.3, using settings 'mysite.settings'
-Development server is running at http://127.0.0.1:8000/
-Quit the server with CONTROL-C.
-
-
-
-
Viewing the Admin
-
Load http://localhost:8000/admin/. You should see this:
-
-
Login with the name and password you created before.
-
-
-
The Admin Index
-
The index will provide a list of all the installed apps and each model
-registered. You should see this:
-
-
Click on Users. Find yourself? Edit yourself, but don't uncheck
-superuser.
-
-
-
Add Posts to the Admin
-
Okay, let's add our app model to the admin.
-
Find the admin.py file in the myblog package. Open it, add the
-following and save the file:
-
-from django.contrib import admin # <- this is already there.
-from myblog.models import Post
-
-admin.site.register(Post)
-
-
Reload the admin index page.
-
-
-
Play A Bit
-
Visit the admin page for Posts. You should see the posts we created earlier in
-the Django shell.
-
Look at the listing of Posts. Because of our __unicode__ method we see a
-nice title.
-
Are there other fields you'd like to see listed?
-
Click on a Post, note what is and is not shown.
-
-
-
Next Steps
-
We've learned a great deal about Django's ORM and Models.
-
We've also spent some time getting to know the Query API provided by model
-managers and QuerySets.
-
We've also hooked up the Django Admin and noted some shortcomings.
-
In class we'll learn how to put a front end on this, add new models, and
-customize the admin experience.
-
-