Downloaded 17 times
![Django Documentation, Release 1.9.3.dev20160224120324
2.1.2 Install it
Next, run the Django command-line utility to create the database tables automatically:
$ python manage.py migrate
The migrate command looks at all your available models and creates tables in your database for whichever tables
don’t already exist, as well as optionally providing much richer schema control.
2.1.3 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:
# Import the models we created from our "news" app
>>> from news.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()
[<Reporter: 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)
<Reporter: John Smith>
>>> Reporter.objects.get(full_name__startswith='John')
<Reporter: John Smith>
>>> Reporter.objects.get(full_name__contains='mith')
<Reporter: John Smith>
>>> Reporter.objects.get(id=2)
Traceback (most recent call last):
...
DoesNotExist: Reporter matching query does not exist.
# Create an article.
>>> from datetime import date
>>> a = Article(pub_date=date.today(), headline='Django is cool',
... content='Yeah.', reporter=r)
>>> a.save()
8 Chapter 2. Getting started](https://image.slidesharecdn.com/20160225-django-documentation-160225091707/85/Django-Documentation-12-320.jpg)
![Django Documentation, Release 1.9.3.dev20160224120324
# Now the article is in the database.
>>> Article.objects.all()
[<Article: 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()
[<Article: 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')
[<Article: 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()
2.1.4 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 inter-
face – a website that lets authenticated users add, change and delete objects. It’s as easy as registering your model in
the admin site:
mysite/news/models.py
from django.db import models
class Article(models.Model):
pub_date = models.DateField()
headline = models.CharField(max_length=200)
content = models.TextField()
reporter = models.ForeignKey(Reporter, on_delete=models.CASCADE)
mysite/news/admin.py
from django.contrib import admin
from . import models
admin.site.register(models.Article)
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.
2.1. Django at a glance 9](https://image.slidesharecdn.com/20160225-django-documentation-160225091707/85/Django-Documentation-13-320.jpg)
![Django Documentation, Release 1.9.3.dev20160224120324
2.1.5 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.
Here’s what a URLconf might look like for the Reporter/Article example above:
mysite/news/urls.py
from django.conf.urls import url
from . import views
urlpatterns = [
url(r'^articles/([0-9]{4})/$', views.year_archive),
url(r'^articles/([0-9]{4})/([0-9]{2})/$', views.month_archive),
url(r'^articles/([0-9]{4})/([0-9]{2})/([0-9]+)/$', 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
news.views.article_detail(request, ’2005’, ’05’, ’39323’).
2.1.6 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:
mysite/news/views.py
from django.shortcuts import render
from .models import Article
def year_archive(request, year):
a_list = Article.objects.filter(pub_date__year=year)
context = {'year': year, 'article_list': a_list}
return render(request, 'news/year_archive.html', context)
This example uses Django’s template system, which has several powerful features but strives to stay simple enough
for non-programmers to use.
10 Chapter 2. Getting started](https://image.slidesharecdn.com/20160225-django-documentation-160225091707/85/Django-Documentation-14-320.jpg)
![Django Documentation, Release 1.9.3.dev20160224120324
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 mobile versions 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.
2.1.8 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!
2.2 Quick install guide
Before you can use Django, you’ll need to get it installed. We have a complete installation guide that covers all
the possibilities; this guide will guide you to a simple, minimal installation that’ll work while you walk through the
introduction.
2.2.1 Install Python
Being a Python Web framework, Django requires Python. See What Python version can I use with Django? for details.
Python includes a lightweight database called SQLite so you won’t need to set up a database just yet.
Get the latest version of Python at https://www.python.org/download/ or with your operating system’s package man-
ager.
Django on Jython
If you use Jython (a Python implementation for the Java platform), you’ll need to follow a few additional steps. See
Running Django on Jython for details.
You can verify that Python is installed by typing python from your shell; you should see something like:
Python 3.4.x
[GCC 4.x] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>>
2.2.2 Set up a database
This step is only necessary if you’d like to work with a “large” database engine like PostgreSQL, MySQL, or Oracle.
To install such a database, consult the database installation information.
12 Chapter 2. Getting started](https://image.slidesharecdn.com/20160225-django-documentation-160225091707/85/Django-Documentation-16-320.jpg)
![Django Documentation, Release 1.9.3.dev20160224120324
2.1.2 Install it
Next, run the Django command-line utility to create the database tables automatically:
$ python manage.py migrate
The migrate command looks at all your available models and creates tables in your database for whichever tables
don’t already exist, as well as optionally providing much richer schema control.
2.1.3 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:
# Import the models we created from our "news" app
>>> from news.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()
[<Reporter: 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)
<Reporter: John Smith>
>>> Reporter.objects.get(full_name__startswith='John')
<Reporter: John Smith>
>>> Reporter.objects.get(full_name__contains='mith')
<Reporter: John Smith>
>>> Reporter.objects.get(id=2)
Traceback (most recent call last):
...
DoesNotExist: Reporter matching query does not exist.
# Create an article.
>>> from datetime import date
>>> a = Article(pub_date=date.today(), headline='Django is cool',
... content='Yeah.', reporter=r)
>>> a.save()
8 Chapter 2. Getting started](/p?url=https%3A%2F%2Fimage.slidesharecdn.com%2F20160225-django-documentation-160225091707%2F85%2FDjango-Documentation-12-320.jpg&__src=https%3A%2F%2Fwww.slideshare.net%2Fslideshow%2Fdjango-documentation%2F58699702%2319&__type=image)
![Django Documentation, Release 1.9.3.dev20160224120324
# Now the article is in the database.
>>> Article.objects.all()
[<Article: 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()
[<Article: 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')
[<Article: 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()
2.1.4 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 inter-
face – a website that lets authenticated users add, change and delete objects. It’s as easy as registering your model in
the admin site:
mysite/news/models.py
from django.db import models
class Article(models.Model):
pub_date = models.DateField()
headline = models.CharField(max_length=200)
content = models.TextField()
reporter = models.ForeignKey(Reporter, on_delete=models.CASCADE)
mysite/news/admin.py
from django.contrib import admin
from . import models
admin.site.register(models.Article)
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.
2.1. Django at a glance 9](/p?url=https%3A%2F%2Fimage.slidesharecdn.com%2F20160225-django-documentation-160225091707%2F85%2FDjango-Documentation-13-320.jpg&__src=https%3A%2F%2Fwww.slideshare.net%2Fslideshow%2Fdjango-documentation%2F58699702%2319&__type=image)
![Django Documentation, Release 1.9.3.dev20160224120324
2.1.5 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.
Here’s what a URLconf might look like for the Reporter/Article example above:
mysite/news/urls.py
from django.conf.urls import url
from . import views
urlpatterns = [
url(r'^articles/([0-9]{4})/$', views.year_archive),
url(r'^articles/([0-9]{4})/([0-9]{2})/$', views.month_archive),
url(r'^articles/([0-9]{4})/([0-9]{2})/([0-9]+)/$', 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
news.views.article_detail(request, ’2005’, ’05’, ’39323’).
2.1.6 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:
mysite/news/views.py
from django.shortcuts import render
from .models import Article
def year_archive(request, year):
a_list = Article.objects.filter(pub_date__year=year)
context = {'year': year, 'article_list': a_list}
return render(request, 'news/year_archive.html', context)
This example uses Django’s template system, which has several powerful features but strives to stay simple enough
for non-programmers to use.
10 Chapter 2. Getting started](/p?url=https%3A%2F%2Fimage.slidesharecdn.com%2F20160225-django-documentation-160225091707%2F85%2FDjango-Documentation-14-320.jpg&__src=https%3A%2F%2Fwww.slideshare.net%2Fslideshow%2Fdjango-documentation%2F58699702%2319&__type=image)
![Django Documentation, Release 1.9.3.dev20160224120324
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 mobile versions 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.
2.1.8 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!
2.2 Quick install guide
Before you can use Django, you’ll need to get it installed. We have a complete installation guide that covers all
the possibilities; this guide will guide you to a simple, minimal installation that’ll work while you walk through the
introduction.
2.2.1 Install Python
Being a Python Web framework, Django requires Python. See What Python version can I use with Django? for details.
Python includes a lightweight database called SQLite so you won’t need to set up a database just yet.
Get the latest version of Python at https://www.python.org/download/ or with your operating system’s package man-
ager.
Django on Jython
If you use Jython (a Python implementation for the Java platform), you’ll need to follow a few additional steps. See
Running Django on Jython for details.
You can verify that Python is installed by typing python from your shell; you should see something like:
Python 3.4.x
[GCC 4.x] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>>
2.2.2 Set up a database
This step is only necessary if you’d like to work with a “large” database engine like PostgreSQL, MySQL, or Oracle.
To install such a database, consult the database installation information.
12 Chapter 2. Getting started](/p?url=https%3A%2F%2Fimage.slidesharecdn.com%2F20160225-django-documentation-160225091707%2F85%2FDjango-Documentation-16-320.jpg&__src=https%3A%2F%2Fwww.slideshare.net%2Fslideshow%2Fdjango-documentation%2F58699702%2319&__type=image)
![Django Documentation, Release 1.9.3.dev20160224120324
2.3.4 Write your first view
Let’s write the first view. Open the file polls/views.py and put the following Python code in it:
polls/views.py
from django.http import HttpResponse
def index(request):
return HttpResponse("Hello, world. You're at the polls index.")
This is the simplest view possible in Django. To call the view, we need to map it to a URL - and for this we need a
URLconf.
To create a URLconf in the polls directory, create a file called urls.py. Your app directory should now look like:
polls/
__init__.py
admin.py
apps.py
migrations/
__init__.py
models.py
tests.py
urls.py
views.py
In the polls/urls.py file include the following code:
polls/urls.py
from django.conf.urls import url
from . import views
urlpatterns = [
url(r'^$', views.index, name='index'),
]
The next step is to point the root URLconf at the polls.urls module. In mysite/urls.py, add an import for
django.conf.urls.include and insert an include() in the urlpatterns list, so you have:
mysite/urls.py
from django.conf.urls import include, url
from django.contrib import admin
urlpatterns = [
url(r'^polls/', include('polls.urls')),
url(r'^admin/', admin.site.urls),
]
When to use include()
You should always use include() when you include other URL patterns. admin.site.urls is the only excep-
tion to this.
Doesn’t match what you see?
2.3. Writing your first Django app, part 1 17](/p?url=https%3A%2F%2Fimage.slidesharecdn.com%2F20160225-django-documentation-160225091707%2F85%2FDjango-Documentation-21-320.jpg&__src=https%3A%2F%2Fwww.slideshare.net%2Fslideshow%2Fdjango-documentation%2F58699702%2319&__type=image)
![Django Documentation, Release 1.9.3.dev20160224120324
The name of each Field instance (e.g. question_text 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 Question.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 arguments. 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.
A Field can also have various optional arguments; in this case, we’ve set the default value of votes to 0.
Finally, note a relationship is defined, using ForeignKey. That tells Django each Choice is related to a single
Question. Django supports all the common database relationships: many-to-one, many-to-many, and one-to-one.
2.4.3 Activating models
That small bit of model code gives Django a lot of information. With it, Django is able to:
• Create a database schema (CREATE TABLE statements) for this app.
• Create a Python database-access API for accessing Question 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 mysite/settings.py file again, and change the INSTALLED_APPS setting to include the string
’polls.apps.PollsConfig’. It’ll look like this:
mysite/settings.py
INSTALLED_APPS = [
'polls.apps.PollsConfig',
'django.contrib.admin',
'django.contrib.auth',
'django.contrib.contenttypes',
'django.contrib.sessions',
'django.contrib.messages',
'django.contrib.staticfiles',
]
Now Django knows to include the polls app. Let’s run another command:
$ python manage.py makemigrations polls
You should see something similar to the following:
Migrations for 'polls':
0001_initial.py:
- Create model Choice
- Create model Question
- Add field question to choice
2.4. Writing your first Django app, part 2 21](/p?url=https%3A%2F%2Fimage.slidesharecdn.com%2F20160225-django-documentation-160225091707%2F85%2FDjango-Documentation-25-320.jpg&__src=https%3A%2F%2Fwww.slideshare.net%2Fslideshow%2Fdjango-documentation%2F58699702%2319&__type=image)
![Django Documentation, Release 1.9.3.dev20160224120324
>>> import django
>>> django.setup()
If this raises an AttributeError, you’re probably using a version of Django that doesn’t match this tutorial
version. You’ll want to either switch to the older tutorial or the newer Django version.
You must run python from the same directory manage.py is in, or ensure that directory is on the Python path, so
that import mysite works.
For more information on all of this, see the django-admin documentation.
Once you’re in the shell, explore the database API:
>>> from polls.models import Question, Choice # Import the model classes we just wrote.
# No questions are in the system yet.
>>> Question.objects.all()
[]
# Create a new Question.
# Support for time zones is enabled in the default settings file, so
# Django expects a datetime with tzinfo for pub_date. Use timezone.now()
# instead of datetime.datetime.now() and it will do the right thing.
>>> from django.utils import timezone
>>> q = Question(question_text="What's new?", pub_date=timezone.now())
# Save the object into the database. You have to call save() explicitly.
>>> q.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.
>>> q.id
1
# Access model field values via Python attributes.
>>> q.question_text
"What's new?"
>>> q.pub_date
datetime.datetime(2012, 2, 26, 13, 0, 0, 775217, tzinfo=<UTC>)
# Change values by changing the attributes, then calling save().
>>> q.question_text = "What's up?"
>>> q.save()
# objects.all() displays all the questions in the database.
>>> Question.objects.all()
[<Question: Question object>]
Wait a minute. <Question: Question object> is, utterly, an unhelpful representation of this object. Let’s
fix that by editing the Question model (in the polls/models.py file) and adding a __str__() method to
both Question and Choice:
polls/models.py
from django.db import models
from django.utils.encoding import python_2_unicode_compatible
24 Chapter 2. Getting started](/p?url=https%3A%2F%2Fimage.slidesharecdn.com%2F20160225-django-documentation-160225091707%2F85%2FDjango-Documentation-28-320.jpg&__src=https%3A%2F%2Fwww.slideshare.net%2Fslideshow%2Fdjango-documentation%2F58699702%2319&__type=image)
![Django Documentation, Release 1.9.3.dev20160224120324
@python_2_unicode_compatible # only if you need to support Python 2
class Question(models.Model):
# ...
def __str__(self):
return self.question_text
@python_2_unicode_compatible # only if you need to support Python 2
class Choice(models.Model):
# ...
def __str__(self):
return self.choice_text
It’s important to add __str__() methods to your models, not only for your own convenience when dealing with the
interactive prompt, but also because objects’ representations are used throughout Django’s automatically-generated
admin.
Note these are normal Python methods. Let’s add a custom method, just for demonstration:
polls/models.py
import datetime
from django.db import models
from django.utils import timezone
class Question(models.Model):
# ...
def was_published_recently(self):
return self.pub_date >= timezone.now() - datetime.timedelta(days=1)
Note the addition of import datetime and from django.utils import timezone, to reference
Python’s standard datetime module and Django’s time-zone-related utilities in django.utils.timezone,
respectively. If you aren’t familiar with time zone handling in Python, you can learn more in the time zone support
docs.
Save these changes and start a new Python interactive shell by running python manage.py shell again:
>>> from polls.models import Question, Choice
# Make sure our __str__() addition worked.
>>> Question.objects.all()
[<Question: What's up?>]
# Django provides a rich database lookup API that's entirely driven by
# keyword arguments.
>>> Question.objects.filter(id=1)
[<Question: What's up?>]
>>> Question.objects.filter(question_text__startswith='What')
[<Question: What's up?>]
# Get the question that was published this year.
>>> from django.utils import timezone
>>> current_year = timezone.now().year
>>> Question.objects.get(pub_date__year=current_year)
<Question: What's up?>
# Request an ID that doesn't exist, this will raise an exception.
>>> Question.objects.get(id=2)
2.4. Writing your first Django app, part 2 25](/p?url=https%3A%2F%2Fimage.slidesharecdn.com%2F20160225-django-documentation-160225091707%2F85%2FDjango-Documentation-29-320.jpg&__src=https%3A%2F%2Fwww.slideshare.net%2Fslideshow%2Fdjango-documentation%2F58699702%2319&__type=image)
![Django Documentation, Release 1.9.3.dev20160224120324
Traceback (most recent call last):
...
DoesNotExist: Question 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 Question.objects.get(id=1).
>>> Question.objects.get(pk=1)
<Question: What's up?>
# Make sure our custom method worked.
>>> q = Question.objects.get(pk=1)
>>> q.was_published_recently()
True
# Give the Question 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. Django creates
# a set to hold the "other side" of a ForeignKey relation
# (e.g. a question's choice) which can be accessed via the API.
>>> q = Question.objects.get(pk=1)
# Display any choices from the related object set -- none so far.
>>> q.choice_set.all()
[]
# Create three choices.
>>> q.choice_set.create(choice_text='Not much', votes=0)
<Choice: Not much>
>>> q.choice_set.create(choice_text='The sky', votes=0)
<Choice: The sky>
>>> c = q.choice_set.create(choice_text='Just hacking again', votes=0)
# Choice objects have API access to their related Question objects.
>>> c.question
<Question: What's up?>
# And vice versa: Question objects get access to Choice objects.
>>> q.choice_set.all()
[<Choice: Not much>, <Choice: The sky>, <Choice: Just hacking again>]
>>> q.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 question whose pub_date is in this year
# (reusing the 'current_year' variable we created above).
>>> Choice.objects.filter(question__pub_date__year=current_year)
[<Choice: Not much>, <Choice: The sky>, <Choice: Just hacking again>]
# Let's delete one of the choices. Use delete() for that.
>>> c = q.choice_set.filter(choice_text__startswith='Just hacking')
>>> c.delete()
For more information on model relations, see Accessing related objects. For more on how to use double underscores
to perform field lookups via the API, see Field lookups. For full details on the database API, see our Database API
reference.
26 Chapter 2. Getting started](/p?url=https%3A%2F%2Fimage.slidesharecdn.com%2F20160225-django-documentation-160225091707%2F85%2FDjango-Documentation-30-320.jpg&__src=https%3A%2F%2Fwww.slideshare.net%2Fslideshow%2Fdjango-documentation%2F58699702%2319&__type=image)
![Django Documentation, Release 1.9.3.dev20160224120324
def vote(request, question_id):
return HttpResponse("You're voting on question %s." % question_id)
Wire these new views into the polls.urls module by adding the following url() calls:
polls/urls.py
from django.conf.urls import url
from . import views
urlpatterns = [
# ex: /polls/
url(r'^$', views.index, name='index'),
# ex: /polls/5/
url(r'^(?P<question_id>[0-9]+)/$', views.detail, name='detail'),
# ex: /polls/5/results/
url(r'^(?P<question_id>[0-9]+)/results/$', views.results, name='results'),
# ex: /polls/5/vote/
url(r'^(?P<question_id>[0-9]+)/vote/$', views.vote, name='vote'),
]
Take a look in your browser, at “/polls/34/”. It’ll run the detail() method and display whatever ID you provide
in the URL. Try “/polls/34/results/” and “/polls/34/vote/” too – these will display the placeholder results and voting
pages.
When somebody requests a page from your website – say, “/polls/34/”, Django will load the mysite.urls 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. The include() functions we are using simply reference other URLconfs.
Note that the regular expressions for the include() functions don’t have a $ (end-of-string match character) but
rather a 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.
The idea behind include() is to make it easy to plug-and-play URLs. Since polls are in their own URLconf
(polls/urls.py), they can be placed under “/polls/”, or under “/fun_polls/”, or under “/content/polls/”, or any
other path root, and the app will still work.
Here’s what happens if a user goes to “/polls/34/” in this system:
• Django will find the match at ’^polls/’
• Then, Django will strip off the matching text ("polls/") and send the remaining text – "34/" – to the
‘polls.urls’ URLconf for further processing which matches r’^(?P<question_id>[0-9]+)/$’ resulting
in a call to the detail() view like so:
detail(request=<HttpRequest object>, question_id='34')
The question_id=’34’ part comes from (?P<question_id>[0-9]+). Using parentheses around a pattern
“captures” the text matched by that pattern and sends it as an argument to the view function; ?P<question_id>
defines the name that will be used to identify the matched pattern; and [0-9]+ 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 .html – unless you want to, in which case you can do something like this:
url(r'^polls/latest.html$', views.index),
But, don’t do that. It’s silly.
32 Chapter 2. Getting started](/p?url=https%3A%2F%2Fimage.slidesharecdn.com%2F20160225-django-documentation-160225091707%2F85%2FDjango-Documentation-36-320.jpg&__src=https%3A%2F%2Fwww.slideshare.net%2Fslideshow%2Fdjango-documentation%2F58699702%2319&__type=image)
![Django Documentation, Release 1.9.3.dev20160224120324
2.5.3 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 2. Here’s one stab at
a new index() view, which displays the latest 5 poll questions in the system, separated by commas, according to
publication date:
polls/views.py
from django.http import HttpResponse
from .models import Question
def index(request):
latest_question_list = Question.objects.order_by('-pub_date')[:5]
output = ', '.join([q.question_text for q in latest_question_list])
return HttpResponse(output)
# Leave the rest of the views (detail, results, vote) unchanged
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
by creating a template that the view can use.
First, create a directory called templates in your polls directory. Django will look for templates in there.
Your project’s TEMPLATES setting describes how Django will load and render templates. The default set-
tings file configures a DjangoTemplates backend whose APP_DIRS option is set to True. By convention
DjangoTemplates looks for a “templates” subdirectory in each of the INSTALLED_APPS.
Within the templates directory you have just created, create another directory called polls,
and within that create a file called index.html. In other words, your template should be at
polls/templates/polls/index.html. Because of how the app_directories template loader
works as described above, you can refer to this template within Django simply as polls/index.html.
Template namespacing
Now we might be able to get away with putting our templates directly in polls/templates (rather than creating
another polls subdirectory), but it would actually be a bad idea. Django will choose the first template it finds whose
name matches, and if you had a template with the same name in a different application, Django would be unable to
distinguish between them. We need to be able to point Django at the right one, and the easiest way to ensure this is by
namespacing them. That is, by putting those templates inside another directory named for the application itself.
Put the following code in that template:
polls/templates/polls/index.html
{% if latest_question_list %}
<ul>
{% for question in latest_question_list %}
2.5. Writing your first Django app, part 3 33](/p?url=https%3A%2F%2Fimage.slidesharecdn.com%2F20160225-django-documentation-160225091707%2F85%2FDjango-Documentation-37-320.jpg&__src=https%3A%2F%2Fwww.slideshare.net%2Fslideshow%2Fdjango-documentation%2F58699702%2319&__type=image)
![Django Documentation, Release 1.9.3.dev20160224120324
<li><a href="/polls/{{ question.id }}/">{{ question.question_text }}</a></li>
{% endfor %}
</ul>
{% else %}
<p>No polls are available.</p>
{% endif %}
Now let’s update our index view in polls/views.py to use the template:
polls/views.py
from django.http import HttpResponse
from django.template import loader
from .models import Question
def index(request):
latest_question_list = Question.objects.order_by('-pub_date')[:5]
template = loader.get_template('polls/index.html')
context = {
'latest_question_list': latest_question_list,
}
return HttpResponse(template.render(context, request))
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.
Load the page by pointing your browser at “/polls/”, and you should see a bulleted-list containing the “What’s up”
question from Tutorial 2. The link points to the question’s detail page.
A shortcut: render()
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:
polls/views.py
from django.shortcuts import render
from .models import Question
def index(request):
latest_question_list = Question.objects.order_by('-pub_date')[:5]
context = {'latest_question_list': latest_question_list}
return render(request, 'polls/index.html', context)
Note that once we’ve done this in all these views, we no longer need to import loader and HttpResponse (you’ll
want to keep HttpResponse if you still have the stub methods for detail, results, and vote).
The render() function takes the request object as its first argument, a template name as its second argument and a
dictionary as its optional third argument. It returns an HttpResponse object of the given template rendered with
the given context.
2.5.4 Raising a 404 error
Now, let’s tackle the question detail view – the page that displays the question text for a given poll. Here’s the view:
34 Chapter 2. Getting started](/p?url=https%3A%2F%2Fimage.slidesharecdn.com%2F20160225-django-documentation-160225091707%2F85%2FDjango-Documentation-38-320.jpg&__src=https%3A%2F%2Fwww.slideshare.net%2Fslideshow%2Fdjango-documentation%2F58699702%2319&__type=image)
![Django Documentation, Release 1.9.3.dev20160224120324
2.5.5 Use the template system
Back to the detail() view for our poll application. Given the context variable question, here’s what the
polls/detail.html template might look like:
polls/templates/polls/detail.html
<h1>{{ question.question_text }}</h1>
<ul>
{% for choice in question.choice_set.all %}
<li>{{ choice.choice_text }}</li>
{% endfor %}
</ul>
The template system uses dot-lookup syntax to access variable attributes. In the example of {{
question.question_text }}, first Django does a dictionary lookup on the object question. Failing that,
it tries an attribute lookup – which works, in this case. If attribute lookup had failed, it would’ve tried a list-index
lookup.
Method-calling happens in the {% for %} loop: question.choice_set.all is interpreted as the Python code
question.choice_set.all(), which returns an iterable of Choice objects and is suitable for use in the {%
for %} tag.
See the template guide for more about templates.
2.5.6 Removing hardcoded URLs in templates
Remember, when we wrote the link to a question in the polls/index.html template, the link was partially
hardcoded like this:
<li><a href="/polls/{{ question.id }}/">{{ question.question_text }}</a></li>
The problem with this hardcoded, tightly-coupled approach is that it becomes challenging to change URLs on projects
with a lot of templates. However, since you defined the name argument in the url() functions in the polls.urls
module, you can remove a reliance on specific URL paths defined in your url configurations by using the {% url
%} template tag:
<li><a href="{% url 'detail' question.id %}">{{ question.question_text }}</a></li>
The way this works is by looking up the URL definition as specified in the polls.urls module. You can see exactly
where the URL name of ‘detail’ is defined below:
...
# the 'name' value as called by the {% url %} template tag
url(r'^(?P<question_id>[0-9]+)/$', views.detail, name='detail'),
...
If you want to change the URL of the polls detail view to something else, perhaps to something like
polls/specifics/12/ instead of doing it in the template (or templates) you would change it in
polls/urls.py:
...
# added the word 'specifics'
url(r'^specifics/(?P<question_id>[0-9]+)/$', views.detail, name='detail'),
...
36 Chapter 2. Getting started](/p?url=https%3A%2F%2Fimage.slidesharecdn.com%2F20160225-django-documentation-160225091707%2F85%2FDjango-Documentation-40-320.jpg&__src=https%3A%2F%2Fwww.slideshare.net%2Fslideshow%2Fdjango-documentation%2F58699702%2319&__type=image)
![Django Documentation, Release 1.9.3.dev20160224120324
2.5.7 Namespacing URL names
The tutorial project has just one app, polls. In real Django projects, there might be five, ten, twenty apps or more.
How does Django differentiate the URL names between them? For example, the polls app has a detail view, and
so might an app on the same project that is for a blog. How does one make it so that Django knows which app view to
create for a url when using the {% url %} template tag?
The answer is to add namespaces to your URLconf. In the polls/urls.py file, go ahead and add an app_name
to set the application namespace:
polls/urls.py
from django.conf.urls import url
from . import views
app_name = 'polls'
urlpatterns = [
url(r'^$', views.index, name='index'),
url(r'^(?P<question_id>[0-9]+)/$', views.detail, name='detail'),
url(r'^(?P<question_id>[0-9]+)/results/$', views.results, name='results'),
url(r'^(?P<question_id>[0-9]+)/vote/$', views.vote, name='vote'),
]
Now change your polls/index.html template from:
polls/templates/polls/index.html
<li><a href="{% url 'detail' question.id %}">{{ question.question_text }}</a></li>
to point at the namespaced detail view:
polls/templates/polls/index.html
<li><a href="{% url 'polls:detail' question.id %}">{{ question.question_text }}</a></li>
When you’re comfortable with writing views, read part 4 of this tutorial to learn about simple form processing and
generic views.
2.6 Writing your first Django app, part 4
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.
2.6.1 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:
polls/templates/polls/detail.html
<h1>{{ question.question_text }}</h1>
{% if error_message %}<p><strong>{{ error_message }}</strong></p>{% endif %}
<form action="{% url 'polls:vote' question.id %}" method="post">
{% csrf_token %}
2.6. Writing your first Django app, part 4 37](/p?url=https%3A%2F%2Fimage.slidesharecdn.com%2F20160225-django-documentation-160225091707%2F85%2FDjango-Documentation-41-320.jpg&__src=https%3A%2F%2Fwww.slideshare.net%2Fslideshow%2Fdjango-documentation%2F58699702%2319&__type=image)
![Django Documentation, Release 1.9.3.dev20160224120324
{% for choice in question.choice_set.all %}
<input type="radio" name="choice" id="choice{{ forloop.counter }}" value="{{ choice.id }}" />
<label for="choice{{ forloop.counter }}">{{ choice.choice_text }}</label><br />
{% endfor %}
<input type="submit" value="Vote" />
</form>
A quick rundown:
• The above template displays a radio button for each question choice. The value of each radio button is the
associated question 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=# where # is the ID of
the selected choice. This is the basic concept of HTML forms.
• We set the form’s action to {% url ’polls:vote’ question.id %}, and we set
method="post". Using method="post" (as opposed to method="get") is very important, be-
cause 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.
• forloop.counter indicates how many times the for tag has gone through its loop
• Since we’re creating a POST form (which can have the effect of modifying data), we need to worry about Cross
Site Request Forgeries. Thankfully, you don’t have to worry too hard, because Django comes with a very easy-
to-use system for protecting against it. In short, all POST forms that are targeted at internal URLs should use
the {% csrf_token %} template tag.
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:
polls/urls.py
url(r'^(?P<question_id>[0-9]+)/vote/$', views.vote, name='vote'),
We also created a dummy implementation of the vote() function. Let’s create a real version. Add the following to
polls/views.py:
polls/views.py
from django.shortcuts import get_object_or_404, render
from django.http import HttpResponseRedirect, HttpResponse
from django.core.urlresolvers import reverse
from .models import Choice, Question
# ...
def vote(request, question_id):
question = get_object_or_404(Question, pk=question_id)
try:
selected_choice = question.choice_set.get(pk=request.POST['choice'])
except (KeyError, Choice.DoesNotExist):
# Redisplay the question voting form.
return render(request, 'polls/detail.html', {
'question': question,
'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
38 Chapter 2. Getting started](/p?url=https%3A%2F%2Fimage.slidesharecdn.com%2F20160225-django-documentation-160225091707%2F85%2FDjango-Documentation-42-320.jpg&__src=https%3A%2F%2Fwww.slideshare.net%2Fslideshow%2Fdjango-documentation%2F58699702%2319&__type=image)
![Django Documentation, Release 1.9.3.dev20160224120324
# user hits the Back button.
return HttpResponseRedirect(reverse('polls:results', args=(question.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 question 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/'
where the 3 is the value of question.id. This redirected URL will then call the ’results’ view to display
the final page.
As mentioned in Tutorial 3, request is an HttpRequest object. For more on HttpRequest objects, see the
request and response documentation.
After somebody votes in a question, the vote() view redirects to the results page for the question. Let’s write that
view:
polls/views.py
from django.shortcuts import get_object_or_404, render
def results(request, question_id):
question = get_object_or_404(Question, pk=question_id)
return render(request, 'polls/results.html', {'question': question})
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 polls/results.html template:
polls/templates/polls/results.html
<h1>{{ question.question_text }}</h1>
<ul>
{% for choice in question.choice_set.all %}
<li>{{ choice.choice_text }} -- {{ choice.votes }} vote{{ choice.votes|pluralize }}</li>
{% endfor %}
</ul>
2.6. Writing your first Django app, part 4 39](/p?url=https%3A%2F%2Fimage.slidesharecdn.com%2F20160225-django-documentation-160225091707%2F85%2FDjango-Documentation-43-320.jpg&__src=https%3A%2F%2Fwww.slideshare.net%2Fslideshow%2Fdjango-documentation%2F58699702%2319&__type=image)
![Django Documentation, Release 1.9.3.dev20160224120324
url(r'^$', views.IndexView.as_view(), name='index'),
url(r'^(?P<pk>[0-9]+)/$', views.DetailView.as_view(), name='detail'),
url(r'^(?P<pk>[0-9]+)/results/$', views.ResultsView.as_view(), name='results'),
url(r'^(?P<question_id>[0-9]+)/vote/$', views.vote, name='vote'),
]
Note that the name of the matched pattern in the regexes of the second and third patterns has changed from
<question_id> to <pk>.
Amend views
Next, we’re going to remove our old index, detail, and results views and use Django’s generic views instead.
To do so, open the polls/views.py file and change it like so:
polls/views.py
from django.shortcuts import get_object_or_404, render
from django.http import HttpResponseRedirect
from django.core.urlresolvers import reverse
from django.views import generic
from .models import Choice, Question
class IndexView(generic.ListView):
template_name = 'polls/index.html'
context_object_name = 'latest_question_list'
def get_queryset(self):
"""Return the last five published questions."""
return Question.objects.order_by('-pub_date')[:5]
class DetailView(generic.DetailView):
model = Question
template_name = 'polls/detail.html'
class ResultsView(generic.DetailView):
model = Question
template_name = 'polls/results.html'
def vote(request, question_id):
... # same as above, no changes needed.
We’re using two generic views here: ListView and DetailView. 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 model it will be acting upon. This is provided using the model attribute.
• The DetailView generic view expects the primary key value captured from the URL to be called "pk", so
we’ve changed question_id to pk for the generic views.
By default, the DetailView generic view uses a template called <app name>/<model
name>_detail.html. In our case, it would use the template "polls/question_detail.html".
The template_name attribute is used to tell Django to use a specific template name instead of the autogenerated
default template name. We also specify the template_name for the results list view – this ensures that the
2.6. Writing your first Django app, part 4 41](/p?url=https%3A%2F%2Fimage.slidesharecdn.com%2F20160225-django-documentation-160225091707%2F85%2FDjango-Documentation-45-320.jpg&__src=https%3A%2F%2Fwww.slideshare.net%2Fslideshow%2Fdjango-documentation%2F58699702%2319&__type=image)
![Django Documentation, Release 1.9.3.dev20160224120324
b'nnn <ul>n n <li><a href="/polls/1/">Who is your favorite Beatle?</a></li>n n
>>> # If the following doesn't work, you probably omitted the call to
>>> # setup_test_environment() described above
>>> response.context['latest_question_list']
[<Question: Who is your favorite Beatle?>]
Improving our view
The list of polls shows polls that aren’t published yet (i.e. those that have a pub_date in the future). Let’s fix that.
In Tutorial 4 we introduced a class-based view, based on ListView:
polls/views.py
class IndexView(generic.ListView):
template_name = 'polls/index.html'
context_object_name = 'latest_question_list'
def get_queryset(self):
"""Return the last five published questions."""
return Question.objects.order_by('-pub_date')[:5]
We need to amend the get_queryset() method and change it so that it also checks the date by comparing it with
timezone.now(). First we need to add an import:
polls/views.py
from django.utils import timezone
and then we must amend the get_queryset method like so:
polls/views.py
def get_queryset(self):
"""
Return the last five published questions (not including those set to be
published in the future).
"""
return Question.objects.filter(
pub_date__lte=timezone.now()
).order_by('-pub_date')[:5]
Question.objects.filter(pub_date__lte=timezone.now()) returns a queryset containing
Questions whose pub_date is less than or equal to - that is, earlier than or equal to - timezone.now.
Testing our new view
Now you can satisfy yourself that this behaves as expected by firing up the runserver, loading the site in your browser,
creating Questions with dates in the past and future, and checking that only those that have been published are
listed. You don’t want to have to do that every single time you make any change that might affect this - so let’s also
create a test, based on our shell session above.
Add the following to polls/tests.py:
polls/tests.py
from django.core.urlresolvers import reverse
48 Chapter 2. Getting started](/p?url=https%3A%2F%2Fimage.slidesharecdn.com%2F20160225-django-documentation-160225091707%2F85%2FDjango-Documentation-52-320.jpg&__src=https%3A%2F%2Fwww.slideshare.net%2Fslideshow%2Fdjango-documentation%2F58699702%2319&__type=image)
![Django Documentation, Release 1.9.3.dev20160224120324
and we’ll create a shortcut function to create questions as well as a new test class:
polls/tests.py
def create_question(question_text, days):
"""
Creates a question with the given `question_text` and published the
given number of `days` offset to now (negative for questions published
in the past, positive for questions that have yet to be published).
"""
time = timezone.now() + datetime.timedelta(days=days)
return Question.objects.create(question_text=question_text,
pub_date=time)
class QuestionViewTests(TestCase):
def test_index_view_with_no_questions(self):
"""
If no questions exist, an appropriate message should be displayed.
"""
response = self.client.get(reverse('polls:index'))
self.assertEqual(response.status_code, 200)
self.assertContains(response, "No polls are available.")
self.assertQuerysetEqual(response.context['latest_question_list'], [])
def test_index_view_with_a_past_question(self):
"""
Questions with a pub_date in the past should be displayed on the
index page.
"""
create_question(question_text="Past question.", days=-30)
response = self.client.get(reverse('polls:index'))
self.assertQuerysetEqual(
response.context['latest_question_list'],
['<Question: Past question.>']
)
def test_index_view_with_a_future_question(self):
"""
Questions with a pub_date in the future should not be displayed on
the index page.
"""
create_question(question_text="Future question.", days=30)
response = self.client.get(reverse('polls:index'))
self.assertContains(response, "No polls are available.",
status_code=200)
self.assertQuerysetEqual(response.context['latest_question_list'], [])
def test_index_view_with_future_question_and_past_question(self):
"""
Even if both past and future questions exist, only past questions
should be displayed.
"""
create_question(question_text="Past question.", days=-30)
create_question(question_text="Future question.", days=30)
response = self.client.get(reverse('polls:index'))
self.assertQuerysetEqual(
response.context['latest_question_list'],
['<Question: Past question.>']
2.7. Writing your first Django app, part 5 49](/p?url=https%3A%2F%2Fimage.slidesharecdn.com%2F20160225-django-documentation-160225091707%2F85%2FDjango-Documentation-53-320.jpg&__src=https%3A%2F%2Fwww.slideshare.net%2Fslideshow%2Fdjango-documentation%2F58699702%2319&__type=image)
![Django Documentation, Release 1.9.3.dev20160224120324
)
def test_index_view_with_two_past_questions(self):
"""
The questions index page may display multiple questions.
"""
create_question(question_text="Past question 1.", days=-30)
create_question(question_text="Past question 2.", days=-5)
response = self.client.get(reverse('polls:index'))
self.assertQuerysetEqual(
response.context['latest_question_list'],
['<Question: Past question 2.>', '<Question: Past question 1.>']
)
Let’s look at some of these more closely.
First is a question shortcut function, create_question, to take some repetition out of the process of creating
questions.
test_index_view_with_no_questions doesn’t create any questions, but checks the message: “No polls
are available.” and verifies the latest_question_list is empty. Note that the django.test.TestCase
class provides some additional assertion methods. In these examples, we use assertContains() and
assertQuerysetEqual().
In test_index_view_with_a_past_question, we create a question and verify that it appears in the list.
In test_index_view_with_a_future_question, we create a question with a pub_date in the future.
The database is reset for each test method, so the first question is no longer there, and so again the index shouldn’t
have any questions in it.
And so on. In effect, we are using the tests to tell a story of admin input and user experience on the site, and checking
that at every state and for every new change in the state of the system, the expected results are published.
Testing the DetailView
What we have works well; however, even though future questions don’t appear in the index, users can still reach them
if they know or guess the right URL. So we need to add a similar constraint to DetailView:
polls/views.py
class DetailView(generic.DetailView):
...
def get_queryset(self):
"""
Excludes any questions that aren't published yet.
"""
return Question.objects.filter(pub_date__lte=timezone.now())
And of course, we will add some tests, to check that a Question whose pub_date is in the past can be displayed,
and that one with a pub_date in the future is not:
polls/tests.py
class QuestionIndexDetailTests(TestCase):
def test_detail_view_with_a_future_question(self):
"""
The detail view of a question with a pub_date in the future should
return a 404 not found.
"""
50 Chapter 2. Getting started](/p?url=https%3A%2F%2Fimage.slidesharecdn.com%2F20160225-django-documentation-160225091707%2F85%2FDjango-Documentation-54-320.jpg&__src=https%3A%2F%2Fwww.slideshare.net%2Fslideshow%2Fdjango-documentation%2F58699702%2319&__type=image)
![Django Documentation, Release 1.9.3.dev20160224120324
2.9 Writing your first Django app, part 7
This tutorial begins where Tutorial 6 left off. We’re continuing the Web-poll application and will focus on customizing
the Django’s automatically-generated admin site that we first explored in Tutorial 2.
2.9.1 Customize the admin form
By registering the Question model with admin.site.register(Question), Django was able to construct
a default form representation. Often, you’ll want to customize how the admin form looks and works. You’ll do this by
telling Django the options you want when you register the object.
Let’s see how this works by reordering the fields on the edit form. Replace the
admin.site.register(Question) line with:
polls/admin.py
from django.contrib import admin
from .models import Question
class QuestionAdmin(admin.ModelAdmin):
fields = ['pub_date', 'question_text']
admin.site.register(Question, QuestionAdmin)
You’ll follow this pattern – create a model admin class, then pass it as the second argument to
admin.site.register() – any time you need to change the admin options for an model.
This particular change above makes the “Publication date” come before the “Question” field:
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:
polls/admin.py
54 Chapter 2. Getting started](/p?url=https%3A%2F%2Fimage.slidesharecdn.com%2F20160225-django-documentation-160225091707%2F85%2FDjango-Documentation-58-320.jpg&__src=https%3A%2F%2Fwww.slideshare.net%2Fslideshow%2Fdjango-documentation%2F58699702%2319&__type=image)
![Django Documentation, Release 1.9.3.dev20160224120324
from django.contrib import admin
from .models import Question
class QuestionAdmin(admin.ModelAdmin):
fieldsets = [
(None, {'fields': ['question_text']}),
('Date information', {'fields': ['pub_date']}),
]
admin.site.register(Question, QuestionAdmin)
The first element of each tuple in fieldsets is the title of the fieldset. Here’s what our form looks like now:
2.9.2 Adding related objects
OK, we have our Question admin page, but a Question has multiple Choices, and the admin page doesn’t display
choices.
Yet.
There are two ways to solve this problem. The first is to register Choice with the admin just as we did with
Question. That’s easy:
polls/admin.py
from django.contrib import admin
from .models import Choice, Question
# ...
admin.site.register(Choice)
2.9. Writing your first Django app, part 7 55](/p?url=https%3A%2F%2Fimage.slidesharecdn.com%2F20160225-django-documentation-160225091707%2F85%2FDjango-Documentation-59-320.jpg&__src=https%3A%2F%2Fwww.slideshare.net%2Fslideshow%2Fdjango-documentation%2F58699702%2319&__type=image)
![Django Documentation, Release 1.9.3.dev20160224120324
Now “Choices” is an available option in the Django admin. The “Add choice” form looks like this:
In that form, the “Question” field is a select box containing every question in the database. Django knows that a
ForeignKey should be represented in the admin as a <select> box. In our case, only one question exists at this
point.
Also note the “Add Another” link next to “Question.” 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 question” form. If you add a
question in that window and click “Save”, Django will save the question 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 Question object. Let’s make that happen.
Remove the register() call for the Choice model. Then, edit the Question registration code to read:
polls/admin.py
from django.contrib import admin
from .models import Choice, Question
class ChoiceInline(admin.StackedInline):
model = Choice
extra = 3
class QuestionAdmin(admin.ModelAdmin):
fieldsets = [
(None, {'fields': ['question_text']}),
('Date information', {'fields': ['pub_date'], 'classes': ['collapse']}),
]
inlines = [ChoiceInline]
admin.site.register(Question, QuestionAdmin)
This tells Django: “Choice objects are edited on the Question admin page. By default, provide enough fields for
56 Chapter 2. Getting started](/p?url=https%3A%2F%2Fimage.slidesharecdn.com%2F20160225-django-documentation-160225091707%2F85%2FDjango-Documentation-60-320.jpg&__src=https%3A%2F%2Fwww.slideshare.net%2Fslideshow%2Fdjango-documentation%2F58699702%2319&__type=image)
![Django Documentation, Release 1.9.3.dev20160224120324
You can improve that by giving that method (in polls/models.py) a few attributes, as follows:
polls/models.py
class Question(models.Model):
# ...
def was_published_recently(self):
return self.pub_date >= timezone.now() - datetime.timedelta(days=1)
was_published_recently.admin_order_field = 'pub_date'
was_published_recently.boolean = True
was_published_recently.short_description = 'Published recently?'
For more information on these method properties, see list_display.
Edit your polls/admin.py file again and add an improvement to the Question change list page: filters using
the list_filter. Add the following line to QuestionAdmin:
list_filter = ['pub_date']
That adds a “Filter” sidebar that lets people filter the change list by the pub_date field:
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 appropriate filter options: “Any date”, “Today”, “Past 7 days”, “This
month”, “This year”.
This is shaping up well. Let’s add some search capability:
search_fields = ['question_text']
That adds a search box at the top of the change list. When somebody enters search terms, Django will search the
question_text field. You can use as many fields as you’d like – although because it uses a LIKE query behind
the scenes, limiting the number of search fields to a reasonable number will make it easier for your database to do the
search.
Now’s also a good time to note that change lists give you free pagination. The default is to display 100
items per page. Change list pagination, search boxes, filters, date-hierarchies, and
column-header-ordering all work together like you think they should.
2.9.4 Customize the admin look and feel
Clearly, having “Django administration” 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.
60 Chapter 2. Getting started](/p?url=https%3A%2F%2Fimage.slidesharecdn.com%2F20160225-django-documentation-160225091707%2F85%2FDjango-Documentation-64-320.jpg&__src=https%3A%2F%2Fwww.slideshare.net%2Fslideshow%2Fdjango-documentation%2F58699702%2319&__type=image)
![Django Documentation, Release 1.9.3.dev20160224120324
Customizing your project’s templates
Create a templates directory in your project directory (the one that contains manage.py). Templates can live
anywhere on your filesystem that Django can access. (Django runs as whatever user your server runs.) However,
keeping your templates within the project is a good convention to follow.
Open your settings file (mysite/settings.py, remember) and add a DIRS option in the TEMPLATES setting:
mysite/settings.py
TEMPLATES = [
{
'BACKEND': 'django.template.backends.django.DjangoTemplates',
'DIRS': [os.path.join(BASE_DIR, 'templates')],
'APP_DIRS': True,
'OPTIONS': {
'context_processors': [
'django.template.context_processors.debug',
'django.template.context_processors.request',
'django.contrib.auth.context_processors.auth',
'django.contrib.messages.context_processors.messages',
],
},
},
]
DIRS is a list of filesystem directories to check when loading Django templates; it’s a search path.
Organizing templates
Just like the static files, we could have all our templates together, in one big templates directory, and it would work
perfectly well. However, templates that belongs to a particular application, we should put in the application’s template
directory (e.g. polls/templates) rather than the project’s (templates). We’ll discuss in more detail in the
reusable apps tutorial why we do this.
Now create a directory called admin inside templates, and copy the template admin/base_site.html
from within the default Django admin template directory in the source code of Django itself
(django/contrib/admin/templates) into that directory.
Where are the Django source files?
If you have difficulty finding where the Django source files are located on your system, run the following command:
$ python -c "import django; print(django.__path__)"
Then, just edit the file and replace {{ site_header|default:_(’Django administration’) }} (in-
cluding the curly braces) with your own site’s name as you see fit. You should end up with a section of code like:
{% block branding %}
<h1 id="site-name"><a href="{% url 'admin:index' %}">Polls Administration</a></h1>
{% endblock %}
We use this approach to teach you how to override templates. In an actual project, you would probably use
the django.contrib.admin.AdminSite.site_header attribute to more easily make this particular cus-
tomization.
2.9. Writing your first Django app, part 7 61](/p?url=https%3A%2F%2Fimage.slidesharecdn.com%2F20160225-django-documentation-160225091707%2F85%2FDjango-Documentation-65-320.jpg&__src=https%3A%2F%2Fwww.slideshare.net%2Fslideshow%2Fdjango-documentation%2F58699702%2319&__type=image)
![Django Documentation, Release 1.9.3.dev20160224120324
1. Add "polls" to your INSTALLED_APPS setting like this::
INSTALLED_APPS = [
...
'polls',
]
2. Include the polls URLconf in your project urls.py like this::
url(r'^polls/', include('polls.urls')),
3. Run `python manage.py migrate` to create the polls models.
4. Start the development server and visit http://127.0.0.1:8000/admin/
to create a poll (you'll need the Admin app enabled).
5. Visit http://127.0.0.1:8000/polls/ to participate in the poll.
4. Create a django-polls/LICENSE file. Choosing a license is beyond the scope of this tutorial, but suffice
it to say that code released publicly without a license is useless. Django and many Django-compatible apps
are distributed under the BSD license; however, you’re free to pick your own license. Just be aware that your
licensing choice will affect who is able to use your code.
5. Next we’ll create a setup.py file which provides details about how to build and install the app. A full
explanation of this file is beyond the scope of this tutorial, but the setuptools docs have a good explanation.
Create a file django-polls/setup.py with the following contents:
django-polls/setup.py
import os
from setuptools import find_packages, setup
with open(os.path.join(os.path.dirname(__file__), 'README.rst')) as readme:
README = readme.read()
# allow setup.py to be run from any path
os.chdir(os.path.normpath(os.path.join(os.path.abspath(__file__), os.pardir)))
setup(
name='django-polls',
version='0.1',
packages=find_packages(),
include_package_data=True,
license='BSD License', # example license
description='A simple Django app to conduct Web-based polls.',
long_description=README,
url='https://www.example.com/',
author='Your Name',
author_email='yourname@example.com',
classifiers=[
'Environment :: Web Environment',
'Framework :: Django',
'Framework :: Django :: X.Y', # replace "X.Y" as appropriate
'Intended Audience :: Developers',
'License :: OSI Approved :: BSD License', # example license
'Operating System :: OS Independent',
'Programming Language :: Python',
# Replace these appropriately if you are stuck on Python 2.
'Programming Language :: Python :: 3',
2.10. Advanced tutorial: How to write reusable apps 65](/p?url=https%3A%2F%2Fimage.slidesharecdn.com%2F20160225-django-documentation-160225091707%2F85%2FDjango-Documentation-69-320.jpg&__src=https%3A%2F%2Fwww.slideshare.net%2Fslideshow%2Fdjango-documentation%2F58699702%2319&__type=image)
![Django Documentation, Release 1.9.3.dev20160224120324
'Programming Language :: Python :: 3.4',
'Programming Language :: Python :: 3.5',
'Topic :: Internet :: WWW/HTTP',
'Topic :: Internet :: WWW/HTTP :: Dynamic Content',
],
)
6. Only Python modules and packages are included in the package by default. To include additional files,
we’ll need to create a MANIFEST.in file. The setuptools docs referred to in the previous step discuss
this file in more details. To include the templates, the README.rst and our LICENSE file, create a file
django-polls/MANIFEST.in with the following contents:
django-polls/MANIFEST.in
include LICENSE
include README.rst
recursive-include polls/static *
recursive-include polls/templates *
7. It’s optional, but recommended, to include detailed documentation with your app. Create an
empty directory django-polls/docs for future documentation. Add an additional line to
django-polls/MANIFEST.in:
recursive-include docs *
Note that the docs directory won’t be included in your package unless you add some files to it. Many Django
apps also provide their documentation online through sites like readthedocs.org.
8. Try building your package with python setup.py sdist (run from inside django-polls). This cre-
ates a directory called dist and builds your new package, django-polls-0.1.tar.gz.
For more information on packaging, see Python’s Tutorial on Packaging and Distributing Projects.
2.10.5 Using your own package
Since we moved the polls directory out of the project, it’s no longer working. We’ll now fix this by installing our
new django-polls package.
Installing as a user library
The following steps install django-polls as a user library. Per-user installs have a lot of advantages over installing
the package system-wide, such as being usable on systems where you don’t have administrator access as well as
preventing the package from affecting system services and other users of the machine.
Note that per-user installations can still affect the behavior of system tools that run as that user, so virtualenv is a
more robust solution (see below).
1. To install the package, use pip (you already installed it, right?):
pip install --user django-polls/dist/django-polls-0.1.tar.gz
2. With luck, your Django project should now work correctly again. Run the server again to confirm this.
3. To uninstall the package, use pip:
pip uninstall django-polls
66 Chapter 2. Getting started](/p?url=https%3A%2F%2Fimage.slidesharecdn.com%2F20160225-django-documentation-160225091707%2F85%2FDjango-Documentation-70-320.jpg&__src=https%3A%2F%2Fwww.slideshare.net%2Fslideshow%2Fdjango-documentation%2F58699702%2319&__type=image)
![Django Documentation, Release 1.9.3.dev20160224120324
While Django’s test suite is running, you’ll see a stream of characters representing the status of each test as it’s run.
E indicates that an error was raised during a test, and F indicates that a test’s assertions failed. Both of these are
considered to be test failures. Meanwhile, x and s indicated expected failures and skipped tests, respectively. Dots
indicate passing tests.
Skipped tests are typically due to missing external libraries required to run the test; see Running all the tests for a list
of dependencies and be sure to install any for tests related to the changes you are making (we won’t need any for this
tutorial).
Once the tests complete, you should be greeted with a message informing you whether the test suite passed or failed.
Since you haven’t yet made any changes to Django’s code, the entire test suite should pass. If you get failures or
errors make sure you’ve followed all of the previous steps properly. See Running the unit tests for more information.
Note that the latest Django trunk may not always be stable. When developing against trunk, you can check Django’s
continuous integration builds to determine if the failures are specific to your machine or if they are also present in
Django’s official builds. If you click to view a particular build, you can view the “Configuration Matrix” which shows
failures broken down by Python version and database backend.
Note: For this tutorial and the ticket we’re working on, testing against SQLite is sufficient, however, it’s possible (and
sometimes necessary) to run the tests using a different database.
2.12.7 Writing some tests for your ticket
In most cases, for a patch to be accepted into Django it has to include tests. For bug fix patches, this means writing a
regression test to ensure that the bug is never reintroduced into Django later on. A regression test should be written in
such a way that it will fail while the bug still exists and pass once the bug has been fixed. For patches containing new
features, you’ll need to include tests which ensure that the new features are working correctly. They too should fail
when the new feature is not present, and then pass once it has been implemented.
A good way to do this is to write your new tests first, before making any changes to the code. This style of development
is called test-driven development and can be applied to both entire projects and single patches. After writing your tests,
you then run them to make sure that they do indeed fail (since you haven’t fixed that bug or added that feature yet). If
your new tests don’t fail, you’ll need to fix them so that they do. After all, a regression test that passes regardless of
whether a bug is present is not very helpful at preventing that bug from reoccurring down the road.
Now for our hands-on example.
Writing some tests for ticket #24788
Ticket #24788 proposes a small feature addition: the ability to specify the class level attribute prefix on Form
classes, so that:
[...] forms which ship with apps could effectively namespace themselves such
that N overlapping form fields could be POSTed at once and resolved to the
correct form.
In order to resolve this ticket, we’ll add a prefix attribute to the BaseForm class. When creating instances of this
class, passing a prefix to the __init__() method will still set that prefix on the created instance. But not passing a
prefix (or passing None) will use the class-level prefix. Before we make those changes though, we’re going to write a
couple tests to verify that our modification functions correctly and continues to function correctly in the future.
Navigate to Django’s tests/forms_tests/tests/ folder and open the test_forms.py file. Add the fol-
lowing code on line 1674 right before the test_forms_with_null_boolean function:
74 Chapter 2. Getting started](/p?url=https%3A%2F%2Fimage.slidesharecdn.com%2F20160225-django-documentation-160225091707%2F85%2FDjango-Documentation-78-320.jpg&__src=https%3A%2F%2Fwww.slideshare.net%2Fslideshow%2Fdjango-documentation%2F58699702%2319&__type=image)
![Django Documentation, Release 1.9.3.dev20160224120324
+ >>> class PersonForm(forms.Form):
+ ... ...
+ ... prefix = 'person'
+
+.. versionadded:: 1.9
+
+ The ability to specify ``prefix`` on the form class was added.
diff --git a/docs/releases/1.9.txt b/docs/releases/1.9.txt
index 5b58f79..f9bb9de 100644
--- a/docs/releases/1.9.txt
+++ b/docs/releases/1.9.txt
@@ -161,6 +161,9 @@ Forms
:attr:`~django.forms.Form.field_order` attribute, the ``field_order``
constructor argument , or the :meth:`~django.forms.Form.order_fields` method.
+* A form prefix can be specified inside a form class, not only when
+ instantiating a form. See :ref:`form-prefix` for details.
+
Generic Views
^^^^^^^^^^^^^
diff --git a/tests/forms_tests/tests/test_forms.py b/tests/forms_tests/tests/test_forms.py
index 690f205..e07fae2 100644
--- a/tests/forms_tests/tests/test_forms.py
+++ b/tests/forms_tests/tests/test_forms.py
@@ -1671,6 +1671,18 @@ class FormsTestCase(SimpleTestCase):
self.assertEqual(p.cleaned_data['last_name'], 'Lennon')
self.assertEqual(p.cleaned_data['birthday'], datetime.date(1940, 10, 9))
+ def test_class_prefix(self):
+ # Prefix can be also specified at the class level.
+ class Person(Form):
+ first_name = CharField()
+ prefix = 'foo'
+
+ p = Person()
+ self.assertEqual(p.prefix, 'foo')
+
+ p = Person(prefix='bar')
+ self.assertEqual(p.prefix, 'bar')
+
def test_forms_with_null_boolean(self):
# NullBooleanField is a bit of a special case because its presentation (widget)
# is different than its data. This is handled transparently, though.
2.12.12 So what do I do next?
Congratulations, you’ve generated your very first Django patch! Now that you’ve got that under your belt, you can
put those skills to good use by helping to improve Django’s codebase. Generating patches and attaching them to Trac
tickets is useful, however, since we are using git - adopting a more git oriented workflow is recommended.
Since we never committed our changes locally, perform the following to get your git branch back to a good starting
point:
$ git reset --hard HEAD
$ git checkout master
78 Chapter 2. Getting started](/p?url=https%3A%2F%2Fimage.slidesharecdn.com%2F20160225-django-documentation-160225091707%2F85%2FDjango-Documentation-82-320.jpg&__src=https%3A%2F%2Fwww.slideshare.net%2Fslideshow%2Fdjango-documentation%2F58699702%2319&__type=image)
![Django Documentation, Release 1.9.3.dev20160224120324
Using models
Once you have defined your models, you need 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 myapp.models (the package structure that is
created for an application by the manage.py startapp script), INSTALLED_APPS should read, in part:
INSTALLED_APPS = [
#...
'myapp',
#...
]
When you add new apps to INSTALLED_APPS, be sure to run manage.py migrate, optionally making migra-
tions for them first with manage.py makemigrations.
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. Be careful not to choose field names that conflict with the models API like
clean, save, or delete.
Example:
from django.db import models
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, on_delete=models.CASCADE)
name = models.CharField(max_length=100)
release_date = models.DateField()
num_stars = models.IntegerField()
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 column type, which tells the database what kind of data to store (e.g. INTEGER, VARCHAR, TEXT).
• The default HTML widget to use when rendering a form field (e.g. <input type="text">, <select>).
• The minimal validation requirements, used in Django’s admin and in automatically-generated forms.
Django ships with dozens of built-in field types; you can find the complete list in the model field reference. You can
easily write your own fields if Django’s built-in ones don’t do the trick; see Writing custom model fields.
Field options
Each field takes a certain set of field-specific arguments (documented in the model field reference). For example,
CharField (and its subclasses) require a max_length argument which specifies the size of the VARCHAR database
3.2. Models and databases 85](/p?url=https%3A%2F%2Fimage.slidesharecdn.com%2F20160225-django-documentation-160225091707%2F85%2FDjango-Documentation-89-320.jpg&__src=https%3A%2F%2Fwww.slideshare.net%2Fslideshow%2Fdjango-documentation%2F58699702%2319&__type=image)
![Django Documentation, Release 1.9.3.dev20160224120324
from django.db import models
class Fruit(models.Model):
name = models.CharField(max_length=100, primary_key=True)
>>> fruit = Fruit.objects.create(name='Apple')
>>> fruit.name = 'Pear'
>>> fruit.save()
>>> Fruit.objects.values_list('name', flat=True)
['Apple', 'Pear']
unique If True, this field must be unique throughout the table.
Again, these are just short descriptions of the most common field options. Full details can be found in the common
model field option reference.
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 Field.primary_key, it won’t add the automatic id column.
Each model requires exactly one field to have primary_key=True (either explicitly declared or automatically
added).
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)
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,
on_delete=models.CASCADE,
verbose_name="the related poll",
)
sites = models.ManyToManyField(Site, verbose_name="list of sites")
place = models.OneToOneField(
Place,
on_delete=models.CASCADE,
verbose_name="related place",
)
3.2. Models and databases 87](/p?url=https%3A%2F%2Fimage.slidesharecdn.com%2F20160225-django-documentation-160225091707%2F85%2FDjango-Documentation-91-320.jpg&__src=https%3A%2F%2Fwww.slideshare.net%2Fslideshow%2Fdjango-documentation%2F58699702%2319&__type=image)
![Django Documentation, Release 1.9.3.dev20160224120324
class Membership(models.Model):
person = models.ForeignKey(Person, on_delete=models.CASCADE)
group = models.ForeignKey(Group, on_delete=models.CASCADE)
date_joined = models.DateField()
invite_reason = models.CharField(max_length=64)
When you set up the intermediary model, you explicitly specify foreign keys to the models that are involved in the
many-to-many relationship. This explicit declaration defines how the two models are related.
There are a few restrictions on the intermediate model:
• Your intermediate model must contain one - and only one - foreign key to the source model (this would
be Group in our example), or you must explicitly specify the foreign keys Django should use for the re-
lationship using ManyToManyField.through_fields. If you have more than one foreign key and
through_fields is not specified, a validation error will be raised. A similar restriction applies to the foreign
key to the target model (this would be Person in our example).
• For a model which has a many-to-many relationship to itself through an intermediary model, two foreign keys
to the same model are permitted, but they will be treated as the two (different) sides of the many-to-many
relationship. If there are more than two foreign keys though, you must also specify through_fields as
above, or a validation error will be raised.
• When defining a many-to-many relationship from a model to itself, using an intermediary model, you must use
symmetrical=False (see the model field reference).
Now that you have set up your ManyToManyField to use your intermediary model (Membership, in this case),
you’re ready to start creating some many-to-many relationships. You do this by creating instances of the intermediate
model:
>>> ringo = Person.objects.create(name="Ringo Starr")
>>> paul = Person.objects.create(name="Paul McCartney")
>>> beatles = Group.objects.create(name="The Beatles")
>>> m1 = Membership(person=ringo, group=beatles,
... date_joined=date(1962, 8, 16),
... invite_reason="Needed a new drummer.")
>>> m1.save()
>>> beatles.members.all()
[<Person: Ringo Starr>]
>>> ringo.group_set.all()
[<Group: The Beatles>]
>>> m2 = Membership.objects.create(person=paul, group=beatles,
... date_joined=date(1960, 8, 1),
... invite_reason="Wanted to form a band.")
>>> beatles.members.all()
[<Person: Ringo Starr>, <Person: Paul McCartney>]
Unlike normal many-to-many fields, you can’t use add, create, or assignment (i.e., beatles.members =
[...]) to create relationships:
# THIS WILL NOT WORK
>>> beatles.members.add(john)
# NEITHER WILL THIS
>>> beatles.members.create(name="George Harrison")
# AND NEITHER WILL THIS
>>> beatles.members = [john, paul, ringo, george]
Why? You can’t just create a relationship between a Person and a Group - you need to specify all the detail for the
relationship required by the Membership model. The simple add, create and assignment calls don’t provide a
90 Chapter 3. Using Django](/p?url=https%3A%2F%2Fimage.slidesharecdn.com%2F20160225-django-documentation-160225091707%2F85%2FDjango-Documentation-94-320.jpg&__src=https%3A%2F%2Fwww.slideshare.net%2Fslideshow%2Fdjango-documentation%2F58699702%2319&__type=image)
![Django Documentation, Release 1.9.3.dev20160224120324
way to specify this extra detail. As a result, they are disabled for many-to-many relationships that use an intermediate
model. The only way to create this type of relationship is to create instances of the intermediate model.
The remove() method is disabled for similar reasons. However, the clear() method can be used to remove all
many-to-many relationships for an instance:
>>> # Beatles have broken up
>>> beatles.members.clear()
>>> # Note that this deletes the intermediate model instances
>>> Membership.objects.all()
[]
Once you have established the many-to-many relationships by creating instances of your intermediate model, you can
issue queries. Just as with normal many-to-many relationships, you can query using the attributes of the many-to-
many-related model:
# Find all the groups with a member whose name starts with 'Paul'
>>> Group.objects.filter(members__name__startswith='Paul')
[<Group: The Beatles>]
As you are using an intermediate model, you can also query on its attributes:
# Find all the members of the Beatles that joined after 1 Jan 1961
>>> Person.objects.filter(
... group__name='The Beatles',
... membership__date_joined__gt=date(1961,1,1))
[<Person: Ringo Starr]
If you need to access a membership’s information you may do so by directly querying the Membership model:
>>> ringos_membership = Membership.objects.get(group=beatles, person=ringo)
>>> ringos_membership.date_joined
datetime.date(1962, 8, 16)
>>> ringos_membership.invite_reason
'Needed a new drummer.'
Another way to access the same information is by querying the many-to-many reverse relationship from a Person
object:
>>> ringos_membership = ringo.membership_set.get(group=beatles)
>>> ringos_membership.date_joined
datetime.date(1962, 8, 16)
>>> ringos_membership.invite_reason
'Needed a new drummer.'
One-to-one relationships 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 were 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; in fact, to handle this you’d typically use inheritance,
which involves an implicit one-to-one relation).
As with ForeignKey, a recursive relationship can be defined and references to as-yet undefined models can be
made.
3.2. Models and databases 91](/p?url=https%3A%2F%2Fimage.slidesharecdn.com%2F20160225-django-documentation-160225091707%2F85%2FDjango-Documentation-95-320.jpg&__src=https%3A%2F%2Fwww.slideshare.net%2Fslideshow%2Fdjango-documentation%2F58699702%2319&__type=image)
![Django Documentation, Release 1.9.3.dev20160224120324
Meta options
Give your model metadata by using an inner class Meta, like so:
from django.db import models
class Ox(models.Model):
horn_length = models.IntegerField()
class Meta:
ordering = ["horn_length"]
verbose_name_plural = "oxen"
Model metadata is “anything that’s not a field”, such as ordering options (ordering), database table name
(db_table), or human-readable singular and plural names (verbose_name and verbose_name_plural).
None are required, and adding class Meta to a model is completely optional.
A complete list of all possible Meta options can be found in the model option reference.
Model attributes
objects The most important attribute of a model is the Manager. It’s the interface through which database query
operations are provided to Django models and is used to retrieve the instances from the database. If no custom
Manager is defined, the default name is objects. Managers are only accessible via model classes, not the
model instances.
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:
from django.db import models
class Person(models.Model):
first_name = models.CharField(max_length=50)
last_name = models.CharField(max_length=50)
birth_date = models.DateField()
def baby_boomer_status(self):
"Returns the person's baby-boomer status."
import datetime
if self.birth_date < datetime.date(1945, 8, 1):
return "Pre-boomer"
elif self.birth_date < datetime.date(1965, 1, 1):
return "Baby boomer"
else:
return "Post-boomer"
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)
3.2. Models and databases 93](/p?url=https%3A%2F%2Fimage.slidesharecdn.com%2F20160225-django-documentation-160225091707%2F85%2FDjango-Documentation-97-320.jpg&__src=https%3A%2F%2Fwww.slideshare.net%2Fslideshow%2Fdjango-documentation%2F58699702%2319&__type=image)
![Django Documentation, Release 1.9.3.dev20160224120324
class Meta:
abstract = True
class Student(CommonInfo):
home_group = models.CharField(max_length=5)
The Student model will have three fields: name, age and home_group. The CommonInfo model cannot be
used as a normal Django model, since it is an abstract base class. It does not generate a database table or have a
manager, and cannot be instantiated or saved directly.
For many uses, this type of model inheritance will be exactly what you want. It provides a way to factor out common
information at the Python level, while still only creating one database table per child model at the database level.
Meta inheritance When an abstract base class is created, Django makes any Meta inner class you declared in the
base class available as an attribute. If a child class does not declare its own Meta class, it will inherit the parent’s Meta.
If the child wants to extend the parent’s Meta class, it can subclass it. For example:
from django.db import models
class CommonInfo(models.Model):
# ...
class Meta:
abstract = True
ordering = ['name']
class Student(CommonInfo):
# ...
class Meta(CommonInfo.Meta):
db_table = 'student_info'
Django does make one adjustment to the Meta class of an abstract base class: before installing the Meta attribute,
it sets abstract=False. This means that children of abstract base classes don’t automatically become abstract
classes themselves. Of course, you can make an abstract base class that inherits from another abstract base class. You
just need to remember to explicitly set abstract=True each time.
Some attributes won’t make sense to include in the Meta class of an abstract base class. For example, including
db_table would mean that all the child classes (the ones that don’t specify their own Meta) would use the same
database table, which is almost certainly not what you want.
Be careful with related_name If you are using the related_name attribute on a ForeignKey or
ManyToManyField, you must always specify a unique reverse name for the field. This would normally cause a
problem in abstract base classes, since the fields on this class are included into each of the child classes, with exactly
the same values for the attributes (including related_name) each time.
To work around this problem, when you are using related_name in an abstract base class (only), part of the name
should contain ’%(app_label)s’ and ’%(class)s’.
• ’%(class)s’ is replaced by the lower-cased name of the child class that the field is used in.
• ’%(app_label)s’ is replaced by the lower-cased name of the app the child class is contained within. Each
installed application name must be unique and the model class names within each app must also be unique,
therefore the resulting name will end up being different.
For example, given an app common/models.py:
from django.db import models
96 Chapter 3. Using Django](/p?url=https%3A%2F%2Fimage.slidesharecdn.com%2F20160225-django-documentation-160225091707%2F85%2FDjango-Documentation-100-320.jpg&__src=https%3A%2F%2Fwww.slideshare.net%2Fslideshow%2Fdjango-documentation%2F58699702%2319&__type=image)
Uploaded byYing wei (Joe) Chou
Django Documentation
The document provides an overview of the Django documentation, which contains tutorials, guides, and reference materials on the major components of the Django web framework, including the model layer, view layer, template layer, forms, and the development and deployment processes. It describes how the documentation is organized and where to find information on specific topics like databases, security, internationalization, and contributing to the Django project.
