(翻译)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代码

1. from django.db import models  
2.   
3.   
4. class Poll(models.Model):  
5.     question = models.CharField(max_length=200)  
6.     pub_date = models.DateTimeField('date published')  
7.   
8.   
9. class Choice(models.Model):  
10.     poll = models.ForeignKey(Poll)  
11.     choice = models.CharField(max_length=200)  
12.     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代码

1. INSTALLED_APPS = (  
2.     'django.contrib.auth',  
3.     'django.contrib.contenttypes',  
4.     'django.contrib.sessions',  
5.     'django.contrib.sites',  
6.     'mysite.polls'  
7. )  

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代码

1. BEGIN;  
2. CREATE TABLE "polls_poll" (  
3.     "id" serial NOT NULL PRIMARY KEY,  
4.     "question" varchar(200) NOT NULL,  
5.     "pub_date" timestamp with time zone NOT NULL  
6. );  
7. CREATE TABLE "polls_choice" (  
8.     "id" serial NOT NULL PRIMARY KEY,  
9.     "poll_id" integer NOT NULL REFERENCES "polls_poll" ("id"),  
10.     "choice" varchar(200) NOT NULL,  
11.     "votes" integer NOT NULL  
12. );  
13. 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代码

1. >>> from mysite.polls.models import Poll, Choice # 引入模型.  
2.   
3.   
4. # 系统里还没有投票.  
5. >>> Poll.objects.all()  
6. []  
7.   
8.   
9. # 创建投票.  
10. >>> import datetime  
11. >>> p = Poll(question="What's up?", pub_date=datetime.datetime.now())  
12.   
13.   
14. # 把投票保存到数据库.  
15. >>> p.save()  
16.   
17.   
18. # Now it has an ID. Note that this might say "1L" instead of "1", depending  
19. # on which database you're using. That's no biggie; it just means your  
20. # database backend prefers to return integers as Python long integer  
21. # objects.  
22. >>> p.id  
23. 1  
24.   
25.   
26. # Access database columns via Python attributes.  
27. >>> p.question  
28. "What's up?"  
29. >>> p.pub_date  
30. datetime.datetime(2007, 7, 15, 12, 00, 53)  
31.   
32.   
33. # 修改时间并保存.  
34. >>> p.pub_date = datetime.datetime(2007, 4, 1, 0, 0)  
35. >>> 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代码

1. class Poll(models.Model):  
2.     # ...  
3.     def __unicode__(self):  
4.         return self.question  
5.   
6.   
7. class Choice(models.Model):  
8.     # ...  
9.     def __unicode__(self):  
10.         return self.choice  

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


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

 

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

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

Python代码

1. import datetime  
2. # ...  
3. class Poll(models.Model):  
4.     # ...  
5.     def was_published_today(self):  
6.         return self.pub_date.date() == datetime.date.today()  
7.   
8.   
9. 这里判断发布日期是否是今天，让我们再次进入交互命令模式。  
10.   
11.   
12. >>> from mysite.polls.models import Poll, Choice  
13.   
14.   
15. # 这里调用了 __unicode__() .  
16. >>> Poll.objects.all()  
17. [<Poll: What's up?>]  
18.   
19.   
20. # Django 提供一个充血数据库API  
21. # keyword arguments.  
22. >>> Poll.objects.filter(id=1)  
23. [<Poll: What's up?>]  
24. >>> Poll.objects.filter(question__startswith='What')  
25. [<Poll: What's up?>]  
26.   
27.   
28. # Get the poll whose year is 2007. Of course, if you're going through this  
29. # 查询2007年的投票.  
30. >>> Poll.objects.get(pub_date__year=2007)  
31. <Poll: What's up?>  
32.   
33.   
34. >>> Poll.objects.get(id=2)  
35. Traceback (most recent call last):  
36.     ...  
37. DoesNotExist: Poll matching query does not exist.  
38.   
39.   
40. # Lookup by a primary key is the most common case, so Django provides a  
41. # shortcut for primary-key exact lookups.  
42. # 获取主键为1的投票 Poll.objects.get(id=1).  
43. >>> Poll.objects.get(pk=1)  
44. <Poll: What's up?>  
45.   
46.   
47. # 调用自定义的方法.  
48. >>> p = Poll.objects.get(pk=1)  
49. >>> p.was_published_today()  
50. False  
51.   
52.   
53. # 为投票添加选项  
54. # choice object, does the INSERT statement, adds the choice to the set  
55. # of available choices and returns the new Choice object.  
56. >>> p = Poll.objects.get(pk=1)  
57. >>> p.choice_set.create(choice='Not much', votes=0)  
58. <Choice: Not much>  
59. >>> p.choice_set.create(choice='The sky', votes=0)  
60. <Choice: The sky>  
61. >>> c = p.choice_set.create(choice='Just hacking again', votes=0)  
62.   
63.   
64. # Choice objects have API access to their related Poll objects.  
65. >>> c.poll  
66. <Poll: What's up?>  
67.   
68.   
69. # 获取投票的所有选项.  
70. >>> p.choice_set.all()  
71. [<Choice: Not much>, <Choice: The sky>, <Choice: Just hacking again>]  
72. >>> p.choice_set.count()  
73. 3  
74.   
75.   
76. # The API automatically follows relationships as far as you need.  
77. # Use double underscores to separate relationships.  
78. # This works as many levels deep as you want; there's no limit.  
79. # Find all Choices for any poll whose pub_date is in 2007.  
80. >>> Choice.objects.filter(poll__pub_date__year=2007)  
81. [<Choice: Not much>, <Choice: The sky>, <Choice: Just hacking again>]  
82.   
83.   
84. # Let's delete one of the choices. Use delete() for that.  
85. >>> c = p.choice_set.filter(choice__startswith='Just hacking')  
86. >>> 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()