/docs/ref/signals.txt

  1=======
  2Signals
  3=======
  4
  5A list of all the signals that Django sends.
  6
  7.. seealso::
  8
  9    See the documentation on the :doc:`signal dispatcher </topics/signals>` for
 10    information regarding how to register for and receive signals.
 11
 12    The :doc:`comment framework </ref/contrib/comments/index>` sends a :doc:`set
 13    of comment-related signals </ref/contrib/comments/signals>`.
 14
 15    The :doc:`authentication framework </topics/auth>` sends :ref:`signals when
 16    a user is logged in / out <topics-auth-signals>`.
 17
 18Model signals
 19=============
 20
 21.. module:: django.db.models.signals
 22   :synopsis: Signals sent by the model system.
 23
 24The :mod:`django.db.models.signals` module defines a set of signals sent by the
 25module system.
 26
 27.. warning::
 28
 29    Many of these signals are sent by various model methods like
 30    :meth:`~django.db.models.Model.__init__` or
 31    :meth:`~django.db.models.Model.save` that you can overwrite in your own
 32    code.
 33
 34    If you override these methods on your model, you must call the parent class'
 35    methods for this signals to be sent.
 36
 37    Note also that Django stores signal handlers as weak references by default,
 38    so if your handler is a local function, it may be garbage collected.  To
 39    prevent this, pass ``weak=False`` when you call the signal's :meth:`~django.dispatch.Signal.connect`.
 40
 41pre_init
 42--------
 43
 44.. attribute:: django.db.models.signals.pre_init
 45   :module:
 46
 47.. ^^^^^^^ this :module: hack keeps Sphinx from prepending the module.
 48
 49Whenever you instantiate a Django model,, this signal is sent at the beginning
 50of the model's :meth:`~django.db.models.Model.__init__` method.
 51
 52Arguments sent with this signal:
 53
 54``sender``
 55    The model class that just had an instance created.
 56
 57``args``
 58    A list of positional arguments passed to
 59    :meth:`~django.db.models.Model.__init__`:
 60
 61``kwargs``
 62    A dictionary of keyword arguments passed to
 63    :meth:`~django.db.models.Model.__init__`:.
 64
 65For example, the :doc:`tutorial </intro/tutorial01>` has this line:
 66
 67.. code-block:: python
 68
 69    p = Poll(question="What's up?", pub_date=datetime.now())
 70
 71The arguments sent to a :data:`pre_init` handler would be:
 72
 73    ==========  ===============================================================
 74    Argument    Value
 75    ==========  ===============================================================
 76    ``sender``  ``Poll`` (the class itself)
 77
 78    ``args``    ``[]`` (an empty list because there were no positional
 79                arguments passed to ``__init__``.)
 80
 81    ``kwargs``  ``{'question': "What's up?", 'pub_date': datetime.now()}``
 82    ==========  ===============================================================
 83
 84post_init
 85---------
 86
 87.. data:: django.db.models.signals.post_init
 88   :module:
 89
 90Like pre_init, but this one is sent when the :meth:`~django.db.models.Model.__init__`: method finishes.
 91
 92Arguments sent with this signal:
 93
 94``sender``
 95    As above: the model class that just had an instance created.
 96
 97``instance``
 98    The actual instance of the model that's just been created.
 99
100pre_save
101--------
102
103.. data:: django.db.models.signals.pre_save
104   :module:
105
106This is sent at the beginning of a model's :meth:`~django.db.models.Model.save`
107method.
108
109Arguments sent with this signal:
110
111``sender``
112    The model class.
113
114``instance``
115    The actual instance being saved.
116
117.. versionadded:: 1.3
118
119``using``
120    The database alias being used.
121
122post_save
123---------
124
125.. data:: django.db.models.signals.post_save
126   :module:
127
128Like :data:`pre_save`, but sent at the end of the
129:meth:`~django.db.models.Model.save` method.
130
131Arguments sent with this signal:
132
133``sender``
134    The model class.
135
136``instance``
137    The actual instance being saved.
138
139``created``
140    A boolean; ``True`` if a new record was created.
141
142.. versionadded:: 1.3
143
144``using``
145    The database alias being used.
146
147pre_delete
148----------
149
150.. data:: django.db.models.signals.pre_delete
151   :module:
152
153Sent at the beginning of a model's :meth:`~django.db.models.Model.delete`
154method.
155
156Arguments sent with this signal:
157
158``sender``
159    The model class.
160
161``instance``
162    The actual instance being deleted.
163
164.. versionadded:: 1.3
165
166``using``
167    The database alias being used.
168
169post_delete
170-----------
171
172.. data:: django.db.models.signals.post_delete
173   :module:
174
175Like :data:`pre_delete`, but sent at the end of the
176:meth:`~django.db.models.Model.delete` method.
177
178Arguments sent with this signal:
179
180``sender``
181    The model class.
182
183``instance``
184    The actual instance being deleted.
185
186    Note that the object will no longer be in the database, so be very
187    careful what you do with this instance.
188
189.. versionadded:: 1.3
190
191``using``
192    The database alias being used.
193
194m2m_changed
195-----------
196
197.. data:: django.db.models.signals.m2m_changed
198   :module:
199
200.. versionadded:: 1.2
201
202Sent when a :class:`ManyToManyField` is changed on a model instance.
203Strictly speaking, this is not a model signal since it is sent by the
204:class:`ManyToManyField`, but since it complements the
205:data:`pre_save`/:data:`post_save` and :data:`pre_delete`/:data:`post_delete`
206when it comes to tracking changes to models, it is included here.
207
208Arguments sent with this signal:
209
210``sender``
211    The intermediate model class describing the :class:`ManyToManyField`.
212    This class is automatically created when a many-to-many field is
213    defined; you can access it using the ``through`` attribute on the
214    many-to-many field.
215
216``instance``
217    The instance whose many-to-many relation is updated. This can be an
218    instance of the ``sender``, or of the class the :class:`ManyToManyField`
219    is related to.
220
221``action``
222    A string indicating the type of update that is done on the relation.
223    This can be one of the following:
224
225    ``"pre_add"``
226        Sent *before* one or more objects are added to the relation.
227    ``"post_add"``
228        Sent *after* one or more objects are added to the relation.
229    ``"pre_remove"``
230        Sent *before* one or more objects are removed from the relation.
231    ``"post_remove"``
232        Sent *after* one or more objects are removed from the relation.
233    ``"pre_clear"``
234        Sent *before* the relation is cleared.
235    ``"post_clear"``
236        Sent *after* the relation is cleared.
237
238``reverse``
239    Indicates which side of the relation is updated (i.e., if it is the
240    forward or reverse relation that is being modified).
241
242``model``
243    The class of the objects that are added to, removed from or cleared
244    from the relation.
245
246``pk_set``
247    For the ``pre_add``, ``post_add``, ``pre_remove`` and ``post_remove``
248    actions, this is a list of primary key values that have been added to
249    or removed from the relation.
250
251    For the ``pre_clear`` and ``post_clear`` actions, this is ``None``.
252
253.. versionadded:: 1.3
254
255``using``
256    The database alias being used.
257
258For example, if a ``Pizza`` can have multiple ``Topping`` objects, modeled
259like this:
260
261.. code-block:: python
262
263    class Topping(models.Model):
264        # ...
265
266    class Pizza(models.Model):
267        # ...
268        toppings = models.ManyToManyField(Topping)
269
270If we would do something like this:
271
272.. code-block:: python
273
274    >>> p = Pizza.object.create(...)
275    >>> t = Topping.objects.create(...)
276    >>> p.toppings.add(t)
277
278the arguments sent to a :data:`m2m_changed` handler would be:
279
280    ==============  ============================================================
281    Argument        Value
282    ==============  ============================================================
283    ``sender``      ``Pizza.toppings.through`` (the intermediate m2m class)
284
285    ``instance``    ``p`` (the ``Pizza`` instance being modified)
286
287    ``action``      ``"pre_add"`` (followed by a separate signal with ``"post_add"``)
288
289    ``reverse``     ``False`` (``Pizza`` contains the :class:`ManyToManyField`,
290                    so this call modifies the forward relation)
291
292    ``model``       ``Topping`` (the class of the objects added to the
293                    ``Pizza``)
294
295    ``pk_set``      ``[t.id]`` (since only ``Topping t`` was added to the relation)
296
297    ``using``       ``"default"`` (since the default router sends writes here)
298    ==============  ============================================================
299
300And if we would then do something like this:
301
302.. code-block:: python
303
304    >>> t.pizza_set.remove(p)
305
306the arguments sent to a :data:`m2m_changed` handler would be:
307
308    ==============  ============================================================
309    Argument        Value
310    ==============  ============================================================
311    ``sender``      ``Pizza.toppings.through`` (the intermediate m2m class)
312
313    ``instance``    ``t`` (the ``Topping`` instance being modified)
314
315    ``action``      ``"pre_remove"`` (followed by a separate signal with ``"post_remove"``)
316
317    ``reverse``     ``True`` (``Pizza`` contains the :class:`ManyToManyField`,
318                    so this call modifies the reverse relation)
319
320    ``model``       ``Pizza`` (the class of the objects removed from the
321                    ``Topping``)
322
323    ``pk_set``      ``[p.id]`` (since only ``Pizza p`` was removed from the
324                    relation)
325
326    ``using``       ``"default"`` (since the default router sends writes here)
327    ==============  ============================================================
328
329class_prepared
330--------------
331
332.. data:: django.db.models.signals.class_prepared
333   :module:
334
335Sent whenever a model class has been "prepared" -- that is, once model has
336been defined and registered with Django's model system. Django uses this
337signal internally; it's not generally used in third-party applications.
338
339Arguments that are sent with this signal:
340
341``sender``
342    The model class which was just prepared.
343
344Management signals
345==================
346
347Signals sent by :doc:`django-admin </ref/django-admin>`.
348
349post_syncdb
350-----------
351
352.. data:: django.db.models.signals.post_syncdb
353   :module:
354
355Sent by :djadmin:`syncdb` after it installs an application.
356
357Any handlers that listen to this signal need to be written in a particular
358place: a ``management`` module in one of your :setting:`INSTALLED_APPS`. If
359handlers are registered anywhere else they may not be loaded by
360:djadmin:`syncdb`.
361
362Arguments sent with this signal:
363
364``sender``
365    The ``models`` module that was just installed. That is, if
366    :djadmin:`syncdb` just installed an app called ``"foo.bar.myapp"``,
367    ``sender`` will be the ``foo.bar.myapp.models`` module.
368
369``app``
370    Same as ``sender``.
371
372``created_models``
373    A list of the model classes from any app which :djadmin:`syncdb` has
374    created so far.
375
376``verbosity``
377    Indicates how much information manage.py is printing on screen. See
378    the :djadminopt:`--verbosity` flag for details.
379
380    Functions which listen for :data:`post_syncdb` should adjust what they
381    output to the screen based on the value of this argument.
382
383``interactive``
384    If ``interactive`` is ``True``, it's safe to prompt the user to input
385    things on the command line. If ``interactive`` is ``False``, functions
386    which listen for this signal should not try to prompt for anything.
387
388    For example, the :mod:`django.contrib.auth` app only prompts to create a
389    superuser when ``interactive`` is ``True``.
390
391For example, ``yourapp/management/__init__.py`` could be written like::
392
393    from django.db.models.signals import post_syncdb
394    import yourapp.models
395
396    def my_callback(sender, **kwargs):
397        # Your specific logic here
398        pass
399
400    post_syncdb.connect(my_callback, sender=yourapp.models)
401
402Request/response signals
403========================
404
405.. module:: django.core.signals
406   :synopsis: Core signals sent by the request/response system.
407
408Signals sent by the core framework when processing a request.
409
410request_started
411---------------
412
413.. data:: django.core.signals.request_started
414   :module:
415
416Sent when Django begins processing an HTTP request.
417
418Arguments sent with this signal:
419
420``sender``
421    The handler class -- e.g.
422    :class:`django.core.handlers.wsgi.WsgiHandler` -- that handled
423    the request.
424
425request_finished
426----------------
427
428.. data:: django.core.signals.request_finished
429   :module:
430
431Sent when Django finishes processing an HTTP request.
432
433Arguments sent with this signal:
434
435``sender``
436    The handler class, as above.
437
438got_request_exception
439---------------------
440
441.. data:: django.core.signals.got_request_exception
442   :module:
443
444This signal is sent whenever Django encounters an exception while processing an incoming HTTP request.
445
446Arguments sent with this signal:
447
448``sender``
449    The handler class, as above.
450
451``request``
452    The :class:`~django.http.HttpRequest` object.
453
454Test signals
455============
456
457.. module:: django.test.signals
458   :synopsis: Signals sent during testing.
459
460Signals only sent when :doc:`running tests </topics/testing>`.
461
462template_rendered
463-----------------
464
465.. data:: django.test.signals.template_rendered
466   :module:
467
468Sent when the test system renders a template. This signal is not emitted during
469normal operation of a Django server -- it is only available during testing.
470
471Arguments sent with this signal:
472
473``sender``
474    The :class:`~django.template.Template` object which was rendered.
475
476``template``
477    Same as sender
478
479``context``
480    The :class:`~django.template.Context` with which the template was
481    rendered.
482
483Database Wrappers
484=================
485
486.. module:: django.db.backends
487   :synopsis: Core signals sent by the database wrapper.
488
489Signals sent by the database wrapper when a database connection is
490initiated.
491
492connection_created
493------------------
494
495.. data:: django.db.backends.signals.connection_created
496   :module:
497
498.. versionchanged:: 1.2
499   The connection argument was added
500
501Sent when the database wrapper makes the initial connection to the
502database.  This is particularly useful if you'd like to send any post
503connection commands to the SQL backend.
504
505Arguments sent with this signal:
506
507``sender``
508    The database wrapper class -- i.e.
509    :class:`django.db.backends.postgresql_psycopg2.DatabaseWrapper` or
510    :class:`django.db.backends.mysql.DatabaseWrapper`, etc.
511
512``connection``
513    The database connection that was opened. This can be used in a
514    multiple-database configuration to differentiate connection signals
515    from different databases.