Ticket #9170: 9170_manage_command.diff

File 9170_manage_command.diff, 4.1 KB (added by ericholscher, 5 years ago)

Super basic example and simple reference

  • docs/howto/custom-management-commands.txt

    diff --git a/docs/howto/custom-management-commands.txt b/docs/howto/custom-management-commands.txt
    index b6cc850..3f633c6 100644
    a b a command that can be executed as an action when you run ``manage.py``:: 
    2020            __init__.py
    2121            commands/
    2222                __init__.py
    23                 explode.py
     23                disable_comments.py
    2424        views.py
    2525
    2626In this example, the ``explode`` command will be made available to any project
    The ``explode.py`` module has only one requirement -- it must define a class 
    3030called ``Command`` that extends ``django.core.management.base.BaseCommand``.
    3131
    3232For more details on how to define your own commands, look at the code for the
    33 existing ``django-admin.py`` commands, in ``/django/core/management/commands``.
    34  No newline at end of file
     33existing ``django-admin.py`` commands, in ``/django/core/management/commands``.
     34
     35A simple example
     36----------------
     37
     38Management 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.
     39
     40Let'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.
     41
     42Following the example configuration above, your code will go in the **disable_comments.py** file::
     43
     44    import datetime
     45    from django.core.management.base import NoArgsCommand
     46
     47    class Command(NoArgsCommand):
     48        help = "Run as a cronjob to clean out old data from the database"
     49
     50        def handle_noargs(self, **options):
     51            from blog.models import Post
     52            for post in Post.objects.all():
     53                post.comments_active = False
     54                post.save()
     55
     56We 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!
     57
     58
     59Types of Management Commands
     60----------------------------
     61
     62There are different types of management commands that you may want to make use of. They all subclass ``BaseCommand``, and give you other options.
     63
     64AppCommand
     65~~~~~~~~~~
     66
     67``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.
     68
     69An example of a command that uses ``AppCommand`` is the ``sqlall`` management command that comes with Django.
     70
     71Rather 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.
     72
     73
     74LabelCommand
     75~~~~~~~~~~~~
     76
     77``LabelCommand`` is a management command which takes one or more arbitrary arguments (labels) on the command line, and does something with each of them.
     78
     79Rather 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.
     80
     81If the arguments should be names of installed applications, use ``AppCommand`` instead.
     82
     83
     84NoArgsCommand
     85~~~~~~~~~~~~~
     86
     87``NoArgsCommand`` is a management command which takes no arguments on the command line.
     88
     89Rather 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.
     90
     91Attempting to pass arguments will raise ``CommandError``.
     92
Back to Top