diff -r 6641e941ef1e -r ff1a9aa48cfd app/django/core/management/base.py --- a/app/django/core/management/base.py Tue Oct 14 12:36:55 2008 +0000 +++ b/app/django/core/management/base.py Tue Oct 14 16:00:59 2008 +0000 @@ -1,3 +1,9 @@ +""" +Base classes for writing management commands (named commands which can +be executed through ``django-admin.py`` or ``manage.py``). + +""" + import os import sys from optparse import make_option, OptionParser @@ -6,14 +12,32 @@ from django.core.exceptions import ImproperlyConfigured from django.core.management.color import color_style +try: + set +except NameError: + from sets import Set as set # For Python 2.3 + class CommandError(Exception): + """ + Exception class indicating a problem while executing a management + command. + + If this exception is raised during the execution of a management + command, 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. + + """ pass def handle_default_options(options): """ - Include any default options that all commands should accept - here so that ManagementUtility can handle them before searching - for user commands. + Include any default options that all commands should accept here + so that ManagementUtility can handle them before searching for + user commands. + """ if options.settings: os.environ['DJANGO_SETTINGS_MODULE'] = options.settings @@ -21,8 +45,85 @@ sys.path.insert(0, options.pythonpath) class BaseCommand(object): + """ + The base class from which all management commands ultimately + derive. + + Use this class if you want access to all of the mechanisms which + parse the command-line arguments and work out what code to call in + response; if you don't need to change any of that behavior, + consider using one of the subclasses defined in this file. + + If you are interested in overriding/customizing various aspects of + the command-parsing and -execution behavior, the normal flow works + as follows: + + 1. ``django-admin.py`` or ``manage.py`` loads the command class + and calls its ``run_from_argv()`` method. + + 2. The ``run_from_argv()`` method calls ``create_parser()`` to get + an ``OptionParser`` for the arguments, parses them, performs + any environment changes requested by options like + ``pythonpath``, and then calls the ``execute()`` method, + passing the parsed arguments. + + 3. The ``execute()`` method attempts to carry out the command by + calling the ``handle()`` method with the parsed arguments; any + output produced by ``handle()`` will be printed to standard + output and, if the command is intended to produce a block of + SQL statements, will be wrapped in ``BEGIN`` and ``COMMIT``. + + 4. If ``handle()`` raised a ``ComandError``, ``execute()`` will + instead print an error message to ``stderr``. + + Thus, the ``handle()`` method is typically the starting point for + subclasses; many built-in commands and command types either place + all of their logic in ``handle()``, or perform some additional + parsing work in ``handle()`` and then delegate from it to more + specialized methods as needed. + + Several attributes affect behavior at various steps along the way: + + ``args`` + A string listing the arguments accepted by the command, + suitable for use in help messages; e.g., a command which takes + a list of application names might set this to ''. + + ``can_import_settings`` + A boolean indicating whether the command needs to be able to + import Django settings; if ``True``, ``execute()`` will verify + that this is possible before proceeding. Default value is + ``True``. + + ``help`` + A short description of the command, which will be printed in + help messages. + + ``option_list`` + This is the list of ``optparse`` options which will be fed + into the command's ``OptionParser`` for parsing arguments. + + ``output_transaction`` + A boolean indicating whether the command outputs SQL + statements; if ``True``, the output will automatically be + wrapped with ``BEGIN;`` and ``COMMIT;``. Default value is + ``False``. + + ``requires_model_validation`` + A boolean; if ``True``, validation of installed models will be + performed prior to executing the command. Default value is + ``True``. To validate an individual application's models + rather than all applications' models, call + ``self.validate(app)`` from ``handle()``, where ``app`` is the + application's Python module. + + """ # Metadata about this command. option_list = ( + make_option('-v', '--verbosity', action='store', dest='verbosity', default='1', + type='choice', choices=['0', '1', '2'], + help='Verbosity level; 0=minimal output, 1=normal output, 2=all output'), make_option('--settings', help='The Python path to a settings module, e.g. "myproject.settings.main". If this isn\'t provided, the DJANGO_SETTINGS_MODULE environment variable will be used.'), make_option('--pythonpath', @@ -43,12 +144,19 @@ def get_version(self): """ - Returns the Django version, which should be correct for all built-in - Django commands. User-supplied commands should override this method. + Return the Django version, which should be correct for all + built-in Django commands. User-supplied commands should + override this method. + """ return django.get_version() def usage(self, subcommand): + """ + Return a brief description of how to use this command, by + default from the attribute ``self.help``. + + """ usage = '%%prog %s [options] %s' % (subcommand, self.args) if self.help: return '%s\n\n%s' % (usage, self.help) @@ -56,30 +164,58 @@ return usage def create_parser(self, prog_name, subcommand): + """ + Create and return the ``OptionParser`` which will be used to + parse the arguments to this command. + + """ return OptionParser(prog=prog_name, usage=self.usage(subcommand), version=self.get_version(), option_list=self.option_list) def print_help(self, prog_name, subcommand): + """ + Print the help message for this command, derived from + ``self.usage()``. + + """ parser = self.create_parser(prog_name, subcommand) parser.print_help() def run_from_argv(self, argv): + """ + Set up any environment changes requested (e.g., Python path + and Django settings), then run this command. + + """ parser = self.create_parser(argv[0], argv[1]) options, args = parser.parse_args(argv[2:]) handle_default_options(options) self.execute(*args, **options.__dict__) def execute(self, *args, **options): + """ + Try to execute this command, performing model validation if + needed (as controlled by the attribute + ``self.requires_model_validation``). If the command raises a + ``CommandError``, intercept it and print it sensibly to + stderr. + + """ # Switch to English, because django-admin.py creates database content # like permissions, and those shouldn't contain any translations. # But only do this if we can assume we have a working settings file, # because django.utils.translation requires settings. if self.can_import_settings: - from django.utils import translation - translation.activate('en-us') - + try: + from django.utils import translation + translation.activate('en-us') + except ImportError, e: + # If settings should be available, but aren't, + # raise the error and quit. + sys.stderr.write(self.style.ERROR(str('Error: %s\n' % e))) + sys.exit(1) try: if self.requires_model_validation: self.validate() @@ -100,8 +236,9 @@ def validate(self, app=None, display_num_errors=False): """ Validates the given app, raising CommandError for any errors. - + If app is None, then this will validate all installed apps. + """ from django.core.management.validation import get_validation_errors try: @@ -118,9 +255,22 @@ print "%s error%s found" % (num_errors, num_errors != 1 and 's' or '') def handle(self, *args, **options): + """ + The actual logic of the command. Subclasses must implement + this method. + + """ raise NotImplementedError() class AppCommand(BaseCommand): + """ + A management command which takes one or more installed application + names as arguments, and does something with each of them. + + Rather than implementing ``handle()``, subclasses must implement + ``handle_app()``, which will be called once for each application. + + """ args = '' def handle(self, *app_labels, **options): @@ -139,9 +289,27 @@ return '\n'.join(output) def handle_app(self, app, **options): + """ + Perform the command's actions for ``app``, which will be the + Python module corresponding to an application name given on + the command line. + + """ raise NotImplementedError() class LabelCommand(BaseCommand): + """ + A management command which takes one or more arbitrary arguments + (labels) on the command line, and does something with each of + them. + + Rather than implementing ``handle()``, subclasses must implement + ``handle_label()``, which will be called once for each label. + + If the arguments should be names of installed applications, use + ``AppCommand`` instead. + + """ args = '