Refs #29501 -- Allowed customizing exit status for management commands.

Author: adamchainz

django/core/management/base.py

@@ -26,7 +26,9 @@ class CommandError(Exception):
  error) is the preferred way to indicate that something has gone
  wrong in the execution of a command.
  """
- pass
+ def __init__(self, *args, returncode=1, **kwargs):
+ self.returncode = returncode
+ super().__init__(*args, **kwargs)
 
 
 class SystemCheckError(CommandError):
@@ -335,7 +337,7 @@ def run_from_argv(self, argv):
  self.stderr.write(str(e), lambda x: x)
  else:
  self.stderr.write('%s: %s' % (e.__class__.__name__, e))
- sys.exit(1)
+ sys.exit(e.returncode)
  finally:
  try:
  connections.close_all()

docs/howto/custom-management-commands.txt

@@ -340,16 +340,22 @@ Rather than implementing :meth:`~BaseCommand.handle`, subclasses must implement
 Command exceptions
 ------------------
 
-.. exception:: CommandError
+.. exception:: CommandError(returncode=1)
 
 Exception class indicating a problem while executing a management command.
 
 If this exception is raised during the execution of a management command from a
 command line console, it will be caught and turned into a nicely-printed error
 message to the appropriate output stream (i.e., stderr); as a result, raising
 this exception (with a sensible description of the error) is the preferred way
-to indicate that something has gone wrong in the execution of a command.
+to indicate that something has gone wrong in the execution of a command. It
+accepts the optional ``returncode`` argument to customize the exit status for
+the management command to exit with, using :func:`sys.exit`.
 
 If a management command is called from code through
 :func:`~django.core.management.call_command`, it's up to you to catch the
 exception when needed.
+
+.. versionchanged:: 3.1
+
+ The ``returncode`` argument was added.

docs/releases/3.1.txt

@@ -313,6 +313,10 @@ Management Commands
 * The new :option:`migrate --check` option makes the command exit with a
  non-zero status when unapplied migrations are detected.
 
+* The new ``returncode`` argument for
+ :attr:`~django.core.management.CommandError` allows customizing the exit
+ status for management commands.
+
 Migrations
 ~~~~~~~~~~
 

tests/user_commands/management/commands/dance.py

@@ -15,7 +15,7 @@ def add_arguments(self, parser):
  def handle(self, *args, **options):
  example = options["example"]
  if example == "raise":
- raise CommandError()
+ raise CommandError(returncode=3)
  if options['verbosity'] > 0:
  self.stdout.write("I don't feel like dancing %s." % options["style"])
  self.stdout.write(','.join(options))

tests/user_commands/tests.py

@@ -57,12 +57,14 @@ def test_system_exit(self):
  """ Exception raised in a command should raise CommandError with
  call_command, but SystemExit when run from command line
  """
- with self.assertRaises(CommandError):
+ with self.assertRaises(CommandError) as cm:
  management.call_command('dance', example="raise")
+ self.assertEqual(cm.exception.returncode, 3)
  dance.Command.requires_system_checks = False
  try:
- with captured_stderr() as stderr, self.assertRaises(SystemExit):
+ with captured_stderr() as stderr, self.assertRaises(SystemExit) as cm:
  management.ManagementUtility(['manage.py', 'dance', '--example=raise']).execute()
+ self.assertEqual(cm.exception.code, 3)
  finally:
  dance.Command.requires_system_checks = True
  self.assertIn("CommandError", stderr.getvalue())