如何创建自定义 django-admin 命令

应用程序可以使用 manage.py 注册自己的操作。例如，您可能希望为要分发的 Django 应用程序添加一个 manage.py 操作。在本文档中，我们将为 教程 中的 polls 应用程序构建一个自定义的 closepoll 命令。

为此，请在应用程序中添加一个 management/commands 目录。Django 将为该目录中每个名称不以下划线开头的 Python 模块注册一个 manage.py 命令。例如

polls/
    __init__.py
    models.py
    management/
        __init__.py
        commands/
            __init__.py
            _private.py
            closepoll.py
    tests.py
    views.py

在此示例中，closepoll 命令将可用于将 polls 应用程序包含在 INSTALLED_APPS 中的任何项目。

_private.py 模块将不可用作管理命令。

closepoll.py 模块只有一个要求 - 它必须定义一个扩展 BaseCommand 或其 子类 的类 Command。

独立脚本

自定义管理命令对于运行独立脚本或从 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"

    def add_arguments(self, parser):
        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)
            )

注意

当您使用管理命令并希望提供控制台输出时，您应该写入 self.stdout 和 self.stderr，而不是直接打印到 stdout 和 stderr。通过使用这些代理，测试自定义命令变得容易得多。另请注意，您无需在消息末尾添加换行符，它将自动添加，除非您指定 ending 参数

self.stdout.write("Unterminated line", ending="")

可以使用 python manage.py closepoll <poll_ids> 调用新的自定义命令。

handle() 方法接受一个或多个 poll_ids，并为每个 poll_ids 将 poll.opened 设置为 False。如果用户引用了任何不存在的投票，则会引发 CommandError。属性 poll.opened 在 教程 中不存在，并在本示例中添加到 polls.models.Question 中。

接受可选参数

相同的 closepoll 可以轻松修改为删除给定的投票而不是关闭它，方法是接受其他命令行选项。这些自定义选项可以在 add_arguments() 方法中添加，如下所示

class Command(BaseCommand):
    def add_arguments(self, parser):
        # Positional arguments
        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 dict 参数中可用。有关 add_argument 用法的更多信息，请参阅 argparse Python 文档。

除了能够添加自定义命令行选项外，所有 管理命令 都可以接受一些默认选项，例如 --verbosity 和 --traceback。

管理命令和语言环境

默认情况下，管理命令使用当前活动的语言环境执行。

如果由于某种原因，您的自定义管理命令必须在没有活动语言环境的情况下运行（例如，为防止将翻译后的内容插入数据库），请使用 @no_translations 装饰器在您的 handle() 方法上停用翻译

from django.core.management.base import BaseCommand, no_translations


class Command(BaseCommand):
    ...

    @no_translations
    def handle(self, *args, **options): ...

由于翻译停用需要访问已配置的设置，因此该装饰器不能用于无需配置设置即可工作的命令。

测试

有关如何测试自定义管理命令的信息，请参阅 测试文档。

覆盖命令

Django 注册内置命令，然后反向搜索 INSTALLED_APPS 中的命令。在搜索过程中，如果命令名称重复了已注册的命令，则新发现的命令将覆盖第一个命令。

换句话说，要覆盖命令，新命令必须具有相同的名称，并且其应用程序必须在 INSTALLED_APPS 中被覆盖的命令的应用程序之前。

可以通过在您的项目应用程序之一中创建一个新命令（在 INSTALLED_APPS 中位于第三方应用程序之前）来使意外被覆盖的第三方应用程序的管理命令在新的名称下可用，该命令导入被覆盖命令的 Command。

命令对象

class BaseCommand[source]

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

如果您希望访问解析命令行参数并确定要响应调用哪些代码的所有机制，请使用此类；如果您不需要更改任何此类行为，请考虑使用其 子类 之一。

子类化 BaseCommand 类要求您实现 handle() 方法。

属性

所有属性都可以在您的派生类中设置，并且可以在 BaseCommand 的 子类 中使用。

BaseCommand.help

命令的简短描述，当用户运行命令 python manage.py help <command> 时，它将打印在帮助消息中。

BaseCommand.missing_args_message

如果您的命令定义了强制位置参数，则可以在缺少参数的情况下自定义返回的消息错误。默认值由 argparse 输出（“参数太少”）。

BaseCommand.output_transaction

一个布尔值，指示命令是否输出 SQL 语句；如果为True，输出将自动用BEGIN;和COMMIT;包裹。默认值为False。

BaseCommand.requires_migrations_checks

一个布尔值；如果为True，则如果磁盘上的迁移集与数据库中的迁移不匹配，命令会打印一条警告。警告不会阻止命令执行。默认值为False。

BaseCommand.requires_system_checks

标签列表或元组，例如[Tags.staticfiles, Tags.models]。在执行命令之前，将检查在所选标签中注册的系统检查是否存在错误。值'__all__'可用于指定应执行所有系统检查。默认值为'__all__'。

BaseCommand.style

一个实例属性，有助于在写入stdout或stderr时创建彩色输出。例如

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

请参阅语法着色，了解如何修改调色板以及查看可用的样式（使用该部分中描述的“角色”的大写版本）。

如果在运行命令时传递--no-color选项，则所有self.style()调用都将返回未着色的原始字符串。

BaseCommand.suppressed_base_arguments

在帮助输出中要抑制的默认命令选项。这应该是一组选项名称（例如'--verbosity'）。抑制选项的默认值仍然会传递。

方法

BaseCommand有一些可以重写的方法，但只有handle()方法必须实现。

在子类中实现构造函数

如果在BaseCommand的子类中实现了__init__，则必须调用BaseCommand的__init__

class Command(BaseCommand):
    def __init__(self, *args, **kwargs):
        super().__init__(*args, **kwargs)
        # ...
BaseCommand.create_parser(prog_name, subcommand, **kwargs)[source]

返回一个CommandParser实例，它是一个ArgumentParser子类，对 Django 进行了一些自定义。

可以通过重写此方法并使用ArgumentParser参数的kwargs调用super()来自定义实例。

BaseCommand.add_arguments(parser)[source]

入口点，用于向解析器添加参数以处理传递给命令的命令行参数。自定义命令应重写此方法以添加命令接受的位置和可选参数。当直接子类化BaseCommand时，不需要调用super()。

BaseCommand.get_version()[source]

返回 Django 版本，对于所有内置的 Django 命令，此版本都应该是正确的。用户提供的命令可以重写此方法以返回自己的版本。

BaseCommand.execute(*args, **options)[source]

尝试执行此命令，根据需要执行系统检查（由requires_system_checks属性控制）。如果命令引发CommandError，则会将其拦截并打印到stderr。

在代码中调用管理命令

不应直接从代码中调用execute()来执行命令。请改用call_command()。

BaseCommand.handle(*args, **options)[source]

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

它可能会返回一个字符串，该字符串将打印到stdout（如果output_transaction为True，则用BEGIN;和COMMIT;包裹）。

BaseCommand.check(app_configs=None, tags=None, display_num_errors=False, include_deployment_checks=False, fail_level=checks.ERROR, databases=None)[source]

使用系统检查框架检查整个 Django 项目是否存在潜在问题。严重问题会作为CommandError引发；警告输出到stderr；次要通知输出到stdout。

如果app_configs和tags都为None，则执行所有系统检查，但部署和数据库相关的检查除外。tags可以是检查标签列表，如compatibility或models。

可以传递include_deployment_checks=True以执行部署检查，并在databases中列出数据库别名以针对它们运行数据库相关的检查。

BaseCommand子类

class AppCommand

一个管理命令，它将一个或多个已安装的应用程序标签作为参数，并对每个标签执行某些操作。

子类必须实现 handle_app_config()，而不是实现 handle()，每个应用程序都会调用一次 handle_app_config()。

AppCommand.handle_app_config(app_config, **options)

对 app_config 执行命令的操作，app_config 将是 AppConfig 实例，对应于命令行上给定的应用程序标签。

class LabelCommand

一个管理命令，它在命令行上接受一个或多个任意参数（标签），并对每个参数执行某些操作。

子类必须实现 handle_label()，而不是实现 handle()，每个标签都会调用一次 handle_label()。

LabelCommand.label

描述传递给命令的任意参数的字符串。该字符串用于命令的使用说明文本和错误消息中。默认为 'label'。

LabelCommand.handle_label(label, **options)

对 label 执行命令的操作，label 将是命令行上给定的字符串。

命令异常

exception CommandError(returncode=1)[source]

指示在执行管理命令时出现问题的异常类。

如果此异常在从命令行控制台执行管理命令期间引发，它将被捕获并转换为打印到相应输出流（即 stderr）的漂亮错误消息；因此，引发此异常（并提供错误的合理描述）是指示命令执行中出现问题的首选方法。它接受可选的 returncode 参数来自定义管理命令退出的退出状态，使用 sys.exit()。

如果通过 call_command() 从代码中调用管理命令，则需要在必要时自行捕获异常。

如何使用 Django 的 CSRF 保护
如何编写自定义存储类
返回顶部