1 =======

     2 Signals

     3 =======

     4 

     5 A 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 Model signals

    16 =============

    17 

    18 .. module:: django.db.models.signals

    19    :synopsis: Signals sent by the model system.

    20 

    21 The :mod:`django.db.models.signals` module defines a set of signals sent by the

    22 module system.

    23 

    24 .. warning::

    25 

    26     Many of these signals are sent by various model methods like

    27     :meth:`~django.db.models.Model.__init__` or

    28     :meth:`~django.db.models.Model.save` that you can overwrite in your own

    29     code.

    30 

    31     If you override these methods on your model, you must call the parent class'

    32     methods for this signals to be sent.

    33 

    34 	Note also that Django stores signal handlers as weak references by default,

    35 	so if your handler is a local function, it may be garbage collected.  To

    36 	prevent this, pass ``weak=False`` when you call the signal's :meth:`~django.dispatch.Signal.connect`.

    37 

    38 pre_init

    39 --------

    40 

    41 .. attribute:: django.db.models.signals.pre_init

    42    :module:

    43 

    44 .. ^^^^^^^ this :module: hack keeps Sphinx from prepending the module.

    45 

    46 Whenever you instantiate a Django model,, this signal is sent at the beginning

    47 of the model's :meth:`~django.db.models.Model.__init__` method.

    48 

    49 Arguments sent with this signal:

    50 

    51     ``sender``

    52         The model class that just had an instance created.

    53 

    54     ``args``

    55         A list of positional arguments passed to

    56         :meth:`~django.db.models.Model.__init__`:

    57 

    58     ``kwargs``

    59         A dictionary of keyword arguments passed to

    60         :meth:`~django.db.models.Model.__init__`:.

    61 

    62 For example, the :doc:`tutorial </intro/tutorial01>` has this line:

    63 

    64 .. code-block:: python

    65 

    66     p = Poll(question="What's up?", pub_date=datetime.now())

    67 

    68 The arguments sent to a :data:`pre_init` handler would be:

    69 

    70     ==========  ===============================================================

    71     Argument    Value

    72     ==========  ===============================================================

    73     ``sender``  ``Poll`` (the class itself)

    74 

    75     ``args``    ``[]`` (an empty list because there were no positional

    76                 arguments passed to ``__init__``.)

    77 

    78     ``kwargs``  ``{'question': "What's up?", 'pub_date': datetime.now()}``

    79     ==========  ===============================================================

    80 

    81 post_init

    82 ---------

    83 

    84 .. data:: django.db.models.signals.post_init

    85    :module:

    86 

    87 Like pre_init, but this one is sent when the :meth:`~django.db.models.Model.__init__`: method finishes.

    88 

    89 Arguments sent with this signal:

    90 

    91     ``sender``

    92         As above: the model class that just had an instance created.

    93 

    94     ``instance``

    95         The actual instance of the model that's just been created.

    96 

    97 pre_save

    98 --------

    99 

   100 .. data:: django.db.models.signals.pre_save

   101    :module:

   102 

   103 This is sent at the beginning of a model's :meth:`~django.db.models.Model.save`

   104 method.

   105 

   106 Arguments sent with this signal:

   107 

   108     ``sender``

   109         The model class.

   110 

   111     ``instance``

   112         The actual instance being saved.

   113 

   114 post_save

   115 ---------

   116 

   117 .. data:: django.db.models.signals.post_save

   118    :module:

   119 

   120 Like :data:`pre_save`, but sent at the end of the

   121 :meth:`~django.db.models.Model.save` method.

   122 

   123 Arguments sent with this signal:

   124 

   125     ``sender``

   126         The model class.

   127 

   128     ``instance``

   129         The actual instance being saved.

   130 

   131     ``created``

   132         A boolean; ``True`` if a new record was created.

   133 

   134 pre_delete

   135 ----------

   136 

   137 .. data:: django.db.models.signals.pre_delete

   138    :module:

   139 

   140 Sent at the beginning of a model's :meth:`~django.db.models.Model.delete`

   141 method.

   142 

   143 Arguments sent with this signal:

   144 

   145     ``sender``

   146         The model class.

   147 

   148     ``instance``

   149         The actual instance being deleted.

   150 

   151 post_delete

   152 -----------

   153 

   154 .. data:: django.db.models.signals.post_delete

   155    :module:

   156 

   157 Like :data:`pre_delete`, but sent at the end of the

   158 :meth:`~django.db.models.Model.delete` method.

   159 

   160 Arguments sent with this signal:

   161 

   162     ``sender``

   163         The model class.

   164 

   165     ``instance``

   166         The actual instance being deleted.

   167 

   168         Note that the object will no longer be in the database, so be very

   169         careful what you do with this instance.

   170 

   171 m2m_changed

   172 -----------

   173 

   174 .. data:: django.db.models.signals.m2m_changed

   175    :module:

   176 

   177 .. versionadded:: 1.2

   178 

   179 Sent when a :class:`ManyToManyField` is changed on a model instance.

   180 Strictly speaking, this is not a model signal since it is sent by the

   181 :class:`ManyToManyField`, but since it complements the

   182 :data:`pre_save`/:data:`post_save` and :data:`pre_delete`/:data:`post_delete`

   183 when it comes to tracking changes to models, it is included here.

   184 

   185 Arguments sent with this signal:

   186 

   187     ``sender``

   188         The intermediate model class describing the :class:`ManyToManyField`.

   189         This class is automatically created when a many-to-many field is

   190         defined; you can access it using the ``through`` attribute on the

   191         many-to-many field.

   192 

   193     ``instance``

   194         The instance whose many-to-many relation is updated. This can be an

   195         instance of the ``sender``, or of the class the :class:`ManyToManyField`

   196         is related to.

   197 

   198     ``action``

   199         A string indicating the type of update that is done on the relation.

   200         This can be one of the following:

   201 

   202         ``"pre_add"``

   203             Sent *before* one or more objects are added to the relation

   204         ``"post_add"``

   205             Sent *after* one or more objects are added to the relation

   206         ``"pre_remove"``

   207             Sent *after* one or more objects are removed from the relation

   208         ``"post_remove"``

   209             Sent *after* one or more objects are removed from the relation

   210         ``"pre_clear"``

   211             Sent *before* the relation is cleared

   212         ``"post_clear"``

   213             Sent *after* the relation is cleared

   214 

   215     ``reverse``

   216         Indicates which side of the relation is updated (i.e., if it is the

   217         forward or reverse relation that is being modified).

   218 

   219     ``model``

   220         The class of the objects that are added to, removed from or cleared

   221         from the relation.

   222 

   223     ``pk_set``

   224         For the ``pre_add``, ``post_add``, ``pre_remove`` and ``post_remove``

   225         actions, this is a list of primary key values that have been added to

   226         or removed from the relation.

   227 

   228         For the ``pre_clear`` and ``post_clear`` actions, this is ``None``.

   229 

   230 For example, if a ``Pizza`` can have multiple ``Topping`` objects, modeled

   231 like this:

   232 

   233 .. code-block:: python

   234 

   235     class Topping(models.Model):

   236         # ...

   237 

   238     class Pizza(models.Model):

   239         # ...

   240         toppings = models.ManyToManyField(Topping)

   241 

   242 If we would do something like this:

   243 

   244 .. code-block:: python

   245 

   246     >>> p = Pizza.object.create(...)

   247     >>> t = Topping.objects.create(...)

   248     >>> p.toppings.add(t)

   249 

   250 the arguments sent to a :data:`m2m_changed` handler would be:

   251 

   252     ==============  ============================================================

   253     Argument        Value

   254     ==============  ============================================================

   255     ``sender``      ``Pizza.toppings.through`` (the intermediate m2m class)

   256 

   257     ``instance``    ``p`` (the ``Pizza`` instance being modified)

   258 

   259     ``action``      ``"pre_add"`` (followed by a separate signal with ``"post_add"``)

   260 

   261     ``reverse``     ``False`` (``Pizza`` contains the :class:`ManyToManyField`,

   262                     so this call modifies the forward relation)

   263 

   264     ``model``       ``Topping`` (the class of the objects added to the

   265                     ``Pizza``)

   266 

   267     ``pk_set``      ``[t.id]`` (since only ``Topping t`` was added to the relation)

   268     ==============  ============================================================

   269 

   270 And if we would then do something like this:

   271 

   272 .. code-block:: python

   273 

   274     >>> t.pizza_set.remove(p)

   275 

   276 the arguments sent to a :data:`m2m_changed` handler would be:

   277 

   278     ==============  ============================================================

   279     Argument        Value

   280     ==============  ============================================================

   281     ``sender``      ``Pizza.toppings.through`` (the intermediate m2m class)

   282 

   283     ``instance``    ``t`` (the ``Topping`` instance being modified)

   284 

   285     ``action``      ``"pre_remove"`` (followed by a separate signal with ``"post_remove"``)

   286 

   287     ``reverse``     ``True`` (``Pizza`` contains the :class:`ManyToManyField`,

   288                     so this call modifies the reverse relation)

   289 

   290     ``model``       ``Pizza`` (the class of the objects removed from the

   291                     ``Topping``)

   292 

   293     ``pk_set``      ``[p.id]`` (since only ``Pizza p`` was removed from the

   294                     relation)

   295     ==============  ============================================================

   296 

   297 class_prepared

   298 --------------

   299 

   300 .. data:: django.db.models.signals.class_prepared

   301    :module:

   302 

   303 Sent whenever a model class has been "prepared" -- that is, once model has

   304 been defined and registered with Django's model system. Django uses this

   305 signal internally; it's not generally used in third-party applications.

   306 

   307 Arguments that are sent with this signal:

   308 

   309 ``sender``

   310     The model class which was just prepared.

   311 

   312 Management signals

   313 ==================

   314 

   315 Signals sent by :doc:`django-admin </ref/django-admin>`.

   316 

   317 post_syncdb

   318 -----------

   319 

   320 .. data:: django.db.models.signals.post_syncdb

   321    :module:

   322 

   323 Sent by :djadmin:`syncdb` after it installs an application.

   324 

   325 Any handlers that listen to this signal need to be written in a particular

   326 place: a ``management`` module in one of your :setting:`INSTALLED_APPS`. If

   327 handlers are registered anywhere else they may not be loaded by

   328 :djadmin:`syncdb`.

   329 

   330 Arguments sent with this signal:

   331 

   332     ``sender``

   333         The ``models`` module that was just installed. That is, if

   334         :djadmin:`syncdb` just installed an app called ``"foo.bar.myapp"``,

   335         ``sender`` will be the ``foo.bar.myapp.models`` module.

   336 

   337     ``app``

   338         Same as ``sender``.

   339 

   340     ``created_models``

   341         A list of the model classes from any app which :djadmin:`syncdb` has

   342         created so far.

   343 

   344     ``verbosity``

   345         Indicates how much information manage.py is printing on screen. See

   346         the :djadminopt:`--verbosity` flag for details.

   347 

   348         Functions which listen for :data:`post_syncdb` should adjust what they

   349         output to the screen based on the value of this argument.

   350 

   351     ``interactive``

   352         If ``interactive`` is ``True``, it's safe to prompt the user to input

   353         things on the command line. If ``interactive`` is ``False``, functions

   354         which listen for this signal should not try to prompt for anything.

   355 

   356         For example, the :mod:`django.contrib.auth` app only prompts to create a

   357         superuser when ``interactive`` is ``True``.

   358 

   359 Request/response signals

   360 ========================

   361 

   362 .. module:: django.core.signals

   363    :synopsis: Core signals sent by the request/response system.

   364 

   365 Signals sent by the core framework when processing a request.

   366 

   367 request_started

   368 ---------------

   369 

   370 .. data:: django.core.signals.request_started

   371    :module:

   372 

   373 Sent when Django begins processing an HTTP request.

   374 

   375 Arguments sent with this signal:

   376 

   377     ``sender``

   378         The handler class -- i.e.

   379         :class:`django.core.handlers.modpython.ModPythonHandler` or

   380         :class:`django.core.handlers.wsgi.WsgiHandler` -- that handled

   381         the request.

   382 

   383 request_finished

   384 ----------------

   385 

   386 .. data:: django.core.signals.request_finished

   387    :module:

   388 

   389 Sent when Django finishes processing an HTTP request.

   390 

   391 Arguments sent with this signal:

   392 

   393     ``sender``

   394         The handler class, as above.

   395 

   396 got_request_exception

   397 ---------------------

   398 

   399 .. data:: django.core.signals.got_request_exception

   400    :module:

   401 

   402 This signal is sent whenever Django encounters an exception while processing an incoming HTTP request.

   403 

   404 Arguments sent with this signal:

   405 

   406     ``sender``

   407         The handler class, as above.

   408 

   409     ``request``

   410         The :class:`~django.http.HttpRequest` object.

   411 

   412 Test signals

   413 ============

   414 

   415 .. module:: django.test.signals

   416    :synopsis: Signals sent during testing.

   417 

   418 Signals only sent when :doc:`running tests </topics/testing>`.

   419 

   420 template_rendered

   421 -----------------

   422 

   423 .. data:: django.test.signals.template_rendered

   424    :module:

   425 

   426 Sent when the test system renders a template. This signal is not emitted during

   427 normal operation of a Django server -- it is only available during testing.

   428 

   429 Arguments sent with this signal:

   430 

   431     sender

   432         The :class:`~django.template.Template` object which was rendered.

   433 

   434     template

   435         Same as sender

   436 

   437     context

   438         The :class:`~django.template.Context` with which the template was

   439         rendered.

   440 

   441 Database Wrappers

   442 =================

   443 

   444 .. module:: django.db.backends

   445    :synopsis: Core signals sent by the database wrapper.

   446 

   447 Signals sent by the database wrapper when a database connection is

   448 initiated.

   449 

   450 connection_created

   451 ------------------

   452 

   453 .. data:: django.db.backends.signals.connection_created

   454    :module:

   455 

   456 .. versionadded:: 1.1

   457 

   458 .. versionchanged:: 1.2

   459    The connection argument was added

   460 

   461 Sent when the database wrapper makes the initial connection to the

   462 database.  This is particularly useful if you'd like to send any post

   463 connection commands to the SQL backend.

   464 

   465 Arguments sent with this signal:

   466 

   467     sender

   468         The database wrapper class -- i.e.

   469         :class: `django.db.backends.postgresql_psycopg2.DatabaseWrapper` or

   470         :class: `django.db.backends.mysql.DatabaseWrapper`, etc.

   471 

   472     connection

   473         The database connection that was opened. This can be used in a

   474         multiple-database configuration to differentiate connection signals

   475         from different databases.