diff options
Diffstat (limited to 'docs/howto/custom-management-commands.txt')
| -rw-r--r-- | docs/howto/custom-management-commands.txt | 29 |
1 files changed, 17 insertions, 12 deletions
diff --git a/docs/howto/custom-management-commands.txt b/docs/howto/custom-management-commands.txt index f8b173cafa..7b25d6bdbe 100644 --- a/docs/howto/custom-management-commands.txt +++ b/docs/howto/custom-management-commands.txt @@ -1,5 +1,3 @@ -.. _howto-custom-management-commands: - ==================================== Writing custom django-admin commands ==================================== @@ -8,9 +6,9 @@ Writing custom django-admin commands Applications can register their own actions with ``manage.py``. For example, you might want to add a ``manage.py`` action for a Django app that you're -distributing. In this document, we will be building a custom ``closepoll`` +distributing. In this document, we will be building a custom ``closepoll`` command for the ``polls`` application from the -:ref:`tutorial<intro-tutorial01>`. +:doc:`tutorial</intro/tutorial01>`. To do this, just add a ``management/commands`` directory to the application. Each Python module in that directory will be auto-discovered and registered as @@ -62,15 +60,22 @@ look like this: poll.opened = False poll.save() - print 'Successfully closed poll "%s"' % poll_id + self.stdout.write('Successfully closed poll "%s"\n' % poll_id) + +.. note:: + When you are using management commands and wish to provide console + output, you should write to ``self.stdout`` and ``self.stderr``, + instead of printing to ``stdout`` and ``stderr`` directly. By + using these proxies, it becomes much easier to test your custom + command. -The new custom command can be called using ``python manage.py closepoll +The new custom command can be called using ``python manage.py closepoll <poll_id>``. The ``handle()`` method takes zero or more ``poll_ids`` and sets ``poll.opened`` to ``False`` for each one. If the user referenced any nonexistant polls, a :class:`CommandError` is raised. The ``poll.opened`` attribute does not exist -in the :ref:`tutorial<intro-tutorial01>` and was added to +in the :doc:`tutorial</intro/tutorial01>` and was added to ``polls.models.Poll`` for this example. The same ``closepoll`` could be easily modified to delete a given poll instead @@ -91,8 +96,8 @@ must be added to :attr:`~BaseCommand.option_list` like this: ) # ... -In addition to being able to add custom command line options, all -:ref:`management commands<ref-django-admin>` can accept some +In addition to being able to add custom command line options, all +:doc:`management commands</ref/django-admin>` can accept some default options such as :djadminopt:`--verbosity` and :djadminopt:`--traceback`. Command objects @@ -113,7 +118,7 @@ Subclassing the :class:`BaseCommand` class requires that you implement the Attributes ---------- -All attributes can be set in your derived class and can be used in +All attributes can be set in your derived class and can be used in :class:`BaseCommand`'s :ref:`subclasses<ref-basecommand-subclasses>`. .. attribute:: BaseCommand.args @@ -133,7 +138,7 @@ All attributes can be set in your derived class and can be used in .. attribute:: BaseCommand.help A short description of the command, which will be printed in the - help message when the user runs the command + help message when the user runs the command ``python manage.py help <command>``. .. attribute:: BaseCommand.option_list @@ -230,7 +235,7 @@ Rather than implementing :meth:`~BaseCommand.handle`, subclasses must implement A command which takes no arguments on the command line. Rather than implementing :meth:`~BaseCommand.handle`, subclasses must implement -:meth:`~NoArgsCommand.handle_noargs`; :meth:`~BaseCommand.handle` itself is +:meth:`~NoArgsCommand.handle_noargs`; :meth:`~BaseCommand.handle` itself is overridden to ensure no arguments are passed to the command. .. method:: NoArgsCommand.handle_noargs(**options) |