python/lib/django_1_4/docs/ref/signals.txt

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