Browse files

magic-removal: Fixed #1464 -- Updated tutorial01 for magic-removal. T…

…hanks, Jeremy D.

git-svn-id: bcc190cf-cafb-0310-a4f2-bffc1f526a37
  • Loading branch information...
1 parent fd00f02 commit 404421895a5a25cc8a3e0b5eec4337a5339a4ea0 @adrianholovaty adrianholovaty committed Mar 17, 2006
Showing with 107 additions and 84 deletions.
  1. +1 −1 docs/middleware.txt
  2. +1 −1 docs/templates_python.txt
  3. +105 −82 docs/tutorial01.txt
@@ -96,7 +96,7 @@ Also removes the content from any response to a HEAD request and sets the
``Date`` and ``Content-Length`` response-headers.
Enables session support. See the `session documentation`_.
@@ -256,7 +256,7 @@ Using a ``Context`` as a stack comes in handy in some custom template tags, as
you'll see below.
Subclassing Context: RequestContext
Django comes with a special ``Context`` class,
``django.template.RequestContext``, that acts slightly differently than
@@ -72,8 +72,8 @@ command line::
Validating models...
0 errors found.
- Starting server on port 8000 with settings module 'myproject.settings'.
- Go to for Django.
+ Django version 0.92, using settings 'myproject.settings'
+ Development server is running at
Quit the server with CONTROL-C (Unix) or CTRL-BREAK (Windows).
(If you get an error about ``DATABASE_ENGINE``, edit your ```` file
@@ -124,30 +124,51 @@ database's connection parameters:
point. Do that with "``CREATE DATABASE database_name;``" within your
database's interactive prompt.
-Run the following command to initialize your database with Django's core
-database tables::
+While you're editing ````, take note of the ``INSTALLED_APPS``
+setting. That variable holds the names of all Django applications that are
+activated in this Django instance. Apps can be used in multiple projects,
+and you can distribute them.
- python init
+By default, ``INSTALLED_APPS`` contains the following apps, all of which come
+with Django::
-If you don't see any errors, it worked.
+ * ``django.contrib.auth`` -- An authentication system.
+ * ``django.contrib.contenttypes`` -- A framework for content types.
+ * ``django.contrib.sessions`` -- A session framework.
+ * ``django.contrib.sites`` -- A framework for managing multiple sites
+ with one Django installation.
+These applications are included by default as a convenience for the common case.
+Each of these applications makes use of at least one database table, though,
+so we need to create the tables in the database before we can use them. To do
+that, run the following command::
+ python syncdb
+The ``syncdb`` command looks at the ``INSTALLED_APPS`` setting and creates any
+necessary database tables according to the database settings in your
+```` file. You'll see a message for each database table it creates,
+and you'll get a prompt asking you if you'd like to create a superuser account
+for the authentication system. Go ahead and do that.
If you're interested, run the command-line client for your database and type
``\dt`` (PostgreSQL), ``SHOW TABLES;`` (MySQL), or ``.schema`` (SQLite) to
display the tables Django created.
-.. admonition:: About those database tables
+.. admonition:: For the minimalists
- The tables created by `` init`` are for sessions, authentication
- and other features Django provides. The next release of Django will have
- a "lite" version of the ``init`` command that won't install any database
- tables if you don't want them.
+ Like we said above, the default applications are included for the common
+ case, but not everybody needs them. If you don't need any or all of them,
+ feel free to comment-out or delete the appropriate line(s) from
+ ``INSTALLED_APPS`` before running ``syncdb``. The ``syncdb`` command will
+ only create tables for apps in ``INSTALLED_APPS``.
Creating models
Now that your environment -- a "project" -- is set up, you're set to start
-doing work. (You won't have to take care of that boring administrative stuff
+doing work.
Each application you write in Django consists of a Python package, somewhere
on your `Python path`_, that follows a certain convention. Django comes with a
@@ -176,9 +197,7 @@ That'll create a directory ``polls``, which is laid out like this::
- models/
This directory structure will house the poll application.
@@ -198,28 +217,28 @@ a question and a publication date. A choice has two fields: the text of the
choice and a vote tally. Each choice is associated with a poll.
These concepts are represented by simple Python classes. Edit the
-``polls/models/`` file so it looks like this::
+``polls/`` file so it looks like this::
- from django.core import meta
+ from django.db import models
- class Poll(meta.Model):
- question = meta.CharField(maxlength=200)
- pub_date = meta.DateTimeField('date published')
+ class Poll(models.Model):
+ question = models.CharField(maxlength=200)
+ pub_date = models.DateTimeField('date published')
- class Choice(meta.Model):
- poll = meta.ForeignKey(Poll)
- choice = meta.CharField(maxlength=200)
- votes = meta.IntegerField()
+ class Choice(models.Model):
+ poll = models.ForeignKey(Poll)
+ choice = models.CharField(maxlength=200)
+ votes = models.IntegerField()
The code is straightforward. Each model is represented by a class that
-subclasses ``django.core.meta.Model``. Each model has a number of class
+subclasses ``django.db.models.Model``. Each model has a number of class
variables, each of which represents a database field in the model.
-Each field is represented by an instance of a ``meta.*Field`` class -- e.g.,
-``meta.CharField`` for character fields and ``meta.DateTimeField`` for
+Each field is represented by an instance of a ``models.*Field`` class -- e.g.,
+``models.CharField`` for character fields and ``models.DateTimeField`` for
datetimes. This tells Django what type of data each field holds.
-The name of each ``meta.*Field`` instance (e.g. ``question`` or ``pub_date`` )
+The name of each ``models.*Field`` instance (e.g. ``question`` or ``pub_date`` )
is the field's name, in machine-friendly format. You'll use this value in your
Python code, and your database will use it as the column name.
@@ -230,11 +249,11 @@ the machine-readable name. In this example, we've only defined a human-readable
name for ``Poll.pub_date``. For all other fields in this model, the field's
machine-readable name will suffice as its human-readable name.
-Some ``meta.*Field`` classes have required elements. ``meta.CharField``, for
-example, requires that you give it a ``maxlength``. That's used not only in the
-database schema, but in validation, as we'll soon see.
+Some ``Field`` classes have required elements. ``CharField``, for example,
+requires that you give it a ``maxlength``. That's used not only in the database
+schema, but in validation, as we'll soon see.
-Finally, note a relationship is defined, using ``meta.ForeignKey``. That tells
+Finally, note a relationship is defined, using ``models.ForeignKey``. That tells
Django each Choice is related to a single Poll. Django supports all the common
database relationships: many-to-ones, many-to-manys and one-to-ones.
@@ -262,6 +281,10 @@ Edit the ```` file again, and change the ``INSTALLED_APPS`` setting
to include the string ``'myproject.polls'``. So it'll look like this::
+ 'django.contrib.auth',
+ 'django.contrib.contenttypes',
+ 'django.contrib.sessions',
+ 'django.contrib.sites',
@@ -275,12 +298,12 @@ Now Django knows ``myproject`` includes the ``polls`` app. Let's run another com
You should see the following (the CREATE TABLE SQL statements for the polls app)::
- CREATE TABLE "polls_polls" (
+ CREATE TABLE "polls_poll" (
"question" varchar(200) NOT NULL,
"pub_date" timestamp with time zone NOT NULL
- CREATE TABLE "polls_choices" (
+ CREATE TABLE "polls_choice" (
"poll_id" integer NOT NULL REFERENCES "polls_polls" ("id"),
"choice" varchar(200) NOT NULL,
@@ -291,12 +314,12 @@ You should see the following (the CREATE TABLE SQL statements for the polls app)
Note the following:
* Table names are automatically generated by combining the name of the app
- (``polls``) with a plural version of the object name (polls and choices).
- (You can override this behavior.)
+ (``polls``) and the lowercase name of the model -- ``poll`` and
+ ``choice``. (You can override this behavior.)
* Primary keys (IDs) are added automatically. (You can override this, too.)
- * Django appends ``"_id"`` to the foreign key field name, by convention.
+ * By convention, Django appends ``"_id"`` to the foreign key field name.
Yes, you can override this, as well.
* The foreign key relationship is made explicit by a ``REFERENCES`` statement.
@@ -306,12 +329,12 @@ Note the following:
``integer primary key`` (SQLite) are handled for you automatically. Same
goes for quoting of field names -- e.g., using double quotes or single
quotes. The author of this tutorial runs PostgreSQL, so the example
- output is inPostgreSQL syntax.
+ output is in PostgreSQL syntax.
If you're interested, also run the following commands:
- * ``python sqlinitialdata polls`` -- Outputs the initial-data
- inserts required for Django's admin framework.
+ * ``python sqlinitialdata polls`` -- Outputs any initial data
+ required for Django's admin framework and your models.
* ``python sqlclear polls`` -- Outputs the necessary ``DROP
TABLE`` statements for this app, according to which tables already exist
@@ -326,14 +349,13 @@ If you're interested, also run the following commands:
Looking at the output of those commands can help you understand what's actually
happening under the hood.
-Now, run this command to create the database tables for the polls app
+Now, run ``syncdb`` again to create those model tables in your database::
- python install polls
+ python syncdb
-Behind the scenes, all that command does is take the output of
-``python sqlall polls`` and execute it in the database pointed-to by
-your Django settings file.
+As a review, the ``syncdb`` command creates the tables for all apps in
+``INSTALLED_APPS`` that don't already exist in your database. So you can run it
+again and again, and it'll always just create the tables that don't exist.
Read the ` documentation`_ for full information on what the
```` utility can do.
@@ -374,17 +396,16 @@ things:
Once you're in the shell, explore the database API::
- # Modules are dynamically created within django.models.
- # Their names are plural versions of the model class names.
- >>> from django.models.polls import polls, choices
+ # Import the model classes we just wrote.
+ >>> from myproject.polls.models import Poll, Choice
# No polls are in the system yet.
- >>> polls.get_list()
+ >>> Poll.objects.all()
# Create a new Poll.
>>> from datetime import datetime
- >>> p = polls.Poll(question="What's up?",
+ >>> p = Poll(question="What's up?",
# Save the object into the database. You have to call save() explicitly.
@@ -407,20 +428,21 @@ Once you're in the shell, explore the database API::
# get_list() displays all the polls in the database.
- >>> polls.get_list()
+ >>> Poll.objects.all()
[<Poll object>]
Wait a minute. ``<Poll object>`` is, utterly, an unhelpful representation of
this object. Let's fix that by editing the polls model
-(in the ``polls/models/`` file) and adding a ``__repr__()`` method to
+(in the ``polls/`` file) and adding a ``__repr__()`` method to
both ``Poll`` and ``Choice``::
- class Poll(meta.Model):
+ class Poll(models.Model):
# ...
def __repr__(self):
return self.question
- class Choice(meta.Model):
+ class Choice(models.Model):
# ...
def __repr__(self):
return self.choice
@@ -432,81 +454,82 @@ representations are used throughout Django's automatically-generated admin.
Note these are normal Python methods. Let's add a custom method, just for
- class Poll(meta.Model):
+ class Poll(models.Model):
# ...
def was_published_today(self):
+ import datetime
return ==
-Note ``import datetime`` wasn't necessary. Each model method has access to
-a handful of commonly-used variables for convenience, including the
-``datetime`` module from the Python standard library.
+Note the addition of ``import datetime`` to reference Python's standard
+``datetime`` module.
Let's jump back into the Python interactive shell by running
``python shell`` again::
- >>> from django.models.polls import polls, choices
+ >>> from myproject.polls.models import Poll, Choice
# Make sure our __repr__() addition worked.
- >>> polls.get_list()
+ >>> Poll.objects.all()
[What's up?]
# Django provides a rich database lookup API that's entirely driven by
# keyword arguments.
- >>> polls.get_object(id__exact=1)
- What's up?
- >>> polls.get_object(question__startswith='What')
- What's up?
+ >>> Poll.objects.filter(id=1)
+ [What's up?]
+ >>> Poll.objects.filter(question__startswith='What')
+ [What's up?]
# Get the poll whose year is 2005. Of course, if you're going through this
# tutorial in another year, change as appropriate.
- >>> polls.get_object(pub_date__year=2005)
+ >>> Poll.objects.get(pub_date__year=2005)
What's up?
- >>> polls.get_object(id__exact=2)
+ >>> Poll.objects.get(id=2)
Traceback (most recent call last):
- PollDoesNotExist: Poll does not exist for {'id__exact': 2}
- >>> polls.get_list(question__startswith='What')
+ DoesNotExist: Poll does not exist for {'id': 2}
+ >>> Poll.objects.filter(question__startswith='What')
[What's up?]
# 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 polls.get_object(id__exact=1).
- >>> polls.get_object(pk=1)
+ # The following is identical to Poll.objects.get(id=1).
+ >>> Poll.objects.get(pk=1)
What's up?
# Make sure our custom method worked.
- >>> p = polls.get_object(pk=1)
+ >>> p = Poll.objects.get(pk=1)
>>> p.was_published_today()
# Give the Poll a couple of Choices. Each one of these method calls does an
# INSERT statement behind the scenes and returns the new Choice object.
- >>> p = polls.get_object(pk=1)
- >>> p.add_choice(choice='Not much', votes=0)
+ >>> p = Poll.objects.get(pk=1)
+ >>> p.choice_set.add(choice='Not much', votes=0)
Not much
- >>> p.add_choice(choice='The sky', votes=0)
+ >>> p.choice_set.add(choice='The sky', votes=0)
The sky
- >>> c = p.add_choice(choice='Just hacking again', votes=0)
+ >>> c = p.choice_set.add(choice='Just hacking again', votes=0)
# Choice objects have API access to their related Poll objects.
- >>> c.get_poll()
+ >>> c.poll
What's up?
# And vice versa: Poll objects get access to Choice objects.
- >>> p.get_choice_list()
+ >>> p.choice_set.all()
[Not much, The sky, Just hacking again]
- >>> p.get_choice_count()
+ >>> p.choice_set.all().count()
# The API automatically follows relationships as far as you need.
# Use double underscores to separate relationships.
# This works as many levels deep as you want. There's no limit.
# Find all Choices for any poll whose pub_date is in 2005.
- >>> choices.get_list(poll__pub_date__year=2005)
+ >>> Choice.objects.filter(poll__pub_date__year=2005)
[Not much, The sky, Just hacking again]
# Let's delete one of the choices. Use delete() for that.
- >>> c = p.get_choice(choice__startswith='Just hacking')
+ >>> c = p.choice_set.filter(choice__startswith='Just hacking')
>>> c.delete()
For full details on the database API, see our `Database API reference`_.

0 comments on commit 4044218

Please sign in to comment.