--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/parts/django/docs/ref/signals.txt Sat Jan 08 11:20:57 2011 +0530
@@ -0,0 +1,475 @@
+=======
+Signals
+=======
+
+A list of all the signals that Django sends.
+
+.. seealso::
+
+ See the documentation on the :doc:`signal dispatcher </topics/signals>` for
+ information regarding how to register for and receive signals.
+
+ The :doc:`comment framework </ref/contrib/comments/index>` sends a :doc:`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.
+
+ Note also that Django stores signal handlers as weak references by default,
+ so if your handler is a local function, it may be garbage collected. To
+ prevent this, pass ``weak=False`` when you call the signal's :meth:`~django.dispatch.Signal.connect`.
+
+pre_init
+--------
+
+.. attribute:: django.db.models.signals.pre_init
+ :module:
+
+.. ^^^^^^^ this :module: hack keeps Sphinx from prepending the module.
+
+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 :doc:`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
+ :module:
+
+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: the 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
+ :module:
+
+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
+ :module:
+
+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 created.
+
+pre_delete
+----------
+
+.. data:: django.db.models.signals.pre_delete
+ :module:
+
+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 deleted.
+
+post_delete
+-----------
+
+.. data:: django.db.models.signals.post_delete
+ :module:
+
+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 deleted.
+
+ Note that the object will no longer be in the database, so be very
+ careful what you do with this instance.
+
+m2m_changed
+-----------
+
+.. data:: django.db.models.signals.m2m_changed
+ :module:
+
+.. versionadded:: 1.2
+
+Sent when a :class:`ManyToManyField` is changed on a model instance.
+Strictly speaking, this is not a model signal since it is sent by the
+:class:`ManyToManyField`, but since it complements the
+:data:`pre_save`/:data:`post_save` and :data:`pre_delete`/:data:`post_delete`
+when it comes to tracking changes to models, it is included here.
+
+Arguments sent with this signal:
+
+ ``sender``
+ The intermediate model class describing the :class:`ManyToManyField`.
+ This class is automatically created when a many-to-many field is
+ defined; you can access it using the ``through`` attribute on the
+ many-to-many field.
+
+ ``instance``
+ The instance whose many-to-many relation is updated. This can be an
+ instance of the ``sender``, or of the class the :class:`ManyToManyField`
+ is related to.
+
+ ``action``
+ A string indicating the type of update that is done on the relation.
+ This can be one of the following:
+
+ ``"pre_add"``
+ Sent *before* one or more objects are added to the relation
+ ``"post_add"``
+ Sent *after* one or more objects are added to the relation
+ ``"pre_remove"``
+ Sent *after* one or more objects are removed from the relation
+ ``"post_remove"``
+ Sent *after* one or more objects are removed from the relation
+ ``"pre_clear"``
+ Sent *before* the relation is cleared
+ ``"post_clear"``
+ Sent *after* the relation is cleared
+
+ ``reverse``
+ Indicates which side of the relation is updated (i.e., if it is the
+ forward or reverse relation that is being modified).
+
+ ``model``
+ The class of the objects that are added to, removed from or cleared
+ from the relation.
+
+ ``pk_set``
+ For the ``pre_add``, ``post_add``, ``pre_remove`` and ``post_remove``
+ actions, this is a list of primary key values that have been added to
+ or removed from the relation.
+
+ For the ``pre_clear`` and ``post_clear`` actions, this is ``None``.
+
+For example, if a ``Pizza`` can have multiple ``Topping`` objects, modeled
+like this:
+
+.. code-block:: python
+
+ class Topping(models.Model):
+ # ...
+
+ class Pizza(models.Model):
+ # ...
+ toppings = models.ManyToManyField(Topping)
+
+If we would do something like this:
+
+.. code-block:: python
+
+ >>> p = Pizza.object.create(...)
+ >>> t = Topping.objects.create(...)
+ >>> p.toppings.add(t)
+
+the arguments sent to a :data:`m2m_changed` handler would be:
+
+ ============== ============================================================
+ Argument Value
+ ============== ============================================================
+ ``sender`` ``Pizza.toppings.through`` (the intermediate m2m class)
+
+ ``instance`` ``p`` (the ``Pizza`` instance being modified)
+
+ ``action`` ``"pre_add"`` (followed by a separate signal with ``"post_add"``)
+
+ ``reverse`` ``False`` (``Pizza`` contains the :class:`ManyToManyField`,
+ so this call modifies the forward relation)
+
+ ``model`` ``Topping`` (the class of the objects added to the
+ ``Pizza``)
+
+ ``pk_set`` ``[t.id]`` (since only ``Topping t`` was added to the relation)
+ ============== ============================================================
+
+And if we would then do something like this:
+
+.. code-block:: python
+
+ >>> t.pizza_set.remove(p)
+
+the arguments sent to a :data:`m2m_changed` handler would be:
+
+ ============== ============================================================
+ Argument Value
+ ============== ============================================================
+ ``sender`` ``Pizza.toppings.through`` (the intermediate m2m class)
+
+ ``instance`` ``t`` (the ``Topping`` instance being modified)
+
+ ``action`` ``"pre_remove"`` (followed by a separate signal with ``"post_remove"``)
+
+ ``reverse`` ``True`` (``Pizza`` contains the :class:`ManyToManyField`,
+ so this call modifies the reverse relation)
+
+ ``model`` ``Pizza`` (the class of the objects removed from the
+ ``Topping``)
+
+ ``pk_set`` ``[p.id]`` (since only ``Pizza p`` was removed from the
+ relation)
+ ============== ============================================================
+
+class_prepared
+--------------
+
+.. data:: django.db.models.signals.class_prepared
+ :module:
+
+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 :doc:`django-admin </ref/django-admin>`.
+
+post_syncdb
+-----------
+
+.. data:: django.db.models.signals.post_syncdb
+ :module:
+
+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
+ :module:
+
+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
+ :module:
+
+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
+ :module:
+
+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 :doc:`running tests </topics/testing>`.
+
+template_rendered
+-----------------
+
+.. data:: django.test.signals.template_rendered
+ :module:
+
+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.
+
+Database Wrappers
+=================
+
+.. module:: django.db.backends
+ :synopsis: Core signals sent by the database wrapper.
+
+Signals sent by the database wrapper when a database connection is
+initiated.
+
+connection_created
+------------------
+
+.. data:: django.db.backends.signals.connection_created
+ :module:
+
+.. versionadded:: 1.1
+
+.. versionchanged:: 1.2
+ The connection argument was added
+
+Sent when the database wrapper makes the initial connection to the
+database. This is particularly useful if you'd like to send any post
+connection commands to the SQL backend.
+
+Arguments sent with this signal:
+
+ sender
+ The database wrapper class -- i.e.
+ :class: `django.db.backends.postgresql_psycopg2.DatabaseWrapper` or
+ :class: `django.db.backends.mysql.DatabaseWrapper`, etc.
+
+ connection
+ The database connection that was opened. This can be used in a
+ multiple-database configuration to differentiate connection signals
+ from different databases.