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目录，如果你还没有准备好，运行python manage.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 

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'. 如下

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语句):

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

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

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


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

 

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

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

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

 

评论

1 楼 liliang_xf 2009-01-14  

翻译的不错。