Hide Notes 

Slide 1: Django | Documentation • Home • Download • Documentation • Weblog • Community • Code Django documentation Documentation These docs are for Django's SVN release, which can be significantly different than previous releases. Get old docs here: 0.96, 0.95. The Django Book We're in the process of writing the official Django book. Follow its progress at djangobook.com. Note that it assumes you're using the Django development version rather than version 0.96. The essential documentation Make sure to read the following documentation. The rest (in the "Reference" section below) can be read in any particular order, as you need the various functionality. • Django overview • Installation guide • Tutorial: Writing your first Django app ♦ Part 1: Initialization, creating models, the database API ♦ Part 2: Exploring the automatically-generated admin site ♦ Part 3: Creating the public interface views ♦ Part 4: Simple form processing and generic views • Frequently asked questions (FAQ) • How to read this documentation Reference • The django-admin.py and manage.py utilities • Models: Creating models | Examples | The database API | Transactions • Templates: Guide for HTML authors | Guide for Python programmers • The newforms library | The old forms and manipulators library • New: Testing Django applications • Sessions Documentation 1
Slide 2: Django | Documentation • Caching • Internationalization • Middleware • Settings files • URL configuration • Request and response objects • Generic views • Authentication • The django.contrib add-ons ♦ New: Databrowse ♦ Syndication feeds (RSS and Atom) (django.contrib.syndication) ♦ Flatpages (django.contrib.flatpages) ♦ Redirects (django.contrib.redirects) ♦ Sites (django.contrib.sites) ♦ Sitemaps (django.contrib.sitemaps) ♦ New: Web design helpers (django.contrib.webdesign) Deployment • Using Django with mod_python • How to use Django with FastCGI, SCGI or AJP Solving specific problems • Authenticating against Django's user database from Apache • Serving static/media files • Sending e-mail • Integrating with (introspecting) a legacy database • Outputting PDFs dynamically • Outputting CSV dynamically Et cetera • Design philosophies • How to contribute to Django • Django admin CSS guide • API stability • Backwards-incompatible changes Release notes • Version 0.96 • Version 0.95 Search docs via Google Reference 2
Slide 3: Django | Documentation Getting help • #django IRC channel • #django IRC logs • Django-users mailing list • Django-developers mailing list • Report a bug • Recent comments posted to djangoproject.com © 2005-2007 Lawrence Journal-World unless otherwise noted. Django is a registered trademark of Lawrence Journal-World. Getting help 3
Slide 4: Django | Documentation • Home • Download • Documentation • Weblog • Community • Code Django documentation Django at a glance This document is for Django's SVN release, which can be significantly different than previous releases. Get old docs here: 0.96, 0.95. Because Django was developed in a fast-paced newsroom environment, it was designed to make common Web-development tasks fast and easy. Here’s an informal overview of how to write a database-driven Web app with Django. The goal of this document is to give you enough technical specifics to understand how Django works, but this isn’t intended to be a tutorial or reference. Please see our more-detailed Django documentation when you’re ready to start a project. Design your model Although you can use Django without a database, it comes with an object-relational mapper in which you describe your database layout in Python code. The data-model syntax offers many rich ways of representing your models — so far, it’s been solving two years’ worth of database-schema problems. Here’s a quick example: class Reporter(models.Model): full_name = models.CharField(max_length=70) def __unicode__(self): return self.full_name class Article(models.Model): pub_date = models.DateTimeField() headline = models.CharField(max_length=200) article = models.TextField() reporter = models.ForeignKey(Reporter) def __unicode__(self): return self.headline Django at a glance 4
Slide 5: Django | Documentation Install it Next, run the Django command-line utility to create the database tables automatically: manage.py syncdb The syncdb command looks at all your available models and creates tables in your database for whichever tables don’t already exist. Enjoy the free API With that, you’ve got a free, and rich, Python API to access your data. The API is created on the fly: No code generation necessary: >>> from mysite.models import Reporter, Article # No reporters are in the system yet. >>> Reporter.objects.all() [] # Create a new Reporter. >>> r = Reporter(full_name='John Smith') # Save the object into the database. You have to call save() explicitly. >>> r.save() # Now it has an ID. >>> r.id 1 # Now the new reporter is in the database. >>> Reporter.objects.all() [John Smith] # Fields are represented as attributes on the Python object. >>> r.full_name 'John Smith' # Django provides a rich database lookup API. >>> Reporter.objects.get(id=1) John Smith >>> Reporter.objects.get(full_name__startswith='John') John Smith >>> Reporter.objects.get(full_name__contains='mith') John Smith >>> Reporter.objects.get(id=2) Traceback (most recent call last): ... DoesNotExist: Reporter does not exist for {'id__exact': 2} # Create an article. >>> from datetime import datetime >>> a = Article(pub_date=datetime.now(), headline='Django is cool', ... article='Yeah.', reporter=r) >>> a.save() # Now the article is in the database. Install it 5
Slide 6: Django | Documentation >>> Article.objects.all() [Django is cool] # Article objects get API access to related Reporter objects. >>> r = a.reporter >>> r.full_name 'John Smith' # And vice versa: Reporter objects get API access to Article objects. >>> r.article_set.all() [Django is cool] # The API follows relationships as far as you need, performing efficient # JOINs for you behind the scenes. # This finds all articles by a reporter whose name starts with "John". >>> Article.objects.filter(reporter__full_name__startswith="John") [Django is cool] # Change an object by altering its attributes and calling save(). >>> r.full_name = 'Billy Goat' >>> r.save() # Delete an object with delete(). >>> r.delete() A dynamic admin interface: It’s not just scaffolding — it’s the whole house Once your models are defined, Django can automatically create a professional, production ready administrative interface — a Web site that lets authenticated users add, change and delete objects. It’s as easy as adding a line of code to your model classes: class Article(models.Model): pub_date = models.DateTimeField() headline = models.CharField(max_length=200) article = models.TextField() reporter = models.ForeignKey(Reporter) class Admin: pass The philosophy here is that your site is edited by a staff, or a client, or maybe just you — and you don’t want to have to deal with creating backend interfaces just to manage content. One typical workflow in creating Django apps is to create models and get the admin sites up and running as fast as possible, so your staff (or clients) can start populating data. Then, develop the way data is presented to the public. Design your URLs A clean, elegant URL scheme is an important detail in a high-quality Web application. Django encourages beautiful URL design and doesn’t put any cruft in URLs, like .php or .asp. To design URLs for an app, you create a Python module called a URLconf. A table of contents for your app, it contains a simple mapping between URL patterns and Python callback functions. URLconfs also serve to decouple URLs from Python code. Enjoy the free API 6
Slide 7: Django | Documentation Here’s what a URLconf might look like for the Reporter/Article example above: from django.conf.urls.defaults import * urlpatterns = patterns('', (r'^articles/(\d{4})/$', 'mysite.views.year_archive'), (r'^articles/(\d{4})/(\d{2})/$', 'mysite.views.month_archive'), (r'^articles/(\d{4})/(\d{2})/(\d+)/$', 'mysite.views.article_detail'), ) The code above maps URLs, as simple regular expressions, to the location of Python callback functions (“views”). The regular expressions use parenthesis to “capture” values from the URLs. When a user requests a page, Django runs through each pattern, in order, and stops at the first one that matches the requested URL. (If none of them matches, Django calls a special-case 404 view.) This is blazingly fast, because the regular expressions are compiled at load time. Once one of the regexes matches, Django imports and calls the given view, which is a simple Python function. Each view gets passed a request object — which contains request metadata — and the values captured in the regex. For example, if a user requested the URL “/articles/2005/05/39323/”, Django would call the function mysite.views.article_detail(request, '2005', '05', '39323'). Write your views Each view is responsible for doing one of two things: Returning an HttpResponse object containing the content for the requested page, or raising an exception such as Http404. The rest is up to you. Generally, a view retrieves data according to the parameters, loads a template and renders the template with the retrieved data. Here’s an example view for year_archive from above: def year_archive(request, year): a_list = Article.objects.filter(pub_date__year=year) return render_to_response('news/year_archive.html', {'year': year, 'article_list': a_list}) This example uses Django’s template system, which has several powerful features but strives to stay simple enough for non-programmers to use. Design your templates The code above loads the news/year_archive.html template. Django has a template search path, which allows you to minimize redundancy among templates. In your Django settings, you specify a list of directories to check for templates. If a template doesn’t exist in the first directory, it checks the second, and so on. Let’s say the news/article_detail.html template was found. Here’s what that might look like: {% extends "base.html" %} {% block title %}Articles for {{ year }}{% endblock %} Design your URLs 7
Slide 8: Django | Documentation {% block content %} <h1>Articles for {{ year }}</h1> {% for article in article_list %} <p>{{ article.headline }}</p> <p>By {{ article.reporter.full_name }}</p> <p>Published {{ article.pub_date|date:"F j, Y" }}</p> {% endfor %} {% endblock %} Variables are surrounded by double-curly braces. {{ article.headline }} means “Output the value of the article’s headline attribute.” But dots aren’t used only for attribute lookup: They also can do dictionary-key lookup, index lookup and function calls. Note {{ article.pub_date|date:"F j, Y" }} uses a Unix-style “pipe” (the “|” character). This is called a template filter, and it’s a way to filter the value of a variable. In this case, the date filter formats a Python datetime object in the given format (as found in PHP’s date function; yes, there is one good idea in PHP). You can chain together as many filters as you’d like. You can write custom filters. You can write custom template tags, which run custom Python code behind the scenes. Finally, Django uses the concept of “template inheritance”: That’s what the {% extends "base.html" %} does. It means “First load the template called ‘base’, which has defined a bunch of blocks, and fill the blocks with the following blocks.” In short, that lets you dramatically cut down on redundancy in templates: Each template has to define only what’s unique to that template. Here’s what the “base.html” template might look like: <html> <head> <title>{% block title %}{% endblock %}</title> </head> <body> <img src="sitelogo.gif" alt="Logo" /> {% block content %}{% endblock %} </body> </html> Simplistically, it defines the look-and-feel of the site (with the site’s logo), and provides “holes” for child templates to fill. This makes a site redesign as easy as changing a single file — the base template. It also lets you create multiple versions of a site, with different base templates, while reusing child templates. Django’s creators have used this technique to create strikingly different cell-phone editions of sites — simply by creating a new base template. Note that you don’t have to use Django’s template system if you prefer another system. While Django’s template system is particularly well-integrated with Django’s model layer, nothing forces you to use it. For that matter, you don’t have to use Django’s database API, either. You can use another database abstraction layer, you can read XML files, you can read files off disk, or anything you want. Each piece of Django — models, views, templates — is decoupled from the next. Design your templates 8
Slide 9: Django | Documentation This is just the surface This has been only a quick overview of Django’s functionality. Some more useful features: • A caching framework that integrates with memcached or other backends. • A syndication framework that makes creating RSS and Atom feeds as easy as writing a small Python class. • More sexy automatically-generated admin features — this overview barely scratched the surface. The next obvious steps are for you to download Django, read the tutorial and join the community. Thanks for your interest! Questions/Feedback If you notice errors with this documentation, please open a ticket and let us know! Please only use the ticket tracker for criticisms and improvements on the docs. For tech support, ask in the IRC channel or post to the django-users list. Contents • Design your model • Install it • Enjoy the free API • A dynamic admin interface: It’s not just scaffolding — it’s the whole house • Design your URLs • Write your views • Design your templates • This is just the surface Last update: August 5, 12:14 a.m. © 2005-2007 Lawrence Journal-World unless otherwise noted. Django is a registered trademark of Lawrence Journal-World. This is just the surface 9
Slide 10: Django | Documentation • Home • Download • Documentation • Weblog • Community • Code Django documentation How to install Django This document is for Django's SVN release, which can be significantly different than previous releases. Get old docs here: 0.96, 0.95. This document will get you up and running with Django. Install Python Being a Python Web framework, Django requires Python. It works with any Python version 2.3 and higher. Get Python at http://www.python.org. If you’re running Linux or Mac OS X, you probably already have it installed. Install Apache and mod_python If you just want to experiment with Django, skip ahead to the next section; Django includes a lightweight web server you can use for testing, so you won’t need to set up Apache until you’re ready to deploy Django in production. If you want to use Django on a production site, use Apache with mod_python. mod_python is similar to mod_perl — it embeds Python within Apache and loads Python code into memory when the server starts. Code stays in memory throughout the life of an Apache process, which leads to significant performance gains over other server arrangements. Make sure you have Apache installed, with the mod_python module activated. Django requires Apache 2.x and mod_python 3.x. See How to use Django with mod_python for information on how to configure mod_python once you have it installed. If you can’t use mod_python for some reason, fear not: Django follows the WSGI spec, which allows it to run on a variety of server platforms. See the server-arrangements wiki page for specific installation instructions for each platform. How to install Django 10
Slide 11: Django | Documentation Get your database running If you plan to use Django’s database API functionality, you’ll need to make sure a database server is running. Django works with PostgreSQL, MySQL, Oracle and SQLite (the latter doesn’t require a separate server to be running). Additionally, you’ll need to make sure your Python database bindings are installed. • If you’re using PostgreSQL, you’ll need the psycopg package. Django supports both version 1 and 2. (When you configure Django’s database layer, specify either postgresql [for version 1] or postgresql_psycopg2 [for version 2].) If you’re on Windows, check out the unofficial compiled Windows version. • If you’re using MySQL, you’ll need MySQLdb, version 1.2.1p2 or higher. You will also want to read the database-specific notes for the MySQL backend. • If you’re using SQLite, you’ll need pysqlite. Use version 2.0.3 or higher. • If you’re using Oracle, you’ll need cx_Oracle, version 4.3.1 or higher. Remove any old versions of Django If you are upgrading your installation of Django from a previous version, you will need to uninstall the old Django version before installing the new version. If you installed Django using setup.py install, uninstalling is as simple as deleting the django directory from your Python site-packages. If you installed Django from a Python egg, remove the Django .egg file, and remove the reference to the egg in the file named easy-install.pth. This file should also be located in your site-packages directory. Where are my site-packages stored? The location of the site-packages directory depends on the operating system, and the location in which Python was installed. To find out your system’s site-packages location, execute the following: python -c "from distutils.sysconfig import get_python_lib; print get_python_lib()" (Note that this should be run from a shell prompt, not a Python interactive prompt.) Install the Django code Installation instructions are slightly different depending on whether you’re installing a distribution-specific package, downloading the the latest official release, or fetching the latest development version. It’s easy, no matter which way you choose. Get your database running 11
Slide 12: Django | Documentation Installing a distribution-specific package Check the distribution specific notes to see if your platform/distribution provides official Django packages/installers. Distribution-provided packages will typically allow for automatic installation of dependancies and easy upgrade paths. Installing an official release 1. Download the latest release from our download page. 2. Untar the downloaded file (e.g. tar xzvf Django-NNN.tar.gz). 3. Change into the downloaded directory (e.g. cd Django-NNN). 4. Run sudo python setup.py install. The command will install Django in your Python installation’s site-packages directory. Installing the development version If you’d like to be able to update your Django code occasionally with the latest bug fixes and improvements, follow these instructions: 1. Make sure you have Subversion installed. 2. Check out the Django code into your Python site-packages directory. On Linux / Mac OSX / Unix, do this: svn co http://code.djangoproject.com/svn/django/trunk/ django_src ln -s `pwd`/django_src/django SITE-PACKAGES-DIR/django (In the above line, change SITE-PACKAGES-DIR to match the location of your system’s site-packages directory, as explained in the “Where are my site-packages stored?” section above.) On Windows, do this: 3. Copy the file django_src/django/bin/django-admin.py to somewhere on your system path, such as /usr/local/bin (Unix) or C:\Python24\Scripts (Windows). This step simply lets you type django-admin.py from within any directory, rather than having to qualify the command with the full path to the file. You don’t have to run python setup.py install, because that command takes care of steps 2 and 3 for you. When you want to update your copy of the Django source code, just run the command svn update from within the django directory. When you do this, Subversion will automatically download any changes. svn co http://code.djangoproject.com/svn/django/trunk/django c:\Python24\lib\site-package Questions/Feedback If you notice errors with this documentation, please open a ticket and let us know! Installing a distribution-specific package 12
Slide 13: Django | Documentation Please only use the ticket tracker for criticisms and improvements on the docs. For tech support, ask in the IRC channel or post to the django-users list. Contents • Install Python • Install Apache and mod_python • Get your database running • Remove any old versions of Django • Install the Django code ♦ Installing a distribution-specific package ♦ Installing an official release ♦ Installing the development version Last update: July 12, 9:41 a.m. © 2005-2007 Lawrence Journal-World unless otherwise noted. Django is a registered trademark of Lawrence Journal-World. Questions/Feedback 13
Slide 14: Django | Documentation • Home • Download • Documentation • Weblog • Community • Code Django documentation Writing your first Django app, part 1 This document is for Django's SVN release, which can be significantly different than previous releases. Get old docs here: 0.96, 0.95. Let’s learn by example. Throughout this tutorial, we’ll walk you through the creation of a basic poll application. It’ll consist of two parts: • A public site that lets people view polls and vote in them. • An admin site that lets you add, change and delete polls. We’ll assume you have Django installed already. You can tell Django is installed by running the Python interactive interpreter and typing import django. If that command runs successfully, with no errors, Django is installed. Where to get help: If you’re having trouble going through this tutorial, please post a message to django-users or drop by #django on irc.freenode.net and we’ll try to help. Creating a project If this is your first time using Django, you’ll have to take care of some initial setup. Namely, you’ll need to auto-generate some code that establishes a Django project — a collection of settings for an instance of Django, including database configuration, Django-specific options and application-specific settings. From the command line, cd into a directory where you’d like to store your code, then run the command django-admin.py startproject mysite. This will create a mysite directory in your current directory. Note Writing your first Django app, part 1 14
Slide 15: Django | Documentation You’ll need to avoid naming projects after built-in Python or Django components. In particular, this means you should avoid using names like django (which will conflict with Django itself) or site (which conflicts with a built-in Python package). (django-admin.py should be on your system path if you installed Django via python setup.py. If it’s not on your path, you can find it in site-packages/django/bin, where site-packages is a directory within your Python installation. Consider symlinking to django-admin.py from some place on your path, such as /usr/local/bin.) Where should this code live? If your background is in PHP, you’re probably used to putting code under the Web server’s document root (in a place such as /var/www). With Django, you don’t do that. It’s not a good idea to put any of this Python code within your Web server’s document root, because it risks the possibility that people may be able to view your code over the Web. That’s not good for security. Put your code in some directory outside of the document root, such as /home/mycode. Let’s look at what startproject created: mysite/ __init__.py manage.py settings.py urls.py These files are: • __init__.py: An empty file that tells Python that this directory should be considered a Python package. (Read more about packages in the official Python docs if you’re a Python beginner.) • manage.py: A command-line utility that lets you interact with this Django project in various ways. • settings.py: Settings/configuration for this Django project. • urls.py: The URL declarations for this Django project; a “table of contents” of your Django-powered site. The development server Let’s verify this worked. Change into the mysite directory, if you haven’t already, and run the command python manage.py runserver. You’ll see the following output on the command line: Validating models... 0 errors found. Django version 0.95, using settings 'mysite.settings' Development server is running at http://127.0.0.1:8000/ Quit the server with CONTROL-C (Unix) or CTRL-BREAK (Windows). You’ve started the Django development server, a lightweight Web server written purely in Python. We’ve included this with Django so you can develop things rapidly, without having to deal with configuring a production server — such as Apache — until you’re ready for production. Creating a project 15
Slide 16: Django | Documentation Now’s a good time to note: DON’T use this server in anything resembling a production environment. It’s intended only for use while developing. (We’re in the business of making Web frameworks, not Web servers.) Now that the server’s running, visit http://127.0.0.1:8000/ with your Web browser. You’ll see a “Welcome to Django” page, in pleasant, light-blue pastel. It worked! Changing the port By default, the runserver command starts the development server on port 8000. If you want to change the server’s port, pass it as a command-line argument. For instance, this command starts the server on port 8080: python manage.py runserver 8080 Full docs for the development server are at django-admin documentation. Database setup Now, edit settings.py. It’s a normal Python module with module-level variables representing Django settings. Change these settings to match your database’s connection parameters: • DATABASE_ENGINE — Either ‘postgresql_psycopg2’, ‘mysql’ or ‘sqlite3’. Other backends are also available. • DATABASE_NAME — The name of your database, or the full (absolute) path to the database file if you’re using SQLite. • DATABASE_USER — Your database username (not used for SQLite). • DATABASE_PASSWORD — Your database password (not used for SQLite). • DATABASE_HOST — The host your database is on. Leave this as an empty string if your database server is on the same physical machine (not used for SQLite). Note If you’re using PostgreSQL or MySQL, make sure you’ve created a database by this point. Do that with “CREATE DATABASE database_name;” within your database’s interactive prompt. While you’re editing settings.py, take note of the INSTALLED_APPS setting towards the bottom of the file. That variable holds the names of all Django applications that are activated in this Django instance. Apps can be used in multiple projects, and you can package and distribute them for use by others in their projects. By default, INSTALLED_APPS contains the following apps, all of which come with Django: • django.contrib.auth — An authentication system. • django.contrib.contenttypes — A framework for content types. • django.contrib.sessions — A session framework. • django.contrib.sites — A framework for managing multiple sites with one Django installation. These applications are included by default as a convenience for the common case. Each of these applications makes use of at least one database table, though, so we need to create the tables in the database before we can use them. To do that, run the following command: The development server 16
Slide 17: Django | Documentation python manage.py syncdb The syncdb command looks at the INSTALLED_APPS setting and creates any necessary database tables according to the database settings in your settings.py file. You’ll see a message for each database table it creates, and you’ll get a prompt asking you if you’d like to create a superuser account for the authentication system. Go ahead and do that. If you’re interested, run the command-line client for your database and type \dt (PostgreSQL), SHOW TABLES; (MySQL), or .schema (SQLite) to display the tables Django created. For the minimalists Like we said above, the default applications are included for the common case, but not everybody needs them. If you don’t need any or all of them, feel free to comment-out or delete the appropriate line(s) from INSTALLED_APPS before running syncdb. The syncdb command will only create tables for apps in INSTALLED_APPS. Creating models Now that your environment — a “project” — is set up, you’re set to start doing work. Each application you write in Django consists of a Python package, somewhere on your Python path, that follows a certain convention. Django comes with a utility that automatically generates the basic directory structure of an app, so you can focus on writing code rather than creating directories. Projects vs. apps What’s the difference between a project and an app? An app is a Web application that does something — e.g., a weblog system, a database of public records or a simple poll app. A project is a collection of configuration and apps for a particular Web site. A project can contain multiple apps. An app can be in multiple projects. In this tutorial, we’ll create our poll app in the mysite directory, for simplicity. As a consequence, the app will be coupled to the project — that is, Python code within the poll app will refer to mysite.polls. Later in this tutorial, we’ll discuss decoupling your apps for distribution. To create your app, make sure you’re in the mysite directory and type this command: python manage.py startapp polls That’ll create a directory polls, which is laid out like this: polls/ __init__.py models.py views.py This directory structure will house the poll application. The first step in writing a database Web app in Django is to define your models — essentially, your database layout, with additional metadata. Database setup 17
Slide 18: Django | Documentation Philosophy A model is the single, definitive source of data about your data. It contains the essential fields and behaviors of the data you’re storing. Django follows the DRY Principle. The goal is to define your data model in one place and automatically derive things from it. In our simple poll app, we’ll create two models: polls and choices. A poll has a question and a publication date. A choice has two fields: the text of the choice and a vote tally. Each choice is associated with a poll. These concepts are represented by simple Python classes. Edit the polls/models.py file so it looks like this: from django.db import models class Poll(models.Model): question = models.CharField(max_length=200) pub_date = models.DateTimeField('date published') class Choice(models.Model): poll = models.ForeignKey(Poll) choice = models.CharField(max_length=200) votes = models.IntegerField() The code is straightforward. Each model is represented by a class that subclasses django.db.models.Model. Each model has a number of class variables, each of which represents a database field in the model. Each field is represented by an instance of a models.*Field class — e.g., models.CharField for character fields and models.DateTimeField for datetimes. This tells Django what type of data each field holds. The name of each models.*Field instance (e.g. question or pub_date ) is the field’s name, in machine-friendly format. You’ll use this value in your Python code, and your database will use it as the column name. You can use an optional first positional argument to a Field to designate a human-readable name. That’s used in a couple of introspective parts of Django, and it doubles as documentation. If this field isn’t provided, Django will use the machine-readable name. In this example, we’ve only defined a human-readable name for Poll.pub_date. For all other fields in this model, the field’s machine-readable name will suffice as its human-readable name. Some Field classes have required elements. CharField, for example, requires that you give it a max_length. That’s used not only in the database schema, but in validation, as we’ll soon see. Finally, note a relationship is defined, using models.ForeignKey. That tells Django each Choice is related to a single Poll. Django supports all the common database relationships: many-to-ones, many-to-manys and one-to-ones. Activating models That small bit of model code gives Django a lot of information. With it, Django is able to: Creating models 18
Slide 19: Django | Documentation • Create a database schema (CREATE TABLE statements) for this app. • Create a Python database-access API for accessing Poll and Choice objects. But first we need to tell our project that the polls app is installed. Philosophy Django apps are “pluggable”: You can use an app in multiple projects, and you can distribute apps, because they don’t have to be tied to a given Django installation. Edit the settings.py file again, and change the INSTALLED_APPS setting to include the string 'mysite.polls'. So it’ll look like this: INSTALLED_APPS = ( 'django.contrib.auth', 'django.contrib.contenttypes', 'django.contrib.sessions', 'django.contrib.sites', 'mysite.polls' ) Now Django knows mysite includes the polls app. Let’s run another command: python manage.py sql polls You should see something similar to the following (the CREATE TABLE SQL statements for the polls app): BEGIN; CREATE TABLE "polls_poll" ( "id" serial NOT NULL PRIMARY KEY, "question" varchar(200) NOT NULL, "pub_date" timestamp with time zone NOT NULL ); CREATE TABLE "polls_choice" ( "id" serial NOT NULL PRIMARY KEY, "poll_id" integer NOT NULL REFERENCES "polls_poll" ("id"), "choice" varchar(200) NOT NULL, "votes" integer NOT NULL ); COMMIT; Note the following: • The exact output will vary depending on the database you are using. • Table names are automatically generated by combining the name of the app (polls) and the lowercase name of the model — poll and choice. (You can override this behavior.) • Primary keys (IDs) are added automatically. (You can override this, too.) • By convention, Django appends "_id" to the foreign key field name. Yes, you can override this, as well. • The foreign key relationship is made explicit by a REFERENCES statement. • It’s tailored to the database you’re using, so database-specific field types such as auto_increment (MySQL), serial (PostgreSQL), or integer primary key (SQLite) are handled for you automatically. Same goes for quoting of field names — e.g., using double quotes or single quotes. The author of this tutorial runs PostgreSQL, so the example output is in PostgreSQL syntax. Activating models 19
Slide 20: Django | Documentation • The sql command doesn’t actually run the SQL in your database - it just prints it to the screen so that you can see what SQL Django thinks is required. If you wanted to, you could copy and paste this SQL into your database prompt. However, as we will see shortly, Django provides an easier way of committing the SQL to the database. If you’re interested, also run the following commands: ◊ python manage.py validate polls — Checks for any errors in the construction of your models. ◊ python manage.py sqlcustom polls — Outputs any custom SQL statements (such as table modifications or constraints) that are defined for the application. ◊ python manage.py sqlclear polls — Outputs the necessary DROP TABLE statements for this app, according to which tables already exist in your database (if any). ◊ python manage.py sqlindexes polls — Outputs the CREATE INDEX statements for this app. ◊ python manage.py sqlall polls — A combination of all the SQL from the ‘sql’, ‘sqlcustom’, and ‘sqlindexes’ commands. Looking at the output of those commands can help you understand what’s actually happening under the hood. Now, run syncdb again to create those model tables in your database: python manage.py syncdb The syncdb command runs the sql from ‘sqlall’ on your database for all apps in INSTALLED_APPS that don’t already exist in your database. This creates all the tables, initial data and indexes for any apps you have added to your project since the last time you ran syncdb. syncdb can be called as often as you like, and it will only ever create the tables that don’t exist. Read the django-admin.py documentation for full information on what the manage.py utility can do. Playing with the API Now, let’s hop into the interactive Python shell and play around with the free API Django gives you. To invoke the Python shell, use this command: python manage.py shell We’re using this instead of simply typing “python”, because manage.py sets up the project’s environment for you. “Setting up the environment” involves two things: • Putting mysite on sys.path. For flexibility, several pieces of Django refer to projects in Python dotted-path notation (e.g. 'mysite.polls.models'). In order for this to work, the mysite package has to be on sys.path. We’ve already seen one example of this: the INSTALLED_APPS setting is a list of packages in dotted-path notation. • Setting the DJANGO_SETTINGS_MODULE environment variable, which gives Django the path to your settings.py file. Bypassing manage.py Playing with the API 20
Slide 21: Django | Documentation If you’d rather not use manage.py, no problem. Just make sure mysite is at the root level on the Python path (i.e., import mysite works) and set the DJANGO_SETTINGS_MODULE environment variable to mysite.settings. For more information on all of this, see the django-admin.py documentation. Once you’re in the shell, explore the database API: # Import the model classes we just wrote. >>> from mysite.polls.models import Poll, Choice # No polls are in the system yet. >>> Poll.objects.all() [] # Create a new Poll. >>> from datetime import datetime >>> p = Poll(question="What's up?", pub_date=datetime.now()) # Save the object into the database. You have to call save() explicitly. >>> p.save() # Now it has an ID. Note that this might say "1L" instead of "1", depending # on which database you're using. That's no biggie; it just means your # database backend prefers to return integers as Python long integer # objects. >>> p.id 1 # Access database columns via Python attributes. >>> p.question "What's up?" >>> p.pub_date datetime.datetime(2005, 7, 15, 12, 00, 53) # Change values by changing the attributes, then calling save(). >>> p.pub_date = datetime(2005, 4, 1, 0, 0) >>> p.save() # objects.all() displays all the polls in the database. >>> Poll.objects.all() [<Poll: Poll object>] Wait a minute. <Poll: Poll object> is, utterly, an unhelpful representation of this object. Let’s fix that by editing the polls model (in the polls/models.py file) and adding a __unicode__() method to both Poll and Choice: class Poll(models.Model): # ... def __unicode__(self): return self.question class Choice(models.Model): # ... def __unicode__(self): return self.choice Playing with the API 21
Slide 22: Django | Documentation It’s important to add __unicode__() methods to your models, not only for your own sanity when dealing with the interactive prompt, but also because objects’ representations are used throughout Django’s automatically-generated admin. Why __unicode__() and not __str__()? If you’re familiar with Python, you might be in the habit of adding __str__() methods to your classes, not __unicode__() methods. We use __unicode__() here because Django models deal with Unicode by default. All data stored in your database is converted to Unicode when it’s returned. Django models have a default __str__() method that calls __unicode__() and converts the result to a UTF-8 bytestring. This means that unicode(p) will return a Unicode string, and str(p) will return a normal string, with characters encoded as UTF-8. If all of this is jibberish to you, just remember to add __unicode__() methods to your models. With any luck, things should Just Work for you. Note these are normal Python methods. Let’s add a custom method, just for demonstration: import datetime # ... class Poll(models.Model): # ... def was_published_today(self): return self.pub_date.date() == datetime.date.today() Note the addition of import datetime to reference Python’s standard datetime module. Let’s jump back into the Python interactive shell by running python manage.py shell again: >>> from mysite.polls.models import Poll, Choice # Make sure our __unicode__() addition worked. >>> Poll.objects.all() [<Poll: What's up?>] # Django provides a rich database lookup API that's entirely driven by # keyword arguments. >>> Poll.objects.filter(id=1) [<Poll: What's up?>] >>> Poll.objects.filter(question__startswith='What') [<Poll: What's up?>] # Get the poll whose year is 2005. Of course, if you're going through this # tutorial in another year, change as appropriate. >>> Poll.objects.get(pub_date__year=2005) <Poll: What's up?> >>> Poll.objects.get(id=2) Traceback (most recent call last): ... DoesNotExist: Poll matching query does not exist. # Lookup by a primary key is the most common case, so Django provides a # shortcut for primary-key exact lookups. # The following is identical to Poll.objects.get(id=1). Playing with the API 22
Slide 23: Django | Documentation >>> Poll.objects.get(pk=1) <Poll: What's up?> # Make sure our custom method worked. >>> p = Poll.objects.get(pk=1) >>> p.was_published_today() False # Give the Poll a couple of Choices. The create call constructs a new # choice object, does the INSERT statement, adds the choice to the set # of available choices and returns the new Choice object. >>> p = Poll.objects.get(pk=1) >>> p.choice_set.create(choice='Not much', votes=0) <Choice: Not much> >>> p.choice_set.create(choice='The sky', votes=0) <Choice: The sky> >>> c = p.choice_set.create(choice='Just hacking again', votes=0) # Choice objects have API access to their related Poll objects. >>> c.poll <Poll: What's up?> # And vice versa: Poll objects get access to Choice objects. >>> p.choice_set.all() [<Choice: Not much>, <Choice: The sky>, <Choice: Just hacking again>] >>> p.choice_set.count() 3 # The API automatically follows relationships as far as you need. # Use double underscores to separate relationships. # This works as many levels deep as you want. There's no limit. # Find all Choices for any poll whose pub_date is in 2005. >>> Choice.objects.filter(poll__pub_date__year=2005) [<Choice: Not much>, <Choice: The sky>, <Choice: Just hacking again>] # Let's delete one of the choices. Use delete() for that. >>> c = p.choice_set.filter(choice__startswith='Just hacking') >>> c.delete() For full details on the database API, see our Database API reference. When you’re comfortable with the API, read part 2 of this tutorial to get Django’s automatic admin working. Questions/Feedback If you notice errors with this documentation, please open a ticket and let us know! Please only use the ticket tracker for criticisms and improvements on the docs. For tech support, ask in the IRC channel or post to the django-users list. Contents • Creating a project ♦ The development server ♦ Database setup Questions/Feedback 23
Slide 24: Django | Documentation • Creating models • Activating models • Playing with the API Last update: August 5, 12:14 a.m. © 2005-2007 Lawrence Journal-World unless otherwise noted. Django is a registered trademark of Lawrence Journal-World. Contents 24
Slide 25: Django | Documentation • Home • Download • Documentation • Weblog • Community • Code Django documentation Writing your first Django app, part 2 This document is for Django's SVN release, which can be significantly different than previous releases. Get old docs here: 0.96, 0.95. This tutorial begins where Tutorial 1 left off. We’re continuing the Web-poll application and will focus on Django’s automatically-generated admin site. Philosophy Generating admin sites for your staff or clients to add, change and delete content is tedious work that doesn’t require much creativity. For that reason, Django entirely automates creation of admin interfaces for models. Django was written in a newsroom environment, with a very clear separation between “content publishers” and the “public” site. Site managers use the system to add news stories, events, sports scores, etc., and that content is displayed on the public site. Django solves the problem of creating a unified interface for site administrators to edit content. The admin isn’t necessarily intended to be used by site visitors; it’s for site managers. Activate the admin site The Django admin site is not activated by default — it’s an opt-in thing. To activate the admin site for your installation, do these three things: • Add "django.contrib.admin" to your INSTALLED_APPS setting. • Run python manage.py syncdb. Since you have added a new application to INSTALLED_APPS, the database tables need to be updated. • Edit your mysite/urls.py file and uncomment the line below “Uncomment this for admin:”. This file is a URLconf; we’ll dig into URLconfs in the next tutorial. For now, all you need to know is that it maps URL roots to applications. Writing your first Django app, part 2 25
Slide 26: Django | Documentation Start the development server Let’s start the development server and explore the admin site. Recall from Tutorial 1 that you start the development server like so: python manage.py runserver Now, open a Web browser and go to “/admin/” on your local domain — e.g., http://127.0.0.1:8000/admin/. You should see the admin’s login screen: Enter the admin site Now, try logging in. (You created a superuser account in the first part of this tutorial, remember?) You should see the Django admin index page: You should see a few other types of editable content, including groups, users and sites. These are core features Django ships with by default. Make the poll app modifiable in the admin But where’s our poll app? It’s not displayed on the admin index page. Just one thing to do: We need to specify in the Poll model that Poll objects have an admin interface. Edit the mysite/polls/models.py file and make the following change to add an inner Admin class: class Poll(models.Model): # ... Start the development server 26
Slide 27: Django | Documentation class Admin: pass The class Admin will contain all the settings that control how this model appears in the Django admin. All the settings are optional, however, so creating an empty class means “give this object an admin interface using all the default options.” Now reload the Django admin page to see your changes. Note that you don’t have to restart the development server — the server will auto-reload your project, so any modifications code will be seen immediately in your browser. Explore the free admin functionality Now that Poll has the inner Admin class, Django knows that it should be displayed on the admin index page: Click “Polls.” Now you’re at the “change list” page for polls. This page displays all the polls in the database and lets you choose one to change it. There’s the “What’s up?” poll we created in the first tutorial: Click the “What’s up?” poll to edit it: Things to note here: • The form is automatically generated from the Poll model. Make the poll app modifiable in the admin 27
Slide 28: Django | Documentation • The different model field types (models.DateTimeField, models.CharField) correspond to the appropriate HTML input widget. Each type of field knows how to display itself in the Django admin. • Each DateTimeField gets free JavaScript shortcuts. Dates get a “Today” shortcut and calendar popup, and times get a “Now” shortcut and a convenient popup that lists commonly entered times. The bottom part of the page gives you a couple of options: • Save — Saves changes and returns to the change-list page for this type of object. • Save and continue editing — Saves changes and reloads the admin page for this object. • Save and add another — Saves changes and loads a new, blank form for this type of object. • Delete — Displays a delete confirmation page. Change the “Date published” by clicking the “Today” and “Now” shortcuts. Then click “Save and continue editing.” Then click “History” in the upper right. You’ll see a page listing all changes made to this object via the Django admin, with the timestamp and username of the person who made the change: Customize the admin form Take a few minutes to marvel at all the code you didn’t have to write. Let’s customize this a bit. We can reorder the fields by explicitly adding a fields parameter to Admin: class Admin: fields = ( (None, {'fields': ('pub_date', 'question')}), ) That made the “Publication date” show up first instead of second: Explore the free admin functionality 28
Slide 29: Django | Documentation This isn’t impressive with only two fields, but for admin forms with dozens of fields, choosing an intuitive order is an important usability detail. And speaking of forms with dozens of fields, you might want to split the form up into fieldsets: class Admin: fields = ( (None, {'fields': ('question',)}), ('Date information', {'fields': ('pub_date',)}), ) The first element of each tuple in fields is the title of the fieldset. Here’s what our form looks like now: You can assign arbitrary HTML classes to each fieldset. Django provides a "collapse" class that displays a particular fieldset initially collapsed. This is useful when you have a long form that contains a number of fields that aren’t commonly used: class Admin: fields = ( (None, {'fields': ('question',)}), ('Date information', {'fields': ('pub_date',), 'classes': 'collapse'}), ) Adding related objects OK, we have our Poll admin page. But a Poll has multiple Choices, and the admin page doesn’t display choices. Yet. Customize the admin form 29
Slide 30: Django | Documentation There are two ways to solve this problem. The first is to give the Choice model its own inner Admin class, just as we did with Poll. Here’s what that would look like: class Choice(models.Model): # ... class Admin: pass Now “Choices” is an available option in the Django admin. The “Add choice” form looks like this: In that form, the “Poll” field is a select box containing every poll in the database. Django knows that a ForeignKey should be represented in the admin as a <select> box. In our case, only one poll exists at this point. Also note the “Add Another” link next to “Poll.” Every object with a ForeignKey relationship to another gets this for free. When you click “Add Another,” you’ll get a popup window with the “Add poll” form. If you add a poll in that window and click “Save,” Django will save the poll to the database and dynamically add it as the selected choice on the “Add choice” form you’re looking at. But, really, this is an inefficient way of adding Choice objects to the system. It’d be better if you could add a bunch of Choices directly when you create the Poll object. Let’s make that happen. Remove the Admin for the Choice model. Then, edit the ForeignKey(Poll) field like so: poll = models.ForeignKey(Poll, edit_inline=models.STACKED, num_in_admin=3) This tells Django: “Choice objects are edited on the Poll admin page. By default, provide enough fields for 3 Choices.” Then change the other fields in Choice to give them core=True: choice = models.CharField(max_length=200, core=True) votes = models.IntegerField(core=True) This tells Django: “When you edit a Choice on the Poll admin page, the ‘choice’ and ‘votes’ fields are required. The presence of at least one of them signifies the addition of a new Choice object, and clearing both of them signifies the deletion of that existing Choice object.” Load the “Add poll” page to see how that looks: Adding related objects 30
Slide 31: Django | Documentation It works like this: There are three slots for related Choices — as specified by num_in_admin — but each time you come back to the “Change” page for an already-created object, you get one extra slot. (This means there’s no hard-coded limit on how many related objects can be added.) If you wanted space for three extra Choices each time you changed the poll, you’d use num_extra_on_change=3. One small problem, though. It takes a lot of screen space to display all the fields for entering related Choice objects. For that reason, Django offers an alternate way of displaying inline related objects: poll = models.ForeignKey(Poll, edit_inline=models.TABULAR, num_in_admin=3) With that edit_inline=models.TABULAR (instead of models.STACKED), the related objects are displayed in a more compact, table-based format: Customize the admin change list Now that the Poll admin page is looking good, let’s make some tweaks to the “change list” page — the one that displays all the polls in the system. Customize the admin change list 31
Slide 32: Django | Documentation Here’s what it looks like at this point: By default, Django displays the str() of each object. But sometimes it’d be more helpful if we could display individual fields. To do that, use the list_display option, which is a tuple of field names to display, as columns, on the change list page for the object: class Poll(models.Model): # ... class Admin: # ... list_display = ('question', 'pub_date') Just for good measure, let’s also include the was_published_today custom method from Tutorial 1: list_display = ('question', 'pub_date', 'was_published_today') Now the poll change list page looks like this: You can click on the column headers to sort by those values — except in the case of the was_published_today header, because sorting by the output of an arbitrary method is not supported. Also note that the column header for was_published_today is, by default, the name of the method (with underscores replaced with spaces). But you can change that by giving that method a short_description attribute: def was_published_today(self): return self.pub_date.date() == datetime.date.today() was_published_today.short_description = 'Published today?' Let’s add another improvement to the Poll change list page: Filters. Add the following line to Poll.Admin: list_filter = ['pub_date'] That adds a “Filter” sidebar that lets people filter the change list by the pub_date field: Customize the admin change list 32
Slide 33: Django | Documentation The type of filter displayed depends on the type of field you’re filtering on. Because pub_date is a DateTimeField, Django knows to give the default filter options for DateTimeFields: “Any date,” “Today,” “Past 7 days,” “This month,” “This year.” This is shaping up well. Let’s add some search capability: search_fields = ['question'] That adds a search box at the top of the change list. When somebody enters search terms, Django will search the question field. You can use as many fields as you’d like — although because it uses a LIKE query behind the scenes, keep it reasonable, to keep your database happy. Finally, because Poll objects have dates, it’d be convenient to be able to drill down by date. Add this line: date_hierarchy = 'pub_date' That adds hierarchical navigation, by date, to the top of the change list page. At top level, it displays all available years. Then it drills down to months and, ultimately, days. Now’s also a good time to note that change lists give you free pagination. The default is to display 50 items per page. Change-list pagination, search boxes, filters, date-hierarchies and column-header-ordering all work together like you think they should. Customize the admin look and feel Clearly, having “Django administration” and “example.com” at the top of each admin page is ridiculous. It’s just placeholder text. That’s easy to change, though, using Django’s template system. The Django admin is powered by Django itself, and its interfaces use Django’s own template system. (How meta!) Open your settings file (mysite/settings.py, remember) and look at the TEMPLATE_DIRS setting. TEMPLATE_DIRS is a tuple of filesystem directories to check when loading Django templates. It’s a search path. By default, TEMPLATE_DIRS is empty. So, let’s add a line to it, to tell Django where our templates live: TEMPLATE_DIRS = ( "/home/my_username/mytemplates", # Change this to your own directory. ) Customize the admin look and feel 33
Slide 34: Django | Documentation Now copy the template admin/base_site.html from within the default Django admin template directory (django/contrib/admin/templates) into an admin subdirectory of whichever directory you’re using in TEMPLATE_DIRS. For example, if your TEMPLATE_DIRS includes "/home/my_username/mytemplates", as above, then copy django/contrib/admin/templates/admin/base_site.html to /home/my_username/mytemplates/admin/base_site.html. Don’t forget that admin subdirectory. Then, just edit the file and replace the generic Django text with your own site’s name and URL as you see fit. Note that any of Django’s default admin templates can be overridden. To override a template, just do the same thing you did with base_site.html — copy it from the default directory into your custom directory, and make changes. Astute readers will ask: But if TEMPLATE_DIRS was empty by default, how was Django finding the default admin templates? The answer is that, by default, Django automatically looks for a templates/ subdirectory within each app package, for use as a fallback. See the loader types documentation for full information. Customize the admin index page On a similar note, you might want to customize the look and feel of the Django admin index page. By default, it displays all available apps, according to your INSTALLED_APPS setting. But the order in which it displays things is random, and you may want to make significant changes to the layout. After all, the index is probably the most important page of the admin, and it should be easy to use. The template to customize is admin/index.html. (Do the same as with admin/base_site.html in the previous section — copy it from the default directory to your custom template directory.) Edit the file, and you’ll see it uses a template tag called {% get_admin_app_list as app_list %}. That’s the magic that retrieves every installed Django app. Instead of using that, you can hard-code links to object-specific admin pages in whatever way you think is best. Django offers another shortcut in this department. Run the command python manage.py adminindex polls to get a chunk of template code for inclusion in the admin index template. It’s a useful starting point. For full details on customizing the look and feel of the Django admin site in general, see the Django admin CSS guide. When you’re comfortable with the admin site, read part 3 of this tutorial to start working on public poll views. Questions/Feedback If you notice errors with this documentation, please open a ticket and let us know! Please only use the ticket tracker for criticisms and improvements on the docs. For tech support, ask in the IRC channel or post to the django-users list. Customize the admin index page 34
Slide 35: Django | Documentation Contents • Activate the admin site • Start the development server • Enter the admin site • Make the poll app modifiable in the admin • Explore the free admin functionality • Customize the admin form • Adding related objects • Customize the admin change list • Customize the admin look and feel • Customize the admin index page Last update: August 5, 12:14 a.m. © 2005-2007 Lawrence Journal-World unless otherwise noted. Django is a registered trademark of Lawrence Journal-World. Contents 35
Slide 36: Django | Documentation • Home • Download • Documentation • Weblog • Community • Code Django documentation Writing your first Django app, part 3 This document is for Django's SVN release, which can be significantly different than previous releases. Get old docs here: 0.96, 0.95. This tutorial begins where Tutorial 2 left off. We’re continuing the Web-poll application and will focus on creating the public interface — “views.” Philosophy A view is a “type” of Web page in your Django application that generally serves a specific function and has a specific template. For example, in a weblog application, you might have the following views: • Blog homepage — displays the latest few entries. • Entry “detail” page — permalink page for a single entry. • Year-based archive page — displays all months with entries in the given year. • Month-based archive page — displays all days with entries in the given month. • Day-based archive page — displays all entries in the given day. • Comment action — handles posting comments to a given entry. In our poll application, we’ll have the following four views: • Poll “archive” page — displays the latest few polls. • Poll “detail” page — displays a poll question, with no results but with a form to vote. • Poll “results” page — displays results for a particular poll. • Vote action — handles voting for a particular choice in a particular poll. In Django, each view is represented by a simple Python function. Design your URLs The first step of writing views is to design your URL structure. You do this by creating a Python module, called a URLconf. URLconfs are how Django associates a given URL with given Python code. Writing your first Django app, part 3 36
Slide 37: Django | Documentation When a user requests a Django-powered page, the system looks at the ROOT_URLCONF setting, which contains a string in Python dotted syntax. Django loads that module and looks for a module-level variable called urlpatterns, which is a sequence of tuples in the following format: (regular expression, Python callback function [, optional dictionary]) Django starts at the first regular expression and makes its way down the list, comparing the requested URL against each regular expression until it finds one that matches. When it finds a match, Django calls the Python callback function, with an HTTPRequest object as the first argument, any “captured” values from the regular expression as keyword arguments, and, optionally, arbitrary keyword arguments from the dictionary (an optional third item in the tuple). For more on HTTPRequest objects, see the request and response documentation. For more details on URLconfs, see the URLconf documentation. When you ran python django-admin.py startproject mysite at the beginning of Tutorial 1, it created a default URLconf in mysite/urls.py. It also automatically set your ROOT_URLCONF setting (in settings.py) to point at that file: ROOT_URLCONF = 'mysite.urls' Time for an example. Edit mysite/urls.py so it looks like this: from django.conf.urls.defaults import * urlpatterns = patterns('', (r'^polls/$', 'mysite.polls.views.index'), (r'^polls/(?P<poll_id>\d+)/$', 'mysite.polls.views.detail'), (r'^polls/(?P<poll_id>\d+)/results/$', 'mysite.polls.views.results'), (r'^polls/(?P<poll_id>\d+)/vote/$', 'mysite.polls.views.vote'), ) This is worth a review. When somebody requests a page from your Web site — say, “/polls/23/”, Django will load this Python module, because it’s pointed to by the ROOT_URLCONF setting. It finds the variable named urlpatterns and traverses the regular expressions in order. When it finds a regular expression that matches — r'^polls/(?P<poll_id>\d+)/$' — it loads the associated Python package/module: mysite.polls.views.detail. That corresponds to the function detail() in mysite/polls/views.py. Finally, it calls that detail() function like so: detail(request=<HttpRequest object>, poll_id='23') The poll_id='23' part comes from (?P<poll_id>\d+). Using parenthesis around a pattern “captures” the text matched by that pattern and sends it as an argument to the view function; the ?P<poll_id> defines the name that will be used to identify the matched pattern; and \d+ is a regular expression to match a sequence of digits (i.e., a number). Because the URL patterns are regular expressions, there really is no limit on what you can do with them. And there’s no need to add URL cruft such as .php — unless you have a sick sense of humor, in which case you can do something like this: (r'^polls/latest\.php$', 'mysite.polls.views.index'), Design your URLs 37
Slide 38: Django | Documentation But, don’t do that. It’s silly. Note that these regular expressions do not search GET and POST parameters, or the domain name. For example, in a request to http://www.example.com/myapp/, the URLconf will look for /myapp/. In a request to http://www.example.com/myapp/?page=3, the URLconf will look for /myapp/. If you need help with regular expressions, see Wikipedia’s entry and the Python documentation. Also, the O’Reilly book “Mastering Regular Expressions” by Jeffrey Friedl is fantastic. Finally, a performance note: these regular expressions are compiled the first time the URLconf module is loaded. They’re super fast. Write your first view Well, we haven’t created any views yet — we just have the URLconf. But let’s make sure Django is following the URLconf properly. Fire up the Django development Web server: python manage.py runserver Now go to “http://localhost:8000/polls/” on your domain in your Web browser. You should get a pleasantly-colored error page with the following message: ViewDoesNotExist at /polls/ Tried index in module mysite.polls.views. Error was: 'module' object has no attribute 'index' This error happened because you haven’t written a function index() in the module mysite/polls/views.py. Try “/polls/23/”, “/polls/23/results/” and “/polls/23/vote/”. The error messages tell you which view Django tried (and failed to find, because you haven’t written any views yet). Time to write the first view. Open the file mysite/polls/views.py and put the following Python code in it: from django.http import HttpResponse def index(request): return HttpResponse("Hello, world. You're at the poll index.") This is the simplest view possible. Go to “/polls/” in your browser, and you should see your text. Now add the following view. It’s slightly different, because it takes an argument (which, remember, is passed in from whatever was captured by the regular expression in the URLconf): def detail(request, poll_id): return HttpResponse("You're looking at poll %s." % poll_id) Take a look in your browser, at “/polls/34/”. It’ll display whatever ID you provide in the URL. Write your first view 38
Slide 39: Django | Documentation Write views that actually do something Each view is responsible for doing one of two things: Returning an HttpResponse object containing the content for the requested page, or raising an exception such as Http404. The rest is up to you. Your view can read records from a database, or not. It can use a template system such as Django’s — or a third-party Python template system — or not. It can generate a PDF file, output XML, create a ZIP file on the fly, anything you want, using whatever Python libraries you want. All Django wants is that HttpResponse. Or an exception. Because it’s convenient, let’s use Django’s own database API, which we covered in Tutorial 1. Here’s one stab at the index() view, which displays the latest 5 poll questions in the system, separated by commas, according to publication date: from mysite.polls.models import Poll from django.http import HttpResponse def index(request): latest_poll_list = Poll.objects.all().order_by('-pub_date')[:5] output = ', '.join([p.question for p in latest_poll_list]) return HttpResponse(output) There’s a problem here, though: The page’s design is hard-coded in the view. If you want to change the way the page looks, you’ll have to edit this Python code. So let’s use Django’s template system to separate the design from Python: from django.template import Context, loader from mysite.polls.models import Poll from django.http import HttpResponse def index(request): latest_poll_list = Poll.objects.all().order_by('-pub_date')[:5] t = loader.get_template('polls/index.html') c = Context({ 'latest_poll_list': latest_poll_list, }) return HttpResponse(t.render(c)) That code loads the template called “polls/index.html” and passes it a context. The context is a dictionary mapping template variable names to Python objects. Reload the page. Now you’ll see an error: TemplateDoesNotExist at /polls/ polls/index.html Ah. There’s no template yet. First, create a directory, somewhere on your filesystem, whose contents Django can access. (Django runs as whatever user your server runs.) Don’t put them under your document root, though. You probably shouldn’t make them public, just for security’s sake. Then edit TEMPLATE_DIRS in your settings.py to tell Django where it can find templates — just as you did in the “Customize the admin look and feel” section of Tutorial 2. Write views that actually do something 39
Slide 40: Django | Documentation When you’ve done that, create a directory polls in your template directory. Within that, create a file called index.html. Note that our loader.get_template('polls/index.html') code from above maps to “[template_directory]/polls/index.html” on the filesystem. Put the following code in that template: {% if latest_poll_list %} <ul> {% for poll in latest_poll_list %} <li>{{ poll.question }}</li> {% endfor %} </ul> {% else %} <p>No polls are available.</p> {% endif %} Load the page in your Web browser, and you should see a bulleted-list containing the “What’s up” poll from Tutorial 1. A shortcut: render_to_response() It’s a very common idiom to load a template, fill a context and return an HttpResponse object with the result of the rendered template. Django provides a shortcut. Here’s the full index() view, rewritten: from django.shortcuts import render_to_response from mysite.polls.models import Poll def index(request): latest_poll_list = Poll.objects.all().order_by('-pub_date')[:5] return render_to_response('polls/index.html', {'latest_poll_list': latest_poll_list}) Note that once we’ve done this in all these views, we no longer need to import loader, Context and HttpResponse. The render_to_response() function takes a template name as its first argument and a dictionary as its optional second argument. It returns an HttpResponse object of the given template rendered with the given context. Raising 404 Now, let’s tackle the poll detail view — the page that displays the question for a given poll. Here’s the view: from django.http import Http404 # ... def detail(request, poll_id): try: p = Poll.objects.get(pk=poll_id) except Poll.DoesNotExist: raise Http404 return render_to_response('polls/detail.html', {'poll': p}) The new concept here: The view raises the django.http.Http404 exception if a poll with the requested ID doesn’t exist. A shortcut: render_to_response() 40
Slide 41: Django | Documentation A shortcut: get_object_or_404() It’s a very common idiom to use get() and raise Http404 if the object doesn’t exist. Django provides a shortcut. Here’s the detail() view, rewritten: from django.shortcuts import render_to_response, get_object_or_404 # ... def detail(request, poll_id): p = get_object_or_404(Poll, pk=poll_id) return render_to_response('polls/detail.html', {'poll': p}) The get_object_or_404() function takes a Django model module as its first argument and an arbitrary number of keyword arguments, which it passes to the module’s get() function. It raises Http404 if the object doesn’t exist. Philosophy Why do we use a helper function get_object_or_404() instead of automatically catching the DoesNotExist exceptions at a higher level, or having the model API raise Http404 instead of DoesNotExist? Because that would couple the model layer to the view layer. One of the foremost design goals of Django is to maintain loose coupling. There’s also a get_list_or_404() function, which works just as get_object_or_404() — except using filter() instead of get(). It raises Http404 if the list is empty. Write a 404 (page not found) view When you raise Http404 from within a view, Django will load a special view devoted to handling 404 errors. It finds it by looking for the variable handler404, which is a string in Python dotted syntax — the same format the normal URLconf callbacks use. A 404 view itself has nothing special: It’s just a normal view. You normally won’t have to bother with writing 404 views. By default, URLconfs have the following line up top: from django.conf.urls.defaults import * That takes care of setting handler404 in the current module. As you can see in django/conf/urls/defaults.py, handler404 is set to 'django.views.defaults.page_not_found' by default. Three more things to note about 404 views: • The 404 view is also called if Django doesn’t find a match after checking every regular expression in the URLconf. • If you don’t define your own 404 view — and simply use the default, which is recommended — you still have one obligation: To create a 404.html template in the root of your template directory. The default 404 view will use that template for all 404 errors. • If DEBUG is set to True (in your settings module) then your 404 view will never be used, and the traceback will be displayed instead. A shortcut: get_object_or_404() 41
Slide 42: Django | Documentation Write a 500 (server error) view Similarly, URLconfs may define a handler500, which points to a view to call in case of server errors. Server errors happen when you have runtime errors in view code. Use the template system Back to the detail() view for our poll application. Given the context variable poll, here’s what the “polls/detail.html” template might look like: <h1>{{ poll.question }}</h1> <ul> {% for choice in poll.choice_set.all %} <li>{{ choice.choice }}</li> {% endfor %} </ul> The template system uses dot-lookup syntax to access variable attributes. In the example of {{ poll.question }}, first Django does a dictionary lookup on the object poll. Failing that, it tries attribute lookup — which works, in this case. If attribute lookup had failed, it would’ve tried calling the method question() on the poll object. Method-calling happens in the {% for %} loop: poll.choice_set.all is interpreted as the Python code poll.choice_set.all(), which returns an iterable of Choice objects and is suitable for use in the {% for %} tag. See the template guide for full details on how templates work. Simplifying the URLconfs Take some time to play around with the views and template system. As you edit the URLconf, you may notice there’s a fair bit of redundancy in it: urlpatterns = patterns('', (r'^polls/$', 'mysite.polls.views.index'), (r'^polls/(?P<poll_id>\d+)/$', 'mysite.polls.views.detail'), (r'^polls/(?P<poll_id>\d+)/results/$', 'mysite.polls.views.results'), (r'^polls/(?P<poll_id>\d+)/vote/$', 'mysite.polls.views.vote'), ) Namely, mysite.polls.views is in every callback. Because this is a common case, the URLconf framework provides a shortcut for common prefixes. You can factor out the common prefixes and add them as the first argument to patterns(), like so: urlpatterns = patterns('mysite.polls.views', (r'^polls/$', 'index'), (r'^polls/(?P<poll_id>\d+)/$', 'detail'), (r'^polls/(?P<poll_id>\d+)/results/$', 'results'), (r'^polls/(?P<poll_id>\d+)/vote/$', 'vote'), ) Write a 500 (server error) view 42
Slide 43: Django | Documentation This is functionally identical to the previous formatting. It’s just a bit tidier. Decoupling the URLconfs While we’re at it, we should take the time to decouple our poll-app URLs from our Django project configuration. Django apps are meant to be pluggable — that is, each particular app should be transferrable to another Django installation with minimal fuss. Our poll app is pretty decoupled at this point, thanks to the strict directory structure that python manage.py startapp created, but one part of it is coupled to the Django settings: The URLconf. We’ve been editing the URLs in mysite/urls.py, but the URL design of an app is specific to the app, not to the Django installation — so let’s move the URLs within the app directory. Copy the file mysite/urls.py to mysite/polls/urls.py. Then, change mysite/urls.py to remove the poll-specific URLs and insert an include(): (r'^polls/', include('mysite.polls.urls')), include(), simply, references another URLconf. Note that the regular expression doesn’t have a $ (end-of-string match character) but has the trailing slash. Whenever Django encounters include(), it chops off whatever part of the URL matched up to that point and sends the remaining string to the included URLconf for further processing. Here’s what happens if a user goes to “/polls/34/” in this system: • Django will find the match at '^polls/' • It will strip off the matching text ("polls/") and send the remaining text — "34/" — to the ‘mysite.polls.urls’ urlconf for further processing. Now that we’ve decoupled that, we need to decouple the ‘mysite.polls.urls’ urlconf by removing the leading “polls/” from each line: urlpatterns = patterns('mysite.polls.views', (r'^$', 'index'), (r'^(?P<poll_id>\d+)/$', 'detail'), (r'^(?P<poll_id>\d+)/results/$', 'results'), (r'^(?P<poll_id>\d+)/vote/$', 'vote'), ) The idea behind include() and URLconf decoupling is to make it easy to plug-and-play URLs. Now that polls are in their own URLconf, they can be placed under “/polls/”, or under “/fun_polls/”, or under “/content/polls/”, or any other URL root, and the app will still work. All the poll app cares about is its relative URLs, not its absolute URLs. When you’re comfortable with writing views, read part 4 of this tutorial to learn about simple form processing and generic views. Simplifying the URLconfs 43
Slide 44: Django | Documentation Questions/Feedback If you notice errors with this documentation, please open a ticket and let us know! Please only use the ticket tracker for criticisms and improvements on the docs. For tech support, ask in the IRC channel or post to the django-users list. Contents • Philosophy • Design your URLs • Write your first view • Write views that actually do something ♦ A shortcut: render_to_response() • Raising 404 ♦ A shortcut: get_object_or_404() • Write a 404 (page not found) view • Write a 500 (server error) view • Use the template system • Simplifying the URLconfs • Decoupling the URLconfs Last update: August 4, 11:39 p.m. © 2005-2007 Lawrence Journal-World unless otherwise noted. Django is a registered trademark of Lawrence Journal-World. Questions/Feedback 44
Slide 45: Django | Documentation • Home • Download • Documentation • Weblog • Community • Code Django documentation Writing your first Django app, part 4 This document is for Django's SVN release, which can be significantly different than previous releases. Get old docs here: 0.96, 0.95. This tutorial begins where Tutorial 3 left off. We’re continuing the Web-poll application and will focus on simple form processing and cutting down our code. Write a simple form Let’s update our poll detail template (“polls/detail.html”) from the last tutorial, so that the template contains an HTML <form> element: <h1>{{ poll.question }}</h1> {% if error_message %}<p><strong>{{ error_message }}</strong></p>{% endif %} <form action="/polls/{{ poll.id }}/vote/" method="post"> {% for choice in poll.choice_set.all %} <input type="radio" name="choice" id="choice{{ forloop.counter }}" value="{{ choice.id }}" <label for="choice{{ forloop.counter }}">{{ choice.choice }}</label><br /> {% endfor %} <input type="submit" value="Vote" /> </form> A quick rundown: • The above template displays a radio button for each poll choice. The value of each radio button is the associated poll choice’s ID. The name of each radio button is "choice". That means, when somebody selects one of the radio buttons and submits the form, it’ll send the POST data choice=3. This is HTML Forms 101. • We set the form’s action to /polls/{{ poll.id }}/vote/, and we set method="post". Using method="post" (as opposed to method="get") is very important, because the act of submitting this form will alter data server-side. Whenever you create a form that alters data server-side, use method="post". This tip isn’t specific to Django; it’s just good Web development practice. Writing your first Django app, part 4 45
Slide 46: Django | Documentation Now, let’s create a Django view that handles the submitted data and does something with it. Remember, in Tutorial 3, we created a URLconf for the polls application that includes this line: (r'^(?P<poll_id>\d+)/vote/$', 'mysite.polls.views.vote'), So let’s create a vote() function in mysite/polls/views.py: from django.shortcuts import get_object_or_404, render_to_response from django.http import HttpResponseRedirect from django.core.urlresolvers import reverse from mysite.polls.models import Choice, Poll # ... def vote(request, poll_id): p = get_object_or_404(Poll, pk=poll_id) try: selected_choice = p.choice_set.get(pk=request.POST['choice']) except (KeyError, Choice.DoesNotExist): # Redisplay the poll voting form. return render_to_response('polls/detail.html', { 'poll': p, 'error_message': "You didn't select a choice.", }) else: selected_choice.votes += 1 selected_choice.save() # Always return an HttpResponseRedirect after successfully dealing # with POST data. This prevents data from being posted twice if a # user hits the Back button. return HttpResponseRedirect(reverse('mysite.polls.views.results', args=(p.id,))) This code includes a few things we haven’t covered yet in this tutorial: • request.POST is a dictionary-like object that lets you access submitted data by key name. In this case, request.POST['choice'] returns the ID of the selected choice, as a string. request.POST values are always strings. Note that Django also provides request.GET for accessing GET data in the same way — but we’re explicitly using request.POST in our code, to ensure that data is only altered via a POST call. • request.POST['choice'] will raise KeyError if choice wasn’t provided in POST data. The above code checks for KeyError and redisplays the poll form with an error message if choice isn’t given. • After incrementing the choice count, the code returns an HttpResponseRedirect rather than a normal HttpResponse. HttpResponseRedirect takes a single argument: the URL to which the user will be redirected (see the following point for how we construct the URL in this case). As the Python comment above points out, you should always return an HttpResponseRedirect after successfully dealing with POST data. This tip isn’t specific to Django; it’s just good Web development practice. • We are using the reverse() function in the HttpResponseRedirect constructor in this example. This function helps avoid having to hardcode a URL in the view function. It is given the name of the view that we want to pass control to and the variable portion of the URL pattern that points to that view. In this case, using the URLConf we set up in Tutorial 3, this reverse() call will return a string like '/polls/3/results/' Write a simple form 46
Slide 47: Django | Documentation … where the 3 is the value of p.id. This redirected URL will then call the 'results' view to display the final page. Note that you need to use the full name of the view here (including the prefix). For more information about reverse(), see the URL dispatcher documentation. As mentioned in Tutorial 3, request is a HTTPRequest object. For more on HTTPRequest objects, see the request and response documentation. After somebody votes in a poll, the vote() view redirects to the results page for the poll. Let’s write that view: def results(request, poll_id): p = get_object_or_404(Poll, pk=poll_id) return render_to_response('polls/results.html', {'poll': p}) This is almost exactly the same as the detail() view from Tutorial 3. The only difference is the template name. We’ll fix this redundancy later. Now, create a results.html template: <h1>{{ poll.question }}</h1> <ul> {% for choice in poll.choice_set.all %} <li>{{ choice.choice }} -- {{ choice.votes }} vote{{ choice.votes|pluralize }}</li> {% endfor %} </ul> Now, go to /polls/1/ in your browser and vote in the poll. You should see a results page that gets updated each time you vote. If you submit the form without having chosen a choice, you should see the error message. Use generic views: Less code is better The detail() (from Tutorial 3) and results() views are stupidly simple — and, as mentioned above, redundant. The index() view (also from Tutorial 3), which displays a list of polls, is similar. These views represent a common case of basic Web development: getting data from the database according to a parameter passed in the URL, loading a template and returning the rendered template. Because this is so common, Django provides a shortcut, called the “generic views” system. Generic views abstract common patterns to the point where you don’t even need to write Python code to write an app. Let’s convert our poll app to use the generic views system, so we can delete a bunch of our own code. We’ll just have to take a few steps to make the conversion. Why the code-shuffle? Generally, when writing a Django app, you’ll evaluate whether generic views are a good fit for your problem, and you’ll use them from the beginning, rather than refactoring your code halfway through. But this tutorial intentionally has focused on writing the views “the hard way” until now, to focus on core concepts. Use generic views: Less code is better 47
Slide 48: Django | Documentation You should know basic math before you start using a calculator. First, open the polls/urls.py URLconf. It looks like this, according to the tutorial so far: from django.conf.urls.defaults import * urlpatterns = patterns('mysite.polls.views', (r'^$', 'index'), (r'^(?P<poll_id>\d+)/$', 'detail'), (r'^(?P<poll_id>\d+)/results/$', 'results'), (r'^(?P<poll_id>\d+)/vote/$', 'vote'), ) Change it like so: from django.conf.urls.defaults import * from mysite.polls.models import Poll info_dict = { 'queryset': Poll.objects.all(), } urlpatterns = patterns('', (r'^$', 'django.views.generic.list_detail.object_list', info_dict), (r'^(?P<object_id>\d+)/$', 'django.views.generic.list_detail.object_detail', info_dict), (r'^(?P<object_id>\d+)/results/$', 'django.views.generic.list_detail.object_detail', dict(i (r'^(?P<poll_id>\d+)/vote/$', 'mysite.polls.views.vote'), ) We’re using two generic views here: object_list and object_detail. Respectively, those two views abstract the concepts of “display a list of objects” and “display a detail page for a particular type of object.” • Each generic view needs to know what data it will be acting upon. This data is provided in a dictionary. The queryset key in this dictionary points to the list of objects to be manipulated by the generic view. • The object_detail generic view expects the ID value captured from the URL to be called "object_id", so we’ve changed poll_id to object_id for the generic views. • We’ve added a name, poll_results, to the results view so that we have a way to refer to its URL later on (see naming URL patterns for more on named patterns). By default, the object_detail generic view uses a template called <app name>/<model name>_detail.html. In our case, it’ll use the template "polls/poll_detail.html". Thus, rename your polls/detail.html template to polls/poll_detail.html, and change the render_to_response() line in vote(). Similarly, the object_list generic view uses a template called <app name>/<model name>_list.html. Thus, rename polls/index.html to polls/poll_list.html. Because we have more than one entry in the URLconf that uses object_detail for the polls app, we manually specify a template name for the results view: template_name='polls/results.html'. Otherwise, both views would use the same template. Note that we use dict() to return an altered dictionary in place. Note Use generic views: Less code is better 48
Slide 49: Django | Documentation all() is lazy It might look a little frightening to see Poll.objects.all() being used in a detail view which only needs one Poll object, but don’t worry; Poll.objects.all() is actually a special object called a QuerySet, which is “lazy” and doesn’t hit your database until it absolutely has to. By the time the database query happens, the object_detail generic view will have narrowed its scope down to a single object, so the eventual query will only select one row from the database. If you’d like to know more about how that works, The Django database API documentation explains the lazy nature of QuerySet objects. In previous parts of the tutorial, the templates have been provided with a context that contains the poll and latest_poll_list context variables. However, the generic views provide the variables object and object_list as context. Therefore, you need to change your templates to match the new context variables. Go through your templates, and modify any reference to latest_poll_list to object_list, and change any reference to poll to object. You can now delete the index(), detail() and results() views from polls/views.py. We don’t need them anymore — they have been replaced by generic views. The vote() view is still required. However, it must be modified to match the new templates and context variables. Change the template call from polls/detail.html to polls/poll_detail.html, and pass object in the context instead of poll. The last thing to do is fix the URL handling to account for the use of generic views. In the vote view above, we used the reverse() function to avoid hard-coding our URLs. Now that we’ve switched to a generic view, we’ll need to change the reverse() call to point back to our new generic view. We can’t simply use the view function anymore — generic views can be (and are) used multiple times — but we can use the name we’ve given: return HttpResponseRedirect(reverse('poll_results', args=(p.id,))) Run the server, and use your new polling app based on generic views. For full details on generic views, see the generic views documentation. Coming soon The tutorial ends here for the time being. But check back soon for the next installments: • Advanced form processing • Using the RSS framework • Using the cache framework • Using the comments framework • Advanced admin features: Permissions • Advanced admin features: Custom JavaScript In the meantime, you can read through the rest of the Django documentation and start writing your own applications. Coming soon 49
Slide 50: Django | Documentation Questions/Feedback If you notice errors with this documentation, please open a ticket and let us know! Please only use the ticket tracker for criticisms and improvements on the docs. For tech support, ask in the IRC channel or post to the django-users list. Contents • Write a simple form • Use generic views: Less code is better • Coming soon Last update: August 4, 11:39 p.m. © 2005-2007 Lawrence Journal-World unless otherwise noted. Django is a registered trademark of Lawrence Journal-World. Questions/Feedback 50
Slide 51: Django | Documentation • Home • Download • Documentation • Weblog • Community • Code Django documentation django-admin.py and manage.py This document is for Django's SVN release, which can be significantly different than previous releases. Get old docs here: 0.96, 0.95. django-admin.py is Django’s command-line utility for administrative tasks. This document outlines all it can do. In addition, manage.py is automatically created in each Django project. manage.py is a thin wrapper around django-admin.py that takes care of two things for you before delegating to django-admin.py: • It puts your project’s package on sys.path. • It sets the DJANGO_SETTINGS_MODULE environment variable so that it points to your project’s settings.py file. The django-admin.py script should be on your system path if you installed Django via its setup.py utility. If it’s not on your path, you can find it in site-packages/django/bin within your Python installation. Consider symlinking it from some place on your path, such as /usr/local/bin. For Windows users, who do not have symlinking functionality available, you can copy django-admin.py to a location on your existing path or edit the PATH settings (under Settings - Control Panel System - Advanced - Environment...) to point to its installed location. Generally, when working on a single Django project, it’s easier to use manage.py. Use django-admin.py with DJANGO_SETTINGS_MODULE, or the --settings command line option, if you need to switch between multiple Django settings files. The command-line examples throughout this document use django-admin.py to be consistent, but any example can use manage.py just as well. Usage django-admin.py action [options] django-admin.py and manage.py 51
Slide 52: Django | Documentation manage.py action [options] action should be one of the actions listed in this document. options, which is optional, should be zero or more of the options listed in this document. Run django-admin.py --help to display a help message that includes a terse list of all available actions and options. Most actions take a list of appname``s. An ``appname is the basename of the package containing your models. For example, if your INSTALLED_APPS contains the string 'mysite.blog', the appname is blog. Available actions adminindex [appname appname …] Prints the admin-index template snippet for the given appnames. Use admin-index template snippets if you want to customize the look and feel of your admin’s index page. See Tutorial 2 for more information. createcachetable [tablename] Creates a cache table named tablename for use with the database cache backend. See the cache documentation for more information. dbshell Runs the command-line client for the database engine specified in your DATABASE_ENGINE setting, with the connection parameters specified in your DATABASE_USER, DATABASE_PASSWORD, etc., settings. • For PostgreSQL, this runs the psql command-line client. • For MySQL, this runs the mysql command-line client. • For SQLite, this runs the sqlite3 command-line client. This command assumes the programs are on your PATH so that a simple call to the program name (psql, mysql, sqlite3) will find the program in the right place. There’s no way to specify the location of the program manually. diffsettings Displays differences between the current settings file and Django’s default settings. Settings that don’t appear in the defaults are followed by "###". For example, the default settings don’t define ROOT_URLCONF, so ROOT_URLCONF is followed by "###" in the output of diffsettings. Note that Django’s default settings live in django/conf/global_settings.py, if you’re ever curious to see the full list of defaults. Usage 52
Slide 53: Django | Documentation dumpdata [appname appname …] Output to standard output all data in the database associated with the named application(s). By default, the database will be dumped in JSON format. If you want the output to be in another format, use the --format option (e.g., format=xml). You may specify any Django serialization backend (including any user specified serialization backends named in the SERIALIZATION_MODULES setting). The --indent option can be used to pretty-print the output. If no application name is provided, all installed applications will be dumped. The output of dumpdata can be used as input for loaddata. flush Return the database to the state it was in immediately after syncdb was executed. This means that all data will be removed from the database, any post-synchronization handlers will be re-executed, and the initial_data fixture will be re-installed. inspectdb Introspects the database tables in the database pointed-to by the DATABASE_NAME setting and outputs a Django model module (a models.py file) to standard output. Use this if you have a legacy database with which you’d like to use Django. The script will inspect the database and create a model for each table within it. As you might expect, the created models will have an attribute for every field in the table. Note that inspectdb has a few special cases in its field-name output: • If inspectdb cannot map a column’s type to a model field type, it’ll use TextField and will insert the Python comment 'This field type is a guess.' next to the field in the generated model. • If the database column name is a Python reserved word (such as 'pass', 'class' or 'for'), inspectdb will append '_field' to the attribute name. For example, if a table has a column 'for', the generated model will have a field 'for_field', with the db_column attribute set to 'for'. inspectdb will insert the Python comment 'Field renamed because it was a Python reserved word.' next to the field. This feature is meant as a shortcut, not as definitive model generation. After you run it, you’ll want to look over the generated models yourself to make customizations. In particular, you’ll need to rearrange models’ order, so that models that refer to other models are ordered properly. Primary keys are automatically introspected for PostgreSQL, MySQL and SQLite, in which case Django puts in the primary_key=True where needed. inspectdb works with PostgreSQL, MySQL and SQLite. Foreign-key detection only works in PostgreSQL and with certain types of MySQL tables. dumpdata [appname appname …] 53
Slide 54: Django | Documentation loaddata [fixture fixture …] Searches for and loads the contents of the named fixture into the database. A Fixture is a collection of files that contain the serialized contents of the database. Each fixture has a unique name; however, the files that comprise the fixture can be distributed over multiple directories, in multiple applications. Django will search in three locations for fixtures: 1. In the fixtures directory of every installed application 2. In any directory named in the FIXTURE_DIRS setting 3. In the literal path named by the fixture Django will load any and all fixtures it finds in these locations that match the provided fixture names. If the named fixture has a file extension, only fixtures of that type will be loaded. For example: django-admin.py loaddata mydata.json would only load JSON fixtures called mydata. The fixture extension must correspond to the registered name of a serializer (e.g., json or xml). If you omit the extension, Django will search all available fixture types for a matching fixture. For example: django-admin.py loaddata mydata would look for any fixture of any fixture type called mydata. If a fixture directory contained mydata.json, that fixture would be loaded as a JSON fixture. However, if two fixtures with the same name but different fixture type are discovered (for example, if mydata.json and mydata.xml were found in the same fixture directory), fixture installation will be aborted, and any data installed in the call to loaddata will be removed from the database. The fixtures that are named can include directory components. These directories will be included in the search path. For example: django-admin.py loaddata foo/bar/mydata.json would search <appname>/fixtures/foo/bar/mydata.json for each installed application, <dirname>/foo/bar/mydata.json for each directory in FIXTURE_DIRS, and the literal path foo/bar/mydata.json. Note that the order in which fixture files are processed is undefined. However, all fixture data is installed as a single transaction, so data in one fixture can reference data in another fixture. If the database backend supports row-level constraints, these constraints will be checked at the end of the transaction. The dumpdata command can be used to generate input for loaddata. MySQL and Fixtures loaddata [fixture fixture …] 54
Slide 55: Django | Documentation Unfortunately, MySQL isn’t capable of completely supporting all the features of Django fixtures. If you use MyISAM tables, MySQL doesn’t support transactions or constraints, so you won’t get a rollback if multiple transaction files are found, or validation of fixture data. If you use InnoDB tables, you won’t be able to have any forward references in your data files - MySQL doesn’t provide a mechanism to defer checking of row constraints until a transaction is committed. reset [appname appname …] Executes the equivalent of sqlreset for the given appnames. runfcgi [options] Starts a set of FastCGI processes suitable for use with any web server which supports the FastCGI protocol. See the FastCGI deployment documentation for details. Requires the Python FastCGI module from flup. runserver [optional port number, or ipaddr:port] Starts a lightweight development Web server on the local machine. By default, the server runs on port 8000 on the IP address 127.0.0.1. You can pass in an IP address and port number explicitly. If you run this script as a user with normal privileges (recommended), you might not have access to start a port on a low port number. Low port numbers are reserved for the superuser (root). DO NOT USE THIS SERVER IN A PRODUCTION SETTING. It has not gone through security audits or performance tests. (And that’s how it’s gonna stay. We’re in the business of making Web frameworks, not Web servers, so improving this server to be able to handle a production environment is outside the scope of Django.) The development server automatically reloads Python code for each request, as needed. You don’t need to restart the server for code changes to take effect. When you start the server, and each time you change Python code while the server is running, the server will validate all of your installed models. (See the validate command below.) If the validator finds errors, it will print them to standard output, but it won’t stop the server. You can run as many servers as you want, as long as they’re on separate ports. Just execute django-admin.py runserver more than once. Note that the default IP address, 127.0.0.1, is not accessible from other machines on your network. To make your development server viewable to other machines on the network, use its own IP address (e.g. 192.168.2.1) or 0.0.0.0. Examples: Port 7000 on IP address 127.0.0.1: django-admin.py runserver 7000 Port 7000 on IP address 1.2.3.4: reset [appname appname …] 55
Slide 56: Django | Documentation django-admin.py runserver 1.2.3.4:7000 Serving static files with the development server By default, the development server doesn’t serve any static files for your site (such as CSS files, images, things under MEDIA_URL and so forth). If you want to configure Django to serve static media, read the serving static files documentation. Turning off auto-reload To disable auto-reloading of code while the development server is running, use the --noreload option, like so: django-admin.py runserver --noreload shell Starts the Python interactive interpreter. Django will use IPython, if it’s installed. If you have IPython installed and want to force use of the “plain” Python interpreter, use the --plain option, like so: django-admin.py shell --plain sql [appname appname …] Prints the CREATE TABLE SQL statements for the given appnames. sqlall [appname appname …] Prints the CREATE TABLE and initial-data SQL statements for the given appnames. Refer to the description of sqlcustom for an explanation of how to specify initial data. sqlclear [appname appname …] Prints the DROP TABLE SQL statements for the given appnames. sqlcustom [appname appname …] Prints the custom SQL statements for the given appnames. For each model in each specified app, this command looks for the file <appname>/sql/<modelname>.sql, where <appname> is the given appname and <modelname> is the model’s name in lowercase. For example, if you have an app news that includes a Story model, sqlcustom will attempt to read a file news/sql/story.sql and append it to the output of this command. Each of the SQL files, if given, is expected to contain valid SQL. The SQL files are piped directly into the database after all of the models’ table-creation statements have been executed. Use this SQL hook to make runserver [optional port number, or ipaddr:port] 56
Slide 57: Django | Documentation any table modifications, or insert any SQL functions into the database. Note that the order in which the SQL files are processed is undefined. sqlindexes [appname appname …] Prints the CREATE INDEX SQL statements for the given appnames. sqlreset [appname appname …] Prints the DROP TABLE SQL, then the CREATE TABLE SQL, for the given appnames. sqlsequencereset [appname appname …] Prints the SQL statements for resetting sequences for the given appnames. See http://simon.incutio.com/archive/2004/04/21/postgres for more information. startapp [appname] Creates a Django app directory structure for the given app name in the current directory. startproject [projectname] Creates a Django project directory structure for the given project name in the current directory. syncdb Creates the database tables for all apps in INSTALLED_APPS whose tables have not already been created. Use this command when you’ve added new applications to your project and want to install them in the database. This includes any apps shipped with Django that might be in INSTALLED_APPS by default. When you start a new project, run this command to install the default apps. Syncdb will not alter existing tables syncdb will only create tables for models which have not yet been installed. It will never issue ALTER TABLE statements to match changes made to a model class after installation. Changes to model classes and database schemas often involve some form of ambiguity and, in those cases, Django would have to guess at the correct changes to make. There is a risk that critical data would be lost in the process. If you have made changes to a model and wish to alter the database tables to match, use the sql command to display the new SQL structure and compare that to your existing table schema to work out the changes. If you’re installing the django.contrib.auth application, syncdb will give you the option of creating a superuser immediately. syncdb will also search for and install any fixture named initial_data with an appropriate extension (e.g. json or xml). See the documentation for loaddata for details on the specification of fixture data sqlcustom [appname appname …] 57
Slide 58: Django | Documentation files. test Discover and run tests for all installed models. See Testing Django applications for more information. validate Validates all installed models (according to the INSTALLED_APPS setting) and prints validation errors to standard output. Available options —settings Example usage: django-admin.py syncdb --settings=mysite.settings Explicitly specifies the settings module to use. The settings module should be in Python package syntax, e.g. mysite.settings. If this isn’t provided, django-admin.py will use the DJANGO_SETTINGS_MODULE environment variable. Note that this option is unnecessary in manage.py, because it takes care of setting DJANGO_SETTINGS_MODULE for you. —pythonpath Example usage: django-admin.py syncdb --pythonpath='/home/djangoprojects/myproject' Adds the given filesystem path to the Python import search path. If this isn’t provided, django-admin.py will use the PYTHONPATH environment variable. Note that this option is unnecessary in manage.py, because it takes care of setting the Python path for you. —format Example usage: django-admin.py dumpdata --format=xml Specifies the output format that will be used. The name provided must be the name of a registered serializer. —help Displays a help message that includes a terse list of all available actions and options. syncdb 58
Slide 59: Django | Documentation —indent Example usage: django-admin.py dumpdata --indent=4 Specifies the number of spaces that will be used for indentation when pretty-printing output. By default, output will not be pretty-printed. Pretty-printing will only be enabled if the indent option is provided. —noinput Inform django-admin that the user should NOT be prompted for any input. Useful if the django-admin script will be executed as an unattended, automated script. —noreload Disable the use of the auto-reloader when running the development server. —version Displays the current Django version. Example output: 0.9.1 0.9.1 (SVN) —verbosity Example usage: django-admin.py syncdb --verbosity=2 Verbosity determines the amount of notification and debug information that will be printed to the console. ‘0’ is no output, ‘1’ is normal output, and 2 is verbose output. —adminmedia Example usage: django-admin.py --adminmedia=/tmp/new-admin-style/ Tells Django where to find the various CSS and JavaScript files for the admin interface when running the development server. Normally these files are served out of the Django source tree, but because some designers customize these files for their site, this option allows you to test against custom versions. Extra niceties —indent 59
Slide 60: Django | Documentation Syntax coloring The django-admin.py / manage.py commands that output SQL to standard output will use pretty color-coded output if your terminal supports ANSI-colored output. It won’t use the color codes if you’re piping the command’s output to another program. Bash completion If you use the Bash shell, consider installing the Django bash completion script, which lives in extras/django_bash_completion in the Django distribution. It enables tab-completion of django-admin.py and manage.py commands, so you can, for instance… • Type django-admin.py. • Press [TAB] to see all available options. • Type sql, then [TAB], to see all available options whose names start with sql. Questions/Feedback If you notice errors with this documentation, please open a ticket and let us know! Please only use the ticket tracker for criticisms and improvements on the docs. For tech support, ask in the IRC channel or post to the django-users list. Contents • Usage • Available actions ♦ adminindex [appname appname …] ♦ createcachetable [tablename] ♦ dbshell ♦ diffsettings ♦ dumpdata [appname appname …] ♦ flush ♦ inspectdb ♦ loaddata [fixture fixture …] ♦ reset [appname appname …] ♦ runfcgi [options] ♦ runserver [optional port number, or ipaddr:port] ◊ Examples: ◊ Serving static files with the development server ◊ Turning off auto-reload ♦ shell ♦ sql [appname appname …] ♦ sqlall [appname appname …] ♦ sqlclear [appname appname …] ♦ sqlcustom [appname appname …] ♦ sqlindexes [appname appname …] ♦ sqlreset [appname appname …] Syntax coloring 60
Slide 61: Django | Documentation ♦ sqlsequencereset [appname appname …] ♦ startapp [appname] ♦ startproject [projectname] ♦ syncdb ♦ test ♦ validate • Available options ♦ —settings ♦ —pythonpath ♦ —format ♦ —help ♦ —indent ♦ —noinput ♦ —noreload ♦ —version ♦ —verbosity ♦ —adminmedia • Extra niceties ♦ Syntax coloring ♦ Bash completion Last update: July 14, 12:27 a.m. © 2005-2007 Lawrence Journal-World unless otherwise noted. Django is a registered trademark of Lawrence Journal-World. Contents 61
Slide 62: Django | Documentation • Home • Download • Documentation • Weblog • Community • Code Django documentation Model reference This document is for Django's SVN release, which can be significantly different than previous releases. Get old docs here: 0.96, 0.95. A model is the single, definitive source of data about your data. It contains the essential fields and behaviors of the data you’re storing. Generally, each model maps to a single database table. The basics: • Each model is a Python class that subclasses django.db.models.Model. • Each attribute of the model represents a database field. • Model metadata (non-field information) goes in an inner class named Meta. • Metadata used for Django’s admin site goes into an inner class named Admin. • With all of this, Django gives you an automatically-generated database-access API, which is explained in the Database API reference. A companion to this document is the official repository of model examples. (In the Django source distribution, these examples are in the tests/modeltests directory.) Quick example This example model defines a Person, which has a first_name and last_name: from django.db import models class Person(models.Model): first_name = models.CharField(max_length=30) last_name = models.CharField(max_length=30) first_name and last_name are fields of the model. Each field is specified as a class attribute, and each attribute maps to a database column. The above Person model would create a database table like this: Model reference 62
Slide 63: Django | Documentation CREATE TABLE myapp_person ( "id" serial NOT NULL PRIMARY KEY, "first_name" varchar(30) NOT NULL, "last_name" varchar(30) NOT NULL ); Some technical notes: • The name of the table, myapp_person, is automatically derived from some model metadata but can be overridden. See Table names below. • An id field is added automatically, but this behavior can be overriden. See Automatic primary key fields below. • The CREATE TABLE SQL in this example is formatted using PostgreSQL syntax, but it’s worth noting Django uses SQL tailored to the database backend specified in your settings file. Fields The most important part of a model — and the only required part of a model — is the list of database fields it defines. Fields are specified by class attributes. Example: class Musician(models.Model): first_name = models.CharField(max_length=50) last_name = models.CharField(max_length=50) instrument = models.CharField(max_length=100) class Album(models.Model): artist = models.ForeignKey(Musician) name = models.CharField(max_length=100) release_date = models.DateField() num_stars = models.IntegerField() Field name restrictions Django places only two restrictions on model field names: 1. A field name cannot be a Python reserved word, because that would result in a Python syntax error. For example: class Example(models.Model): pass = models.IntegerField() # 'pass' is a reserved word! 2. A field name cannot contain more than one underscore in a row, due to the way Django’s query lookup syntax works. For example: class Example(models.Model): foo__bar = models.IntegerField() # 'foo__bar' has two underscores! These limitations can be worked around, though, because your field name doesn’t necessarily have to match your database column name. See db_column below. SQL reserved words, such as join, where or select, are allowed as model field names, because Django escapes all database table names and column names in every underlying SQL query. It uses the quoting syntax Quick example 63
Slide 64: Django | Documentation of your particular database engine. Field types Each field in your model should be an instance of the appropriate Field class. Django uses the field class types to determine a few things: • The database column type (e.g. INTEGER, VARCHAR). • The widget to use in Django’s admin interface, if you care to use it (e.g. <input type="text">, <select>). • The minimal validation requirements, used in Django’s admin and in manipulators. Here are all available field types: AutoField An IntegerField that automatically increments according to available IDs. You usually won’t need to use this directly; a primary key field will automatically be added to your model if you don’t specify otherwise. See Automatic primary key fields. BooleanField A true/false field. The admin represents this as a checkbox. CharField A string field, for small- to large-sized strings. For large amounts of text, use TextField. The admin represents this as an <input type="text"> (a single-line input). CharField has an extra required argument, max_length, the maximum length (in characters) of the field. The max_length is enforced at the database level and in Django’s validation. Django veterans: Note that the argument is now called max_length to provide consistency throughout Django. There is full legacy support for the old maxlength argument, but max_length is prefered. CommaSeparatedIntegerField System Message: WARNING/2 (<string>, line 154) Block quote ends without a blank line; unexpected unindent. A field of integers separated by commas. As in CharField, the max_length argument is required. Field name restrictions 64
Slide 65: Django | Documentation DateField A date field. Has a few extra optional arguments: Description Automatically set the field to now every time the object is saved. Useful for auto_now “last-modified” timestamps. Note that the current date is always used; it’s not just a default value that you can override. Automatically set the field to now when the object is first created. Useful for creation of auto_now_add timestamps. Note that the current date is always used; it’s not just a default value that you can override. The admin represents this as an <input type="text"> with a JavaScript calendar and a shortcut for “Today.” DateTimeField A date and time field. Takes the same extra options as DateField. The admin represents this as two <input type="text"> fields, with JavaScript shortcuts. DecimalField New in Django development version A fixed-precision decimal number, represented in Python by a Decimal instance. Has two required arguments: Argument Description max_digits The maximum number of digits allowed in the number. decimal_places The number of decimal places to store with the number. For example, to store numbers up to 999 with a resolution of 2 decimal places, you’d use: models.DecimalField(..., max_digits=5, decimal_places=2) Argument And to store numbers up to approximately one billion with a resolution of 10 decimal places: models.DecimalField(..., max_digits=19, decimal_places=10) The admin represents this as an <input type="text"> (a single-line input). EmailField A CharField that checks that the value is a valid e-mail address. This doesn’t accept max_length; its max_length is automatically set to 75. FileField A file-upload field. Has one required argument: Field types 65
Slide 66: Django | Documentation Description A local filesystem path that will be appended to your MEDIA_ROOT setting to determine the upload_to output of the get_<fieldname>_url() helper function. This path may contain strftime formatting, which will be replaced by the date/time of the file upload (so that uploaded files don’t fill up the given directory). The admin represents this field as an <input type="file"> (a file-upload widget). Using a FileField or an ImageField (see below) in a model takes a few steps: 1. In your settings file, you’ll need to define MEDIA_ROOT as the full path to a directory where you’d like Django to store uploaded files. (For performance, these files are not stored in the database.) Define MEDIA_URL as the base public URL of that directory. Make sure that this directory is writable by the Web server’s user account. 2. Add the FileField or ImageField to your model, making sure to define the upload_to option to tell Django to which subdirectory of MEDIA_ROOT it should upload files. 3. All that will be stored in your database is a path to the file (relative to MEDIA_ROOT). You’ll most likely want to use the convenience get_<fieldname>_url function provided by Django. For example, if your ImageField is called mug_shot, you can get the absolute URL to your image in a template with {{ object.get_mug_shot_url }}. For example, say your MEDIA_ROOT is set to '/home/media', and upload_to is set to 'photos/%Y/%m/%d'. The '%Y/%m/%d' part of upload_to is strftime formatting; '%Y' is the four-digit year, '%m' is the two-digit month and '%d' is the two-digit day. If you upload a file on Jan. 15, 2007, it will be saved in the directory /home/media/photos/2007/01/15. If you want to retrieve the upload file’s on-disk filename, or a URL that refers to that file, or the file’s size, you can use the get_FOO_filename(), get_FOO_url() and get_FOO_size() methods. They are all documented here. Note that whenever you deal with uploaded files, you should pay close attention to where you’re uploading them and what type of files they are, to avoid security holes. Validate all uploaded files so that you’re sure the files are what you think they are. For example, if you blindly let somebody upload files, without validation, to a directory that’s within your Web server’s document root, then somebody could upload a CGI or PHP script and execute that script by visiting its URL on your site. Don’t allow that. FilePathField A field whose choices are limited to the filenames in a certain directory on the filesystem. Has three special arguments, of which the first is required: Argument path Description Required. The absolute filesystem path to a directory from which this FilePathField should get its choices. Example: "/home/images". Optional. A regular expression, as a string, that FilePathField will use to filter filenames. Note that the regex will be applied to the base filename, not the full path. Example: "foo.*\.txt^", which will match a file called foo23.txt but not bar.txt or foo23.gif. Argument match recursive Field types 66
Slide 67: Django | Documentation Optional. Either True or False. Default is False. Specifies whether all subdirectories of path should be included. Of course, these arguments can be used together. The one potential gotcha is that match applies to the base filename, not the full path. So, this example: FilePathField(path="/home/images", match="foo.*", recursive=True) …will match /home/images/foo.gif but not /home/images/foo/bar.gif because the match applies to the base filename (foo.gif and bar.gif). FloatField Changed in Django development version A floating-point number represented in Python by a float instance. The admin represents this as an <input type="text"> (a single-line input). NOTE: The semantics of FloatField have changed in the Django development version. See the Django 0.96 documentation for the old behavior. ImageField Like FileField, but validates that the uploaded object is a valid image. Has two extra optional arguments, height_field and width_field, which, if set, will be auto-populated with the height and width of the image each time a model instance is saved. In addition to the special get_FOO_* methods that are available for FileField, an ImageField also has get_FOO_height() and get_FOO_width() methods. These are documented elsewhere. Requires the Python Imaging Library. IntegerField An integer. The admin represents this as an <input type="text"> (a single-line input). IPAddressField An IP address, in string format (i.e. “24.124.1.30”). The admin represents this as an <input type="text"> (a single-line input). NullBooleanField Like a BooleanField, but allows NULL as one of the options. Use this instead of a BooleanField with null=True. Field types 67
Slide 68: Django | Documentation The admin represents this as a <select> box with “Unknown”, “Yes” and “No” choices. PhoneNumberField A CharField that checks that the value is a valid U.S.A.-style phone number (in the format XXX-XXX-XXXX). PositiveIntegerField Like an IntegerField, but must be positive. PositiveSmallIntegerField Like a PositiveIntegerField, but only allows values under a certain (database-dependent) point. SlugField “Slug” is a newspaper term. A slug is a short label for something, containing only letters, numbers, underscores or hyphens. They’re generally used in URLs. Like a CharField, you can specify max_length. If max_length is not specified, Django will use a default length of 50. Implies db_index=True. Accepts an extra option, prepopulate_from, which is a list of fields from which to auto-populate the slug, via JavaScript, in the object’s admin form: models.SlugField(prepopulate_from=("pre_name", "name")) prepopulate_from doesn’t accept DateTimeFields. The admin represents SlugField as an <input type="text"> (a single-line input). SmallIntegerField Like an IntegerField, but only allows values under a certain (database-dependent) point. TextField A large text field. The admin represents this as a <textarea> (a multi-line input). TimeField A time. Accepts the same auto-population options as DateField and DateTimeField. The admin represents this as an <input type="text"> with some JavaScript shortcuts. Field types 68
Slide 69: Django | Documentation URLField A field for a URL. If the verify_exists option is True (default), the URL given will be checked for existence (i.e., the URL actually loads and doesn’t give a 404 response). The admin represents this as an <input type="text"> (a single-line input). URLField takes an optional argument, max_length, the maximum length (in characters) of the field. The maximum length is enforced at the database level and in Django’s validation. If you don’t specify max_length, a default of 200 is used. USStateField A two-letter U.S. state abbreviation. The admin represents this as an <input type="text"> (a single-line input). XMLField A TextField that checks that the value is valid XML that matches a given schema. Takes one required argument, schema_path, which is the filesystem path to a RelaxNG schema against which to validate the field. Field options The following arguments are available to all field types. All are optional. null If True, Django will store empty values as NULL in the database. Default is False. Note that empty string values will always get stored as empty strings, not as NULL. Only use null=True for non-string fields such as integers, booleans and dates. For both types of fields, you will also need to set blank=True if you wish to permit empty values in forms, as the null parameter only affects database storage (see blank, below). Avoid using null on string-based fields such as CharField and TextField unless you have an excellent reason. If a string-based field has null=True, that means it has two possible values for “no data”: NULL, and the empty string. In most cases, it’s redundant to have two possible values for “no data;” Django convention is to use the empty string, not NULL. Note When using the Oracle database backend, the null=True option will be coerced for string-based fields that can blank, and the value NULL will be stored to denote the empty string. blank If True, the field is allowed to be blank. Default is False. Field types 69
Slide 70: Django | Documentation Note that this is different than null. null is purely database-related, whereas blank is validation-related. If a field has blank=True, validation on Django’s admin site will allow entry of an empty value. If a field has blank=False, the field will be required. choices An iterable (e.g., a list or tuple) of 2-tuples to use as choices for this field. If this is given, Django’s admin will use a select box instead of the standard text field and will limit choices to the choices given. A choices list looks like this: YEAR_IN_SCHOOL_CHOICES = ( ('FR', 'Freshman'), ('SO', 'Sophomore'), ('JR', 'Junior'), ('SR', 'Senior'), ('GR', 'Graduate'), ) The first element in each tuple is the actual value to be stored. The second element is the human-readable name for the option. The choices list can be defined either as part of your model class: class Foo(models.Model): GENDER_CHOICES = ( ('M', 'Male'), ('F', 'Female'), ) gender = models.CharField(max_length=1, choices=GENDER_CHOICES) or outside your model class altogether: GENDER_CHOICES = ( ('M', 'Male'), ('F', 'Female'), ) class Foo(models.Model): gender = models.CharField(max_length=1, choices=GENDER_CHOICES) For each model field that has choices set, Django will add a method to retrieve the human-readable name for the field’s current value. See get_FOO_display in the database API documentation. Finally, note that choices can be any iterable object — not necessarily a list or tuple. This lets you construct choices dynamically. But if you find yourself hacking choices to be dynamic, you’re probably better off using a proper database table with a ForeignKey. choices is meant for static data that doesn’t change much, if ever. core For objects that are edited inline to a related object. Field options 70
Slide 71: Django | Documentation In the Django admin, if all “core” fields in an inline-edited object are cleared, the object will be deleted. It is an error to have an inline-editable relation without at least one core=True field. Please note that each field marked “core” is treated as a required field by the Django admin site. Essentially, this means you should put core=True on all required fields in your related object that is being edited inline. db_column The name of the database column to use for this field. If this isn’t given, Django will use the field’s name. If your database column name is an SQL reserved word, or contains characters that aren’t allowed in Python variable names — notably, the hyphen — that’s OK. Django quotes column and table names behind the scenes. db_index If True, django-admin.py sqlindexes will output a CREATE INDEX statement for this field. db_tablespace New in Django development version The name of the database tablespace to use for this field’s index, if indeed this field is indexed. The default is the db_tablespace of the model, if any. If the backend doesn’t support tablespaces, this option is ignored. default The default value for the field. editable If False, the field will not be editable in the admin or via form processing using the object’s AddManipulator or ChangeManipulator classes. Default is True. help_text Extra “help” text to be displayed under the field on the object’s admin form. It’s useful for documentation even if your object doesn’t have an admin form. primary_key If True, this field is the primary key for the model. If you don’t specify primary_key=True for any fields in your model, Django will automatically add this field: id = models.AutoField('ID', primary_key=True) Thus, you don’t need to set primary_key=True on any of your fields unless you want to override the default primary-key behavior. Field options 71
Slide 72: Django | Documentation primary_key=True implies blank=False, null=False and unique=True. Only one primary key is allowed on an object. radio_admin By default, Django’s admin uses a select-box interface (<select>) for fields that are ForeignKey or have choices set. If radio_admin is set to True, Django will use a radio-button interface instead. Don’t use this for a field unless it’s a ForeignKey or has choices set. unique If True, this field must be unique throughout the table. This is enforced at the database level and at the Django admin-form level. unique_for_date Set this to the name of a DateField or DateTimeField to require that this field be unique for the value of the date field. For example, if you have a field title that has unique_for_date="pub_date", then Django wouldn’t allow the entry of two records with the same title and pub_date. This is enforced at the Django admin-form level but not at the database level. unique_for_month Like unique_for_date, but requires the field to be unique with respect to the month. unique_for_year Like unique_for_date and unique_for_month. validator_list A list of extra validators to apply to the field. Each should be a callable that takes the parameters field_data, all_data and raises django.core.validators.ValidationError for errors. (See the validator docs.) Django comes with quite a few validators. They’re in django.core.validators. Verbose field names Each field type, except for ForeignKey, ManyToManyField and OneToOneField, takes an optional first positional argument — a verbose name. If the verbose name isn’t given, Django will automatically create it using the field’s attribute name, converting underscores to spaces. In this example, the verbose name is "Person's first name": first_name = models.CharField("Person's first name", max_length=30) Field options 72
Slide 73: Django | Documentation In this example, the verbose name is "first name": first_name = models.CharField(max_length=30) ForeignKey, ManyToManyField and OneToOneField require the first argument to be a model class, so use the verbose_name keyword argument: poll = models.ForeignKey(Poll, verbose_name="the related poll") sites = models.ManyToManyField(Site, verbose_name="list of sites") place = models.OneToOneField(Place, verbose_name="related place") Convention is not to capitalize the first letter of the verbose_name. Django will automatically capitalize the first letter where it needs to. Relationships Clearly, the power of relational databases lies in relating tables to each other. Django offers ways to define the three most common types of database relationships: Many-to-one, many-to-many and one-to-one. Many-to-one relationships To define a many-to-one relationship, use ForeignKey. You use it just like any other Field type: by including it as a class attribute of your model. ForeignKey requires a positional argument: The class to which the model is related. For example, if a Car model has a Manufacturer — that is, a Manufacturer makes multiple cars but each Car only has one Manufacturer — use the following definitions: class Manufacturer(models.Model): # ... class Car(models.Model): manufacturer = models.ForeignKey(Manufacturer) # ... To create a recursive relationship — an object that has a many-to-one relationship with itself — use models.ForeignKey('self'). If you need to create a relationship on a model that has not yet been defined, you can use the name of the model, rather than the model object itself: class Car(models.Model): manufacturer = models.ForeignKey('Manufacturer') # ... class Manufacturer(models.Model): # ... Note, however, that you can only use strings to refer to models in the same models.py file — you cannot use a string to reference a model in a different application, or to reference a model that has been imported from elsewhere. Verbose field names 73
Slide 74: Django | Documentation Behind the scenes, Django appends "_id" to the field name to create its database column name. In the above example, the database table for the Car model will have a manufacturer_id column. (You can change this explicitly by specifying db_column; see db_column below.) However, your code should never have to deal with the database column name, unless you write custom SQL. You’ll always deal with the field names of your model object. It’s suggested, but not required, that the name of a ForeignKey field (manufacturer in the example above) be the name of the model, lowercase. You can, of course, call the field whatever you want. For example: class Car(models.Model): company_that_makes_it = models.ForeignKey(Manufacturer) # ... See the Many-to-one relationship model example for a full example. ForeignKey fields take a number of extra arguments for defining how the relationship should work. All are optional: Argument Description If not False, this related object is edited “inline” on the related object’s page. This means that the object will not have its own admin interface. Use either models.TABULAR or models.STACKED, which, respectively, designate whether the inline-editable objects are displayed as a table or as a “stack” of fieldsets. A dictionary of lookup arguments and values (see the Database API reference) that limit the available admin choices for this object. Use this with functions from the Python datetime module to limit choices of objects by date. For example: limit_choices_to = {'pub_date__lte': datetime.now} edit_inline limit_choices_to only allows the choice of related objects with a pub_date before the current date/time to be chosen. Instead of a dictionary this can also be a Q object (an object with a get_sql() method) for more complex queries. Not compatible with edit_inline. For inline-edited objects, this is the maximum number of related objects to display in the admin. Thus, if a pizza could only have up to 10 toppings, max_num_in_admin=10 would ensure that a user never enters more than 10 toppings. Note that this doesn’t ensure more than 10 related toppings ever get created. It simply controls the admin interface; it doesn’t enforce things at the Python API level or database level. The minimum number of related objects displayed in the admin. Normally, at the creation stage, num_in_admin inline objects are shown, and at the edit stage num_extra_on_change blank objects are shown in addition to all max_num_in_admin min_num_in_admin Relationships 74
Slide 75: Django | Documentation pre-existing related objects. However, no fewer than min_num_in_admin related objects will ever be displayed. num_extra_on_change The number of extra blank related-object fields to show at the change stage. The default number of inline objects to display on the object page at the add num_in_admin stage. Only display a field for the integer to be entered instead of a drop-down menu. This is useful when related to an object type that will have too many rows to raw_id_admin make a select box practical. Not used with edit_inline. The name to use for the relation from the related object back to this one. See the related_name related objects documentation for a full explanation and example. The field on the related object that the relation is to. By default, Django uses the to_field primary key of the related object. Many-to-many relationships To define a many-to-many relationship, use ManyToManyField. You use it just like any other Field type: by including it as a class attribute of your model. ManyToManyField requires a positional argument: The class to which the model is related. For example, if a Pizza has multiple Topping objects — that is, a Topping can be on multiple pizzas and each Pizza has multiple toppings — here’s how you’d represent that: class Topping(models.Model): # ... class Pizza(models.Model): # ... toppings = models.ManyToManyField(Topping) As with ForeignKey, a relationship to self can be defined by using the string 'self' instead of the model name, and you can refer to as-yet undefined models by using a string containing the model name. However, you can only use strings to refer to models in the same models.py file — you cannot use a string to reference a model in a different application, or to reference a model that has been imported from elsewhere. It’s suggested, but not required, that the name of a ManyToManyField (toppings in the example above) be a plural describing the set of related model objects. Behind the scenes, Django creates an intermediary join table to represent the many-to-many relationship. It doesn’t matter which model gets the ManyToManyField, but you only need it in one of the models — not in both. Generally, ManyToManyField instances should go in the object that’s going to be edited in the admin interface, if you’re using Django’s admin. In the above example, toppings is in Pizza (rather than Topping having a pizzas ManyToManyField ) because it’s more natural to think about a Pizza having toppings than a topping being on multiple pizzas. The way it’s set up above, the Pizza admin form would let users select the toppings. Relationships 75
Slide 76: Django | Documentation See the Many-to-many relationship model example for a full example. ManyToManyField objects take a number of extra arguments for defining how the relationship should work. All are optional: Argument related_name Description See the description under ForeignKey above. Use a nifty unobtrusive Javascript “filter” interface instead of the usability-challenged <select multiple> in the admin form for this object. The filter_interface value should be models.HORIZONTAL or models.VERTICAL (i.e. should the interface be stacked horizontally or vertically). limit_choices_to See the description under ForeignKey above. Only used in the definition of ManyToManyFields on self. Consider the following model: class Person(models.Model): friends = models.ManyToManyField(“self”) symmetrical When Django processes this model, it identifies that it has a ManyToManyField on itself, and as a result, it doesn’t add a person_set attribute to the Person class. Instead, the ManyToManyField is assumed to be symmetrical — that is, if I am your friend, then you are my friend. If you do not want symmetry in ManyToMany relationships with self, set symmetrical to False. This will force Django to add the descriptor for the reverse relationship, allowing ManyToMany relationships to be non-symmetrical. The name of the table to create for storing the many-to-many data. If this is not db_table provided, Django will assume a default name based upon the names of the two tables being joined. One-to-one relationships The semantics of one-to-one relationships will be changing soon, so we don’t recommend you use them. If that doesn’t scare you away, keep reading. To define a one-to-one relationship, use OneToOneField. You use it just like any other Field type: by including it as a class attribute of your model. This is most useful on the primary key of an object when that object “extends” another object in some way. OneToOneField requires a positional argument: The class to which the model is related. For example, if you’re building a database of “places”, you would build pretty standard stuff such as address, phone number, etc. in the database. Then, if you wanted to build a database of restaurants on top of the places, instead of repeating yourself and replicating those fields in the Restaurant model, you could make Restaurant have a OneToOneField to Place (because a restaurant “is-a” place). As with ForeignKey, a relationship to self can be defined by using the string "self" instead of the model name; references to as-yet undefined models can be made by using a string containing the model name. Relationships 76
Slide 77: Django | Documentation This OneToOneField will actually replace the primary key id field (since one-to-one relations share the same primary key), and will be displayed as a read-only field when you edit an object in the admin interface: See the One-to-one relationship model example for a full example. Custom field types New in Django development version Django’s built-in field types don’t cover every possible database column type — only the common types, such as VARCHAR and INTEGER. For more obscure column types, such as geographic polygons or even user-created types such as PostgreSQL custom types, you can define your own Django Field subclasses. Experimental territory This is an area of Django that traditionally has not been documented, but we’re starting to include bits of documentation, one feature at a time. Please forgive the sparseness of this section. If you like living on the edge and are comfortable with the risk of unstable, undocumented APIs, see the code for the core Field class in django/db/models/fields/__init__.py — but if/when the innards change, don’t say we didn’t warn you. To create a custom field type, simply subclass django.db.models.Field. Here is an incomplete list of the methods you should implement: db_type() Returns the database column data type for the Field, taking into account the current DATABASE_ENGINE setting. Say you’ve created a PostgreSQL custom type called mytype. You can use this field with Django by subclassing Field and implementing the db_type() method, like so: from django.db import models class MytypeField(models.Field): def db_type(self): return 'mytype' Once you have MytypeField, you can use it in any model, just like any other Field type: class Person(models.Model): name = models.CharField(max_length=80) gender = models.CharField(max_length=1) something_else = MytypeField() If you aim to build a database-agnostic application, you should account for differences in database column types. For example, the date/time column type in PostgreSQL is called timestamp, while the same column in MySQL is called datetime. The simplest way to handle this in a db_type() method is to import the Django settings module and check the DATABASE_ENGINE setting. For example: class MyDateField(models.Field): Custom field types 77
Slide 78: Django | Documentation def db_type(self): from django.conf import settings if settings.DATABASE_ENGINE == 'mysql': return 'datetime' else: return 'timestamp' The db_type() method is only called by Django when the framework constructs the CREATE TABLE statements for your application — that is, when you first create your tables. It’s not called at any other time, so it can afford to execute slightly complex code, such as the DATABASE_ENGINE check in the above example. Some database column types accept parameters, such as CHAR(25), where the parameter 25 represents the maximum column length. In cases like these, it’s more flexible if the parameter is specified in the model rather than being hard-coded in the db_type() method. For example, it wouldn’t make much sense to have a CharMaxlength25Field, shown here: # This is a silly example of hard-coded parameters. class CharMaxlength25Field(models.Field): def db_type(self): return 'char(25)' # In the model: class MyModel(models.Model): # ... my_field = CharMaxlength25Field() The better way of doing this would be to make the parameter specifiable at run time — i.e., when the class is instantiated. To do that, just implement __init__(), like so: # This is a much more flexible example. class BetterCharField(models.Field): def __init__(self, max_length, *args, **kwargs): self.max_length = max_length super(BetterCharField, self).__init__(*args, **kwargs) def db_type(self): return 'char(%s)' % self.max_length # In the model: class MyModel(models.Model): # ... my_field = BetterCharField(25) Note that if you implement __init__() on a Field subclass, it’s important to call Field.__init__() — i.e., the parent class’ __init__() method. Meta options Give your model metadata by using an inner class Meta, like so: class Foo(models.Model): bar = models.CharField(max_length=30) class Meta: # ... Meta options 78
Slide 79: Django | Documentation Model metadata is “anything that’s not a field”, such as ordering options, etc. Here’s a list of all possible Meta options. No options are required. Adding class Meta to a model is completely optional. db_table The name of the database table to use for the model: db_table = 'music_album' If this isn’t given, Django will use app_label + '_' + model_class_name. See “Table names” below for more. If your database table name is an SQL reserved word, or contains characters that aren’t allowed in Python variable names — notably, the hyphen — that’s OK. Django quotes column and table names behind the scenes. db_tablespace New in Django development version The name of the database tablespace to use for the model. If the backend doesn’t support tablespaces, this option is ignored. get_latest_by The name of a DateField or DateTimeField in the model. This specifies the default field to use in your model Manager‘s latest() method. Example: get_latest_by = "order_date" See the docs for latest() for more. order_with_respect_to Marks this object as “orderable” with respect to the given field. This is almost always used with related objects to allow them to be ordered with respect to a parent object. For example, if an Answer relates to a Question object, and a question has more than one answer, and the order of answers matters, you’d do this: class Answer(models.Model): question = models.ForeignKey(Question) # ... class Meta: order_with_respect_to = 'question' db_table 79
Slide 80: Django | Documentation ordering The default ordering for the object, for use when obtaining lists of objects: ordering = ['-order_date'] This is a tuple or list of strings. Each string is a field name with an optional “-” prefix, which indicates descending order. Fields without a leading “-” will be ordered ascending. Use the string “?” to order randomly. For example, to order by a pub_date field ascending, use this: ordering = ['pub_date'] To order by pub_date descending, use this: ordering = ['-pub_date'] To order by pub_date descending, then by author ascending, use this: ordering = ['-pub_date', 'author'] See Specifying ordering for more examples. Note that, regardless of how many fields are in ordering, the admin site uses only the first field. permissions Extra permissions to enter into the permissions table when creating this object. Add, delete and change permissions are automatically created for each object that has admin set. This example specifies an extra permission, can_deliver_pizzas: permissions = (("can_deliver_pizzas", "Can deliver pizzas"),) This is a list or tuple of 2-tuples in the format (permission_code, human_readable_permission_name). unique_together Sets of field names that, taken together, must be unique: unique_together = (("driver", "restaurant"),) This is a list of lists of fields that must be unique when considered together. It’s used in the Django admin and is enforced at the database level (i.e., the appropriate UNIQUE statements are included in the CREATE TABLE statement). verbose_name A human-readable name for the object, singular: ordering 80
Slide 81: Django | Documentation verbose_name = "pizza" If this isn’t given, Django will use a munged version of the class name: CamelCase becomes camel case. verbose_name_plural The plural name for the object: verbose_name_plural = "stories" If this isn’t given, Django will use verbose_name + "s". Table names To save you time, Django automatically derives the name of the database table from the name of your model class and the app that contains it. A model’s database table name is constructed by joining the model’s “app label” — the name you used in manage.py startapp — to the model’s class name, with an underscore between them. For example, if you have an app bookstore (as created by manage.py startapp bookstore), a model defined as class Book will have a database table named bookstore_book. To override the database table name, use the db_table parameter in class Meta. Automatic primary key fields By default, Django gives each model the following field: id = models.AutoField(primary_key=True) This is an auto-incrementing primary key. If you’d like to specify a custom primary key, just specify primary_key=True on one of your fields. If Django sees you’ve explicitly set primary_key, it won’t add the automatic id column. Each model requires exactly one field to have primary_key=True. Admin options If you want your model to be visible to Django’s admin site, give your model an inner "class Admin", like so: class Person(models.Model): first_name = models.CharField(max_length=30) last_name = models.CharField(max_length=30) class Admin: # Admin options go here pass verbose_name 81
Slide 82: Django | Documentation The Admin class tells Django how to display the model in the admin site. Here’s a list of all possible Admin options. None of these options are required. To use an admin interface without specifying any options, use pass, like so: class Admin: pass Adding class Admin to a model is completely optional. date_hierarchy Set date_hierarchy to the name of a DateField or DateTimeField in your model, and the change list page will include a date-based drilldown navigation by that field. Example: date_hierarchy = 'pub_date' fields Set fields to control the layout of admin “add” and “change” pages. fields is a list of two-tuples, in which each two-tuple represents a <fieldset> on the admin form page. (A <fieldset> is a “section” of the form.) The two-tuples are in the format (name, field_options), where name is a string representing the title of the fieldset and field_options is a dictionary of information about the fieldset, including a list of fields to be displayed in it. A full example, taken from the django.contrib.flatpages.FlatPage model: class Admin: fields = ( (None, { 'fields': ('url', 'title', 'content', 'sites') }), ('Advanced options', { 'classes': 'collapse', 'fields' : ('enable_comments', 'registration_required', 'template_name') }), ) This results in an admin page that looks like: Admin options 82
Slide 83: Django | Documentation If fields isn’t given, Django will default to displaying each field that isn’t an AutoField and has editable=True, in a single fieldset, in the same order as the fields are defined in the model. The field_options dictionary can have the following keys: fields A tuple of field names to display in this fieldset. This key is required. Example: { 'fields': ('first_name', 'last_name', 'address', 'city', 'state'), } To display multiple fields on the same line, wrap those fields in their own tuple. In this example, the first_name and last_name fields will display on the same line: { 'fields': (('first_name', 'last_name'), 'address', 'city', 'state'), } classes A string containing extra CSS classes to apply to the fieldset. Example: { 'classes': 'wide', fields 83
Slide 84: Django | Documentation } Apply multiple classes by separating them with spaces. Example: { 'classes': 'wide extrapretty', } Two useful classes defined by the default admin-site stylesheet are collapse and wide. Fieldsets with the collapse style will be initially collapsed in the admin and replaced with a small “click to expand” link. Fieldsets with the wide style will be given extra horizontal space. description A string of optional extra text to be displayed at the top of each fieldset, under the heading of the fieldset. It’s used verbatim, so you can use any HTML and you must escape any special HTML characters (such as ampersands) yourself. js A list of strings representing URLs of JavaScript files to link into the admin screen via <script src=""> tags. This can be used to tweak a given type of admin page in JavaScript or to provide “quick links” to fill in default values for certain fields. If you use relative URLs — URLs that don’t start with http:// or / — then the admin site will automatically prefix these links with settings.ADMIN_MEDIA_PREFIX. list_display Set list_display to control which fields are displayed on the change list page of the admin. Example: list_display = ('first_name', 'last_name') If you don’t set list_display, the admin site will display a single column that displays the __str__() representation of each object. A few special cases to note about list_display: • If the field is a ForeignKey, Django will display the __str__() of the related object. • ManyToManyField fields aren’t supported, because that would entail executing a separate SQL statement for each row in the table. If you want to do this nonetheless, give your model a custom method, and add that method’s name to list_display. (See below for more on custom methods in list_display.) • If the field is a BooleanField or NullBooleanField, Django will display a pretty “on” or “off” icon instead of True or False. • If the string given is a method of the model, Django will call it and display the output. This method should have a short_description function attribute, for use as the header for the field. Here’s a full example model: fields 84
Slide 85: Django | Documentation class Person(models.Model): name = models.CharField(max_length=50) birthday = models.DateField() class Admin: list_display = ('name', 'decade_born_in') def decade_born_in(self): return self.birthday.strftime('%Y')[:3] + "0's" decade_born_in.short_description = 'Birth decade' • If the string given is a method of the model, Django will HTML-escape the output by default. If you’d rather not escape the output of the method, give the method an allow_tags attribute whose value is True. Here’s a full example model: class Person(models.Model): first_name = models.CharField(max_length=50) last_name = models.CharField(max_length=50) color_code = models.CharField(max_length=6) class Admin: list_display = ('first_name', 'last_name', 'colored_name') def colored_name(self): return '<span style="color: #%s;">%s %s</span>' % (self.color_code, self.first_na colored_name.allow_tags = True • If the string given is a method of the model that returns True or False Django will display a pretty “on” or “off” icon if you give the method a boolean attribute whose value is True. Here’s a full example model: class Person(models.Model): first_name = models.CharField(max_length=50) birthday = models.DateField() class Admin: list_display = ('name', 'born_in_fifties') def born_in_fifties(self): return self.birthday.strftime('%Y')[:3] == 5 born_in_fifties.boolean = True • The __str__() and __unicode__() methods are just as valid in list_display as any other model method, so it’s perfectly OK to do this: list_display = ('__unicode__', 'some_other_field') • Usually, elements of list_display that aren’t actual database fields can’t be used in sorting (because Django does all the sorting at the database level). However, if an element of list_display represents a certain database field, you can indicate this fact by setting the admin_order_field attribute of the item. For example: class Person(models.Model): first_name = models.CharField(max_length=50) list_display 85
Slide 86: Django | Documentation color_code = models.CharField(max_length=6) class Admin: list_display = ('first_name', 'colored_first_name') def colored_first_name(self): return '<span style="color: #%s;">%s</span>' % (self.color_code, self.first_name) colored_first_name.allow_tags = True colored_first_name.admin_order_field = 'first_name' The above will tell Django to order by the first_name field when trying to sort by colored_first_name in the admin. list_display_links Set list_display_links to control which fields in list_display should be linked to the “change” page for an object. By default, the change list page will link the first column — the first field specified in list_display — to the change page for each item. But list_display_links lets you change which columns are linked. Set list_display_links to a list or tuple of field names (in the same format as list_display) to link. list_display_links can specify one or many field names. As long as the field names appear in list_display, Django doesn’t care how many (or how few) fields are linked. The only requirement is: If you want to use list_display_links, you must define list_display. In this example, the first_name and last_name fields will be linked on the change list page: class Admin: list_display = ('first_name', 'last_name', 'birthday') list_display_links = ('first_name', 'last_name') Finally, note that in order to use list_display_links, you must define list_display, too. list_filter Set list_filter to activate filters in the right sidebar of the change list page of the admin. This should be a list of field names, and each specified field should be either a BooleanField, DateField, DateTimeField or ForeignKey. This example, taken from the django.contrib.auth.models.User model, shows how both list_display and list_filter work: class Admin: list_display = ('username', 'email', 'first_name', 'last_name', 'is_staff') list_filter = ('is_staff', 'is_superuser') The above code results in an admin change list page that looks like this: list_display_links 86
Slide 87: Django | Documentation (This example also has search_fields defined. See below.) list_per_page Set list_per_page to control how many items appear on each paginated admin change list page. By default, this is set to 100. list_select_related Set list_select_related to tell Django to use select_related() in retrieving the list of objects on the admin change list page. This can save you a bunch of database queries. The value should be either True or False. Default is False. Note that Django will use select_related(), regardless of this setting, if one of the list_display fields is a ForeignKey. For more on select_related(), see the select_related() docs. ordering Set ordering to specify how objects on the admin change list page should be ordered. This should be a list or tuple in the same format as a model’s ordering parameter. If this isn’t provided, the Django admin will use the model’s default ordering. save_as Set save_as to enable a “save as” feature on admin change forms. Normally, objects have three save options: “Save”, “Save and continue editing” and “Save and add another”. If save_as is True, “Save and add another” will be replaced by a “Save as” button. “Save as” means the object will be saved as a new object (with a new ID), rather than the old object. By default, save_as is set to False. list_filter 87
Slide 88: Django | Documentation save_on_top Set save_on_top to add save buttons across the top of your admin change forms. Normally, the save buttons appear only at the bottom of the forms. If you set save_on_top, the buttons will appear both on the top and the bottom. By default, save_on_top is set to False. search_fields Set search_fields to enable a search box on the admin change list page. This should be set to a list of field names that will be searched whenever somebody submits a search query in that text box. These fields should be some kind of text field, such as CharField or TextField. You can also perform a related lookup on a ForeignKey with the lookup API “follow” notation: search_fields = ['foreign_key__related_fieldname'] When somebody does a search in the admin search box, Django splits the search query into words and returns all objects that contain each of the words, case insensitive, where each word must be in at least one of search_fields. For example, if search_fields is set to ['first_name', 'last_name'] and a user searches for john lennon, Django will do the equivalent of this SQL WHERE clause: WHERE (first_name ILIKE '%john%' OR last_name ILIKE '%john%') AND (first_name ILIKE '%lennon%' OR last_name ILIKE '%lennon%') For faster and/or more restrictive searches, prefix the field name with an operator: ^ Matches the beginning of the field. For example, if search_fields is set to ['^first_name', '^last_name'] and a user searches for john lennon, Django will do the equivalent of this SQL WHERE clause: WHERE (first_name ILIKE 'john%' OR last_name ILIKE 'john%') AND (first_name ILIKE 'lennon%' OR last_name ILIKE 'lennon%') This query is more efficient than the normal '%john%' query, because the database only needs to check the beginning of a column’s data, rather than seeking through the entire column’s data. Plus, if the column has an index on it, some databases may be able to use the index for this query, even though it’s a LIKE query. = Matches exactly, case-insensitive. For example, if search_fields is set to ['=first_name', '=last_name'] and a user searches for john lennon, Django will do the equivalent of this SQL WHERE clause: WHERE (first_name ILIKE 'john' OR last_name ILIKE 'john') AND (first_name ILIKE 'lennon' OR last_name ILIKE 'lennon') Note that the query input is split by spaces, so, following this example, it’s not currently not possible to search for all records in which first_name is exactly 'john winston' (containing a space). save_on_top 88
Slide 89: Django | Documentation @ Performs a full-text match. This is like the default search method but uses an index. Currently this is only available for MySQL. Managers A Manager is the interface through which database query operations are provided to Django models. At least one Manager exists for every model in a Django application. The way Manager classes work is documented in the Retrieving objects section of the database API docs, but this section specifically touches on model options that customize Manager behavior. Manager names By default, Django adds a Manager with the name objects to every Django model class. However, if you want to use objects as a field name, or if you want to use a name other than objects for the Manager, you can rename it on a per-model basis. To rename the Manager for a given class, define a class attribute of type models.Manager() on that model. For example: from django.db import models class Person(models.Model): #... people = models.Manager() Using this example model, Person.objects will generate an AttributeError exception, but Person.people.all() will provide a list of all Person objects. Custom Managers You can use a custom Manager in a particular model by extending the base Manager class and instantiating your custom Manager in your model. There are two reasons you might want to customize a Manager: to add extra Manager methods, and/or to modify the initial QuerySet the Manager returns. Adding extra Manager methods Adding extra Manager methods is the preferred way to add “table-level” functionality to your models. (For “row-level” functionality — i.e., functions that act on a single instance of a model object — use Model methods, not custom Manager methods.) A custom Manager method can return anything you want. It doesn’t have to return a QuerySet. For example, this custom Manager offers a method with_counts(), which returns a list of all OpinionPoll objects, each with an extra num_responses attribute that is the result of an aggregate query: class PollManager(models.Manager): def with_counts(self): from django.db import connection search_fields 89
Slide 90: Django | Documentation cursor = connection.cursor() cursor.execute(""" SELECT p.id, p.question, p.poll_date, COUNT(*) FROM polls_opinionpoll p, polls_response r WHERE p.id = r.poll_id GROUP BY 1, 2, 3 ORDER BY 3 DESC""") result_list = [] for row in cursor.fetchall(): p = self.model(id=row[0], question=row[1], poll_date=row[2]) p.num_responses = row[3] result_list.append(p) return result_list class OpinionPoll(models.Model): question = models.CharField(max_length=200) poll_date = models.DateField() objects = PollManager() class Response(models.Model): poll = models.ForeignKey(Poll) person_name = models.CharField(max_length=50) response = models.TextField() With this example, you’d use OpinionPoll.objects.with_counts() to return that list of OpinionPoll objects with num_responses attributes. Another thing to note about this example is that Manager methods can access self.model to get the model class to which they’re attached. Modifying initial Manager QuerySets A Manager‘s base QuerySet returns all objects in the system. For example, using this model: class Book(models.Model): title = models.CharField(max_length=100) author = models.CharField(max_length=50) …the statement Book.objects.all() will return all books in the database. You can override a Manager‘s base QuerySet by overriding the Manager.get_query_set() method. get_query_set() should return a QuerySet with the properties you require. For example, the following model has two Managers — one that returns all objects, and one that returns only the books by Roald Dahl: # First, define the Manager subclass. class DahlBookManager(models.Manager): def get_query_set(self): return super(DahlBookManager, self).get_query_set().filter(author='Roald Dahl') # Then hook it into the Book model explicitly. class Book(models.Model): title = models.CharField(max_length=100) author = models.CharField(max_length=50) objects = models.Manager() # The default manager. Custom Managers 90
Slide 91: Django | Documentation dahl_objects = DahlBookManager() # The Dahl-specific manager. With this sample model, Book.objects.all() will return all books in the database, but Book.dahl_objects.all() will only return the ones written by Roald Dahl. Of course, because get_query_set() returns a QuerySet object, you can use filter(), exclude() and all the other QuerySet methods on it. So these statements are all legal: Book.dahl_objects.all() Book.dahl_objects.filter(title='Matilda') Book.dahl_objects.count() This example also pointed out another interesting technique: using multiple managers on the same model. You can attach as many Manager() instances to a model as you’d like. This is an easy way to define common “filters” for your models. For example: class MaleManager(models.Manager): def get_query_set(self): return super(MaleManager, self).get_query_set().filter(sex='M') class FemaleManager(models.Manager): def get_query_set(self): return super(FemaleManager, self).get_query_set().filter(sex='F') class Person(models.Model): first_name = models.CharField(max_length=50) last_name = models.CharField(max_length=50) sex = models.CharField(max_length=1, choices=(('M', 'Male'), ('F', 'Female'))) people = models.Manager() men = MaleManager() women = FemaleManager() This example allows you to request Person.men.all(), Person.women.all(), and Person.people.all(), yielding predictable results. If you use custom Manager objects, take note that the first Manager Django encounters (in order by which they’re defined in the model) has a special status. Django interprets the first Manager defined in a class as the “default” Manager. Certain operations — such as Django’s admin site — use the default Manager to obtain lists of objects, so it’s generally a good idea for the first Manager to be relatively unfiltered. In the last example, the people Manager is defined first — so it’s the default Manager. Model methods Define custom methods on a model to add custom “row-level” functionality to your objects. Whereas Manager methods are intended to do “table-wide” things, model methods should act on a particular model instance. This is a valuable technique for keeping business logic in one place — the model. For example, this model has a few custom methods: class Person(models.Model): Model methods 91
Slide 92: Django | Documentation first_name = models.CharField(max_length=50) last_name = models.CharField(max_length=50) birth_date = models.DateField() address = models.CharField(max_length=100) city = models.CharField(max_length=50) state = models.USStateField() # Yes, this is America-centric... def baby_boomer_status(self): "Returns the person's baby-boomer status." import datetime if datetime.date(1945, 8, 1) <= self.birth_date <= datetime.date(1964, 12, 31): return "Baby boomer" if self.birth_date < datetime.date(1945, 8, 1): return "Pre-boomer" return "Post-boomer" def is_midwestern(self): "Returns True if this person is from the Midwest." return self.state in ('IL', 'WI', 'MI', 'IN', 'OH', 'IA', 'MO') def _get_full_name(self): "Returns the person's full name." return '%s %s' % (self.first_name, self.last_name) full_name = property(_get_full_name) The last method in this example is a property. Read more about properties. A few object methods have special meaning: __str__ __str__() is a Python “magic method” that defines what should be returned if you call str() on the object. Django uses str(obj) (or the related function, unicode(obj) — see below) in a number of places, most notably as the value displayed to render an object in the Django admin site and as the value inserted into a template when it displays an object. Thus, you should always return a nice, human-readable string for the object’s __str__. Although this isn’t required, it’s strongly encouraged (see the description of __unicode__, below, before putting _str__ methods everywhere). For example: class Person(models.Model): first_name = models.CharField(max_length=50) last_name = models.CharField(max_length=50) def __str__(self): # Note use of django.utils.encoding.smart_str() here because # first_name and last_name will be unicode strings. return smart_str('%s %s' % (self.first_name, self.last_name)) __unicode__ The __unicode__() method is called whenever you call unicode() on an object. Since Django’s database backends will return Unicode strings in your model’s attributes, you would normally want to write a __unicode__() method for your model. The example in the previous section could be written more simply as: __str__ 92
Slide 93: Django | Documentation class Person(models.Model): first_name = models.CharField(max_length=50) last_name = models.CharField(max_length=50) def __unicode__(self): return u'%s %s' % (self.first_name, self.last_name) If you define a __unicode__() method on your model and not a __str__() method, Django will automatically provide you with a __str__() that calls __unicode()__ and then converts the result correctly to a UTF-8 encoded string object. This is recommended development practice: define only __unicode__() and let Django take care of the conversion to string objects when required. get_absolute_url Define a get_absolute_url() method to tell Django how to calculate the URL for an object. For example: def get_absolute_url(self): return "/people/%i/" % self.id Django uses this in its admin interface. If an object defines get_absolute_url(), the object-editing page will have a “View on site” link that will jump you directly to the object’s public view, according to get_absolute_url(). Also, a couple of other bits of Django, such as the `syndication feed framework`_, use get_absolute_url() as a convenience to reward people who’ve defined the method. It’s good practice to use get_absolute_url() in templates, instead of hard-coding your objects’ URLs. For example, this template code is bad: <a href="/people/{{ object.id }}/">{{ object.name }}</a> But this template code is good: <a href="{{ object.get_absolute_url }}">{{ object.name }}</a> Note The string you return from get_absolute_url() must contain only ASCII characters (required by the URI spec, RFC 2396) that have been URL-encoded, if necessary. Code and templates using get_absolute_url() should be able to use the result directly without needing to do any further processing. You may wish to use the django.utils.encoding.iri_to_uri() function to help with this if you are using unicode strings a lot. The permalink decorator The problem with the way we wrote get_absolute_url() above is that it slightly violates the DRY principle: the URL for this object is defined both in the URLConf file and in the model. You can further decouple your models from the URLconf using the permalink decorator. This decorator is passed the view function, a list of positional parameters and (optionally) a dictionary of named parameters. Django then works out the correct full URL path using the URLconf, substituting the parameters you have __unicode__ 93
Slide 94: Django | Documentation given into the URL. For example, if your URLconf contained a line such as: (r'^people/(\d+)/$', 'people.views.details'), …your model could have a get_absolute_url method that looked like this: from django.db.models import permalink def get_absolute_url(self): return ('people.views.details', [str(self.id)]) get_absolute_url = permalink(get_absolute_url) Similarly, if you had a URLconf entry that looked like: (r'/archive/(?P<year>\d{4})/(?P<month>\d{1,2})/(?P<day>\d{1,2})/$', archive_view) …you could reference this using permalink() as follows: def get_absolute_url(self): return ('archive_view', (), { 'year': self.created.year, 'month': self.created.month, 'day': self.created.day}) get_absolute_url = permalink(get_absolute_url) Notice that we specify an empty sequence for the second argument in this case, because we only want to pass keyword arguments, not named arguments. In this way, you’re tying the model’s absolute URL to the view that is used to display it, without repeating the URL information anywhere. You can still use the get_absolute_url method in templates, as before. Executing custom SQL Feel free to write custom SQL statements in custom model methods and module-level methods. The object django.db.connection represents the current database connection. To use it, call connection.cursor() to get a cursor object. Then, call cursor.execute(sql, [params]) to execute the SQL and cursor.fetchone() or cursor.fetchall() to return the resulting rows. Example: def my_custom_sql(self): from django.db import connection cursor = connection.cursor() cursor.execute("SELECT foo FROM bar WHERE baz = %s", [self.baz]) row = cursor.fetchone() return row connection and cursor mostly implement the standard Python DB-API (except when it comes to transaction handling). If you’re not familiar with the Python DB-API, note that the SQL statement in cursor.execute() uses placeholders, "%s", rather than adding parameters directly within the SQL. If you use this technique, the underlying database library will automatically add quotes and escaping to your parameter(s) as necessary. (Also note that Django expects the "%s" placeholder, not the "?" placeholder, which is used by the SQLite Python bindings. This is for the sake of consistency and sanity.) get_absolute_url 94
Slide 95: Django | Documentation A final note: If all you want to do is a custom WHERE clause, you can just use the where, tables and params arguments to the standard lookup API. See Other lookup options. Overriding default model methods As explained in the database API docs, each model gets a few methods automatically — most notably, save() and delete(). You can override these methods to alter behavior. A classic use-case for overriding the built-in methods is if you want something to happen whenever you save an object. For example: class Blog(models.Model): name = models.CharField(max_length=100) tagline = models.TextField() def save(self): do_something() super(Blog, self).save() # Call the "real" save() method. do_something_else() You can also prevent saving: class Blog(models.Model): name = models.CharField(max_length=100) tagline = models.TextField() def save(self): if self.name == "Yoko Ono's blog": return # Yoko shall never have her own blog! else: super(Blog, self).save() # Call the "real" save() method. Models across files It’s perfectly OK to relate a model to one from another app. To do this, just import the related model at the top of the model that holds your model. Then, just refer to the other model class wherever needed. For example: from mysite.geography.models import ZipCode class Restaurant(models.Model): # ... zip_code = models.ForeignKey(ZipCode) Using models Once you have created your models, the final step is to tell Django you’re going to use those models. Do this by editing your settings file and changing the INSTALLED_APPS setting to add the name of the module that contains your models.py. For example, if the models for your application live in the module mysite.myapp.models (the package structure that is created for an application by the manage.py startapp script), INSTALLED_APPS should read, in part: Executing custom SQL 95
Slide 96: Django | Documentation INSTALLED_APPS = ( #... 'mysite.myapp', #... ) Providing initial SQL data Django provides a hook for passing the database arbitrary SQL that’s executed just after the CREATE TABLE statements. Use this hook, for example, if you want to populate default records, or create SQL functions, automatically. The hook is simple: Django just looks for a file called <appname>/sql/<modelname>.sql, where <appname> is your app directory and <modelname> is the model’s name in lowercase. In the Person example model at the top of this document, assuming it lives in an app called myapp, you could add arbitrary SQL to the file myapp/sql/person.sql. Here’s an example of what the file might contain: INSERT INTO myapp_person (first_name, last_name) VALUES ('John', 'Lennon'); INSERT INTO myapp_person (first_name, last_name) VALUES ('Paul', 'McCartney'); Each SQL file, if given, is expected to contain valid SQL. The SQL files are piped directly into the database after all of the models’ table-creation statements have been executed. The SQL files are read by the sqlcustom, sqlreset, sqlall and reset commands in manage.py. Refer to the manage.py documentation for more information. Note that if you have multiple SQL data files, there’s no guarantee of the order in which they’re executed. The only thing you can assume is that, by the time your custom data files are executed, all the database tables already will have been created. Database-backend-specific SQL data There’s also a hook for backend-specific SQL data. For example, you can have separate initial-data files for PostgreSQL and MySQL. For each app, Django looks for a file called <appname>/sql/<modelname>.<backend>.sql, where <appname> is your app directory, <modelname> is the model’s name in lowercase and <backend> is the value of DATABASE_ENGINE in your settings file (e.g., postgresql, mysql). Backend-specific SQL data is executed before non-backend-specific SQL data. For example, if your app contains the files sql/person.sql and sql/person.postgresql.sql and you’re installing the app on PostgreSQL, Django will execute the contents of sql/person.postgresql.sql first, then sql/person.sql. Docutils System Messages System Message: ERROR/3 (<string>, line 1949); backlink Unknown target name: “syndication feed framework”. Using models 96
Slide 97: Django | Documentation Questions/Feedback If you notice errors with this documentation, please open a ticket and let us know! Please only use the ticket tracker for criticisms and improvements on the docs. For tech support, ask in the IRC channel or post to the django-users list. Contents • Quick example • Fields ♦ Field name restrictions ♦ Field types ◊ AutoField ◊ BooleanField ◊ CharField ◊ DateField ◊ DateTimeField ◊ DecimalField ◊ EmailField ◊ FileField ◊ FilePathField ◊ FloatField ◊ ImageField ◊ IntegerField ◊ IPAddressField ◊ NullBooleanField ◊ PhoneNumberField ◊ PositiveIntegerField ◊ PositiveSmallIntegerField ◊ SlugField ◊ SmallIntegerField ◊ TextField ◊ TimeField ◊ URLField ◊ USStateField ◊ XMLField ♦ Field options ◊ null ◊ blank ◊ choices ◊ core ◊ db_column ◊ db_index ◊ db_tablespace ◊ default ◊ editable ◊ help_text ◊ primary_key Questions/Feedback 97
Slide 98: Django | Documentation ◊ radio_admin ◊ unique ◊ unique_for_date ◊ unique_for_month ◊ unique_for_year ◊ validator_list ♦ Verbose field names ♦ Relationships ◊ Many-to-one relationships ◊ Many-to-many relationships ◊ One-to-one relationships ♦ Custom field types ◊ db_type() • Meta options ♦ db_table ♦ db_tablespace ♦ get_latest_by ♦ order_with_respect_to ♦ ordering ♦ permissions ♦ unique_together ♦ verbose_name ♦ verbose_name_plural • Table names • Automatic primary key fields • Admin options ♦ date_hierarchy ♦ fields ◊ fields ◊ classes ◊ description ♦ js ♦ list_display ♦ list_display_links ♦ list_filter ♦ list_per_page ♦ list_select_related ♦ ordering ♦ save_as ♦ save_on_top ♦ search_fields • Managers ♦ Manager names ♦ Custom Managers ◊ Adding extra Manager methods ◊ Modifying initial Manager QuerySets • Model methods Contents 98
Slide 99: Django | Documentation ♦ __str__ ♦ __unicode__ ♦ get_absolute_url ◊ The permalink decorator ♦ Executing custom SQL ♦ Overriding default model methods • Models across files • Using models • Providing initial SQL data ♦ Database-backend-specific SQL data Last update: August 5, 12:14 a.m. © 2005-2007 Lawrence Journal-World unless otherwise noted. Django is a registered trademark of Lawrence Journal-World. Last update: 99
Slide 100: Django | Documentation • Home • Download • Documentation • Weblog • Community • Code Django documentation Database API reference This document is for Django's SVN release, which can be significantly different than previous releases. Get old docs here: 0.96, 0.95. Once you’ve created your data models, Django automatically gives you a database-abstraction API that lets you create, retrieve, update and delete objects. This document explains that API. Throughout this reference, we’ll refer to the following models, which comprise a weblog application: class Blog(models.Model): name = models.CharField(max_length=100) tagline = models.TextField() def __unicode__(self): return self.name class Author(models.Model): name = models.CharField(max_length=50) email = models.EmailField() def __unicode__(self): return self.name class Entry(models.Model): blog = models.ForeignKey(Blog) headline = models.CharField(max_length=255) body_text = models.TextField() pub_date = models.DateTimeField() authors = models.ManyToManyField(Author) def __unicode__(self): return self.headline Creating objects To represent database-table data in Python objects, Django uses an intuitive system: A model class represents a database table, and an instance of that class represents a particular record in the database table. Database API reference 100
Slide 101: Django | Documentation To create an object, instantiate it using keyword arguments to the model class, then call save() to save it to the database. You import the model class from wherever it lives on the Python path, as you may expect. (We point this out here because previous Django versions required funky model importing.) Assuming models live in a file mysite/blog/models.py, here’s an example: from mysite.blog.models import Blog b = Blog(name='Beatles Blog', tagline='All the latest Beatles news.') b.save() This performs an INSERT SQL statement behind the scenes. Django doesn’t hit the database until you explicitly call save(). The save() method has no return value. To create an object and save it all in one step see the create method. Auto-incrementing primary keys If a model has an AutoField — an auto-incrementing primary key — then that auto-incremented value will be calculated and saved as an attribute on your object the first time you call save(). Example: b2 = Blog(name='Cheddar Talk', tagline='Thoughts on cheese.') b2.id # Returns None, because b doesn't have an ID yet. b2.save() b2.id # Returns the ID of your new object. There’s no way to tell what the value of an ID will be before you call save(), because that value is calculated by your database, not by Django. (For convenience, each model has an AutoField named id by default unless you explicitly specify primary_key=True on a field. See the AutoField documentation.) Explicitly specifying auto-primary-key values If a model has an AutoField but you want to define a new object’s ID explicitly when saving, just define it explicitly before saving, rather than relying on the auto-assignment of the ID. Example: b3 = Blog(id=3, name='Cheddar Talk', tagline='Thoughts on cheese.') b3.id # Returns 3. b3.save() b3.id # Returns 3. If you assign auto-primary-key values manually, make sure not to use an already-existing primary-key value! If you create a new object with an explicit primary-key value that already exists in the database, Django will assume you’re changing the existing record rather than creating a new one. Creating objects 101
Slide 102: Django | Documentation Given the above 'Cheddar Talk' blog example, this example would override the previous record in the database: b4 = Blog(id=3, name='Not Cheddar', tagline='Anything but cheese.') b4.save() # Overrides the previous blog with ID=3! See How Django knows to UPDATE vs. INSERT, below, for the reason this happens. Explicitly specifying auto-primary-key values is mostly useful for bulk-saving objects, when you’re confident you won’t have primary-key collision. What happens when you save? When you save an object, Django performs the following steps: 1. Emit a ``pre_save`` signal. This provides a notification that an object is about to be saved. You can register a listener that will be invoked whenever this signal is emitted. (These signals are not yet documented.) 2. Pre-process the data. Each field on the object is asked to perform any automated data modification that the field may need to perform. Most fields do no pre-processing — the field data is kept as-is. Pre-processing is only used on fields that have special behavior. For example, if your model has a DateField with auto_now=True, the pre-save phase will alter the data in the object to ensure that the date field contains the current date stamp. (Our documentation doesn’t yet include a list of all the fields with this “special behavior.”) 3. Prepare the data for the database. Each field is asked to provide its current value in a data type that can be written to the database. Most fields require no data preparation. Simple data types, such as integers and strings, are ‘ready to write’ as a Python object. However, more complex data types often require some modification. For example, DateFields use a Python datetime object to store data. Databases don’t store datetime objects, so the field value must be converted into an ISO-compliant date string for insertion into the database. 4. Insert the data into the database. The pre-processed, prepared data is then composed into an SQL statement for insertion into the database. 5. Emit a ``post_save`` signal. As with the pre_save signal, this is used to provide notification that an object has been successfully saved. (These signals are not yet documented.) Raw Saves New in Django development version The pre-processing step (#2 in the previous section) is useful, but it modifies the data stored in a field. This can cause problems if you’re relying upon the data you provide being used as-is. For example, if you’re setting up conditions for a test, you’ll want the test conditions to be repeatable. If pre-processing is performed, the data used to specify test conditions may be modified, changing the conditions for the test each time the test is run. Auto-incrementing primary keys 102
Slide 103: Django | Documentation In cases such as this, you need to prevent pre-processing from being performed when you save an object. To do this, you can invoke a raw save by passing raw=True as an argument to the save() method: b4.save(raw=True) # Save object, but do no pre-processing A raw save skips the usual data pre-processing that is performed during the save. All other steps in the save (pre-save signal, data preparation, data insertion, and post-save signal) are performed as normal. When to use a raw save Generally speaking, you shouldn’t need to use a raw save. Disabling field pre-processing is an extraordinary measure that should only be required in extraordinary circumstances, such as setting up reliable test conditions. Saving changes to objects To save changes to an object that’s already in the database, use save(). Given a Blog instance b5 that has already been saved to the database, this example changes its name and updates its record in the database: b5.name = 'New name' b5.save() This performs an UPDATE SQL statement behind the scenes. Django doesn’t hit the database until you explicitly call save(). The save() method has no return value. Updating ForeignKey fields works exactly the same way; simply assign an object of the right type to the field in question: joe = Author.objects.create(name="Joe") entry.author = joe entry.save() Django will complain if you try to assign an object of the wrong type. How Django knows to UPDATE vs. INSERT You may have noticed Django database objects use the same save() method for creating and changing objects. Django abstracts the need to use INSERT or UPDATE SQL statements. Specifically, when you call save(), Django follows this algorithm: • If the object’s primary key attribute is set to a value that evaluates to True (i.e., a value other than None or the empty string), Django executes a SELECT query to determine whether a record with the given primary key already exists. • If the record with the given primary key does already exist, Django executes an UPDATE query. • If the object’s primary key attribute is not set, or if it’s set but a record doesn’t exist, Django executes an INSERT. What happens when you save? 103
Slide 104: Django | Documentation The one gotcha here is that you should be careful not to specify a primary-key value explicitly when saving new objects, if you cannot guarantee the primary-key value is unused. For more on this nuance, see “Explicitly specifying auto-primary-key values” above. Retrieving objects To retrieve objects from your database, you construct a QuerySet via a Manager on your model class. A QuerySet represents a collection of objects from your database. It can have zero, one or many filters — criteria that narrow down the collection based on given parameters. In SQL terms, a QuerySet equates to a SELECT statement, and a filter is a limiting clause such as WHERE or LIMIT. You get a QuerySet by using your model’s Manager. Each model has at least one Manager, and it’s called objects by default. Access it directly via the model class, like so: Blog.objects # <django.db.models.manager.Manager object at ...> b = Blog(name='Foo', tagline='Bar') b.objects # AttributeError: "Manager isn't accessible via Blog instances." (Managers are accessible only via model classes, rather than from model instances, to enforce a separation between “table-level” operations and “record-level” operations.) The Manager is the main source of QuerySets for a model. It acts as a “root” QuerySet that describes all objects in the model’s database table. For example, Blog.objects is the initial QuerySet that contains all Blog objects in the database. Retrieving all objects The simplest way to retrieve objects from a table is to get all of them. To do this, use the all() method on a Manager. Example: all_entries = Entry.objects.all() The all() method returns a QuerySet of all the objects in the database. (If Entry.objects is a QuerySet, why can’t we just do Entry.objects? That’s because Entry.objects, the root QuerySet, is a special case that cannot be evaluated. The all() method returns a QuerySet that can be evaluated.) Filtering objects The root QuerySet provided by the Manager describes all objects in the database table. Usually, though, you’ll need to select only a subset of the complete set of objects. To create such a subset, you refine the initial QuerySet, adding filter conditions. The two most common ways to refine a QuerySet are: filter(**kwargs) How Django knows to UPDATE vs. INSERT 104
Slide 105: Django | Documentation Returns a new QuerySet containing objects that match the given lookup parameters. exclude(**kwargs) Returns a new QuerySet containing objects that do not match the given lookup parameters. The lookup parameters (**kwargs in the above function definitions) should be in the format described in Field lookups below. For example, to get a QuerySet of blog entries from the year 2006, use filter() like so: Entry.objects.filter(pub_date__year=2006) (Note we don’t have to add an all() — Entry.objects.all().filter(...). That would still work, but you only need all() when you want all objects from the root QuerySet.) Chaining filters The result of refining a QuerySet is itself a QuerySet, so it’s possible to chain refinements together. For example: Entry.objects.filter( headline__startswith='What').exclude( pub_date__gte=datetime.now()).filter( pub_date__gte=datetime(2005, 1, 1)) …takes the initial QuerySet of all entries in the database, adds a filter, then an exclusion, then another filter. The final result is a QuerySet containing all entries with a headline that starts with “What”, that were published between January 1, 2005, and the current day. Filtered QuerySets are unique Each time you refine a QuerySet, you get a brand-new QuerySet that is in no way bound to the previous QuerySet. Each refinement creates a separate and distinct QuerySet that can be stored, used and reused. Example: q1 = Entry.objects.filter(headline__startswith="What") q2 = q1.exclude(pub_date__gte=datetime.now()) q3 = q1.filter(pub_date__gte=datetime.now()) These three QuerySets are separate. The first is a base QuerySet containing all entries that contain a headline starting with “What”. The second is a subset of the first, with an additional criteria that excludes records whose pub_date is greater than now. The third is a subset of the first, with an additional criteria that selects only the records whose pub_date is greater than now. The initial QuerySet (q1) is unaffected by the refinement process. QuerySets are lazy QuerySets are lazy — the act of creating a QuerySet doesn’t involve any database activity. You can stack filters together all day long, and Django won’t actually run the query until the QuerySet is evaluated. Filtering objects 105
Slide 106: Django | Documentation When QuerySets are evaluated You can evaluate a QuerySet in the following ways: • Iteration. A QuerySet is iterable, and it executes its database query the first time you iterate over it. For example, this will print the headline of all entries in the database: for e in Entry.objects.all(): print e.headline • Slicing. As explained in Limiting QuerySets below, a QuerySet can be sliced, using Python’s array-slicing syntax. Usually slicing a QuerySet returns another (unevaluated )``QuerySet``, but Django will execute the database query if you use the “step” parameter of slice syntax. • repr(). A QuerySet is evaluated when you call repr() on it. This is for convenience in the Python interactive interpreter, so you can immediately see your results when using the API interactively. • len(). A QuerySet is evaluated when you call len() on it. This, as you might expect, returns the length of the result list. Note: Don’t use len() on QuerySets if all you want to do is determine the number of records in the set. It’s much more efficient to handle a count at the database level, using SQL’s SELECT COUNT(*), and Django provides a count() method for precisely this reason. See count() below. • list(). Force evaluation of a QuerySet by calling list() on it. For example: entry_list = list(Entry.objects.all()) Be warned, though, that this could have a large memory overhead, because Django will load each element of the list into memory. In contrast, iterating over a QuerySet will take advantage of your database to load data and instantiate objects only as you need them. Limiting QuerySets Use Python’s array-slicing syntax to limit your QuerySet to a certain number of results. This is the equivalent of SQL’s LIMIT and OFFSET clauses. For example, this returns the first 5 objects (LIMIT 5): Entry.objects.all()[:5] This returns the sixth through tenth objects (OFFSET 5 LIMIT 5): Entry.objects.all()[5:10] Generally, slicing a QuerySet returns a new QuerySet — it doesn’t evaluate the query. An exception is if you use the “step” parameter of Python slice syntax. For example, this would actually execute the query in order to return a list of every second object of the first 10: Entry.objects.all()[:10:2] To retrieve a single object rather than a list (e.g. SELECT foo FROM bar LIMIT 1), use a simple index instead of a slice. For example, this returns the first Entry in the database, after ordering entries QuerySets are lazy 106
Slide 107: Django | Documentation alphabetically by headline: Entry.objects.order_by('headline')[0] This is roughly equivalent to: Entry.objects.order_by('headline')[0:1].get() Note, however, that the first of these will raise IndexError while the second will raise DoesNotExist if no objects match the given criteria. QuerySet methods that return new QuerySets Django provides a range of QuerySet refinement methods that modify either the types of results returned by the QuerySet or the way its SQL query is executed. filter(**kwargs) Returns a new QuerySet containing objects that match the given lookup parameters. The lookup parameters (**kwargs) should be in the format described in Field lookups below. Multiple parameters are joined via AND in the underlying SQL statement. exclude(**kwargs) Returns a new QuerySet containing objects that do not match the given lookup parameters. The lookup parameters (**kwargs) should be in the format described in Field lookups below. Multiple parameters are joined via AND in the underlying SQL statement, and the whole thing is enclosed in a NOT(). This example excludes all entries whose pub_date is later than 2005-1-3 AND whose headline is “Hello”: Entry.objects.exclude(pub_date__gt=datetime.date(2005, 1, 3), headline='Hello') In SQL terms, that evaluates to: SELECT ... WHERE NOT (pub_date > '2005-1-3' AND headline = 'Hello') This example excludes all entries whose pub_date is later than 2005-1-3 AND whose headline is NOT “Hello”: Entry.objects.exclude(pub_date__gt=datetime.date(2005, 1, 3)).exclude(headline='Hello') In SQL terms, that evaluates to: SELECT ... WHERE NOT pub_date > '2005-1-3' AND NOT headline = 'Hello' Note the second example is more restrictive. Limiting QuerySets 107
Slide 108: Django | Documentation order_by(*fields) By default, results returned by a QuerySet are ordered by the ordering tuple given by the ordering option in the model’s Meta. You can override this on a per-QuerySet basis by using the order_by method. Example: Entry.objects.filter(pub_date__year=2005).order_by('-pub_date', 'headline') The result above will be ordered by pub_date descending, then by headline ascending. The negative sign in front of "-pub_date" indicates descending order. Ascending order is implied. To order randomly, use "?", like so: Entry.objects.order_by('?') To order by a field in a different table, add the other table’s name and a dot, like so: Entry.objects.order_by('blogs_blog.name', 'headline') There’s no way to specify whether ordering should be case sensitive. With respect to case-sensitivity, Django will order results however your database backend normally orders them. distinct() Returns a new QuerySet that uses SELECT DISTINCT in its SQL query. This eliminates duplicate rows from the query results. By default, a QuerySet will not eliminate duplicate rows. In practice, this is rarely a problem, because simple queries such as Blog.objects.all() don’t introduce the possibility of duplicate result rows. However, if your query spans multiple tables, it’s possible to get duplicate results when a QuerySet is evaluated. That’s when you’d use distinct(). values(*fields) Returns a ValuesQuerySet — a QuerySet that evaluates to a list of dictionaries instead of model-instance objects. Each of those dictionaries represents an object, with the keys corresponding to the attribute names of model objects. This example compares the dictionaries of values() with the normal model objects: # This list contains a Blog object. >>> Blog.objects.filter(name__startswith='Beatles') [Beatles Blog] # This list contains a dictionary. >>> Blog.objects.filter(name__startswith='Beatles').values() [{'id': 1, 'name': 'Beatles Blog', 'tagline': 'All the latest Beatles news.'}] QuerySet methods that return new QuerySets 108
Slide 109: Django | Documentation values() takes optional positional arguments, *fields, which specify field names to which the SELECT should be limited. If you specify the fields, each dictionary will contain only the field keys/values for the fields you specify. If you don’t specify the fields, each dictionary will contain a key and value for every field in the database table. Example: >>> Blog.objects.values() [{'id': 1, 'name': 'Beatles Blog', 'tagline': 'All the latest Beatles news.'}], >>> Blog.objects.values('id', 'name') [{'id': 1, 'name': 'Beatles Blog'}] A ValuesQuerySet is useful when you know you’re only going to need values from a small number of the available fields and you won’t need the functionality of a model instance object. It’s more efficient to select only the fields you need to use. Finally, note a ValuesQuerySet is a subclass of QuerySet, so it has all methods of QuerySet. You can call filter() on it, or order_by(), or whatever. Yes, that means these two calls are identical: Blog.objects.values().order_by('id') Blog.objects.order_by('id').values() The people who made Django prefer to put all the SQL-affecting methods first, followed (optionally) by any output-affecting methods (such as values()), but it doesn’t really matter. This is your chance to really flaunt your individualism. dates(field, kind, order='ASC') Returns a DateQuerySet — a QuerySet that evaluates to a list of datetime.datetime objects representing all available dates of a particular kind within the contents of the QuerySet. field should be the name of a DateField or DateTimeField of your model. kind should be either "year", "month" or "day". Each datetime.datetime object in the result list is “truncated” to the given type. • "year" returns a list of all distinct year values for the field. • "month" returns a list of all distinct year/month values for the field. • "day" returns a list of all distinct year/month/day values for the field. order, which defaults to 'ASC', should be either 'ASC' or 'DESC'. This specifies how to order the results. Examples: >>> Entry.objects.dates('pub_date', 'year') [datetime.datetime(2005, 1, 1)] >>> Entry.objects.dates('pub_date', 'month') [datetime.datetime(2005, 2, 1), datetime.datetime(2005, 3, 1)] >>> Entry.objects.dates('pub_date', 'day') [datetime.datetime(2005, 2, 20), datetime.datetime(2005, 3, 20)] >>> Entry.objects.dates('pub_date', 'day', order='DESC') [datetime.datetime(2005, 3, 20), datetime.datetime(2005, 2, 20)] QuerySet methods that return new QuerySets 109
Slide 110: Django | Documentation >>> Entry.objects.filter(headline__contains='Lennon').dates('pub_date', 'day') [datetime.datetime(2005, 3, 20)] none() New in Django development version Returns an EmptyQuerySet — a QuerySet that always evaluates to an empty list. This can be used in cases where you know that you should return an empty result set and your caller is expecting a QuerySet object (instead of returning an empty list, for example.) Examples: >>> Entry.objects.none() [] select_related() Returns a QuerySet that will automatically “follow” foreign-key relationships, selecting that additional related-object data when it executes its query. This is a performance booster which results in (sometimes much) larger queries but means later use of foreign-key relationships won’t require database queries. The following examples illustrate the difference between plain lookups and select_related() lookups. Here’s standard lookup: # Hits the database. e = Entry.objects.get(id=5) # Hits the database again to get the related Blog object. b = e.blog And here’s select_related lookup: # Hits the database. e = Entry.objects.select_related().get(id=5) # Doesn't hit the database, because e.blog has been prepopulated # in the previous query. b = e.blog select_related() follows foreign keys as far as possible. If you have the following models: class City(models.Model): # ... class Person(models.Model): # ... hometown = models.ForeignKey(City) class Book(models.Model): # ... author = models.ForeignKey(Person) …then a call to Book.objects.select_related().get(id=4) will cache the related Person and the related City: QuerySet methods that return new QuerySets 110
Slide 111: Django | Documentation b = Book.objects.select_related().get(id=4) p = b.author # Doesn't hit the database. c = p.hometown # Doesn't hit the database. b = Book.objects.get(id=4) # No select_related() in this example. p = b.author # Hits the database. c = p.hometown # Hits the database. Note that select_related() does not follow foreign keys that have null=True. Usually, using select_related() can vastly improve performance because your app can avoid many database calls. However, in situations with deeply nested sets of relationships select_related() can sometimes end up following “too many” relations, and can generate queries so large that they end up being slow. In these situations, you can use the depth argument to select_related() to control how many “levels” of relations select_related() will actually follow: b = Book.objects.select_related(depth=1).get(id=4) p = b.author # Doesn't hit the database. c = p.hometown # Requires a database call. The depth argument is new in the Django development version. extra(select=None, where=None, params=None, tables=None) Sometimes, the Django query syntax by itself can’t easily express a complex WHERE clause. For these edge cases, Django provides the extra() QuerySet modifier — a hook for injecting specific clauses into the SQL generated by a QuerySet. By definition, these extra lookups may not be portable to different database engines (because you’re explicitly writing SQL code) and violate the DRY principle, so you should avoid them if possible. Specify one or more of params, select, where or tables. None of the arguments is required, but you should use at least one of them. select The select argument lets you put extra fields in the SELECT clause. It should be a dictionary mapping attribute names to SQL clauses to use to calculate that attribute. Example: Entry.objects.extra(select={'is_recent': "pub_date > '2006-01-01'"}) As a result, each Entry object will have an extra attribute, is_recent, a boolean representing whether the entry’s pub_date is greater than Jan. 1, 2006. Django inserts the given SQL snippet directly into the SELECT statement, so the resulting SQL of the above example would be: SELECT blog_entry.*, (pub_date > '2006-01-01') FROM blog_entry; QuerySet methods that return new QuerySets 111
Slide 112: Django | Documentation The next example is more advanced; it does a subquery to give each resulting Blog object an entry_count attribute, an integer count of associated Entry objects: Blog.objects.extra( select={ 'entry_count': 'SELECT COUNT(*) FROM blog_entry WHERE blog_entry.blog_id = blog_b }, ) (In this particular case, we’re exploiting the fact that the query will already contain the blog_blog table in its FROM clause.) The resulting SQL of the above example would be: SELECT blog_blog.*, (SELECT COUNT(*) FROM blog_entry WHERE blog_entry.blog_id = blog_blog FROM blog_blog; Note that the parenthesis required by most database engines around subqueries are not required in Django’s select clauses. Also note that some database backends, such as some MySQL versions, don’t support subqueries. where / tables You can define explicit SQL WHERE clauses — perhaps to perform non-explicit joins — by using where. You can manually add tables to the SQL FROM clause by using tables. where and tables both take a list of strings. All where parameters are “AND”ed to any other search criteria. Example: Entry.objects.extra(where=['id IN (3, 4, 5, 20)']) …translates (roughly) into the following SQL: SELECT * FROM blog_entry WHERE id IN (3, 4, 5, 20); params The select and where parameters described above may use standard Python database string placeholders — '%s' to indicate parameters the database engine should automatically quote. The params argument is a list of any extra parameters to be substituted. Example: Entry.objects.extra(where=['headline=%s'], params=['Lennon']) Always use params instead of embedding values directly into select or where because params will ensure values are quoted correctly according to your particular backend. (For example, quotes will be escaped correctly.) Bad: Entry.objects.extra(where=["headline='Lennon'"]) Good: QuerySet methods that return new QuerySets 112
Slide 113: Django | Documentation Entry.objects.extra(where=['headline=%s'], params=['Lennon']) QuerySet methods that do not return QuerySets The following QuerySet methods evaluate the QuerySet and return something other than a QuerySet. These methods do not use a cache (see Caching and QuerySets below). Rather, they query the database each time they’re called. get(**kwargs) Returns the object matching the given lookup parameters, which should be in the format described in Field lookups. get() raises AssertionError if more than one object was found. get() raises a DoesNotExist exception if an object wasn’t found for the given parameters. The DoesNotExist exception is an attribute of the model class. Example: Entry.objects.get(id='foo') # raises Entry.DoesNotExist The DoesNotExist exception inherits from django.core.exceptions.ObjectDoesNotExist, so you can target multiple DoesNotExist exceptions. Example: from django.core.exceptions import ObjectDoesNotExist try: e = Entry.objects.get(id=3) b = Blog.objects.get(id=1) except ObjectDoesNotExist: print "Either the entry or blog doesn't exist." create(**kwargs) A convenience method for creating an object and saving it all in one step. Thus: p = Person.objects.create(first_name="Bruce", last_name="Springsteen") and: p = Person(first_name="Bruce", last_name="Springsteen") p.save() are equivalent. get_or_create(**kwargs) A convenience method for looking up an object with the given kwargs, creating one if necessary. Returns a tuple of (object, created), where object is the retrieved or created object and created is a boolean specifying whether a new object was created. This is meant as a shortcut to boilerplatish code and is mostly useful for data-import scripts. For example: QuerySet methods that do not return QuerySets 113
Slide 114: Django | Documentation try: obj = Person.objects.get(first_name='John', last_name='Lennon') except Person.DoesNotExist: obj = Person(first_name='John', last_name='Lennon', birthday=date(1940, 10, 9)) obj.save() This pattern gets quite unwieldy as the number of fields in a model goes up. The above example can be rewritten using get_or_create() like so: obj, created = Person.objects.get_or_create(first_name='John', last_name='Lennon', defaults={'birthday': date(1940, 10, 9)}) Any keyword arguments passed to get_or_create() — except an optional one called defaults — will be used in a get() call. If an object is found, get_or_create() returns a tuple of that object and False. If an object is not found, get_or_create() will instantiate and save a new object, returning a tuple of the new object and True. The new object will be created according to this algorithm: defaults = kwargs.pop('defaults', {}) params = dict([(k, v) for k, v in kwargs.items() if '__' not in k]) params.update(defaults) obj = self.model(**params) obj.save() In English, that means start with any non-'defaults' keyword argument that doesn’t contain a double underscore (which would indicate a non-exact lookup). Then add the contents of defaults, overriding any keys if necessary, and use the result as the keyword arguments to the model class. If you have a field named defaults and want to use it as an exact lookup in get_or_create(), just use 'defaults__exact', like so: Foo.objects.get_or_create(defaults__exact='bar', defaults={'defaults': 'baz'}) Finally, a word on using get_or_create() in Django views. As mentioned earlier, get_or_create() is mostly useful in scripts that need to parse data and create new records if existing ones aren’t available. But if you need to use get_or_create() in a view, please make sure to use it only in POST requests unless you have a good reason not to. GET requests shouldn’t have any effect on data; use POST whenever a request to a page has a side effect on your data. For more, see Safe methods in the HTTP spec. count() Returns an integer representing the number of objects in the database matching the QuerySet. count() never raises exceptions. Example: # Returns the total number of entries in the database. Entry.objects.count() # Returns the number of entries whose headline contains 'Lennon' Entry.objects.filter(headline__contains='Lennon').count() count() performs a SELECT COUNT(*) behind the scenes, so you should always use count() rather than loading all of the record into Python objects and calling len() on the result. QuerySet methods that do not return QuerySets 114
Slide 115: Django | Documentation Depending on which database you’re using (e.g. PostgreSQL vs. MySQL), count() may return a long integer instead of a normal Python integer. This is an underlying implementation quirk that shouldn’t pose any real-world problems. in_bulk(id_list) Takes a list of primary-key values and returns a dictionary mapping each primary-key value to an instance of the object with the given ID. Example: >>> {1: >>> {1: >>> {} Blog.objects.in_bulk([1]) Beatles Blog} Blog.objects.in_bulk([1, 2]) Beatles Blog, 2: Cheddar Talk} Blog.objects.in_bulk([]) If you pass in_bulk() an empty list, you’ll get an empty dictionary. latest(field_name=None) Returns the latest object in the table, by date, using the field_name provided as the date field. This example returns the latest Entry in the table, according to the pub_date field: Entry.objects.latest('pub_date') If your model’s Meta specifies get_latest_by, you can leave off the field_name argument to latest(). Django will use the field specified in get_latest_by by default. Like get(), latest() raises DoesNotExist if an object doesn’t exist with the given parameters. Note latest() exists purely for convenience and readability. Field lookups Field lookups are how you specify the meat of an SQL WHERE clause. They’re specified as keyword arguments to the QuerySet methods filter(), exclude() and get(). Basic lookups keyword arguments take the form field__lookuptype=value. (That’s a double-underscore). For example: Entry.objects.filter(pub_date__lte='2006-01-01') translates (roughly) into the following SQL: SELECT * FROM blog_entry WHERE pub_date <= '2006-01-01'; How this is possible QuerySet methods that do not return QuerySets 115
Slide 116: Django | Documentation Python has the ability to define functions that accept arbitrary name-value arguments whose names and values are evaluated at runtime. For more information, see Keyword Arguments in the official Python tutorial. If you pass an invalid keyword argument, a lookup function will raise TypeError. The database API supports the following lookup types: exact Exact match. If the value provided for comparison is None, it will be interpreted as an SQL NULL (See isnull for more details). Examples: Entry.objects.get(id__exact=14) Entry.objects.get(id__exact=None) SQL equivalents: SELECT ... WHERE id = 14; SELECT ... WHERE id = NULL; iexact Case-insensitive exact match. Example: Blog.objects.get(name__iexact='beatles blog') SQL equivalent: SELECT ... WHERE name ILIKE 'beatles blog'; Note this will match 'Beatles Blog', 'beatles blog', 'BeAtLes BLoG', etc. contains Case-sensitive containment test. Example: Entry.objects.get(headline__contains='Lennon') SQL equivalent: SELECT ... WHERE headline LIKE '%Lennon%'; Note this will match the headline 'Today Lennon honored' but not 'today lennon honored'. SQLite doesn’t support case-sensitive LIKE statements; contains acts like icontains for SQLite. Field lookups 116
Slide 117: Django | Documentation icontains Case-insensitive containment test. Example: Entry.objects.get(headline__icontains='Lennon') SQL equivalent: SELECT ... WHERE headline ILIKE '%Lennon%'; gt Greater than. Example: Entry.objects.filter(id__gt=4) SQL equivalent: SELECT ... WHERE id > 4; gte Greater than or equal to. lt Less than. lte Less than or equal to. in In a given list. Example: Entry.objects.filter(id__in=[1, 3, 4]) SQL equivalent: SELECT ... WHERE id IN (1, 3, 4); startswith Case-sensitive starts-with. Field lookups 117
Slide 118: Django | Documentation Example: Entry.objects.filter(headline__startswith='Will') SQL equivalent: SELECT ... WHERE headline LIKE 'Will%'; SQLite doesn’t support case-sensitive LIKE statements; startswith acts like istartswith for SQLite. istartswith Case-insensitive starts-with. Example: Entry.objects.filter(headline__istartswith='will') SQL equivalent: SELECT ... WHERE headline ILIKE 'Will%'; endswith Case-sensitive ends-with. Example: Entry.objects.filter(headline__endswith='cats') SQL equivalent: SELECT ... WHERE headline LIKE '%cats'; SQLite doesn’t support case-sensitive LIKE statements; endswith acts like iendswith for SQLite. iendswith Case-insensitive ends-with. Example: Entry.objects.filter(headline__iendswith='will') SQL equivalent: SELECT ... WHERE headline ILIKE '%will' range Range test (inclusive). Field lookups 118
Slide 119: Django | Documentation Example: start_date = datetime.date(2005, 1, 1) end_date = datetime.date(2005, 3, 31) Entry.objects.filter(pub_date__range=(start_date, end_date)) SQL equivalent: SELECT ... WHERE pub_date BETWEEN '2005-01-01' and '2005-03-31'; You can use range anywhere you can use BETWEEN in SQL — for dates, numbers and even characters. year For date/datetime fields, exact year match. Takes a four-digit year. Example: Entry.objects.filter(pub_date__year=2005) SQL equivalent: SELECT ... WHERE EXTRACT('year' FROM pub_date) = '2005'; (The exact SQL syntax varies for each database engine.) month For date/datetime fields, exact month match. Takes an integer 1 (January) through 12 (December). Example: Entry.objects.filter(pub_date__month=12) SQL equivalent: SELECT ... WHERE EXTRACT('month' FROM pub_date) = '12'; (The exact SQL syntax varies for each database engine.) day For date/datetime fields, exact day match. Example: Entry.objects.filter(pub_date__day=3) SQL equivalent: SELECT ... WHERE EXTRACT('day' FROM pub_date) = '3'; Field lookups 119
Slide 120: Django | Documentation (The exact SQL syntax varies for each database engine.) Note this will match any record with a pub_date on the third day of the month, such as January 3, July 3, etc. isnull Takes either True or False, which correspond to SQL queries of IS NULL and IS NOT NULL, respectively. Example: Entry.objects.filter(pub_date__isnull=True) SQL equivalent: SELECT ... WHERE pub_date IS NULL; __isnull=True vs __exact=None There is an important difference between __isnull=True and __exact=None. __exact=None will always return an empty result set, because SQL requires that no value is equal to NULL. __isnull determines if the field is currently holding the value of NULL without performing a comparison. search A boolean full-text search, taking advantage of full-text indexing. This is like contains but is significantly faster due to full-text indexing. Note this is only available in MySQL and requires direct manipulation of the database to add the full-text index. regex New in Django development version Case-sensitive regular expression match. The regular expression syntax is that of the database backend in use. In the case of SQLite, which doesn’t natively support regular-expression lookups, the syntax is that of Python’s re module. Example: Entry.objects.get(title__regex=r'^(An?|The) +') SQL equivalents: SELECT ... WHERE title REGEXP BINARY '^(An?|The) +'; -- MySQL SELECT ... WHERE REGEXP_LIKE(title, '^(an?|the) +', 'c'); -- Oracle SELECT ... WHERE title ~ '^(An?|The) +'; -- PostgreSQL Field lookups 120
Slide 121: Django | Documentation SELECT ... WHERE title REGEXP '^(An?|The) +'; -- SQLite Using raw strings (e.g., r'foo' instead of 'foo') for passing in the regular expression syntax is recommended. Regular expression matching is not supported on the ado_mssql backend. It will raise a NotImplementedError at runtime. iregex New in Django development version Case-insensitive regular expression match. Example: Entry.objects.get(title__iregex=r'^(an?|the) +') SQL equivalents: SELECT ... WHERE title REGEXP '^(an?|the) +'; -- MySQL SELECT ... WHERE REGEXP_LIKE(title, '^(an?|the) +', 'i'); -- Oracle SELECT ... WHERE title ~* '^(an?|the) +'; -- PostgreSQL SELECT ... WHERE title REGEXP '(?i)^(an?|the) +'; -- SQLite Default lookups are exact If you don’t provide a lookup type — that is, if your keyword argument doesn’t contain a double underscore — the lookup type is assumed to be exact. For example, the following two statements are equivalent: Blog.objects.get(id__exact=14) # Explicit form Blog.objects.get(id=14) # __exact is implied This is for convenience, because exact lookups are the common case. The pk lookup shortcut For convenience, Django provides a pk lookup type, which stands for “primary_key”. In the example Blog model, the primary key is the id field, so these three statements are equivalent: Blog.objects.get(id__exact=14) # Explicit form Blog.objects.get(id=14) # __exact is implied Blog.objects.get(pk=14) # pk implies id__exact The use of pk isn’t limited to __exact queries — any query term can be combined with pk to perform a query on the primary key of a model: Field lookups 121
Slide 122: Django | Documentation # Get blogs entries with id 1, 4 and 7 Blog.objects.filter(pk__in=[1,4,7]) # Get all blog entries with id > 14 Blog.objects.filter(pk__gt=14) pk lookups also work across joins. For example, these three statements are equivalent: Entry.objects.filter(blog__id__exact=3) # Explicit form Entry.objects.filter(blog__id=3) # __exact is implied Entry.objects.filter(blog__pk=3) # __pk implies __id__exact Lookups that span relationships Django offers a powerful and intuitive way to “follow” relationships in lookups, taking care of the SQL JOINs for you automatically, behind the scenes. To span a relationship, just use the field name of related fields across models, separated by double underscores, until you get to the field you want. This example retrieves all Entry objects with a Blog whose name is 'Beatles Blog': Entry.objects.filter(blog__name__exact='Beatles Blog') This spanning can be as deep as you’d like. It works backwards, too. To refer to a “reverse” relationship, just use the lowercase name of the model. This example retrieves all Blog objects which have at least one Entry whose headline contains 'Lennon': Blog.objects.filter(entry__headline__contains='Lennon') Escaping percent signs and underscores in LIKE statements The field lookups that equate to LIKE SQL statements (iexact, contains, icontains, startswith, istartswith, endswith and iendswith) will automatically escape the two special characters used in LIKE statements — the percent sign and the underscore. (In a LIKE statement, the percent sign signifies a multiple-character wildcard and the underscore signifies a single-character wildcard.) This means things should work intuitively, so the abstraction doesn’t leak. For example, to retrieve all the entries that contain a percent sign, just use the percent sign as any other character: Entry.objects.filter(headline__contains='%') Django takes care of the quoting for you; the resulting SQL will look something like this: SELECT ... WHERE headline LIKE '%\%%'; Same goes for underscores. Both percentage signs and underscores are handled for you transparently. Caching and QuerySets Each QuerySet contains a cache, to minimize database access. It’s important to understand how it works, in order to write the most efficient code. The pk lookup shortcut 122
Slide 123: Django | Documentation In a newly created QuerySet, the cache is empty. The first time a QuerySet is evaluated — and, hence, a database query happens — Django saves the query results in the QuerySet‘s cache and returns the results that have been explicitly requested (e.g., the next element, if the QuerySet is being iterated over). Subsequent evaluations of the QuerySet reuse the cached results. Keep this caching behavior in mind, because it may bite you if you don’t use your QuerySets correctly. For example, the following will create two QuerySets, evaluate them, and throw them away: print [e.headline for e in Entry.objects.all()] print [e.pub_date for e in Entry.objects.all()] That means the same database query will be executed twice, effectively doubling your database load. Also, there’s a possibility the two lists may not include the same database records, because an Entry may have been added or deleted in the split second between the two requests. To avoid this problem, simply save the QuerySet and reuse it: queryset = Poll.objects.all() print [p.headline for p in queryset] # Evaluate the query set. print [p.pub_date for p in queryset] # Re-use the cache from the evaluation. Comparing objects To compare two model instances, just use the standard Python comparison operator, the double equals sign: ==. Behind the scenes, that compares the primary key values of two models. Using the Entry example above, the following two statements are equivalent: some_entry == other_entry some_entry.id == other_entry.id If a model’s primary key isn’t called id, no problem. Comparisons will always use the primary key, whatever it’s called. For example, if a model’s primary key field is called name, these two statements are equivalent: some_obj == other_obj some_obj.name == other_obj.name Complex lookups with Q objects Keyword argument queries — in filter(), etc. — are “AND”ed together. If you need to execute more complex queries (for example, queries with OR statements), you can use Q objects. A Q object (django.db.models.Q) is an object used to encapsulate a collection of keyword arguments. These keyword arguments are specified as in “Field lookups” above. For example, this Q object encapsulates a single LIKE query: Q(question__startswith='What') Q objects can be combined using the & and | operators. When an operator is used on two Q objects, it yields a new Q object. Caching and QuerySets 123
Slide 124: Django | Documentation For example, this statement yields a single Q object that represents the “OR” of two "question__startswith" queries: Q(question__startswith='Who') | Q(question__startswith='What') This is equivalent to the following SQL WHERE clause: WHERE question LIKE 'Who%' OR question LIKE 'What%' You can compose statements of arbitrary complexity by combining Q objects with the & and | operators. You can also use parenthetical grouping. Each lookup function that takes keyword-arguments (e.g. filter(), exclude(), get()) can also be passed one or more Q objects as positional (not-named) arguments. If you provide multiple Q object arguments to a lookup function, the arguments will be “AND”ed together. For example: Poll.objects.get( Q(question__startswith='Who'), Q(pub_date=date(2005, 5, 2)) | Q(pub_date=date(2005, 5, 6)) ) … roughly translates into the SQL: SELECT * from polls WHERE question LIKE 'Who%' AND (pub_date = '2005-05-02' OR pub_date = '2005-05-06') Lookup functions can mix the use of Q objects and keyword arguments. All arguments provided to a lookup function (be they keyword arguments or Q objects) are “AND”ed together. However, if a Q object is provided, it must precede the definition of any keyword arguments. For example: Poll.objects.get( Q(pub_date=date(2005, 5, 2)) | Q(pub_date=date(2005, 5, 6)), question__startswith='Who') … would be a valid query, equivalent to the previous example; but: # INVALID QUERY Poll.objects.get( question__startswith='Who', Q(pub_date=date(2005, 5, 2)) | Q(pub_date=date(2005, 5, 6))) … would not be valid. See the OR lookups examples page for more examples. Related objects When you define a relationship in a model (i.e., a ForeignKey, OneToOneField, or ManyToManyField), instances of that model will have a convenient API to access the related object(s). Using the models at the top of this page, for example, an Entry object e can get its associated Blog object by accessing the blog attribute: e.blog. Complex lookups with Q objects 124
Slide 125: Django | Documentation (Behind the scenes, this functionality is implemented by Python descriptors. This shouldn’t really matter to you, but we point it out here for the curious.) Django also creates API accessors for the “other” side of the relationship — the link from the related model to the model that defines the relationship. For example, a Blog object b has access to a list of all related Entry objects via the entry_set attribute: b.entry_set.all(). All examples in this section use the sample Blog, Author and Entry models defined at the top of this page. One-to-many relationships Forward If a model has a ForeignKey, instances of that model will have access to the related (foreign) object via a simple attribute of the model. Example: e = Entry.objects.get(id=2) e.blog # Returns the related Blog object. You can get and set via a foreign-key attribute. As you may expect, changes to the foreign key aren’t saved to the database until you call save(). Example: e = Entry.objects.get(id=2) e.blog = some_blog e.save() If a ForeignKey field has null=True set (i.e., it allows NULL values), you can assign None to it. Example: e = Entry.objects.get(id=2) e.blog = None e.save() # "UPDATE blog_entry SET blog_id = NULL ...;" Forward access to one-to-many relationships is cached the first time the related object is accessed. Subsequent accesses to the foreign key on the same object instance are cached. Example: e = Entry.objects.get(id=2) print e.blog # Hits the database to retrieve the associated Blog. print e.blog # Doesn't hit the database; uses cached version. Note that the select_related() QuerySet method recursively prepopulates the cache of all one-to-many relationships ahead of time. Example: e = Entry.objects.select_related().get(id=2) print e.blog # Doesn't hit the database; uses cached version. print e.blog # Doesn't hit the database; uses cached version. select_related() is documented in the “QuerySet methods that return new QuerySets” section above. Related objects 125
Slide 126: Django | Documentation Backward If a model has a ForeignKey, instances of the foreign-key model will have access to a Manager that returns all instances of the first model. By default, this Manager is named FOO_set, where FOO is the source model name, lowercased. This Manager returns QuerySets, which can be filtered and manipulated as described in the “Retrieving objects” section above. Example: b = Blog.objects.get(id=1) b.entry_set.all() # Returns all Entry objects related to Blog. # b.entry_set is a Manager that returns QuerySets. b.entry_set.filter(headline__contains='Lennon') b.entry_set.count() You can override the FOO_set name by setting the related_name parameter in the ForeignKey() definition. For example, if the Entry model was altered to blog = ForeignKey(Blog, related_name='entries'), the above example code would look like this: b = Blog.objects.get(id=1) b.entries.all() # Returns all Entry objects related to Blog. # b.entries is a Manager that returns QuerySets. b.entries.filter(headline__contains='Lennon') b.entries.count() You cannot access a reverse ForeignKey Manager from the class; it must be accessed from an instance. Example: Blog.entry_set # Raises AttributeError: "Manager must be accessed via instance". In addition to the QuerySet methods defined in “Retrieving objects” above, the ForeignKey Manager has these additional methods: • add(obj1, obj2, ...): Adds the specified model objects to the related object set. Example: b = Blog.objects.get(id=1) e = Entry.objects.get(id=234) b.entry_set.add(e) # Associates Entry e with Blog b. • create(**kwargs): Creates a new object, saves it and puts it in the related object set. Returns the newly created object. Example: b = Blog.objects.get(id=1) e = b.entry_set.create(headline='Hello', body_text='Hi', pub_date=datetime.date(2005, 1, # No need to call e.save() at this point -- it's already been saved. This is equivalent to (but much simpler than): b = Blog.objects.get(id=1) One-to-many relationships 126
Slide 127: Django | Documentation e = Entry(blog=b, headline='Hello', body_text='Hi', pub_date=datetime.date(2005, 1, 1)) e.save() Note that there’s no need to specify the keyword argument of the model that defines the relationship. In the above example, we don’t pass the parameter blog to create(). Django figures out that the new Entry object’s blog field should be set to b. • remove(obj1, obj2, ...): Removes the specified model objects from the related object set. Example: b = Blog.objects.get(id=1) e = Entry.objects.get(id=234) b.entry_set.remove(e) # Disassociates Entry e from Blog b. In order to prevent database inconsistency, this method only exists on ForeignKey objects where null=True. If the related field can’t be set to None (NULL), then an object can’t be removed from a relation without being added to another. In the above example, removing e from b.entry_set() is equivalent to doing e.blog = None, and because the blog ForeignKey doesn’t have null=True, this is invalid. • clear(): Removes all objects from the related object set. Example: b = Blog.objects.get(id=1) b.entry_set.clear() Note this doesn’t delete the related objects — it just disassociates them. Just like remove(), clear() is only available on ForeignKey``s where ``null=True. To assign the members of a related set in one fell swoop, just assign to it from any iterable object. Example: b = Blog.objects.get(id=1) b.entry_set = [e1, e2] If the clear() method is available, any pre-existing objects will be removed from the entry_set before all objects in the iterable (in this case, a list) are added to the set. If the clear() method is not available, all objects in the iterable will be added without removing any existing elements. Each “reverse” operation described in this section has an immediate effect on the database. Every addition, creation and deletion is immediately and automatically saved to the database. Many-to-many relationships Both ends of a many-to-many relationship get automatic API access to the other end. The API works just as a “backward” one-to-many relationship. See Backward above. The only difference is in the attribute naming: The model that defines the ManyToManyField uses the attribute name of that field itself, whereas the “reverse” model uses the lowercased model name of the original model, plus '_set' (just like reverse one-to-many relationships). An example makes this easier to understand: Many-to-many relationships 127
Slide 128: Django | Documentation e = Entry.objects.get(id=3) e.authors.all() # Returns all Author objects for this Entry. e.authors.count() e.authors.filter(name__contains='John') a = Author.objects.get(id=5) a.entry_set.all() # Returns all Entry objects for this Author. Like ForeignKey, ManyToManyField can specify related_name. In the above example, if the ManyToManyField in Entry had specified related_name='entries', then each Author instance would have an entries attribute instead of entry_set. One-to-one relationships The semantics of one-to-one relationships will be changing soon, so we don’t recommend you use them. How are the backward relationships possible? Other object-relational mappers require you to define relationships on both sides. The Django developers believe this is a violation of the DRY (Don’t Repeat Yourself) principle, so Django only requires you to define the relationship on one end. But how is this possible, given that a model class doesn’t know which other model classes are related to it until those other model classes are loaded? The answer lies in the INSTALLED_APPS setting. The first time any model is loaded, Django iterates over every model in INSTALLED_APPS and creates the backward relationships in memory as needed. Essentially, one of the functions of INSTALLED_APPS is to tell Django the entire model domain. Queries over related objects Queries involving related objects follow the same rules as queries involving normal value fields. When specifying the the value for a query to match, you may use either an object instance itself, or the primary key value for the object. For example, if you have a Blog object b with id=5, the following three queries would be identical: Entry.objects.filter(blog=b) # Query using object instance Entry.objects.filter(blog=b.id) # Query using id from instance Entry.objects.filter(blog=5) # Query using id directly Deleting objects The delete method, conveniently, is named delete(). This method immediately deletes the object and has no return value. Example: e.delete() You can also delete objects in bulk. Every QuerySet has a delete() method, which deletes all members of that QuerySet. One-to-one relationships 128
Slide 129: Django | Documentation For example, this deletes all Entry objects with a pub_date year of 2005: Entry.objects.filter(pub_date__year=2005).delete() When Django deletes an object, it emulates the behavior of the SQL constraint ON DELETE CASCADE — in other words, any objects which had foreign keys pointing at the object to be deleted will be deleted along with it. For example: b = Blog.objects.get(pk=1) # This will delete the Blog and all of its Entry objects. b.delete() Note that delete() is the only QuerySet method that is not exposed on a Manager itself. This is a safety mechanism to prevent you from accidentally requesting Entry.objects.delete(), and deleting all the entries. If you do want to delete all the objects, then you have to explicitly request a complete query set: Entry.objects.all().delete() Extra instance methods In addition to save(), delete(), a model object might get any or all of the following methods: get_FOO_display() For every field that has choices set, the object will have a get_FOO_display() method, where FOO is the name of the field. This method returns the “human-readable” value of the field. For example, in the following model: GENDER_CHOICES = ( ('M', 'Male'), ('F', 'Female'), ) class Person(models.Model): name = models.CharField(max_length=20) gender = models.CharField(max_length=1, choices=GENDER_CHOICES) …each Person instance will have a get_gender_display() method. Example: >>> p = Person(name='John', gender='M') >>> p.save() >>> p.gender 'M' >>> p.get_gender_display() 'Male' get_next_by_FOO(**kwargs) and get_previous_by_FOO(**kwargs) For every DateField and DateTimeField that does not have null=True, the object will have get_next_by_FOO() and get_previous_by_FOO() methods, where FOO is the name of the field. This returns the next and previous object with respect to the date field, raising the appropriate DoesNotExist exception when appropriate. Deleting objects 129
Slide 130: Django | Documentation Both methods accept optional keyword arguments, which should be in the format described in Field lookups above. Note that in the case of identical date values, these methods will use the ID as a fallback check. This guarantees that no records are skipped or duplicated. For a full example, see the lookup API sample model. get_FOO_filename() For every FileField, the object will have a get_FOO_filename() method, where FOO is the name of the field. This returns the full filesystem path to the file, according to your MEDIA_ROOT setting. Note that ImageField is technically a subclass of FileField, so every model with an ImageField will also get this method. get_FOO_url() For every FileField, the object will have a get_FOO_url() method, where FOO is the name of the field. This returns the full URL to the file, according to your MEDIA_URL setting. If the value is blank, this method returns an empty string. get_FOO_size() For every FileField, the object will have a get_FOO_size() method, where FOO is the name of the field. This returns the size of the file, in bytes. (Behind the scenes, it uses os.path.getsize.) save_FOO_file(filename, raw_contents) For every FileField, the object will have a save_FOO_file() method, where FOO is the name of the field. This saves the given file to the filesystem, using the given filename. If a file with the given filename already exists, Django adds an underscore to the end of the filename (but before the extension) until the filename is available. get_FOO_height() and get_FOO_width() For every ImageField, the object will have get_FOO_height() and get_FOO_width() methods, where FOO is the name of the field. This returns the height (or width) of the image, as an integer, in pixels. Shortcuts As you develop views, you will discover a number of common idioms in the way you use the database API. Django encodes some of these idioms as shortcuts that can be used to simplify the process of writing views. These functions are in the django.shortcuts module. get_object_or_404() One common idiom to use get() and raise Http404 if the object doesn’t exist. This idiom is captured by get_object_or_404(). This function takes a Django model as its first argument and an arbitrary number of keyword arguments, which it passes to the default manager’s get() function. It raises Http404 if the object doesn’t exist. For example: get_next_by_FOO(**kwargs) and get_previous_by_FOO(**kwargs) 130
Slide 131: Django | Documentation # Get the Entry with a primary key of 3 e = get_object_or_404(Entry, pk=3) When you provide a model to this shortcut function, the default manager is used to execute the underlying get() query. If you don’t want to use the default manager, or if you want to search a list of related objects, you can provide get_object_or_404() with a Manager object instead. For example: # Get the author of blog instance e with a name of 'Fred' a = get_object_or_404(e.authors, name='Fred') # Use a custom manager 'recent_entries' in the search for an # entry with a primary key of 3 e = get_object_or_404(Entry.recent_entries, pk=3) New in Django development version: The first argument to get_object_or_404() can be a QuerySet object. This is useful in cases where you’ve defined a custom manager method. For example: # Use a QuerySet returned from a 'published' method of a custom manager # in the search for an entry with primary key of 5 e = get_object_or_404(Entry.objects.published(), pk=5) get_list_or_404() get_list_or_404 behaves the same way as get_object_or_404() — except that it uses filter() instead of get(). It raises Http404 if the list is empty. Falling back to raw SQL If you find yourself needing to write an SQL query that is too complex for Django’s database-mapper to handle, you can fall back into raw-SQL statement mode. The preferred way to do this is by giving your model custom methods or custom manager methods that execute queries. Although there’s nothing in Django that requires database queries to live in the model layer, this approach keeps all your data-access logic in one place, which is smart from an code-organization standpoint. For instructions, see Executing custom SQL. Finally, it’s important to note that the Django database layer is merely an interface to your database. You can access your database via other tools, programming languages or database frameworks; there’s nothing Django-specific about your database. Questions/Feedback If you notice errors with this documentation, please open a ticket and let us know! Please only use the ticket tracker for criticisms and improvements on the docs. For tech support, ask in the IRC channel or post to the django-users list. Contents • Creating objects get_object_or_404() 131
Slide 132: Django | Documentation ♦ Auto-incrementing primary keys ◊ Explicitly specifying auto-primary-key values ♦ What happens when you save? ◊ Raw Saves • Saving changes to objects ♦ How Django knows to UPDATE vs. INSERT • Retrieving objects ♦ Retrieving all objects ♦ Filtering objects ◊ Chaining filters ♦ Filtered QuerySets are unique ♦ QuerySets are lazy ◊ When QuerySets are evaluated ♦ Limiting QuerySets ♦ QuerySet methods that return new QuerySets ◊ filter(**kwargs) ◊ exclude(**kwargs) ◊ order_by(*fields) ◊ distinct() ◊ values(*fields) ◊ dates(field, kind, order='ASC') ◊ none() ◊ select_related() ◊ extra(select=None, where=None, params=None, tables=None) ♦ QuerySet methods that do not return QuerySets ◊ get(**kwargs) ◊ create(**kwargs) ◊ get_or_create(**kwargs) ◊ count() ◊ in_bulk(id_list) ◊ latest(field_name=None) ♦ Field lookups ◊ exact ◊ iexact ◊ contains ◊ icontains ◊ gt ◊ gte ◊ lt ◊ lte ◊ in ◊ startswith ◊ istartswith ◊ endswith ◊ iendswith ◊ range ◊ year ◊ month ◊ day Contents 132
Slide 133: Django | Documentation ◊ isnull ◊ search ◊ regex ◊ iregex ♦ Default lookups are exact ♦ The pk lookup shortcut ◊ Lookups that span relationships ◊ Escaping percent signs and underscores in LIKE statements ♦ Caching and QuerySets • Comparing objects • Complex lookups with Q objects • Related objects ♦ One-to-many relationships ◊ Forward ◊ Backward ♦ Many-to-many relationships ♦ One-to-one relationships ♦ How are the backward relationships possible? ♦ Queries over related objects • Deleting objects • Extra instance methods ♦ get_FOO_display() ♦ get_next_by_FOO(**kwargs) and get_previous_by_FOO(**kwargs) ♦ get_FOO_filename() ♦ get_FOO_url() ♦ get_FOO_size() ♦ save_FOO_file(filename, raw_contents) ♦ get_FOO_height() and get_FOO_width() • Shortcuts ♦ get_object_or_404() ♦ get_list_or_404() • Falling back to raw SQL Last update: August 5, 12:14 a.m. © 2005-2007 Lawrence Journal-World unless otherwise noted. Django is a registered trademark of Lawrence Journal-World. Last update: 133
Slide 134: Django | Documentation • Home • Download • Documentation • Weblog • Community • Code Django documentation Managing database transactions This document is for Django's SVN release, which can be significantly different than previous releases. Get old docs here: 0.96, 0.95. Django gives you a few ways to control how database transactions are managed, if you’re using a database that supports transactions. Django’s default transaction behavior Django’s default behavior is to commit automatically when any built-in, data-altering model function is called. For example, if you call model.save() or model.delete(), the change will be committed immediately. This is much like the auto-commit setting for most databases. As soon as you perform an action that needs to write to the database, Django produces the INSERT/UPDATE/DELETE statements and then does the COMMIT. There’s no implicit ROLLBACK. Tying transactions to HTTP requests The recommended way to handle transactions in Web requests is to tie them to the request and response phases via Django’s TransactionMiddleware. It works like this: When a request starts, Django starts a transaction. If the response is produced without problems, Django commits any pending transactions. If the view function produces an exception, Django rolls back any pending transactions. To activate this feature, just add the TransactionMiddleware middleware to your MIDDLEWARE_CLASSES setting: MIDDLEWARE_CLASSES = ( 'django.contrib.sessions.middleware.SessionMiddleware', 'django.middleware.common.CommonMiddleware', 'django.middleware.cache.CacheMiddleware', 'django.middleware.transaction.TransactionMiddleware', Managing database transactions 134
Slide 135: Django | Documentation ) The order is quite important. The transaction middleware applies not only to view functions, but also for all middleware modules that come after it. So if you use the session middleware after the transaction middleware, session creation will be part of the transaction. An exception is CacheMiddleware, which is never affected. The cache middleware uses its own database cursor (which is mapped to its own database connection internally). Controlling transaction management in views For most people, implicit request-based transactions work wonderfully. However, if you need more fine-grained control over how transactions are managed, you can use Python decorators to change the way transactions are handled by a particular view function. Note Although the examples below use view functions as examples, these decorators can be applied to non-view functions as well. django.db.transaction.autocommit Use the autocommit decorator to switch a view function to Django’s default commit behavior, regardless of the global transaction setting. Example: from django.db import transaction @transaction.autocommit def viewfunc(request): .... Within viewfunc(), transactions will be committed as soon as you call model.save(), model.delete(), or any other function that writes to the database. django.db.transaction.commit_on_success Use the commit_on_success decorator to use a single transaction for all the work done in a function: from django.db import transaction @transaction.commit_on_success def viewfunc(request): .... If the function returns successfully, then Django will commit all work done within the function at that point. If the function raises an exception, though, Django will roll back the transaction. Tying transactions to HTTP requests 135
Slide 136: Django | Documentation django.db.transaction.commit_manually Use the commit_manually decorator if you need full control over transactions. It tells Django you’ll be managing the transaction on your own. If your view changes data and doesn’t commit() or rollback(), Django will raise a TransactionManagementError exception. Manual transaction management looks like this: from django.db import transaction @transaction.commit_manually def viewfunc(request): ... # You can commit/rollback however and whenever you want transaction.commit() ... # But you've got to remember to do it yourself! try: ... except: transaction.rollback() else: transaction.commit() An important note to users of earlier Django releases: The database connection.commit() and connection.rollback() methods (called db.commit() and db.rollback() in 0.91 and earlier) no longer exist. They’ve been replaced by transaction.commit() and transaction.rollback(). How to globally deactivate transaction management Control freaks can totally disable all transaction management by setting DISABLE_TRANSACTION_MANAGEMENT to True in the Django settings file. If you do this, Django won’t provide any automatic transaction management whatsoever. Middleware will no longer implicitly commit transactions, and you’ll need to roll management yourself. This even requires you to commit changes done by middleware somewhere else. Thus, this is best used in situations where you want to run your own transaction-controlling middleware or do something really strange. In almost all situations, you’ll be better off using the default behavior, or the transaction middleware, and only modify selected functions as needed. Transactions in MySQL If you’re using MySQL, your tables may or may not support transactions; it depends on your MySQL version and the table types you’re using. (By “table types,” we mean something like “InnoDB” or “MyISAM”.) MySQL transaction peculiarities are outside the scope of this article, but the MySQL site has information on MySQL transactions. django.db.transaction.commit_manually 136
Slide 137: Django | Documentation If your MySQL setup does not support transactions, then Django will function in auto-commit mode: Statements will be executed and committed as soon as they’re called. If your MySQL setup does support transactions, Django will handle transactions as explained in this document. Questions/Feedback If you notice errors with this documentation, please open a ticket and let us know! Please only use the ticket tracker for criticisms and improvements on the docs. For tech support, ask in the IRC channel or post to the django-users list. Contents • Django’s default transaction behavior • Tying transactions to HTTP requests • Controlling transaction management in views ♦ django.db.transaction.autocommit ♦ django.db.transaction.commit_on_success ♦ django.db.transaction.commit_manually • How to globally deactivate transaction management • Transactions in MySQL Last update: July 23, 9:39 p.m. © 2005-2007 Lawrence Journal-World unless otherwise noted. Django is a registered trademark of Lawrence Journal-World. Transactions in MySQL 137
Slide 138: Django | Documentation • Home • Download • Documentation • Weblog • Community • Code Django documentation The Django template language: For template authors This document is for Django's SVN release, which can be significantly different than previous releases. Get old docs here: 0.96, 0.95. Django’s template language is designed to strike a balance between power and ease. It’s designed to feel comfortable to those used to working with HTML. If you have any exposure to other text-based template languages, such as Smarty or CheetahTemplate, you should feel right at home with Django’s templates. Templates A template is simply a text file. It can generate any text-based format (HTML, XML, CSV, etc.). A template contains variables, which get replaced with values when the template is evaluated, and tags, which control the logic of the template. Below is a minimal template that illustrates a few basics. Each element will be explained later in this document.: {% extends "base_generic.html" %} {% block title %}{{ section.title }}{% endblock %} {% block content %} <h1>{{ section.title }}</h1> {% for story in story_list %} <h2> <a href="{{ story.get_absolute_url }}"> {{ story.headline|upper }} </a> </h2> <p>{{ story.tease|truncatewords:"100" }}</p> {% endfor %} {% endblock %} Philosophy The Django template language: For template authors 138
Slide 139: Django | Documentation Why use a text-based template instead of an XML-based one (like Zope’s TAL)? We wanted Django’s template language to be usable for more than just XML/HTML templates. At World Online, we use it for e-mails, JavaScript and CSV. You can use the template language for any text-based format. Oh, and one more thing: Making humans edit XML is sadistic! Variables Variables look like this: {{ variable }}. When the template engine encounters a variable, it evaluates that variable and replaces it with the result. Use a dot (.) to access attributes of a variable. Behind the scenes Technically, when the template system encounters a dot, it tries the following lookups, in this order: • Dictionary lookup • Attribute lookup • Method call • List-index lookup In the above example, {{ section.title }} will be replaced with the title attribute of the section object. If you use a variable that doesn’t exist, the template system will insert the value of the TEMPLATE_STRING_IF_INVALID setting, which is set to '' (the empty string) by default. See Using the built-in reference, below, for help on finding what variables are available in a given template. Filters You can modify variables for display by using filters. Filters look like this: {{ name|lower }}. This displays the value of the {{ name }} variable after being filtered through the lower filter, which converts text to lowercase. Use a pipe (|) to apply a filter. Filters can be “chained.” The output of one filter is applied to the next. {{ text|escape|linebreaks }} is a common idiom for escaping text contents, then converting line breaks to <p> tags. Some filters take arguments. A filter argument looks like this: {{ bio|truncatewords:30 }}. This will display the first 30 words of the bio variable. Filter arguments that contain spaces must be quoted; for example, to join a list with commas and spaced you’d use {{ list|join:", " }}. The Built-in filter reference below describes all the built-in filters. Templates 139
Slide 140: Django | Documentation Tags Tags look like this: {% tag %}. Tags are more complex than variables: Some create text in the output, some control flow by performing loops or logic, and some load external information into the template to be used by later variables. Some tags require beginning and ending tags (i.e. {% tag %} ... tag contents ... {% endtag %}). The Built-in tag reference below describes all the built-in tags. You can create your own tags, if you know how to write Python code. Comments To comment-out part of a line in a template, use the comment syntax: {# #}. For example, this template would render as 'hello': {# greeting #}hello A comment can contain any template code, invalid or not. For example: {# {% if foo %}bar{% else %} #} This syntax can only be used for single-line comments (no newlines are permitted between the {# and #} delimiters). If you need to comment out a multiline portion of the template, see the comment tag, below. Template inheritance The most powerful — and thus the most complex — part of Django’s template engine is template inheritance. Template inheritance allows you to build a base “skeleton” template that contains all the common elements of your site and defines blocks that child templates can override. It’s easiest to understand template inheritance by starting with an example: <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> <head> <link rel="stylesheet" href="style.css" /> <title>{% block title %}My amazing site{% endblock %}</title> </head> <body> <div id="sidebar"> {% block sidebar %} <ul> <li><a href="/">Home</a></li> <li><a href="/blog/">Blog</a></li> </ul> {% endblock %} </div> <div id="content"> {% block content %}{% endblock %} Tags 140
Slide 141: Django | Documentation </div> </body> </html> This template, which we’ll call base.html, defines a simple HTML skeleton document that you might use for a simple two-column page. It’s the job of “child” templates to fill the empty blocks with content. In this example, the {% block %} tag defines three blocks that child templates can fill in. All the block tag does is to tell the template engine that a child template may override those portions of the template. A child template might look like this: {% extends "base.html" %} {% block title %}My amazing blog{% endblock %} {% block content %} {% for entry in blog_entries %} <h2>{{ entry.title }}</h2> <p>{{ entry.body }}</p> {% endfor %} {% endblock %} The {% extends %} tag is the key here. It tells the template engine that this template “extends” another template. When the template system evaluates this template, first it locates the parent — in this case, “base.html”. At that point, the template engine will notice the three {% block %} tags in base.html and replace those blocks with the contents of the child template. Depending on the value of blog_entries, the output might look like: <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> <head> <link rel="stylesheet" href="style.css" /> <title>My amazing blog</title> </head> <body> <div id="sidebar"> <ul> <li><a href="/">Home</a></li> <li><a href="/blog/">Blog</a></li> </ul> </div> <div id="content"> <h2>Entry one</h2> <p>This is my first entry.</p> <h2>Entry two</h2> <p>This is my second entry.</p> </div> </body> </html> Template inheritance 141
Slide 142: Django | Documentation Note that since the child template didn’t define the sidebar block, the value from the parent template is used instead. Content within a {% block %} tag in a parent template is always used as a fallback. You can use as many levels of inheritance as needed. One common way of using inheritance is the following three-level approach: • Create a base.html template that holds the main look-and-feel of your site. • Create a base_SECTIONNAME.html template for each “section” of your site. For example, base_news.html, base_sports.html. These templates all extend base.html and include section-specific styles/design. • Create individual templates for each type of page, such as a news article or blog entry. These templates extend the appropriate section template. This approach maximizes code reuse and makes it easy to add items to shared content areas, such as section-wide navigation. Here are some tips for working with inheritance: • If you use {% extends %} in a template, it must be the first template tag in that template. Template inheritance won’t work, otherwise. • More {% block %} tags in your base templates are better. Remember, child templates don’t have to define all parent blocks, so you can fill in reasonable defaults in a number of blocks, then only define the ones you need later. It’s better to have more hooks than fewer hooks. • If you find yourself duplicating content in a number of templates, it probably means you should move that content to a {% block %} in a parent template. • If you need to get the content of the block from the parent template, the {{ block.super }} variable will do the trick. This is useful if you want to add to the contents of a parent block instead of completely overriding it. • For extra readability, you can optionally give a name to your {% endblock %} tag. For example: {% block content %} ... {% endblock content %} In larger templates, this technique helps you see which {% block %} tags are being closed. Finally, note that you can’t define multiple {% block %} tags with the same name in the same template. This limitation exists because a block tag works in “both” directions. That is, a block tag doesn’t just provide a hole to fill — it also defines the content that fills the hole in the parent. If there were two similarly-named {% block %} tags in a template, that template’s parent wouldn’t know which one of the blocks’ content to use. Using the built-in reference Django’s admin interface includes a complete reference of all template tags and filters available for a given site. To see it, go to your admin interface and click the “Documentation” link in the upper right of the page. The reference is divided into 4 sections: tags, filters, models, and views. The tags and filters sections describe all the built-in tags (in fact, the tag and filter references below come directly from those pages) as well as any custom tag or filter libraries available. Using the built-in reference 142
Slide 143: Django | Documentation The views page is the most valuable. Each URL in your site has a separate entry here, and clicking on a URL will show you: • The name of the view function that generates that view. • A short description of what the view does. • The context, or a list of variables available in the view’s template. • The name of the template or templates that are used for that view. Each view documentation page also has a bookmarklet that you can use to jump from any page to the documentation page for that view. Because Django-powered sites usually use database objects, the models section of the documentation page describes each type of object in the system along with all the fields available on that object. Taken together, the documentation pages should tell you every tag, filter, variable and object available to you in a given template. Custom tag and filter libraries Certain applications provide custom tag and filter libraries. To access them in a template, use the {% load %} tag: {% load comments %} {% comment_form for blogs.entries entry.id with is_public yes %} In the above, the load tag loads the comments tag library, which then makes the comment_form tag available for use. Consult the documentation area in your admin to find the list of custom libraries in your installation. The {% load %} tag can take multiple library names, separated by spaces. Example: {% load comments i18n %} Custom libraries and template inheritance When you load a custom tag or filter library, the tags/filters are only made available to the current template — not any parent or child templates along the template-inheritance path. For example, if a template foo.html has {% load comments %}, a child template (e.g., one that has {% extends "foo.html" %}) will not have access to the comments template tags and filters. The child template is responsible for its own {% load comments %}. This is a feature for the sake of maintainability and sanity. Built-in tag and filter reference For those without an admin site available, reference for the stock tags and filters follows. Because Django is highly customizable, the reference in your admin should be considered the final word on what tags and filters are available, and what they do. Custom tag and filter libraries 143
Slide 144: Django | Documentation Built-in tag reference block Define a block that can be overridden by child templates. See Template inheritance for more information. comment Ignore everything between {% comment %} and {% endcomment %} cycle Cycle among the given strings each time this tag is encountered. Within a loop, cycles among the given strings each time through the loop: {% for o in some_list %} <tr class="{% cycle row1,row2 %}"> ... </tr> {% endfor %} Outside of a loop, give the values a unique name the first time you call it, then use that name each successive time through: <tr class="{% cycle row1,row2,row3 as rowcolors %}">...</tr> <tr class="{% cycle rowcolors %}">...</tr> <tr class="{% cycle rowcolors %}">...</tr> You can use any number of values, separated by commas. Make sure not to put spaces between the values — only commas. debug Output a whole load of debugging information, including the current context and imported modules. extends Signal that this template extends a parent template. This tag can be used in two ways: • {% extends "base.html" %} (with quotes) uses the literal value "base.html" as the name of the parent template to extend. • {% extends variable %} uses the value of variable. If the variable evaluates to a string, Django will use that string as the name of the parent template. If the variable evaluates to a Template object, Django will use that object as the parent template. See Template inheritance for more information. Built-in tag reference 144
Slide 145: Django | Documentation filter Filter the contents of the variable through variable filters. Filters can also be piped through each other, and they can have arguments — just like in variable syntax. Sample usage: {% filter escape|lower %} This text will be HTML-escaped, and will appear in all lowercase. {% endfilter %} firstof Outputs the first variable passed that is not False. Outputs nothing if all the passed variables are False. Sample usage: {% firstof var1 var2 var3 %} This is equivalent to: {% if var1 %} {{ var1 }} {% else %}{% if var2 %} {{ var2 }} {% else %}{% if var3 %} {{ var3 }} {% endif %}{% endif %}{% endif %} for Loop over each item in an array. For example, to display a list of athletes provided in athlete_list: <ul> {% for athlete in athlete_list %} <li>{{ athlete.name }}</li> {% endfor %} </ul> You can loop over a list in reverse by using {% for obj in list reversed %}. New in Django development version If you need to loop over a list of lists, you can unpack the values in eachs sub-list into a set of known names. For example, if your context contains a list of (x,y) coordinates called points, you could use the following to output the list of points: {% for x, y in points %} There is a point at {{ x }},{{ y }} {% endfor %} This can also be useful if you need to access the items in a dictionary. For example, if your context contained a dictionary data, the following would display the keys and values of the dictionary: {% for key, value in data.items %} Built-in tag reference 145
Slide 146: Django | Documentation {{ key }}: {{ value }} {% endfor %} The for loop sets a number of variables available within the loop: Variable forloop.counter forloop.counter0 forloop.revcounter forloop.revcounter0 forloop.first forloop.last forloop.parentloop if Description The current iteration of the loop (1-indexed) The current iteration of the loop (0-indexed) The number of iterations from the end of the loop (1-indexed) The number of iterations from the end of the loop (0-indexed) True if this is the first time through the loop True if this is the last time through the loop For nested loops, this is the loop “above” the current one The {% if %} tag evaluates a variable, and if that variable is “true” (i.e. exists, is not empty, and is not a false boolean value) the contents of the block are output: {% if athlete_list %} Number of athletes: {{ athlete_list|length }} {% else %} No athletes. {% endif %} In the above, if athlete_list is not empty, the number of athletes will be displayed by the {{ athlete_list|length }} variable. As you can see, the if tag can take an optional {% else %} clause that will be displayed if the test fails. if tags may use and, or or not to test a number of variables or to negate a given variable: {% if athlete_list and coach_list %} Both athletes and coaches are available. {% endif %} {% if not athlete_list %} There are no athletes. {% endif %} {% if athlete_list or coach_list %} There are some athletes or some coaches. {% endif %} {% if not athlete_list or coach_list %} There are no athletes or there are some coaches (OK, so writing English translations of boolean logic sounds stupid; it's not our fault). {% endif %} {% if athlete_list and not coach_list %} There are some athletes and absolutely no coaches. {% endif %} Built-in tag reference 146
Slide 147: Django | Documentation if tags don’t allow and and or clauses within the same tag, because the order of logic would be ambiguous. For example, this is invalid: {% if athlete_list and coach_list or cheerleader_list %} If you need to combine and and or to do advanced logic, just use nested if tags. For example: {% if athlete_list %} {% if coach_list or cheerleader_list %} We have athletes, and either coaches or cheerleaders! {% endif %} {% endif %} Multiple uses of the same logical operator are fine, as long as you use the same operator. For example, this is valid: {% if athlete_list or coach_list or parent_list or teacher_list %} ifchanged Check if a value has changed from the last iteration of a loop. The ‘ifchanged’ block tag is used within a loop. It has two possible uses. 1. Checks its own rendered contents against its previous state and only displays the content if it has changed. For example, this displays a list of days, only displaying the month if it changes: <h1>Archive for {{ year }}</h1> {% for date in days %} {% ifchanged %}<h3>{{ date|date:"F" }}</h3>{% endifchanged %} <a href="{{ date|date:"M/d"|lower }}/">{{ date|date:"j" }}</a> {% endfor %} 2. If given a variable, check whether that variable has changed. For example, the following shows the date every time it changes, but only shows the hour if both the hour and the date has changed: {% for date in days %} {% ifchanged date.date %} {{ date.date }} {% endifchanged %} {% ifchanged date.hour date.date %} {{ date.hour }} {% endifchanged %} {% endfor %} ifequal Output the contents of the block if the two arguments equal each other. Example: {% ifequal user.id comment.user_id %} ... {% endifequal %} As in the {% if %} tag, an {% else %} clause is optional. Built-in tag reference 147
Slide 148: Django | Documentation The arguments can be hard-coded strings, so the following is valid: {% ifequal user.username "adrian" %} ... {% endifequal %} It is only possible to compare an argument to template variables or strings. You cannot check for equality with Python objects such as True or False. If you need to test if something is true or false, use the if tag instead. ifnotequal Just like ifequal, except it tests that the two arguments are not equal. include Loads a template and renders it with the current context. This is a way of “including” other templates within a template. The template name can either be a variable or a hard-coded (quoted) string, in either single or double quotes. This example includes the contents of the template "foo/bar.html": {% include "foo/bar.html" %} This example includes the contents of the template whose name is contained in the variable template_name: {% include template_name %} An included template is rendered with the context of the template that’s including it. This example produces the output "Hello, John": • Context: variable person is set to "john". • Template: {% include "name_snippet.html" %} • The name_snippet.html template: Hello, {{ person }} See also: {% ssi %}. load Load a custom template tag set. See Custom tag and filter libraries for more information. Built-in tag reference 148
Slide 149: Django | Documentation now Display the date, formatted according to the given string. Uses the same format as PHP’s date() function (http://php.net/date) with some custom extensions. Available format strings: Format character a A b B d D f F g G h H i I j l L m M n N O P r s S t Description 'a.m.' or 'p.m.' (Note that this is slightly different than PHP’s output, because this includes periods to match Associated Press style.) 'AM' or 'PM'. Month, textual, 3 letters, lowercase. Not implemented. Day of the month, 2 digits with leading zeros. Day of the week, textual, 3 letters. Time, in 12-hour hours and minutes, with minutes left off if they’re zero. Proprietary extension. Month, textual, long. Hour, 12-hour format without leading zeros. Hour, 24-hour format without leading zeros. Hour, 12-hour format. Hour, 24-hour format. Minutes. Not implemented. Day of the month without leading zeros. Day of the week, textual, long. Boolean for whether it’s a leap year. Month, 2 digits with leading zeros. Month, textual, 3 letters. Month without leading zeros. Month abbreviation in Associated Press style. Proprietary extension. Difference to Greenwich time in hours. Time, in 12-hour hours, minutes and ‘a.m.’/’p.m.’, with minutes left off if they’re zero and the special-case strings ‘midnight’ and ‘noon’ if appropriate. Proprietary extension. RFC 822 formatted date. Seconds, 2 digits with leading zeros. English ordinal suffix for day of the month, 2 characters. Number of days in the given month. Example output 'a.m.' 'AM' 'jan' '01' to '31' 'Fri' '1', '1:30' 'January' '1' to '12' '0' to '23' '01' to '12' '00' to '23' '00' to '59' '1' to '31' 'Friday' True or False '01' to '12' 'Jan' '1' to '12' 'Jan.', 'Feb.', 'March', 'May' '+0200' '1 a.m.', '1:30 p.m.', 'midnight', 'noon', '12:30 p.m.' 'Thu, 21 Dec 2000 16:01:07 +0200' '00' to '59' 'st', 'nd', 'rd' or 'th' 28 to 31 Built-in tag reference 149
Slide 150: Django | Documentation T U w W y Y z Z Example: Time zone of this machine. Not implemented. Day of the week, digits without leading zeros. ISO-8601 week number of year, with weeks starting on Monday. Year, 2 digits. Year, 4 digits. Day of the year. Time zone offset in seconds. The offset for timezones west of UTC is always negative, and for those east of UTC is always positive. 'EST', 'MDT' '0' (Sunday) to '6' (Saturday) 1, 23 '99' '1999' 0 to 365 -43200 to 43200 It is {% now "jS F Y H:i" %} Note that you can backslash-escape a format string if you want to use the “raw” value. In this example, “f” is backslash-escaped, because otherwise “f” is a format string that displays the time. The “o” doesn’t need to be escaped, because it’s not a format character: It is the {% now "jS o\f F" %} This would display as “It is the 4th of September”. regroup Regroup a list of alike objects by a common attribute. This complex tag is best illustrated by use of an example: say that people is a list of people represented by dictionaries with first_name, last_name, and gender keys: people = [ {'first_name': {'first_name': {'first_name': {'first_name': {'first_name': ] 'George', 'last_name': 'Bush', 'gender': 'Male'}, 'Bill', 'last_name': 'Clinton', 'gender': 'Male'}, 'Margaret', 'last_name': 'Thatcher', 'gender': 'Female'}, 'Condoleezza', 'last_name': 'Rice', 'gender': 'Female'}, 'Pat', 'last_name': 'Smith', 'gender': 'Unknown'}, …and you’d like to display a hierarchical list that is ordered by gender, like this: • Male: ⋅ George Bush ⋅ Bill Clinton • Female: ⋅ Margaret Thatcher ⋅ Condoleezza Rice • Unknown: ⋅ Pat Smith Built-in tag reference 150