"""

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

import django

from django.core.exceptions import ImproperlyConfigured

from django.core.management.color import color_style

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.

    """

    if options.settings:

        os.environ['DJANGO_SETTINGS_MODULE'] = options.settings

    if options.pythonpath:

        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 ``CommandError``, ``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',

            help='A directory to add to the Python path, e.g. "/home/djangoprojects/myproject".'),

        make_option('--traceback', action='store_true',

            help='Print traceback on exception'),

    )

    help = ''

    args = ''

    # Configuration shortcuts that alter various logic.

    can_import_settings = True

    requires_model_validation = True

    output_transaction = False # Whether to wrap the output in a "BEGIN; COMMIT;"

    def __init__(self):

        self.style = color_style()

    def get_version(self):

        """

        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)

        else:

            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:

            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.exit(1)

        try:

            if self.requires_model_validation:

                self.validate()

            output = self.handle(*args, **options)

            if output:

                if self.output_transaction:

                    # This needs to be imported here, because it relies on settings.

                    from django.db import connection

                    if connection.ops.start_transaction_sql():

                        print self.style.SQL_KEYWORD(connection.ops.start_transaction_sql())

                print output

                if self.output_transaction:

                    print self.style.SQL_KEYWORD("COMMIT;")

        except CommandError, e:

            sys.exit(1)

    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:

            from cStringIO import StringIO

        except ImportError:

            from StringIO import StringIO

        s = StringIO()

        num_errors = get_validation_errors(s, app)

        if num_errors:

            s.seek(0)

            error_text = s.read()

            raise CommandError("One or more models did not validate:\n%s" % error_text)

        if display_num_errors:

            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):

        from django.db import models

        if not app_labels:

            raise CommandError('Enter at least one appname.')

        try:

            app_list = [models.get_app(app_label) for app_label in app_labels]

        except (ImproperlyConfigured, ImportError), e:

            raise CommandError("%s. Are you sure your INSTALLED_APPS setting is correct?" % e)

        output = []

        for app in app_list:

            app_output = self.handle_app(app, **options)

            if app_output:

                output.append(app_output)

        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'

    def handle(self, *labels, **options):

        if not labels:

            raise CommandError('Enter at least one %s.' % self.label)

        output = []

        for label in labels:

            label_output = self.handle_label(label, **options)

            if label_output:

                output.append(label_output)

        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):

        if args:

            raise CommandError("Command doesn't accept any arguments")

        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'.

    # name -- The name of the application or project.

    # directory -- The directory to which the layout template should be copied.

    # other_name -- When copying an application layout, this should be the name

    #               of the project.

    import re

    import shutil

    other = {'project': 'app', 'app': 'project'}[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)

    except OSError, e:

        raise CommandError(e)

    # Determine where the app or project templates are. Use

    # django.__path__[0] because we don't know into which directory

    # django has been installed.

    template_dir = os.path.join(django.__path__[0], 'conf', '%s_template' % app_or_project)

    for d, subdirs, files in os.walk(template_dir):

        relative_dir = d[len(template_dir)+1:].replace('%s_name' % app_or_project, name)

        if relative_dir:

            os.mkdir(os.path.join(top_dir, relative_dir))

        for i, subdir in enumerate(subdirs):

            if subdir.startswith('.'):

                del subdirs[i]

        for f in files:

            if not f.endswith('.py'):

                # Ignore .pyc, .pyo, .py.class etc, as they cause various

                # breakages.

                continue

            path_old = os.path.join(d, f)

            path_new = os.path.join(top_dir, relative_dir, f.replace('%s_name' % app_or_project, name))

            fp_old = open(path_old, 'r')

            fp_new = open(path_new, 'w')

            fp_new.write(fp_old.read().replace('{{ %s_name }}' % app_or_project, name).replace('{{ %s_name }}' % other, other_name))

            fp_old.close()

            fp_new.close()

            try:

                shutil.copymode(path_old, path_new)

                _make_writeable(path_new)

            except OSError:

                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):

    """

    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()

        return

    if not os.access(filename, os.W_OK):

        st = os.stat(filename)

        new_permissions = stat.S_IMODE(st.st_mode) | stat.S_IWUSR

        os.chmod(filename, new_permissions)