编写自定义 `django-admin` 命令

要做到这一点，在应用程序中添加一个 management/commands 目录。Django 会给目录下的每个 Python 模块注册一个 manage.py 命令，这个命令的名字不以下划线开头。例如：

在这个例子中，closepoll 命令将提供给任何在中包含 polls 应用程序的项目。

_private.py 模块将不会作为管理命令使用。

closepoll.py 模块只有一个要求——必须定义 Command 类，该类继承自 BaseCommand 或其。

独立的脚本

自定义管理命令在运行独立脚本命令方面十分有用，也可用于 UNIX 的周期性 crontab 任务，或是 Windows 的定时任务。

要实现该命令，请编辑 polls/management/commands/closepoll.py 如下：

from django.core.management.base import BaseCommand, CommandError
from polls.models import Question as Poll
class Command(BaseCommand):
    help = 'Closes the specified poll for voting'
        parser.add_argument('poll_ids', nargs='+', type=int)
    def handle(self, *args, **options):
        for poll_id in options['poll_ids']:
            try:
                poll = Poll.objects.get(pk=poll_id)
            except Poll.DoesNotExist:
                raise CommandError('Poll "%s" does not exist' % poll_id)
            poll.opened = False
            poll.save()
            self.stdout.write(self.style.SUCCESS('Successfully closed poll "%s"' % poll_id))

注解

当你使用管理命令并希望提供控制台输出时，你需要 write 至 self.stdout 和 self.stderr，而不是直接 print 至 stdout 和 stderr。利用这些代理，测试自定义命令会更方便。还需要注意的是，你不需要用换行符来结束消息，它会自动添加，除非你指定了 ending 参数：

这个新的自定义命令能用 python manage.py closepoll <poll_ids> 调用。

handle() 方法接受一个或多个 poll_ids，并将每个 poll.opened 设置为 False。若用户传入了不存在的 polls，将会抛出 CommandError。中不存在 poll.opened 属性，只是这里为了本例添加至 polls.models.Question 的。

同样的 closepoll 可以很容易地修改，通过接受额外的命令行选项来删除一个给定的投票，而不是关闭它。这些自定义选项可以在 add_arguments() 方法中添加，比如：

class Command(BaseCommand):
        parser.add_argument('poll_ids', nargs='+', type=int)
        # Named (optional) arguments
        parser.add_argument(
            '--delete',
            action='store_true',
            help='Delete poll instead of closing it',
        )
    def handle(self, *args, **options):
        # ...
        if options['delete']:
            poll.delete()
        # ...

选项（本例中 delete）是由 handle 方法的 options 字典参数传入的。参见 Python 文档查询，获取更多 add_argument 的用法。

为了能添加自定义命令选项，所以的管理命令都能接受一些默认选项，例如和 --traceback。

默认情况下，管理命令以当前活动的 locale 执行。

如果由于某些原因，你的自定义管理命令必须在没有活动的 locale 的情况下运行（例如，为了防止翻译的内容被插入数据库），请在你的方法上使用 @no_translations 装饰器停用翻译：

由于禁用翻译需要使用配置文件，故装饰器不能用于那些不加载配置文件的命令。

关于如何测试自定义管理命令的内容可在测试文档中找到。

Django 先注册内置命令，然后按相反的顺序在查找命令。在查找时，如果一个命令和已注册的命令重名，这个新发现的命令会覆盖第一个命令。

换句话说，为了覆盖一个命令，新命令必须有同样的名字并且它的 app 在 INSTALLED_APPS 中必须排在被覆盖命令 app 的前面。

第三方应用提供的管理命令若被不小心重写，能通过在你项目中的某个应用（在配置在第三方应用之前）创建新命令的方式为其取个别名，另其能被调用。这个应用需要导入被重写的 Command。

class BaseCommand

所有管理命令最终派生的基类。

如果你想处理解析命令行参数，决定调用什么代码的过程，使用这个类。如果你不需要改变任何行为，考虑直接使用它的某个子类。

继承要求你重写 handle() 方法。

能被你派生的子类设置的，且能被的子类使用的属性。

命令简介，当用户运行命令 python manage.py help <command> 时包含在打印的帮助信息内。

BaseCommand.``missing_args_message

如果你的命令定义了必须的位置参数，你可以在缺失参数时返回自定义错误消息。默认输出由打印(“too few arguments”)。

BaseCommand.``output_transaction

一个布尔值，决定命令是否暑输出 SQL 语句；若为 True，输出内容会自动以 BEGIN; 和 COMMIT; 包裹。默认值为 False。

BaseCommand.``requires_migrations_checks

一个布尔值；若为 True，命令会在硬盘上存储的 migrations 与数据库中的不一致时打印警告。警告不会阻止命令执行。默认值为 False。

BaseCommand.``requires_system_checks

A list or tuple of tags, e.g. [Tags.staticfiles, Tags.models]. System checks registered in the chosen tags will be checked for errors prior to executing the command. The value '__all__' can be used to specify that all system checks should be performed. Default value is '__all__'.

Changed in Django Development version:

In older versions, the requires_system_checks attribute expects a boolean value instead of a list or tuple of tags.

BaseCommand.``style

一个实例属性，用于向 stdout 或 stderr 输出彩色内容。例如:

self.stdout.write(self.style.SUCCESS('...'))

参考语法着色了解如何修改调色板与现成的样式（使用本节介绍的大写字母版本的 “roles”）。

如果运行命令时传递了选项，所有的调用会返回未染色的原始字符串。

BaseCommand 有很多方法可供重写，不过仅有是必须实现的。

子类中实现构造器

若 BaseCommand 的子类实现了 __init__ 方法，那么就必须调用的 __init__:

BaseCommand.``create_parser(prog_name, subcommand, \*kwargs*)

返回一个 CommandParser 实例，它是 ArgumentParser 的子类，包含一些针对 Django 的个性化设计。

你可以自定义这个实例，通过重写此方法，并为 super() 方法传入值为的 kwargs 参数。

BaseCommand.``add_arguments(parser)

添加命令行转换参数的入口，用于处理传给命令行的参数。自定义命令需要重写此方法，并同时添加命令接受的位置参数和可选参数。直接使用 BaseCommand 的子类时无需调用 super()。

BaseCommand.``get_version()

返回 Django 版本，内置 Django 命令必须正确返回。用户实现的命令可以重写此方法返回自己的版本。

BaseCommand.``execute(\args, **options*)

在你的代码中调用管理命令

执行命令时，不要从代码直接调用 execute() 方法。而是使用 call_command()。

BaseCommand.``handle(\args, **options*)

命令的实际逻辑处理。子类必须实现此方法。

此方法可能会返回一个字符串，输出至 stdout （若为 True，则由 BEGIN; 和 COMMIT 包裹）。

BaseCommand.``check(app_configs=None, tags=None, display_num_errors=False)

利用系统检查框架校验 Django 项目是否存在隐含的问题。严重的问题会抛出 CommandError；警告会输出至 stderr；次要通知输出至 stdout。

若 app_configs 和 tags 均为 None，所以的系统检查项都会被运行。tags 能是一个检查标签的列表，例如 compatibility 或 models。

class AppCommand

管理命令接受一个或多个应用标签参数，并对每项应用做某些事。

子类必须实现，而不是 handle()。此方法会为每个应用调用一次。

AppCommand.``handle_app_config(app_config, \*options*)

为 app_config 运行命令，这会是的实例，并指向命令行给定的应用标签。

class LabelCommand

一个管理命令，从命令行接受一个或任意多个参数(labels)，并针对每项做些事情。

子类必须实现 handle_label()，而不是。此方法会为每个应用调用一次。

LabelCommand.``label

一个字符串，介绍了传递给命令的任意多个参数。此字符串用于命令的用法文本和错误消息。默认为 'label'。

LabelCommand.``handle_label(label, \*options*)

运行 label 指定的命令动作，由命令行传入的字符串指定。

exception CommandError(returncode=1)

异常类说明在运行管理命令时出错了。

在命令行控制台里执行管理命令的过程中，如果抛出了这个异常，该异常将会被捕获并以便于阅读的样子打印到对应的输出流（i.e., stderr）；因此，抛出这个异常（对错误的适当描述）是说明命令执行出错了的首选方式。它接收可选参数 returncode 来使用 sys.exit() 自定义退出管理命令所用的退出状态。

如果管理命令是由调用的，是否捕获异常取决于你。

Changed in Django 3.1:

新增了 returncode 参数。

编写自定义 django-admin 命令

编写自定义 django-admin 命令

编写自定义 `django-admin` 命令