django-adminmanage.py

django admin 是 Django 用于管理任务的命令行实用程序。这份文件概述了它所能做的一切。

此外,manage.py 会在每个 Django 项目中自动创建。它做的事情和 django-admin 一样,但也设置了 DJANGO_SETTINGS_MODULE 环境变量,使其指向你的项目的 settings.py 文件。

如果你通过 pip 安装 Django,django-admin 脚本应该在你的系统路径中。如果它不在你的系统路径中,请确保你的虚拟环境已经被激活。

一般来说,当你在一个 Django 项目中工作时,使用 manage.py 比使用 django-admin 更容易。如果你需要在多个 Django 配置文件之间切换,可以使用 django-adminDJANGO_SETTINGS_MODULE--settings 命令行选项。

为了保持一致,本文中的命令行例子都使用了 django-admin,但任何例子都可以使用 manage.pypython -m django

用法

$ django-admin <command> [options]
$ manage.py <command> [options]
$ python -m django <command> [options]
...\> django-admin <command> [options]
...\> manage.py <command> [options]
...\> py -m django <command> [options]

command 应是本文件所列的命令之一。options 是可选的,应该是 0 个或更多可用于指定命令的选项。

获得运行时帮助

django-admin help

运行 django-admin help 来显示使用信息和每个应用程序提供的命令列表。

运行 django-admin help --commands 来显示所有可用命令的列表。

运行 django-admin help <command> 来显示命令的描述和可用选项的列表。

应用名称

许多命令都需要一个“应用名称”的列表。一个“应用名称”是包含你模型的包的基名。例如,如果你的 INSTALLED_APPS 包含字符串 'mysite.blog',则应用名称为 blog

确定版本

django-admin version

运行 django-admin version 来显示当前的 Django 版本。

输出遵循 PEP 440 中描述的架构:

1.4.dev17026
1.4a1
1.4

显示 debug 输出

Use --verbosity, where it is supported, to specify the amount of notification and debug information that django-admin prints to the console.

可用命令

check

django-admin check [app_label [app_label ...]]

使用 系统检查框架 来检查整个 Django 项目的常见问题。

默认情况下,所有应用都会被检查。你可以通过提供一个应用标签的列表作为参数来检查应用的子集:

django-admin check auth admin myapp
--tag TAGS, -t TAGS

系统检查框架执行许多不同类型的检查,这些检查都是 用标签 分类的。你可以使用这些标签将执行的检查限制为只在特定类别中的检查。例如,要只执行模型和兼容性检查,运行:

django-admin check --tag models --tag compatibility
--database DATABASE
New in Django 3.1.

指定运行检查需要数据库访问的数据库:

django-admin check --database default --database other

默认情况下,这些检查不会被运行。

--list-tags

列出所有可用的标签。

--deploy

激活一些仅在部署环境中相关的附加检查。

你可以在你的本地开发环境中使用这个选项,但是由于你的本地开发配置模块可能没有很多你的生产设置,你可能会想把 check 命令指向不同的配置模块,可以通过设置 DJANGO_SETTINGS_MODULE 环境变量,或者通过传递 --settings 选项:

django-admin check --deploy --settings=production_settings

或者你可以直接在生产或暂存部署上运行它,以验证是否使用了正确的配置(省略 --settings)。你甚至可以把它作为集成测试套件的一部分。

--fail-level {CRITICAL,ERROR,WARNING,INFO,DEBUG}

指定导致命令以非零状态退出的消息级别。默认值是 ERROR

compilemessages

django-admin compilemessages

makemessages 创建的 .po 文件编译成 .mo 文件,以用于内置的 gettext 支持。参见 国际化和本地化

--locale LOCALE, -l LOCALE

指定要处理的 locale。如果没有提供,则会处理所有的 locale。

--exclude EXCLUDE, -x EXCLUDE

指定要从处理中排除的 locale。如果没有提供,则不排除任何 locale。

--use-fuzzy, -f

包括 fuzzy 翻译 到编译文件。

用法示例:

django-admin compilemessages --locale=pt_BR
django-admin compilemessages --locale=pt_BR --locale=fr -f
django-admin compilemessages -l pt_BR
django-admin compilemessages -l pt_BR -l fr --use-fuzzy
django-admin compilemessages --exclude=pt_BR
django-admin compilemessages --exclude=pt_BR --exclude=fr
django-admin compilemessages -x pt_BR
django-admin compilemessages -x pt_BR -x fr
--ignore PATTERN, -i PATTERN

忽略与给定 glob 风格的模式相匹配的目录。使用多次可以忽略更多的目录。

用法示例:

django-admin compilemessages --ignore=cache --ignore=outdated/*/locale

createcachetable

django-admin createcachetable

使用你的配置文件中的信息创建用于数据库缓存后台的缓存表。更多信息请参见 Django 缓存框架

--database DATABASE

指定创建缓存表的数据库。默认值为 default

--dry-run

打印无需实际运行的 SQL,所以你可以自定义它或使用迁移框架。

dbshell

django-admin dbshell

运行你的 ENGINE 配置中指定的数据库引擎的命令行客户端,连接参数在你的 USERPASSWORD 等配置中指定。

  • 对于 PostgreSQL 来说,这将运行 psql 命令行客户端。
  • 对于 MySQL 来说,这将运行 mysql 命令行客户端。
  • 对于 SQLite 来说,这将运行 sqlite3 命令行客户端。
  • 对于 Oracle 来说,这将运行 sqlplus 命令行客户端。

这个命令假设程序在你的 PATH 上,这样调用程序名(psqlmysqlsqlite3sqlplus)就能在正确的地方找到程序。没有办法手动指定程序的位置。

--database DATABASE

指定打开命令行的数据库。默认为 default

-- ARGUMENTS
New in Django 3.1.

-- 分界线后的任何参数都会被传递给底层的命令行客户端。例如,对于 PostgreSQL,你可以使用 psql 命令的 -c 标志直接执行一个原始 SQL 查询:

$ django-admin dbshell -- -c 'select current_user'
 current_user
--------------
 postgres
(1 row)
...\> django-admin dbshell -- -c 'select current_user'
 current_user
--------------
 postgres
(1 row)

在 MySQL/MariaDB 上,你可以用 mysql 命令的 -e 标志来实现:

$ django-admin dbshell -- -e "select user()"
+----------------------+
| user()               |
+----------------------+
| djangonaut@localhost |
+----------------------+
...\> django-admin dbshell -- -e "select user()"
+----------------------+
| user()               |
+----------------------+
| djangonaut@localhost |
+----------------------+

注解

要注意的是,在数据库配置的 OPTIONS 部分的 DATABASES 中,并不是所有的选项都会传递给命令行客户端,例如 'isolation_level'

diffsettings

django-admin diffsettings

显示当前设置文件与 Django 默认配置(或由 --default 指定的其他配置文件)之间的差异。

默认配置中没有出现的配置,后面都是 "##"。例如,默认配置没有定义 ROOT_URLCONF,所以 ROOT_URLCONFdiffsettings 的输出中,后面跟了 "##"

--all

显示所有的配置,即使它们有 Django 的默认值。这些配置的前缀是 "##"

--default MODULE

要与当前配置进行比较的配置模块。留空以便与 Django 的默认配置进行比较。

--output {hash,unified}

指定输出格式。可用值是 hashunifiedhash 是默认模式,显示上述的输出。unified 显示的输出类似于 diff -u。缺省配置的前面是减号,后面是改变后的配置,前面是加号。

dumpdata

django-admin dumpdata [app_label[.ModelName] [app_label[.ModelName] ...]]

将数据库中与指定应用程序相关联的所有数据输出到标准输出。

如果没有提供应用程序名称,所有安装的应用程序将被转储。

dumpdata 的输出可以作为 loaddata 的输入。

注意 dumpdata 使用模型上的默认管理器来选择要转储的记录。如果你使用 自定义管理器 作为默认管理器,并且它过滤了一些可用的记录,那么并非所有的对象都会被转储。

--all, -a

使用 Django 的基础管理器,转储那些可能被自定义管理器过滤或修改的记录。

--format FORMAT

指定输出的序列化格式。默认为 JSON。支持的格式在 序列化格式 中列出。

--indent INDENT

指定输出中使用的缩进空格数。默认值为 None,在单行上显示所有数据。

--exclude EXCLUDE, -e EXCLUDE

防止特定的应用程序或模型(以 app_label.ModelName 的形式指定)被转储。如果你指定一个模型名称,那么只有该模型将被排除,而不是整个应用程序。你也可以混合应用程序名称和模型名称。

如果你想排除多个应用程序,可以多次传递 --exclude

django-admin dumpdata --exclude=auth --exclude=contenttypes
--database DATABASE

指定转储数据的数据库。默认值为 default

--natural-foreign

使用 natural_key() 模型方法将任何外键和多对多关系序列化到定义该方法的类型的对象。 请参阅 自然键 文档,了解更多关于这个和下一个选项的细节。

--natural-primary

省略该对象序列化数据中的主键,因为它可以在反序列化过程中计算。

--pks PRIMARY_KEYS

只输出由逗号分隔的主键列表指定的对象。这仅在转储一个模型时可用。默认情况下,输出模型的所有记录。

--output OUTPUT, -o OUTPUT

指定要将序列化数据写入的文件。默认情况下,数据将被写入标准输出。

当设置了这个选项,并且 --verbosity 大于 0(默认值)时,终端会显示一个进度条。

固定数据压缩

New in Django 3.2.

输出文件可以用 bz2gzlzmaxz 格式之一进行压缩,方法是在文件名后面加上相应的扩展名。例如,将数据输出为一个压缩的 JSON 文件:

django-admin dumpdata -o mydata.json.gz

flush

django-admin flush

从数据库中删除所有数据,并重新执行任何同步后处理程序。已应用迁移的表不会被清除。

如果你宁愿从一个空数据库开始,重新运行所有的迁移,你应该删除并重新创建数据库,然后运行 migrate

--noinput, --no-input

禁止所有的用户提示。

--database DATABASE

指定要刷新的数据库。默认为 default

inspectdb

django-admin inspectdb [table [table ...]]

NAME 配置指向的数据库中的数据库表进行检查,并将一个 Django 模型模块(models.py 文件)输出到标准输出。

你可以通过传递表或视图的名称作为参数来选择要检查的表或视图。如果没有提供参数,只有在使用 --include-views 选项时,才会为视图创建模型。如果使用了 --include-partitions 选项,则会在 PostgreSQL 上为分区表创建模型。

如果你有一个遗留的数据库,并且你想使用 Django,那么就使用这个脚本。脚本将检查数据库,并为其中的每个表创建一个模型。

正如你所期望的那样,创建的模型将为表中的每个字段提供一个属性。请注意,inspectdb 在其字段名输出中有一些特殊情况:

  • 如果 inspectdb 不能将列的类型映射到模型字段类型,它将使用 TextField,并在生成的模型中的字段旁边插入 Python 注释 'This field type is a guess.'。识别的字段可能取决于 INSTALLED_APPS 中列出的应用程序。例如,django.contrib.postgres 增加了对几个 PostgreSQL 特定字段类型的识别。
  • 如果数据库列名是 Python 的保留字(如 'pass''class''for'),inspectdb 将在属性名后面附加 '_field'。例如,如果一个表有一列 'for',生成的模型将有一个字段 'for_field'db_column 属性设置为 'for'inspectdb 将在字段旁边插入 Python 注释 'Field renamed because it was a Python reserved word.'

这个功能是作为一个快捷方式,而不是作为明确的模型生成。在你运行它之后,你将希望自己查看生成的模型以进行自定义。特别是,你需要重新安排模型的顺序,使引用其他模型的模型正确排序。

当在模型字段上指定了 default 时,Django 不会创建数据库默认值。同样,数据库默认值也不会转化为模型字段默认值,也不会被 inspectdb 以任何方式检测到。

默认情况下,inspectdb 创建的是未管理的模型。也就是说,模型的 Meta 类中的 managed = False 告诉 Django 不要管理每个表的创建、修改和删除。如果你确实想让 Django 管理表的生命周期,你需要将 managed 选项改为 True (或者将其删除,因为 True 是其默认值)。

特定于数据库的注释

Oracle
  • 如果使用 --includ-views,则会为物化视图创建模型。
PostgreSQL
  • 为外部表创建模型。
  • 如果使用 --includ-views,则会为物化视图创建模型。
  • 如果使用 --include-partitions,则为分区表创建模型。
--database DATABASE

指定要检查的数据库。默认为 default

--include-partitions

如果提供了这个选项,也会为分区创建模型。

只实现了对 PostgreSQL 的支持。

--include-views

如果提供了这个选项,也会为数据库视图创建模型。

loaddata

django-admin loaddata fixture [fixture ...]

搜索并将已命名固定数据中的内容加载到数据库中。

--database DATABASE

指定数据将被载入的数据库。默认值为 default

--ignorenonexistent, -i

忽略自固定数据最初生成以来可能已经被删除的字段和模型。

--app APP_LABEL

指定一个单一的应用来寻找固定数据,而不是在所有的应用程序中寻找。

--format FORMAT

从标准输入中读取 的固定数据指定 序列化格式 (例如,jsonxml)。

--exclude EXCLUDE, -e EXCLUDE

排除从给定的应用程序和/或模型加载固定数据(以 app_labelapp_label.ModelName 的形式)。多次使用该选项以排除一个以上的应用程序或模型。

什么是“固定数据”?

固定数据 是包含数据库序列化内容的文件集合。每个固定数据都有一个独有的名称,组成固定数据的文件可以分布在多个应用程序的多个目录中。

Django 会在三个位置搜索固定数据:

  1. 在每个安装的应用程序的 fixtures 目录中
  2. FIXTURE_DIRS 配置中命名的任何目录中
  3. 在由固定数据命名的文字路径中

Django 将加载它在这些位置找到的与所提供的固定数据名称相匹配的任何和所有固定数据。

如果命名的固定数据有一个文件扩展名,只有该类型的固定数据才会被加载。例如:

django-admin loaddata mydata.json

将只加载名为 mydata 的 JSON 固定数据。固定数据扩展必须与 序列化器 的注册名称相对应(例如,jsonxml)。

如果你省略了扩展,Django 会搜索所有可用的固定数据类型来寻找匹配的固定数据。例如:

django-admin loaddata mydata

将寻找任何固定数据类型的名为 mydata 的固定数据。如果一个固定数据目录包含 mydata.json,该固定数据将作为 JSON 固定数据加载。

被命名的固定数据可以包括目录组件。这些目录将被包含在搜索路径中。例如:

django-admin loaddata foo/bar/mydata.json

将为每个安装的应用程序搜索 <app_label>/fixtures/foo/bar/mydata.json,为 FIXTURE_DIRS 中的每个目录搜索 <dirname>/foo/bar/mydata.json,并搜索字面路径 foo/bar/mydata.json

当固定数据文件被处理后,数据会被原样保存到数据库中。模型定义的 save() 方法不会被调用,任何 pre_savepost_save 信号都会以 raw=True 被调用,因为实例只包含模型本地的属性。例如,你可能希望禁用访问相关字段的处理程序,这些字段在加载固定数据时不存在,否则会引发异常:

from django.db.models.signals import post_save
from .models import MyModel

def my_handler(**kwargs):
    # disable the handler during fixture loading
    if kwargs['raw']:
        return
    ...

post_save.connect(my_handler, sender=MyModel)

你也可以写一个装饰器来封装这个逻辑:

from functools import wraps

def disable_for_loaddata(signal_handler):
    """
    Decorator that turns off signal handlers when loading fixture data.
    """
    @wraps(signal_handler)
    def wrapper(*args, **kwargs):
        if kwargs['raw']:
            return
        signal_handler(*args, **kwargs)
    return wrapper

@disable_for_loaddata
def my_handler(**kwargs):
    ...

只要注意这个逻辑会在每当固定数据被反序列化时禁用信号,而不仅仅是在 loaddata 期间。

请注意,处理夹固定数据文件的顺序是未定义的。然而,所有的固定数据的数据都是作为一个事务安装的,因此一个固定数据中的数据可以引用另一个固定数据中的数据。如果数据库后端支持行级约束,这些约束将在事务结束时被检查。

dumpdata 命令可以用来生成 loaddata 的输入。

压缩的固定数据

固定数据可以用 zipgzbz2lzmaxz 格式进行压缩。例如:

django-admin loaddata mydata.json

将寻找任何 mydata.jsonmydata.json.zipmydata.json.gzmydata.json.bz2mydata.json.lzmamydata.json.xz。压缩档案中包含的第一个文件被使用。

需要注意的是,如果发现两个名称相同但固定数据类型不同的固定数据(例如,如果在同一个固定数据目录中发现了 mydata.jsonmydata.xml.gz),固定数据安装将被中止,并且在调用 loaddata 时安装的任何数据将从数据库中删除。

使用 MyISAM 的 MySQL 与固定数据

MySQL 的 MyISAM 存储引擎不支持事务或约束,所以如果你使用 MyISAM,你不会得到固定数据的数据验证,如果发现多个事务文件,也不会有回滚。

Changed in Django 3.2:

增加了对 XZ 档案(.xz)和 LZMA 档案(.lzma)的支持。

特定数据库的固定数据

如果你在一个多数据库配置中,你可能会有想加载到一个数据库,但不加载到另一个数据库的固定数据。在这种情况下,你可以在固定数据的名称中添加一个数据库标识符。

例如,如果你的 DATABASES 配置中定义了一个 'master' 数据库,请将固定数据命名为 mydata.master.jsonmydata.master.json.gz,只有当你指定要将数据加载到 master 数据库中时,固定数据才会被加载。

stdin 加载固定数据

你可以使用破折号作为固定数据名称,从 sys.stdin 加载输入。例如:

django-admin loaddata --format=json -

当从 stdin 读取时,需要使用 --format 选项来指定输入的 序列化格式 (例如 jsonxml)。

stdin 加载对标准输入和输出重定向很有用。例如:

django-admin dumpdata --format=json --database=test app_label.ModelName | django-admin loaddata --format=json --database=prod -

makemessages

django-admin makemessages

遍历当前目录下的整个源码树,并提取所有标记为翻译的字符串,并在 conf/locale(在 Django 树中)或 locale(对于项目和应用程序)目录下创建(或更新)一个消息文件。在对消息文件进行修改后,你需要使用 compilemessages 来编译它们,以便使用内置的 gettext 支持。详情请看 i18n 文档

该命令不需要设置配置。但是,当配置没有设置时,命令不能忽略 MEDIA_ROOTSTATIC_ROOT 目录,也不能包含 LOCALE_PATHS

--all, -a

更新所有可用语言的消息文件。

--extension EXTENSIONS, -e EXTENSIONS

指定要检查的文件扩展名列表(默认:htmltxtpyjs 如果 --domainjs)。

用法示例:

django-admin makemessages --locale=de --extension xhtml

用逗号分隔多个扩展名,或多次使用 -e--extension

django-admin makemessages --locale=de --extension=html,txt --extension xml
--locale LOCALE, -l LOCALE

指定要处理的 locale。

--exclude EXCLUDE, -x EXCLUDE

指定要从处理中排除的 locale。如果没有提供,则不排除任何 locale。

用法示例:

django-admin makemessages --locale=pt_BR
django-admin makemessages --locale=pt_BR --locale=fr
django-admin makemessages -l pt_BR
django-admin makemessages -l pt_BR -l fr
django-admin makemessages --exclude=pt_BR
django-admin makemessages --exclude=pt_BR --exclude=fr
django-admin makemessages -x pt_BR
django-admin makemessages -x pt_BR -x fr
--domain DOMAIN, -d DOMAIN

指定消息文件的域。支持的选项有:

  • django 适用于所有 *.py*.html*.txt 文件(默认)
  • djangojs 适用于 *.js 文件

在寻找新的翻译字符串时,跟踪指向目录的符号链接。

用法示例:

django-admin makemessages --locale=de --symlinks
--ignore PATTERN, -i PATTERN

忽略与给定的 glob 风格模式匹配的文件或目录。多次使用可以忽略更多的文件或目录。

这些模式默认使用:'CVS''.*''*~''*.pyc'

用法示例:

django-admin makemessages --locale=en_US --ignore=apps/* --ignore=secret/*.html
--no-default-ignore

禁用 --ignore 的默认值。

--no-wrap

禁用将语言文件中的长消息行分成几行。

--no-location

禁止在语言文件中写 '#: filename:line' 注释行。使用该选项会使技术熟练的译者更难理解每条消息的上下文。

--add-location [{full,file,never}]

控制语言文件中的 #: filename:line 注释行。如果该选项是:

  • full (如果没有给出,则为默认值):行中包括文件名和行号。
  • file :省略行号。
  • never :压制行数(与 --no-location 相同)。

需要 gettext 0.19 或更新版本。

--keep-pot

防止删除在创建 .po 文件之前生成的临时 .pot 文件。这对调试可能妨碍最终语言文件创建的错误很有用。

参见

关于如何自定义 makemessages 传递给 xgettext 的关键字,请参见 自定义 makemessages 命令 的说明。

makemigrations

django-admin makemigrations [app_label [app_label ...]]

根据检测到的模型变化创建新的迁移。迁移,它们与应用程序的关系以及更多的内容在 迁移文档 中深入介绍。

提供一个或多个应用名称作为参数,将把创建的迁移限制在指定的应用和任何所需的依赖关系上(例如,ForeignKey 的另一端的表)。

要将迁移添加到没有 migrations 目录的应用中,运行 makemigrations,并使用应用的 app_label

--noinput, --no-input

压制所有用户提示。如果不能自动解决被抑制的提示,命令将以 error code 3 退出。

--empty

为指定的应用程序输出一个空的迁移,用于手动编辑。这是为高级用户准备的,除非你熟悉迁移格式、迁移操作和迁移之间的依赖关系,否则不应使用。

--dry-run

显示在不向磁盘写入任何迁移文件的情况下进行的迁移。使用这个选项和 --verbosity 3 也会显示将被写入的完整迁移文件。

--merge

可以解决迁移冲突。

--name NAME, -n NAME

允许对生成的迁移进行命名,而不是使用生成的名称。名称必须是有效的 Python 标识符

--no-header

生成没有 Django 版本和时间戳头的迁移文件。

--check

当检测到没有迁移的模型变化时,使 makemigrations 以非零状态退出。

Changed in Django 3.2:

增加了在没有活动数据库连接的情况下调用 makemigrations 的支持。在这种情况下,将跳过对一致的迁移历史的检查。

migrate

django-admin migrate [app_label] [migration_name]

将数据库状态与当前的模型集和迁移同步。在 迁移文档 中深入介绍了迁移,它们与应用的关系等。

该命令的行为根据提供的参数而改变:

  • 没有参数:运行所有的应用程序的所有迁移。
  • <app_label> :指定的应用程序将运行其迁移,直至其最近的迁移。由于依赖关系,这可能涉及到运行其他应用的迁移。
  • <app_label> <migrationname>: 将数据库模式调整到适用指定迁移的状态,但不适用同一应用程序中后来的迁移。如果你之前已经迁移过命名的迁移,这可能涉及到取消应用迁移。你可以使用迁移名称的前缀,例如 0001,只要它对给定的应用程序名称是唯一的。使用名称 zero 来回溯所有的迁移,即恢复一个应用的所有已应用迁移。

警告

当取消应用迁移时,所有依赖的迁移也将被取消应用,无论 <app_label>。你可以使用 --plan 来检查哪些迁移将被取消应用。

--database DATABASE

指定要迁移的数据库。默认值为 default

--fake

标记目标的迁移(按照上面的规则)已应用,但没有实际运行 SQL 来改变你的数据库架构。

这是为高级用户准备的,如果他们要手动应用更改,可以直接操作当前的迁移状态;要注意的是,使用 --fake 会有将迁移状态表置于需要手动恢复才能使迁移正确运行的状态的风险。

--fake-initial

允许 Django 在迁移中所有 CreateModel 操作创建的所有模型名称的数据库表已经存在的情况下,跳过应用的初始迁移。这个选项是为了在第一次针对一个在使用 migrations 之前就存在的数据库运行迁移时使用。但是,除了匹配表名之外,这个选项并不检查数据库架构是否匹配,因此只有当你确信你现有的架构与初始迁移中记录的内容相匹配时,才可以安全使用。

--plan

显示对给定的 migrate 命令将进行的迁移操作。

--run-syncdb

允许在没有迁移的情况下为应用创建表。虽然不推荐这样做,但在有数百个模型的大型项目中,迁移框架有时太慢。

--noinput, --no-input

压制所有用户提示。一个例子是询问有关删除陈旧内容类型的提示。

--check
New in Django 3.1.

当检测到未应用的迁移时,使 migrate 以非零状态退出。

runserver

django-admin runserver [addrport]

在本地机器上启动一个轻量级的开发 Web 服务器。默认情况下,该服务器在 IP 地址 127.0.0.1 的 8000 端口上运行。你可以明确地传递一个 IP 地址和端口号。

如果你以普通用户的身份运行这个脚本 (推荐), 你可能无法在低端口号上启动一个端口。低端口号是为超级用户(root)保留的。

本服务器使用 WSGI_APPLICATION 配置中指定的 WSGI 应用对象。

请勿在生产环境中使用本服务器。它没有经过安全审计或性能测试。(这也是它将会一直存在的原因。我们的业务是制作 Web 框架,而不是 Web 服务器,所以改进这个服务器使其能够处理生产环境不在 Django 的范围之内。)

开发服务器会根据需要为每个请求自动重新加载 Python 代码。你不需要重新启动服务器以使代码更改生效。然而,有些操作,如添加文件不会触发重启,所以在这些情况下你必须重启服务器。

如果你使用的是 Linux 或 MacOS,并且同时安装了 pywatchmanWatchman 服务,内核信号将被用来自动加载服务器(而不是每秒轮询文件修改时间戳)。这为大型项目提供了更好的性能,减少了代码修改后的响应时间,更强大的变化检测,并减少了资源使用。Django 支持 pywatchman 1.2.0 及以上版本。

有许多文件的大目录可能会导致性能问题。

当使用 Watchman 时,如果项目中包含大的非 Python 目录,比如 node_modules,建议忽略这个目录以获得最佳性能。关于如何做到这一点,请参见 watchman文档

Watchman 超时

DJANGO_WATCHMAN_TIMEOUT

Watchman 客户端的默认超时时间是 5 秒。你可以通过设置 DJANGO_WATCHMAN_TIMEOUT 环境变量来改变它。

当你启动服务器时,以及每次在服务器运行时修改 Python 代码时,系统检查框架会检查你的整个 Django 项目是否存在一些常见的错误(参见 check 命令)。如果发现任何错误,它们将被打印到标准输出。

你可以运行任意多的并发服务器,只要它们在不同的端口上,只要执行 django-admin runerver 一次以上。

请注意,默认的 IP 地址 127.0.0.1 是不能从网络上的其他机器访问的。要使网络上的其他机器可以查看你的开发服务器,请使用它自己的 IP 地址(如 192.168.2.1)或 0.0.0.0:: (启用 IPv6)。

你可以提供一个用括号包围的 IPv6 地址(例如 [200a::1]:8000)。这将自动启用 IPv6 支持。

也可以使用只包含 ASCII 字符的主机名。

如果 staticfiles contrib 应用被启用(新项目中的默认值), runserver 命令将被它自己的 runserver 命令覆盖。

服务器的每个请求和响应的日志都会被发送到 django.server 日志器。

--noreload

禁用自动加载器。这意味着,如果特定的 Python 模块已经被加载到内存中,那么你在服务器运行时所做的任何 Python 代码更改将 不会 生效。

--nothreading

在开发服务器中禁止使用线程。默认情况下,服务器是多线程的。

--ipv6, -6

开发服务器使用 IPv6。这将默认 IP 地址从 127.0.0.1 改为 ::1

使用不同端口和地址的例子

IP 地址 127.0.0.1 上的 8000 端口:

django-admin runserver

IP 地址 1.2.3.4 上的 8000 端口:

django-admin runserver 1.2.3.4:8000

IP 地址 127.0.0.1 上的 7000 端口:

django-admin runserver 7000

IP 地址 1.2.3.4 上的 7000 端口:

django-admin runserver 1.2.3.4:7000

IPv6 地址 ::1 上的 8000 端口:

django-admin runserver -6

IPv6 地址 ::1 上的 7000 端口:

django-admin runserver -6 7000

IPv6 地址 2001:0db8:1234:5678::9 上的 7000 端口:

django-admin runserver [2001:0db8:1234:5678::9]:7000

主机 localhost 的 IPv4 地址上的 8000 端口:

django-admin runserver localhost:8000

主机 localhost 的 IPv6 地址上的 8000 端口:

django-admin runserver -6 localhost:8000

用开发服务器服务静态文件

默认情况下,开发服务器不会为你的网站提供任何静态文件(比如 CSS 文件、图片、 MEDIA_URL 下的东西等等)。如果你想设置 Django 为服务静态媒体,请阅读 管理静态文件(比如图片、JavaScript、CSS)

sendtestemail

django-admin sendtestemail [email [email ...]]

向指定的收件人发送一封测试邮件(确认通过 Django 发送邮件是否正常)。例如:

django-admin sendtestemail foo@example.com bar@example.com

有几个选项,你可以将它们任意组合在一起使用:

--managers

使用 mail_managers()MANAGERS 中指定的邮件地址发送邮件。

--admins

使用 mail_admins()ADMINS 中指定的邮件地址发送邮件。

shell

django-admin shell

启动 Python 交互式解释器。

--interface {ipython,bpython,python}, -i {ipython,bpython,python}

指定要使用的命令行。默认情况下,Django 会使用安装了的 IPythonbpython 。如果两者都安装了,请指定使用哪一个:

IPython:

django-admin shell -i ipython

bpython:

django-admin shell -i bpython

如果你安装了一个“富”命令行,但想强制使用“纯” Python 解释器,使用 python 作为接口名,比如:

django-admin shell -i python
--nostartup

禁止读取“纯" Python 解释器的启动脚本。默认情况下,读取 PYTHONSTARTUP 环境变量或 ~/.pythonrc.py 脚本所指向的脚本。

--command COMMAND, -c COMMAND

让你以字符串的方式传递一个命令,以 Django 的方式执行,比如:

django-admin shell --command="import django; print(django.__version__)"

你也可以在标准输入上传入代码来执行。例如:

$ django-admin shell <<EOF
> import django
> print(django.__version__)
> EOF

在 Windows 上,由于 select.select() 在该平台上的实现限制,REPL 被输出。

showmigrations

django-admin showmigrations [app_label [app_label ...]]

显示一个项目中的所有迁移。你可以从两种格式中选择一种:

--list, -l

列出 Django 知道的所有应用,每个应用的可用迁移,以及每个迁移是否被应用(在迁移名称旁边用 [X] 标记)。对于 --verbosity 2 及以上的应用,也会显示应用的日期时间。

没有迁移的应用程序也在列表中,但下面印有 (no migrations)

这是默认的输出格式。

--plan, -p

显示 Django 将遵循的迁移计划。和 --list 一样,应用的迁移也用 [X] 标记。对于 --verbosity 2 以上,也会显示迁移的所有依赖关系。

app_label 参数限制了输出,但是,所提供的应用的依赖也可能被包括在内。

--database DATABASE

指定要检查的数据库。默认为 default

sqlflush

django-admin sqlflush

打印 flush 命令执行的 SQL 语句。

--database DATABASE

指定要打印 SQL 的数据库。默认值为 default

sqlmigrate

django-admin sqlmigrate app_label migration_name

打印指定迁移的 SQL。这需要一个活动的数据库连接,它将用来解析约束名;这意味着你必须针对你希望以后应用它的数据库副本生成 SQL。

请注意,sqlmigrate 不会对其输出进行着色。

--backwards

生成用于解除应用迁移的 SQL。默认情况下,所创建的 SQL 是用于向前运行迁移。

--database DATABASE

指定要生成 SQL 的数据库。默认值为 default

sqlsequencereset

django-admin sqlsequencereset app_label [app_label ...]

打印用于重置给定应用名称序列的 SQL 语句。

序列是一些数据库引擎用来跟踪自动递增字段的下一个可用数字的索引。

使用此命令生成 SQL,它将修复序列与其自动递增的字段数据不同步的情况。

--database DATABASE

指定要打印 SQL 的数据库。默认值为 default

squashmigrations

django-admin squashmigrations app_label [start_migration_name] migration_name

如果可能的话,将 app_label 的迁移(包括 migration_name)压缩成较少的迁移。压制后的迁移可以和未压制的迁移安全地并存。更多信息,请阅读 压缩迁移

当给定 start_migration_name 时,Django 将只包含从这个迁移开始的迁移。这有助于减少 RunPythondjango.db.migrations.operations.RunSQL 迁移操作的限制。

--no-optimize

当生成一个压缩的迁移时,禁用优化器。默认情况下,Django 会尝试优化迁移中的操作,以减少生成文件的大小。如果这个过程失败或创建不正确的迁移,请使用这个选项,不过也请提交一个 Django 的 bug 报告来说明这个行为,因为优化的目的是为了安全。

--noinput, --no-input

禁止所有的用户提示。

--squashed-name SQUASHED_NAME

设置被压缩的迁移的名称。当省略时,名称以第一次和最后一次迁移为基础,中间为 _squashed_

--no-header

生成没有 Django 版本和时间戳头的压缩迁移文件。

startapp

django-admin startapp name [directory]

在当前目录或给定的目标目录中为给定的应用名创建一个 Django 应用目录结构。

默认情况下,新目录 包含 models.py 文件和其他应用模板文件。如果只给出应用名称,应用目录将被创建在当前工作目录下。

如果提供了可选的目的地,Django 将使用现有的目录,而不是创建一个新的目录。你可以使用 '.' 来表示当前的工作目录。

例子:

django-admin startapp myapp /Users/jezdez/Code/myapp
--template TEMPLATE

提供指向自定义应用模板文件目录的路径,或指向未压缩档案(.tar)或压缩档案(. tar.gz.tar.bz2.tar.xz.tar.lzma.tgz.tbz2.txz.tlz.zip)的路径。

例如,在创建 myapp 引用时,这将在给定目录中寻找一个应用模板:

django-admin startapp --template=/Users/jezdez/Code/my_app_template myapp

Django 还将接受 URL(httphttpsftp)与应用模板文件一起压缩归档,即时下载并解压。

例如,利用 GitHub 将仓库以 zip 文件形式公开的特性,你可以使用这样的 URL:

django-admin startapp --template=https://github.com/githubuser/django-app-template/archive/master.zip myapp
--extension EXTENSIONS, -e EXTENSIONS

指定应用模板中的哪些文件扩展名应该用模板引擎渲染。默认值为 py

--name FILES, -n FILES

指定应用模板中的哪些文件(除了那些匹配 --extension 的文件外)应该用模板引擎渲染。默认为空列表。

所有匹配文件使用的 template context 是:

  • 传递给 startapp 命令的任何选项(在命令行支持的选项中)
  • app_name ——传递给命令的应用名称
  • app_directory ——新创建的应用的完整路径
  • camel_case_app_name ——驼峰大小写格式的应用名称
  • docs_version ——文档的版本: 'dev''1.x'
  • django_version ——Django 的版本,例如 '2.0.3'

警告

当应用模板文件用 Django 模板引擎渲染时(默认是所有 *.py 文件),Django 也会替换掉所有包含的游离模板变量。例如,如果其中一个 Python 文件中包含了解释与模板渲染相关的特定功能的 docstring,可能会导致一个错误的例子。

为了解决这个问题,你可以使用 templatetag 模板标签来”转义“模板语法的各个部分。

此外,为了允许包含 Django 模板语言语法的 Python 模板文件,同时也为了防止打包系统试图对无效的 *.py 文件进行字节编译,以 .py-tpl 结尾的模板文件将改名为 .py

startproject

django-admin startproject name [directory]

在当前目录或给定的目标目录中为给定的项目名称创建一个 Django 项目目录结构。

默认情况下,新目录 包含 manage.py 和一个项目包(包含 settings.py 和其他文件)。

如果只给出项目名称,则项目目录和项目包都将命名为 <projectname>,并在当前工作目录下创建项目目录。

如果提供了可选的目的地,Django 将使用该已有目录作为项目目录,并在其中创建 manage.py 和项目包。用 '.' 表示当前的工作目录。

例子:

django-admin startproject myproject /Users/jezdez/Code/myproject_repo
--template TEMPLATE

指定一个自定义项目模板的目录、文件路径或 URL。参见 startapp --template 文档中的例子和用法。

--extension EXTENSIONS, -e EXTENSIONS

指定项目模板中的哪些文件扩展名应该用模板引擎渲染。默认值为 py

--name FILES, -n FILES

指定项目模板中的哪些文件(除了那些匹配 --extension 的文件外)应该用模板引擎渲染。默认为空列表。

使用的 template context 是:

  • 传递给 startproject 命令的任何选项(在命令支持的选项中)
  • project_name ——传给命令的项目名称
  • project_directory ——新创建项目的完整路径
  • secret_key —— SECRET_KEY 设置的随机密钥
  • docs_version ——文档的版本: 'dev''1.x'
  • django_version ——Django 的版本,例如 '2.0.3'

也请参考 startapp 中提到的 渲染警告

test

django-admin test [test_label [test_label ...]]

为所有安装的应用运行测试。参见 Django 中的测试 获取更多信息。

--failfast

测试失败后立即停止运行测试并报告失败。

--testrunner TESTRUNNER

控制用于执行测试的测试运行器类。这个值会覆盖 TEST_RUNNER 配置提供的值。

--noinput, --no-input

压制所有用户提示。一个典型的提示是关于删除现有测试数据库的警告。

测试运行器选项

test 命令代表指定的 --testrunner 接收选项。这些是默认测试运行器的选项: DiscoverRunner

--keepdb

在测试运行之间保留测试数据库。这样做的好处是可以跳过创建和销毁这两个动作,从而大大缩短测试运行的时间,尤其是在大型测试套件中。如果测试数据库不存在,将在第一次运行时创建,然后在以后的每次运行中保留。除非 MIGRATE 测试配置为 False,否则任何未应用的迁移也会在运行测试套件之前应用到测试数据库。

--reverse, -r

以相反的执行顺序对测试用例进行排序。按测试类分组 在使用该选项时将被保留。

--debug-mode

在运行测试之前,将 DEBUG 设置为 True。这可能有助于解决测试失败的问题。

--debug-sql, -d

对失败的测试启用 SQL 日志。如果 --verbosity2,那么通过测试的查询也会被输出。

--parallel [N]
DJANGO_TEST_PROCESSES

在单独的并行进程中运行测试。由于现代处理器拥有多个内核,这使得运行测试的速度大大加快。

默认情况下,--parallel 根据 multiprocessing.cpu_count(),每个内核运行一个进程。你可以通过提供它作为选项的值来调整进程数量,例如 --parallel=4,或者通过设置 DJANGO_TEST_PROCESSES 环境变量来调整。

Django 将测试用例—— unittest.TestCase 子类——分配给子进程。如果测试用例比配置的进程少,Django 会相应减少进程的数量。

每个进程都会得到它们自己的数据库。你必须确保不同的测试用例不会访问相同的资源。例如,接触文件系统的测试用例应该创建一个临时目录供自己使用。

注解

如果你有不能并行运行的测试类,你可以使用 SerializeMixin 按顺序运行它们。参见 强制按顺序运行测试类

这个选项需要第三方的 tlib 包才能正确显示回溯。

$ python -m pip install tblib

这个功能在 Windows 上无法使用。它也不能与 Oracle 数据库后端一起工作。

如果你想在调试测试时使用 pdb,你必须禁用并行执行(-parallel=1)。如果不这样做,你会看到类似 bdb.BdbQuit 的东西。

警告

当启用测试并行化后,测试失败时,Django 可能无法显示异常回溯。这可能会给调试带来困难。如果你遇到这个问题,请在不并行的情况下运行受影响的测试,以查看失败的回溯。

这是一个众所周知的限制。这是因为需要对对象进行序列化,以便在进程间进行交换。详见 What can be pickled and unpickled?

--tag TAGS

只运行 特定标签标记 的测试。可多次指定,并与 test --exclud-tag 结合使用。

--exclude-tag EXCLUDE_TAGS

不包括 特定标签标记的 测试。可多次指定,并与 test --tag 结合使用。

-k TEST_NAME_PATTERNS

运行与测试名称模式相匹配的测试方法和类,与 unittest's -k option 一样。可以指定多次。

Python 3.7 及以后版本

这个功能只适用于 Python 3.7 及以后的版本。

--pdb

在每次测试错误或失败时,都会产生一个 pdb 调试器。如果你安装了 ipdb,则使用其代替。

--buffer, -b
New in Django 3.1.

丢弃通过测试的输出(stdoutstderr),与 unittest's --buffer option 一样。

--no-faulthandler
New in Django 3.2.

Django 在启动测试时自动调用 faulthandler.enable(),这允许它在解释器崩溃时打印一个回溯信息。传递 --no-faulthandler 来禁止这种行为。

--timing
New in Django 3.2.

输出时间,包括数据库设置和总运行时间。

testserver

django-admin testserver [fixture [fixture ...]]

使用给定固定数据中的数据运行一个 Django 开发服务器(如 runserver)。

例如,这个命令:

django-admin testserver mydata.json

...将执行以下步骤:

  1. 按照 测试数据库 中的描述,创建一个测试数据库。
  2. 用给定固定数据的数据填充测试数据库。关于固定数据的更多信息,请参见上面的 loaddata 的文档)。
  3. 运行 Django 开发服务器(如 runserver),指向这个新创建的测试数据库,而不是你的生产数据库。

这在很多方面都很有用:

  • 当你在编写 单元测试 的时候,你可以使用 testserver 在 Web 浏览器中手动与视图交互。
  • 假设你正在开发 Django 应用,并且有一个“原始”的数据库副本,你想与之交互。你可以将你的数据库转储到一个固定数据中(使用 dumpdata 命令,上面已经解释过了),然后使用 testserver 用这些数据运行你的 Web 应用程序。有了这种安排,你可以灵活地以任何方式搞乱你的数据,因为你知道你所做的任何数据改变都只是对测试数据库进行的。

请注意,这个服务器 不会 自动检测你的 Python 源代码的变化(就像 srunerver 那样)。但是,它可以检测到对模板的更改。

--addrport ADDRPORT

指定与默认的 127.0.0.1:8000 不同的端口或 IP 地址和端口。这个值的格式和作用与 runserver 命令的参数完全相同。

举例:

fixture1fixture2 在 7000 端口运行测试服务器:

django-admin testserver --addrport 7000 fixture1 fixture2
django-admin testserver fixture1 fixture2 --addrport 7000

(上面的语句是等价的。我们把这两句话都包括在内,是为了证明选项是在固定数据参数之前还是之后并不重要。)

在 1.2.3.4:7000 上用 test 固定数据运行:

django-admin testserver --addrport 1.2.3.4:7000 test
--noinput, --no-input

压制所有用户提示。一个典型的提示是关于删除现有测试数据库的警告。

应用程序提供的命令

有些命令只有 enabled 实现 它们的 django.contrib 应用程序时才可用。本节将按照应用来介绍这些命令。

django.contrib.auth

changepassword

django-admin changepassword [<username>]

只有安装了 Django 的 认证系统django.contrib.auth),这个命令才有效。

允许更改用户的密码。它提示你为给定的用户输入两次新密码。如果输入的密码相同,则立即成为新密码。如果你没有提供用户,命令将尝试更改与当前用户用户名匹配的密码。

--database DATABASE

指定要为用户查询的数据库。默认为 default

用法示例:

django-admin changepassword ringo

createsuperuser

django-admin createsuperuser
DJANGO_SUPERUSER_PASSWORD

只有安装了 Django 的 认证系统django.contrib.auth),这个命令才有效。

创建一个超级用户账户(拥有所有权限的用户)。如果你需要创建一个初始的超级用户账户,或者你需要为你的网站程序化地生成超级用户账户,这很有用。

当交互式运行时,该命令将提示为新的超级用户账户提供密码。非交互式运行时,可以通过设置 DJANGO_SUPERUSER_PASSWORD 环境变量提供密码。否则,将不设置密码,超级用户账户将无法登录,直到手动为其设置密码。

在非交互模式下, USERNAME_FIELD 和必填字段(列在 REQUIRED_FIELDS 中)回落到 DJANGO_SUPERUSER_<uppercase_field_name> 环境变量,除非它们被命令行参数覆盖。例如,要提供一个 email 字段,你可以使用 DJANGO_SUPERUSER_EMAIL 环境变量。

--noinput, --no-input

压制所有用户提示。如果被抑制的提示不能自动解决,命令将以 error code 1 退出。

--username USERNAME
--email EMAIL

新账户的用户名和电子邮件地址可以通过使用命令行中的 --username--email 参数来提供。如果没有提供这两个参数中的任何一个,createsuperuser 将在交互式运行时提示输入。

--database DATABASE

指定保存超级用户对象的数据库。

如果你想自定义数据输入和验证,可以子类管理命令,并覆盖 get_input_data()。关于现有的实现和方法的参数,请查阅源代码。例如,如果你在 REQUIRED_FIELDS 中有一个 ForeignKey,并且希望允许创建一个实例,而不是输入现有实例的主键,这可能是有用的。

django.contrib.contenttypes

remove_stale_contenttypes

django-admin remove_stale_contenttypes

只有安装了 Django 的 contenttypes 应用django.contrib.contenttypes),这个命令才有效。

删除数据库中陈旧的内容类型(来自已删除的模型)。依赖于已删除内容类型的任何对象也将被删除。在你确认可以继续删除之前,将显示一个已删除对象的列表。

--database DATABASE

指定要使用的数据库。默认为 default

--include-stale-apps
New in Django 3.1.

删除陈旧的内容类型,包括以前安装的应用程序的内容类型,这些内容类型已经从 INSTALLED_APPS 中删除。默认值为 False

django.contrib.gis

ogrinspect

只有在安装了 GeoDjangodjango.contrib.gis)的情况下,该命令才可用。

请参考 GeoDjango 文档中它的 描述

django.contrib.sessions

clearsessions

django-admin clearsessions

可以以定时任务的形式运行,也可以直接清理过期会话。

django.contrib.sitemaps

ping_google

只有安装了 站点地图框架django.contrib.sitemaps),该命令才可用。

请参考站点地图文档中的 描述

django.contrib.staticfiles

collectstatic

只有安装了 静态文件应用程序django.contrib.staticfiles),该命令才可用。

请参考它的 静态文件 文档中的 描述

findstatic

只有安装了 静态文件应用程序django.contrib.staticfiles),该命令才可用。

请参考它的 静态文件 文档中的 描述

默认选项

Although some commands may allow their own custom options, every command allows for the following options by default:

--pythonpath PYTHONPATH

将给定的文件系统路径添加到 Python import 搜索路径 中。如果没有提供,django-admin 将使用 PYTHONPATH 环境变量。

这个选项在 manage.py 中是不必要的,因为它为你设置了 Python 路径。

用法示例:

django-admin migrate --pythonpath='/home/djangoprojects/myproject'
--settings SETTINGS

指定要使用的配置模块。配置模块应该使用 Python 包语法,例如 mysite.settings。如果没有提供,django-admin 将使用 DJANGO_SETTINGS_MODULE 环境变量。

这个选项在 manage.py 中是不必要的,因为它默认使用当前项目中的 settings.py

用法示例:

django-admin migrate --settings=mysite.settings
--traceback

当发生 CommandError 时,显示完整的堆栈跟踪。默认情况下,django-admin 将在发生 CommandError 时显示一个错误信息,并对任何其他异常显示一个完整的堆栈跟踪。

This option is ignored by runserver.

用法示例:

django-admin migrate --traceback
--verbosity {0,1,2,3}, -v {0,1,2,3}

指定命令应打印到控制台的通知和调试信息的数量。

  • 0 表示没有输出。
  • 1 表示正常输出(默认)。
  • 2 表示详细输出。
  • 3 表示 非常 详细输出。

This option is ignored by runserver.

用法示例:

django-admin migrate --verbosity 2
--no-color

禁用彩色化的命令输出。 有些命令会将其输出格式化为彩色。例如,错误将以红色打印到控制台,SQL 语句将以语法高亮显示。

用法示例:

django-admin runserver --no-color
--force-color

强制对命令输出进行着色,如果不这样做的话,就会像 语法着色 中所讨论的那样被禁用。例如,你可能希望将彩色输出管道到另一个命令。

--skip-checks

在运行命令之前,跳过运行系统检查。这个选项只有在 required_system_checks 命令属性不是一个空列表或元组时才可用。

用法示例:

django-admin migrate --skip-checks

额外的细节

语法着色

DJANGO_COLORS

django-adminmanage.py 命令会使用漂亮的彩色编码输出,如果你的终端支持 ANSI 彩色输出的话。如果你把命令的输出用管道传送到另一个程序,它不会使用颜色代码,除非使用 --force-color 选项。

Windows 支持

在 Windows 10 上,Windows Terminal 应用程序、VS Code 和 PowerShell(启用虚拟终端处理)允许彩色输出,并且默认支持。

在 Windows 下,传统的 cmd.exe 本地控制台不支持 ANSI 转义序列,所以默认情况下没有彩色输出。在这种情况下,需要两个第三方库中的一个:

  • 安装 colorama ,一个将 ANSI 颜色代码翻译成 Windows API 调用的 Python 包。Django 命令会检测到它的存在,并利用它的服务为输出着色,就像在基于 Unix 的平台上一样。colorama 可以通过 pip 安装:

    ...\> py -m pip install colorama
    
  • 安装 ANSICON ,一个第三方工具,允许 cmd.exe 处理 ANSI 颜色代码。Django 命令会检测到它的存在,并利用它的服务为输出着色,就像在基于 Unix 的平台上一样。

在 Windows 上的其他现代终端环境,支持终端颜色,但没有被 Django 自动检测到,可以通过设置适当的环境变量 ANSICON="on" 来 “假装” 安装 ANSICON

Changed in Django 3.2:

更新了对 Windows 上语法着色的支持。

自定义颜色

语法高亮的颜色是可以自定义的。Django 有三种调色板:

  • dark,适合在黑色背景上显示白色文字的终端。这是默认的调色板。
  • light,适用于白底黑字的终端。
  • nocolor,禁用语法高亮。

你可以通过设置 DJANGO_COLORS 环境变量来选择调色板,以指定你要使用的调色板。例如,要在 Unix 或 OS/X BASH 命令行下指定 light 调色板,你可以在命令提示符下运行以下内容:

export DJANGO_COLORS="light"

你也可以自定义使用的颜色。Django 指定了一些使用颜色的角色:

  • error - 一个重大错误。
  • notice - 一个小错误。
  • success - 成功。
  • warning - 警告。
  • sql_field - SQL 中模型字段的名称。
  • sql_coltype - SQL 中模型字段的类型。
  • sql_keyword - 一个 SQL 关键字。
  • sql_table - SQL 中的模型名称。
  • http_info - 一个 1XX 的 HTTP Informational 服务器响应。
  • http_success - 一个 2XX 的 HTTP Success 服务器响应。
  • http_not_modified - 一个 304 HTTP Not Modified 服务器响应。
  • http_redirect - 一个除 304 之外的 3XX HTTP 重定向服务器响应。
  • http_not_found - 一个 404 HTTP Not Found 服务器响应。
  • http_bad_request - 一个除了 404 之外的 4XX HTTP Bad Request 服务器响应。
  • http_server_error - 5XX HTTP 服务器错误响应。
  • migrate_heading - 迁移管理命令中的标题。
  • migrate_label - 迁移名称。

这些角色中的每一个都可以从以下列表中指定特定的前景和背景颜色:

  • black
  • red
  • green
  • yellow
  • blue
  • magenta
  • cyan
  • white

然后可以通过使用以下显示选项来修改这些颜色:

  • bold
  • underscore
  • blink
  • reverse
  • conceal

颜色规格遵循以下模式之一:

  • role=fg
  • role=fg/bg
  • role=fg,option,option
  • role=fg/bg,option,option

其中 role 是一个有效颜色角色的名称,fg 是前景色,bg 是背景色,每个 option 是颜色修改选项之一。然后用分号分隔多个颜色规范。例如:

export DJANGO_COLORS="error=yellow/blue,blink;notice=magenta"

将指定使用蓝色上闪烁的黄色显示错误,使用洋红色显示通知。所有其他颜色角色将不着色。

也可以通过扩展基本调色板来指定颜色。如果你在颜色规格中加入一个调色板名称,那么该调色板所隐含的所有颜色都会被加载。所以:

export DJANGO_COLORS="light;error=yellow/blue,blink;notice=magenta"

将指定使用浅色调色板中的所有颜色,除了 错误和通知的颜色,这些颜色将被覆盖。

Bash 补全

如果你使用 Bash shell,可以考虑安装 Django 的 bash 补全脚本,它在 Django 源码发行版的 extras/django_bash_completion 中。它可以使 django-adminmanage.py 命令的 tab 补全,所以你可以,例如...

  • 输入 django-admin
  • 按 [TAB] 查看所有可用选项。
  • 输入 sql,然后输入 [TAB],查看所有名称以 sql 开头的可用选项。

关于如何添加自定义动作,请参见 编写自定义 django-admin 命令

从你的代码中运行管理命令

django.core.management.call_command(name, *args, **options)

要从代码中调用管理命令,使用 call_command

name
要调用的命令名称或命令对象的名称。除非测试时需要该对象,否则最好传递名称。
*args
命令接受的参数列表。参数被传递给参数解析器,所以你可以使用与命令行相同的风格。例如,call_command('flush', '--verbosity=0')
**options
在命令行中接受的命名选项。选项传递给命令时不会触发参数解析器,这意味着你需要传递正确的类型。例如,call_command('flush', verbosity=0) (0 必须是一个整数而不是字符串)。

举例:

from django.core import management
from django.core.management.commands import loaddata

management.call_command('flush', verbosity=0, interactive=False)
management.call_command('loaddata', 'test_data', verbosity=0)
management.call_command(loaddata.Command(), 'test_data', verbosity=0)

需要注意的是,没有参数的命令选项是以关键字 TrueFalse 的形式传递的,如上面的 interactive 选项。

命名的参数可以通过使用以下任何一种语法来传递:

# Similar to the command line
management.call_command('dumpdata', '--natural-foreign')

# Named argument similar to the command line minus the initial dashes and
# with internal dashes replaced by underscores
management.call_command('dumpdata', natural_foreign=True)

# `use_natural_foreign_keys` is the option destination variable
management.call_command('dumpdata', use_natural_foreign_keys=True)

当使用 call_command() 而不是 django-adminmanage.py 时,一些命令选项有不同的名称。例如,django-admin createsuperuser --no-input 翻译成 call_command('creasuperuser', interactive=False)。要找到 call_command() 的关键字参数名,请检查命令的源代码中传递给 parser.add_argument()dest 参数。

取多个选项的命令选项会通过一个列表:

management.call_command('dumpdata', exclude=['contenttypes', 'auth'])

call_command() 函数的返回值与命令的 handle() 方法的返回值相同。

输出重定向

注意,你可以重定向标准输出和错误流,因为所有命令都支持 stdoutstderr 选项。例如,你可以写:

with open('/path/to/command_output', 'w') as f:
    management.call_command('dumpdata', stdout=f)
Back to Top