Better documentation, removed runfcgi, added createcachetable, merge with Michael's changes

library/django-manage

@@ -24,54 +24,55 @@ DOCUMENTATION = '''
 module: django-manage
 short_description: Manages a Django application.
 description:
-     - Manages a Django application.
+     - Manages a Django application using the I(manage.py) application frontend to I(django-admin). With the I(virtualenv) parameter, all management commands will be executed by the given I(virtualenv) installation.
 version_added: "1.1"
 options:
   command:
     choices: [ 'cleanup', 'flush', 'loaddata', 'runfcgi', 'syncdb', 'test', 'validate' ]
     description:
-      - The name of the Django management command to run. 
+      - The name of the Django management command to run. Allowed commands are cleanup, createcachetable, flush, loaddata, syncdb, test, validate.
     required: true
   app_path:
     description:
-      - The path to the root of the Django application
+      - The path to the root of the Django application where B(manage.py) lives.
     required: true
   settings:
     description:
-      - The Python path to a settings module.
+      - The Python path to the application's settings module, such as 'myapp.settings'.
     required: false
   pythonpath:
     description:
-      - A directory to add to the Python path
+      - A directory to add to the Python path. Typically used to include the settings module if it is located external to the application directory.
     required: false
   virtualenv:
     description:
-      - An optional path to a I(virtualenv) directory to use while running the manage application
+      - An optional path to a I(virtualenv) installation to use while running the manage application.
     required: false
   apps:
     description:
-      - A list of space-delimited apps to target, used for some commands
+      - A list of space-delimited apps to target. Used by the 'test' command.
     required: false
-  database:
+  cache_table:
     description:
-      - The database to target, used for some commands
+      - The name of the table used for database-backed caching. Used by the 'createcachetable' command.
     required: false
-  extra_args:
+  database:
     description:
-      - Extra arguments to append to the command string; used only for runfcgi
+      - The database to target. Used by the 'createcachetable', 'flush', 'loaddata', and 'syncdb' commands.
     required: false
   failfast:
     description:
-      - Fail the command immediately if a test fails.
+      - Fail the command immediately if a test fails. Used by the 'test' command.
     required: false
   fixtures:
     description:
-      - A space-delimited list of fixture file names to load in the database.
+      - A space-delimited list of fixture file names to load in the database. B(Required) by the 'loaddata' command.
     required: false
-requirements: [ "virtualenv", "django" ]
 notes:
-   - Please note that U(http://www.virtualenv.org/, virtualenv) must be installed on the remote host if the virtualenv parameter is specified.
-   - Please note that I(flup) must be installed on the remote host if using the I(runfcgi) command.
+   - U(http://www.virtualenv.org/, virtualenv) must be installed on the remote host if the virtualenv parameter is specified.
+   - This module will create a virtualenv if one does not already exist.
+   - This module assumes English error messages for the 'createcachetable' command to detect table existence, unfortunately.
+requirements: [ "virtualenv", "django" ]
 author: Scott Anderson
 '''
 
@@ -90,6 +91,9 @@ django-manage: >
     pythonpath=$settings_dir 
     virtualenv=$virtualenv_dir 
     database=$mydb
+
+#Run the SmokeTest test case from the main app. Useful for testing deploys.
+django-manage command=test app_path=django_dir apps=main.SmokeTest
 """
 
 
@@ -121,6 +125,9 @@ def _ensure_virtualenv(module):
 
     os.environ["PATH"] = "%s:%s" % (vbin, os.environ["PATH"])
 
+def createcachetable_filter_output(line):
+    return "Already exists" not in line
+
 def flush_filter_output(line):
     return "Installed" in line and "Installed 0 object" not in line
 
@@ -133,9 +140,9 @@ def syncdb_filter_output(line):
 def main():
     command_allowed_param_map = dict(
         cleanup=(),
+        createcachetable=('cache_table', 'database', ),
         flush=('database', ),
         loaddata=('database', 'fixtures', ),
-        runfcgi=('extra_args', ),
         syncdb=('database', ),
         test=('failfast', 'testrunner', 'liveserver', 'apps', ),
         validate=(),
@@ -143,6 +150,7 @@ def main():
 
     command_required_param_map = dict(
         loaddata=('fixtures', ),
+        createcachetable=('cache_table', ),
         )
 
     # forces --noinput on every command that needs it
@@ -153,27 +161,28 @@ def main():
         )
 
     # These params are allowed for certain commands only
-    specific_params = ('apps', 'database', 'extra_args', 'failfast', 'fixtures', 'liveserver', 'testrunner', )
+    specific_params = ('apps', 'database', 'failfast', 'fixtures', 'liveserver', 'testrunner', )
 
     # These params are automatically added to the command if present
     general_params = ('settings', 'pythonpath', )
     specific_boolean_params = ('failfast', )
-    end_of_command_params = ('apps', 'fixtures', 'extra_args', )
+    end_of_command_params = ('apps', 'cache_table', 'fixtures', )
 
     module = AnsibleModule(
-        argument_spec = dict(
-            command    = dict(default=None, required=True, choices=command_allowed_param_map.keys()),
-            app_path   = dict(default=None, required=True),
-            settings   = dict(default=None, required=False),
-            pythonpath = dict(default=None, required=False, aliases=['python_path']),
-            virtualenv = dict(default=None, required=False, aliases=['virtual_env']),
-            apps       = dict(default=None, required=False),
-            database   = dict(default=None, required=False),
-            extra_args = dict(default=None, required=False),
-            failfast   = dict(default='no', required=False, choices=BOOLEANS, aliases=['fail_fast']),
-            fixtures   = dict(default=None, required=False),
-            liveserver = dict(default=None, required=False, aliases=['live_server']),
-            testrunner = dict(default=None, required=False, aliases=['test_runner']),
+        argument_spec=dict(
+            command     = dict(default=None, required=True, choices=command_allowed_param_map.keys()),
+            app_path    = dict(default=None, required=True),
+            settings    = dict(default=None, required=False),
+            pythonpath  = dict(default=None, required=False, aliases=['python_path']),
+            virtualenv  = dict(default=None, required=False, aliases=['virtual_env']),
+
+            apps        = dict(default=None, required=False),
+            cache_table = dict(default=None, required=False),
+            database    = dict(default=None, required=False),
+            failfast    = dict(default='no', required=False, choices=BOOLEANS, aliases=['fail_fast']),
+            fixtures    = dict(default=None, required=False),
+            liveserver  = dict(default=None, required=False, aliases=['live_server']),
+            testrunner  = dict(default=None, required=False, aliases=['test_runner']),
         ),
     )
 
@@ -188,11 +197,9 @@ def main():
         if value and param not in command_allowed_param_map[command]:
             module.fail_json(msg='%s param is incompatible with command=%s' % (param, command))
 
-    required = command_required_param_map.get(command, None)
-    if required:
-        for param in required:
-            if not module.params[param]:
-                module.fail_json(msg='%s param is required for command=%s' % (param, command))
+    for param in command_required_param_map.get(command, ()):
+        if not module.params[param]:
+            module.fail_json(msg='%s param is required for command=%s' % (param, command))
 
     venv = module.params['virtualenv']
 
@@ -219,7 +226,10 @@ def main():
 
     rc, out, err = module.run_command(cmd)
     if rc != 0:
-        _fail(module, cmd, out, err, path=os.environ["PATH"], syspath=sys.path)
+        if command == 'createcachetable' and 'table' in err and 'already exists' in err:
+            out = 'Already exists.'
+        else:
+            _fail(module, cmd, out, err, path=os.environ["PATH"], syspath=sys.path)
 
     changed = False