diff -r 5ff1fc726848 -r c6bca38c1cbf parts/django/docs/ref/signals.txt --- /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 ` for + information regarding how to register for and receive signals. + + The :doc:`comment framework ` sends a :doc:`set + of comment-related 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 ` 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 `. + +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 `. + +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.