https://docs.djangoproject.com/en/1.3/intro/tutorial01/
Projects vs. apps
What's the difference between a project and an app? An app is a Web
application that does something -- e.g., a Weblog system, a database of
public records or a simple poll app. A project is a collection of
configuration and apps for a particular Web site. A project can contain
multiple apps. An app can be in multiple projects.
To create your app, make sure you're in the mysite directory and type
this command:
python manage.py startapp polls
That'll create a directory polls, which is laid out like this:
polls/
__init__.py
models.py
tests.py
views.py
This directory structure will house the poll application.
The first step in writing a database Web app in Django is to define your models
-- essentially, your database layout, with additional metadata.
In our simple poll app, we'll create two models: polls and choices. A poll has
a question and a publication date. A choice has two fields: the text of the
choice and a vote tally. Each choice is associated with a poll.
These concepts are represented by simple Python classes. Edit the
polls/models.py file so it looks like this:
from django.db import models
class Poll(models.Model):
question = models.CharField(max_length=200)
pub_date = models.DateTimeField('date published')
class Choice(models.Model):
poll = models.ForeignKey(Poll)
choice = models.CharField(max_length=200)
votes = models.IntegerField()
The code is straightforward. Each model is represented by a class that
subclasses django.db.models.Model. Each model has a number of class
variables, each of which represents a database field in the model.
Each field is represented by an instance of a Field
class -- e.g., CharField for character fields and
DateTimeField for datetimes. This tells Django what
type of data each field holds.
The name of each Field instance (e.g. question or
pub_date ) is the field's name, in machine-friendly format. You'll use this
value in your Python code, and your database will use it as the column name.
You can use an optional first positional argument to a
Field to designate a human-readable name. That's used
in a couple of introspective parts of Django, and it doubles as documentation.
If this field isn't provided, Django will use the machine-readable name. In this
example, we've only defined a human-readable name for Poll.pub_date. For all
other fields in this model, the field's machine-readable name will suffice as
its human-readable name.
Some Field classes have required elements.
CharField, for example, requires that you give it a
max_length. That's used not only in the database
schema, but in validation, as we'll soon see.
Finally, note a relationship is defined, using
ForeignKey. That tells Django each Choice is related
to a single Poll. Django supports all the common database relationships:
many-to-ones, many-to-manys and one-to-ones.
Activating models
That small bit of model code gives Django a lot of information. With it, Django
is able to:
- Create a database schema (CREATE TABLE statements) for this app.
- Create a Python database-access API for accessing Poll and Choice objects.
But first we need to tell our project that the polls app is installed.
dit the settings.py file again, and change the
INSTALLED_APPS setting to include the string 'polls'. So
it'll look like this:
INSTALLED_APPS = (
'django.contrib.auth',
'django.contrib.contenttypes',
'django.contrib.sessions',
'django.contrib.sites',
'polls'
)
Now Django knows to include the polls app. Let's run another
command:
python manage.py sql polls
The syncdb command runs the sql from 'sqlall' on your database for
all apps in INSTALLED_APPS that don't already exist in your database.
This creates all the tables, initial data and indexes for any apps you have
added to your project since the last time you ran syncdb. syncdb can
be called as often as you like, and it will only ever create the tables that
don't exist.
Read the django-admin.py documentation for full
information on what the manage.py utility can do.