/docs/ref/signals.txt
Plain Text | 515 lines | 345 code | 170 blank | 0 comment | 0 complexity | 8a7fe644a9e74a634831fccf56e6d755 MD5 | raw file
Possible License(s): BSD-3-Clause
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.