Debian Codegraph @

docs/ref/signals.txt

raw
1 =======
2 Signals
3 =======
4
5 A list of all the signals that Django sends. All built-in signals are sent
6 using the :meth:`~django.dispatch.Signal.send` method.
7
8 .. seealso::
9
10 See the documentation on the :doc:`signal dispatcher </topics/signals>` for
11 information regarding how to register for and receive signals.
12
13 The :doc:`authentication framework </topics/auth/index>` sends :ref:`signals when
14 a user is logged in / out <topics-auth-signals>`.
15
16 Model signals
17 =============
18
19 .. module:: django.db.models.signals
20 :synopsis: Signals sent by the model system.
21
22 The :mod:`django.db.models.signals` module defines a set of signals sent by the
23 model system.
24
25 .. warning::
26
27 Signals can make your code harder to maintain. Consider implementing a
28 helper method on a :ref:`custom manager <custom-managers>`, to
29 both update your models and perform additional logic, or else
30 :ref:`overriding model methods <overriding-model-methods>` before using
31 model signals.
32
33 .. warning::
34
35 Many of these signals are sent by various model methods like
36 ``__init__()`` or :meth:`~django.db.models.Model.save` that you can
37 override in your own code.
38
39 If you override these methods on your model, you must call the parent class'
40 methods for these signals to be sent.
41
42 Note also that Django stores signal handlers as weak references by default,
43 so if your handler is a local function, it may be garbage collected. To
44 prevent this, pass ``weak=False`` when you call the signal's :meth:`~django.dispatch.Signal.connect`.
45
46 .. note::
47
48 Model signals ``sender`` model can be lazily referenced when connecting a
49 receiver by specifying its full application label. For example, an
50 ``Question`` model defined in the ``polls`` application could be referenced
51 as ``'polls.Question'``. This sort of reference can be quite handy when
52 dealing with circular import dependencies and swappable models.
53
54 ``pre_init``
55 ------------
56
57 .. attribute:: django.db.models.signals.pre_init
58 :module:
59
60 .. ^^^^^^^ this :module: hack keeps Sphinx from prepending the module.
61
62 Whenever you instantiate a Django model, this signal is sent at the beginning
63 of the model's ``__init__()`` method.
64
65 Arguments sent with this signal:
66
67 ``sender``
68 The model class that just had an instance created.
69
70 ``args``
71 A list of positional arguments passed to ``__init__()``.
72
73 ``kwargs``
74 A dictionary of keyword arguments passed to ``__init__()``.
75
76 For example, the :doc:`tutorial </intro/tutorial02>` has this line::
77
78 q = Question(question_text="What's new?", pub_date=timezone.now())
79
80 The arguments sent to a :data:`pre_init` handler would be:
81
82 ========== ===============================================================
83 Argument Value
84 ========== ===============================================================
85 ``sender`` ``Question`` (the class itself)
86
87 ``args`` ``[]`` (an empty list because there were no positional
88 arguments passed to ``__init__()``)
89
90 ``kwargs`` ``{'question_text': "What's new?",``
91 ``'pub_date': datetime.datetime(2012, 2, 26, 13, 0, 0, 775217, tzinfo=datetime.timezone.utc)}``
92 ========== ===============================================================
93
94 ``post_init``
95 -------------
96
97 .. data:: django.db.models.signals.post_init
98 :module:
99
100 Like pre_init, but this one is sent when the ``__init__()`` method finishes.
101
102 Arguments sent with this signal:
103
104 ``sender``
105 As above: the model class that just had an instance created.
106
107 ``instance``
108 The actual instance of the model that's just been created.
109
110 .. note::
111
112 :attr:`instance._state <django.db.models.Model._state>` isn't set
113 before sending the ``post_init`` signal, so ``_state`` attributes
114 always have their default values. For example, ``_state.db`` is
115 ``None``.
116
117 .. warning::
118
119 For performance reasons, you shouldn't perform queries in receivers of
120 ``pre_init`` or ``post_init`` signals because they would be executed for
121 each instance returned during queryset iteration.
122
123 ``pre_save``
124 ------------
125
126 .. data:: django.db.models.signals.pre_save
127 :module:
128
129 This is sent at the beginning of a model's :meth:`~django.db.models.Model.save`
130 method.
131
132 Arguments sent with this signal:
133
134 ``sender``
135 The model class.
136
137 ``instance``
138 The actual instance being saved.
139
140 ``raw``
141 A boolean; ``True`` if the model is saved exactly as presented
142 (i.e. when loading a :ref:`fixture <fixtures-explanation>`). One should not
143 query/modify other records in the database as the database might not be in
144 a consistent state yet.
145
146 ``using``
147 The database alias being used.
148
149 ``update_fields``
150 The set of fields to update as passed to :meth:`.Model.save`, or ``None``
151 if ``update_fields`` wasn't passed to ``save()``.
152
153 ``post_save``
154 -------------
155
156 .. data:: django.db.models.signals.post_save
157 :module:
158
159 Like :data:`pre_save`, but sent at the end of the
160 :meth:`~django.db.models.Model.save` method.
161
162 Arguments sent with this signal:
163
164 ``sender``
165 The model class.
166
167 ``instance``
168 The actual instance being saved.
169
170 ``created``
171 A boolean; ``True`` if a new record was created.
172
173 ``raw``
174 A boolean; ``True`` if the model is saved exactly as presented
175 (i.e. when loading a :ref:`fixture <fixtures-explanation>`). One should not
176 query/modify other records in the database as the database might not be in
177 a consistent state yet.
178
179 ``using``
180 The database alias being used.
181
182 ``update_fields``
183 The set of fields to update as passed to :meth:`.Model.save`, or ``None``
184 if ``update_fields`` wasn't passed to ``save()``.
185
186 ``pre_delete``
187 --------------
188
189 .. data:: django.db.models.signals.pre_delete
190 :module:
191
192 Sent at the beginning of a model's :meth:`~django.db.models.Model.delete`
193 method and a queryset's :meth:`~django.db.models.query.QuerySet.delete` method.
194
195 Arguments sent with this signal:
196
197 ``sender``
198 The model class.
199
200 ``instance``
201 The actual instance being deleted.
202
203 ``using``
204 The database alias being used.
205
206 ``origin``
207 The ``Model`` or ``QuerySet`` instance from which the deletion originated,
208 that is, the instance whose ``delete()`` method was invoked.
209
210 ``post_delete``
211 ---------------
212
213 .. data:: django.db.models.signals.post_delete
214 :module:
215
216 Like :data:`pre_delete`, but sent at the end of a model's
217 :meth:`~django.db.models.Model.delete` method and a queryset's
218 :meth:`~django.db.models.query.QuerySet.delete` method.
219
220 Arguments sent with this signal:
221
222 ``sender``
223 The model class.
224
225 ``instance``
226 The actual instance being deleted.
227
228 Note that the object will no longer be in the database, so be very
229 careful what you do with this instance.
230
231 ``using``
232 The database alias being used.
233
234 ``origin``
235 The ``Model`` or ``QuerySet`` instance from which the deletion originated,
236 that is, the instance whose ``delete()`` method was invoked.
237
238 ``m2m_changed``
239 ---------------
240
241 .. data:: django.db.models.signals.m2m_changed
242 :module:
243
244 Sent when a :class:`~django.db.models.ManyToManyField` is changed on a model
245 instance. Strictly speaking, this is not a model signal since it is sent by the
246 :class:`~django.db.models.ManyToManyField`, but since it complements the
247 :data:`pre_save`/:data:`post_save` and :data:`pre_delete`/:data:`post_delete`
248 when it comes to tracking changes to models, it is included here.
249
250 Arguments sent with this signal:
251
252 ``sender``
253 The intermediate model class describing the
254 :class:`~django.db.models.ManyToManyField`. This class is automatically
255 created when a many-to-many field is defined; you can access it using the
256 ``through`` attribute on the many-to-many field.
257
258 ``instance``
259 The instance whose many-to-many relation is updated. This can be an
260 instance of the ``sender``, or of the class the
261 :class:`~django.db.models.ManyToManyField` is related to.
262
263 ``action``
264 A string indicating the type of update that is done on the relation.
265 This can be one of the following:
266
267 ``"pre_add"``
268 Sent *before* one or more objects are added to the relation.
269 ``"post_add"``
270 Sent *after* one or more objects are added to the relation.
271 ``"pre_remove"``
272 Sent *before* one or more objects are removed from the relation.
273 ``"post_remove"``
274 Sent *after* one or more objects are removed from the relation.
275 ``"pre_clear"``
276 Sent *before* the relation is cleared.
277 ``"post_clear"``
278 Sent *after* the relation is cleared.
279
280 ``reverse``
281 Indicates which side of the relation is updated (i.e., if it is the
282 forward or reverse relation that is being modified).
283
284 ``model``
285 The class of the objects that are added to, removed from or cleared
286 from the relation.
287
288 ``pk_set``
289 For the ``pre_add`` and ``post_add`` actions, this is a set of primary key
290 values that will be, or have been, added to the relation. This may be a
291 subset of the values submitted to be added, since inserts must filter
292 existing values in order to avoid a database ``IntegrityError``.
293
294 For the ``pre_remove`` and ``post_remove`` actions, this is a set of
295 primary key values that was submitted to be removed from the relation. This
296 is not dependent on whether the values actually will be, or have been,
297 removed. In particular, non-existent values may be submitted, and will
298 appear in ``pk_set``, even though they have no effect on the database.
299
300 For the ``pre_clear`` and ``post_clear`` actions, this is ``None``.
301
302 ``using``
303 The database alias being used.
304
305 For example, if a ``Pizza`` can have multiple ``Topping`` objects, modeled
306 like this::
307
308 class Topping(models.Model):
309 # ...
310 pass
311
312
313 class Pizza(models.Model):
314 # ...
315 toppings = models.ManyToManyField(Topping)
316
317 If we connected a handler like this::
318
319 from django.db.models.signals import m2m_changed
320
321
322 def toppings_changed(sender, **kwargs):
323 # Do something
324 pass
325
326
327 m2m_changed.connect(toppings_changed, sender=Pizza.toppings.through)
328
329 and then did something like this:
330
331 .. code-block:: pycon
332
333 >>> p = Pizza.objects.create(...)
334 >>> t = Topping.objects.create(...)
335 >>> p.toppings.add(t)
336
337 the arguments sent to a :data:`m2m_changed` handler (``toppings_changed`` in
338 the example above) would be:
339
340 ============== ============================================================
341 Argument Value
342 ============== ============================================================
343 ``sender`` ``Pizza.toppings.through`` (the intermediate m2m class)
344
345 ``instance`` ``p`` (the ``Pizza`` instance being modified)
346
347 ``action`` ``"pre_add"`` (followed by a separate signal with ``"post_add"``)
348
349 ``reverse`` ``False`` (``Pizza`` contains the
350 :class:`~django.db.models.ManyToManyField`, so this call
351 modifies the forward relation)
352
353 ``model`` ``Topping`` (the class of the objects added to the
354 ``Pizza``)
355
356 ``pk_set`` ``{t.id}`` (since only ``Topping t`` was added to the relation)
357
358 ``using`` ``"default"`` (since the default router sends writes here)
359 ============== ============================================================
360
361 And if we would then do something like this:
362
363 .. code-block:: pycon
364
365 >>> t.pizza_set.remove(p)
366
367 the arguments sent to a :data:`m2m_changed` handler would be:
368
369 ============== ============================================================
370 Argument Value
371 ============== ============================================================
372 ``sender`` ``Pizza.toppings.through`` (the intermediate m2m class)
373
374 ``instance`` ``t`` (the ``Topping`` instance being modified)
375
376 ``action`` ``"pre_remove"`` (followed by a separate signal with ``"post_remove"``)
377
378 ``reverse`` ``True`` (``Pizza`` contains the
379 :class:`~django.db.models.ManyToManyField`, so this call
380 modifies the reverse relation)
381
382 ``model`` ``Pizza`` (the class of the objects removed from the
383 ``Topping``)
384
385 ``pk_set`` ``{p.id}`` (since only ``Pizza p`` was removed from the
386 relation)
387
388 ``using`` ``"default"`` (since the default router sends writes here)
389 ============== ============================================================
390
391 ``class_prepared``
392 ------------------
393
394 .. data:: django.db.models.signals.class_prepared
395 :module:
396
397 Sent whenever a model class has been "prepared" -- that is, once a model has
398 been defined and registered with Django's model system. Django uses this
399 signal internally; it's not generally used in third-party applications.
400
401 Since this signal is sent during the app registry population process, and
402 :meth:`AppConfig.ready() <django.apps.AppConfig.ready>` runs after the app
403 registry is fully populated, receivers cannot be connected in that method.
404 One possibility is to connect them ``AppConfig.__init__()`` instead, taking
405 care not to import models or trigger calls to the app registry.
406
407 Arguments that are sent with this signal:
408
409 ``sender``
410 The model class which was just prepared.
411
412 Management signals
413 ==================
414
415 Signals sent by :doc:`django-admin </ref/django-admin>`.
416
417 ``pre_migrate``
418 ---------------
419
420 .. data:: django.db.models.signals.pre_migrate
421 :module:
422
423 Sent by the :djadmin:`migrate` command before it starts to install an
424 application. It's not emitted for applications that lack a ``models`` module.
425
426 Arguments sent with this signal:
427
428 ``sender``
429 An :class:`~django.apps.AppConfig` instance for the application about to
430 be migrated/synced.
431
432 ``app_config``
433 Same as ``sender``.
434
435 ``verbosity``
436 Indicates how much information ``manage.py`` is printing on screen. See
437 the :option:`--verbosity` flag for details.
438
439 Functions which listen for :data:`pre_migrate` should adjust what they
440 output to the screen based on the value of this argument.
441
442 ``interactive``
443 If ``interactive`` is ``True``, it's safe to prompt the user to input
444 things on the command line. If ``interactive`` is ``False``, functions
445 which listen for this signal should not try to prompt for anything.
446
447 For example, the :mod:`django.contrib.auth` app only prompts to create a
448 superuser when ``interactive`` is ``True``.
449
450 ``stdout``
451 A stream-like object where verbose output should be redirected.
452
453 ``using``
454 The alias of database on which a command will operate.
455
456 ``plan``
457 The migration plan that is going to be used for the migration run. While
458 the plan is not public API, this allows for the rare cases when it is
459 necessary to know the plan. A plan is a list of 2-tuples with the first
460 item being the instance of a migration class and the second item showing
461 if the migration was rolled back (``True``) or applied (``False``).
462
463 ``apps``
464 An instance of :data:`Apps <django.apps>` containing the state of the
465 project before the migration run. It should be used instead of the global
466 :attr:`apps <django.apps.apps>` registry to retrieve the models you
467 want to perform operations on.
468
469 ``post_migrate``
470 ----------------
471
472 .. data:: django.db.models.signals.post_migrate
473 :module:
474
475 Sent at the end of the :djadmin:`migrate` (even if no migrations are run) and
476 :djadmin:`flush` commands. It's not emitted for applications that lack a
477 ``models`` module.
478
479 Handlers of this signal must not perform database schema alterations as doing
480 so may cause the :djadmin:`flush` command to fail if it runs during the
481 :djadmin:`migrate` command.
482
483 Arguments sent with this signal:
484
485 ``sender``
486 An :class:`~django.apps.AppConfig` instance for the application that was
487 just installed.
488
489 ``app_config``
490 Same as ``sender``.
491
492 ``verbosity``
493 Indicates how much information ``manage.py`` is printing on screen. See
494 the :option:`--verbosity` flag for details.
495
496 Functions which listen for :data:`post_migrate` should adjust what they
497 output to the screen based on the value of this argument.
498
499 ``interactive``
500 If ``interactive`` is ``True``, it's safe to prompt the user to input
501 things on the command line. If ``interactive`` is ``False``, functions
502 which listen for this signal should not try to prompt for anything.
503
504 For example, the :mod:`django.contrib.auth` app only prompts to create a
505 superuser when ``interactive`` is ``True``.
506
507 ``stdout``
508 A stream-like object where verbose output should be redirected.
509
510 ``using``
511 The database alias used for synchronization. Defaults to the ``default``
512 database.
513
514 ``plan``
515 The migration plan that was used for the migration run. While the plan is
516 not public API, this allows for the rare cases when it is necessary to
517 know the plan. A plan is a list of 2-tuples with the first item being
518 the instance of a migration class and the second item showing if the
519 migration was rolled back (``True``) or applied (``False``).
520
521 ``apps``
522 An instance of :data:`Apps <django.apps.apps>` containing the state of the
523 project after the migration run. It should be used instead of the global
524 :attr:`apps <django.apps.apps>` registry to retrieve the models you
525 want to perform operations on.
526
527 For example, you could register a callback in an
528 :class:`~django.apps.AppConfig` like this::
529
530 from django.apps import AppConfig
531 from django.db.models.signals import post_migrate
532
533
534 def my_callback(sender, **kwargs):
535 # Your specific logic here
536 pass
537
538
539 class MyAppConfig(AppConfig):
540 ...
541
542 def ready(self):
543 post_migrate.connect(my_callback, sender=self)
544
545 .. note::
546
547 If you provide an :class:`~django.apps.AppConfig` instance as the sender
548 argument, please ensure that the signal is registered in
549 :meth:`~django.apps.AppConfig.ready`. ``AppConfig``\s are recreated for
550 tests that run with a modified set of :setting:`INSTALLED_APPS` (such as
551 when settings are overridden) and such signals should be connected for each
552 new ``AppConfig`` instance.
553
554 Request/response signals
555 ========================
556
557 .. module:: django.core.signals
558 :synopsis: Core signals sent by the request/response system.
559
560 Signals sent by the core framework when processing a request.
561
562 .. warning::
563
564 Signals can make your code harder to maintain. Consider :doc:`using a
565 middleware </topics/http/middleware>` before using request/response
566 signals.
567
568 ``request_started``
569 -------------------
570
571 .. data:: django.core.signals.request_started
572 :module:
573
574 Sent when Django begins processing an HTTP request.
575
576 Arguments sent with this signal:
577
578 ``sender``
579 The handler class -- e.g. ``django.core.handlers.wsgi.WsgiHandler`` -- that
580 handled the request.
581 ``environ``
582 The ``environ`` dictionary provided to the request.
583
584 ``request_finished``
585 --------------------
586
587 .. data:: django.core.signals.request_finished
588 :module:
589
590 Sent when Django finishes delivering an HTTP response to the client.
591
592 Arguments sent with this signal:
593
594 ``sender``
595 The handler class, as above.
596
597 ``got_request_exception``
598 -------------------------
599
600 .. data:: django.core.signals.got_request_exception
601 :module:
602
603 This signal is sent whenever Django encounters an exception while processing an incoming HTTP request.
604
605 Arguments sent with this signal:
606
607 ``sender``
608 Unused (always ``None``).
609
610 ``request``
611 The :class:`~django.http.HttpRequest` object.
612
613 Test signals
614 ============
615
616 .. module:: django.test.signals
617 :synopsis: Signals sent during testing.
618
619 Signals only sent when :ref:`running tests <running-tests>`.
620
621 ``setting_changed``
622 -------------------
623
624 .. data:: django.test.signals.setting_changed
625 :module:
626
627 This signal is sent when the value of a setting is changed through the
628 ``django.test.TestCase.settings()`` context manager or the
629 :func:`django.test.override_settings` decorator/context manager.
630
631 It's actually sent twice: when the new value is applied ("setup") and when the
632 original value is restored ("teardown"). Use the ``enter`` argument to
633 distinguish between the two.
634
635 You can also import this signal from ``django.core.signals`` to avoid importing
636 from ``django.test`` in non-test situations.
637
638 Arguments sent with this signal:
639
640 ``sender``
641 The settings handler.
642
643 ``setting``
644 The name of the setting.
645
646 ``value``
647 The value of the setting after the change. For settings that initially
648 don't exist, in the "teardown" phase, ``value`` is ``None``.
649
650 ``enter``
651 A boolean; ``True`` if the setting is applied, ``False`` if restored.
652
653 ``template_rendered``
654 ---------------------
655
656 .. data:: django.test.signals.template_rendered
657 :module:
658
659 Sent when the test system renders a template. This signal is not emitted during
660 normal operation of a Django server -- it is only available during testing.
661
662 Arguments sent with this signal:
663
664 ``sender``
665 The :class:`~django.template.Template` object which was rendered.
666
667 ``template``
668 Same as sender
669
670 ``context``
671 The :class:`~django.template.Context` with which the template was
672 rendered.
673
674 Database Wrappers
675 =================
676
677 .. module:: django.db.backends
678 :synopsis: Core signals sent by the database wrapper.
679
680 Signals sent by the database wrapper when a database connection is
681 initiated.
682
683 ``connection_created``
684 ----------------------
685
686 .. data:: django.db.backends.signals.connection_created
687 :module:
688
689 Sent when the database wrapper makes the initial connection to the
690 database. This is particularly useful if you'd like to send any post
691 connection commands to the SQL backend.
692
693 Arguments sent with this signal:
694
695 ``sender``
696 The database wrapper class -- i.e.
697 ``django.db.backends.postgresql.DatabaseWrapper`` or
698 ``django.db.backends.mysql.DatabaseWrapper``, etc.
699
700 ``connection``
701 The database connection that was opened. This can be used in a
702 multiple-database configuration to differentiate connection signals
703 from different databases.