Debian Codegraph @

django/core/management/base.py

raw
1 """
2 Base classes for writing management commands (named commands which can
3 be executed through ``django-admin`` or ``manage.py``).
4 """
5
6 import argparse
7 import os
8 import sys
9 from argparse import ArgumentParser, HelpFormatter
10 from functools import partial
11 from io import TextIOBase
12
13 import django
14 from django.core import checks
15 from django.core.exceptions import ImproperlyConfigured
16 from django.core.management.color import color_style, no_style
17 from django.db import DEFAULT_DB_ALIAS, connections
18 from django.utils.version import PY314
19
20 ALL_CHECKS = "__all__"
21
22
23 class CommandError(Exception):
24 """
25 Exception class indicating a problem while executing a management
26 command.
27
28 If this exception is raised during the execution of a management
29 command, it will be caught and turned into a nicely-printed error
30 message to the appropriate output stream (i.e., stderr); as a
31 result, raising this exception (with a sensible description of the
32 error) is the preferred way to indicate that something has gone
33 wrong in the execution of a command.
34 """
35
36 def __init__(self, *args, returncode=1, **kwargs):
37 self.returncode = returncode
38 super().__init__(*args, **kwargs)
39
40
41 class SystemCheckError(CommandError):
42 """
43 The system check framework detected unrecoverable errors.
44 """
45
46 pass
47
48
49 class CommandParser(ArgumentParser):
50 """
51 Customized ArgumentParser class to improve some error messages and prevent
52 SystemExit in several occasions, as SystemExit is unacceptable when a
53 command is called programmatically.
54 """
55
56 def __init__(
57 self, *, missing_args_message=None, called_from_command_line=None, **kwargs
58 ):
59 self.missing_args_message = missing_args_message
60 self.called_from_command_line = called_from_command_line
61 if PY314:
62 if os.environ.get("DJANGO_COLORS") == "nocolor" or "--no-color" in sys.argv:
63 kwargs.setdefault("color", False)
64 super().__init__(**kwargs)
65
66 def parse_args(self, args=None, namespace=None):
67 # Catch missing argument for a better error message
68 if self.missing_args_message and not (
69 args or any(not arg.startswith("-") for arg in args)
70 ):
71 self.error(self.missing_args_message)
72 return super().parse_args(args, namespace)
73
74 def error(self, message):
75 if self.called_from_command_line:
76 super().error(message)
77 else:
78 raise CommandError("Error: %s" % message)
79
80 def add_subparsers(self, **kwargs):
81 parser_class = kwargs.get("parser_class", type(self))
82 if issubclass(parser_class, CommandParser):
83 kwargs["parser_class"] = partial(
84 parser_class,
85 called_from_command_line=self.called_from_command_line,
86 )
87 return super().add_subparsers(**kwargs)
88
89
90 def handle_default_options(options):
91 """
92 Include any default options that all commands should accept here
93 so that ManagementUtility can handle them before searching for
94 user commands.
95 """
96 if options.settings:
97 os.environ["DJANGO_SETTINGS_MODULE"] = options.settings
98 if options.pythonpath:
99 sys.path.insert(0, options.pythonpath)
100
101
102 def no_translations(handle_func):
103 """Decorator that forces a command to run with translations deactivated."""
104
105 def wrapper(*args, **kwargs):
106 from django.utils import translation
107
108 saved_locale = translation.get_language()
109 translation.deactivate_all()
110 try:
111 res = handle_func(*args, **kwargs)
112 finally:
113 if saved_locale is not None:
114 translation.activate(saved_locale)
115 return res
116
117 return wrapper
118
119
120 class DjangoHelpFormatter(HelpFormatter):
121 """
122 Customized formatter so that command-specific arguments appear in the
123 --help output before arguments common to all commands.
124 """
125
126 show_last = {
127 "--version",
128 "--verbosity",
129 "--traceback",
130 "--settings",
131 "--pythonpath",
132 "--no-color",
133 "--force-color",
134 "--skip-checks",
135 }
136
137 def _reordered_actions(self, actions):
138 return sorted(
139 actions, key=lambda a: set(a.option_strings) & self.show_last != set()
140 )
141
142 def add_usage(self, usage, actions, *args, **kwargs):
143 super().add_usage(usage, self._reordered_actions(actions), *args, **kwargs)
144
145 def add_arguments(self, actions):
146 super().add_arguments(self._reordered_actions(actions))
147
148
149 class OutputWrapper:
150 """
151 Wrapper around stdout/stderr
152 """
153
154 @property
155 def style_func(self):
156 return self._style_func
157
158 @style_func.setter
159 def style_func(self, style_func):
160 if style_func and self.isatty():
161 self._style_func = style_func
162 else:
163 self._style_func = lambda x: x
164
165 def __init__(self, out, ending="\n"):
166 self._out = out
167 self.style_func = None
168 self.ending = ending
169
170 def __getattr__(self, name):
171 return getattr(self._out, name)
172
173 def flush(self):
174 if hasattr(self._out, "flush"):
175 self._out.flush()
176
177 def isatty(self):
178 return hasattr(self._out, "isatty") and self._out.isatty()
179
180 def write(self, msg="", style_func=None, ending=None):
181 ending = self.ending if ending is None else ending
182 if ending and not msg.endswith(ending):
183 msg += ending
184 style_func = style_func or self.style_func
185 self._out.write(style_func(msg))
186
187
188 TextIOBase.register(OutputWrapper)
189
190
191 class BaseCommand:
192 """
193 The base class from which all management commands ultimately
194 derive.
195
196 Use this class if you want access to all of the mechanisms which
197 parse the command-line arguments and work out what code to call in
198 response; if you don't need to change any of that behavior,
199 consider using one of the subclasses defined in this file.
200
201 If you are interested in overriding/customizing various aspects of
202 the command-parsing and -execution behavior, the normal flow works
203 as follows:
204
205 1. ``django-admin`` or ``manage.py`` loads the command class
206 and calls its ``run_from_argv()`` method.
207
208 2. The ``run_from_argv()`` method calls ``create_parser()`` to get
209 an ``ArgumentParser`` for the arguments, parses them, performs
210 any environment changes requested by options like
211 ``pythonpath``, and then calls the ``execute()`` method,
212 passing the parsed arguments.
213
214 3. The ``execute()`` method attempts to carry out the command by
215 calling the ``handle()`` method with the parsed arguments; any
216 output produced by ``handle()`` will be printed to standard
217 output and, if the command is intended to produce a block of
218 SQL statements, will be wrapped in ``BEGIN`` and ``COMMIT``.
219
220 4. If ``handle()`` or ``execute()`` raised any exception (e.g.
221 ``CommandError``), ``run_from_argv()`` will instead print an error
222 message to ``stderr``.
223
224 Thus, the ``handle()`` method is typically the starting point for
225 subclasses; many built-in commands and command types either place
226 all of their logic in ``handle()``, or perform some additional
227 parsing work in ``handle()`` and then delegate from it to more
228 specialized methods as needed.
229
230 Several attributes affect behavior at various steps along the way:
231
232 ``help``
233 A short description of the command, which will be printed in
234 help messages.
235
236 ``output_transaction``
237 A boolean indicating whether the command outputs SQL
238 statements; if ``True``, the output will automatically be
239 wrapped with ``BEGIN;`` and ``COMMIT;``. Default value is
240 ``False``.
241
242 ``requires_migrations_checks``
243 A boolean; if ``True``, the command prints a warning if the set of
244 migrations on disk don't match the migrations in the database.
245
246 ``requires_system_checks``
247 A list or tuple of tags, e.g. [Tags.staticfiles, Tags.models]. System
248 checks registered in the chosen tags will be checked for errors prior
249 to executing the command. The value '__all__' can be used to specify
250 that all system checks should be performed. Default value is '__all__'.
251
252 To validate an individual application's models
253 rather than all applications' models, call
254 ``self.check(app_configs)`` from ``handle()``, where ``app_configs``
255 is the list of application's configuration provided by the
256 app registry.
257
258 ``stealth_options``
259 A tuple of any options the command uses which aren't defined by the
260 argument parser.
261 """
262
263 # Metadata about this command.
264 help = ""
265
266 # Configuration shortcuts that alter various logic.
267 _called_from_command_line = False
268 output_transaction = False # Whether to wrap the output in a "BEGIN; COMMIT;"
269 requires_migrations_checks = False
270 requires_system_checks = "__all__"
271 # Arguments, common to all commands, which aren't defined by the argument
272 # parser.
273 base_stealth_options = ("stderr", "stdout")
274 # Command-specific options not defined by the argument parser.
275 stealth_options = ()
276 suppressed_base_arguments = set()
277
278 def __init__(self, stdout=None, stderr=None, no_color=False, force_color=False):
279 self.stdout = OutputWrapper(stdout or sys.stdout)
280 self.stderr = OutputWrapper(stderr or sys.stderr)
281 if no_color and force_color:
282 raise CommandError("'no_color' and 'force_color' can't be used together.")
283 if no_color:
284 self.style = no_style()
285 else:
286 self.style = color_style(force_color)
287 self.stderr.style_func = self.style.ERROR
288 if (
289 not isinstance(self.requires_system_checks, (list, tuple))
290 and self.requires_system_checks != ALL_CHECKS
291 ):
292 raise TypeError("requires_system_checks must be a list or tuple.")
293
294 def get_version(self):
295 """
296 Return the Django version, which should be correct for all built-in
297 Django commands. User-supplied commands can override this method to
298 return their own version.
299 """
300 return django.get_version()
301
302 def create_parser(self, prog_name, subcommand, **kwargs):
303 """
304 Create and return the ``ArgumentParser`` which will be used to
305 parse the arguments to this command.
306 """
307 kwargs.setdefault("formatter_class", DjangoHelpFormatter)
308 parser = CommandParser(
309 prog="%s %s" % (os.path.basename(prog_name), subcommand),
310 description=self.help or None,
311 missing_args_message=getattr(self, "missing_args_message", None),
312 called_from_command_line=getattr(self, "_called_from_command_line", None),
313 **kwargs,
314 )
315 self.add_base_argument(
316 parser,
317 "--version",
318 action="version",
319 version=self.get_version(),
320 help="Show program's version number and exit.",
321 )
322 self.add_base_argument(
323 parser,
324 "-v",
325 "--verbosity",
326 default=1,
327 type=int,
328 choices=[0, 1, 2, 3],
329 help=(
330 "Verbosity level; 0=minimal output, 1=normal output, 2=verbose output, "
331 "3=very verbose output"
332 ),
333 )
334 self.add_base_argument(
335 parser,
336 "--settings",
337 help=(
338 "The Python path to a settings module, e.g. "
339 '"myproject.settings.main". If this isn\'t provided, the '
340 "DJANGO_SETTINGS_MODULE environment variable will be used."
341 ),
342 )
343 self.add_base_argument(
344 parser,
345 "--pythonpath",
346 help=(
347 "A directory to add to the Python path, e.g. "
348 '"/home/djangoprojects/myproject".'
349 ),
350 )
351 self.add_base_argument(
352 parser,
353 "--traceback",
354 action="store_true",
355 help="Display a full stack trace on CommandError exceptions.",
356 )
357 self.add_base_argument(
358 parser,
359 "--no-color",
360 action="store_true",
361 help="Don't colorize the command output.",
362 )
363 self.add_base_argument(
364 parser,
365 "--force-color",
366 action="store_true",
367 help="Force colorization of the command output.",
368 )
369 if self.requires_system_checks:
370 parser.add_argument(
371 "--skip-checks",
372 action="store_true",
373 help="Skip system checks.",
374 )
375 self.add_arguments(parser)
376 return parser
377
378 def add_arguments(self, parser):
379 """
380 Entry point for subclassed commands to add custom arguments.
381 """
382 pass
383
384 def add_base_argument(self, parser, *args, **kwargs):
385 """
386 Call the parser's add_argument() method, suppressing the help text
387 according to BaseCommand.suppressed_base_arguments.
388 """
389 for arg in args:
390 if arg in self.suppressed_base_arguments:
391 kwargs["help"] = argparse.SUPPRESS
392 break
393 parser.add_argument(*args, **kwargs)
394
395 def print_help(self, prog_name, subcommand):
396 """
397 Print the help message for this command, derived from
398 ``self.usage()``.
399 """
400 parser = self.create_parser(prog_name, subcommand)
401 parser.print_help()
402
403 def run_from_argv(self, argv):
404 """
405 Set up any environment changes requested (e.g., Python path
406 and Django settings), then run this command. If the
407 command raises a ``CommandError``, intercept it and print it sensibly
408 to stderr. If the ``--traceback`` option is present or the raised
409 ``Exception`` is not ``CommandError``, raise it.
410 """
411 self._called_from_command_line = True
412 parser = self.create_parser(argv[0], argv[1])
413
414 options = parser.parse_args(argv[2:])
415 cmd_options = vars(options)
416 # Move positional args out of options to mimic legacy optparse
417 args = cmd_options.pop("args", ())
418 handle_default_options(options)
419 try:
420 self.execute(*args, **cmd_options)
421 except CommandError as e:
422 if options.traceback:
423 raise
424
425 # SystemCheckError takes care of its own formatting.
426 if isinstance(e, SystemCheckError):
427 self.stderr.write(str(e), lambda x: x)
428 else:
429 self.stderr.write("%s: %s" % (e.__class__.__name__, e))
430 sys.exit(e.returncode)
431 finally:
432 try:
433 connections.close_all()
434 except ImproperlyConfigured:
435 # Ignore if connections aren't setup at this point (e.g. no
436 # configured settings).
437 pass
438
439 def execute(self, *args, **options):
440 """
441 Try to execute this command, performing system checks if needed (as
442 controlled by the ``requires_system_checks`` attribute, except if
443 force-skipped).
444 """
445 if options["force_color"] and options["no_color"]:
446 raise CommandError(
447 "The --no-color and --force-color options can't be used together."
448 )
449 if options["force_color"]:
450 self.style = color_style(force_color=True)
451 elif options["no_color"]:
452 self.style = no_style()
453 self.stderr.style_func = None
454 if options.get("stdout"):
455 self.stdout = OutputWrapper(options["stdout"])
456 if options.get("stderr"):
457 self.stderr = OutputWrapper(options["stderr"])
458
459 if self.requires_system_checks and not options["skip_checks"]:
460 check_kwargs = self.get_check_kwargs(options)
461 self.check(**check_kwargs)
462 if self.requires_migrations_checks:
463 self.check_migrations()
464 output = self.handle(*args, **options)
465 if output:
466 if self.output_transaction:
467 connection = connections[options.get("database", DEFAULT_DB_ALIAS)]
468 output = "%s\n%s\n%s" % (
469 self.style.SQL_KEYWORD(connection.ops.start_transaction_sql()),
470 output,
471 self.style.SQL_KEYWORD(connection.ops.end_transaction_sql()),
472 )
473 self.stdout.write(output)
474 return output
475
476 def get_check_kwargs(self, options):
477 if self.requires_system_checks == ALL_CHECKS:
478 return {}
479 return {"tags": self.requires_system_checks}
480
481 def check(
482 self,
483 app_configs=None,
484 tags=None,
485 display_num_errors=False,
486 include_deployment_checks=False,
487 fail_level=checks.ERROR,
488 databases=None,
489 ):
490 """
491 Use the system check framework to validate entire Django project.
492 Raise CommandError for any serious message (error or critical errors).
493 If there are only light messages (like warnings), print them to stderr
494 and don't raise an exception.
495 """
496 all_issues = checks.run_checks(
497 app_configs=app_configs,
498 tags=tags,
499 include_deployment_checks=include_deployment_checks,
500 databases=databases,
501 )
502
503 header, body, footer = "", "", ""
504 visible_issue_count = 0 # excludes silenced warnings
505
506 if all_issues:
507 debugs = [
508 e for e in all_issues if e.level < checks.INFO and not e.is_silenced()
509 ]
510 infos = [
511 e
512 for e in all_issues
513 if checks.INFO <= e.level < checks.WARNING and not e.is_silenced()
514 ]
515 warnings = [
516 e
517 for e in all_issues
518 if checks.WARNING <= e.level < checks.ERROR and not e.is_silenced()
519 ]
520 errors = [
521 e
522 for e in all_issues
523 if checks.ERROR <= e.level < checks.CRITICAL and not e.is_silenced()
524 ]
525 criticals = [
526 e
527 for e in all_issues
528 if checks.CRITICAL <= e.level and not e.is_silenced()
529 ]
530 sorted_issues = [
531 (criticals, "CRITICALS"),
532 (errors, "ERRORS"),
533 (warnings, "WARNINGS"),
534 (infos, "INFOS"),
535 (debugs, "DEBUGS"),
536 ]
537
538 for issues, group_name in sorted_issues:
539 if issues:
540 visible_issue_count += len(issues)
541 formatted = (
542 (
543 self.style.ERROR(str(e))
544 if e.is_serious()
545 else self.style.WARNING(str(e))
546 )
547 for e in issues
548 )
549 formatted = "\n".join(sorted(formatted))
550 body += "\n%s:\n%s\n" % (group_name, formatted)
551
552 if visible_issue_count:
553 header = "System check identified some issues:\n"
554
555 if display_num_errors:
556 if visible_issue_count:
557 footer += "\n"
558 footer += "System check identified %s (%s silenced)." % (
559 (
560 "no issues"
561 if visible_issue_count == 0
562 else (
563 "1 issue"
564 if visible_issue_count == 1
565 else "%s issues" % visible_issue_count
566 )
567 ),
568 len(all_issues) - visible_issue_count,
569 )
570
571 if any(e.is_serious(fail_level) and not e.is_silenced() for e in all_issues):
572 msg = self.style.ERROR("SystemCheckError: %s" % header) + body + footer
573 raise SystemCheckError(msg)
574 else:
575 msg = header + body + footer
576
577 if msg:
578 if visible_issue_count:
579 self.stderr.write(msg, lambda x: x)
580 else:
581 self.stdout.write(msg)
582
583 def check_migrations(self):
584 """
585 Print a warning if the set of migrations on disk don't match the
586 migrations in the database.
587 """
588 from django.db.migrations.executor import MigrationExecutor
589
590 try:
591 executor = MigrationExecutor(connections[DEFAULT_DB_ALIAS])
592 except ImproperlyConfigured:
593 # No databases are configured (or the dummy one)
594 return
595
596 plan = executor.migration_plan(executor.loader.graph.leaf_nodes())
597 if plan:
598 apps_waiting_migration = sorted(
599 {migration.app_label for migration, backwards in plan}
600 )
601 self.stdout.write(
602 self.style.NOTICE(
603 "\nYou have %(unapplied_migration_count)s unapplied migration(s). "
604 "Your project may not work properly until you apply the "
605 "migrations for app(s): %(apps_waiting_migration)s."
606 % {
607 "unapplied_migration_count": len(plan),
608 "apps_waiting_migration": ", ".join(apps_waiting_migration),
609 }
610 )
611 )
612 self.stdout.write(
613 self.style.NOTICE("Run 'python manage.py migrate' to apply them.")
614 )
615
616 def handle(self, *args, **options):
617 """
618 The actual logic of the command. Subclasses must implement
619 this method.
620 """
621 raise NotImplementedError(
622 "subclasses of BaseCommand must provide a handle() method"
623 )
624
625
626 class AppCommand(BaseCommand):
627 """
628 A management command which takes one or more installed application labels
629 as arguments, and does something with each of them.
630
631 Rather than implementing ``handle()``, subclasses must implement
632 ``handle_app_config()``, which will be called once for each application.
633 """
634
635 missing_args_message = "Enter at least one application label."
636
637 def add_arguments(self, parser):
638 parser.add_argument(
639 "args",
640 metavar="app_label",
641 nargs="+",
642 help="One or more application label.",
643 )
644
645 def handle(self, *app_labels, **options):
646 from django.apps import apps
647
648 try:
649 app_configs = [apps.get_app_config(app_label) for app_label in app_labels]
650 except (LookupError, ImportError) as e:
651 raise CommandError(
652 "%s. Are you sure your INSTALLED_APPS setting is correct?" % e
653 )
654 output = []
655 for app_config in app_configs:
656 app_output = self.handle_app_config(app_config, **options)
657 if app_output:
658 output.append(app_output)
659 return "\n".join(output)
660
661 def handle_app_config(self, app_config, **options):
662 """
663 Perform the command's actions for app_config, an AppConfig instance
664 corresponding to an application label given on the command line.
665 """
666 raise NotImplementedError(
667 "Subclasses of AppCommand must provide a handle_app_config() method."
668 )
669
670
671 class LabelCommand(BaseCommand):
672 """
673 A management command which takes one or more arbitrary arguments
674 (labels) on the command line, and does something with each of
675 them.
676
677 Rather than implementing ``handle()``, subclasses must implement
678 ``handle_label()``, which will be called once for each label.
679
680 If the arguments should be names of installed applications, use
681 ``AppCommand`` instead.
682 """
683
684 label = "label"
685 missing_args_message = "Enter at least one %s."
686
687 def __init__(self, *args, **kwargs):
688 super().__init__(*args, **kwargs)
689
690 if self.missing_args_message == LabelCommand.missing_args_message:
691 self.missing_args_message = self.missing_args_message % self.label
692
693 def add_arguments(self, parser):
694 parser.add_argument("args", metavar=self.label, nargs="+")
695
696 def handle(self, *labels, **options):
697 output = []
698 for label in labels:
699 label_output = self.handle_label(label, **options)
700 if label_output:
701 output.append(label_output)
702 return "\n".join(output)
703
704 def handle_label(self, label, **options):
705 """
706 Perform the command's actions for ``label``, which will be the
707 string as given on the command line.
708 """
709 raise NotImplementedError(
710 "subclasses of LabelCommand must provide a handle_label() method"
711 )