Fixed #8326: added signals documentation.

Thanks to MercuryTide's signal whitepaper from 2006 (http://www.mercurytide.co.uk/whitepapers/django-signals/) for inspiration and ideas for organization, and to the folks who got the Signals wiki page together for some of the content.


git-svn-id: http://code.djangoproject.com/svn/django/trunk@8590 bcc190cf-cafb-0310-a4f2-bffc1f526a37

4 files changed, 385 insertions, 1 deletions

diff --git a/docs/ref/contrib/comments/index.txt b/docs/ref/contrib/comments/index.txt
index 1e9418b55a..443c89d3c1 100644
--- a/docs/ref/contrib/comments/index.txt
+++ b/docs/ref/contrib/comments/index.txt
@@ -208,5 +208,6 @@ More information
    :maxdepth: 1
 
    settings
+   signals
    upgrade
 
diff --git a/docs/ref/contrib/comments/signals.txt b/docs/ref/contrib/comments/signals.txt
new file mode 100644
index 0000000000..d3fd85cad5
--- /dev/null
+++ b/docs/ref/contrib/comments/signals.txt
@@ -0,0 +1,88 @@
+.. _ref-contrib-comments-signals:
+
+================================
+Signals sent by the comments app
+================================
+
+.. module:: django.contrib.comments.signals
+   :synopsis: Signals sent by the comment module.
+
+The comment app sends a series of :ref:`signals <topics-signals>` to allow for
+comment moderation and similar activities. See :ref:`the introduction to signals
+<topics-signals>` for information about how to register for and receive these
+signals.
+
+comment_will_be_posted
+======================
+
+.. data:: django.contrib.comments.signals.comment_will_be_posted
+
+Sent just before a comment will be saved, after it's been sanity checked and
+submitted. This can be used to modify the comment (in place) with posting
+details or other such actions.
+
+If any receiver returns ``False`` the comment will be discarded and a 403 (not
+allowed) response will be returned.
+
+This signal is sent at more or less the same time (just before, actually) as the
+``Comment`` object's :data:`~django.db.models.signals.pre_save` signal.
+
+Arguments sent with this signal:
+    
+    ``sender``
+        The comment model.
+        
+    ``comment``
+        The comment instance about to be posted. Note that it won't have been
+        saved into the database yet, so it won't have a primary key, and any
+        relations might not work correctly yet.
+        
+    ``request``
+        The :class:`~django.http.HttpRequest` that posted the comment.
+        
+comment_was_posted
+==================
+
+.. data:: django.contrib.comments.signals.comment_was_posted
+
+Sent just after the comment is saved.
+
+Arguments sent with this signal:
+    
+    ``sender``
+        The comment model.
+        
+    ``comment``
+        The comment instance that was posted. Note that it will have already
+        been saved, so if you modify it you'll need to call
+        :meth:`~django.db.models.Model.save` again.
+        
+    ``request``
+        The :class:`~django.http.HttpRequest` that posted the comment.
+
+comment_was_flagged
+===================
+
+Sent after a comment was "flagged" in some way. Check the flag to see if this
+was a user requesting removal of a comment, a moderator approving/removing a
+comment, or some other custom user flag.
+
+Arguments sent with this signal:
+    
+    ``sender``
+        The comment model.
+        
+    ``comment``
+        The comment instance that was posted. Note that it will have already
+        been saved, so if you modify it you'll need to call
+        :meth:`~django.db.models.Model.save` again.
+        
+    ``flag``
+        The :class:`~django.contrib.comments.models.CommentFlag` that's been
+        attached to the comment.
+        
+    ``created``
+        ``True`` if this is a new flag; ``False`` if it's a duplicate flag.
+        
+    ``request``
+        The :class:`~django.http.HttpRequest` that posted the comment.
diff --git a/docs/ref/index.txt b/docs/ref/index.txt
index ac71175abf..c54cd20954 100644
--- a/docs/ref/index.txt
+++ b/docs/ref/index.txt
@@ -9,13 +9,14 @@ API Reference
    contrib/index
    databases
    django-admin
+   files/index
    forms/index
    generic-views
    middleware
    models/index
    request-response
    settings
+   signals
    templates/index
    unicode
-   files/index
    
\ No newline at end of file
diff --git a/docs/ref/signals.txt b/docs/ref/signals.txt
new file mode 100644
index 0000000000..df6097fb82
--- /dev/null
+++ b/docs/ref/signals.txt
@@ -0,0 +1,294 @@
+.. _ref-signals:
+
+=========================
+Built-in signal reference
+=========================
+
+A list of all the signals that Django sends.
+
+.. seealso::
+
+    The :ref:`comment framework <ref-contrib-comments-index>` sends a :ref:`set
+    of comment-related signals <ref-contrib-comments-signals>`.
+
+Model signals
+=============
+
+.. module:: django.db.models.signals
+   :synopsis: Signals sent by the model system.
+
+The :mod:`django.db.models.signals` module defines a set of signals sent by the
+module system.
+
+.. warning::
+
+    Many of these signals are sent by various model methods like
+    :meth:`~django.db.models.Model.__init__` or
+    :meth:`~django.db.models.Model.save` that you can overwrite in your own
+    code.
+
+    If you override these methods on your model, you must call the parent class'
+    methods for this signals to be sent.
+
+pre_init
+--------
+
+.. data:: django.db.models.signals.pre_init
+
+Whenever you instantiate a Django model,, this signal is sent at the beginning
+of the model's :meth:`~django.db.models.Model.__init__` method.
+
+Arguments sent with this signal:
+
+    ``sender``
+        The model class that just had an instance created.
+
+    ``args``
+        A list of positional arguments passed to
+        :meth:`~django.db.models.Model.__init__`:
+
+    ``kwargs``
+        A dictionary of keyword arguments passed to
+        :meth:`~django.db.models.Model.__init__`:.
+
+For example, the :ref:`tutorial <intro-tutorial01>` has this line:
+
+.. code-block:: python
+
+    p = Poll(question="What's up?", pub_date=datetime.now())
+
+The arguments sent to a :data:`pre_init` handler would be:
+
+    ==========  ===============================================================
+    Argument    Value
+    ==========  ===============================================================
+    ``sender``  ``Poll`` (the class itself)
+
+    ``args``    ``[]`` (an empty list because there were no positional
+                arguments passed to ``__init__``.)
+
+    ``kwargs``  ``{'question': "What's up?", 'pub_date': datetime.now()}``
+    ==========  ===============================================================
+
+post_init
+---------
+
+.. data:: django.db.models.signals.post_init
+
+Like pre_init, but this one is sent when the :meth:`~django.db.models.Model.__init__`: method finishes.
+
+Arguments sent with this signal:
+
+    ``sender``
+        As above: rhe model class that just had an instance created.
+
+    ``instance``
+        The actual instance of the model that's just been created.
+
+pre_save
+--------
+
+.. data:: django.db.models.signals.pre_save
+
+This is sent at the beginning of a model's :meth:`~django.db.models.Model.save`
+method.
+
+Arguments sent with this signal:
+
+    ``sender``
+        The model class.
+
+    ``instance``
+        The actual instance being saved.
+
+post_save
+---------
+
+.. data:: django.db.models.signals.post_save
+
+Like :data:`pre_save`, but sent at the end of the
+:meth:`~django.db.models.Model.save` method.
+
+Arguments sent with this signal:
+
+    ``sender``
+        The model class.
+
+    ``instance``
+        The actual instance being saved.
+
+    ``created``
+        A boolean; ``True`` if a new record was create.
+
+pre_delete
+----------
+
+.. data:: django.db.models.signals.pre_delete
+
+Sent at the beginning of a model's :meth:`~django.db.models.Model.delete`
+method.
+
+Arguments sent with this signal:
+
+    ``sender``
+        The model class.
+
+    ``instance``
+        The actual instance being saved.
+
+post_delete
+-----------
+
+.. data:: django.db.models.signals.post_delete
+
+Like :data:`pre_delete`, but sent at the end of the
+:meth:`~django.db.models.Model.delete` method.
+
+Arguments sent with this signal:
+
+    ``sender``
+        The model class.
+
+    ``instance``
+        The actual instance being saved.
+
+        Note that the object will no longer be in the database, so be very
+        careful what you do with this instance
+
+class_prepared
+--------------
+
+.. data:: django.db.models.signals.class_prepared
+
+Sent whenever a model class has been "prepared" -- that is, once model has
+been defined and registered with Django's model system. Django uses this
+signal internally; it's not generally used in third-party applications.
+
+Arguments that are sent with this signal:
+
+``sender``
+    The model class which was just prepared.
+
+Management signals
+==================
+
+Signals sent by :ref:`django-admin <ref-django-admin>`.
+
+post_syncdb
+-----------
+
+.. data:: django.db.models.signals.post_syncdb
+
+Sent by :djadmin:`syncdb` after it installs an application.
+
+Any handlers that listen to this signal need to be written in a particular
+place: a ``management`` module in one of your :setting:`INSTALLED_APPS`. If
+handlers are registered anywhere else they may not be loaded by
+:djadmin:`syncdb`.
+
+Arguments sent with this signal:
+
+    ``sender``
+        The ``models`` module that was just installed. That is, if
+        :djadmin:`syncdb` just installed an app called ``"foo.bar.myapp"``,
+        ``sender`` will be the ``foo.bar.myapp.models`` module.
+
+    ``app``
+        Same as ``sender``.
+
+    ``created_models``
+        A list of the model classes from any app which :djadmin:`syncdb` has
+        created so far.
+
+    ``verbosity``
+        Indicates how much information manage.py is printing on screen. See
+        the :djadminopt:`--verbosity`` flag for details.
+
+        Functions which listen for :data:`post_syncdb` should adjust what they
+        output to the screen based on the value of this argument.
+
+    ``interactive``
+        If ``interactive`` is ``True``, it's safe to prompt the user to input
+        things on the command line. If ``interactive`` is ``False``, functions
+        which listen for this signal should not try to prompt for anything.
+
+        For example, the :mod:`django.contrib.auth` app only prompts to create a
+        superuser when ``interactive`` is ``True``.
+
+Request/response signals
+========================
+
+.. module:: django.core.signals
+   :synopsis: Core signals sent by the request/response system.
+
+Signals sent by the core framework when processing a request.
+
+request_started
+---------------
+
+.. data:: django.core.signals.request_started
+
+Sent when Django begins processing an HTTP request.
+
+Arguments sent with this signal:
+
+    ``sender``
+        The handler class -- i.e.
+        :class:`django.core.handlers.modpython.ModPythonHandler` or
+        :class:`django.core.handlers.wsgi.WsgiHandler` -- that handled
+        the request.
+
+request_finished
+----------------
+
+.. data:: django.core.signals.request_finished
+
+Sent when Django finishes processing an HTTP request.
+
+Arguments sent with this signal:
+
+    ``sender``
+        The handler class, as above.
+
+got_request_exception
+---------------------
+
+.. data:: django.core.signals.got_request_exception
+
+This signal is sent whenever Django encounters an exception while processing an incoming HTTP request.
+
+Arguments sent with this signal:
+
+    ``sender``
+        The handler class, as above.
+
+    ``request``
+        The :class:`~django.http.HttpRequest` object.
+
+Test signals
+============
+
+.. module:: django.test.signals
+   :synopsis: Signals sent during testing.
+
+Signals only sent when :ref:`running tests <topics-testing>`.
+
+template_rendered
+-----------------
+
+.. data:: django.test.signals.template_rendered
+
+Sent when the test system renders a template. This signal is not emitted during
+normal operation of a Django server -- it is only available during testing.
+
+Arguments sent with this signal:
+
+    sender
+        The :class:`~django.template.Template` object which was rendered.
+
+    template
+        Same as sender
+
+    context
+        The :class:`~django.template.Context` with which the template was
+        rendered.