(翻译)Django 1.0 中文文档-----指导 第一部分

编写你的第一个Django程序

我们从一个例子开始学起

贯穿这个指导，我们将带你建立一个简单的投票程序

它由两个部分构成：
一个可以让人们看到投票的公开站点
一个可以让你增加修改删除的管理站点

我们假设你已经安装好了Django,你可以通过Python 脚本 import django 来查看Django是否已安装，如果运行成功没有报错，说明Django已经安装。

创建工程

如果这是你第一次使用Django，你需要注意下初始设置，也就是你需要自动生成Django工程的结构代码，一个Django实例的设置集合，包括数据库配置，Django功能选项，和应用程序的功能设置。

在命令行上，cd 命令进入你想要保存代码的目录，然后运行命令
django-admin.py startproject mysite. 将会创建一个名字为mysite的目录

如果你通过python setup.py安装的django,django-admin.py 会加入到系统 path 中，如果path里没有，你可以在path里创建链接到django-admin.py,
如 /usr/local/bin目录

我们看下startproject都创建了什么

mysite/
__init__.py /
manage.py
settings.py
urls.py

这些文件是:

__init__.py: 一个空文件，告诉python这个目录要被看作是python的包. (你可以阅读下python关于包的文档)

manage.py: 一个命令行工具，让你和django进行各种不通的交互。

settings.py: django配置文件.

urls.py: 为django工程声明URL; 网站的地址目录

服务开发

我们确认服务可工作，进入到mysite目录，如果你还没有准备好，运行pythonmanage.py runserver，你将会看到下面命令行输出

Validating models... 0 errors found. Django version 1.0, using settings 'mysite.settings' Development server is running at http://127.0.0.1:8000/ Quit the server with CONTROL-C.

你已经启动了Django服务，一个完全由python写的轻量级网页服务。
这个已经包含在Django中，因此你可以快速开发而不需要配置一个生产环境服务，如Apache工具，直到你已经开发完毕。

现在这注意下，这个服务不能用在生产环境，他只适合开发时使用。

现在服务启动运行，用浏览器访问地址 http://127.0.0.1:8000/ ，你将会看到
“welcome to Django” 页面。令人愉快的淡蓝色页面。

数据库设置

现在我们编辑 settings.py. 这是标准的python组件模块描述django的配置.

将这些配置改成你自己的数据库链接参数

DATABASE_ENGINE -- 支持 'postgresql_psycopg2', 'mysql' ， 'sqlite3'. 等

DATABASE_NAME -- 你的数据库名称，如果你用的是 SQLite, 填写你数据库文件路径; DATABASE_NAME 应该是个完整路径,包括文件名, 如果文件不存在, 第一次将会自动创建

DATABASE_USER -- 数据库的用户名，sqlite不需要

DATABASE_PASSWORD -- 数据库的密码，sqlite不需要

DATABASE_HOST -- 你的数据库主机. 如果在本机，这里可以不填 (sqlite不需要).

如果你刚刚接触数据库, 我们推荐你用简单的SQLITE (DATABASE_ENGINE ='sqlite3'). SQLite已经包含在python2.5以上版本,所以你不需要在安装他。

当你编辑settings.py时，注意INSTALLED_APPS部分的设置，这个变量控制了所有django实例里的应用程序，应用可以用在多个项目中，你可以打包分发用在其他工程中。

默认配置中, INSTALLED_APPS 包含了下面的应用, 都是来源django:

django.contrib.auth -- 一个认证系统.

django.contrib.contenttypes -- 一个内容类型架构.

django.contrib.sessions -- 一个会话架构.

django.contrib.sites -- 一个多站管理架构.

这些应用默认包含以方便大多数情况的应用.

每个应用都至少用到一个数据表,因此我们需要先在数据库中创建表. 我们可以通过运行下面的命令来实现
python manage.py syncdb
syncdb 命令 会查看 INSTALLED_APPS 设置并创建必要的数据表根据数据库设置参数. 你将会看到每个数据表创建的信息,并且会提示你是否创建一个认证系统的超级管理账号，继续。。
如果你有兴趣，可以运行数据库的客户端来查看被创建的数据表
创建模型

现在一个工程环境就创建起来了，你现在可以让他工作起来。
你写的每个django应用都包含爱一个python包中，你的python路径某个地方，遵循一个确定的规则。
django带有一个自动生成应用程序基本目录结构的功能，因此你可以专注写代码而不用创建目录。

在这篇指导里，我们简单的在mysite目录里创建我们的投票程序，因而应用将和工程联系起来，投票程序将关联到mysite.polls.
接下来，我们将讨论应用程序的解耦。

确定你在mysite目录，创建你的应用，执行这个命令
python manage.py startapp polls
创建一个polls目录，布局如下：
polls/
__init__.py
models.py
views.py
这个目录结构容纳投票程序。

第一步用django编写了一个数据库WEB应用，即将定义模型，本质上，你的数据库布局是依照另外的元数据。

在我们简单的投票程序里，我们将创建两个模型，polls和choices.一个投票有问题和发布日期。一个选项有两个字段：
选项文字和选票记录。每个选项关联一个投票。

这些概念用简单的python类描述出来，像下面这样编辑polls/models.py

Python代码



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()

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()

代码简单易懂，每个模型都是用django.db.models.Model的子类描述，每个模型有一些变量描述数据库字段。

每个字段用一个Field类实例描述，CharField用于字符字段,DateTimeField 用于时间日期，这样告诉django掌握每个字段的类型。

field实例的名字就是这个field字段的名字，是友好的格式，在python里取值用，在数据库中当做表列名用。

你可以为Field指定参数，增加可读性。

一些Field类有必填元素，例如CharField需要指定max_length,这个参数不只是用在数据库元数据上，还用户数据校验。

最后，注意关心定义，使用ForeignKey.这个告诉Django每个选项关联到一个单独的投票上，Django支持所有数据关系定义。
多对一，多对多，一对一。

激活模型

一小段模型代码为Django提供了很多信息，通过这个，DJANGO将做如下事情

为应用程序创建数据库元数据
为投票对象，选项对象创建数据库操作API

不过首先我们需要先告诉工程投票程序安装好

再次编辑settings.py，修改INSTALLED_APPS 设置，加入'mysite.polls'. 如下

Python代码



INSTALLED_APPS = (

'django.contrib.auth',

'django.contrib.contenttypes',

'django.contrib.sessions',

'django.contrib.sites',

'mysite.polls'

)

INSTALLED_APPS = (
'django.contrib.auth',
'django.contrib.contenttypes',
'django.contrib.sessions',
'django.contrib.sites',
'mysite.polls'
)

现在django知道mysite包含了polls应用. 我们运行另一个命令:

python manage.py sql polls

你应该会看到类似如下的输出 (创建poll和choice的sql语句):

Sql代码



BEGIN;

CREATE TABLE "polls_poll" (

"id" serial NOT NULL PRIMARY KEY,

"question" varchar(200) NOT NULL,

"pub_date" timestamp with time zone NOT NULL

);

CREATE TABLE "polls_choice" (

"id" serial NOT NULL PRIMARY KEY,

"poll_id" integer NOT NULL REFERENCES "polls_poll" ("id"),

"choice" varchar(200) NOT NULL,

"votes" integer NOT NULL

);

COMMIT;

BEGIN;
CREATE TABLE "polls_poll" (
"id" serial NOT NULL PRIMARY KEY,
"question" varchar(200) NOT NULL,
"pub_date" timestamp with time zone NOT NULL
);
CREATE TABLE "polls_choice" (
"id" serial NOT NULL PRIMARY KEY,
"poll_id" integer NOT NULL REFERENCES "polls_poll" ("id"),
"choice" varchar(200) NOT NULL,
"votes" integer NOT NULL
);
COMMIT;

注意下面的内容:

确切的输出会依赖你使用的数据库。
表名会自动根据应用名和小写的模型名组合生成。
主键会自动添加（你也可以指定）
根据协定，django会附加“_id”到外键字段名，当然你可以自己指定。
外键关系通过 REFERENCES 语句声明建立。
这里会根据不通数据库，各自功能字段生成对应的数据库语法SQL。这里我们用的是PostgreSQL，输出的是PostgreSQL语法SQL。
输出的SQL实际并没有在数据上执行，只是打印在屏幕上，如果你需要，你可以复制到数据库里执行，然而我们将会看到django提供了一个更简单的方法执行SQL到数据库。

如果你感兴趣，可以运行下面的命令：

python manage.py validate
-- 检查你的模型构造是否有错误
python manage.py sqlcustom polls
-- 输出自定义语句 (如表的修改和约束) 定义在应用程序里的.
python manage.py sqlclear polls
-- 为应用生成删除表语句, 根据的是你数据库里的表 .
python manage.py sqlindexes polls
-- 为你的应用输出创建索引语句.
python manage.py sqlall polls
-- 生成应用中所有的SQL,包含 sqlcustom, 和 sqlindexes 命令的.

查看这些命令输出可以帮助我们理解实际上在这下面发生了什么

现在, 再次运行 syncdb 创建表到你的数据库:

python manage.py syncdb

syncdb命令会将INSTALLED_APPS里的应用包含的模型创建到数据库中，已经创建的会跳过。

用API 运行

现在我们进入python交互命令模式，使用django提供的API，用下面命令

python manage.py shell

Python代码



>>> from mysite.polls.models import Poll, Choice # 引入模型.

# 系统里还没有投票.

>>> Poll.objects.all()

[]

# 创建投票.

>>> import datetime

>>> p = Poll(question="What's up?", pub_date=datetime.datetime.now())

# 把投票保存到数据库.

>>> p.save()

# Now it has an ID. Note that this might say "1L" instead of "1", depending

# on which database you're using. That's no biggie; it just means your

# database backend prefers to return integers as Python long integer

# objects.

>>> p.id

1

# Access database columns via Python attributes.

>>> p.question

"What's up?"

>>> p.pub_date

datetime.datetime(2007, 7, 15, 12, 00, 53)

# 修改时间并保存.

>>> p.pub_date = datetime.datetime(2007, 4, 1, 0, 0)

>>> p.save()

>>> from mysite.polls.models import Poll, Choice # 引入模型.

# 系统里还没有投票.
>>> Poll.objects.all()
[]

# 创建投票.
>>> import datetime
>>> p = Poll(question="What's up?", pub_date=datetime.datetime.now())

# 把投票保存到数据库.
>>> p.save()

# Now it has an ID. Note that this might say "1L" instead of "1", depending
# on which database you're using. That's no biggie; it just means your
# database backend prefers to return integers as Python long integer
# objects.
>>> p.id
1

# Access database columns via Python attributes.
>>> p.question
"What's up?"
>>> p.pub_date
datetime.datetime(2007, 7, 15, 12, 00, 53)

# 修改时间并保存.
>>> p.pub_date = datetime.datetime(2007, 4, 1, 0, 0)
>>> p.save()

# objects.all() 显示所有的投票.
>>> Poll.objects.all()
[<Poll: Poll object>]

等一下，这里[<Poll: Poll object>]对我们没有实际意义和帮助，我们可以给模型加一个__unicode__()

Python代码



class Poll(models.Model):

# ...

def __unicode__(self):

return self.question

class Choice(models.Model):

# ...

def __unicode__(self):

return self.choice

class Poll(models.Model):
# ...
def __unicode__(self):
return self.question

class Choice(models.Model):
# ...
def __unicode__(self):
return self.choice

这样我们就可以看到模型对象属性内容。

我们还可以定义其他方法为模型扩展功能。

Python代码



import datetime

# ...

class Poll(models.Model):

# ...

def was_published_today(self):

return self.pub_date.date() == datetime.date.today()

这里判断发布日期是否是今天，让我们再次进入交互命令模式。

>>> from mysite.polls.models import Poll, Choice

# 这里调用了 __unicode__() .

>>> Poll.objects.all()

[<Poll: What's up?>]

# Django 提供一个充血数据库API

# keyword arguments.

>>> Poll.objects.filter(id=1)

[<Poll: What's up?>]

>>> Poll.objects.filter(question__startswith='What')

[<Poll: What's up?>]

# Get the poll whose year is 2007. Of course, if you're going through this

# 查询2007年的投票.

>>> Poll.objects.get(pub_date__year=2007)

<Poll: What's up?>

>>> Poll.objects.get(id=2)

Traceback (most recent call last):

...

DoesNotExist: Poll matching query does not exist.

# Lookup by a primary key is the most common case, so Django provides a

# shortcut for primary-key exact lookups.

# 获取主键为1的投票 Poll.objects.get(id=1).

>>> Poll.objects.get(pk=1)

<Poll: What's up?>

# 调用自定义的方法.

>>> p = Poll.objects.get(pk=1)

>>> p.was_published_today()

False

# 为投票添加选项

# choice object, does the INSERT statement, adds the choice to the set

# of available choices and returns the new Choice object.

>>> p = Poll.objects.get(pk=1)

>>> p.choice_set.create(choice='Not much', votes=0)

<Choice: Not much>

>>> p.choice_set.create(choice='The sky', votes=0)

<Choice: The sky>

>>> c = p.choice_set.create(choice='Just hacking again', votes=0)

# Choice objects have API access to their related Poll objects.

>>> c.poll

<Poll: What's up?>

# 获取投票的所有选项.

>>> p.choice_set.all()

[<Choice: Not much>, <Choice: The sky>, <Choice: Just hacking again>]

>>> p.choice_set.count()

3

# The API automatically follows relationships as far as you need.

# Use double underscores to separate relationships.

# This works as many levels deep as you want; there's no limit.

# Find all Choices for any poll whose pub_date is in 2007.

>>> Choice.objects.filter(poll__pub_date__year=2007)

[<Choice: Not much>, <Choice: The sky>, <Choice: Just hacking again>]

# Let's delete one of the choices. Use delete() for that.

>>> c = p.choice_set.filter(choice__startswith='Just hacking')

>>> c.delete()

import datetime
# ...
class Poll(models.Model):
# ...
def was_published_today(self):
return self.pub_date.date() == datetime.date.today()

这里判断发布日期是否是今天，让我们再次进入交互命令模式。

>>> from mysite.polls.models import Poll, Choice

# 这里调用了 __unicode__() .
>>> Poll.objects.all()
[<Poll: What's up?>]

# Django 提供一个充血数据库API
# keyword arguments.
>>> Poll.objects.filter(id=1)
[<Poll: What's up?>]
>>> Poll.objects.filter(question__startswith='What')
[<Poll: What's up?>]

# Get the poll whose year is 2007. Of course, if you're going through this
# 查询2007年的投票.
>>> Poll.objects.get(pub_date__year=2007)
<Poll: What's up?>

>>> Poll.objects.get(id=2)
Traceback (most recent call last):
...
DoesNotExist: Poll matching query does not exist.

# Lookup by a primary key is the most common case, so Django provides a
# shortcut for primary-key exact lookups.
# 获取主键为1的投票 Poll.objects.get(id=1).
>>> Poll.objects.get(pk=1)
<Poll: What's up?>

# 调用自定义的方法.
>>> p = Poll.objects.get(pk=1)
>>> p.was_published_today()
False

# 为投票添加选项
# choice object, does the INSERT statement, adds the choice to the set
# of available choices and returns the new Choice object.
>>> p = Poll.objects.get(pk=1)
>>> p.choice_set.create(choice='Not much', votes=0)
<Choice: Not much>
>>> p.choice_set.create(choice='The sky', votes=0)
<Choice: The sky>
>>> c = p.choice_set.create(choice='Just hacking again', votes=0)

# Choice objects have API access to their related Poll objects.
>>> c.poll
<Poll: What's up?>

# 获取投票的所有选项.
>>> p.choice_set.all()
[<Choice: Not much>, <Choice: The sky>, <Choice: Just hacking again>]
>>> p.choice_set.count()
3

# The API automatically follows relationships as far as you need.
# Use double underscores to separate relationships.
# This works as many levels deep as you want; there's no limit.
# Find all Choices for any poll whose pub_date is in 2007.
>>> Choice.objects.filter(poll__pub_date__year=2007)
[<Choice: Not much>, <Choice: The sky>, <Choice: Just hacking again>]

# Let's delete one of the choices. Use delete() for that.
>>> c = p.choice_set.filter(choice__startswith='Just hacking')
>>> c.delete()