Applications can register their own actions with manage.py. For example,\nyou might want to add a manage.py action for a Django app that you’re\ndistributing. In this document, we will be building a custom closepoll\ncommand for the polls application from the\ntutorial.
To do this, just add a management/commands directory to the application.\nDjango will register a manage.py command for each Python module in that\ndirectory whose name doesn’t begin with an underscore. For example:
polls/\n __init__.py\n models.py\n management/\n __init__.py\n commands/\n __init__.py\n _private.py\n closepoll.py\n tests.py\n views.py\nOn Python 2, be sure to include __init__.py files in both the\nmanagement and management/commands directories as done above or your\ncommand will not be detected.
In this example, the closepoll command will be made available to any project\nthat includes the polls application in INSTALLED_APPS.
The _private.py module will not be available as a management command.
The closepoll.py module has only one requirement – it must define a class\nCommand that extends BaseCommand or one of its\nsubclasses.
To implement the command, edit polls/management/commands/closepoll.py to\nlook like this:
from django.core.management.base import BaseCommand, CommandError\nfrom polls.models import Poll\n\nclass Command(BaseCommand):\n help = 'Closes the specified poll for voting'\n\n def add_arguments(self, parser):\n parser.add_argument('poll_id', nargs='+', type=int)\n\n def handle(self, *args, **options):\n for poll_id in options['poll_id']:\n try:\n poll = Poll.objects.get(pk=poll_id)\n except Poll.DoesNotExist:\n raise CommandError('Poll "%s" does not exist' % poll_id)\n\n poll.opened = False\n poll.save()\n\n self.stdout.write('Successfully closed poll "%s"' % poll_id)\nThe new custom command can be called using python manage.py closepoll\n<poll_id>.
The handle() method takes one or more poll_ids and sets poll.opened\nto False for each one. If the user referenced any nonexistent polls, a\nCommandError is raised. The poll.opened attribute does not exist\nin the tutorial and was added to\npolls.models.Poll for this example.
The same closepoll could be easily modified to delete a given poll instead\nof closing it by accepting additional command line options. These custom\noptions can be added in the add_arguments() method like this:
class Command(BaseCommand):\n def add_arguments(self, parser):\n # Positional arguments\n parser.add_argument('poll_id', nargs='+', type=int)\n\n # Named (optional) arguments\n parser.add_argument('--delete',\n action='store_true',\n dest='delete',\n default=False,\n help='Delete poll instead of closing it')\n\n def handle(self, *args, **options):\n # ...\n if options['delete']:\n poll.delete()\n # ...\nThe option (delete in our example) is available in the options dict\nparameter of the handle method. See the argparse Python documentation\nfor more about add_argument usage.
In addition to being able to add custom command line options, all\nmanagement commands can accept some\ndefault options such as --verbosity and --traceback.
By default, the BaseCommand.execute() method deactivates translations\nbecause some commands shipped with Django perform several tasks (for example,\nuser-facing content rendering and database population) that require a\nproject-neutral string language.
If, for some reason, your custom management command needs to use a fixed locale,\nyou should manually activate and deactivate it in your\nhandle() method using the functions provided by the I18N\nsupport code:
from django.core.management.base import BaseCommand, CommandError\nfrom django.utils import translation\n\nclass Command(BaseCommand):\n ...\n can_import_settings = True\n\n def handle(self, *args, **options):\n\n # Activate a fixed locale, e.g. Russian\n translation.activate('ru')\n\n # Or you can activate the LANGUAGE_CODE # chosen in the settings:\n from django.conf import settings\n translation.activate(settings.LANGUAGE_CODE)\n\n # Your command logic here\n ...\n\n translation.deactivate()\nAnother need might be that your command simply should use the locale set in\nsettings and Django should be kept from deactivating it. You can achieve\nit by using the BaseCommand.leave_locale_alone option.
When working on the scenarios described above though, take into account that\nsystem management commands typically have to be very careful about running in\nnon-uniform locales, so you might need to:
\nMake sure the USE_I18N setting is always True when running\nthe command (this is a good example of the potential problems stemming\nfrom a dynamic runtime environment that Django commands avoid offhand by\ndeactivating translations).
Review the code of your command and the code it calls for behavioral\ndifferences when locales are changed and evaluate its impact on\npredictable behavior of your command.
Information on how to test custom management commands can be found in the\ntesting docs.
\nThe base class from which all management commands ultimately derive.
\nUse this class if you want access to all of the mechanisms which\nparse the command-line arguments and work out what code to call in\nresponse; if you don’t need to change any of that behavior,\nconsider using one of its subclasses.
\nSubclassing the BaseCommand class requires that you implement the\nhandle() method.
All attributes can be set in your derived class and can be used in\nBaseCommand’s subclasses.
A string listing the arguments accepted by the command,\nsuitable for use in help messages; e.g., a command which takes\na list of application names might set this to ‘<app_label\napp_label …>’.
\n\nA boolean indicating whether the command needs to be able to\nimport Django settings; if True, execute() will verify\nthat this is possible before proceeding. Default value is\nTrue.
A short description of the command, which will be printed in the\nhelp message when the user runs the command\npython manage.py help <command>.
If your command defines mandatory positional arguments, you can customize\nthe message error returned in the case of missing arguments. The default is\noutput by argparse (“too few arguments”).
This is the list of optparse options which will be fed\ninto the command’s OptionParser for parsing arguments.
A boolean indicating whether the command outputs SQL statements; if\nTrue, the output will automatically be wrapped with BEGIN; and\nCOMMIT;. Default value is False.
A boolean; if True, the entire Django project will be checked for\npotential problems prior to executing the command. If\nrequires_system_checks is missing, the value of\nrequires_model_validation is used. If the latter flag is missing\nas well, the default value (True) is used. Defining both\nrequires_system_checks and requires_model_validation will result\nin an error.
A boolean; if True, validation of installed models will be performed\nprior to executing the command. Default value is True. To validate an\nindividual application’s models rather than all applications’ models, call\nvalidate() from handle().
A boolean indicating whether the locale set in settings should be preserved\nduring the execution of the command instead of being forcibly set to ‘en-us’.
\nDefault value is False.
Make sure you know what you are doing if you decide to change the value of\nthis option in your custom command if it creates database content that\nis locale-sensitive and such content shouldn’t contain any translations\n(like it happens e.g. with django.contrib.auth permissions) as making the\nlocale differ from the de facto default ‘en-us’ might cause unintended\neffects. Seethe Management commands and locales section above for\nfurther details.
\nThis option can’t be False when the\ncan_import_settings option is set to False too\nbecause attempting to set the locale needs access to settings. This\ncondition will generate a CommandError.
An instance attribute that helps create colored output when writing to\nstdout or stderr. For example:
self.stdout.write(self.style.NOTICE('...'))\nSee Syntax coloring to learn how to modify the color palette and to\nsee the available styles (use uppercased versions of the “roles” described\nin that section).
\nIf you pass the --no-color option when running your\ncommand, all self.style() calls will return the original string\nuncolored.
BaseCommand has a few methods that can be overridden but only\nthe handle() method must be implemented.
Entry point to add parser arguments to handle command line arguments passed\nto the command. Custom commands should override this method to add both\npositional and optional arguments accepted by the command. Calling\nsuper() is not needed when directly subclassing BaseCommand.
Returns the Django version, which should be correct for all built-in Django\ncommands. User-supplied commands can override this method to return their\nown version.
\nTries to execute this command, performing system checks if needed (as\ncontrolled by the requires_system_checks attribute). If the command\nraises a CommandError, it’s intercepted and printed to stderr.
The actual logic of the command. Subclasses must implement this method.
\nIt may return a Unicode string which will be printed to stdout (wrapped\nby BEGIN; and COMMIT; if output_transaction is True).
Uses the system check framework to inspect the entire Django project for\npotential problems. Serious problems are raised as a CommandError;\nwarnings are output to stderr; minor notifications are output to stdout.
If app_configs and tags are both None, all system checks are\nperformed. tags can be a list of check tags, like compatibility or\nmodels.
If app is None, then all installed apps are checked for errors.
A management command which takes one or more installed application labels as\narguments, and does something with each of them.
\nRather than implementing handle(), subclasses must\nimplement handle_app_config(), which will be called once for\neach application.
Perform the command’s actions for app_config, which will be an\nAppConfig instance corresponding to an application\nlabel given on the command line.
A management command which takes one or more arbitrary arguments (labels) on\nthe command line, and does something with each of them.
\nRather than implementing handle(), subclasses must implement\nhandle_label(), which will be called once for each label.
Perform the command’s actions for label, which will be the string as\ngiven on the command line.
A command which takes no arguments on the command line.
\nRather than implementing handle(), subclasses must implement\nhandle_noargs(); handle() itself is\noverridden to ensure no arguments are passed to the command.
Perform this command’s actions
\nException class indicating a problem while executing a management command.
\nIf this exception is raised during the execution of a management command from a\ncommand line console, it will be caught and turned into a nicely-printed error\nmessage to the appropriate output stream (i.e., stderr); as a result, raising\nthis exception (with a sensible description of the error) is the preferred way\nto indicate that something has gone wrong in the execution of a command.
\nIf a management command is called from code through call_command, it’s up to you to catch the exception when needed.
\n