--- 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 '<appname
+ appname ...>'.
+
+ ``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 = '<appname appname ...>'
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 = '<label label ...>'
label = 'label'
@@ -157,9 +325,24 @@
return '\n'.join(output)
def handle_label(self, label, **options):
+ """
+ Perform the command's actions for ``label``, which will be the
+ string as given on the command line.
+
+ """
raise NotImplementedError()
class NoArgsCommand(BaseCommand):
+ """
+ A command which takes no arguments on the command line.
+
+ Rather than implementing ``handle()``, subclasses must implement
+ ``handle_noargs()``; ``handle()`` itself is overridden to ensure
+ no arguments are passed to the command.
+
+ Attempting to pass arguments will raise ``CommandError``.
+
+ """
args = ''
def handle(self, *args, **options):
@@ -168,12 +351,17 @@
return self.handle_noargs(**options)
def handle_noargs(self, **options):
+ """
+ Perform this command's actions.
+
+ """
raise NotImplementedError()
def copy_helper(style, app_or_project, name, directory, other_name=''):
"""
Copies either a Django application layout template or a Django project
layout template into the specified directory.
+
"""
# style -- A color style object (see django.core.management.color).
# app_or_project -- The string 'app' or 'project'.
@@ -184,8 +372,13 @@
import re
import shutil
other = {'project': 'app', 'app': 'project'}[app_or_project]
- if not re.search(r'^\w+$', name): # If it's not a valid directory name.
- raise CommandError("%r is not a valid %s name. Please use only numbers, letters and underscores." % (name, app_or_project))
+ if not re.search(r'^[_a-zA-Z]\w*$', name): # If it's not a valid directory name.
+ # Provide a smart error message, depending on the error.
+ if not re.search(r'^[_a-zA-Z]', name):
+ message = 'make sure the name begins with a letter or underscore'
+ else:
+ message = 'use only numbers, letters and underscores'
+ raise CommandError("%r is not a valid %s name. Please %s." % (name, app_or_project, message))
top_dir = os.path.join(directory, name)
try:
os.mkdir(top_dir)
@@ -221,7 +414,11 @@
sys.stderr.write(style.NOTICE("Notice: Couldn't set permission bits on %s. You're probably using an uncommon filesystem setup. No problem.\n" % path_new))
def _make_writeable(filename):
- "Makes sure that the file is writeable. Useful if our source is read-only."
+ """
+ Make sure that the file is writeable. Useful if our source is
+ read-only.
+
+ """
import stat
if sys.platform.startswith('java'):
# On Jython there is no os.access()