下载和安装¶

$ pip install django-extensions

$ easy_install django-extensions

python setup.py install

INSTALLED_APPS = (
    ...
    'django_extensions',
)

版本控制¶

django-extensions 目前被托管在github上: https://github.com/django-extensions/django-extensions

django command extensions 的dev版本在包含了新特性的同时还可以稳定运行,在正式环境下也推荐使用 [2].

使用git命令克隆 django-extensions 源码到本地:

git clone git://github.com/django-extensions/django-extensions.git

下载源码后可以在项目根目录下执行 python setup.py install 安装,或将 extensions 目录添加到Python环境变量中.最通用的做法是创建一个软连接指向代码的目录,并将软连接添加到Python环境变量中.比如Python的site-packages目录 [3]:

ln -sf /full/path/to/django-extensions/django_extensions /usr/lib/python2.7/site-packages/django_extensions

检查django-extensions是否被正确安装,在Python的shell中输入下面命令 [4]:

>>> import django_extensions
>>> django_extensions.VERSION
(1, 2, 5)

注意:通过git克隆出来的代码比通过源包(pypi)安装的代码版本更新.通过源码安装虽然可能会包含bug或兼容性问题,但也会包含一些新特性.

交互式的 Python Shells¶

shell_plus支持3种交互的Python shell.

BPython:

$ ./manage.py shell_plus --use-bpython

IPython:

$ ./manage.py shell_plus --use-ipython

Python:

$ ./manage.py shell_plus --use-plain

默认shell优先顺序是: bpython, ipython, python.

也可以在 settings.py 配置中指定优先选择的shell工具:

# 在shell_plus中使用ipython作为交互工具
SHELL_PLUS = "ipython"

配置¶

如果遇到apps中包含的的models名字出现冲突,或不想载入特定apps的models的情况,可以通过配置别名的方法解决:

提示: 下列配置仅在shell_plus中生效,不会影响当前项目运行的环境变量:

# 将自动载入的Messages模块重命名为blog_messages

SHELL_PLUS_MODEL_ALIASES = {'blog': {'Messages': 'blog_messages'},}

# 不加载sites app和pictures的blog模型

SHELL_PLUS_DONT_LOAD = ['sites', 'blog.pictures']

设置别名和声明不加载的配置可以同时使用.也可以通过命令行参数谁知不加载的模块:

$ ./manage.py shell_plus --dont-load app1 --dont-load app2.module1

命令行的参数和配置文件中的设置是可以同时使用的,所以一次性的参数完全可以通过命令行运行,省去频繁修改配置文件的麻烦.

shell_plus还能使用 IPython Notebook .将浏览器作为交互的shell:

$ ./manage.py shell_plus --notebook

IPython Notebook 中也会将所有模块和models加载到全局变量中.

IPython NoteBook 中自动加载模块功能是通过参数配置的,默认为启用状态.:

--ext django_extensions.management.notebook_extension

自定义 IPython Notebook 配置需要覆盖Django项目的 IPYTHON_ARGUMENTS 配置:

IPYTHON_ARGUMENTS = [
    '--ext', 'django_extensions.management.notebook_extension',
    '--ext', 'myproject.notebook_extension',
    '--debug',
]

想在 IPython Notebook 中启用自动加载功能,要么包含django-extensions默认的notebook扩展配置,要么把自动加载的代码拷贝到自定义的扩展中.

提示: IPython Notebook 的特性中不能识别 --dont-load 参数.

附加的引入模块¶

在配置文件中设置 SHELL_PLUS_PRE_IMPORTS 和 SHELL_PLUS_POST_IMPORTS 可以指定附加的引入模块.第一个配置中添加的模块会先于所有模块加载,第二个配置中添加的模块会后于所有模块加载.这两个配置的格式相同,在settings.py文件中添加:

SHELL_PLUS_PRE_IMPORTS = (
    ('module.submodule1', ('class1', 'function2')),
    ('module.submodule2', 'function3'),
    ('module.submodule3', '*'),
    'module.submodule4'
)

上面的配置被转换为Python的引入代码结果,如下所示:

from module.submodule1 import class1, function2
from module.submodule2 import function3
from module.submodule3 import *
import module.submodule4

这些引入的变量在shell执行时就可以使用了.

用法举例¶

例子需要在项目的根目录下执行,该目录下要包含 settings.py 文件 [1]

# 获取命令行的帮助
./manage.py create_app --help

# 从 [APP_NAME].dia 文件中生成 ``models.py`` 和 ``admin.py`` ,这个文件应该放在与 ``settings.py`` 相同的文件目录下
./manage.py create_app -d APP_NAME

从sample.dia文件生成app¶

./manage.py create_app --diagram=sample.dia webdata

-d 参数或 --diagram 参数通过 dia2django 生成models.py, 详细文档查看 django wiki.

译者注: 新版本Django原生命令 startapp 也提供了通过 --template 指定模板来创建app的功能

为什么有这个功能¶

这样做的有几点好处:

• 数据库变更时会少出现些莫名其妙的错误: 不依赖ID的外键,会忽略掉新增和删除的列
• 编辑脚本后可以自动生成很多的实例数据

例如,编辑一个脚本,生成一些测试的初始数据到数据库中:

for i in xrange(2000):
    poll = Poll()
    poll.question = "Question #%d" % i
    poll.pub_date = date(2001,01,01) + timedelta(days=i)
    poll.save()

真实情况下数据库可能更大更复杂,通常是通过Admin后台生成一下测试数据,再导出脚本.编辑导出的脚本,得到更多的数据.

特性支持¶

• 外键和多对多关系(通过Python变量,而不是ID)
• 外键或多对多中对自己的引用
• models子类
• ContentType 字段类型,并生成关联关系(查看 issue 43)
• 递归引用
• 排除自增字段
• 父类不会被包含,除非没有子类继承它
• 可以引用单独的类

还不支持的特性¶

• 完美的支持引用字段(比如 自增字段 的引用)
• Intermediate join tables: issue 48
• GIS字段: issue 72 [1]

如何使用¶

从指定的app中导出所有models的建表语句:

$ ./manage.py dumpscript appname > scripts/testdata.py

导出指定模型的数据,添加参数 appname.ModelName

$ ./manage.py dumpscript appname.ModelName > scripts/testdata.py

清空指定app对应数据库数据,然后重新加载数据:

$ ./manage.py reset appname
$ ./manage.py runscript testdata

提示: runscript 命令只能执行在 scripts 模块下的脚本,所以要在 scripts 目录下创建 __init__.py 文件.

警告¶

# 错误用法
$ ./manage.py dumpscript appname > dumps/appname.py

# 正确用法
$ ./manage.py dumpscript appname > dumps/appname_all.py

# 正确用法
$ ./manage.py dumpscript appname.Somemodel > dumps/appname_somemodel.py

介绍¶

runscript 命令允许在django项目的环境下执行任意脚本.就像在 shell 命令中执行脚本一样:

$ python manage.py shell

开始使用¶

首先要在项目根目录下创建一个脚本的目录,名字是 scripts

$ mkdir scripts
$ touch scripts/__init__.py

然后,创建一个想要执行的Python脚本:

$ touch scripts/delete_all_polls.py

这个脚本文件中必须包含 run() 方法, runscript 命令执行时会自动调用该方法.这个脚本中可以引用django项目中的任意模块或数据模型.

例如:

# scripts/delete_all_polls.py

from Polls.models import Poll

def run():
    # Get all polls
    all_polls = Poll.objects.all()
    # Delete polls
    all_polls.delete()

提示: runscript 命令可以找到任意app下 scripts 目录中的脚本文件.

用法¶

runscript 命令可以在shell中调用 scripts 目录下的Python脚本.

例如:

$ python manage.py runscript delete_all_polls

提示: runscript 命令会首先检查每个app下的 scripts 目录,如果找到对应名字的脚本就会执行.然后检查 project_root/scripts 目录下是否包含符合名字的脚本,如果找到也会执行.也就是说,我们可以在不同的app中创建相同名字的脚本,并且都会被执行.

用法举例¶

将所有用户信息导出成 '"First Last" <my@addr.com>;' 格式:

$ ./manage.py export_emails > addresses.txt

以LinkedIn pre-approve格式从 Attendees 组中导出用户信息:

$ ./manage.py export_emails -g Attendees -f linkedin pycon08.csv

以GMail(Google Docs)格式创建一个CSV文件:

$ ./manage.py export_emails --format=google google.csv

可选用的格式¶

"First Last" <user@host.com>;

当前数据模型的字段的扩展¶

• AutoSlugField - 自动生成一个唯一的slug,生成方式是以迭代方式给当前字段后面添加一个随机字符,知道不重复为止.slug生成方式的灵感来自于 SmileyChris 的唯一码生成代码片段.
• CreationDateTimeField - DateTimeField类型字段,会自动保存数据第一次被保存到数据库的时间戳.工作方式与添加了 auto_now_add=True 参数相同,而 auto_now_add 参数已经不推荐使用.
• ModificationDateTimeField - DateTimeField类型字段,当数据出现修改是会自动保存被修改的时间戳.工作方式与添加了 auto_now=True 参数相同,而 auto_now 参数已经不推荐使用.
• UUIDField - 唯一标识码字段,通过本地Python模块生成的唯一标识码,支持所有版本的uuid.
• EncryptedCharField - 字符串类型字段,会将数据以加密的方式保存和现实,加密方法使用 Keyczar.使用这个扩展字段时需要安装Keyczar,通过Keyczar库生成加密的密钥,还要在django项目的 settings.py 中添加 settings.ENCRYPTED_FIELD_KEYS_DIR 配置,指向密钥的完整目录.
• EncryptedTextField - 字符串类型字段,与 EncryptedCharField 字段类似,但是继承自 TextField 字段.

选择生成图表的库¶

graph_model 命令可以指定使用哪个库来生成图片,使用参数 --pygraphviz 或 --pydot ,需要安装相应的依赖库.

默认选择 pygraphviz 库生成图表,如果没有指定参数,也没有安装 pygraphviz 库,则会抛出异常.

安装 pygraphviz 库:

$ pip install pygraphviz

安装是可能因为无法编译需要的C扩展而安装失败.那么可能需要尝试其它安装方法,或使用 PyDot.

安装 pydot 库:

$ pip install pyparsing==1.5.7
$ pip install pydot

安装过程很快,注意要安装指定版本的 pyparsing .否则可能会出错:

Couldn't import dot_parser, loading of dot files will not be possible.

默认配置¶

在项目的配置文件中可以使用 GRAPH_MODELS 配置生成图表时的默认参数:

GRAPH_MODELS = {
  'all_applications': True,
  'group_models': True,
}

配置的参数名与在命令行中的参数名是一样的,只要去掉作为参数的两个建号,并把参数中的减号换成下划线.

用例¶

安装 django-extensions 后,就可以创建 .dot 文件.或通过 graph_models 命令生成图表,看下面的例子:

# 创建一个 .dot 文件
$ ./manage.py graph_models -a > my_project.dot

# 创建一个PNG图片,包含应用的结构,把图片命名为my_project_visualized.png
$ ./manage.py graph_models -a -g -o my_project_visualized.png

# 这个例子中指明了使用哪个Python的图表库
$ ./manage.py graph_models --pygraphviz -a -g -o my_project_visualized.png
$ ./manage.py graph_models --pydot -a -g -o my_project_visualized.png

# 创建一个只包含 'foo' 和 'bar' 应用的 dot 文件
$ ./manage.py graph_models foo bar > my_project.dot

定时的计划任务¶

runjob[s] -l

@hourly /path/to/my/project/manage.py runjobs hourly

@daily /path/to/my/project/manage.py runjobs daily

@weekly /path/to/my/project/manage.py runjobs weekly

@monthly /path/to/my/project/manage.py runjobs monthly

数据库字段的扩展¶

• TimeStampedModel - 抽象类,包含了由自己管理的 created 和 modified 字段.

简介¶

请使用 django_extensions 的命名空间,而不是绝对路径

命名空间的建议¶

一些简单的建议:

• django_extensions.commands (20% 的人在正式环境中使用的绝对路径)
• django_extensions.commands.development (所有在开发中都会用到的功能)
• django_extensions.commands.extra
• django_extensions.db
• django_extensions.templates
• django_extensions.jobs

数据库部分使用方式都是正确的,因为目前只有一种引用方式:

from django_extensions.db.models import something

简介¶

Django使用 diffsettings 命令输出当前项目配置与默认配置的区别.有时也需要直接查看当前项目的所有配置,尤其是配置十分复杂的时候,比如都包含好几个配置文件 [1].例如,在测试和开发环境中使用不同的配置文件,并且都包含了默认的 settings.py 文件,这样就不能直观的查看配置文件了.

print_settings 命令支持从不同的格式文件中输出数据.

详情¶

最简单的输出配置命令如下,不需要添加参数:

$ python manage.py print_settings

以不同格式输出:

$ python manage.py print_settings --format=json
$ python manage.py print_settings --format=yaml    # 需要安装 PyYAML

通过 --help 参数可以获取更多帮助:

$ python manage.py print_settings --help
Usage: manage.py print_settings [options]

Print the active Django settings.

Options:
  -v VERBOSITY, --verbosity=VERBOSITY
                        Verbosity level; 0=minimal output, 1=normal output,
                        2=verbose output, 3=very verbose output
  --settings=SETTINGS   The Python path to a settings module, e.g.
                        "myproject.settings.main". If this isn't provided, the
                        DJANGO_SETTINGS_MODULE environment variable will be
                        used.
  --pythonpath=PYTHONPATH
                        A directory to add to the Python path, e.g.
                        "/home/djangoprojects/myproject".
  --traceback           Print traceback on exception
  --format=FORMAT       Specifies output format.
  --indent=INDENT       Specifies indent level for JSON and YAML
  --version             show program's version number and exit
  -h, --help            show this help message and exit

简介¶

runprofileserver 命令在启动django服务的同时其用了跟踪分析工具,会将服务的分析信息保存到 .prof 后缀文件中.使用 --prof-path 参数指定保存分析文件到指定目录.每一个请求的分析数据都会被保存成一个profile文件.

如果没有指定 --prof-path 参数,分析数据的 .prof 文件会被保存到 /tmp 目录下.建议使用特定目录保存分析文件,这样方便我们随时查看分析数据,也不会弄乱 /tmp 目录,使用windows系统时一定要指定``–prof-path`` 参数,因为windows系统没有 /tmp 目录.

分析文件的名字默认名字是:

{path}.{duration:06d}ms.{time}

也可以通过 --prof-file 参数指定生成的服务分析文件名字.文件名格式规则参考: Format Specification.

例如:

• “{time}-{path}-{duration}ms” - 用请求的道达时间命名分析文件.
• “{duration:06d}ms.{path}.{time}” - 用请求的相应时间命名分析文件.

聚合profile¶

Django提供了一个profile文件聚合的工具 gather_profile_stats.py ,在Django安装目录的 bin 目录下可以找到.

KCacheGrind¶

新版本的 runprofileserver 命令可以把分析的结果文件保存成 KCacheGrind 格式文件,这样就可以通过 KCacheGrind 的分析工具来查看分析数据.

例子:

$ mkdir /tmp/my-profile-data
$ ./manage.py runprofileserver --kcachegrind --prof-path=/tmp/my-profile-data
Validating models...
0 errors found

Django version 1.0-post-release-SVN-SVN-unknown, using settings 'complete_project.settings'
Development server is running at http://127.0.0.1:8000/
Quit the server with CONTROL-C.
[13/Nov/2008 06:29:38] "GET / HTTP/1.1" 200 41107
[13/Nov/2008 06:29:39] "GET /site_media/base.css?743 HTTP/1.1" 200 17227
[13/Nov/2008 06:29:39] "GET /site_media/logo.png HTTP/1.1" 200 3474
[13/Nov/2008 06:29:39] "GET /site_media/jquery.js HTTP/1.1" 200 31033
[13/Nov/2008 06:29:39] "GET /site_media/heading.png HTTP/1.1" 200 247
[13/Nov/2008 06:29:39] "GET /site_media/base.js HTTP/1.1" 200 751
<ctrl-c>
$ kcachegrind /tmp/my-profile-data/root.12574391.592.prof

相关知识链接¶

• http://code.djangoproject.com/wiki/ProfilingDjango
• http://www.rkblog.rk.edu.pl/w/p/django-profiling-hotshot-and-kcachegrind/
• http://code.djangoproject.com/browser/django/trunk/django/bin/profiling/gather_profile_stats.py
• http://www.oluyede.org/blog/2007/03/07/profiling-django/
• http://simonwillison.net/2008/May/22/debugging/

简介¶

runserver_plus 命令需要安装 Werkzeug WSGI utilities . Werkzeug 是Python作为web服务的杀手级调试工具,还能进行基于ajax的错误断点调试(允许在出错的地方执行代码). 当然还提供了一个漂亮的错误展示页面.

开始使用¶

在启动Django的测试服务时,只要用 runserver_plus 命令代替 runserver 命令就可以了:

$ python manage.py runserver_plus

* Running on http://127.0.0.1:8000/
* Restarting with reloader...

Validating models...
0 errors found

Django version 0.97-newforms-admin-SVN-unknown, using settings 'screencasts.settings'
Development server is running at http://127.0.0.1:8000/
Using the Werkzeug debugger (http://werkzeug.pocoo.org/)
Quit the server with CONTROL-C.

runserver_plus 命令接受原来的所有参数.也就是可以随意指定端口和host,跟原生的 runserver 命令一模一样.

深入使用¶

runserver_plus 启动的服务遇到代码抛出异常时,会得到一个 Werkzeug 的错误显示页面(不是默认的Django错误页面).

当鼠标划过特定错误行(堆栈)时,就会显示出当前位置的调试扩展功能,注意图片右边出现的2个按钮:

这2个选项是:

查看源码¶

这是点击 显示源码 后的效果:

产看错误产生的源码有助于快速定位错误原因.抛出异常的部分被高亮显示,这样更方便查看.

有一个不够人性化的地方是,点击 查看源码 后,页面没有自动滚动到底部(源码显示的地方),这容易让人觉得什么都没有发生,其实是没有看到.

命令行调试¶

在错误页面上点击命令行调试按钮后,会显示出一个命令行调试工具(网页里面的输入框),是不是屌爆了:

这样就会出现一个基于ajax的命令行调试工具,输入的命令通过ajax方式发送到后台,再把返回的结果输出,然后就可以任意发挥了.截图中,在调试框里输入了 print environ 命令来查看当前环境中给方法传入了哪些参数.

注意 : 该方法不能被用在任何正式环境中,即使是在正式环境中检测问题时也不行.命令行调试工具允许在服务器端执行Python命令,这是非常危险的.

$ python manage.py runserver_plus --cert cert
Validating models...
0 errors found

Django version 1.6.dev20130122125534, using settings 'mysite.settings'
Development server is running at http://127.0.0.1:8000/
Using the Werkzeug debugger (http://werkzeug.pocoo.org/)
Quit the server with CONTROL-C.
 * Running on https://127.0.0.1:8000/
 * Restarting with reloader
Validating models...
0 errors found

Django version 1.6.dev20130122125534, using settings 'mysite.settings'
Development server is running at http://127.0.0.1:8000/
Using the Werkzeug debugger (http://werkzeug.pocoo.org/)
Quit the server with CONTROL-C.

$ python manage.py runserver_plus --cert /tmp/cert

$ pip install pyOpenSSL

用法举例¶

上传到S3的 mybucket

$ ./manage.py sync_s3 mybucket

上传到S3的 mybucket ,并对CSS/JS文件进行gzip压缩和添加缓存过期时间:

$ ./manage.py sync_s3 mybucket --gzip --expires

只上传 media 文件到S3的 mybucket 中:

$ ./manage.py sync_s3 mybucket  --media-only  # or --static-only

依赖的库和配置¶

sync_s3 命令需要安装 boto 库,改命令在1.4c版本下测试通过:

http://code.google.com/p/boto/

当然还要添加AWS账户的S3密钥,在项目配置文件 settings.py 文件中增加配置:

# settings.py
AWS_ACCESS_KEY_ID = ''
AWS_SECRET_ACCESS_KEY = ''

支持的数据库¶

sqldiff 命令当前支持的数据库:

• PostgreSQL
• Sqlite3
• MySQL
• Oracle

欢迎提供支持其它数据库的 patch ! :-)

用法举例¶

查看所有app数据模型与数据库之间的区别:

$ ./manage.py sqldiff -a

用文本显示所有app数据模型与数据库之间的区别:

$ ./manage.py sqldiff -a -t

简介¶

不用再手动创建数据库, settings.py 文件中已经包含了需要的信息,所以Do It Yourself.

用法¶

$ python manage.py sqlcreate [--router=<routername>] | <my_database_shell_command>

sqlcreate 命令会将SQL语句输出用来检查(如果你想检查的话).但最终还是要输入到数据库的shell中来执行.

如果有合适的方法证明当前用户有修改数据库的权限,那就可以把输出结果直接导入到数据库中.但是因为项目的配置方式,这种直接修改数据库的方式是不能接受的.

用法举例¶

$ ./manage.py sqlcreate [--router=<routername>] | psql -U <db_administrator> -W

$ ./manage.py sqlcreate [--router=<routername>] | mysql -u <db_administrator> -p

存在的问题¶

• CREATE DATABASE 不是SQL标准语句,所以可能不能支持所有数据库 [1].
• 回滚数据库时没有创建用户名及密码,但会尝试将数据库权限分配一个用户 [2] .
• 缺少表空间的设置,等等.

参数¶

配置¶

用法举例¶

./manage.py validate_templates

译者注: validate_templates 命令适用与检测Django框架原生模板,如果使用了其它模板(jinja等),则该命令会失去检测效果.