Ticket #9170: 9170_manage_command.diff

docs/howto/custom-management-commands.txt

@@ -20 +20 @@
             __init__.py
             commands/
                 __init__.py
-                explode.py
+                disable_comments.py
         views.py
 
 In this example, the ``explode`` command will be made available to any project
@@ -30 +30 @@
 called ``Command`` that extends ``django.core.management.base.BaseCommand``.
 
 For more details on how to define your own commands, look at the code for the
-existing ``django-admin.py`` commands, in ``/django/core/management/commands``.
- No newline at end of file
+existing ``django-admin.py`` commands, in ``/django/core/management/commands``.
+
+A simple example
+----------------
+
+Management commands are generally useful because they allow you to execute code in the context of the Django Application which you are in. You can be sure that the environment and your models will be there, because they are processed through Django. A common use for management commands is for a cron job that will be called to do something with your Django installation.
+
+Let's say we have a blog application, and every once in a while we'd like to disable comments on our posts. This makes sure that spam comments won't get posted to them. If there is a spam attack on my blog, and I want to close comments quickly. We could write a management command to accomplish this.
+
+Following the example configuration above, your code will go in the **disable_comments.py** file::
+
+    import datetime
+    from django.core.management.base import NoArgsCommand
+
+    class Command(NoArgsCommand):
+        help = "Run as a cronjob to clean out old data from the database"
+
+        def handle_noargs(self, **options):
+            from blog.models import Post
+            for post in Post.objects.all():
+                post.comments_active = False
+                post.save()
+
+We could then run this command from the command line like ``./manage.py disable_comments``, or optionally ``django-admin.py disable_comments``. That is really all their is to it!
+
+
+Types of Management Commands
+----------------------------
+
+There are different types of management commands that you may want to make use of. They all subclass ``BaseCommand``, and give you other options.
+
+AppCommand
+~~~~~~~~~~
+
+``AppCommand`` is a management command which takes one or more installed application names as arguments, and does something with each of them. It is useful for management commands that act on an app specifically, and will validate that the apps you pass in exist.
+
+An example of a command that uses ``AppCommand`` is the ``sqlall`` management command that comes with Django.
+
+Rather than implementing ``handle()``, subclasses must implement ``handle_app``, function, which is passed in the model objects of the application. If multiple applications are passed in, it will called once for each application. 
+
+
+LabelCommand
+~~~~~~~~~~~~
+
+``LabelCommand`` is 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. An example of a command that does this is the ``startapp`` command.
+
+If the arguments should be names of installed applications, use ``AppCommand`` instead.
+
+
+NoArgsCommand
+~~~~~~~~~~~~~
+
+``NoArgsCommand`` is a management 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. ``syncdb`` is an example of this type of command.
+
+Attempting to pass arguments will raise ``CommandError``.
+