Django 1.8.2 文档

编写你的Django应用,第1部分

让我们通过例子学习。

本教程中,我们将带领你创建一个基本的投票应用。

它包含两部分:

  • 一个公开的网站,可以让访客查看投票的结果并让他们进行投票。
  • 一个后台管理网站,你可以添加、修改和删除选票。

如果你已经安装了Django你可以运行下面的命令来查看你的Django版本号

$ python -c "import django; print(django.get_version())"

如果Django已经安装,你应该看到安装的版本号。如果还没有安装,你会看到一个“No module named django”的错误。

本教程是针对Django 1.8和Python 3.2或更高版本编写的。如果Django版本不符,可以通过当前页面右下角的版本转换器查看适用于你所使用的版本的Django教程,或者把Django升级到最新的版本。如果你还在使用2.7版本的Python,你将需要按照注释中的内容稍微调整一下示例代码。

关于如何删除旧版本的Django并安装一个新的,请参见如何安装 Django中的建议。

你可以在下列地址寻求帮助:

如果您在学习本教程的过程中遇到问题,请向django-users发送邮件或者访问#django on irc.freenode.net与其他可能会帮助你的Django用户交流。

创建一个项目

如果这是你第一次使用Django,你需要完成一些初始化设置。 你需要自己用代码来创建一个Django项目 ——一个Django框架开发的网站,创建项目后我们需要的配置的东西,包括数据库的配置、针对Django的配置选项和app的配置选项。

在命令行(终端)中,cd(例如cd exam)到你想要用来保存代码的目录,然后运行如下命令:

$ django-admin startproject mysite

这将会在你的当前目录下生成一个 mysite 目录。如果它不能正常工作,请查看运行django-admin遇到的问题

注意

你给项目命名时,项目名称不能和Python或Django的 内部组件名称同名。尤其,你应该避免使用类似django(与Django自身冲突)或 test(与Python内建的包冲突)这样的名称。

代码应该存在哪里?

如果你曾经学过普通的旧式的PHP(没有使用过现代的框架),你可能习惯于将代码放在Web服务器的文档根目录下(例如/var/www)。但是对于Django,你不该这么做。将Python代码放在你的Web服务器的根目录不是个好主意,因为它可能会有让别人在网上看到你的代码的风险。这样不安全。

将你的代码放置在Web服务器根目录以外的地方,例如/home/mycode

让我们看一下startproject生成了什么:

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

这些文件是:

  • 外层的mysite/根目录仅仅是项目的一个容器。它的命名对Django无关紧要;你可以把它重新命名为任何你喜欢的名字。
  • manage.py:一个命令行工具,可以使你用多种方式对Django项目进行交互。 你可以在django-admin和manage.py中读到关于manage.py的所有细节。
  • 内层的mysite/目录是你的项目的真正的Python包。它是你导入任何东西时将需要使用的Python包的名字(例如 mysite.urls)。
  • mysite/__init__.py:一个空文件,它告诉Python这个目录应该被看做一个Python包。 (如果你是一个Python初学者,关于包的更多内容请阅读Python的官方文档)。
  • mysite/settings.py:该Django 项目的设置/配置。Django 设置 将告诉你这些设置如何工作。
  • mysite/urls.py:该Django项目的URL声明;你的Django站点的“目录”。 你可以在URL 转发器 中阅读到更多关于URL的内容。
  • mysite/wsgi.py:用于你的项目的与WSGI兼容的Web服务器入口。 更多细节请参见如何利用WSGI进行部署

数据库的建立

现在,编辑mysite/settings.py它是一个用模块级别变量表示 Django 配置的普通 Python 模块。

默认情况下,该配置使用SQLite。如果你是数据库初学者,或者你只是想要试用一下Django,它是最简单的选择。 SQLite包含在Python中,所以你不需要另外安装其他任何东西来支持你的数据库。然而,当你开始第一个真正的项目时,你可能想使用一个更健壮的数据库比如PostgreSQL来避免在未来遇到令人头疼的数据库切换问题。

如果你希望使用另外一种数据库,请配置合适的database binding,并在 DATABASES 'default'条目中修改以下的配置以匹配你的数据库连接的设置:

  • ENGINE'django.db.backends.sqlite3', 'django.db.backends.postgresql_psycopg2', 'django.db.backends.mysql''django.db.backends.oracle'其它的后台也可以支持
  • NAME –  数据库的名称。如果你使用SQLite,数据库将是你计算机上的一个文件; 如果是这样的话,NAME应该是这个文件的绝对路径,包括文件名。默认值是os.path.join(BASE_DIR, 'db.sqlite3'),它将文件保存在你项目的目录中。

当你的项目使用SQLite之外的其他数据库引擎时,就必须添加USERPASSWORDHOST等额外的设置。 更多的细节,请参见DATABASES的参考文档。

如果你使用PostgreSQL或者MySQL,确保到此你已经建立好一个数据库。 可以在你的数据库的交互式提示命令下,使用“CREATE DATABASE database_name;”创建它。

如果你使用SQLite,你不需要事先创建任何东西 —— 数据库文件将会在需要的时候自动创建。

当你编辑mysite/settings.py时,请设置TIME_ZONE为你自己的时区。

另外,请注意文件顶端的INSTALLED_APPS设置。它保存这个Django实例中激活的所有的Django应用的名字。 应用可以在多个项目中使用,而且你可以将这些应用打包和分发给其他人在他们的项目中使用。

默认情况下,INSTALLED_APPS包含下面的应用,它们都是Django 与生俱来的:

这些应用,默认包含在Django中,以方便通用场合下使用。

然而上面的部分应用至少需要使用一个数据库表,因此我们需要在使用它们之前先在数据库中创建相应的表。要做到这一点,请运行以下命令:

$ python manage.py migrate

migrate查看INSTALLED_APPS设置并根据mysite/settings.py文件中的数据库设置创建任何必要的数据库表,数据库的迁移还会跟踪应用的变化(我们稍后会讲到)。user如果你有兴趣,可以运行你的数据库的命令行客户端并输入dt (PostgreSQL), SHOW TABLES; (MySQL)或.schema (SQLite)来显示Django创建的表。

对于极简主义者来说

就像我们上面说到的,以上包含的默认应用用于常见的场景,但并不是每个人都需要它们。 如果你不需要它们中的任何一个或所有应用,可以在运行migrate之前从INSTALLED_APPS中自由地注释或删除相应的行。migrate 命令将只为INSTALLED_APPS中的应用运行数据库的迁移。

开发服务器

让我们验证一下你的Django项目是否工作。 如果你不在外层的mysite目录下,那么进入这个目录,然后运行以下命令:

$ python manage.py runserver

你将看到命令行下输出了以下内容:

Performing system checks...

0 errors found
May 13, 2015 - 15:50:53
Django version 1.8, using settings 'mysite.settings'
Starting development server at http://127.0.0.1:8000/
Quit the server with CONTROL-C.

这表明你已经启动了Django开发服务器,一个用纯Python写的轻量级Web服务器。 我们在Django中内置了它,这样你就可以在不配置用于生产环境的服务器 —— 例如Apache —— 的情况下快速开发出产品,直到你准备好上线。

请注意:不要在任何生产环境使用这个服务器。它仅仅是用于在开发中使用。(我们的重点是编写Web框架,非Web服务器。)

既然服务器已经运行,请用你的浏览器访问 http://127.0.0.1:8000/在淡蓝色背景下,你将看到一个“Welcome to Django”的页面。 它运行成功了!

更改端口

默认情况下,runserver命令在内部IP的8000端口启动开发服务器。

如果你需改变服务器的端口,把要使用的端口作为一个命令行参数传递给它。 例如,这个命令在8080端口启动服务器:

$ python manage.py runserver 8080

如果你需改变服务器的IP地址,把IP地址和端口号放到一起。 因此若要监听所有的外网IP,请使用(如果你想在另外一台电脑上展示你的工作,会非常有用):

$ python manage.py runserver 0.0.0.0:8000

开发服务器的所有文档可以在runserver的参考手册中找到。

runserver的自动重载

开发服务器会根据需要自动重新载入Python代码。 你不必为了使更改的代码生效而重启服务器。 然而,一些行为比如添加文件,不会触发服务器的重启,所以在这种情况下你需要手动重启服务器。

创建模型

现在,你的开发环境 —— 一个“项目” —— 已经建立起来,你将开始在上面做一些东西。

你编写的每个Django应用都是遵循特定约定且包含一个Python包。 Django自带一个工具,它可以自动生成应用的基本目录结构,这样你就能专心于书写代码而不是创建目录。

项目 vs. 应用

项目和应用之间有什么不同? 应用是一个Web应用程序,它完成具体的事项 —— 比如一个博客系统、一个存储公共档案的数据库或者一个简单的投票应用。 项目是一个特定网站中相关配置和应用的集合。一个项目可以包含多个应用。一个应用可以运用到多个项目中去。

你的应用可以放在Python path上的任何位置。在本教程中,我们将在你的manage.py文件同级目录创建我们的投票应用,以便可以将它作为顶层模块导入,而不是mysite的子模块。

要创建您的应用程序,请确保您与manage.py在同一目录中,并键入以下命令:

$ python manage.py startapp polls

这将创建一个目录polls,它的结构如下:

polls/
    __init__.py
    admin.py
    migrations/
        __init__.py
    models.py
    tests.py
    views.py

我们的polls应用将基于这个目录结构。

当编写一个数据库驱动的Web应用时,第一步就是定义该应用的模型 —— 本质上,就是定义该模型所对应的数据库设计及其附带的元数据。

原理

模型指出了数据的唯一、明确的真实来源。 它包含了正在存储的数据的基本字段和行为。 Django遵循DRY (Don't repeat yourself)原则这个原则的目标是在一个地方定义你的数据模型,并自动从它获得需要的信息。

迁移工具也符合以上哲学 —— 这不同于Ruby On Rails中的迁移;例如,迁移完全依照于你的模型文件且本质上只是一个历史记录,Django通过这个历史记录更新你的数据库模式使它与你现在的模型文件保持一致。

在这个简单的投票应用中,我们将创建两个模型: QuestionChoiceQuestion对象具有一个question_text(问题)属性和一个publish_date(发布时间)属性。 Choice有两个字段:选择的内容和选择的得票统计。 每个Choice与一个Question关联。

这些概念通过简单的Python类来表示。 编辑polls/models.py文件,并让它看起来像这样:

polls/models.py
from django.db import models


class Question(models.Model):
    question_text = models.CharField(max_length=200)
    pub_date = models.DateTimeField('date published')


class Choice(models.Model):
    question = models.ForeignKey(Question)
    choice_text = models.CharField(max_length=200)
    votes = models.IntegerField(default=0)

上述代码非常直观。每个模型都用一个类表示,该类继承自django.db.models.Model每个模型都有一些类变量,在模型中每个类变量都代表了数据库中的一个字段。

每个字段通过Field类的一个实例表示 —— 例如字符字段CharField和日期字段DateTimeField这种方法告诉Django,每个字段中保存着什么类型的数据。

每个Field 实例的名字(例如question_textpub_date)就是字段的名字,并且是机器可读的格式。你将在Python代码中使用到它的值,并且你的数据库将把它用作表的列名。

你可以使用Field的第一个参数来指定一个人类可读的名字,这是可选的。它在Django的内省机制中有使用,而且可以兼作文档。 如果没有提供这个参数,Django将使用那个机器可读的名字(实例名)。 在这个例子中,我们只为Question.pub_date定义一个人类可读的名字。 对于这个模型中其他的字段,机器可读的名字(实例名)足以充分地表达出它的含义。

某些Field 类具有必选的参数。例如,CharField要求您给它一个max_length。 这个参数不仅用于数据库模式,而且数据验证中也会用到,我们稍后会看到。

Field 还具有各种可选参数。在这个例子中,我们设置votes字段的默认值 为0。

最后,注意我们使用ForeignKey定义了一个关联。它告诉Django每个Choice都只关联一个QuestionDjango支持所有常见的数据库关联:多对一、多对多和一对一。

激活模型

上面那段简短的模型代码给了Django很多信息。 有了这些代码,Django就能够自动完成以下两个功能:

  • 为该应用创建数据库表(CREATE TABLE 语句)。
  • Question对象和Choice对象创建一个访问数据库的python API。

但是,我们首先得告诉项目:polls应用已经安装。 

原理:

Django 应用是可以“热插拔”的,即可以在多个项目中使用同一个应用,也可以分发这些应用, 因为它们不需要与某个特定的Django安装绑定。

再次编辑mysite/settings.py文件,并修改INSTALLED_APPS设置以包含字符串'polls'所以它现在是这样的:

mysite/settings.py
INSTALLED_APPS = (
    'django.contrib.admin',
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.messages',
    'django.contrib.staticfiles',
    'polls',
)

现在Django知道要包含polls应用。 让我们运行另外一个命令:

$ python manage.py makemigrations polls

你应该看到类似下面的内容:

Migrations for 'polls':
  0001_initial.py:
    - Create model Question
    - Create model Choice
    - Add field question to choice

通过运行makemigrations告诉Django,已经对模型做了一些更改(在这个例子中,你创建了一个新的模型)并且会将这些更改记录为迁移文件

迁移是 Django 如何储存模型的变化(以及您的数据库模式),它们只是磁盘上的文件。如果愿意,你可以阅读这些为新模型建立的迁移文件;这个迁移文件就是  polls/migrations/0001_initial.py不用担心,Django不要求你在每次Django生成迁移文件之后都要阅读这些文件,但是它们被设计成可人为编辑的形式,以便你可以手工稍微修改一下Django的某些具体行为。

有一个命令可以运行这些迁移文件并自动管理你的数据库模式 —— 它叫做migrate,我们一会儿会用到它 —— 但是首先,让我们看一下迁移行为将会执行哪些SQL语句。sqlmigrate命令接收迁移文件的名字并返回它们的SQL语句:

$ python manage.py sqlmigrate polls 0001

你应该会看到类似如下的内容(为了便于阅读我们对它重新编排了格式):

BEGIN;
CREATE TABLE "polls_choice" (
    "id" serial NOT NULL PRIMARY KEY,
    "choice_text" varchar(200) NOT NULL,
    "votes" integer NOT NULL
);
CREATE TABLE "polls_question" (
    "id" serial NOT NULL PRIMARY KEY,
    "question_text" varchar(200) NOT NULL,
    "pub_date" timestamp with time zone NOT NULL
);
ALTER TABLE "polls_choice" ADD COLUMN "question_id" integer NOT NULL;
ALTER TABLE "polls_choice" ALTER COLUMN "question_id" DROP DEFAULT;
CREATE INDEX "polls_choice_7aa0f6ee" ON "polls_choice" ("question_id");
ALTER TABLE "polls_choice"
  ADD CONSTRAINT "polls_choice_question_id_246c99a640fbbd72_fk_polls_question_id"
    FOREIGN KEY ("question_id")
    REFERENCES "polls_question" ("id")
    DEFERRABLE INITIALLY DEFERRED;

COMMIT;

请注意以下几点:

  • 输出的具体内容会依据你使用的数据库而不同。 以上例子使用的数据库是PostgreSQL。
  • 表名是自动生成的,由app的名字(polls)和模型名字的小写字母组合而成 —— questionchoice(你可以重写这个行为。)
  • 主键(id)是自动添加的。(你也可以重写这个行为。)
  • 按照惯例,Django会在外键的字段名后面添加 "_id"。(是的,你依然可以重写这个行为。)
  • 外键关系由FOREIGN KEY约束显式声明。不用在意DEFERRABLE部分;它只是告诉PostgreSQL直到事务的最后再执行外键关联。
  • 这些SQL语句是针对你所使用的数据库定制的,所以会为你自动处理某些数据库所特有的字段例如auto_increment (MySQL)、 serial (PostgreSQL)或integer primary key autoincrement (SQLite) 。在处理字段名的引号时也是如此 —— 例如,使用双引号还是单引号。
  • sqlmigrate命令并不会在你的数据库上真正运行迁移文件 —— 它只是把Django 认为需要的SQL打印在屏幕上以让你能够看到。 这对于检查Django将要进行的数据库操作或者你的数据库管理员需要这些SQL脚本是非常有用的。

如果有兴趣,你还可以运行python manage.py check它会检查你的项目中的模型是否存在问题,而不用执行迁移或者接触数据库。

现在,再次运行migrate以在你的数据库中创建模型所对应的表:

$ python manage.py migrate
Operations to perform:
  Synchronize unmigrated apps: staticfiles, messages
  Apply all migrations: admin, contenttypes, polls, auth, sessions
Synchronizing apps without migrations:
  Creating tables...
    Running deferred SQL...
  Installing custom SQL...
Running migrations:
  Rendering model states... DONE
  Applying <migration name>... OK

migrate命令会找出所有还没有被应用的迁移文件(Django使用数据库中一个叫做django_migrations的特殊表来追踪哪些迁移文件已经被应用过),并且在你的数据库上运行它们 —— 本质上来讲,就是使你的数据库模式和你改动后的模型进行同步。

迁移功能非常强大,可以让你在开发过程中不断修改你的模型而不用删除数据库或者表然后再重新生成一个新的 —— 它专注于升级你的数据库且不丢失数据。 我们将在本教程的后续章节对迁移进行深入地讲解,但是现在,请记住实现模型变更的三个步骤:

将生成和应用迁移文件的命令分成几个命令来执行,是因为你可能需要将迁移文件提交到你的版本控制系统中并跟随你的应用一起变化; 这样做不仅可以使开发变得更加简单,而且对其他开发者以及上线生产非常有用。

阅读django-admin 的文档来了解manage.py 工具能做的所有事情。

玩转API

现在,让我们进入Python的交互式shell,玩转这些Django提供给你的API。 使用如下命令来调用Python shell:

$ python manage.py shell

我们使用上述命令而不是简单地键入“python”进入python环境,是因为manage.py 设置了DJANGO_SETTINGS_MODULE 环境变量,该环境变量告诉Django导入mysite/settings.py文件的路径。

绕开 manage.py

如果你不想使用manage.py,也没问题。只要设置DJANGO_SETTINGS_MODULE 环境变量为 mysite.settings,启动一个普通的Python shell,然后建立Django:

>>> import django
>>> django.setup()

如果以上命令引发了一个AttributeError,可能是你使用了一个和本教程不匹配的Django版本。 也许你应该切换到新一点或者旧一点的Django版本中去

您必须在与manage.py同一级目录中运行python,或确保该目录在Python Path中,以便import mysite能运行。

所有这些信息,请参见django-admin 的文档

一旦你进入shell,请浏览数据库API

>>> from polls.models import Question, Choice   # Import the model classes we just wrote.

# No questions are in the system yet.
>>> Question.objects.all()
[]

# Create a new Question.
# Support for time zones is enabled in the default settings file, so
# Django expects a datetime with tzinfo for pub_date. Use timezone.now()
# instead of datetime.datetime.now() and it will do the right thing.
>>> from django.utils import timezone
>>> q = Question(question_text="What's new?", pub_date=timezone.now())

# Save the object into the database. You have to call save() explicitly.
>>> q.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.
>>> q.id
1

# Access model field values via Python attributes.
>>> q.question_text
"What's new?"
>>> q.pub_date
datetime.datetime(2012, 2, 26, 13, 0, 0, 775217, tzinfo=<UTC>)

# Change values by changing the attributes, then calling save().
>>> q.question_text = "What's up?"
>>> q.save()

# objects.all() displays all the questions in the database.
>>> Question.objects.all()
[<Question: Question object>]

先等一下。<Question: Question object>对于这个对象是一个完全没有意义的表示。 让我们来修复这个问题,编辑Question模型(在polls/models.py文件中)并添加一个__str__()方法给QuestionChoice

polls/models.py
from django.db import models

class Question(models.Model):
    # ...
    def __str__(self):              # __unicode__ on Python 2
        return self.question_text

class Choice(models.Model):
    # ...
    def __str__(self):              # __unicode__ on Python 2
        return self.choice_text

给你的模型添加__str__()方法很重要,不仅会使你自己在使用交互式命令行时看得更加方便,而且会在Django自动生成的管理界面中使用对象的这种表示。

__str__ 还是 __unicode__?

对于Python 3来说,这很简单,只需使用__str__()

对于Python 2来说,你应该定义__unicode__()方法并返回unicode 值。Django 模型具有一个默认的__str__() 方法,它会调用__unicode__()并将结果转换为UTF-8 字节字符串。这意味着unicode(p)将返回一个Unicode 字符串,而str(p)将返回一个字节字符串,其字符以UTF-8编码。Python 的行为则相反:对象__unicode__方法调用 __str__方法并将结果理解为ASCII 字节字符串。这个不同点可能会产生困惑。

如果以上这些令你费解的话,那就使用Python 3吧。

请注意这些都是普通的Python方法。 让我们演示一下如何添加一个自定义的方法:

polls/models.py
import datetime

from django.db import models
from django.utils import timezone


class Question(models.Model):
    # ...
    def was_published_recently(self):
        return self.pub_date >= timezone.now() - datetime.timedelta(days=1)

注意import datetimefrom django.utils import timezone分别引用Python 的标准datetime 模块和Django django.utils.timezone中时区相关的工具。如果你不了解Python中时区的处理方法,你可以在时区支持的文档 中了解更多的知识。

保存这些改动,然后通过python manage.py shell再次打开一个新的Python 交互式shell:

>>> from polls.models import Question, Choice

# Make sure our __str__() addition worked.
>>> Question.objects.all()
[<Question: What's up?>]

# Django provides a rich database lookup API that's entirely driven by
# keyword arguments.
>>> Question.objects.filter(id=1)
[<Question: What's up?>]
>>> Question.objects.filter(question_text__startswith='What')
[<Question: What's up?>]

# Get the question that was published this year.
>>> from django.utils import timezone
>>> current_year = timezone.now().year
>>> Question.objects.get(pub_date__year=current_year)
<Question: What's up?>

# Request an ID that doesn't exist, this will raise an exception.
>>> Question.objects.get(id=2)
Traceback (most recent call last):
    ...
DoesNotExist: Question 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.
# The following is identical to Question.objects.get(id=1).
>>> Question.objects.get(pk=1)
<Question: What's up?>

# Make sure our custom method worked.
>>> q = Question.objects.get(pk=1)
>>> q.was_published_recently()
True

# Give the Question a couple of Choices. The create call constructs a new
# Choice object, does the INSERT statement, adds the choice to the set
# of available choices and returns the new Choice object. Django creates
# a set to hold the "other side" of a ForeignKey relation
# (e.g. a question's choice) which can be accessed via the API.
>>> q = Question.objects.get(pk=1)

# Display any choices from the related object set -- none so far.
>>> q.choice_set.all()
[]

# Create three choices.
>>> q.choice_set.create(choice_text='Not much', votes=0)
<Choice: Not much>
>>> q.choice_set.create(choice_text='The sky', votes=0)
<Choice: The sky>
>>> c = q.choice_set.create(choice_text='Just hacking again', votes=0)

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

# And vice versa: Question objects get access to Choice objects.
>>> q.choice_set.all()
[<Choice: Not much>, <Choice: The sky>, <Choice: Just hacking again>]
>>> q.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 question whose pub_date is in this year
# (reusing the 'current_year' variable we created above).
>>> Choice.objects.filter(question__pub_date__year=current_year)
[<Choice: Not much>, <Choice: The sky>, <Choice: Just hacking again>]

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

For more information on model relations, see Accessing related objects.更多关于如何在这些API中使用双下划线来执行字段查询的信息,请查看 字段查询更多关于数据库API的信息,请查看我们的 数据库API参考

如果你适应了这些API,可以阅读本教程的第2部分来让Django的自动管理界面工作起来。